kibi-cli 2.3.0 → 2.5.0

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

@@ -1,6 +1,6 @@
 import type { PrologPort } from "../../public/operations/runtime-types.js";
-import type { RelationshipInput } from "./types.js";
-export declare const RELATIONSHIP_TYPES: readonly ["depends_on", "specified_by", "verified_by", "validates", "implements", "covered_by", "executable_for", "constrained_by", "constrains", "requires_property", "requires_predicate", "requires_rule", "guards", "publishes", "consumes", "supersedes", "restates", "relates_to"];
+import type { RelationshipInput, StagedUpsertState } from "./types.js";
+export declare const RELATIONSHIP_TYPES: readonly ["depends_on", "specified_by", "verified_by", "validates", "implements", "covered_by", "executable_for", "constrained_by", "constrains", "requires_property", "requires_predicate", "requires_rule", "guards", "publishes", "consumes", "supersedes", "restates", "assumes", "exempts", "relates_to"];
 export type RelationshipType = (typeof RELATIONSHIP_TYPES)[number];
 export declare function wrongKindRelationshipError(type: string, target: string, wrongKind: string): Error;
 export declare function dependentRelationshipsGoal(entityId: string): string;
@@ -19,10 +19,10 @@ type SupersedesHistoryDeps = Readonly<{
 }>;
 export declare function firstGitAdditionCommit(workspaceRoot: string, source: string): string | null;
 export declare function classifySupersedesHistory(workspaceRoot: string, sourceCommit: string | null, targetCommit: string | null, deps?: Pick<SupersedesHistoryDeps, "isAncestor">): SupersedesHistory;
-export declare function validateSupersedesSourceHistory(prolog: PrologPort, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], workspaceRoot: string, deps?: SupersedesHistoryDeps): Promise<void>;
+export declare function validateSupersedesSourceHistory(prolog: PrologPort, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], workspaceRoot: string, deps?: SupersedesHistoryDeps, staged?: StagedUpsertState): Promise<void>;
 export declare function formatRelationshipSourceMismatch(entityId: string, relationship: RelationshipInput): string;
-export declare function validateLiveRelationshipTargets(prolog: PrologPort, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[]): Promise<void>;
-export declare function validateStrictLanePairing(prolog: PrologPort, relationships: readonly RelationshipInput[]): Promise<void>;
+export declare function validateLiveRelationshipTargets(prolog: PrologPort, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], staged?: StagedUpsertState): Promise<void>;
+export declare function validateStrictLanePairing(prolog: PrologPort, relationships: readonly RelationshipInput[], staged?: StagedUpsertState): Promise<void>;
 export declare function existingRelationships(prolog: PrologPort, entityId: string): Promise<readonly RelationshipInput[]>;
 export {};
 //# sourceMappingURL=relationships.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/relationships.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,kBAAkB,0RAmBrB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,KAAK,CAKP;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,KAAK,iBAAiB,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAgCF,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAER;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAczE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,IAAI,CAMN;AAED,KAAK,iBAAiB,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AAE1D,KAAK,qBAAqB,GAAG,QAAQ,CAAC;IACpC,mBAAmB,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC9E,UAAU,EAAE,CACV,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,KACf,OAAO,GAAG,IAAI,CAAC;CACrB,CAAC,CAAC;AAMH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAef;AAsBD,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,IAAI,GAAE,IAAI,CACR,qBAAqB,EACrB,YAAY,CACqB,GAClC,iBAAiB,CAenB;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,qBAAuD,GAC5D,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,iBAAiB,GAC9B,MAAM,CAIR;AAuBD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAevC"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/relationships.ts"],"names":[],"mappings":"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"}

package/dist/operations/mutation/relationships.js

