kibi-cli 0.19.0 → 2.0.0

package/src/public/operations/specs/planning.ts

@@ -0,0 +1,241 @@
+import {
+  type ApplyPlanArgs,
+  type ApplyPlanResult,
+  executeApplyPlan,
+} from "../../../operations/planning/apply-plan.js";
+import {
+  type CompileIntentArgs,
+  type CompilePlanV1,
+  executeCompileIntent,
+} from "../../../operations/planning/compile-intent.js";
+import type { OperationSpec } from "../types.js";
+
+export type {
+  CompileIntentArgs,
+  CompilePlanV1,
+  ContradictionWitness,
+  ProposalDecision,
+  ScenarioDraft,
+  TestDraft,
+  TraceabilityProposal,
+} from "../../../operations/planning/compile-intent.js";
+export type {
+  ApplyPlanArgs,
+  ApplyPlanResult,
+} from "../../../operations/planning/apply-plan.js";
+export type { MigrationPlan } from "../migration-plan.js";
+export { executeApplyPlan } from "../../../operations/planning/apply-plan.js";
+export { executeCompileIntent } from "../../../operations/planning/compile-intent.js";
+
+// implements REQ-kibi-change-to-proof-plan-compiler
+export const compileIntentSpec = {
+  name: "kb_compile_intent",
+  cliName: "compile-intent",
+  description:
+    "Compile complete change intent into a deterministic, snapshot-bound read-only plan. Reuses intent-aware discovery and semantic modeling, accounts for every proposition, reports contradiction witnesses, proposes traceability links, and emits dependency-ordered kb_upsert-style steps only for resolved typed claims. No mutation side effects.",
+  businessInputSchema: {
+    type: "object",
+    required: ["intent", "mode"],
+    properties: {
+      intent: {
+        type: "string",
+        minLength: 1,
+        maxLength: 10000,
+        description:
+          "Complete post-change normative intent. Send the desired behavior, not a patch fragment.",
+      },
+      mode: {
+        type: "string",
+        enum: ["create", "update"],
+        description:
+          "Create a new requirement or update an existing one. Update auto-selection is allowed only with a high-confidence, well-separated candidate.",
+      },
+      requirementId: {
+        type: "string",
+        description:
+          "Optional exact requirement ID. Required for an update when automatic selection is below the confidence and margin gates.",
+      },
+      title: {
+        type: "string",
+        description:
+          "Optional requirement title; existing title is preserved for updates when omitted.",
+      },
+      clauses: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        maxItems: 64,
+        description:
+          "Optional complete atomic clause decomposition. Each assertive clause receives independent proposition accounting.",
+      },
+      semanticFacets: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          actors: { type: "array", items: { type: "string" }, maxItems: 20 },
+          actions: { type: "array", items: { type: "string" }, maxItems: 20 },
+          objects: { type: "array", items: { type: "string" }, maxItems: 20 },
+          constraints: {
+            type: "array",
+            items: { type: "string" },
+            maxItems: 20,
+          },
+          aliases: { type: "array", items: { type: "string" }, maxItems: 20 },
+        },
+        description:
+          "Host-agent facets forwarded to deterministic intent-v1 discovery.",
+      },
+      sourceLocations: {
+        type: "array",
+        maxItems: 20,
+        items: {
+          type: "object",
+          required: ["path"],
+          additionalProperties: false,
+          properties: {
+            path: { type: "string", minLength: 1 },
+            line: { type: "integer", minimum: 1 },
+            column: { type: "integer", minimum: 1 },
+            symbol: { type: "string", minLength: 1 },
+          },
+        },
+        description:
+          "Workspace-relative source coordinates used for discovery and before-hash binding.",
+      },
+      interpretations: {
+        type: "array",
+        maxItems: 3,
+        items: {
+          type: "object",
+          required: ["claim_key", "claim_text", "ir"],
+          properties: {
+            claim_key: { type: "string" },
+            claim_text: { type: "string" },
+            confidence: { type: "number", minimum: 0, maximum: 1 },
+            span: { type: "object" },
+            ir: { type: "object" },
+          },
+        },
+        description:
+          "Optional host-supplied typed kibi.logic.v1 interpretations; Kibi validates them before including rule steps.",
+      },
+      scenarioDrafts: {
+        type: "array",
+        maxItems: 20,
+        items: {
+          type: "object",
+          required: ["title", "body"],
+          properties: {
+            id: { type: "string" },
+            title: { type: "string", minLength: 1 },
+            body: { type: "string", minLength: 1 },
+          },
+        },
+        description:
+          "Optional scenario drafts. Each is linked requirement -> scenario with specified_by.",
+      },
+      testDrafts: {
+        type: "array",
+        maxItems: 20,
+        items: {
+          type: "object",
+          required: ["title", "body"],
+          properties: {
+            id: { type: "string" },
+            title: { type: "string", minLength: 1 },
+            body: { type: "string", minLength: 1 },
+            scenarioIds: {
+              type: "array",
+              items: { type: "string", minLength: 1 },
+              maxItems: 20,
+              description:
+                "Stable scenario draft IDs verified by this test. Required when multiple scenario drafts are supplied.",
+            },
+            verificationScope: {
+              type: "string",
+              enum: ["unit", "integration", "end_to_end"],
+            },
+            verificationPerspective: {
+              type: "string",
+              enum: ["internal", "consumer"],
+            },
+          },
+        },
+        description:
+          "Optional test drafts. Tests are attached to scenarios with verified_by; direct req -> test proof links are not emitted.",
+      },
+      proposalDecisions: {
+        type: "array",
+        maxItems: 20,
+        items: {
+          type: "object",
+          required: ["proposalId", "decision"],
+          properties: {
+            proposalId: { type: "string", minLength: 1 },
+            decision: { type: "string", enum: ["accept", "reject"] },
+          },
+        },
+        description:
+          "Explicit decisions for deterministic traceability proposals. Pending proposals never enter steps.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read", "workspace-read"],
+  execute: executeCompileIntent,
+} as const satisfies OperationSpec<CompileIntentArgs, CompilePlanV1>;
+
+// implements REQ-kibi-change-to-proof-plan-compiler
+export const applyPlanSpec = {
+  name: "kb_apply_plan",
+  cliName: "apply-plan",
+  description:
+    "Apply an explicitly approved kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or entity-deletion plan after revalidating its canonical hash and live snapshots. Bootstrap actions are dependency-ordered, sequential, source-first, and recoverable from a typed journal.",
+  businessInputSchema: {
+    type: "object",
+    oneOf: [
+      {
+        required: ["plan", "approvedPlanHash"],
+        not: { required: ["recoveryJournalId"] },
+      },
+      {
+        required: ["recoveryJournalId"],
+        not: {
+          anyOf: [{ required: ["plan"] }, { required: ["approvedPlanHash"] }],
+        },
+      },
+    ],
+    properties: {
+      approvedPlanHash: {
+        type: "string",
+        pattern: "^[a-fA-F0-9]{64}$",
+        description:
+          "Exact SHA-256 planHash returned by kb_plan_bootstrap, kb_compile_intent, or another approved plan after human review.",
+      },
+      plan: {
+        type: "object",
+        required: ["version", "planHash"],
+        description:
+          "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked/non-automatic actions.",
+      },
+      approvedActionIds: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        description:
+          "Required for migration-plan.v2. Exact automatic action IDs explicitly approved for this application.",
+      },
+      recoveryJournalId: {
+        type: "string",
+        pattern: "^[A-Za-z0-9._-]+$",
+        description:
+          "Typed recovery journal identifier returned by a committed_with_repairs result. Recovery replays only the immutable journal and never the original plan request.",
+      },
+    },
+  },
+  // Applying an entity-deletion plan must also retract the compiled entity;
+  // acquire the branch engine up front so the source commit and compiled
+  // retraction run under one capability-scoped operation context. Recovery
+  // journals remain usable even when the engine is unavailable.
+  requiresProlog: true,
+  effects: ["kb-read", "kb-write", "workspace-read", "workspace-write"],
+  execute: executeApplyPlan,
+} as const satisfies OperationSpec<ApplyPlanArgs, ApplyPlanResult>;

