archctx-contracts 0.8.0 → 0.8.1

package/fixtures/valid/archctx-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "archcontext.capabilities/v1",
-  "package": { "name": "archctx", "version": "0.8.0" },
+  "package": { "name": "archctx", "version": "0.8.1" },
   "protocols": {
     "projectionRequest": "archcontext.projection-request/v1",
     "projectionResult": "archcontext.projection-result/v2",

package/fixtures/valid/product-version-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": "archcontext.product-version-manifest/v1",
   "product": {
     "name": "archctx",
-    "version": "0.8.0",
+    "version": "0.8.1",
     "distribution": "one-package"
   },
   "packageManager": "bun@1.4.3",
@@ -12,25 +12,25 @@
   "surfaces": {
     "cli": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.8.0",
+      "version": "0.8.1",
       "entrypoint": "archctx"
     },
     "daemon": {
       "packageName": "@archcontext/local-runtime",
-      "version": "0.8.0",
+      "version": "0.8.1",
       "entrypoint": "archctx daemon start",
       "rpcSchemaVersion": "archcontext.runtime-rpc/v2"
     },
     "mcp": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.8.0",
+      "version": "0.8.1",
       "entrypoint": "archctx mcp",
       "transport": "stdio"
     }
   },
   "schemas": {
     "schemaSetVersion": "2026-06-25.al0-ledger",
-    "contractsPackageVersion": "0.8.0",
+    "contractsPackageVersion": "0.8.1",
     "reviewChallenge": "archcontext.review-challenge/v2",
     "attestation": "archcontext.attestation/v2",
     "deviceIdentity": "archcontext.device-identity/v1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx-contracts",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/schemas/runtime/native-model-issue.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archctx.repoharness.com/schemas/runtime/native-model-issue.schema.json",
+  "title": "NativeModelIssue",
+  "description": "A native model schema or reference issue. Source paths are optional for callers that do not supply parsed record paths.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["entityId", "field", "invariant"],
+  "properties": {
+    "entityId": { "type": "string" },
+    "field": { "type": "string" },
+    "invariant": { "type": "string" },
+    "path": {
+      "type": "string",
+      "description": "The repository-relative path of the parsed source file that holds this record. It is not derived from the entity ID."
+    }
+  }
+}

package/src/failure.ts

@@ -23,6 +23,16 @@ export interface FailureEnvelope<C extends FailureCode = FailureCode> {
   error: StrictFailure<C>;
 }
 type Policy = { code: FailureCode; message: string; fields?: readonly string[]; action?: string; facts?: Readonly<Record<string, string>>; native?: boolean; recovery?: boolean; journalRecovery?: boolean; retryable?: boolean };