@@ -19,6 +19,8 @@ export const RELATIONSHIP_TYPES = [
     "consumes",
     "supersedes",
     "restates",
+    "assumes",
+    "exempts",
     "relates_to",
 ];
 export function wrongKindRelationshipError(type, target, wrongKind) {
@@ -111,7 +113,7 @@ export function classifySupersedesHistory(workspaceRoot, sourceCommit, targetCom
     return sourceBeforeTarget === true ? "reversed" : "unknown";
 }
 // implements REQ-011
-export async function validateSupersedesSourceHistory(prolog, entity, relationships, workspaceRoot, deps = DEFAULT_SUPERSEDES_HISTORY_DEPS) {
+export async function validateSupersedesSourceHistory(prolog, entity, relationships, workspaceRoot, deps = DEFAULT_SUPERSEDES_HISTORY_DEPS, staged) {
     const sourceId = typeof entity.id === "string" ? entity.id : "";
     const source = typeof entity.source === "string" ? entity.source : "";
     const sourceCommit = deps.firstAdditionCommit(workspaceRoot, source);
@@ -120,7 +122,11 @@ export async function validateSupersedesSourceHistory(prolog, entity, relationsh
             continue;
         const targetId = stringField(relationship, "to");
         let targetSource = "";
-        if (prolog.queryEntities) {
+        const planned = staged?.entities.get(targetId);
+        if (planned !== undefined) {
+            targetSource = typeof planned.source === "string" ? planned.source : "";
+        }
+        else if (prolog.queryEntities) {
             const targetPage = await prolog.queryEntities({
                 id: targetId,
                 limit: 1,
@@ -146,9 +152,12 @@ export function formatRelationshipSourceMismatch(entityId, relationship) {
     const to = stringField(relationship, "to");
     return `Relationship source must match the upserted entity ${entityId}; received from=${from}. To add ${from} -> ${to}, upsert ${from} instead and include the relationship in that call.`;
 }
-async function endpointType(prolog, entity, endpointId) {
+async function endpointType(prolog, entity, endpointId, staged) {
     if (endpointId === entity.id && typeof entity.type === "string")
         return entity.type;
+    const planned = staged?.entities.get(endpointId);
+    if (planned !== undefined && typeof planned.type === "string")
+        return planned.type;
     let result;
     try {
         result = await prolog.query(`kb_entity('${escapeAtom(endpointId)}', Type, _)`);
@@ -163,10 +172,10 @@ async function endpointType(prolog, entity, endpointId) {
     const type = result.bindings.Type;
     return type ? type.replace(/^['"]|['"]$/g, "") : null;
 }
-export async function validateLiveRelationshipTargets(prolog, entity, relationships) {
+export async function validateLiveRelationshipTargets(prolog, entity, relationships, staged) {
     for (const relationship of relationships) {
-        const fromType = await endpointType(prolog, entity, stringField(relationship, "from"));
-        const toType = await endpointType(prolog, entity, stringField(relationship, "to"));
+        const fromType = await endpointType(prolog, entity, stringField(relationship, "from"), staged);
+        const toType = await endpointType(prolog, entity, stringField(relationship, "to"), staged);
         if (fromType === null || toType === null)
             continue;
         const tuple = {
@@ -179,12 +188,21 @@ export async function validateLiveRelationshipTargets(prolog, entity, relationsh
             throw new Error(formatInvalidRelationshipTuple(tuple));
     }
 }
-export async function validateStrictLanePairing(prolog, relationships) {
+function plannedFactKind(planned) {
+    return planned.type === "fact" && typeof planned.fact_kind === "string"
+        ? planned.fact_kind
+        : undefined;
+}
+export async function validateStrictLanePairing(prolog, relationships, staged) {
     for (const relationship of relationships) {
         const target = stringField(relationship, "to");
+        // A target an earlier plan step writes is judged by that write.
+        const planned = staged?.entities.get(target);
         if (relationship.type === "requires_rule") {
-            const result = await prolog.query(`once((kb_entity('${escapeAtom(target)}', fact, _RuleProps), memberchk(fact_kind=_RuleKind, _RuleProps), normalize_term_atom(_RuleKind, rule)))`);
-            if (!result.success) {
+            const isRule = planned !== undefined
+                ? plannedFactKind(planned) === "rule"
+                : (await prolog.query(`once((kb_entity('${escapeAtom(target)}', fact, _RuleProps), memberchk(fact_kind=_RuleKind, _RuleProps), normalize_term_atom(_RuleKind, rule)))`)).success;
+            if (!isRule) {
                 throw new Error(`Relationship 'requires_rule' requires target '${target}' to be a fact_kind=rule fact.`);
             }
             continue;
@@ -196,8 +214,10 @@ export async function validateStrictLanePairing(prolog, relationships) {
                 : null;
         if (wrongKind === null)
             continue;
-        const result = await prolog.query(`once((kb_entity('${escapeAtom(target)}', fact, _SlpProps), memberchk(fact_kind=_SlpFK, _SlpProps), normalize_term_atom(_SlpFK, ${wrongKind})))`);
-        if (result.success)
+        const isWrongKind = planned !== undefined
+            ? plannedFactKind(planned) === wrongKind
+            : (await prolog.query(`once((kb_entity('${escapeAtom(target)}', fact, _SlpProps), memberchk(fact_kind=_SlpFK, _SlpProps), normalize_term_atom(_SlpFK, ${wrongKind})))`)).success;
+        if (isWrongKind)
             throw wrongKindRelationshipError(String(relationship.type), target, wrongKind);
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/serialization.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAsDpD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAMR;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAOxE;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtD"}
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/serialization.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAwDpD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAMR;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAOxE;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtD"}

package/dist/operations/mutation/serialization.js

@@ -12,6 +12,7 @@ const ATOM_FIELDS = [
     "operator",
     "value_type",
     "polarity",
+    "expects",
 ];
 const STRING_FIELDS = [
     "id",
@@ -32,7 +33,8 @@ function serializeValue(key, value) {
         key === "semantic_inventory" ||
         key === "proof_contract" ||
         key === "proof_bindings" ||
-        key === "proof_receipts") {
+        key === "proof_receipts" ||
+        key === "origin") {
         return toPrologString(JSON.stringify(value));
     }
     if (Array.isArray(value))

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

@@ -62,6 +62,12 @@ export declare function renderYamlRelationshipDeletion(sourcePathValue: string,
     body: string;
     removed: boolean;
 };
+/**
+ * The bytes an upsert of `entity` publishes at `relativePath`, merged into the
+ * document's current content. Compile plans render their documents with it
+ * so a plan writes exactly what `kb_upsert` would.
+ */
+export declare function renderSourceDocument(input: UpsertInput, entity: Readonly<Record<string, unknown>>, existingContent: string | undefined, relativePath: string): string;
 export declare function writeSourceForUpsert(input: UpsertInput, entity: Readonly<Record<string, unknown>>, existing?: Readonly<Record<string, unknown>>, context?: OperationContext, sourceDocumentOverride?: string): Promise<{
     receipt: SourceWriteReceipt;
     rollback: () => Promise<void>;

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

@@ -601,7 +601,13 @@ export function renderYamlRelationshipDeletion(sourcePathValue, existingContent,
         ? { body: doc.toString(AUTHORED_YAML_OPTIONS), removed: true }
         : { body: existingContent, removed: false };
 }
-function renderSourceDocument(input, entity, existingContent, relativePath) {
+/**
+ * The bytes an upsert of `entity` publishes at `relativePath`, merged into the
+ * document's current content. Compile plans render their documents with it
+ * so a plan writes exactly what `kb_upsert` would.
+ */
+// implements REQ-kibi-change-to-proof-plan-compiler-v2
+export function renderSourceDocument(input, entity, existingContent, relativePath) {
     const extension = path.extname(relativePath).toLowerCase();
     if (extension === ".yaml" || extension === ".yml") {
         if (input.type !== "symbol") {

package/dist/operations/mutation/symbol-refresh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-refresh.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-refresh.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAgBjF,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,WAAW,GACX,SAAS,GACT,WAAW,CAAC;AAGhB,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,0BAA0B,CAAC;CACnD,CAAC;AAGF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,IAAI,IAAI,CAAC;CAClB,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,aAAa,CAAC,CAAC;AAsD5B,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,IAAI,CAMN;AA6OD,4EAA4E;AAC5E,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,yEAAyE;AAEzE,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAGxB;AAED;;;GAGG;AAEH,wBAAsB,mCAAmC,CACvD,QAAQ,EAAE,MAAM,EAChB,oBAAoB,EAAE,MAAM,EAC5B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAOxB;AAGD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,IAAI,CAEN"}
+{"version":3,"file":"symbol-refresh.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-refresh.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAgBjF,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,WAAW,GACX,SAAS,GACT,WAAW,CAAC;AAGhB,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,0BAA0B,CAAC;CACnD,CAAC;AAGF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,IAAI,IAAI,CAAC;CAClB,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,aAAa,CAAC,CAAC;AAsD5B,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,IAAI,CAMN;AAiPD,4EAA4E;AAC5E,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,yEAAyE;AAEzE,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAGxB;AAED;;;GAGG;AAEH,wBAAsB,mCAAmC,CACvD,QAAQ,EAAE,MAAM,EAChB,oBAAoB,EAAE,MAAM,EAC5B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAOxB;AAGD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,IAAI,CAEN"}

package/dist/operations/mutation/symbol-refresh.js

@@ -165,7 +165,10 @@ async function refreshUnlocked(symbolId, context, options = {}) {
     }
     const sourceFile = typeof entry.sourceFile === "string" ? entry.sourceFile : "";
     const title = typeof entry.title === "string" ? entry.title : "";
-    const [enriched] = await enrichSymbolCoordinates([{ ...entry, id: symbolId, title, sourceFile }], context.workspaceRoot);
+    // Targeted refresh publishes coordinates only, like
+    // `kibi sync --refresh-symbol-coordinates`, so decorated Python may bind
+    // explicit declarations while the analysis itself stays partial.
+    const [enriched] = await enrichSymbolCoordinates([{ ...entry, id: symbolId, title, sourceFile }], context.workspaceRoot, { allowPythonDecoratorCoordinates: true });
     let next = coordinate(enriched);
     let sourceText = next === null ? sourceTextFor(sourceFile, context.workspaceRoot) : null;
     if (next === null &&

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

@@ -12,9 +12,23 @@ export type UpsertInput = {
         /** Complete document bytes. Omit to preserve the existing body bytes. */
         readonly body?: string;
     };
+    /** Validate and preview the write without mutating the KB. */
+    readonly dryRun?: boolean;
     readonly _skipContradictionCheck?: boolean;
     readonly _requestId?: string;
 };
+/**
+ * Store state an upsert's validation must see in addition to the live KB:
+ * what earlier steps of the same plan will have written by the time this
+ * upsert runs. Validators treat these entities and relationships as present,
+ * and a staged entity shadows the stored entity with the same id.
+ */
+export type StagedUpsertState = {
+    /** Validated entities (id, type and properties) by id. */
+    readonly entities: ReadonlyMap<string, Readonly<Record<string, unknown>>>;
+    /** Relationships the earlier steps add, in step order. */
+    readonly relationships: readonly RelationshipInput[];
+};
 export type ValidatedUpsert = {
     readonly entity: Record<string, unknown>;
     readonly relationships: readonly RelationshipInput[];

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

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

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

@@ -1,8 +1,35 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
 import type { OperationResult } from "../../public/operations/types.js";
-import type { RelationshipInput, UpsertInput, UpsertPayload } from "./types.js";
-export declare function validateAppendOnlyProofReceipts(entity: Readonly<Record<string, unknown>>, context: OperationContext): Promise<void>;
-export declare function effectiveRelationships(input: UpsertInput, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext): Promise<readonly RelationshipInput[]>;
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import type { RelationshipInput, StagedUpsertState, UpsertInput, UpsertPayload, ValidatedUpsert } from "./types.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): Promise<readonly RelationshipInput[]>;
+export type UpsertValidationOptions = Readonly<{
+    /** Skip the append-only receipt check (kibi proof prune only). */
+    readonly allowReceiptsPrune?: boolean;
+    /**
+     * What earlier steps of the same plan will have written when this upsert
+     * runs. Entities and relationships they create count as present.
+     */
+    readonly staged?: StagedUpsertState;
+}>;
+export type UpsertValidation = Readonly<{
+    readonly validated: ValidatedUpsert;
+    /** The upsert's relationships merged with the entity's existing ones. */
+    readonly relationships: readonly RelationshipInput[];
+    readonly semantic: ReturnType<typeof analyzeSemanticAdvisorInput>;
+}>;
+/**
+ * The complete validation an upsert passes before its first write: schema,
+ * append-only proof receipts, relationship sources, symbol granularity,
+ * strict-lane pairing, live relationship targets, supersedes direction,
+ * proposition-complete ingestion, logical grounding claim keys and predicate
+ * argument vocabulary. executeUpsert runs it for every write, and
+ * kb_apply_plan runs it for every plan step before the plan's first write,
+ * passing the earlier steps' writes as `staged`.
+ */
+export declare function validateUpsertForCommit(input: UpsertInput, context: OperationContext, options?: UpsertValidationOptions): Promise<UpsertValidation>;
 export type UpsertExecutionOptions = Readonly<{
     /**
      * Internal escape hatch for proof-receipt ingest: when provided, the

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":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAqCxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAoGhF,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAaf;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,GACxB,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAuBvC;AAmCD,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;AAEH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAshBzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AAiCnF,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AA6CpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAmCD,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,GACzB,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,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,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;CACnE,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAkE3B;AAGD,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,CAggBzC"}

package/dist/operations/mutation/upsert.js

@@ -14,6 +14,8 @@ import { entityIdStyleWarnings } from "../../utils/entity-id-style.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
 import { buildUpsertCommitGoal, formatUpsertError } from "./contradictions.js";
+import { resolveUpsertOrigin } from "./origin.js";
+import { planRecoveryNotes, settlePendingPlanApplyJournals, withPlanRecoveryNotes, } from "./plan-apply-journal.js";
 import { assertPredicateArgumentVocabulary } from "./predicate-vocabulary-guard.js";
 import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, validateSupersedesSourceHistory, } from "./relationships.js";
 import { MutationRollbackFailureError, MutationSaga } from "./saga.js";
@@ -51,7 +53,8 @@ function fileHash(pathname) {
 function textHash(value) {
     return createHash("sha256").update(value).digest("hex");
 }
-function assertRelationshipShardContained(workspaceRoot, shardPath) {
+// implements REQ-core-atomic-upsert-persistence
+export function assertRelationshipShardContained(workspaceRoot, shardPath) {
     const root = path.resolve(workspaceRoot);
     const relationshipRoot = path.resolve(root, ".kb", "relationships");
     const absolute = path.resolve(shardPath);
@@ -92,13 +95,20 @@ function restoreRelationshipShard(shardPath, before, expectedAfterHash) {
     }
     writeFileSync(shardPath, before, "utf8");
 }
-export async function validateAppendOnlyProofReceipts(entity, context) {
+export async function validateAppendOnlyProofReceipts(entity, context, staged) {
     if (entity.type !== "test")
         return;
-    const existing = await loadEntities(requireProlog(context), {
-        id: String(entity.id),
-        type: "test",
-    });
+    // An earlier plan step that writes the same test is the history this
+    // write must extend.
+    const planned = staged?.entities.get(String(entity.id));
+    const existing = planned !== undefined
+        ? planned.type === "test"
+            ? [planned]
+            : []
+        : await loadEntities(requireProlog(context), {
+            id: String(entity.id),
+            type: "test",
+        });
     const previous = receiptRecords(existing[0]?.proof_receipts);
     if (!previous || previous.length === 0)
         return;
@@ -108,19 +118,24 @@ export async function validateAppendOnlyProofReceipts(entity, context) {
         throw new Error(`Entity validation failed: ${errors.join("; ")}`);
     }
 }
-export async function effectiveRelationships(input, entity, relationships, context) {
+export async function effectiveRelationships(input, entity, relationships, context, staged) {
     const prolog = requireProlog(context);
+    // Relationships an earlier plan step adds from this entity will exist when
+    // this upsert runs.
+    const plannedOwn = (staged?.relationships ?? []).filter((relationship) => relationship.from === input.id);
     const exists = await prolog.query(`once(kb_entity('${escapeAtom(input.id)}', _, _))`);
-    if (!exists.success)
+    if (!exists.success && plannedOwn.length === 0)
         return relationships;
     try {
-        const current = (await existingRelationships(prolog, String(entity.id)))
-            // An upsert owns only relationships whose source is the upserted entity.
-            // Incoming relationships must not be copied into its validation or
-            // canonical source projection.
-            .filter((relationship) => relationship.from === input.id);
+        const current = exists.success
+            ? (await existingRelationships(prolog, String(entity.id)))
+                // An upsert owns only relationships whose source is the upserted
+                // entity. Incoming relationships must not be copied into its
+                // validation or canonical source projection.
+                .filter((relationship) => relationship.from === input.id)
+            : [];
         const merged = new Map();
-        for (const relationship of [...current, ...relationships]) {
+        for (const relationship of [...current, ...plannedOwn, ...relationships]) {
             const key = `${String(relationship.type)}\u0000${String(relationship.from)}\u0000${String(relationship.to)}`;
             // The explicit input wins so any supplied metadata is retained.
             merged.set(key, relationship);
@@ -161,7 +176,68 @@ function reextractCanonicalSymbolEntity(symbolId, authoredRelativePath, workspac
             : { sourceFile: result.sourceFile }),
     };
 }
+// implements REQ-kibi-truthful-consistency
+/**
+ * The complete validation an upsert passes before its first write: schema,
+ * append-only proof receipts, relationship sources, symbol granularity,
+ * strict-lane pairing, live relationship targets, supersedes direction,
+ * proposition-complete ingestion, logical grounding claim keys and predicate
+ * argument vocabulary. executeUpsert runs it for every write, and
+ * kb_apply_plan runs it for every plan step before the plan's first write,
+ * passing the earlier steps' writes as `staged`.
+ */
+export async function validateUpsertForCommit(input, context, options = {}) {
+    const prolog = requireProlog(context);
+    const staged = options.staged;
+    const validated = validateUpsertInput(input, context.clock());
+    if (options.allowReceiptsPrune !== true) {
+        await validateAppendOnlyProofReceipts(validated.entity, context, staged);
+    }
+    validateRelationshipSources(input.id, validated.relationships);
+    await validateSymbolGranularity(validated.entity, validated.relationships, context);
+    const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context, staged);
+    await validateStrictLanePairing(prolog, validated.relationships, staged);
+    await validateLiveRelationshipTargets(prolog, validated.entity, validated.relationships, staged);
+    await validateSupersedesSourceHistory(prolog, validated.entity, validated.relationships, context.workspaceRoot, undefined, staged);
+    const semantic = analyzeSemanticAdvisorInput({
+        payload: { ...input, relationships },
+    });
+    assertSemanticInventoryBoundary({ ...input, relationships }, relationships, semantic.receipt);
+    await assertLogicalGroundingClaimKeys(prolog, { ...input, relationships }, relationships, staged);
+    await assertPredicateArgumentVocabulary(prolog, validated.entity, staged);
+    // The origin the write records is added last: none of the checks above
+    // reads it, and a rejected payload never pays for the stored-origin read.
+    const recorded = await resolveUpsertOrigin(input, prolog, context.clock(), staged);
+    return {
+        validated: recorded === input
+            ? validated
+            : validateUpsertInput(recorded, context.clock()),
+        relationships,
+        semantic,
+    };
+}
+// implements REQ-kibi-operation-interface-parity
+/**
+ * A dry run is the former kb_validate_upsert preflight on the kb_upsert
+ * surface: the same validation and semantic advisor receipt, no KB or
+ * workspace write, and both write effects reported as skipped.
+ */
+async function dryRunUpsert(input, context) {
+    const { dryRun: _dryRun, ...payload } = input;
+    const { executeValidateUpsert } = await import("./validate-upsert.js");
+    const result = await executeValidateUpsert(payload, context);
+    return {
+        content: result.content,
+        structuredContent: {
+            ...result.structuredContent,
+            dryRun: true,
+            skippedEffects: ["kb-write", "workspace-write"],
+        },
+    };
+}
 export async function executeUpsert(input, context, options = {}) {
+    if (input.dryRun === true)
+        return dryRunUpsert(input, context);
     const branchAttachment = context.branchAttachment ?? resolveBranchAttachment(context.workspaceRoot);
     if ("error" in branchAttachment) {
         throw new Error(`Unable to resolve KB branch: ${branchAttachment.error}`);
@@ -186,6 +262,7 @@ export async function executeUpsert(input, context, options = {}) {
     let operationFailure;
     const relationshipShardBefore = new Map();
     const relationshipShardAfterHash = new Map();
+    let planRecoveryWarnings = [];
     const holdsSymbolCompilerLock = input.type === "symbol" &&
         context.fs !== undefined &&
         context.sourceFirst !== false;
@@ -195,6 +272,10 @@ export async function executeUpsert(input, context, options = {}) {
     try {
         if (holdsSourceMutationLock) {
             sourceMutationLock = await acquireWorkspaceMutationLock(context.workspaceRoot);
+            // implements REQ-core-atomic-upsert-persistence
+            // An interrupted kb_apply_plan left a journal: complete or roll it back
+            // before this write reads or changes the files the journal guards.
+            planRecoveryWarnings = planRecoveryNotes(await settlePendingPlanApplyJournals({ ...context, branchAttachment }, { prolog: async () => prolog }));
         }
         if (holdsSymbolCompilerLock) {
             // Symbol source publication, coordinate refresh, canonical
@@ -203,24 +284,11 @@ export async function executeUpsert(input, context, options = {}) {
             // upserts cannot lose updates.
             compilerLock = await acquireSymbolCompilerLock(context.workspaceRoot);
         }
-        const validated = validateUpsertInput(input, context.clock());
-        if (options.allowReceiptsPrune !== true) {
-            await validateAppendOnlyProofReceipts(validated.entity, context);
-        }
-        validateRelationshipSources(input.id, validated.relationships);
-        await validateSymbolGranularity(validated.entity, validated.relationships, context);
-        const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context);
-        relationshipCount = validated.relationships.length;
-        await validateStrictLanePairing(prolog, validated.relationships);
-        await validateLiveRelationshipTargets(prolog, validated.entity, validated.relationships);
-        await validateSupersedesSourceHistory(prolog, validated.entity, validated.relationships, context.workspaceRoot);
-        const semantic = analyzeSemanticAdvisorInput({
-            payload: { ...input, relationships },
+        const { validated, relationships, semantic } = await validateUpsertForCommit(input, context, {
+            allowReceiptsPrune: options.allowReceiptsPrune === true,
         });
+        relationshipCount = validated.relationships.length;
         semanticAdvisor = semantic.receipt;
-        assertSemanticInventoryBoundary({ ...input, relationships }, relationships, semantic.receipt);
-        await assertLogicalGroundingClaimKeys(prolog, { ...input, relationships }, relationships);
-        await assertPredicateArgumentVocabulary(prolog, validated.entity);
         if (context.fs !== undefined && context.sourceFirst !== false) {
             const existingRows = await loadEntities(prolog, {
                 id: input.id,
@@ -374,7 +442,7 @@ export async function executeUpsert(input, context, options = {}) {
                     created: 0,
                     updated: 0,
                     relationships_created: validated.relationships.length,
-                    warnings: semantic.warnings,
+                    warnings: [...planRecoveryWarnings, ...semantic.warnings],
                     semanticAdvisor: semantic.receipt,
                     deferredCommit,
                     ...(sourceWrite ? { sourceWrites: [sourceWrite.receipt] } : {}),
@@ -444,6 +512,7 @@ export async function executeUpsert(input, context, options = {}) {
             updated: changeKind === "updated" ? 1 : 0,
             relationships_created: validated.relationships.length,
             warnings: [
+                ...planRecoveryWarnings,
                 ...semantic.warnings,
                 ...coverage,
                 ...idStyleWarnings,
@@ -519,7 +588,7 @@ export async function executeUpsert(input, context, options = {}) {
                     created: changeKind === "created" ? 1 : 0,
                     updated: changeKind === "updated" ? 1 : 0,
                     relationships_created: relationshipCount,
-                    warnings: [detail],
+                    warnings: [...planRecoveryWarnings, detail],
                     semanticAdvisor: semanticAdvisor,
                     status: "committed_with_repairs",
                     effectFailures: [
@@ -560,11 +629,12 @@ export async function executeUpsert(input, context, options = {}) {
             throw failure;
         }
         if (error instanceof OperationError) {
-            operationFailure = { error };
-            throw error;
+            const failure = withPlanRecoveryNotes(error, planRecoveryWarnings);
+            operationFailure = { error: failure };
+            throw failure;
         }
         const message = error instanceof Error ? error.message : String(error);
-        const failure = new Error(`Upsert execution failed: ${message}`);
+        const failure = withPlanRecoveryNotes(new Error(`Upsert execution failed: ${message}`), planRecoveryWarnings);
         operationFailure = { error: failure };
         throw failure;
     }

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

@@ -1,5 +1,11 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
 import type { OperationResult } from "../../public/operations/types.js";
 import type { UpsertInput, ValidateUpsertPayload } from "./types.js";
+/**
+ * kb_upsert dryRun:true (and the former kb_validate_upsert preflight). With a
+ * store it runs validateUpsertForCommit, the exact validation a real
+ * kb_upsert runs before its first write, so a dry run accepts only what the
+ * write would accept; without a store it runs the store-independent checks.
+ */
 export declare function executeValidateUpsert(input: UpsertInput, context: OperationContext): Promise<OperationResult<ValidateUpsertPayload>>;
 //# sourceMappingURL=validate-upsert.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAcxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAerE,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAoGjD"}
+{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAMxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA+CrE;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAwDjD"}