kibi-cli 2.3.0 → 2.5.0

package/dist/public/telemetry-acceptance.js

@@ -7,6 +7,7 @@ export const DEFAULT_TELEMETRY_ACCEPTANCE_POLICY = {
     telemetryCompletenessMinimum: 0.95,
     validationBeforeUpsertMinimum: 1,
     advisorBeforeRequirementWriteMinimum: 1,
+    lookupBeforeFirstEditMinimum: 1,
     sourceLookupZeroResultMaximum: 0.2,
     preflightMaxAgeSeconds: 60 * 60,
     advisorMaxAgeSeconds: 24 * 60 * 60,
@@ -15,8 +16,26 @@ export const DEFAULT_TELEMETRY_ACCEPTANCE_POLICY = {
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+/**
+ * Hook rows and line numbers of every array `parseTelemetryUsageLog`
+ * returned. The array itself keeps its operation-only shape, so callers that
+ * pass it straight to the analyzers need no change.
+ */
+const parsedUsageLogs = new WeakMap();
+/**
+ * Parse Kibi operation events from `.kb/usage.log`.
+ *
+ * Host plugin hooks share the log and tag their rows `interface: "hook"`.
+ * Those rows describe agent activity around Kibi calls, not Kibi operations,
+ * so they are left out of the returned array: otherwise a busy editing
+ * session would push every operation out of the bounded acceptance window.
+ * They stay attached to the array for `partitionTelemetryUsage`, which is how
+ * the `lookup_before_first_edit` metric reads them.
+ */
 export function parseTelemetryUsageLog(contents) {
     const events = [];
+    const operationLines = [];
+    const hookRows = [];
     for (const [index, line] of contents.split(/\r?\n/).entries()) {
         const trimmed = line.trim();
         if (!trimmed)
@@ -32,10 +51,48 @@ export function parseTelemetryUsageLog(contents) {
         if (!isRecord(parsed)) {
             throw new Error(`Failed to parse .kb/usage.log line ${index + 1}: expected object`);
         }
+        if (parsed.interface === "hook") {
+            hookRows.push({
+                event: parsed,
+                logLine: index + 1,
+                operationsBefore: events.length,
+            });
+            continue;
+        }
         events.push(parsed);
+        operationLines.push(index + 1);
     }
+    parsedUsageLogs.set(events, { operationLines, hookRows });
     return events;
 }
+// implements REQ-kibi-telemetry-acceptance-gate-v2, REQ-claude-hook-usage-telemetry-v2
+/**
+ * Split events into Kibi operations and host hook rows. Arrays from
+ * `parseTelemetryUsageLog` carry their hook rows and log lines; any other
+ * array is split on `interface: "hook"`, with positions as line numbers.
+ */
+export function partitionTelemetryUsage(events) {
+    const parsed = parsedUsageLogs.get(events);
+    if (parsed !== undefined)
+        return { operations: events, ...parsed };
+    const operations = [];
+    const operationLines = [];
+    const hookRows = [];
+    for (const [index, event] of events.entries()) {
+        if (event.interface === "hook") {
+            hookRows.push({
+                event: event,
+                logLine: index + 1,
+                operationsBefore: operations.length,
+            });
+        }
+        else {
+            operations.push(event);
+            operationLines.push(index + 1);
+        }
+    }
+    return { operations, operationLines, hookRows };
+}
 function eventArgs(event) {
     return event.business_args ?? event.args ?? {};
 }
@@ -251,6 +308,77 @@ function advisorBeforeRequirementWriteMetric(all, recentStart, policy) {
         },
     };
 }
+// implements REQ-kibi-telemetry-acceptance-gate-v2
+/** Kibi operations that count as looking up requirements before an edit. */
+export const LOOKUP_BEFORE_EDIT_OPERATIONS = ["kb_query", "kb_search"];
+function hookSession(event) {
+    const sessionId = event.session_id;
+    if (typeof sessionId !== "string" || sessionId.length === 0)
+        return undefined;
+    return `${event.host ?? "unknown"}:${sessionId}`;
+}
+// implements REQ-kibi-telemetry-acceptance-gate-v2, REQ-claude-hook-usage-telemetry-v2
+/**
+ * For each host session, its first edit of a file whose symbols implement a
+ * requirement and whether a Kibi lookup (MCP or CLI) preceded it. Rows
+ * without a session id cannot be ordered within a session and are skipped;
+ * sessions whose first linked edit predates the evaluated window are left
+ * out.
+ */
+export function firstLinkedEdits(hookRows, recentStart) {
+    const lookedUp = new Set();
+    const edited = new Set();
+    const firstEdits = [];
+    for (const row of hookRows) {
+        const session = hookSession(row.event);
+        if (session === undefined)
+            continue;
+        const { hook_action: action, kb_operation: operation } = row.event;
+        if (action === "kb_usage" &&
+            LOOKUP_BEFORE_EDIT_OPERATIONS.some((candidate) => candidate === operation)) {
+            lookedUp.add(session);
+            continue;
+        }
+        if (action !== "edited" ||
+            edited.has(session) ||
+            !Array.isArray(row.event.requirement_ids) ||
+            row.event.requirement_ids.length === 0) {
+            continue;
+        }
+        edited.add(session);
+        if (row.operationsBefore < recentStart)
+            continue;
+        firstEdits.push({ session, edit: row, lookedUp: lookedUp.has(session) });
+    }
+    return firstEdits;
+}
+function lookupBeforeFirstEditMetric(hookRows, recentStart, policy) {
+    const firstEdits = firstLinkedEdits(hookRows, recentStart);
+    const attempts = firstEdits.length;
+    const guided = firstEdits.filter((entry) => entry.lookedUp).length;
+    const unguidedEditPaths = new Set(firstEdits
+        .filter((entry) => !entry.lookedUp)
+        .map((entry) => entry.edit.event.path ?? "unknown path"));
+    const actual = rate(guided, attempts);
+    return {
+        id: "lookup_before_first_edit",
+        status: thresholdStatus(actual, ">=", policy.lookupBeforeFirstEditMinimum),
+        numerator: guided,
+        denominator: attempts,
+        ...(actual !== undefined ? { rate: actual } : {}),
+        threshold: {
+            operator: ">=",
+            value: policy.lookupBeforeFirstEditMinimum,
+        },
+        message: attempts === 0
+            ? "No host hook recorded an edit of a requirement-linked file in the evaluated window."
+            : `${guided}/${attempts} sessions ran kb_search or kb_query before their first edit of a requirement-linked file.`,
+        evidence: {
+            unguidedEditPaths: [...unguidedEditPaths].sort().slice(0, 20),
+            lookupOperations: [...LOOKUP_BEFORE_EDIT_OPERATIONS],
+        },
+    };
+}
 function sourceLookupMessage(zeroResults, lookups, unobservable) {
     const unreadable = unobservable > 0
         ? `${unobservable} source-linked lookups recorded no readable result count.`
@@ -452,7 +580,8 @@ function reportStatus(metrics, fresh) {
     return "passed";
 }
 export function analyzeTelemetryAcceptance(events, now = new Date(), policy = DEFAULT_TELEMETRY_ACCEPTANCE_POLICY) {
-    const all = events.map((event, index) => ({
+    const { operations, hookRows } = partitionTelemetryUsage(events);
+    const all = operations.map((event, index) => ({
         event,
         index,
         time: timestampMillis(event.timestamp),
@@ -473,15 +602,16 @@ export function analyzeTelemetryAcceptance(events, now = new Date(), policy = DE
         telemetryCompletenessMetric(recent, policy),
         advisorBeforeRequirementWriteMetric(all, recentStart, policy),
         validationBeforeUpsertMetric(all, recentStart, policy),
+        lookupBeforeFirstEditMetric(hookRows, recentStart, policy),
         sourceLookupMetric(recent, policy),
         proofGapRecoveryMetric(recent),
         receiptFreshnessMetric(recent),
         repeatedMutationFailuresMetric(recent, policy),
     ];
     const diagnostics = [];
-    if (events.length === 0)
+    if (operations.length === 0)
         diagnostics.push("usage_log_empty");
-    if (lastTime === null && events.length > 0) {
+    if (lastTime === null && operations.length > 0) {
         diagnostics.push("usage_log_timestamps_unavailable");
     }
     else if (!fresh) {
@@ -495,9 +625,9 @@ export function analyzeTelemetryAcceptance(events, now = new Date(), policy = DE
         evaluatedAt: now.toISOString(),
         policy,
         scope: {
-            totalEvents: events.length,
+            totalEvents: operations.length,
             evaluatedEvents: recent.length,
-            truncated: events.length > recent.length,
+            truncated: operations.length > recent.length,
             firstTimestamp: firstTime === null ? null : new Date(firstTime).toISOString(),
             lastTimestamp: lastTime === null ? null : new Date(lastTime).toISOString(),
             evidenceAgeSeconds: ageSeconds,
@@ -518,13 +648,19 @@ const METRIC_DIAGNOSTICS = {
         id: "semantic_advisor_bypassed",
         severity: "warning",
         rank: 30,
-        suggestion: "Run kb_semantic_advisor on the complete current requirement prose before its next upsert, preserve the returned source hash, and recheck telemetry.",
+        suggestion: "Run kb_model with mode analyze (CLI: semantic-advisor) on the complete current requirement prose before its next upsert, preserve the returned source hash, and recheck telemetry.",
     },
     validation_before_upsert: {
         id: "mutation_validation_bypassed",
         severity: "warning",
         rank: 20,
-        suggestion: "Run kb_validate_upsert for the exact payload no more than one hour before each sequential kb_upsert attempt.",
+        suggestion: "Run kb_upsert with dryRun true (CLI: validate-upsert) for the exact payload no more than one hour before each sequential kb_upsert attempt.",
+    },
+    lookup_before_first_edit: {
+        id: "lookup_before_first_edit_bypassed",
+        severity: "warning",
+        rank: 35,
+        suggestion: "Before a session's first edit of a requirement-linked file, run kb_search for the change (or kb_query with sourceFile for the file) and read the requirements it names; host hook rows in diagnostic mode record the order.",
     },
     source_lookup_zero_result_rate: {
         id: "source_lookup_zero_result_rate_high",

package/dist/public/telemetry-remediation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-remediation.d.ts","sourceRoot":"","sources":["../../src/public/telemetry-remediation.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EAEzB,MAAM,2BAA2B,CAAC;AAEnC,eAAO,MAAM,6BAA6B,EACxC,+BAAwC,CAAC;AAE3C,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,CAAC;IAC1D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,kCAAkC,GAAG,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,6BAA6B,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACrD;AAyJD,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,GAAG,GAAE,IAAiB,EACtB,MAAM,GAAE,yBAA+D,GACtE,0BAA0B,CAqQ5B"}
+{"version":3,"file":"telemetry-remediation.d.ts","sourceRoot":"","sources":["../../src/public/telemetry-remediation.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EAIzB,MAAM,2BAA2B,CAAC;AAEnC,eAAO,MAAM,6BAA6B,EACxC,+BAAwC,CAAC;AAE3C,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,CAAC;IAC1D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,kCAAkC,GAAG,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,6BAA6B,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACrD;AA4JD,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,GAAG,GAAE,IAAiB,EACtB,MAAM,GAAE,yBAA+D,GACtE,0BAA0B,CA6R5B"}

package/dist/public/telemetry-remediation.js

@@ -1,10 +1,11 @@
 import { diagnosticMutationFingerprint } from "./diagnostic-usage.js";
-import { DEFAULT_TELEMETRY_ACCEPTANCE_POLICY, analyzeTelemetryAcceptance, } from "./telemetry-acceptance.js";
+import { DEFAULT_TELEMETRY_ACCEPTANCE_POLICY, analyzeTelemetryAcceptance, firstLinkedEdits, partitionTelemetryUsage, } from "./telemetry-acceptance.js";
 export const TELEMETRY_REMEDIATION_VERSION = "kibi.telemetry-remediation.v1";
 const RANKS = {
     repeated_mutation_failures: 10,
     validation_before_upsert: 20,
     advisor_before_requirement_write: 30,
+    lookup_before_first_edit: 35,
     e2e_receipt_freshness: 40,
     proof_gap_recovery: 50,
     source_lookup_zero_result_rate: 60,
@@ -66,7 +67,7 @@ function target(event) {
 }
 function reference(entry) {
     return {
-        logLine: entry.index + 1,
+        logLine: entry.logLine,
         requestId: entry.event.request_id ?? null,
         timestamp: entry.event.timestamp ?? null,
         tool: entry.event.tool ?? null,
@@ -76,7 +77,7 @@ function reference(entry) {
 }
 function eventItem(metric, entry, itemTarget, reason, action) {
     return {
-        id: `${metric}:line-${entry.index + 1}:${itemTarget}`,
+        id: `${metric}:line-${entry.logLine}:${itemTarget}`,
         rank: RANKS[metric],
         metric,
         scope: "event",
@@ -104,13 +105,16 @@ function isActionable(acceptance, metric) {
 }
 export function buildTelemetryRemediationReport(events, now = new Date(), policy = DEFAULT_TELEMETRY_ACCEPTANCE_POLICY) {
     const acceptance = analyzeTelemetryAcceptance(events, now, policy);
-    const all = events.map((event, index) => ({
+    const { operations, operationLines, hookRows } = partitionTelemetryUsage(events);
+    const timeOf = (event) => event.timestamp === undefined ||
+        !Number.isFinite(Date.parse(event.timestamp))
+        ? null
+        : Date.parse(event.timestamp);
+    const all = operations.map((event, index) => ({
         event,
         index,
-        time: event.timestamp === undefined ||
-            !Number.isFinite(Date.parse(event.timestamp))
-            ? null
-            : Date.parse(event.timestamp),
+        logLine: operationLines[index] ?? index + 1,
+        time: timeOf(event),
     }));
     const recentStart = Math.max(0, all.length - policy.eventLimit);
     const recent = all.slice(recentStart);
@@ -142,7 +146,7 @@ export function buildTelemetryRemediationReport(events, now = new Date(), policy
             const match = (preflights.get(fingerprint(entry.event)) ?? []).findLast((candidate) => compatible(candidate.event, entry.event) &&
                 withinAge(candidate.time, entry.time, policy.preflightMaxAgeSeconds));
             if (match === undefined) {
-                items.push(eventItem("validation_before_upsert", entry, target(entry.event), "No recent successful preflight matches this exact payload and correlation context.", "Run kb_validate_upsert for this exact payload in the same session/actor context before retrying once."));
+                items.push(eventItem("validation_before_upsert", entry, target(entry.event), "No recent successful preflight matches this exact payload and correlation context.", "Run kb_upsert with dryRun true (CLI: validate-upsert) for this exact payload in the same session/actor context before retrying once."));
             }
         }
     }
@@ -176,10 +180,22 @@ export function buildTelemetryRemediationReport(events, now = new Date(), policy
                         entry.event.semantic_source_hash) &&
                 withinAge(candidate.time, entry.time, policy.advisorMaxAgeSeconds));
             if (match === undefined) {
-                items.push(eventItem("advisor_before_requirement_write", entry, requirementId, "No recent semantic-advisor event matches this requirement, source hash, and correlation context.", "Run kb_semantic_advisor on the complete prose in the same session/actor context before the next upsert."));
+                items.push(eventItem("advisor_before_requirement_write", entry, requirementId, "No recent semantic-advisor event matches this requirement, source hash, and correlation context.", "Run kb_model with mode analyze (CLI: semantic-advisor) on the complete prose in the same session/actor context before the next upsert."));
             }
         }
     }
+    if (isActionable(acceptance, "lookup_before_first_edit")) {
+        for (const { edit, lookedUp } of firstLinkedEdits(hookRows, recentStart)) {
+            if (lookedUp)
+                continue;
+            items.push(eventItem("lookup_before_first_edit", {
+                event: edit.event,
+                index: edit.operationsBefore,
+                logLine: edit.logLine,
+                time: timeOf(edit.event),
+            }, edit.event.path ?? "unknown path", "This session edited a requirement-linked file before any kb_search or kb_query.", "Before the next edit of this file, run kb_search for the change or kb_query with this sourceFile, and read the requirements it names."));
+        }
+    }
     if (isActionable(acceptance, "source_lookup_zero_result_rate")) {
         for (const entry of recent) {
             const sourceFile = args(entry.event).sourceFile;

package/dist/relationships/shards.d.ts

@@ -30,6 +30,11 @@ export declare function computeShardPath(kbRoot: string, entityId: string): stri
  * Throws on parse errors.
  */
 export declare function readShard(shardPath: string): RelationshipRecord[];
+/**
+ * Parses relationship shard text read from `shardPath`.
+ * Returns an empty array for blank text. Throws on parse errors.
+ */
+export declare function parseShardText(content: string, shardPath: string): RelationshipRecord[];
 /**
  * Writes a relationship shard file.
  * Creates parent directories if needed.
@@ -65,6 +70,14 @@ export declare function appendRelationship(kbRoot: string, relationship: Omit<Re
     shardPath: string;
     recordId: string;
 };
+/**
+ * The shard text appendRelationship would publish for `relationship`, without
+ * writing it: `existing` is the current shard text, or null when the shard
+ * file does not exist. Returns null when the shard already records the
+ * relationship. Callers that must journal exact after-bytes before any write
+ * (atomic plan application) render a shard through this function.
+ */
+export declare function renderShardWithRelationship(shardPath: string, existing: string | null, relationship: Omit<RelationshipRecord, "id">): string | null;
 /**
  * Lists all shard files in the relationships directory.
  */

package/dist/relationships/shards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shards.d.ts","sourceRoot":"","sources":["../../src/relationships/shards.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAsFjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAAE,GAC5B,IAAI,CAoBN;AAwBD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC,CAAC;AAEH;;;GAGG;AACH;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,oBAAoB,EAAE,EAC1C,SAAS,EAAE,MAAM,GAChB,MAAM,CA2BR;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,oBAAoB,EAAE,GACzC,0BAA0B,EAAE,CAwC9B;AAqCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,GAC3C;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAwCzC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAUnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAUlE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,kBAAkB,EAAE,EAC7B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,kBAAkB,EAAE,CAKtB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAE1B,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,QAAQ,EAAE,kBAAkB,EAAE,GAC7B,kBAAkB,EAAE,CAgCtB"}
+{"version":3,"file":"shards.d.ts","sourceRoot":"","sources":["../../src/relationships/shards.ts"],"names":[],"mappings":"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"}

package/dist/relationships/shards.js

@@ -51,7 +51,14 @@ export function readShard(shardPath) {
     if (!fs.existsSync(shardPath)) {
         return [];
     }
-    const content = fs.readFileSync(shardPath, "utf8");
+    return parseShardText(fs.readFileSync(shardPath, "utf8"), shardPath);
+}
+/**
+ * Parses relationship shard text read from `shardPath`.
+ * Returns an empty array for blank text. Throws on parse errors.
+ */
+// implements REQ-kibi-operation-interface-parity
+export function parseShardText(content, shardPath) {
     if (!content.trim()) {
         return [];
     }
@@ -121,7 +128,10 @@ export function writeShard(shardPath, records) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    // Sort and dedupe records
+    atomicWriteText(shardPath, renderShardRecords(records));
+}
+/** Canonical shard text for `records`: sorted and deduplicated. */
+function renderShardRecords(records) {
     const sorted = sortRecords(records);
     const seen = new Set();
     const unique = [];
@@ -132,8 +142,7 @@ export function writeShard(shardPath, records) {
         seen.add(key);
         unique.push(record);
     }
-    const yamlContent = serializeToYAML(unique);
-    atomicWriteText(shardPath, yamlContent);
+    return serializeToYAML(unique);
 }
 /**
  * Publish one canonical shard replacement atomically. Relationship shards are
@@ -254,32 +263,49 @@ function sortRecords(records) {
  */
 export function appendRelationship(kbRoot, relationship) {
     const shardPath = computeShardPath(kbRoot, relationship.from);
-    const existing = readShard(shardPath);
-    // Generate deterministic ID
-    const recordId = relationshipIdFor(relationship.type, relationship.from, relationship.to);
-    // Check if relationship already exists
-    const exists = existing.some((r) => r.type === relationship.type &&
-        r.from === relationship.from &&
-        r.to === relationship.to);
-    if (!exists) {
-        const newRecord = {
-            ...relationship,
-            id: recordId,
-        };
-        if (fs.existsSync(shardPath)) {
-            const document = parseDocument(fs.readFileSync(shardPath, "utf8"));
-            const sequence = document.get("relationships", true);
-            if (!sequence || typeof sequence !== "object" || !("items" in sequence)) {
-                throw new Error(`Invalid shard file: missing 'relationships' array at ${shardPath}`);
-            }
-            sequence.items.push(newRecord);
-            atomicWriteText(shardPath, document.toString());
-        }
-        else {
-            writeShard(shardPath, [newRecord]);
+    const existing = fs.existsSync(shardPath)
+        ? fs.readFileSync(shardPath, "utf8")
+        : null;
+    const next = renderShardWithRelationship(shardPath, existing, relationship);
+    if (next !== null) {
+        if (existing === null) {
+            fs.mkdirSync(path.dirname(shardPath), { recursive: true });
         }
+        atomicWriteText(shardPath, next);
     }
-    return { shardPath, recordId };
+    return {
+        shardPath,
+        recordId: relationshipIdFor(relationship.type, relationship.from, relationship.to),
+    };
+}
+/**
+ * The shard text appendRelationship would publish for `relationship`, without
+ * writing it: `existing` is the current shard text, or null when the shard
+ * file does not exist. Returns null when the shard already records the
+ * relationship. Callers that must journal exact after-bytes before any write
+ * (atomic plan application) render a shard through this function.
+ */
+// implements REQ-kibi-operation-interface-parity, REQ-core-atomic-upsert-persistence
+export function renderShardWithRelationship(shardPath, existing, relationship) {
+    const records = existing === null ? [] : parseShardText(existing, shardPath);
+    if (records.some((r) => r.type === relationship.type &&
+        r.from === relationship.from &&
+        r.to === relationship.to)) {
+        return null;
+    }
+    const newRecord = {
+        ...relationship,
+        id: relationshipIdFor(relationship.type, relationship.from, relationship.to),
+    };
+    if (existing === null)
+        return renderShardRecords([newRecord]);
+    const document = parseDocument(existing);
+    const sequence = document.get("relationships", true);
+    if (!sequence || typeof sequence !== "object" || !("items" in sequence)) {
+        throw new Error(`Invalid shard file: missing 'relationships' array at ${shardPath}`);
+    }
+    sequence.items.push(newRecord);
+    return document.toString();
 }
 /**
  * Lists all shard files in the relationships directory.

package/dist/runtime/cli-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/cli-runtime.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAKV,gBAAgB,EAEhB,cAAc,EACf,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,KAAK,qBAAqB,EAE3B,MAAM,6BAA6B,CAAC;AAErC,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAOR;AAkFD,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,cAAmB,GAC3B,gBAAgB,CAwHlB"}
+{"version":3,"file":"cli-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/cli-runtime.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAKV,gBAAgB,EAEhB,cAAc,EACf,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,6BAA6B,CAAC;AAOrC,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAOR;AA2GD,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,cAAmB,GAC3B,gBAAgB,CA4IlB"}

package/dist/runtime/cli-runtime.js

@@ -3,7 +3,8 @@ import { retryAttachAfterBreakingStaleLock } from "../prolog/store-lock.js";
 import { EngineClient } from "../engine.js";
 import { CapabilityRegistryCache, ensureCapabilityRegistry, } from "../plugins/registry.js";
 import { nodeFilesystem, nodeGit, nodeNetwork, } from "../public/operations/node-ports.js";
-import { resolveBranchAttachment, } from "../utils/branch-resolver.js";
+import { resolveReadBranchAttachment, } from "../utils/branch-resolver.js";
+import { declaresWriteEffect, refreshDetachedSnapshot, resolveOperationAttachment, } from "./detached-snapshot.js";
 export function attachmentFailureMessage(attachment) {
     const isNonGitContext = attachment.code === "NOT_A_GIT_REPO" ||
         attachment.code === "GIT_NOT_AVAILABLE";
@@ -65,6 +66,27 @@ function resolvePluginsOption(plugins) {
         return plugins;
     return async () => plugins;
 }
+/**
+ * The detached-HEAD snapshot attachment for a KB read that may run without
+ * Prolog (status), or undefined when the checkout resolves normally (that
+ * path keeps its lazy, non-mutating behavior). A failed snapshot compile is
+ * reported but not fatal, so status can still diagnose the snapshot store.
+ */
+// implements REQ-branch-store-recovery-v4
+async function resolveDetachedReadAttachment(root) {
+    const attachment = resolveReadBranchAttachment(root);
+    if ("error" in attachment || attachment.readOnly === undefined) {
+        return undefined;
+    }
+    console.warn(`[KIBI] ${attachment.readOnly.notice}`);
+    try {
+        await refreshDetachedSnapshot(root, attachment);
+    }
+    catch (error) {
+        console.warn(`[KIBI] ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return attachment;
+}
 // implements REQ-kibi-operation-interface-parity
 export function createCliRuntime(options = {}) {
     const ownedPrologs = new WeakMap();
@@ -102,10 +124,16 @@ export function createCliRuntime(options = {}) {
                 // That keeps pre-init and damaged-store diagnostics non-mutating.
                 let lazyProlog = merged.prolog;
                 const lazyContext = {};
+                // A KB read on a detached HEAD answers from the checkout's snapshot;
+                // resolve it up front so the operation reports which store it read.
+                const detachedAttachment = !declaresWriteEffect(spec.effects) && spec.effects.includes("kb-read")
+                    ? await resolveDetachedReadAttachment(root)
+                    : undefined;
                 const ensureProlog = async () => {
                     if (lazyProlog !== undefined)
                         return bindSignal(lazyProlog, signal);
-                    const attachment = resolveBranchAttachment(root);
+                    const attachment = detachedAttachment ??
+                        (await resolveOperationAttachment(root, spec));
                     if ("error" in attachment) {
                         throw new Error(`Failed to resolve active branch: ${attachment.error}`);
                     }
@@ -125,16 +153,29 @@ export function createCliRuntime(options = {}) {
                         ? { prolog: bindSignal(merged.prolog, signal) }
                         : {}),
                     ...(lazyEngine ? { engine: lazyEngine } : {}),
+                    ...(detachedAttachment
+                        ? { branchAttachment: detachedAttachment }
+                        : {}),
                     ensureProlog,
                 };
                 lazyContext.current = context;
                 return context;
             }
-            const attachment = resolveBranchAttachment(root);
+            let attachment;
+            try {
+                attachment = await resolveOperationAttachment(root, spec);
+            }
+            catch (error) {
+                await merged.prolog?.terminate?.();
+                throw error;
+            }
             if ("error" in attachment) {
                 await merged.prolog?.terminate?.();
                 throw new Error(attachmentFailureMessage(attachment));
             }
+            if (attachment.readOnly !== undefined) {
+                console.warn(`[KIBI] ${attachment.readOnly.notice}`);
+            }
             if (attachment.migrationRequired) {
                 console.warn(`[KIBI] Legacy branch attachment: Git '${attachment.gitBranch}' is reading KB '${attachment.kbBranch}'. Migrate with 'kibi branch migrate --from ${attachment.kbBranch} --to ${attachment.gitBranch} --apply'; writes are blocked until then.`);
             }

package/dist/runtime/detached-snapshot.d.ts

@@ -0,0 +1,38 @@
+import type { OperationEffect } from "../public/operations/types.js";
+import { type BranchAttachment, type BranchResolutionError } from "../utils/branch-resolver.js";
+/** Envelope diagnostic code reported while a detached snapshot is attached. */
+export declare const DETACHED_HEAD_READ_ONLY_CODE = "detached_head_read_only";
+export type DetachedReadOnlyDiagnostic = {
+    readonly code: typeof DETACHED_HEAD_READ_ONLY_CODE;
+    readonly severity: "warning";
+    readonly message: string;
+    readonly detail: {
+        readonly head: string;
+        readonly branchesAtHead: readonly string[];
+        readonly kbBranch: string;
+        readonly storePath: string;
+        readonly writes: "refused";
+    };
+};
+/** True when an operation declares a KB or workspace write. */
+export declare function declaresWriteEffect(effects: readonly OperationEffect[] | readonly string[]): boolean;
+/**
+ * Compile (or incrementally refresh) the read-only snapshot of a detached
+ * checkout. The snapshot store is a cache of the checkout's tracked sources:
+ * refreshing it never touches a branch KB or an authored file.
+ */
+export declare function refreshDetachedSnapshot(workspaceRoot: string, attachment: BranchAttachment): Promise<void>;
+/**
+ * Resolve the branch attachment an operation may use.
+ *
+ * Writes keep the exact-branch contract and receive an actionable refusal on
+ * a detached HEAD. Reads on a detached HEAD that no single branch points at
+ * attach a freshly compiled read-only snapshot of the checkout.
+ */
+export declare function resolveOperationAttachment(workspaceRoot: string, spec: {
+    readonly name: string;
+    readonly effects: readonly OperationEffect[];
+}): Promise<BranchAttachment | BranchResolutionError>;
+/** The envelope diagnostic for an operation answered from a snapshot. */
+export declare function detachedReadOnlyDiagnostic(attachment: BranchAttachment | undefined): DetachedReadOnlyDiagnostic | undefined;
+//# sourceMappingURL=detached-snapshot.d.ts.map

package/dist/runtime/detached-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detached-snapshot.d.ts","sourceRoot":"","sources":["../../src/runtime/detached-snapshot.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAI3B,MAAM,6BAA6B,CAAC;AAErC,+EAA+E;AAE/E,eAAO,MAAM,4BAA4B,4BAA4B,CAAC;AAGtE,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,IAAI,EAAE,OAAO,4BAA4B,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;QAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;KAC5B,CAAC;CACH,CAAC;AAEF,+DAA+D;AAE/D,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,MAAM,EAAE,GACtD,OAAO,CAIT;AAED;;;;GAIG;AAEH,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,gBAAgB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;GAMG;AAEH,wBAAsB,0BAA0B,CAC9C,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,GAC5E,OAAO,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,CAoBnD;AAED,yEAAyE;AAEzE,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,gBAAgB,GAAG,SAAS,GACvC,0BAA0B,GAAG,SAAS,CAexC"}