package/src/public/operations/specs/proof.ts

@@ -0,0 +1,43 @@
+import {
+  type IngestProofArgs,
+  type IngestProofResult,
+  executeIngestProof,
+} from "../../../operations/proof/ingest-proof.js";
+import { PROOF_RUN_ARTIFACT_SCHEMA } from "../../proof-protocol.js";
+import type { OperationSpec } from "../types.js";
+
+export type {
+  IngestProofArgs,
+  IngestProofResult,
+} from "../../../operations/proof/ingest-proof.js";
+export { executeIngestProof } from "../../../operations/proof/ingest-proof.js";
+
+// implements REQ-kibi-proof-evidence-protocol
+export const ingestProofSpec = {
+  name: "kb_ingest_proof",
+  cliName: "ingest-proof",
+  description:
+    "Ingest a producer-emitted kibi.proof-run.v1 artifact and evaluate it against each selected test's kibi.proof-contract.v1 proof obligations. Revalidates the live workspace snapshot, integration command binding, run-level outcome, attempt history, success policy, and append-only proof-receipt history before deriving and appending idempotent kibi.proof-receipt.v1 receipts. Producers report what happened; Kibi evaluates proof. Prefer `kibi prove` so the configured producer runs automatically; direct ingestion is an integration path for custom producers and agents.",
+  businessInputSchema: {
+    type: "object",
+    required: ["snapshot", "artifact"],
+    properties: {
+      snapshot: {
+        type: "string",
+        pattern: "^[a-f0-9]{64}$",
+        description: "Workspace snapshot captured immediately before the run.",
+      },
+      artifact: PROOF_RUN_ARTIFACT_SCHEMA,
+      testIds: {
+        type: "array",
+        minItems: 1,
+        items: { type: "string", minLength: 1 },
+        description:
+          "Existing test entities with proof_contract.v1. Omit to evaluate every test contracted to the artifact's integration.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read", "kb-write", "workspace-read"],
+  execute: executeIngestProof,
+} as const satisfies OperationSpec<IngestProofArgs, IngestProofResult>;

package/src/public/operations/specs/reporting.ts

@@ -1,8 +1,18 @@
-import { VERIFICATION_RECEIPT_MAX_AGE_SECONDS } from "../../verification-receipt.js";
+import { join } from "node:path";
+
+import { resolveBoundSymbolScope } from "../../../extractors/manifest.js";
+import { PROOF_RECEIPT_MAX_AGE_SECONDS } from "../../proof-receipt.js";
+import { executeStatus } from "../discovery-executors.js";
 import {
   type LegacyMigrationPlan,
   buildLegacyMigrationPlanFromContext,
 } from "../legacy-migration-plan.js";
+import {
+  type MigrationPlan,
+  buildActionsFromCoverage,
+  buildMigrationPlan,
+  mergeMigrationPlans,
+} from "../migration-plan.js";
 import {
   runOperationJsonQuery,
   toPrologAtom,
@@ -10,6 +20,10 @@ import {
 } from "../prolog-json.js";
 import { type RepairPlan, buildRepairPlan } from "../repair-plan.js";
 import type { OperationContext } from "../runtime-types.js";
+import {
+  addCoordinateRepairEvidence,
+  buildSymbolRepairPlan,
+} from "../symbol-repair-plan.js";
 import type { OperationResult, OperationSpec } from "../types.js";
 import { readWorkspaceSnapshot } from "../workspace-snapshot.js";
 
@@ -45,6 +59,8 @@ export type CoverageInput = {
   readonly by?: "req" | "symbol" | "type";
   readonly tags?: readonly string[];
   readonly includePassing?: boolean;
+  /** Requirement proof-status filter (req mode). Implies include-passing. */
+  readonly statuses?: readonly string[];
   readonly includeTransitive?: boolean;
   readonly limit?: number;
   readonly offset?: number;
@@ -60,6 +76,8 @@ export type CoveragePayload = {
   readonly rows: readonly Readonly<Record<string, unknown>>[];
   readonly repairPlan?: RepairPlan;
   readonly legacyMigrationPlan?: LegacyMigrationPlan;
+  readonly symbolRepairPlan?: Readonly<Record<string, unknown>>;
+  readonly migrationPlan?: MigrationPlan;
   readonly meta?: Readonly<Record<string, unknown>>;
 };
 
@@ -95,6 +113,22 @@ function validateEntityType(type?: string): void {
   }
 }
 
+const COVERAGE_PROOF_STATUSES: ReadonlySet<string> = new Set([
+  "proven",
+  "missing",
+  "unresolved",
+  "not_applicable",
+]);
+
+function validateCoverageStatus(status: string): string {
+  if (!COVERAGE_PROOF_STATUSES.has(status)) {
+    throw new Error(
+      `Invalid coverage status '${status}'. Valid statuses: ${[...COVERAGE_PROOF_STATUSES].join(", ")}.`,
+    );
+  }
+  return status;
+}
+
 export async function executeFindGaps(
   input: FindGapsInput,
   context: OperationContext,
@@ -151,6 +185,79 @@ export const findGapsSpec = {
   execute: executeFindGaps,
 } as const satisfies OperationSpec<FindGapsInput, FindGapsPayload>;
 
+/**
+ * Per-contract receipt binding (W2): compute the current binding hash for
+ * every receipt-bearing test (contract + receipt-stripped authored document
+ * + bound-symbol code scope) and hand the Prolog coverage stage a
+ * TestId -> BindingHash dict. This is the default binding mode since slice 3;
+ * KIBI_PROOF_BINDING_MODE=strict-snapshot opts out (receipts then match only
+ * against the whole-workspace snapshot they were proven on).
+ */
+// implements REQ-kibi-proof-evidence-protocol
+export function currentProofBindingMode(): "per_contract" | "strict_snapshot" {
+  return process.env.KIBI_PROOF_BINDING_MODE?.trim() === "strict-snapshot"
+    ? "strict_snapshot"
+    : "per_contract";
+}
+
+async function perContractTestBindings(
+  context: OperationContext,
+): Promise<string | null> {
+  if (currentProofBindingMode() !== "per_contract") return null;
+  const { loadEntities } = await import("../discovery-entities.js");
+  const { receiptBindingHash } = await import("../../proof-fingerprint.js");
+  const { removeFrontmatterBlock } = await import(
+    "../../../operations/proof/receipt-document.js"
+  );
+  let tests: Record<string, unknown>[];
+  try {
+    tests = await loadEntities(context.prolog as never, { type: "test" });
+  } catch {
+    return null;
+  }
+  const entries: string[] = [];
+  const manifestPath = join(context.workspaceRoot, ".kb", "symbols.yaml");
+  for (const test of tests) {
+    const testId = typeof test.id === "string" ? test.id : "";
+    const contract =
+      test.proof_contract !== undefined &&
+      test.proof_contract !== null &&
+      typeof test.proof_contract === "object"
+        ? (test.proof_contract as Record<string, unknown>)
+        : undefined;
+    const source = typeof test.source === "string" ? test.source : "";
+    if (testId === "" || contract === undefined || source === "") continue;
+    if (!/\.(md|mdx)$/i.test(source)) continue;
+    if (!context.fs) continue;
+    try {
+      const absolute = join(context.workspaceRoot, source);
+      const authored = await context.fs.readFile(absolute);
+      const stripped = removeFrontmatterBlock(authored, "proof_receipts");
+      const rawBindings: ReadonlyArray<{ symbol_id?: unknown }> = Array.isArray(
+        test.proof_bindings,
+      )
+        ? (test.proof_bindings as ReadonlyArray<{ symbol_id?: unknown }>)
+        : [];
+      const boundIds = rawBindings
+        .map((binding) =>
+          typeof binding.symbol_id === "string" ? binding.symbol_id : "",
+        )
+        .filter((id) => id !== "");
+      const codeScope = resolveBoundSymbolScope(manifestPath, boundIds);
+      const binding = receiptBindingHash(
+        contract as never,
+        stripped ?? authored,
+        codeScope,
+      );
+      entries.push(`${toPrologAtom(testId)}: ${toPrologAtom(binding)}`);
+    } catch {
+      // Unreadable documents keep strict semantics for that test.
+    }
+  }
+  if (entries.length === 0) return null;
+  return `_{${entries.join(", ")}}`;
+}
+
 export async function executeCoverage(
   input: CoverageInput,
   context: OperationContext,
@@ -161,13 +268,38 @@ export async function executeCoverage(
       ? snapshotEvidence.snapshot.hash
       : "unknown";
     const checkedAt = context.clock().toISOString();
+    const statuses = (input.statuses ?? []).map((status) =>
+      validateCoverageStatus(status),
+    );
+    const bindingsDict =
+      statuses.length === 0 && (input.by ?? "req") === "req"
+        ? await perContractTestBindings(context)
+        : null;
+    const goal =
+      bindingsDict !== null
+        ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, per_contract, ${bindingsDict}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
+        : statuses.length > 0
+          ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${toPrologList(statuses)}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
+          : `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`;
     const payload = await runOperationJsonQuery<CoveragePayload>(
       requireProlog(context),
       "discovery.pl",
-      `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${VERIFICATION_RECEIPT_MAX_AGE_SECONDS}, JsonString)`,
+      goal,
       "Coverage execution",
     );
-    const repairPlan = buildRepairPlan(payload, input, codeSnapshot);
+    const rows =
+      (input.by ?? "req") === "req"
+        ? await addCoordinateRepairEvidence(payload.rows, context)
+        : payload.rows;
+    const repairPlan = buildRepairPlan(
+      { ...payload, rows },
+      input,
+      codeSnapshot,
+    );
+    const symbolRepairPlan =
+      input.by === "symbol"
+        ? await buildSymbolRepairPlan(payload.rows, context)
+        : undefined;
     const legacyMigrationPlan =
       input.includeMigrationPreview === true && repairPlan !== undefined
         ? await buildLegacyMigrationPlanFromContext(
@@ -177,23 +309,63 @@ export async function executeCoverage(
             context,
           )
         : undefined;
+    // Coverage can still report its complete Prolog-backed domain in a
+    // synthetic or non-Git workspace where branch status cannot be resolved.
+    // Preserve the coverage plan and let status expose its own branch action
+    // when an attachment is available.
+    let statusPlan: MigrationPlan | undefined;
+    try {
+      const statusResult = await executeStatus({}, context);
+      statusPlan = statusResult.structuredContent?.migrationPlan;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!message.includes("Failed to resolve active branch")) throw error;
+    }
+    const coveragePlan = buildMigrationPlan({
+      expected: {
+        branch: context.branchAttachment?.gitBranch ?? null,
+        kbBranch: context.branchAttachment?.kbBranch ?? null,
+        ...(typeof payload.meta?.snapshotId === "string"
+          ? { kbSnapshotId: payload.meta.snapshotId }
+          : {}),
+        workspaceSnapshot: codeSnapshot,
+      },
+      evaluatedDomains: ["semantic", "proof", "symbol"],
+      incompleteDomains:
+        payload.meta?.scopeComplete === false ? ["coverage"] : [],
+      actions: buildActionsFromCoverage({
+        ...(repairPlan !== undefined
+          ? {
+              repairPlan: repairPlan as unknown as Readonly<
+                Record<string, unknown>
+              >,
+            }
+          : {}),
+        ...(symbolRepairPlan !== undefined ? { symbolRepairPlan } : {}),
+      }),
+    });
+    const migrationPlan = statusPlan
+      ? mergeMigrationPlans([statusPlan, coveragePlan])
+      : coveragePlan;
     const enrichedPayload = {
       ...payload,
+      rows,
       ...(repairPlan !== undefined ? { repairPlan } : {}),
       ...(legacyMigrationPlan !== undefined ? { legacyMigrationPlan } : {}),
+      ...(symbolRepairPlan !== undefined ? { symbolRepairPlan } : {}),
+      migrationPlan,
       meta: {
         ...(payload.meta ?? {}),
-        verificationReceiptMaxAgeSeconds: VERIFICATION_RECEIPT_MAX_AGE_SECONDS,
-        verificationSnapshot: codeSnapshot,
-        verificationSnapshotAvailable: snapshotEvidence.available,
+        proofReceiptMaxAgeSeconds: PROOF_RECEIPT_MAX_AGE_SECONDS,
+        proofSnapshot: codeSnapshot,
+        proofSnapshotAvailable: snapshotEvidence.available,
         ...(snapshotEvidence.available
           ? {
-              verificationSnapshotDirty: snapshotEvidence.snapshot.dirty,
-              verificationSnapshotFileCount:
-                snapshotEvidence.snapshot.fileCount,
-              verificationSnapshotVersion: snapshotEvidence.snapshot.version,
+              proofSnapshotDirty: snapshotEvidence.snapshot.dirty,
+              proofSnapshotFileCount: snapshotEvidence.snapshot.fileCount,
+              proofSnapshotVersion: snapshotEvidence.snapshot.version,
             }
-          : { verificationSnapshotError: snapshotEvidence.error }),
+          : { proofSnapshotError: snapshotEvidence.error }),
       },
     };
     const fullyCovered = Number(enrichedPayload.summary?.fullyCovered ?? 0);
@@ -218,13 +390,22 @@ export const coverageSpec = {
   name: "kb_coverage",
   cliName: "coverage",
   description:
-    "Generate curated structural coverage and conservative end-to-end requirement proof reports for requirements, symbols, or grouped types. Requirement reports include a deterministic, dependency-ordered, read-only repair plan; optional legacy migration previews reconstruct authored proposition inventories and rank exact schema candidates without producing executable writes. Paginated plans identify incomplete scope. Requirement rows keep coverageStatus separate from proofStatus and require fresh snapshot-bound E2E receipts before proof. No mutation side effects.",
+    "Generate curated structural coverage and conservative end-to-end requirement proof reports for requirements, symbols, or grouped types. Reports include the compatible repair plan plus typed kibi.migration-plan.v2 actions; semantic and E2E actions remain review/execution work. Paginated plans identify incomplete scope and no mutation occurs.",
   businessInputSchema: {
     type: "object",
     properties: {
       by: { type: "string", enum: ["req", "symbol", "type"], default: "req" },
       tags: { type: "array", items: { type: "string" } },
       includePassing: { type: "boolean", default: false },
+      statuses: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: ["proven", "missing", "unresolved", "not_applicable"],
+        },
+        description:
+          "Requirement proof-status filter (req mode): include only rows whose proofStatus is listed. Selecting statuses implies include-passing; not_applicable rows carry their typed applicability reason in proofStages.applicability.reason. The summary always reflects the whole KB.",
+      },
       includeTransitive: { type: "boolean", default: true },
       limit: { type: "integer", default: 100 },
       offset: { type: "integer", default: 0 },

package/src/public/operations/specs/upsert.ts

@@ -32,6 +32,16 @@ export const upsertSpec = {
       },
       properties: ENTITY_PROPERTIES_SCHEMA,
       relationships: RELATIONSHIPS_SCHEMA,
+      document: {
+        type: "object",
+        additionalProperties: false,
+        description:
+          "Optional source-first document write. Paths are workspace-relative; omit body when updating to preserve the existing body bytes.",
+        properties: {
+          path: { type: "string", minLength: 1 },
+          body: { type: "string" },
+        },
+      },
     },
   },
   requiresProlog: true,