kibi-cli 2.25.0 → 2.26.1

package/dist/operations/migration/schema6.js

@@ -21,16 +21,18 @@ import { FIRMNESS_FROM_ORIGIN_SCHEMA_VERSION } from "../../public/operations/dec
 import { migrationAction, } from "../../public/operations/migration-plan.js";
 import { CLOSE_SUPERSEDED_REQUIREMENTS_ACTION_ID, CLOSE_SUPERSEDED_REQUIREMENTS_CODE, MIGRATION_SYNC_ACTION_ID, MIGRATION_SYNC_CODE, SOURCE_PATH_REWRITE_ACTION_ID, SOURCE_PATH_REWRITE_CODE, closeSupersededRequirementsActionInput, exceptionUnapprovedActionInput, migrationSyncActionInput, sourcePathReviewActionInput, sourcePathRewriteActionInput, supersessionCycleReviewActionInput, } from "../../public/operations/schema6-check-actions.js";
 import { readAllShards } from "../../relationships/shards.js";
+import { KB_PATHS } from "../../utils/kb-paths.js";
 import { CONTEXT_MISSING_TAG_CODE, SEMANTIC_TEXT_PIN_CODE, applyContextMissingTags, applySemanticTextPins, countByType, planContextMissingTags, planSemanticTextPins, } from "./entity-body-context.js";
 import { FIRM_SUPERSEDE_ACKNOWLEDGE_CODE, applyFirmSupersedeAcknowledgement, planFirmSupersedeAcknowledgement, } from "./firm-supersede.js";
 import { applyInventoryRederivation, applyInventoryRederivationDroppingGrounding, planInventoryRederivation, } from "./inventory-rederive.js";
 import { listLaneMarkdownFiles } from "./kb-sources.js";
 import { applyOriginBackfill, planOriginBackfill } from "./origin-backfill.js";
 import { POLARITY_VALUE_BACKFILL_CODE, applyPolarityValueBackfill, planPolarityValueBackfill, } from "./polarity-values.js";
-import { applyRequirementStatusMapping, planRequirementStatusMappings, } from "./requirement-status.js";
+import { DELIVERED_REQUIREMENT_TAG, applyDeliveredStatusMappings, applyRequirementStatusMapping, planRequirementStatusMappings, } from "./requirement-status.js";
 import { applySourcePathRepairs, findSourceRepairs, plannedSourcePathRepairs, } from "./source-paths.js";
 import { applySupersededClosures, planSupersededClosures, } from "./superseded-closure.js";
 import { SUPERSEDES_REASON_ACKNOWLEDGE_CODE, applySupersedesReasonAcknowledgement, planSupersedesReasonAcknowledgement, } from "./supersedes-reason.js";
+import { coordinateRefreshFailureMessage, readGeneratedManifestBytes, refreshCoordinatesAfterMigration, } from "./symbol-coordinates-refresh.js";
 import { SYMBOL_LEGACY_LINK_MARK_ACTION_ID, SYMBOL_LEGACY_LINK_MARK_CODE, applySymbolLegacyLinks, planSymbolLegacyLinks, } from "./symbol-legacy-links.js";
 /** The KB schema generation that introduced entity `origin`. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
@@ -56,6 +58,11 @@ export const SEMANTIC_INVENTORY_REDERIVE_DROP_GROUNDING_CODE = "semantic_invento
 /** Review, applied only when approved by id: map a legacy requirement status. */
 // implements REQ-cli-schema-migration
 export const REQ_STATUS_VOCABULARY_MAP_CODE = "req_status_vocabulary_map";
