Integration/v1 adr alignment

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, "integration/**"]
   pull_request:
-    branches: [main]
+    branches: [main, "integration/**"]
 
 env:
   CARGO_TERM_COLOR: always

.github/workflows/release.yml

@@ -1,5 +1,28 @@
 name: Release
 
+# Triggered by a version tag push (e.g. v0.2.0).
+# Builds Rust binaries per-platform, publishes each @khive/kernel-{platform}
+# npm subpackage, then publishes the umbrella khive package.
+#
+# Per ADR-026 §"Atomic release semantics": all subpackage publishes must
+# succeed before the umbrella publishes. This is enforced by separating the
+# workflow into two phases:
+#
+#   Phase 1 (build-platform matrix): compile binaries, stage into subpackage
+#     bin/, remove .gitkeep, and upload the whole subpackage as a GH Actions
+#     artifact. No `npm publish` happens here.
+#
+#   Phase 2 (publish-all, single job): downloads all six platform artifacts,
+#     updates versions, publishes the six subpackages, then publishes the
+#     umbrella — in a single sequential job. If any subpackage publish fails,
+#     the umbrella is never published. Because publishing is serialised in one
+#     job, partial failure cannot leave mismatched versions permanently on the
+#     registry (any already-published subpackage can be unpublished within 72h
+#     via `npm unpublish` before the version is re-released).
+#
+# This satisfies the ADR guarantee: partial failure leaves the user able to
+# install the previous khive version unchanged.
+
 on:
   push:
     tags:
@@ -8,63 +31,207 @@ on:
 permissions:
   contents: write
 
+env:
+  CARGO_TERM_COLOR: always
+
 jobs:
-  compile:
+  # ─────────────────────────────────────────────────────────────────────────
+  # Phase 1: Build Rust binaries per platform and upload as GH artifacts.
+  # No npm publish happens here — that is deferred to Phase 2.
+  # ─────────────────────────────────────────────────────────────────────────
+  build-platform:
     strategy:
+      fail-fast: true
       matrix:
         include:
-          - os: macos-latest
+          - platform: darwin-arm64
+            os: macos-latest
             target: aarch64-apple-darwin
-            binary: khive-darwin-arm64
-          - os: macos-13
+            cross: false
+
+          - platform: darwin-x64
+            os: macos-latest
             target: x86_64-apple-darwin
-            binary: khive-darwin-x64
-          - os: ubuntu-latest
+            cross: false
+
+          - platform: linux-x64-gnu
+            os: ubuntu-latest
             target: x86_64-unknown-linux-gnu
-            binary: khive-linux-x64
-          - os: ubuntu-latest
+            cross: false
+
+          - platform: linux-x64-musl
+            os: ubuntu-latest
+            target: x86_64-unknown-linux-musl
+            cross: true
+
+          - platform: linux-arm64
+            os: ubuntu-latest
             target: aarch64-unknown-linux-gnu
-            binary: khive-linux-arm64
-          - os: windows-latest
+            cross: true
+
+          - platform: win32-x64
+            os: windows-latest
             target: x86_64-pc-windows-msvc
-            binary: khive-win32-x64.exe
+            cross: false
+
     runs-on: ${{ matrix.os }}
+
     steps:
       - uses: actions/checkout@v4
-      - uses: denoland/setup-deno@v2
+
+      - uses: dtolnay/rust-toolchain@1.94.1
         with:
-          deno-version: v2.x
-      - name: Compile
+          targets: ${{ matrix.target }}
+
+      - name: Install cargo-zigbuild (cross-compile targets only)
+        if: ${{ matrix.cross }}
+        run: pip3 install ziglang && cargo install cargo-zigbuild
+
+      - name: Build binaries (native)
+        if: ${{ !matrix.cross }}
+        working-directory: crates
+        run: |
+          cargo build --release --target ${{ matrix.target }} -p kkernel -p khive-mcp
+
+      - name: Build binaries (zigbuild cross)
+        if: ${{ matrix.cross }}
+        working-directory: crates
         run: |
-          deno compile \
-            --allow-read --allow-write --allow-run --allow-env \
-            --target ${{ matrix.target }} \
-            --output npm/bin/${{ matrix.binary }} \
-            cli/main.ts
-      - uses: actions/upload-artifact@v4
+          cargo zigbuild --release --target ${{ matrix.target }} -p kkernel -p khive-mcp
+
+      - name: Stage binaries into subpackage bin/
+        shell: bash
+        run: |
+          PKG_DIR="npm/kernel-${{ matrix.platform }}/bin"
+          SRC="crates/target/${{ matrix.target }}/release"
+          # Remove the placeholder so it is not shipped in the published tarball (MIN-1).
+          rm -f "${PKG_DIR}/.gitkeep"
+          if [[ "${{ matrix.os }}" == "windows-latest" ]]; then
+            cp "${SRC}/kkernel.exe"    "${PKG_DIR}/kkernel.exe"
+            cp "${SRC}/khive-mcp.exe" "${PKG_DIR}/khive-mcp.exe"
+          else
+            cp "${SRC}/kkernel"    "${PKG_DIR}/kkernel"
+            cp "${SRC}/khive-mcp" "${PKG_DIR}/khive-mcp"
+            chmod +x "${PKG_DIR}/kkernel" "${PKG_DIR}/khive-mcp"
+          fi
+
+      - name: Upload subpackage artifact
+        uses: actions/upload-artifact@v4
         with:
-          name: ${{ matrix.binary }}
-          path: npm/bin/${{ matrix.binary }}
+          name: kernel-${{ matrix.platform }}
+          path: npm/kernel-${{ matrix.platform }}/
+          # Retain for 1 day — only needed during this release run.
+          retention-days: 1
 
-  publish:
-    needs: compile
+  # ─────────────────────────────────────────────────────────────────────────
+  # Phase 2: Publish all subpackages + umbrella atomically in a single job.
+  # Runs only after ALL Phase 1 jobs succeed (needs: build-platform with
+  # fail-fast: true propagates any single failure here).
+  # ─────────────────────────────────────────────────────────────────────────
+  publish-all:
+    needs: build-platform
     runs-on: ubuntu-latest
+
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
-        with:
-          path: npm/bin
-          merge-multiple: true
-      - name: Set version from tag
-        run: |
-          VERSION="${GITHUB_REF#refs/tags/v}"
-          jq --arg v "$VERSION" '.version = $v' npm/package.json > tmp.json
-          mv tmp.json npm/package.json
+
       - uses: actions/setup-node@v4
         with:
           node-version: 20
           registry-url: https://registry.npmjs.org
-      - name: Publish
+
+      # Extract the version from the git tag (strip leading "v").
+      # Passed via env var to avoid shell-interpolation issues in node -e (MIN-3).
+      - name: Extract version
+        run: |
+          echo "VERSION=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_ENV"
+
+      # Download all six platform artifacts into their respective directories.
+      - name: Download all platform artifacts
+        uses: actions/download-artifact@v4
+        with:
+          # Download to npm/ — each artifact named kernel-{platform} lands in
+          # npm/kernel-{platform}/ matching the checkout layout.
+          path: npm/
+          # pattern matches kernel-* artifacts from Phase 1
+          pattern: kernel-*
+
+      # actions/checkout@v4 above restored npm/kernel-*/bin/.gitkeep (it's tracked
+      # in git so the bin/ dirs exist for new clones). actions/download-artifact
+      # does not delete it. Remove it here so the published tarball ships only
+      # the platform binary, not the placeholder. (NEW-1 round-2 fix.)
+      - name: Remove .gitkeep placeholders before publish
+        run: rm -f npm/kernel-*/bin/.gitkeep
+
+      # Set the version in each subpackage's package.json.
+      # VERSION and PKG_JSON are passed via env vars to avoid shell-interpolation
+      # of special characters inside the node -e script (MIN-3).
+      - name: Set subpackage versions
+        run: |
+          for platform in darwin-arm64 darwin-x64 linux-x64-gnu linux-x64-musl linux-arm64 win32-x64; do
+            PKG_JSON="npm/kernel-${platform}/package.json" VERSION="${{ env.VERSION }}" node -e "
+              const fs = require('fs');
+              const pkg = JSON.parse(fs.readFileSync(process.env.PKG_JSON));
+              pkg.version = process.env.VERSION;
+              fs.writeFileSync(process.env.PKG_JSON, JSON.stringify(pkg, null, 2) + '\n');
+            "
+          done
+
+      # Publish all six subpackages. If any fails, subsequent steps (including
+      # umbrella publish) do not run. GitHub Actions sequential steps in a
+      # single job guarantee this ordering.
+      - name: Publish @khive/kernel-darwin-arm64
+        working-directory: npm/kernel-darwin-arm64
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish @khive/kernel-darwin-x64
+        working-directory: npm/kernel-darwin-x64
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish @khive/kernel-linux-x64-gnu
+        working-directory: npm/kernel-linux-x64-gnu
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish @khive/kernel-linux-x64-musl
+        working-directory: npm/kernel-linux-x64-musl
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish @khive/kernel-linux-arm64
+        working-directory: npm/kernel-linux-arm64
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish @khive/kernel-win32-x64
+        working-directory: npm/kernel-win32-x64
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Only reached if all six subpackage publishes succeeded.
+      - name: Set umbrella version and pin subpackage versions
+        env:
+          VERSION: ${{ env.VERSION }}
+        run: |
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('npm/package.json'));
+            pkg.version = process.env.VERSION;
+            for (const k of Object.keys(pkg.optionalDependencies || {})) {
+              pkg.optionalDependencies[k] = process.env.VERSION;
+            }
+            fs.writeFileSync('npm/package.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+
+      - name: Publish khive (umbrella)
         working-directory: npm
         run: npm publish --access public
         env:

.gitignore

@@ -80,3 +80,5 @@ docs/adr/_review/
 
 # Compiled CLI binaries (built by scripts/compile.sh, not committed)
 npm/bin/khive-*
+# Exception: npm/bin/khive-mcp is the Node shim for the MCP binary, not a compiled binary.
+!npm/bin/khive-mcp

Makefile

@@ -1,4 +1,4 @@
-.PHONY: check clippy test contract-test fmt fmt-check build clean ci docs-check publish publish-dry local
+.PHONY: check clippy test contract-test fmt fmt-check build clean ci docs-check publish publish-dry local proof-check
 
 check:
 	cd crates && cargo check --workspace
@@ -23,6 +23,9 @@ fmt-check:
 build:
 	cd crates && cargo build --workspace --release
 
+proof-check:
+	./scripts/check-proof-references.sh
+
 clean:
 	cd crates && cargo clean
 

cli/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@khive/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "khive — research knowledge graph CLI",
   "license": "Apache-2.0",
   "tasks": {

cli/kg/doctor.ts

@@ -98,8 +98,7 @@ export async function inspectKg(repoRoot: string): Promise<DoctorReport> {
         code: "DUPLICATE_ID",
         file: ENTITIES_FILE,
         line: entry.line,
-        message:
-          `Duplicate entity id '${id}' (first seen on line ${entityFirstLine.get(id)})`,
+        message: `Duplicate entity id '${id}' (first seen on line ${entityFirstLine.get(id)})`,
       });
     } else {
       entityIds.add(id);
@@ -237,8 +236,7 @@ export async function inspectKg(repoRoot: string): Promise<DoctorReport> {
           code: "DUPLICATE_NATURAL_KEY",
           file: EDGES_FILE,
           line: entry.line,
-          message:
-            `Duplicate edge (source=${source}, target=${target}, relation=${relation})`,
+          message: `Duplicate edge (source=${source}, target=${target}, relation=${relation})`,
         });
       } else {
         naturalKeys.add(naturalKey);
@@ -292,9 +290,7 @@ function formatDoctor(report: DoctorReport, json: boolean): string {
   ];
 
   for (const issue of report.issues) {
-    const loc = issue.line !== undefined
-      ? `${issue.file}:${issue.line}`
-      : issue.file;
+    const loc = issue.line !== undefined ? `${issue.file}:${issue.line}` : issue.file;
     const prefix = issue.severity === "error" ? "ERROR" : "WARN ";
     lines.push(`  [${prefix}] ${issue.code}: ${issue.message} (${loc})`);
   }

cli/kg/doctor_test.ts

@@ -21,10 +21,10 @@ async function setupKg(
   edges: unknown[],
 ): Promise<void> {
   await Deno.mkdir(`${dir}/.khive/kg`, { recursive: true });
-  const entitiesNdjson =
-    entities.map((e) => JSON.stringify(e)).join("\n") + (entities.length > 0 ? "\n" : "");
-  const edgesNdjson =
-    edges.map((e) => JSON.stringify(e)).join("\n") + (edges.length > 0 ? "\n" : "");
+  const entitiesNdjson = entities.map((e) => JSON.stringify(e)).join("\n") +
+    (entities.length > 0 ? "\n" : "");
+  const edgesNdjson = edges.map((e) => JSON.stringify(e)).join("\n") +
+    (edges.length > 0 ? "\n" : "");
   await Deno.writeTextFile(`${dir}/.khive/kg/entities.ndjson`, entitiesNdjson);
   await Deno.writeTextFile(`${dir}/.khive/kg/edges.ndjson`, edgesNdjson);
 }

cli/kg/export.ts

@@ -273,6 +273,17 @@ export async function runExport(repoRoot: string, args: string[]): Promise<void>
     return;
   }
 
+  if (format !== "ndjson") {
+    // ADR-036 §8: the --format flag on export is reserved; any non-ndjson value
+    // is rejected with a "not yet implemented" error until P1/P2 adapters ship.
+    console.error(
+      `Error: --format ${JSON.stringify(format)} is not yet implemented for export.\n` +
+        `Supported: ndjson (default), archive.\n` +
+        `Non-NDJSON export formats are deferred to P1/P2 (ADR-036 §8).`,
+    );
+    Deno.exit(1);
+  }
+
   // Default: canonical NDJSON export
   try {
     await exportCanonical(repoRoot);