knodin 0.8.7 → 0.9.0

package/dist/src/tools/knodin-tools.js

@@ -24,6 +24,7 @@ import { diagnoseFailure, } from "../failure-diagnosis.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../graph-query-health.js";
 import { inspectRepositoryIntegrationStatus } from "../init.js";
 import { attachLifecycleHealth, attachRepairLifecycle } from "../lifecycle-health.js";
+import { readManagerUpdateState, readUpdateJournal, updateAttention } from "../manager-update.js";
 import { listMirrors } from "../mirror.js";
 import { compressOutput, compressOutputFile, deleteOutputArtifact, readOutputArtifact, } from "../output-compression.js";
 import { appendTelemetryRecord, clearTelemetry, countOutputTokens, exportTelemetry, measureOutput, readTelemetryRecords, telemetryStatus, writeTelemetryReport, } from "../output-telemetry.js";
@@ -158,6 +159,13 @@ const GRAPH_INDEPENDENT_QUERY_PATTERNS = new Set([
     "lsp_implementations",
     "file_metrics",
 ]);
+const BATCH_QUERY_PATTERNS = new Set([
+    "callers_of",
+    "callees_of",
+    "imports_of",
+    "importers_of",
+    "file_summary",
+]);
 function buildDocumentedKnodinTools() {
     return [
         {
@@ -514,8 +522,14 @@ function buildDocumentedKnodinTools() {
                     repositories: { type: "array", items: { type: "string" } },
                     scope: { type: "string", enum: ["personal", "team"] },
                     distributed: { type: "boolean" },
-                    repositoryIds: { type: "object", additionalProperties: { type: "string" } },
-                    components: { type: "object", additionalProperties: { type: "object" } },
+                    repositoryIds: {
+                        type: "object",
+                        additionalProperties: { type: "string" },
+                    },
+                    components: {
+                        type: "object",
+                        additionalProperties: { type: "object" },
+                    },
                     evidence: { type: "string" },
                     relationshipType: { type: "string", enum: RELATIONSHIP_TYPES },
                     requireComplete: { type: "boolean" },
@@ -814,7 +828,11 @@ async function handleRepositoriesOperation(options) {
             dryRun,
             manifestPath,
             indexMode: (target) => indexModeForPath(loadSystemConfiguration(target), target),
-            isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command, memoryLimitBytes }),
+            isolatedInitialize: (target) => runRepositoryInitializationProcess({
+                repository: target,
+                command,
+                memoryLimitBytes,
+            }),
         });
         const { repositories } = await inventory();
         return bounded({ schemaVersion: 1, ...summary, repositories }, "repositories:init");
@@ -1376,7 +1394,7 @@ async function handleDiagnosticsOperation(repo, args, bounded) {
 async function dispatchKnodinTool(args) {
     const startedAt = performance.now();
     const parsedArgs = (args ?? {});
-    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositories, scope, distributed, repositoryIds, components, evidence, relationshipType, requireComplete, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, planDigest, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
+    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, queries, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositories, scope, distributed, repositoryIds, components, evidence, relationshipType, requireComplete, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, planDigest, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
     const repo = repoPath ?? process.cwd();
     const selector = {
         identity: expandCompactIdentity(identity),
@@ -1469,7 +1487,10 @@ async function dispatchKnodinTool(args) {
             "search",
         ].includes(rootOperation);
         const enriched = includeSharedIndex && result && typeof result === "object" && !Array.isArray(result)
-            ? { ...result, sharedIndex: sharedIndexEnvelope() }
+            ? {
+                ...result,
+                sharedIndex: sharedIndexEnvelope(),
+            }
             : result;
         const key = `${op}${minimal ? ":minimal" : ""}`;
         const output = applyResponseBudget(enriched, op, budget, RESPONSE_DEFAULTS[key] ?? RESPONSE_DEFAULTS.default);
@@ -1527,11 +1548,16 @@ async function dispatchKnodinTool(args) {
             return engine.status(repo, { audit: statusAudit }).then((result) => bounded({
                 ...attachLifecycleHealth(repo, result),
                 integration: inspectRepositoryIntegrationStatus(repo),
-                update: trustedUpdateStatus({
-                    currentVersion: result.version,
-                    installMethod: "unknown",
-                    env: process.env,
-                }),
+                update: {
+                    ...trustedUpdateStatus({
+                        currentVersion: result.version,
+                        installMethod: "unknown",
+                        env: process.env,
+                    }),
+                    managerState: readManagerUpdateState(),
+                    attention: updateAttention(readManagerUpdateState()),
+                    journal: readUpdateJournal(),
+                },
             }, "status"));
         case "wait":
             return bounded(await waitForFresh(engine, repo, timeoutMs), "wait");
@@ -1719,6 +1745,39 @@ async function dispatchKnodinTool(args) {
                 expectedLogin,
             }), "prs");
         }
+        case "query_batch": {
+            if (!process.env.KNODIN_UPDATE_VERIFICATION_TOKEN)
+                throw new Error("knodin query_batch is restricted to the isolated update verifier");
+            if (!Array.isArray(queries) || queries.length < 1 || queries.length > 32)
+                throw new Error("knodin query_batch requires 1-32 `queries`");
+            for (const item of queries) {
+                if (!item ||
+                    typeof item.symbol !== "string" ||
+                    item.symbol.length === 0 ||
+                    !BATCH_QUERY_PATTERNS.has(item.pattern))
+                    throw new Error("knodin query_batch accepts only non-empty callers/callees/imports/importers/file-summary queries");
+            }
+            const queryHealth = await inspectGatewayGraphHealth(repo);
+            if (!queryHealth.available)
+                return bounded(queryHealth, "query_batch");
+            const outputs = [];
+            for (const item of queries) {
+                outputs.push({
+                    pattern: item.pattern,
+                    symbol: item.symbol,
+                    output: await engine.query(item.pattern, item.symbol, repo, undefined, Math.min(limit ?? itemBudget ?? 100, itemBudget ?? 1000)),
+                });
+            }
+            const verifiedQueryHealth = await inspectGatewayGraphHealth(repo);
+            if (!verifiedQueryHealth.available)
+                return bounded(verifiedQueryHealth, "query_batch");
+            return bounded({
+                results: outputs.map((item) => ({
+                    ...item,
+                    output: decorateGraphQueryResult(item.output, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness),
+                })),
+            }, "query_batch");
+        }
         case "query": {
             if (!pattern)
                 throw new Error("knodin query requires `pattern`");

package/dist/src/update-ceremony.js

@@ -40,7 +40,7 @@ export function validateRootCeremonyManifest(value) {
         manifest.productionActivation !== false)
         throw new Error("invalid fail-closed ceremony header");
     if (!Array.isArray(manifest.custodians) ||
-        manifest.custodians.length < 3 ||
+        manifest.custodians.length < 1 ||
         new Set(manifest.custodians.map((c) => c.id)).size !== manifest.custodians.length ||
         manifest.custodians.some((c) => {
             exactKeys(c, c.role === "root-signer"
@@ -54,7 +54,7 @@ export function validateRootCeremonyManifest(value) {
                         !Array.isArray(c.recoveryKeyIds) ||
                         c.recoveryKeyIds.some((id) => !SHA256.test(id)))));
         }))
-        throw new Error("at least three distinct named custodians are required");
+        throw new Error("at least one named maintainer custodian is required");
     const roles = ["root", "targets", "snapshot", "timestamp"];
     exactKeys(manifest.roleKeyIds, roles, "roleKeyIds");
     exactKeys(manifest.thresholds, roles, "thresholds");
@@ -68,14 +68,11 @@ export function validateRootCeremonyManifest(value) {
             throw new Error("role keys must be valid and disjoint");
         for (const id of ids)
             all.add(id);
-        if (!Number.isInteger(threshold) ||
-            threshold < (role === "root" || role === "targets" ? 2 : 1) ||
-            threshold > ids.length)
+        if (!Number.isInteger(threshold) || threshold < 1 || threshold > ids.length)
             throw new Error(`invalid ${role} threshold`);
     }
-    if (manifest.custodians.filter((c) => c.role === "root-signer").length < manifest.thresholds.root ||
-        !manifest.custodians.some((c) => c.role === "recovery"))
-        throw new Error("custodian roles do not satisfy threshold and recovery separation");
+    if (manifest.custodians.filter((c) => c.role === "root-signer").length < manifest.thresholds.root)
+        throw new Error("maintainer custodians do not satisfy the root threshold");
     const assigned = manifest.custodians
         .filter((c) => c.role === "root-signer")
         .map((c) => c.publicKeyId)
@@ -85,15 +82,9 @@ export function validateRootCeremonyManifest(value) {
     if (assigned.join("\0") !== [...manifest.roleKeyIds.root].sort(compareBytes).join("\0"))
         throw new Error("root signer assignments must exactly match root role keys");
     const recovery = manifest.custodians.filter((c) => c.role === "recovery");
-    if (recovery.length < manifest.thresholds.root ||
-        new Set(recovery.map((c) => c.evidenceId)).size !== recovery.length ||
-        recovery.some((c) => !c.recoveryKeyIds?.length ||
-            new Set(c.recoveryKeyIds).size !== c.recoveryKeyIds.length ||
-            c.recoveryKeyIds.length >= manifest.thresholds.root))
-        throw new Error("recovery sets must preserve root threshold independence");
-    const recovered = new Set(recovery.flatMap((c) => c.recoveryKeyIds ?? []));
-    if (manifest.roleKeyIds.root.some((id) => !recovered.has(id)))
-        throw new Error("recovery assignments must cover every root role key");
+    if (new Set(recovery.map((c) => c.evidenceId)).size !== recovery.length ||
+        recovery.some((c) => !c.recoveryKeyIds?.length || new Set(c.recoveryKeyIds).size !== c.recoveryKeyIds.length))
+        throw new Error("recovery assignments must be unique and non-empty when declared");
     return manifest;
 }
 export function validateRootPinReviewReceipt(value, manifest) {
@@ -115,20 +106,21 @@ export function validateRootPinReviewReceipt(value, manifest) {
         receipt.ceremonyId !== manifest.ceremonyId ||
         !SHA256.test(receipt.rootEnvelopeSha256) ||
         !ID.test(receipt.reviewerId) ||
-        manifest.custodians.some((c) => c.id === receipt.reviewerId) ||
         receipt.decision !== "approved" ||
-        receipt.authentication !== "rehearsal-unsigned" ||
+        (manifest.purpose === "rehearsal"
+            ? receipt.authentication !== "rehearsal-unsigned" ||
+                manifest.custodians.some((c) => c.id === receipt.reviewerId)
+            : receipt.authentication !== "maintainer-attested" ||
+                !manifest.custodians.some((c) => c.id === receipt.reviewerId)) ||
         receipt.productionActivation !== false ||
         !Number.isFinite(Date.parse(receipt.reviewedAt)) ||
         new Date(receipt.reviewedAt).toISOString() !== receipt.reviewedAt)
-        throw new Error("invalid or non-independent pin-review receipt");
+        throw new Error("invalid root-pin attestation receipt");
     return receipt;
 }
 export function preparePublicRootImport(envelope, pin, manifestValue, receiptValue, now = new Date()) {
     rejectPrivateMaterial(envelope, "rootEnvelope");
     const manifest = validateRootCeremonyManifest(manifestValue);
-    if (manifest.purpose === "production")
-        throw new Error("production import requires externally authenticated review and remains blocked");
     const receipt = validateRootPinReviewReceipt(receiptValue, manifest);
     if (Date.parse(receipt.reviewedAt) > now.getTime())
         throw new Error("pin-review receipt cannot be future-dated");
@@ -156,7 +148,11 @@ export function preparePublicRootImport(envelope, pin, manifestValue, receiptVal
     }
     const digest = createHash("sha256").update(canonicalizeUpdateMetadata(envelope)).digest("hex");
     if (pin !== digest || receipt.rootEnvelopeSha256 !== digest)
-        throw new Error("root envelope, pin, and independent review receipt disagree");
+        throw new Error("root envelope, pin, and maintainer attestation disagree");
     verifyUpdateRootChain(envelope, pin, [], now);
-    return { rootEnvelope: envelope, rootEnvelopeSha256: digest, productionActivation: false };
+    return {
+        rootEnvelope: envelope,
+        rootEnvelopeSha256: digest,
+        productionActivation: false,
+    };
 }

package/dist/src/update-coordination.js

@@ -0,0 +1,158 @@
+import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { readUpdateJournal } from "./manager-update.js";
+function coordinationRoot(stateHome) {
+    const root = stateHome ?? process.env.XDG_STATE_HOME ?? path.join(os.homedir(), ".local", "state");
+    return path.join(root, "knodin", "coordination");
+}
+function processStartToken(pid) {
+    try {
+        if (process.platform === "win32") {
+            return execFileSync("powershell.exe", ["-NoProfile", "-Command", `(Get-Process -Id ${pid}).StartTime.ToUniversalTime().Ticks`], { encoding: "utf8", timeout: 2_000 }).trim();
+        }
+        return execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8",
+            timeout: 2_000,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function readLease(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024)
+            return null;
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        return value.schemaVersion === 1 && typeof value.nonce === "string" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function live(record) {
+    return Boolean(record && processStartToken(record.pid) === record.processStartToken);
+}
+function writeExclusive(file, record) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const descriptor = fs.openSync(file, "wx", 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify(record)}\n`, "utf8");
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function releaseOwned(file, nonce) {
+    const current = readLease(file);
+    if (current?.nonce !== nonce)
+        return;
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function updateLeaseFile(stateHome) {
+    return path.join(coordinationRoot(stateHome), "update.lock");
+}
+function lifecycleDirectory(stateHome) {
+    return path.join(coordinationRoot(stateHome), "lifecycle");
+}
+function tokenHash(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+function activeLifecycleLeases(stateHome) {
+    const directory = lifecycleDirectory(stateHome);
+    let names = [];
+    try {
+        names = fs.readdirSync(directory).slice(0, 4096);
+    }
+    catch {
+        return [];
+    }
+    const active = [];
+    for (const name of names) {
+        const file = path.join(directory, name);
+        const record = readLease(file);
+        if (live(record))
+            active.push(record);
+        else
+            releaseOwned(file, record?.nonce ?? "");
+    }
+    return active;
+}
+export function acquireLifecycleCoordination(options) {
+    const updateFile = updateLeaseFile(options.stateHome);
+    const update = readLease(updateFile);
+    if (live(update)) {
+        const permitted = options.verificationToken &&
+            update?.verificationTokenHash === tokenHash(options.verificationToken);
+        if (!permitted)
+            throw new Error("an executable update is active; retry lifecycle work after it completes");
+    }
+    else if (update) {
+        const journal = readUpdateJournal(options.stateHome);
+        if (journal && !["candidate-verified", "rollback-verified"].includes(journal.state)) {
+            throw new Error(`an interrupted update is ${journal.state}; run \`knodin update status\` to recover it`);
+        }
+        releaseOwned(updateFile, update.nonce);
+    }
+    const nonce = randomUUID();
+    const record = {
+        schemaVersion: 1,
+        kind: "lifecycle",
+        nonce,
+        pid: process.pid,
+        processStartToken: processStartToken(process.pid) ?? "unavailable",
+        command: options.command,
+        repository: fs.realpathSync(options.repository),
+        startedAt: new Date().toISOString(),
+    };
+    const file = path.join(lifecycleDirectory(options.stateHome), `${process.pid}-${nonce}.json`);
+    writeExclusive(file, record);
+    return { record, release: () => releaseOwned(file, nonce) };
+}
+export function acquireExclusiveUpdateCoordination(options) {
+    const active = activeLifecycleLeases(options.stateHome);
+    if (active.length > 0) {
+        throw new Error(`executable replacement deferred while ${active.length} lifecycle operation(s) are active`);
+    }
+    const file = updateLeaseFile(options.stateHome);
+    const existing = readLease(file);
+    if (live(existing))
+        throw new Error("another executable update is active");
+    if (existing) {
+        const journal = readUpdateJournal(options.stateHome);
+        if (journal &&
+            !["candidate-verified", "rollback-verified"].includes(journal.state) &&
+            !options.recovery) {
+            throw new Error(`interrupted update recovery required from journal state ${journal.state}`);
+        }
+        releaseOwned(file, existing.nonce);
+    }
+    const nonce = randomUUID();
+    const record = {
+        schemaVersion: 1,
+        kind: "update",
+        nonce,
+        pid: process.pid,
+        processStartToken: processStartToken(process.pid) ?? "unavailable",
+        command: "update",
+        startedAt: new Date().toISOString(),
+        verificationTokenHash: tokenHash(options.verificationToken),
+    };
+    writeExclusive(file, record);
+    return { record, release: () => releaseOwned(file, nonce) };
+}
+export function coordinationStatus(stateHome) {
+    const update = readLease(updateLeaseFile(stateHome));
+    return { update: live(update) ? update : null, lifecycle: activeLifecycleLeases(stateHome) };
+}