+/** Automatic: map delivery statuses to `closed` plus the tag `implemented`. */
+// implements REQ-cli-schema-migration
+export const REQ_STATUS_DELIVERED_MAP_CODE = "req_status_delivered_map";
+// implements REQ-cli-schema-migration
+export const REQ_STATUS_DELIVERED_MAP_ACTION_ID = "req-status-delivered-map";
 /** Automatic: stamp `origin: {kind: migration}` on authored entities. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
 export const ENTITY_ORIGIN_BACKFILL_CODE = "entity_origin_backfill";
@@ -210,16 +217,52 @@ function plannedDrops(action) {
         : []);
 }
 /**
- * One action per requirement whose status is outside the vocabulary: a
- * review (the target status is a semantic choice) carrying the suggested
- * mapping and the inventory drift the requirement shows once mapped. With a
- * suggestion it is executable when approved by id; the re-derivation of the
- * latent drift depends on it.
+ * The automatic action for requirements whose status is delivery vocabulary
+ * (`implemented`, `done`, `completed`): sync cannot compile them, and their
+ * one lossless reading is `closed` plus the tag `implemented`.
+ */
+function deliveredStatusAction(findings) {
+    return migrationAction({
+        id: REQ_STATUS_DELIVERED_MAP_ACTION_ID,
+        code: REQ_STATUS_DELIVERED_MAP_CODE,
+        category: "schema",
+        safety: "automatic",
+        autoApplicable: true,
+        invocation: { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
+        affectedEntityIds: findings.map((finding) => finding.requirementId),
+        affectedFiles: findings.map((finding) => finding.path),
+        postconditions: [{ rule: "req-status-vocabulary", findings: 0 }],
+        evidence: {
+            reason: "Delivery statuses are outside the entity schema, so kibi sync cannot compile these requirements and every store-backed tool misses them. Each becomes status closed with the tag implemented, which Kibi reads as a delivered requirement that still owes coverage; only the status line and the tags change.",
+            count: findings.length,
+            mappings: findings.map((finding) => ({
+                requirementId: finding.requirementId,
+                path: finding.path,
+                from: finding.status,
+                to: finding.automatic?.status ?? "closed",
+                tag: finding.automatic?.tag ?? DELIVERED_REQUIREMENT_TAG,
+            })),
+        },
+    });
+}
+/**
+ * Requirements whose status is outside the vocabulary. Delivery vocabulary
+ * gets one automatic action (see deliveredStatusAction). Every other status
+ * gets one review action (the target status is a semantic choice) carrying
+ * the suggested mapping and the inventory drift the requirement shows once
+ * mapped. With a suggestion it is executable when approved by id; the
+ * re-derivation of the latent drift depends on it.
  */
 // implements REQ-cli-schema-migration, REQ-kibi-proposition-complete-ingestion
 export function requirementStatusActions(workspaceRoot) {
     const actions = [];
-    for (const finding of planRequirementStatusMappings(workspaceRoot)) {
+    const findings = planRequirementStatusMappings(workspaceRoot);
+    const delivered = findings.filter((finding) => finding.automatic !== null);
+    if (delivered.length > 0)
+        actions.push(deliveredStatusAction(delivered));
+    for (const finding of findings) {
+        if (finding.automatic !== null)
+            continue;
         const id = `req-status-vocabulary-map-${finding.requirementId}`;
         const drift = finding.latentDrift;
         const target = finding.suggestedStatus;
@@ -232,7 +275,9 @@ export function requirementStatusActions(workspaceRoot) {
             invocation: target === null
                 ? {
                     kind: "review",
-                    instruction: `${finding.requirementId} (${finding.path}) has status ${finding.status}, which is not a requirement status, so it is skipped by the proof ladder and its semantic inventory is never validated. Set status to open, in_progress or closed (legacy: active, approved) in the file, or use proof_exempt to park it, then rerun kibi migrate.`,
+                    instruction: finding.extractionError === null
+                        ? `${finding.requirementId} (${finding.path}) has status ${finding.status}, which is not a requirement status, so it is skipped by the proof ladder and its semantic inventory is never validated. Set status to open, in_progress or closed (legacy: active, approved) in the file, or use proof_exempt to park it, then rerun kibi migrate.`
+                        : `${finding.requirementId} (${finding.path}) has status ${finding.status}, which is not a status Kibi knows, so kibi sync cannot compile it (${finding.extractionError}) and kb_query, kb_coverage and kb_upsert do not see it. Set status to open, in_progress or closed in the file (closed with the tag implemented for delivered work), then run kibi sync and rerun kibi migrate.`,
                 }
                 : { kind: "cli", command_argv: approvalArgv([id]) },
             affectedEntityIds: [finding.requirementId],
@@ -241,9 +286,14 @@ export function requirementStatusActions(workspaceRoot) {
             dispositionRequired: true,
             allowedDispositions: ["fixed", "deferred"],
             evidence: {
-                reason: `Status ${finding.status} is ADR or lifecycle vocabulary, not a requirement status: the requirement is skipped by the proof ladder and kibi sync never validates its semantic inventory.`,
+                reason: finding.extractionError === null
+                    ? `Status ${finding.status} is ADR or lifecycle vocabulary, not a requirement status: the requirement is skipped by the proof ladder and kibi sync never validates its semantic inventory.`
+                    : `Status ${finding.status} is outside the entity schema, so kibi sync cannot compile the requirement at all.`,
                 status: finding.status,
                 suggestedStatus: target,
+                ...(finding.extractionError === null
+                    ? {}
+                    : { extractionError: finding.extractionError }),
                 ...(target === null
                     ? {}
                     : {
@@ -515,9 +565,13 @@ export function buildSchema6MigrationFragment(input) {
         if (!plan.safe && plan.rederivableByDroppingGrounding)
             actions.push(dropGroundingAction(plan));
     }
-    // Requirements with a status outside the vocabulary: mapping is a review,
-    // and their latent drift is re-derived only after an approved mapping.
-    actions.push(...requirementStatusActions(input.workspaceRoot));
+    // Requirements with a status outside the vocabulary: delivery statuses are
+    // mapped automatically; any other mapping is a review, and its latent drift
+    // is re-derived only after an approved mapping.
+    const statusActions = requirementStatusActions(input.workspaceRoot);
+    actions.push(...statusActions);
+    if (statusActions.some((action) => action.id === REQ_STATUS_DELIVERED_MAP_ACTION_ID))
+        sourceRewriteActionIds.push(REQ_STATUS_DELIVERED_MAP_ACTION_ID);
     if (drift.some((plan) => !plan.safe)) {
         diagnostics.push(`${drift.filter((plan) => !plan.safe).length} requirement inventory(ies) need a manual fix before kibi sync succeeds; see the semantic_inventory_review actions.`);
     }
@@ -637,7 +691,9 @@ export function symbolLegacyLinkAction(workspaceRoot) {
         autoApplicable: true,
         invocation: { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
         affectedEntityIds: plan.targets.map((target) => target.id),
-        affectedFiles: [plan.manifestPath],
+        // A mark changes the record's coordinate identity, so the action also
+        // regenerates the coordinate artifact.
+        affectedFiles: [plan.manifestPath, KB_PATHS.symbolCoordinates],
         postconditions: [{ rule: "symbol_granularity_violation", findings: 0 }],
         evidence: {
             reason: "These symbols link a source file coarsely while it declares narrower behavioral symbols, so the staged check (kibi check --staged) blocks the next commit that touches them. Each gets granularity_reason: legacy-link (accepted legacy granularity); no link moves and no other field changes.",
@@ -725,6 +781,12 @@ export async function applySchema6MigrationAction(action, context) {
             applyRequirementStatusMapping(context.workspaceRoot, mapping.path, mapping.from, mapping.to);
             return;
         }
+        case REQ_STATUS_DELIVERED_MAP_CODE: {
+            const result = applyDeliveredStatusMappings(context.workspaceRoot, new Set(action.affectedEntityIds));
+            if (result.skipped.length > 0)
+                throw new Error(`Could not map the status of ${result.skipped.map((skip) => `${skip.path} (${skip.reason})`).join(", ")}; set status: closed and add the tag implemented by hand.`);
+            return;
+        }
         case SEMANTIC_INVENTORY_REDERIVE_DROP_GROUNDING_CODE: {
             const requirementId = action.affectedEntityIds[0];
             const contractHash = action.evidence.contractHash;
@@ -737,6 +799,7 @@ export async function applySchema6MigrationAction(action, context) {
             applyOriginBackfill(context.workspaceRoot, context.clock().toISOString());
             return;
         case SYMBOL_LEGACY_LINK_MARK_CODE: {
+            const before = readGeneratedManifestBytes(context.workspaceRoot);
             const result = applySymbolLegacyLinks(context.workspaceRoot, {
                 ...(typeof action.evidence.manifestHash === "string"
                     ? { expectedHash: action.evidence.manifestHash }
@@ -745,6 +808,11 @@ export async function applySchema6MigrationAction(action, context) {
             });
             if (result.unmarked.length > 0)
                 throw new Error(`Could not mark ${result.unmarked.join(", ")} as legacy-link in place; add granularity_reason: legacy-link to them by hand.`);
+            // A legacy-link mark changes the record's coordinate identity; keep
+            // the generated artifact current so the next commit carries no drift.
+            const refresh = await refreshCoordinatesAfterMigration(context.workspaceRoot, before);
+            if (refresh.outcome === "failed")
+                console.warn(`Warning: ${coordinateRefreshFailureMessage(refresh.reason)}`);
             return;
         }
         case CLOSE_SUPERSEDED_REQUIREMENTS_CODE: {
@@ -791,6 +859,7 @@ export const SCHEMA6_AUTOMATIC_CODES = new Set([
     SUPERSEDES_REASON_ACKNOWLEDGE_CODE,
     FIRM_SUPERSEDE_ACKNOWLEDGE_CODE,
     SEMANTIC_INVENTORY_REDERIVE_CODE,
+    REQ_STATUS_DELIVERED_MAP_CODE,
     ENTITY_ORIGIN_BACKFILL_CODE,
     CLOSE_SUPERSEDED_REQUIREMENTS_CODE,
     SOURCE_PATH_REWRITE_CODE,

package/dist/operations/migration/symbol-coordinates-refresh.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bytes of the symbols manifest and its generated coordinate artifact at
+ * their canonical paths; null for a file that does not exist.
+ */
+export type GeneratedManifestBytes = Readonly<{
+    symbols: string | null;
+    coordinates: string | null;
+}>;
+/** Snapshot taken before a migration writes, to tell what it rewrote. */
+export declare function readGeneratedManifestBytes(workspaceRoot: string): GeneratedManifestBytes;
+/** What the post-migration coordinate refresh did. */
+export type MigrationCoordinateRefresh = {
+    outcome: "skipped";
+} | {
+    outcome: "refreshed";
+} | {
+    outcome: "failed";
+    reason: string;
+};
+/**
+ * Refresh generated symbol coordinates the way
+ * `kibi sync --refresh-symbol-coordinates` does, after a migration rewrote or
+ * moved the symbols manifest. The coordinate artifact binds each record by an
+ * identity hash that includes `granularity_reason`, so a legacy-link mark
+ * leaves the committed coordinates stale; without this refresh the pre-commit
+ * generated-manifest gate rejects the first commit after a migration.
+ *
+ * Skipped when `before` shows the run left both files untouched, or when the
+ * manifest has no symbols. A refresh failure is returned, not thrown: the
+ * migration itself is complete, and the caller tells the user to refresh by
+ * hand before committing.
+ */
+export declare function refreshCoordinatesAfterMigration(workspaceRoot: string, before?: GeneratedManifestBytes): Promise<MigrationCoordinateRefresh>;
+/** The line a migration prints when its coordinate refresh failed. */
+export declare function coordinateRefreshFailureMessage(reason: string): string;
+//# sourceMappingURL=symbol-coordinates-refresh.d.ts.map

package/dist/operations/migration/symbol-coordinates-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-coordinates-refresh.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/symbol-coordinates-refresh.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,CAAC;AAMH,yEAAyE;AAEzE,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,GACpB,sBAAsB,CAMxB;AAYD,sDAAsD;AAEtD,MAAM,MAAM,0BAA0B,GAClC;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,GACtB;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,GACxB;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C;;;;;;;;;;;;GAYG;AAEH,wBAAsB,gCAAgC,CACpD,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,0BAA0B,CAAC,CA0CrC;AAED,sEAAsE;AAEtE,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtE"}

package/dist/operations/migration/symbol-coordinates-refresh.js

@@ -0,0 +1,99 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { load as parseYAML } from "js-yaml";
+import { resolveSymbolsManifestPaths } from "../../utils/manifest-paths.js";
+import { republishPendingSourceReceipt } from "../mutation/source-authoring.js";
+import { withSymbolCompilerLock } from "../mutation/symbol-compiler-lock.js";
+function readOrNull(filePath) {
+    return existsSync(filePath) ? readFileSync(filePath, "utf8") : null;
+}
+/** Snapshot taken before a migration writes, to tell what it rewrote. */
+// implements REQ-cli-migration-first-commit
+export function readGeneratedManifestBytes(workspaceRoot) {
+    const paths = resolveSymbolsManifestPaths(workspaceRoot);
+    return {
+        symbols: readOrNull(paths.symbolsPath),
+        coordinates: readOrNull(paths.coordinatesPath),
+    };
+}
+function hasSymbols(content) {
+    try {
+        const parsed = parseYAML(content);
+        return Array.isArray(parsed?.symbols) && parsed.symbols.length > 0;
+    }
+    catch {
+        // An unreadable manifest is reported by the refresh itself.
+        return true;
+    }
+}
+/**
+ * Refresh generated symbol coordinates the way
+ * `kibi sync --refresh-symbol-coordinates` does, after a migration rewrote or
+ * moved the symbols manifest. The coordinate artifact binds each record by an
+ * identity hash that includes `granularity_reason`, so a legacy-link mark
+ * leaves the committed coordinates stale; without this refresh the pre-commit
+ * generated-manifest gate rejects the first commit after a migration.
+ *
+ * Skipped when `before` shows the run left both files untouched, or when the
+ * manifest has no symbols. A refresh failure is returned, not thrown: the
+ * migration itself is complete, and the caller tells the user to refresh by
+ * hand before committing.
+ */
+// implements REQ-cli-migration-first-commit
+export async function refreshCoordinatesAfterMigration(workspaceRoot, before) {
+    const after = readGeneratedManifestBytes(workspaceRoot);
+    if (after.symbols === null || !hasSymbols(after.symbols))
+        return { outcome: "skipped" };
+    if (before !== undefined &&
+        before.symbols === after.symbols &&
+        before.coordinates === after.coordinates)
+        return { outcome: "skipped" };
+    const { symbolsPath, coordinatesPath } = resolveSymbolsManifestPaths(workspaceRoot);
+    try {
+        const { refreshManifestCoordinates } = await import("../../commands/sync/manifest.js");
+        await withSymbolCompilerLock(workspaceRoot, () => refreshManifestCoordinates(symbolsPath, workspaceRoot, {
+            refreshSymbolCoordinates: true,
+        }));
+        // Files the migration moved are still untracked and pinned by a
+        // pending-source receipt; rebind each to its refreshed bytes so the next
+        // sync does not refuse it as hash drift. A file without a receipt is
+        // left alone.
+        for (const filePath of [symbolsPath, coordinatesPath]) {
+            if (!existsSync(filePath))
+                continue;
+            republishPendingSourceReceipt(workspaceRoot, path.relative(workspaceRoot, filePath).split(path.sep).join("/"), createHash("sha256")
+                .update(readFileSync(filePath, "utf8"), "utf8")
+                .digest("hex"));
+        }
+        return { outcome: "refreshed" };
+    }
+    catch (error) {
+        return {
+            outcome: "failed",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** The line a migration prints when its coordinate refresh failed. */
+// implements REQ-cli-migration-first-commit
+export function coordinateRefreshFailureMessage(reason) {
+    return `Could not refresh symbol coordinates after the migration (${reason}). Run 'kibi sync --refresh-symbol-coordinates' and stage .kb/symbols.yaml and .kb/symbol-coordinates.yaml before the first commit, or the pre-commit hook reports generated manifest drift.`;
+}

package/dist/operations/mutation/source-authoring.d.ts

@@ -43,6 +43,15 @@ export declare function normalizeAuthoredSourcePath(workspaceRoot: string, sourc
  */
 export declare function configuredSourceTarget(workspaceRoot: string, type: string): string | undefined;
 export declare function hasConfiguredSourceTarget(workspaceRoot: string, type: string): boolean;
+/**
+ * The absolute authored document an upsert of an entity the store does not
+ * hold would write: the same resolution writeSourceForUpsert uses, so a check
+ * on that file judges the file the writer merges into. Undefined when the
+ * writer has no target (it reports DOCUMENT_PATH_REQUIRED itself).
+ */
+export declare function newEntitySourceTarget(context: OperationContext, input: UpsertInput): string | undefined;
+/** The front matter of an authored document; throws on YAML it cannot parse. */
+export declare function authoredFrontmatter(content: string): Record<string, unknown>;
 /** Generated coordinate fields belong exclusively to `.kb/symbol-coordinates.yaml`. */
 export declare const GENERATED_SYMBOL_FIELDS: readonly ["sourceLine", "sourceColumn", "sourceEndLine", "sourceEndColumn", "coordinatesGeneratedAt"];
 export declare function manifestRelationships(item: unknown): Array<{

package/dist/operations/mutation/source-authoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-authoring.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/source-authoring.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"source-authoring.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/source-authoring.ts"],"names":[],"mappings":"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"}

package/dist/operations/mutation/source-authoring.js

@@ -248,6 +248,26 @@ function sourcePath(context, input, entity, existing) {
     }
     return resolveContainedSourcePath(context.workspaceRoot, relative);
 }
+/**
+ * The absolute authored document an upsert of an entity the store does not
+ * hold would write: the same resolution writeSourceForUpsert uses, so a check
+ * on that file judges the file the writer merges into. Undefined when the
+ * writer has no target (it reports DOCUMENT_PATH_REQUIRED itself).
+ */
+// implements REQ-kibi-uncompiled-source-visibility
+export function newEntitySourceTarget(context, input) {
+    try {
+        return sourcePath(context, input, { id: input.id }, undefined);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The front matter of an authored document; throws on YAML it cannot parse. */
+// implements REQ-kibi-uncompiled-source-visibility
+export function authoredFrontmatter(content) {
+    return bodyAndFrontmatter(content).frontmatter;
+}
 /**
  * Front matter keys an upsert never writes: runtime provenance/timestamps
  * belong to the compiled entity, not to the authored source artifact, and

package/dist/operations/mutation/stored-entity.d.ts

@@ -9,6 +9,11 @@ export type StoredEntityLookup = {
     readonly exists: () => Promise<boolean>;
     /** The stored entity, loaded only when one exists. */
     readonly entity: () => Promise<StoredEntity>;
+    /**
+     * The entity's own relationships when they come from its authored file
+     * rather than the store (an entity the store does not hold yet).
+     */
+    readonly relationships?: readonly Readonly<Record<string, unknown>>[];
 };
 /**
  * One read of the entity an upsert replaces, shared by every step of the

package/dist/operations/mutation/stored-entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stored-entity.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/stored-entity.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;AAEhF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CAC9C,CAAC;AAGF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,kBAAkB,CAsBpB"}
+{"version":3,"file":"stored-entity.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/stored-entity.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;AAGhF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CACvE,CAAC;AAGF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,kBAAkB,CAsBpB"}

package/dist/operations/mutation/uncompiled-source.d.ts

@@ -0,0 +1,43 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+import type { StoredEntityLookup } from "./stored-entity.js";
+import type { RelationshipInput, UpsertInput } from "./types.js";
+/**
+ * An authored document for an entity the compiled store does not hold: the
+ * file the source-first writer would merge an upsert into.
+ */
+export type UncompiledAuthoredSource = Readonly<{
+    /** Workspace-relative path. */
+    path: string;
+    absolute: string;
+    content: string;
+    /**
+     * The entity as its file states it: the extracted entity when the file
+     * compiles, its front matter when it does not.
+     */
+    stored: Readonly<Record<string, unknown>>;
+    /** Why kibi sync cannot compile the file as authored; null when it can. */
+    extractionError: string | null;
+}>;
+/**
+ * The authored document an upsert of `input` would merge into although the
+ * store does not hold the entity: a file left out of the last sync (one sync
+ * could not extract, or one written since). Null when the writer would
+ * create a new file, writes a symbol manifest, or the file declares another
+ * entity. A file whose front matter does not parse is refused here: the
+ * writer could not merge into it either.
+ */
+export declare function readUncompiledAuthoredSource(context: OperationContext, input: UpsertInput): Promise<UncompiledAuthoredSource | null>;
+/**
+ * The store lookup for an upsert whose entity exists only in its authored
+ * file: the file's own state is what the write changes, so the stored
+ * ledger, origin and firmness checks read it.
+ */
+export declare function authoredEntityLookup(source: UncompiledAuthoredSource): StoredEntityLookup;
+/**
+ * Render the document the writer will leave and extract it as kibi sync
+ * will. A write that leaves the file uncompilable is refused, naming the
+ * file and the error, because the entity would stay invisible to every
+ * store-backed tool. Returns the relationships the written file declares.
+ */
+export declare function assertAuthoredWriteCompiles(source: UncompiledAuthoredSource, input: UpsertInput, entity: Readonly<Record<string, unknown>>): readonly RelationshipInput[];
+//# sourceMappingURL=uncompiled-source.d.ts.map

package/dist/operations/mutation/uncompiled-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uncompiled-source.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/uncompiled-source.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAMjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEjE;;;GAGG;AAEH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,2EAA2E;IAC3E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC,CAAC;AAMH;;;;;;;GAOG;AAEH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CA8C1C;AAED;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,wBAAwB,GAC/B,kBAAkB,CAKpB;AAED;;;;;GAKG;AAEH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,wBAAwB,EAChC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,SAAS,iBAAiB,EAAE,CAa9B"}

package/dist/operations/mutation/uncompiled-source.js

@@ -0,0 +1,115 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import path from "node:path";
+import { sourceExtractionRemediation } from "../../commands/sync/cache.js";
+import { extractFromMarkdownString } from "../../extractors/markdown.js";
+import { authoredFrontmatter, newEntitySourceTarget, renderSourceDocument, } from "./source-authoring.js";
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The authored document an upsert of `input` would merge into although the
+ * store does not hold the entity: a file left out of the last sync (one sync
+ * could not extract, or one written since). Null when the writer would
+ * create a new file, writes a symbol manifest, or the file declares another
+ * entity. A file whose front matter does not parse is refused here: the
+ * writer could not merge into it either.
+ */
+// implements REQ-kibi-uncompiled-source-visibility
+export async function readUncompiledAuthoredSource(context, input) {
+    if (context.fs === undefined || context.sourceFirst === false)
+        return null;
+    if (input.type === "symbol")
+        return null;
+    const absolute = newEntitySourceTarget(context, input);
+    if (absolute === undefined || !/\.mdx?$/i.test(absolute))
+        return null;
+    let content;
+    try {
+        content = await context.fs.readFile(absolute);
+    }
+    catch {
+        return null;
+    }
+    const relative = path
+        .relative(context.workspaceRoot, absolute)
+        .replaceAll(path.sep, "/");
+    try {
+        const { entity } = extractFromMarkdownString(content, absolute);
+        if (entity.id !== input.id)
+            return null;
+        return {
+            path: relative,
+            absolute,
+            content,
+            stored: entity,
+            extractionError: null,
+        };
+    }
+    catch (error) {
+        const extractionError = errorText(error);
+        let frontmatter;
+        try {
+            frontmatter = authoredFrontmatter(content);
+        }
+        catch (parseError) {
+            throw new Error(`Upsert of ${input.id} refused: ${relative} exists but kibi sync cannot compile it (${extractionError}), and its front matter does not parse (${errorText(parseError)}), so the write cannot merge into it. Fix the front matter of ${relative}, run kibi sync, then retry.`);
+        }
+        if (frontmatter.id !== undefined && frontmatter.id !== input.id)
+            return null;
+        if (frontmatter.type !== undefined && frontmatter.type !== input.type)
+            return null;
+        return {
+            path: relative,
+            absolute,
+            content,
+            stored: { ...frontmatter, id: input.id, type: input.type },
+            extractionError,
+        };
+    }
+}
+/**
+ * The store lookup for an upsert whose entity exists only in its authored
+ * file: the file's own state is what the write changes, so the stored
+ * ledger, origin and firmness checks read it.
+ */
+// implements REQ-kibi-uncompiled-source-visibility
+export function authoredEntityLookup(source) {
+    return {
+        exists: async () => true,
+        entity: async () => source.stored,
+    };
+}
+/**
+ * Render the document the writer will leave and extract it as kibi sync
+ * will. A write that leaves the file uncompilable is refused, naming the
+ * file and the error, because the entity would stay invisible to every
+ * store-backed tool. Returns the relationships the written file declares.
+ */
+// implements REQ-kibi-uncompiled-source-visibility
+export function assertAuthoredWriteCompiles(source, input, entity) {
+    let after;
+    try {
+        after = renderSourceDocument(input, entity, source.content, source.path);
+        return extractFromMarkdownString(after, source.absolute).relationships.map((relationship) => ({ ...relationship }));
+    }
+    catch (error) {
+        const message = errorText(error);
+        throw new Error(`Upsert of ${input.id} refused: ${input.id} exists in ${source.path} but is not compiled${source.extractionError === null ? "" : ` (${source.extractionError})`}, and this write would leave the file uncompilable: ${message}. ${sourceExtractionRemediation(source.path, message)}`);
+    }
+}

package/dist/operations/mutation/upsert.d.ts

@@ -3,6 +3,7 @@ import type { OperationResult } from "../../public/operations/types.js";
 import type { SemanticAdvisorReceipt } from "../semantic-advisor/types.js";
 import { type StoredEntityLookup } from "./stored-entity.js";
 import type { RelationshipInput, StagedUpsertState, UpsertInput, UpsertPayload, ValidatedUpsert } from "./types.js";
+import { type UncompiledAuthoredSource } from "./uncompiled-source.js";
 export declare function assertRelationshipShardContained(workspaceRoot: string, shardPath: string): void;
 export declare function validateAppendOnlyProofReceipts(entity: Readonly<Record<string, unknown>>, context: OperationContext, staged?: StagedUpsertState): Promise<void>;
 export declare function effectiveRelationships(input: UpsertInput, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext, staged?: StagedUpsertState, lookup?: StoredEntityLookup): Promise<readonly RelationshipInput[]>;
@@ -32,6 +33,11 @@ export declare function analyzeUpsertSemantics(payload: UpsertInput & {
 }): UpsertSemanticAnalysis;
 export type UpsertValidation = Readonly<{
     readonly validated: ValidatedUpsert;
+    /**
+     * The authored file the write merges into although the store does not
+     * hold the entity; absent for an ordinary create or update.
+     */
+    readonly uncompiledSource?: UncompiledAuthoredSource;
     /** The upsert's relationships merged with the entity's existing ones. */
     readonly relationships: readonly RelationshipInput[];
     readonly semantic: UpsertSemanticAnalysis;

package/dist/operations/mutation/upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAexE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AA6B3E,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AAsEpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAwCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,GAAG;IACrB,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD,GACA,sBAAsB,CASxB;AAGD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;CAC3C,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAkF3B;AAgDD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA2hBzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"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"}