kibi-cli 0.18.1 → 1.0.1

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

@@ -0,0 +1,234 @@
+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 },
+            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/reporting.ts

@@ -1,8 +1,15 @@
 import { VERIFICATION_RECEIPT_MAX_AGE_SECONDS } from "../../verification-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 +17,7 @@ import {
 } from "../prolog-json.js";
 import { type RepairPlan, buildRepairPlan } from "../repair-plan.js";
 import type { OperationContext } from "../runtime-types.js";
+import { buildSymbolRepairPlan } from "../symbol-repair-plan.js";
 import type { OperationResult, OperationSpec } from "../types.js";
 import { readWorkspaceSnapshot } from "../workspace-snapshot.js";
 
@@ -60,6 +68,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>>;
 };
 
@@ -168,6 +178,10 @@ export async function executeCoverage(
       "Coverage execution",
     );
     const repairPlan = buildRepairPlan(payload, input, codeSnapshot);
+    const symbolRepairPlan =
+      input.by === "symbol"
+        ? await buildSymbolRepairPlan(payload.rows, context)
+        : undefined;
     const legacyMigrationPlan =
       input.includeMigrationPreview === true && repairPlan !== undefined
         ? await buildLegacyMigrationPlanFromContext(
@@ -177,10 +191,50 @@ 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", "verification", "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,
       ...(repairPlan !== undefined ? { repairPlan } : {}),
       ...(legacyMigrationPlan !== undefined ? { legacyMigrationPlan } : {}),
+      ...(symbolRepairPlan !== undefined ? { symbolRepairPlan } : {}),
+      migrationPlan,
       meta: {
         ...(payload.meta ?? {}),
         verificationReceiptMaxAgeSeconds: VERIFICATION_RECEIPT_MAX_AGE_SECONDS,
@@ -218,7 +272,7 @@ 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: {

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,

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

@@ -0,0 +1,78 @@
+import {
+  type IngestVerificationArgs,
+  type IngestVerificationResult,
+  executeIngestVerification,
+} from "../../../operations/verification/ingest-verification.js";
+import type { OperationSpec } from "../types.js";
+
+export type {
+  IngestVerificationArgs,
+  IngestVerificationResult,
+} from "../../../operations/verification/ingest-verification.js";
+export { executeIngestVerification } from "../../../operations/verification/ingest-verification.js";
+
+// implements REQ-kibi-verification-evidence-contract
+export const ingestVerificationSpec = {
+  name: "kb_ingest_verification",
+  cliName: "ingest-verification",
+  description:
+    "Ingest a reporter-produced kibi.playwright-run.v1 artifact for a contracted test. Revalidates the live workspace snapshot, runner/command contract, required case/project coverage, and append-only receipt history before deriving and appending a kibi.verification-receipt.v2. It never accepts a caller-authored receipt or trusted outcome.",
+  businessInputSchema: {
+    type: "object",
+    required: ["testId", "snapshot", "artifact"],
+    properties: {
+      testId: {
+        type: "string",
+        minLength: 1,
+        description: "Existing test entity with verification_contract.v1.",
+      },
+      snapshot: {
+        type: "string",
+        pattern: "^[a-f0-9]{64}$",
+        description:
+          "Workspace verification snapshot captured immediately before the run.",
+      },
+      artifact: {
+        type: "object",
+        required: [
+          "version",
+          "runner",
+          "command_argv",
+          "code_snapshot",
+          "environment_hash",
+          "started_at",
+          "finished_at",
+          "process_exit_code",
+          "cases",
+        ],
+        properties: {
+          version: { type: "string", const: "kibi.playwright-run.v1" },
+          runner: { type: "string", minLength: 1 },
+          command_argv: {
+            type: "array",
+            minItems: 1,
+            items: { type: "string", minLength: 1 },
+          },
+          code_snapshot: { type: "string", pattern: "^[a-f0-9]{64}$" },
+          environment_hash: { type: "string", pattern: "^[a-f0-9]{64}$" },
+          started_at: { type: "string", minLength: 1 },
+          finished_at: { type: "string", minLength: 1 },
+          process_exit_code: { type: "integer" },
+          cases: {
+            type: "array",
+            minItems: 1,
+            maxItems: 1000,
+            items: { type: "object" },
+          },
+        },
+        additionalProperties: true,
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read", "kb-write", "workspace-read"],
+  execute: executeIngestVerification,
+} as const satisfies OperationSpec<
+  IngestVerificationArgs,
+  IngestVerificationResult
+>;

package/src/public/operations/symbol-repair-plan.ts

@@ -0,0 +1,164 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { analyzeSourceText } from "../../extractors/symbols-coordinator.js";
+import { loadEntities } from "./discovery-entities.js";
+import type { OperationContext } from "./runtime-types.js";
+
+export const SYMBOL_REPAIR_PLAN_VERSION = "kibi.symbol-repair-plan.v1" as const;
+
+export type SymbolRepairPlan = Readonly<{
+  version: typeof SYMBOL_REPAIR_PLAN_VERSION;
+  readOnly: true;
+  autoApplicable: false;
+  repairs: readonly Readonly<Record<string, unknown>>[];
+}>;
+
+function sourceFileOf(
+  entity: Readonly<Record<string, unknown>>,
+): string | null {
+  const value = entity.sourceFile ?? entity.source;
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function coordinatesPresent(
+  entity: Readonly<Record<string, unknown>>,
+): boolean {
+  return [
+    entity.sourceLine,
+    entity.sourceColumn,
+    entity.sourceEndLine,
+    entity.sourceEndColumn,
+  ].every((value) => Number.isInteger(value) && Number(value) >= 0);
+}
+
+function currentCandidates(
+  entity: Readonly<Record<string, unknown>>,
+  symbols: readonly Readonly<Record<string, unknown>>[],
+  extractedByPath: ReadonlyMap<
+    string,
+    readonly { name: string; kind: string }[]
+  >,
+): Readonly<Record<string, unknown>>[] {
+  const title = typeof entity.title === "string" ? entity.title : "";
+  const kind = typeof entity.symbol_kind === "string" ? entity.symbol_kind : "";
+  const source = sourceFileOf(entity);
+  const extracted = source ? (extractedByPath.get(source) ?? []) : [];
+  const names = new Set(
+    extracted
+      .filter((candidate) => !kind || candidate.kind === kind)
+      .map((candidate) => candidate.name),
+  );
+  return symbols
+    .filter((candidate) => candidate.id !== entity.id)
+    .filter((candidate) => {
+      const candidateTitle =
+        typeof candidate.title === "string" ? candidate.title : "";
+      const candidateKind =
+        typeof candidate.symbol_kind === "string" ? candidate.symbol_kind : "";
+      return (
+        (title !== "" && candidateTitle === title) ||
+        (kind !== "" && candidateKind === kind && names.has(candidateTitle))
+      );
+    })
+    .map((candidate) => ({
+      symbolId: String(candidate.id),
+      title: candidate.title,
+      symbolKind: candidate.symbol_kind,
+      sourceFile: sourceFileOf(candidate),
+      evidence: "current extraction/title/kind match",
+    }));
+}
+
+/** Build review-only, evidence-backed symbol recovery suggestions. */
+export async function buildSymbolRepairPlan(
+  rows: readonly Readonly<Record<string, unknown>>[],
+  context: OperationContext,
+): Promise<SymbolRepairPlan | undefined> {
+  if (!context.prolog || rows.length === 0) return undefined;
+  const symbols = await loadEntities(context.prolog, { type: "symbol" });
+  const extractedByPath = new Map<
+    string,
+    readonly { name: string; kind: string }[]
+  >();
+  for (const symbol of symbols) {
+    const source = sourceFileOf(symbol);
+    if (!source || extractedByPath.has(source)) continue;
+    const absolute = path.isAbsolute(source)
+      ? source
+      : path.resolve(context.workspaceRoot, source);
+    if (!existsSync(absolute)) continue;
+    try {
+      const analysis = analyzeSourceText(
+        absolute,
+        readFileSync(absolute, "utf8"),
+      );
+      extractedByPath.set(
+        source,
+        analysis.symbols.map((candidate) => ({
+          name: candidate.name,
+          kind: candidate.kind,
+        })),
+      );
+    } catch {
+      extractedByPath.set(source, []);
+    }
+  }
+
+  const repairs = rows.flatMap((row) => {
+    if (row.type !== "symbol") return [];
+    const entity = symbols.find((candidate) => candidate.id === row.id);
+    if (!entity) return [];
+    const source = sourceFileOf(entity);
+    const absolute = source
+      ? path.isAbsolute(source)
+        ? source
+        : path.resolve(context.workspaceRoot, source)
+      : null;
+    const exists = absolute !== null && existsSync(absolute);
+    const candidates = currentCandidates(entity, symbols, extractedByPath);
+    const extraction = source ? extractedByPath.get(source) : undefined;
+    const extractionProvesAbsent =
+      exists &&
+      extraction !== undefined &&
+      !extraction.some(
+        (candidate) =>
+          candidate.name === entity.title &&
+          (!entity.symbol_kind || candidate.kind === entity.symbol_kind),
+      );
+    const gaps = Array.isArray(row.gaps) ? row.gaps.map(String) : [];
+    const action = !exists
+      ? entity.symbol_origin === "extracted"
+        ? "delete_obsolete_symbol"
+        : "review"
+      : extractionProvesAbsent && entity.symbol_origin === "extracted"
+        ? "delete_obsolete_symbol"
+        : !coordinatesPresent(entity)
+          ? "refresh_coordinates"
+          : candidates.length > 0
+            ? "remap"
+            : "review";
+    return [
+      {
+        symbolId: String(entity.id),
+        action,
+        candidates,
+        evidence: {
+          sourceFile: source,
+          sourceExists: exists,
+          extractionProvesAbsent,
+          gaps,
+          currentExtractionAvailable: source
+            ? extractedByPath.has(source)
+            : false,
+          autoApply: false,
+        },
+      },
+    ];
+  });
+  return {
+    version: SYMBOL_REPAIR_PLAN_VERSION,
+    readOnly: true,
+    autoApplicable: false,
+    repairs,
+  };
+}

package/src/public/operations/types.ts

@@ -18,7 +18,10 @@ export type OperationName =
   | "kb_check"
   | "kb_model_requirement"
   | "kb_suggest_predicates"
-  | "kb_autopilot_generate";
+  | "kb_plan_bootstrap"
+  | "kb_compile_intent"
+  | "kb_apply_plan"
+  | "kb_ingest_verification";
 
 export type OperationEffect =
   | "local-read"
@@ -28,6 +31,14 @@ export type OperationEffect =
   | "kb-write"
   | "workspace-write";
 
+export type OperationEffectDeclaration = Readonly<{
+  kind: OperationEffect;
+  mutability: "read" | "write";
+  destructive: boolean;
+  retrySafety: "safe" | "unsafe";
+  openWorld: boolean;
+}>;
+
 export interface OperationContent {
   readonly type: string;
   readonly text?: string;
@@ -38,6 +49,40 @@ export interface OperationResult<O = unknown> {
   readonly structuredContent?: O;
 }
 
+export type KibiResultStatus = "success" | "committed_with_repairs" | "error";
+
+export type KibiResult<T = unknown> = {
+  readonly kibiProtocol: 1;
+  readonly operation: OperationName | string;
+  readonly resultVersion: string;
+  readonly status: KibiResultStatus;
+  readonly data: T;
+  readonly effects: readonly {
+    readonly kind: string;
+    readonly status: "completed" | "failed" | "not_applicable";
+    readonly detail?: unknown;
+    readonly errorCode?: string;
+  }[];
+  readonly diagnostics: readonly {
+    readonly code?: string;
+    readonly severity?: "info" | "warning" | "error";
+    readonly message: string;
+    readonly detail?: unknown;
+  }[];
+  readonly nextActions: readonly {
+    readonly operation: OperationName | string;
+    readonly input?: unknown;
+    readonly reason: string;
+    readonly required: boolean;
+  }[];
+  readonly error?: {
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly details?: unknown;
+  };
+};
+
 export interface OperationSpec<
   I = Readonly<Record<string, unknown>>,
   O = unknown,
@@ -48,6 +93,12 @@ export interface OperationSpec<
   readonly businessInputSchema: Readonly<Record<string, unknown>>;
   readonly requiresProlog: boolean;
   readonly effects: readonly OperationEffect[];
+  /** Generated effect metadata used by MCP annotations and telemetry. */
+  readonly declaredEffects?: readonly OperationEffectDeclaration[];
+  /** Version of the machine-readable result data for this operation. */
+  readonly resultVersion?: string;
+  /** JSON Schema for the machine-readable result data. */
+  readonly outputSchema?: Readonly<Record<string, unknown>>;
   readonly execute: {
     bivarianceHack(
       input: I,
@@ -55,3 +106,13 @@ export interface OperationSpec<
     ): Promise<OperationResult<O>>;
   }["bivarianceHack"];
 }
+
+/** A catalog spec after its generated machine contract has been attached. */
+export type ResolvedOperationSpec<
+  I = Readonly<Record<string, unknown>>,
+  O = unknown,
+> = OperationSpec<I, O> & {
+  readonly declaredEffects: readonly OperationEffectDeclaration[];
+  readonly resultVersion: string;
+  readonly outputSchema: Readonly<Record<string, unknown>>;
+};