+/** Closed repository diagnostics. Messages contain no process output or filesystem paths. */
+export const CODE_FACTS_ISSUE_MESSAGES = Object.freeze({
+  "not-initialized": "CodeGraph repository status is not initialized",
+  "version-mismatch": "CodeGraph repository status version mismatch",
+  "project-path-mismatch": "CodeGraph repository project path mismatch",
+  "index-incomplete": "CodeGraph repository index is not complete and compatible",
+  "extraction-version-mismatch": "CodeGraph repository extraction version mismatch",
+  "worktree-mismatch": "CodeGraph repository worktree mismatch",
+  "pending-source-changes": "CodeGraph repository index has pending or unreported source changes"
+});
 /** Each reason has a closed fact vocabulary. No source text or recovery binding is a summary fact. */
 const policies: Record<string, Policy> = {
   "git-worktree-required": { code: "AC_REPO_NOT_FOUND", message: "This operation requires a Git worktree.", fields: ["checks"] },
@@ -33,6 +43,7 @@ const policies: Record<string, Policy> = {
   "projection-manifest-invalid": { code: "AC_PRECONDITION_FAILED", message: "The committed projection manifest violates its contract." },
   "projection-footprint-uncovered": { code: "AC_PRECONDITION_FAILED", message: "Declared source footprints lack a projection target." },
   "index-missing": { code: "AC_CODE_FACTS_UNAVAILABLE", message: "Required code facts have no available index. Run codegraph init." },
+  "code-facts-not-ready": { code: "AC_CODE_FACTS_NOT_READY", message: "Repository code facts are not ready. Run archctx doctor --json and follow the reported action.", facts: { issues: "codeFactsIssues" } },
   "checkpoint-input-invalid": { code: "AC_SCHEMA_INVALID", message: "Checkpoint arguments violate the declared input schema.", fields: ["issueCount"], action: "correct-command-arguments" },
   "cli-input-invalid": { code: "AC_SCHEMA_INVALID", message: "Command arguments violate the declared input contract.", action: "correct-command-arguments" },
   "complete-input-invalid": { code: "AC_SCHEMA_INVALID", message: "Completion input violates the caller authority contract.", action: "correct-command-arguments" },
@@ -41,7 +52,7 @@ const policies: Record<string, Policy> = {
   "runtime-version-unsupported": { code: "AC_RUNTIME_VERSION_UNSUPPORTED", message: "The connected runtime version is unsupported." },
   "rpc-timeout": { code: "RPC_TIMEOUT", message: "The runtime RPC deadline elapsed without a response; a mutation outcome is unknown.", fields: ["method", "timeoutMs", "elapsedMs", "mutationOutcome"], action: "reconcile-before-retry" },
   "rpc-aborted": { code: "RPC_ABORTED", message: "The runtime RPC caller aborted without a response; a mutation outcome is unknown.", fields: ["method", "timeoutMs", "elapsedMs", "mutationOutcome"], action: "reconcile-before-retry" },
-  "failure-unclassified": { code: "AC_UNCLASSIFIED_FAILURE", message: "The operation failed without a classified cause. Inspect local diagnostics before retrying.", action: "inspect-diagnostics" },
+  "failure-unclassified": { code: "AC_UNCLASSIFIED_FAILURE", message: "The operation failed without a classified cause. Run archctx doctor --json before retrying.", action: "inspect-diagnostics" },
 };
 // C1 policies are selected at explicit producer branches, never from diagnostic text.
 Object.assign(policies, {
@@ -278,7 +289,7 @@ for (const policy of Object.values(policies)) {
 }
 export const FAILURE_POLICIES: Readonly<Record<string, Readonly<Policy>>> = Object.freeze(policies);
 const catalogDefaults = Object.fromEntries(Object.entries(ERROR_CATALOG).map(([code, value]) => [code, Object.freeze({ severity: value.severity, retryable: value.retryable, action: value.action })])) as Readonly<Record<ArchContextErrorCode, Readonly<Pick<StrictFailure, "severity" | "retryable" | "action">>>>;
-const actions = new Set([...Object.values(catalogDefaults).map(value => value.action), "correct-command-arguments", "inspect-diagnostics", "reconcile-before-retry", ...Object.values(policies).flatMap(policy => policy.action ? [policy.action] : [])]);
+const actions = new Set([...Object.values(catalogDefaults).map(value => value.action), "correct-command-arguments", "inspect-diagnostics", "reconcile-before-retry", "install-compatible-codegraph", ...Object.values(policies).flatMap(policy => policy.action ? [policy.action] : [])]);
 const bytes = (value: string) => new TextEncoder().encode(value).byteLength;
 const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
 const finiteNonnegative = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
@@ -400,6 +411,20 @@ const localEnums: Readonly<Record<string, readonly string[]>> = {
   ]
 };
 function localFactValue(rule: string, value: unknown): Json {
+  if (rule === "codeFactsIssues") {
+    if (!Array.isArray(value)) throw new Error("Code facts issues must be a list");
+    const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+    if (!Number.isSafeInteger(length) || length < 1 || length > 32 || Reflect.ownKeys(value).length !== length + 1) throw new Error("Code facts issues exceed their closed budget");
+    return Array.from({ length }, (_, index) => {
+      const entry = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!entry || !("value" in entry)) throw new Error("Code facts issues must use own data");
+      const fields = dataRecord(entry.value);
+      const code = fields.code?.value, message = fields.message?.value;
+      if (Object.keys(fields).length !== 2 || typeof code !== "string" || !Object.hasOwn(CODE_FACTS_ISSUE_MESSAGES, code)
+        || message !== CODE_FACTS_ISSUE_MESSAGES[code as keyof typeof CODE_FACTS_ISSUE_MESSAGES]) throw new Error("Unknown code facts diagnostic");
+      return { code, message };
+    });
+  }
   if (rule === "commandSuggestion" && (value === null || (typeof value === "string" && bytes(value) <= 1024 && /^archctx (recommendations |refactor verify )[^\r\n]*$/.test(value)))) return value;
   if (rule === "publicConfirmationToken" && typeof value === "string" && bytes(value) <= 1024 && /^public:github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+:[a-f0-9]{40}:[A-Za-z0-9_.:-]+$/.test(value)) return value;
   if (rule === "diagnosticPaths" || rule === "diagnosticCommands") {
@@ -568,7 +593,7 @@ function nativeFactsFor(policy: Policy, input: unknown): {[key: string]: Json} {
     if (type === "diagnostic") { const s = text(value); if (bytes(s) > 256) { omit(s); return undefined; } return s; }
     const item = dataRecord(value);
     if (type === "issues") {
-      if (Object.keys(item).length !== 3 || !["entityId", "field", "invariant"].every(key => Object.hasOwn(item, key))) throw new Error("Native issue schema is invalid");
+      if (!["entityId", "field", "invariant"].every(key => Object.hasOwn(item, key)) || Object.keys(item).some(key => !["entityId", "field", "invariant", "path"].includes(key))) throw new Error("Native issue schema is invalid");
       const clean = Object.fromEntries(Object.entries(item).map(([key, data]) => [key, text(data.value)]));
       if (Object.values(clean).some(v => bytes(v) > 256)) { omit(clean); return undefined; }
       return clean;
@@ -616,12 +641,21 @@ function nativeFactsFor(policy: Policy, input: unknown): {[key: string]: Json} {
     }
     result[key] = values;
   }
+  const sourceIssues = Array.isArray(result.issues) ? result.issues as Array<Record<string, Json>> : [];
+  // Legacy issues without source paths keep any explicit path supplied by the caller.
+  const summarizePath = sourceIssues.some(issue => typeof issue.path === "string");
   const counts = () => {
     if (!Number.isSafeInteger(omitted) || !Number.isSafeInteger(characters)) throw new Error("Native diagnostic counts exceed schema");
     if (omitted) result.omittedDiagnosticCount = omitted;
     if (characters) result.omittedDiagnosticCharacters = characters;
   };
   const fits = () => {
+    // Derive the summary from surviving whole issues, including after budget omission.
+    if (summarizePath) {
+      const path = sourceIssues[0]?.path;
+      if (typeof path === "string" && sourceIssues.every(issue => issue.path === path)) result.path = path;
+      else delete result.path;
+    }
     counts();
     const base = catalogDefaults[policy.code as ArchContextErrorCode];
     const error = {code: policy.code, message: policy.message, severity: base.severity, retryable: policy.retryable ?? base.retryable, action: policy.action ?? base.action, reasonCode: Object.entries(policies).find(([, p]) => p === policy)?.[0], details: result};

package/src/native-context.ts

@@ -149,7 +149,7 @@ export function nativeByteCompare(left: string, right: string): number {
 
 type SchemaDocument = Parameters<typeof validateJsonSchema>[0];
 export interface NativeContextSchemas { node: SchemaDocument; relation: SchemaDocument; flow: SchemaDocument }
-export interface NativeModelIssue { entityId: string; field: string; invariant: string }
+export interface NativeModelIssue { entityId: string; field: string; invariant: string; path?: string }
 
 /** Fixed canonical documents are supplied by the bundled reader, never by repository input. */
 export function nativeContextSchemaResolver(schemas: NativeContextSchemas): JsonSchemaResolver {
@@ -162,10 +162,14 @@ export function nativeAllowedNodeKinds(schemas: NativeContextSchemas): string[]
   return [...kinds] as string[];
 }
 
-/** Complete native shape/reference validation; no filesystem, symbols, runtime or mutation. */
-export function nativeContextModelIssues(model: NativeContextModel, schemas: NativeContextSchemas): NativeModelIssue[] {
+/** Complete native shape/reference validation; optional paths bind parsed records, never IDs. */
+export function nativeContextModelIssues(model: NativeContextModel, schemas: NativeContextSchemas, recordPaths?: ReadonlyMap<NativeModelRecord, string>): NativeModelIssue[] {
   const issues: NativeModelIssue[] = [];
-  const add = (entityId: string, field: string, invariant: string) => issues.push({ entityId, field, invariant });
+  const add = (record: NativeModelRecord | string, field: string, invariant: string) => {
+    const entityId = typeof record === "string" ? record : typeof record.id === "string" ? record.id : "(undeclared)";
+    const path = typeof record === "string" ? undefined : recordPaths?.get(record);
+    issues.push({ entityId, field, invariant, ...(path === undefined ? {} : { path }) });
+  };
   const resolveSchema = nativeContextSchemaResolver(schemas);
   const ids = new Set<string>();
   for (const [kind, records] of [["node", model.nodes], ["relation", model.relations], ["flow", model.flows]] as const) {
@@ -182,46 +186,45 @@ export function nativeContextModelIssues(model: NativeContextModel, schemas: Nat
         const item = pending.pop()!;
         const value = item.value;
         if (item.exit) { active.delete(value as object); done.add(value as object); continue; }
-        if (typeof value === "number" && !Number.isFinite(value)) { add(id, item.field, "non-json-number"); jsonInvalid = true; break; }
+        if (typeof value === "number" && !Number.isFinite(value)) { add(record, item.field, "non-json-number"); jsonInvalid = true; break; }
         if (value === null || typeof value !== "object") continue;
-        if (active.has(value)) { add(id, item.field, "non-json-cycle"); jsonInvalid = true; break; }
+        if (active.has(value)) { add(record, item.field, "non-json-cycle"); jsonInvalid = true; break; }
         if (done.has(value)) continue;
         const prototype = Object.getPrototypeOf(value);
-        if (Array.isArray(value) ? prototype !== Array.prototype : prototype !== Object.prototype) { add(id, item.field, "non-json-prototype"); jsonInvalid = true; break; }
+        if (Array.isArray(value) ? prototype !== Array.prototype : prototype !== Object.prototype) { add(record, item.field, "non-json-prototype"); jsonInvalid = true; break; }
         active.add(value); pending.push({ value, field: item.field, exit: true });
         for (const [key, child] of Object.entries(value)) pending.push({ value: child, field: `${item.field}.${key}` });
       }
       if (jsonInvalid) continue;
       const schema = kind === "node" ? schemas.node : kind === "relation" ? schemas.relation : schemas.flow;
-      for (const issue of validateJsonSchema(schema, record, { resolveSchema }).issues) add(id, issue.path, issue.message);
-      if (ids.has(id)) add(id, "id", "duplicate-entity-id");
+      for (const issue of validateJsonSchema(schema, record, { resolveSchema }).issues) add(record, issue.path, issue.message);
+      if (ids.has(id)) add(record, "id", "duplicate-entity-id");
       ids.add(id);
     }
   }
   // Invalid shapes cannot safely participate in reference validation.
   if (issues.length > 0) return issues;
   for (const kind of ["nodes", "relations", "flows"] as const) {
-    const expected = new Set(model[kind].map(entity => entity.id as string));
-    for (const id of expected) if (!Object.hasOwn(model.sourcePaths[kind], id)) add(id, `sourcePaths.${kind}`, "source-path-index-incomplete");
+    const expected = new Map(model[kind].map(entity => [entity.id as string, entity]));
+    for (const [id, entity] of expected) if (!Object.hasOwn(model.sourcePaths[kind], id)) add(entity, `sourcePaths.${kind}`, "source-path-index-incomplete");
     for (const [id, path] of Object.entries(model.sourcePaths[kind])) {
       if (!expected.has(id)) add(id, `sourcePaths.${kind}`, "source-path-index-unknown-entity");
-      if (!isNativeContextPath(path)) add(id, `sourcePaths.${kind}`, "path-unsafe");
+      if (!isNativeContextPath(path)) add(expected.get(id) ?? id, `sourcePaths.${kind}`, "path-unsafe");
     }
   }
   const nodes = new Map(model.nodes.map(node => [node.id as string, node]));
   const checked = new Set<string>();
   for (const node of model.nodes) {
-    const id = node.id as string;
     const chain = new Set<string>();
     let cursor: NativeModelRecord | undefined = node;
     while (cursor) {
       const current = cursor.id as string;
-      if (chain.has(current)) { add(id, "parent", "parent-cycle"); break; }
+      if (chain.has(current)) { add(node, "parent", "parent-cycle"); break; }
       if (checked.has(current)) break;
       chain.add(current);
       if (cursor.parent === undefined) break;
       const parent = nodes.get(cursor.parent as string);
-      if (!parent) { add(current, "parent", "parent-node-missing"); break; }
+      if (!parent) { add(cursor, "parent", "parent-node-missing"); break; }
       cursor = parent;
     }
     for (const current of chain) checked.add(current);
@@ -229,48 +232,47 @@ export function nativeContextModelIssues(model: NativeContextModel, schemas: Nat
   const selectors = new Set<string>();
   for (const node of model.nodes) {
     const source = node.source as { include?: string[]; exclude?: string[]; entrypoints?: Array<{ id: string; path: string; symbols: Array<{ name: string; sinks: Array<{ id: string; path: string; symbol: string }> }> }> } | undefined;
-    for (const path of [...source?.include ?? [], ...source?.exclude ?? []]) if (!isNativeContextPath(path)) add(node.id as string, "source", "path-unsafe");
+    for (const path of [...source?.include ?? [], ...source?.exclude ?? []]) if (!isNativeContextPath(path)) add(node, "source", "path-unsafe");
     for (const entry of source?.entrypoints ?? []) {
-      if (!isNativeContextPath(entry.path)) add(node.id as string, "source.entrypoints.path", "path-unsafe");
+      if (!isNativeContextPath(entry.path)) add(node, "source.entrypoints.path", "path-unsafe");
       for (const symbol of entry.symbols) {
         for (const sink of symbol.sinks) {
-          if (!isNativeContextPath(sink.path)) add(node.id as string, "source.entrypoints.symbols.sinks.path", "path-unsafe");
+          if (!isNativeContextPath(sink.path)) add(node, "source.entrypoints.symbols.sinks.path", "path-unsafe");
           const selector = JSON.stringify([entry.id, symbol.name, sink.id]);
-          if (selectors.has(selector)) add(node.id as string, "source.entrypoints.symbols.sinks.id", "selector-ambiguous");
+          if (selectors.has(selector)) add(node, "source.entrypoints.symbols.sinks.id", "selector-ambiguous");
           selectors.add(selector);
         }
       }
     }
   }
   for (const relation of model.relations) {
-    for (const field of ["source", "target", "via"] as const) if (relation[field] !== undefined && !nodes.has(relation[field] as string)) add(relation.id as string, field, "relation-node-missing");
+    for (const field of ["source", "target", "via"] as const) if (relation[field] !== undefined && !nodes.has(relation[field] as string)) add(relation, field, "relation-node-missing");
   }
   for (const flow of model.flows) {
-    const id = flow.id as string;
-    if (nodes.get(flow.capabilityId as string)?.kind !== "capability") add(id, "capabilityId", "flow-capability-missing");
+    if (nodes.get(flow.capabilityId as string)?.kind !== "capability") add(flow, "capabilityId", "flow-capability-missing");
     if (flow.applicability !== "required") continue;
     const participants = flow.participants as Array<{ id: string; nodeId: string }>;
     const participantIds = new Set<string>();
     for (const participant of participants) {
-      if (participantIds.has(participant.id)) add(id, "participants.id", "participant-id-ambiguous");
+      if (participantIds.has(participant.id)) add(flow, "participants.id", "participant-id-ambiguous");
       participantIds.add(participant.id);
-      if (!nodes.has(participant.nodeId)) add(id, "participants.nodeId", "participant-node-missing");
+      if (!nodes.has(participant.nodeId)) add(flow, "participants.nodeId", "participant-node-missing");
     }
     const definitions = new Map<string, string>();
     const outcomes = flow.outcomes as Array<{ id: string; steps: NativeModelRecord[]; terminal: { participant: string } }>;
     const outcomeIds = new Set<string>();
     for (const outcome of outcomes) {
-      if (outcomeIds.has(outcome.id)) add(id, "outcomes.id", "outcome-id-ambiguous");
+      if (outcomeIds.has(outcome.id)) add(flow, "outcomes.id", "outcome-id-ambiguous");
       outcomeIds.add(outcome.id);
-      if (!participantIds.has(outcome.terminal.participant)) add(id, "outcomes.terminal", "terminal-participant-missing");
+      if (!participantIds.has(outcome.terminal.participant)) add(flow, "outcomes.terminal", "terminal-participant-missing");
     }
     for (const step of [...flow.steps as NativeModelRecord[], ...outcomes.flatMap(outcome => outcome.steps)]) {
-      if (!participantIds.has(step.from as string) || !participantIds.has(step.to as string)) add(id, "steps", "step-participant-missing");
+      if (!participantIds.has(step.from as string) || !participantIds.has(step.to as string)) add(flow, "steps", "step-participant-missing");
       const definition = canonicalize(step);
-      if (definitions.has(step.id as string) && definitions.get(step.id as string) !== definition) add(id, "steps.id", "step-definition-ambiguous");
+      if (definitions.has(step.id as string) && definitions.get(step.id as string) !== definition) add(flow, "steps.id", "step-definition-ambiguous");
       definitions.set(step.id as string, definition);
       const selector = step.evidence as { entrypointId: string; sourceSymbol: string; sinkId: string };
-      if (!selectors.has(JSON.stringify([selector.entrypointId, selector.sourceSymbol, selector.sinkId]))) add(id, "steps.evidence", "selector-missing");
+      if (!selectors.has(JSON.stringify([selector.entrypointId, selector.sourceSymbol, selector.sinkId]))) add(flow, "steps.evidence", "selector-missing");
     }
   }
   return issues;

package/src/ports.ts

@@ -121,6 +121,8 @@ export interface SourceSelector {
 }
 
 export interface CodeFactsPort {
+  /** Read-only compatibility check before the existing incremental sync. No retry or rebuild. */
+  assertCanSync?(workspaceRoot: string): void;
   ensureReady(workspace: WorkspaceRef): Promise<CodeFactsSnapshot>;
   sync(input: { workspace: WorkspaceRef; changedPaths?: string[] }): Promise<CodeFactsSnapshot>;
   buildTaskContext(input: { task: string; maxSymbols: number; includeSource: boolean; changedPaths?: string[] }): Promise<NormalizedCodeContext>;
@@ -148,6 +150,8 @@ export interface ModelValidationResult {
    * `appliesTo` id with no node. Omitted when empty.
    */
   referenceErrors?: string[];
+  /** Node schema errors with their file paths. Only a write to that node can repair them. */
+  nodeSchemaErrors?: { path: string; error: string }[];
   /** Problems that do not invalidate the model, such as an ignored legacy setting. Omitted when empty. */
   warnings?: string[];
   modelDigest: string;

package/src/product-version.ts

@@ -1,5 +1,5 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.8.0";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.8.1";
 export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.3";
 export const ARCHCONTEXT_NODE_RANGE = ">=22.22 <26";
 export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v2";

package/src/schema.ts

@@ -18,6 +18,7 @@ export type ArchContextErrorCode =
   | "AC_NODE_VERSION_UNSUPPORTED"
   | "AC_CODEGRAPH_UNAVAILABLE"
   | "AC_CODE_FACTS_UNAVAILABLE"
+  | "AC_CODE_FACTS_NOT_READY"
   | "AC_INDEX_STALE"
   | "AC_CONTEXT_STALE"
   | "AC_SCHEMA_INVALID"
@@ -68,6 +69,7 @@ export const ERROR_CATALOG: Record<ArchContextErrorCode, Omit<ArchContextError,
   AC_NODE_VERSION_UNSUPPORTED: { code: "AC_NODE_VERSION_UNSUPPORTED", severity: "error", retryable: false, action: "use-supported-node-version" },
   AC_CODEGRAPH_UNAVAILABLE: { code: "AC_CODEGRAPH_UNAVAILABLE", severity: "error", retryable: true, action: "run-diagnostics" },
   AC_CODE_FACTS_UNAVAILABLE: { code: "AC_CODE_FACTS_UNAVAILABLE", severity: "error", retryable: true, action: "codegraph-init" },
+  AC_CODE_FACTS_NOT_READY: { code: "AC_CODE_FACTS_NOT_READY", severity: "error", retryable: false, action: "codegraph-index" },
   AC_INDEX_STALE: { code: "AC_INDEX_STALE", severity: "warning", retryable: true, action: "sync-codefacts" },
   AC_CONTEXT_STALE: { code: "AC_CONTEXT_STALE", severity: "warning", retryable: true, action: "prepare-task-again" },
   AC_SCHEMA_INVALID: { code: "AC_SCHEMA_INVALID", severity: "error", retryable: false, action: "repair-model" },