archctx 0.8.0 → 0.8.1

package/assets/catalog.yaml

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "archcontext.practice-catalog-manifest/v1",
   "catalogVersion": "2026.06.0",
-  "productVersion": "0.8.0",
+  "productVersion": "0.8.1",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "entries": [
     {
@@ -389,5 +389,5 @@
     "structurizr.dsl",
     "twelve-factor"
   ],
-  "catalogDigest": "sha256:801316c8423f6d599e58a67ff0aa4cdd190fa105f263f0e636f5105709e325d2"
+  "catalogDigest": "sha256:abdff8c6f9f2ffc75fe35295b097884ec2996b179628bb81966f62cbb29ad75a"
 }

package/bin/archctx.mjs

@@ -96,6 +96,7 @@ var init_schema = __esm(() => {
     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" },
@@ -2031,6 +2032,23 @@ function dataRecord(value) {
   return fields;
 }
 function localFactValue(rule, value) {
+  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])
+        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))
@@ -2130,7 +2148,7 @@ function nativeFactsFor(policy, input) {
     }
     const item = dataRecord(value);
     if (type === "issues") {
-      if (Object.keys(item).length !== 3 || !["entityId", "field", "invariant"].every((key) => Object.hasOwn(item, key)))
+      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)) {
@@ -2202,6 +2220,8 @@ function nativeFactsFor(policy, input) {
     }
     result[key] = values;
   }
+  const sourceIssues = Array.isArray(result.issues) ? result.issues : [];
+  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");
@@ -2211,6 +2231,13 @@ function nativeFactsFor(policy, input) {
       result.omittedDiagnosticCharacters = characters;
   };
   const fits = () => {
+    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];
     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 };
@@ -2325,12 +2352,21 @@ function normalizeFailureResult(result, stage, requestId = "failure") {
     return toEnvelope(requestId, undefined, "failure-metadata");
   }
 }
-var FAILURE_STAGES, policies, FAILURE_POLICIES, catalogDefaults, actions, bytes = (value) => new TextEncoder().encode(value).byteLength, record2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value), finiteNonnegative = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0, criticalKey = (key) => /id$|digest|receipt|binding|readback|lookupkey/i.test(key), localEnums, nativeEnums, nativeDiagnosticKinds, FailureError;
+var FAILURE_STAGES, CODE_FACTS_ISSUE_MESSAGES, policies, FAILURE_POLICIES, catalogDefaults, actions, bytes = (value) => new TextEncoder().encode(value).byteLength, record2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value), finiteNonnegative = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0, criticalKey = (key) => /id$|digest|receipt|binding|readback|lookupkey/i.test(key), localEnums, nativeEnums, nativeDiagnosticKinds, FailureError;
 var init_failure = __esm(() => {
   init_changeset_recovery();
   init_projection_recovery();
   init_schema();
   FAILURE_STAGES = Object.freeze(["debt", "complete", "practice-checkpoint", "cli", "mcp", "hook-checkpoint", "failure-metadata", "public-operation", "native-export", "docs-anchors", "flows-check"]);
+  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"
+  });
   policies = {
     "git-worktree-required": { code: "AC_REPO_NOT_FOUND", message: "This operation requires a Git worktree.", fields: ["checks"] },
     "model-missing": { code: "AC_MODEL_ADOPTION_REQUIRED", message: "Architecture debt requires an adopted model.", fields: ["checks"] },
@@ -2340,6 +2376,7 @@ var init_failure = __esm(() => {
     "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" },
@@ -2348,7 +2385,7 @@ var init_failure = __esm(() => {
     "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" }
   };
   Object.assign(policies, {
     "developer-review-run-not-owned": { code: "AC_PRECONDITION_FAILED", message: "developer-review-run-not-owned", facts: { refusal: "reviewOwnershipRefusal" } },
@@ -2585,7 +2622,7 @@ var init_failure = __esm(() => {
   }
   FAILURE_POLICIES = Object.freeze(policies);
   catalogDefaults = Object.fromEntries(Object.entries(ERROR_CATALOG).map(([code, value]) => [code, Object.freeze({ severity: value.severity, retryable: value.retryable, action: value.action })]));
-  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] : [])]);
+  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] : [])]);
   localEnums = {
     reviewWorktreeRefusal: ["UNKNOWN", "HEAD_UNAVAILABLE", "HEAD_SHA_MISMATCH", "TREE_OID_MISMATCH", "WORKTREE_NOT_DETACHED", "WORKTREE_NOT_CLEAN"],
     reviewOwnershipRefusal: ["persisted-manifest-missing", "persisted-manifest-identity-mismatch", "run-id", "manifest-path", "lock-path", "persisted-manifest-mismatch", "persisted-lock-mismatch", "run-root-name", "worktree-temp-root", "codegraph-temporary-state-root", "run-root-not-a-directory", "run-root-owner-marker-missing", "run-root-owner-marker-mismatch", "worktree-temporary-root", "worktree-root", "worktree-source-root"],
@@ -2992,9 +3029,13 @@ function nativeAllowedNodeKinds(schemas) {
     throw new Error("canonical-node-kind-enum-unavailable");
   return [...kinds];
 }
-function nativeContextModelIssues(model, schemas) {
+function nativeContextModelIssues(model, schemas, recordPaths) {
   const issues = [];
-  const add = (entityId, field, invariant) => issues.push({ entityId, field, invariant });
+  const add = (record, field, invariant) => {
+    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;
   for (const [kind, records] of [["node", model.nodes], ["relation", model.relations], ["flow", model.flows]]) {
@@ -3013,14 +3054,14 @@ function nativeContextModelIssues(model, schemas) {
           continue;
         }
         if (typeof value === "number" && !Number.isFinite(value)) {
-          add(id, item.field, "non-json-number");
+          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");
+          add(record, item.field, "non-json-cycle");
           jsonInvalid = true;
           break;
         }
@@ -3028,7 +3069,7 @@ function nativeContextModelIssues(model, schemas) {
           continue;
         const prototype = Object.getPrototypeOf(value);
         if (Array.isArray(value) ? prototype !== Array.prototype : prototype !== Object.prototype) {
-          add(id, item.field, "non-json-prototype");
+          add(record, item.field, "non-json-prototype");
           jsonInvalid = true;
           break;
         }
@@ -3041,36 +3082,35 @@ function nativeContextModelIssues(model, schemas) {
         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);
+        add(record, issue.path, issue.message);
       if (ids.has(id))
-        add(id, "id", "duplicate-entity-id");
+        add(record, "id", "duplicate-entity-id");
       ids.add(id);
     }
   }
   if (issues.length > 0)
     return issues;
   for (const kind of ["nodes", "relations", "flows"]) {
-    const expected = new Set(model[kind].map((entity) => entity.id));
-    for (const id of expected)
+    const expected = new Map(model[kind].map((entity) => [entity.id, entity]));
+    for (const [id, entity] of expected)
       if (!Object.hasOwn(model.sourcePaths[kind], id))
-        add(id, `sourcePaths.${kind}`, "source-path-index-incomplete");
+        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");
+        add(expected.get(id) ?? id, `sourcePaths.${kind}`, "path-unsafe");
     }
   }
   const nodes = new Map(model.nodes.map((node) => [node.id, node]));
   const checked = new Set;
   for (const node of model.nodes) {
-    const id = node.id;
     const chain = new Set;
     let cursor = node;
     while (cursor) {
       const current = cursor.id;
       if (chain.has(current)) {
-        add(id, "parent", "parent-cycle");
+        add(node, "parent", "parent-cycle");
         break;
       }
       if (checked.has(current))
@@ -3080,7 +3120,7 @@ function nativeContextModelIssues(model, schemas) {
         break;
       const parent = nodes.get(cursor.parent);
       if (!parent) {
-        add(current, "parent", "parent-node-missing");
+        add(cursor, "parent", "parent-node-missing");
         break;
       }
       cursor = parent;
@@ -3093,17 +3133,17 @@ function nativeContextModelIssues(model, schemas) {
     const source = node.source;
     for (const path of [...source?.include ?? [], ...source?.exclude ?? []])
       if (!isNativeContextPath(path))
-        add(node.id, "source", "path-unsafe");
+        add(node, "source", "path-unsafe");
     for (const entry of source?.entrypoints ?? []) {
       if (!isNativeContextPath(entry.path))
-        add(node.id, "source.entrypoints.path", "path-unsafe");
+        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, "source.entrypoints.symbols.sinks.path", "path-unsafe");
+            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, "source.entrypoints.symbols.sinks.id", "selector-ambiguous");
+            add(node, "source.entrypoints.symbols.sinks.id", "selector-ambiguous");
           selectors.add(selector);
         }
       }
@@ -3112,43 +3152,42 @@ function nativeContextModelIssues(model, schemas) {
   for (const relation of model.relations) {
     for (const field of ["source", "target", "via"])
       if (relation[field] !== undefined && !nodes.has(relation[field]))
-        add(relation.id, field, "relation-node-missing");
+        add(relation, field, "relation-node-missing");
   }
   for (const flow of model.flows) {
-    const id = flow.id;
     if (nodes.get(flow.capabilityId)?.kind !== "capability")
-      add(id, "capabilityId", "flow-capability-missing");
+      add(flow, "capabilityId", "flow-capability-missing");
     if (flow.applicability !== "required")
       continue;
     const participants = flow.participants;
     const participantIds = new Set;
     for (const participant of participants) {
       if (participantIds.has(participant.id))
-        add(id, "participants.id", "participant-id-ambiguous");
+        add(flow, "participants.id", "participant-id-ambiguous");
       participantIds.add(participant.id);
       if (!nodes.has(participant.nodeId))
-        add(id, "participants.nodeId", "participant-node-missing");
+        add(flow, "participants.nodeId", "participant-node-missing");
     }
     const definitions = new Map;
     const outcomes = flow.outcomes;
     const outcomeIds = new Set;
     for (const outcome of outcomes) {
       if (outcomeIds.has(outcome.id))
-        add(id, "outcomes.id", "outcome-id-ambiguous");
+        add(flow, "outcomes.id", "outcome-id-ambiguous");
       outcomeIds.add(outcome.id);
       if (!participantIds.has(outcome.terminal.participant))
-        add(id, "outcomes.terminal", "terminal-participant-missing");
+        add(flow, "outcomes.terminal", "terminal-participant-missing");
     }
     for (const step of [...flow.steps, ...outcomes.flatMap((outcome) => outcome.steps)]) {
       if (!participantIds.has(step.from) || !participantIds.has(step.to))
-        add(id, "steps", "step-participant-missing");
+        add(flow, "steps", "step-participant-missing");
       const definition = canonicalize(step);
       if (definitions.has(step.id) && definitions.get(step.id) !== definition)
-        add(id, "steps.id", "step-definition-ambiguous");
+        add(flow, "steps.id", "step-definition-ambiguous");
       definitions.set(step.id, definition);
       const selector = step.evidence;
       if (!selectors.has(JSON.stringify([selector.entrypointId, selector.sourceSymbol, selector.sinkId])))
-        add(id, "steps.evidence", "selector-missing");
+        add(flow, "steps.evidence", "selector-missing");
     }
   }
   return issues;
@@ -3828,7 +3867,7 @@ function compareVersionTriples(left, right) {
   }
   return 0;
 }
-var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.8.0", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.3", ARCHCONTEXT_NODE_RANGE = ">=22.22 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v2", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
+var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.8.1", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.3", ARCHCONTEXT_NODE_RANGE = ">=22.22 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v2", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
 
 // packages/contracts/src/refactor.ts
 function refactorNamespaceIssues(value, label = "product.id") {
@@ -15748,10 +15787,10 @@ function sourceIncludeAnchors(patterns) {
 init_src();
 
 // packages/core/architecture-domain/src/index.ts
-init_src();
 import { createHash as createHash2 } from "node:crypto";
 import { readFileSync, realpathSync, statSync } from "node:fs";
 import { resolve } from "node:path";
+init_src();
 var LANDSCAPE_FILE = ".archcontext/landscape.yaml";
 var ADAPTER_PROTECTED_NATIVE_FIELDS = ["evidence", "verification", "constraint", "intervention"];
 var DEFAULT_IGNORES = new Set([
@@ -15980,7 +16019,7 @@ function parseJsonOrStableYaml(body, path) {
   if (!trimmed)
     throw new Error(`${path}: empty model file`);
   if (trimmed.startsWith("{") || trimmed.startsWith("["))
-    return checkedJsonDecode(trimmed, path, "json-document");
+    return checkedJsonOrFlowYaml(trimmed, path, "json-document");
   return new StableYamlParser(body, path).parse();
 }
 var ADR_FILE_PATH = /^docs\/adr\/ADR-\d{4}-.+\.md$/;
@@ -16361,7 +16400,7 @@ function parseScalar(value, path) {
   if (/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(value))
     return Number(value);
   if (/^["[{]/.test(value))
-    return checkedJsonDecode(value, path, "json-scalar");
+    return checkedJsonOrFlowYaml(value, path, "json-scalar");
   return value;
 }
 
@@ -16379,6 +16418,54 @@ class DuplicateModelKeyError extends Error {
     this.name = "DuplicateModelKeyError";
   }
 }
+function checkedJsonOrFlowYaml(source, path, branch) {
+  try {
+    return checkedJsonDecode(source, path, branch);
+  } catch (error) {
+    if (!(error instanceof SyntaxError) || !(source.startsWith("{") || source.startsWith("[")))
+      throw error;
+  }
+  return checkedFlowYamlDecode(source, path);
+}
+function checkedFlowYamlDecode(source, path) {
+  const document = $parseDocument(source, { version: "1.2", schema: "core", uniqueKeys: false, prettyErrors: false });
+  const invalid = (reason) => {
+    throw new SyntaxError(`${path}: invalid YAML flow collection (${reason})`);
+  };
+  if (document.errors.length || document.warnings.length)
+    invalid("parse error or warning");
+  if (!$isMap(document.contents) && !$isSeq(document.contents) || !document.contents.flow)
+    invalid("expected flow collection");
+  const decode = (node) => {
+    if (node === null)
+      return null;
+    if (!$isScalar(node) && !$isMap(node) && !$isSeq(node))
+      return invalid("unsupported node or alias");
+    if (node.anchor || node.tag)
+      return invalid("anchor or explicit tag");
+    if ($isScalar(node)) {
+      const value = node.value;
+      if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+      if (typeof value === "number" && Number.isFinite(value))
+        return value;
+      return invalid("non-JSON scalar");
+    }
+    if ($isSeq(node))
+      return node.items.map(decode);
+    const keys = new Set;
+    return Object.fromEntries(node.items.map((pair) => {
+      if (!$isScalar(pair.key))
+        return invalid("non-scalar key");
+      const key = String(decode(pair.key));
+      if (keys.has(key))
+        throw new DuplicateModelKeyError(path, "yaml-flow", key, pair.key.range[0]);
+      keys.add(key);
+      return [key, decode(pair.value)];
+    }));
+  };
+  return decode(document.contents);
+}
 function checkedJsonDecode(source, path, branch) {
   let offset = 0;
   const whitespace = () => {
@@ -16968,6 +17055,12 @@ function renderAdrReferenceUpdate(body, references) {
   return rendered;
 }
 // packages/core/changeset-engine/src/index.ts
+function changeSetBaseModelBlockingErrors(result, draft) {
+  const repairedPaths = new Set(draft.operations.filter((operation) => operation.op === "update_entity_fields" || operation.op === "delete_entity").map((operation) => operation.path));
+  const repairedErrors = new Set((result.nodeSchemaErrors ?? []).filter((issue) => repairedPaths.has(issue.path)).map((issue) => issue.error));
+  return baseModelBlockingErrors(result).filter((error) => !repairedErrors.has(error));
+}
+
 class ChangeSetEngine {
   deps;
   states = new Map;
@@ -17190,10 +17283,16 @@ class ChangeSetEngine {
   }
   async validateModel(root, draft, deps, phase) {
     const result = await deps.modelStore.validateModel({ root, repositoryId: draft.reason.taskSessionId, headSha: draft.base.headSha });
-    const blocked = phase === "before" ? baseModelBlockingErrors(result).length > 0 : !result.valid;
+    const errors = phase === "before" ? changeSetBaseModelBlockingErrors(result, draft) : result.errors;
+    const blocked = phase === "before" ? errors.length > 0 : !result.valid;
     if (blocked) {
-      const errors = phase === "before" ? baseModelBlockingErrors(result) : result.errors;
-      throw new Error(`ChangeSet model validation failed ${phase} apply: ${errors.join("; ") || "unknown validation error"}`);
+      const path = errors[0]?.match(/^(\.archcontext\/.+?): /)?.[1];
+      const error = new FailureError("AC_SCHEMA_INVALID", "native-context-model-invalid", {
+        invariant: `model-validation-${phase}-apply`,
+        ...path ? { path } : {}
+      });
+      error.message = `ChangeSet model validation failed ${phase} apply: ${errors.join("; ") || "unknown validation error"}`;
+      throw error;
     }
   }
   requireDeps() {
@@ -22897,9 +22996,6 @@ function isGitWorktreeError(error) {
   return error instanceof Error && /git|Command failed/.test(error.message);
 }
 
-// packages/local-runtime/runtime-daemon/src/producer-failure.ts
-init_src();
-
 // packages/local-runtime/egress-admission/src/index.ts
 var LOCAL_EGRESS_MODE_ENV2 = "ARCHCONTEXT_EGRESS_MODE";
 var LOCAL_EGRESS_CHANNELS2 = ["context7", "agent-audit", "github-issue-publishing", "npm-update-check", "codegraph-telemetry"];
@@ -22931,6 +23027,7 @@ function withLocalEgress2(channel, operation, env = process.env) {
 }
 
 // packages/local-runtime/codegraph-adapter/src/index.ts
+init_src();
 import { execFileSync as execFileSync2 } from "node:child_process";
 import { createHash as createHash5 } from "node:crypto";
 import { accessSync, closeSync as closeSync3, constants as fsConstants2, existsSync as existsSync6, openSync as openSync3, readFileSync as readFileSync7, readSync, realpathSync as realpathSync3, statSync as statSync3 } from "node:fs";
@@ -23932,10 +24029,15 @@ class CodeGraphCliProvider {
   }
   async indexAll(workspaceRoot) {
     this.workspaceRoot = workspaceRoot;
-    if (!existsSync6(join3(workspaceRoot, ".codegraph"))) {
-      throw new Error(`CodeGraph index missing at ${workspaceRoot}; run codegraph init before using archctxd`);
-    }
+    this.assertCanSync(workspaceRoot);
     this.run(["sync", workspaceRoot]);
+    this.assertReady(workspaceRoot);
+  }
+  assertReady(workspaceRoot) {
+    assertRepositoryCodeFactsReady(workspaceRoot, this.binary === DEFAULT_CODEGRAPH_BINARY ? {} : { binary: this.binary });
+  }
+  assertCanSync(workspaceRoot) {
+    this.assertReady(workspaceRoot);
   }
   async buildContext(task, options) {
     const query = scopedTaskQuery(task, options.changedPaths ?? []);
@@ -23998,7 +24100,7 @@ class CodeGraphCliProvider {
   }
   run(args) {
     disableCodeGraphTelemetryByDefault();
-    const invocation = codeGraphCliInvocation(this.binary, this.workspaceRoot);
+    const invocation = this.binary === DEFAULT_CODEGRAPH_BINARY ? packagedCodeGraphCliInvocation() : codeGraphCliInvocation(this.binary, this.workspaceRoot);
     try {
       return execFileSync2(invocation.command, [...invocation.argsPrefix, ...args], {
         cwd: this.workspaceRoot,
@@ -24129,8 +24231,14 @@ class CodeGraphAdapter {
     this.provider = provider;
     disableCodeGraphTelemetryByDefault();
   }
+  assertCanSync(workspaceRoot) {
+    this.assertCompatible();
+    this.provider.assertCanSync?.(workspaceRoot);
+  }
   async ensureReady(workspace) {
     this.assertCompatible();
+    if (this.#snapshot)
+      this.provider.assertReady?.(workspace.root);
     this.#snapshot ??= await this.sync({ workspace });
     return this.#snapshot;
   }
@@ -24594,7 +24702,7 @@ function readProjectionHeadSha(root) {
 function projectionCodeGraphStatusIssues(status, root, phase) {
   const issue = (code, text) => ({
     code,
-    message: `CodeGraph ${phase} ${text}`
+    message: phase === "repository" ? CODE_FACTS_ISSUE_MESSAGES[code] : `CodeGraph ${phase} ${text}`
   });
   if (!status.initialized)
     return [issue("not-initialized", "status is not initialized")];
@@ -24703,7 +24811,7 @@ function inspectRepositoryCodeFacts(root, options = {}) {
       message: (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim().slice(0, 400)
     };
   }
-  const versionIssues = codeGraphVersion === REQUIRED_CODEGRAPH_VERSION ? [] : [{ code: "version-mismatch", message: `CodeGraph ${REQUIRED_CODEGRAPH_VERSION} required, got actual binary ${codeGraphVersion || "unknown"}` }];
+  const versionIssues = codeGraphVersion === REQUIRED_CODEGRAPH_VERSION ? [] : [{ code: "version-mismatch", message: CODE_FACTS_ISSUE_MESSAGES["version-mismatch"] }];
   if (!indexPresent) {
     return { schemaVersion, state: "index-missing", indexPresent: false, requiredVersion: REQUIRED_CODEGRAPH_VERSION, codeGraphVersion, issues: versionIssues };
   }
@@ -24733,12 +24841,25 @@ function inspectRepositoryCodeFacts(root, options = {}) {
       current: status.index?.currentExtractionVersion ?? null
     },
     indexState: status.index?.state ?? null,
-    reindexRecommended: status.index?.reindexRecommended ?? null,
+    reindexRecommended: issues.some((issue) => issue.code !== "pending-source-changes"),
     pendingRefs: status.index?.pendingRefs ?? null,
     pendingChanges: pending ? { added: pending.added, modified: pending.modified, removed: pending.removed } : null,
     issues
   };
 }
+function assertRepositoryCodeFactsReady(root, options = {}) {
+  const facts = inspectRepositoryCodeFacts(root, options);
+  if (facts.state === "index-missing")
+    throw new ProjectionCodeFactsUnavailableError("index-missing");
+  if (facts.state === "unavailable")
+    throw new FailureError("AC_CODE_FACTS_UNAVAILABLE", "code-facts-unavailable", {}, { action: "inspect-diagnostics", retryable: false });
+  if (facts.state === "not-ready") {
+    if (facts.issues.every((issue) => issue.code === "pending-source-changes"))
+      return;
+    const action = facts.codeGraphVersion !== REQUIRED_CODEGRAPH_VERSION ? "install-compatible-codegraph" : "codegraph-index";
+    throw new FailureError("AC_CODE_FACTS_NOT_READY", "code-facts-not-ready", { issues: facts.issues }, { action });
+  }
+}
 function codeGraphIndexAvailable(workspaceRoot) {
   return existsSync6(join3(workspaceRoot, ".codegraph"));
 }
@@ -25061,6 +25182,7 @@ function parseExploreSymbols(output, maxSymbols) {
 }
 
 // packages/local-runtime/runtime-daemon/src/producer-failure.ts
+init_src();
 function selectedProducerData(error, key) {
   const descriptor = Object.getOwnPropertyDescriptor(error, key);
   if (!descriptor || !("value" in descriptor))
@@ -26151,12 +26273,6 @@ function isPresent2(value) {
 init_src();
 import { existsSync as existsSync7, lstatSync as lstatSync5, mkdirSync as mkdirSync4, readdirSync as readdirSync4, readFileSync as readFileSync8, rmSync as rmSync4 } from "node:fs";
 import { dirname as dirname5, resolve as resolve11 } from "node:path";
-
-// packages/local-runtime/model-store-yaml/src/native-context.ts
-init_src();
-import { createHash as createHash6 } from "node:crypto";
-import { constants, closeSync as closeSync4, fstatSync as fstatSync2, lstatSync as lstatSync4, openSync as openSync4, readSync as readSync2, realpathSync as realpathSync4 } from "node:fs";
-import { join as join4, resolve as resolve10 } from "node:path";
 // schemas/repo/architecture-node.schema.json
 var architecture_node_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -26245,6 +26361,12 @@ var architecture_node_schema_default = {
     extensions: { type: "object", additionalProperties: true }
   }
 };
+
+// packages/local-runtime/model-store-yaml/src/native-context.ts
+init_src();
+import { createHash as createHash6 } from "node:crypto";
+import { constants, closeSync as closeSync4, fstatSync as fstatSync2, lstatSync as lstatSync4, openSync as openSync4, readSync as readSync2, realpathSync as realpathSync4 } from "node:fs";
+import { join as join4, resolve as resolve10 } from "node:path";
 // schemas/repo/architecture-relation.schema.json
 var architecture_relation_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -26751,6 +26873,7 @@ function capture(source, snapshot) {
   if (typeof budget !== "number" || !Number.isSafeInteger(budget) || budget <= 0)
     throw new NativeContextError("native-context-budget-invalid", { path: MANIFEST, field: "runtime.contextBudgetBytes" });
   const model = { nodes: [], relations: [], flows: [], sourcePaths: { nodes: {}, relations: {}, flows: {} } };
+  const recordPaths = new Map;
   for (const spec of specs)
     if (spec.role !== "manifest") {
       const value = record5(parseInput(source, spec.path));
@@ -26758,10 +26881,11 @@ function capture(source, snapshot) {
         throw new NativeContextError("native-context-model-invalid", { path: spec.path, invariant: "entity-object-required" });
       const kind = spec.role === "node" ? "nodes" : spec.role === "relation" ? "relations" : "flows";
       model[kind].push(value);
+      recordPaths.set(value, spec.path);
       if (typeof value.id === "string")
         model.sourcePaths[kind][value.id] = spec.path;
     }
-  const issues = nativeContextModelIssues(model, SCHEMAS);
+  const issues = nativeContextModelIssues(model, SCHEMAS, recordPaths);
   if (issues.length > 0)
     throw new NativeContextError(issues.some((issue) => issue.invariant === "path-unsafe") ? "native-context-path-unsafe" : "native-context-model-invalid", { issues: issues.slice(0, 32), omittedDiagnosticCount: Math.max(0, issues.length - 32) });
   for (const kind of MODEL_KINDS)
@@ -27100,6 +27224,7 @@ class YamlModelStore {
   }
   async validateModel(workspace) {
     const errors = [];
+    const nodeSchemaErrors = [];
     for (const required of [".archcontext/manifest.yaml", ".archcontext/product.yaml"]) {
       try {
         readFileSync8(resolve11(workspace.root, required), "utf8");
@@ -27109,11 +27234,25 @@ class YamlModelStore {
     }
     const files = listModelFiles(workspace.root);
     for (const file of files) {
+      if (file.path.startsWith(".archcontext/model/") && /\.ya?ml$/.test(file.path)) {
+        try {
+          const value = parseJsonOrStableYaml(file.body, file.path);
+          if (file.path.startsWith(".archcontext/model/nodes/")) {
+            const { issues } = validateJsonSchema(architecture_node_schema_default, value);
+            for (const issue of issues) {
+              const error = `${file.path}: ${issue.path}: ${issue.message}`;
+              errors.push(error);
+              nodeSchemaErrors.push({ path: file.path, error });
+            }
+            continue;
+          }
+        } catch (error) {
+          errors.push(`${file.path}: invalid model YAML: ${error instanceof Error ? error.message : String(error)}`);
+          continue;
+        }
+      }
       if (!file.schemaVersion.startsWith("archcontext."))
         errors.push(`${file.path}: missing schemaVersion`);
-      if (file.path.startsWith(".archcontext/model/nodes/") && file.schemaVersion !== "archcontext.node/v2") {
-        errors.push(`${file.path}: expected archcontext.node/v2, got ${file.schemaVersion || "missing"}`);
-      }
       if (file.path.startsWith(".archcontext/model/flows/") && file.schemaVersion !== "archcontext.flow/v1") {
         errors.push(`${file.path}: expected archcontext.flow/v1, got ${file.schemaVersion || "missing"}`);
       }
@@ -27129,6 +27268,7 @@ class YamlModelStore {
       valid: errors.length === 0,
       errors,
       ...referenceErrors.length > 0 ? { referenceErrors } : {},
+      ...nodeSchemaErrors.length > 0 ? { nodeSchemaErrors } : {},
       ...warnings.length > 0 ? { warnings } : {},
       modelDigest
     };
@@ -34042,7 +34182,7 @@ function readArchitectureDebtEvidence(root, input) {
     capabilityByNodeId
   } };
 }
-function runArchitectureDebtCommand(cwd, input = {}) {
+function runArchitectureDebtCommand(cwd, input = {}, codeFactsOptions = {}) {
   let root;
   try {
     root = findRepositoryRoot(cwd);
@@ -34050,6 +34190,8 @@ function runArchitectureDebtCommand(cwd, input = {}) {
     return failureEnvelope("debt", knownFailure("AC_REPO_NOT_FOUND", "git-worktree-required", { checks: ["ownership", "anchors"] }));
   }
   try {
+    if (codeGraphIndexAvailable(root))
+      assertRepositoryCodeFactsReady(root, codeFactsOptions);
     return okEnvelope("debt", readArchitectureDebt(root, input));
   } catch (error) {
     return selectedProducerFailureEnvelope("debt", error, "debt");
@@ -34596,10 +34738,10 @@ function assertAllowedArchContextPath2(root, relativePath, scope) {
 }
 
 // packages/core/architecture-domain/src/index.ts
-init_src();
 import { createHash as createHash9 } from "node:crypto";
 import { readFileSync as readFileSync14, realpathSync as realpathSync7, statSync as statSync4 } from "node:fs";
 import { resolve as resolve18 } from "node:path";
+init_src();
 var DEFAULT_IGNORES2 = new Set([
   ".git",
   ".codegraph",
@@ -34818,7 +34960,10 @@ var WINDOWS_CREATE_TIMEOUT_MS = 60000;
 var WINDOWS_READ_TIMEOUT_MS = 1e4;
 var REMOVE_HANDLE_RELEASE_MARGIN_MS = 2000;
 var REMOVE_RETRY_DELAY_MS = 25;
+var WINDOWS_CONTROL_FILE_PHASES = ["script", "input", "parsed", "opened", "verified", "done"];
+var WINDOWS_CONTROL_FILE_PHASE_MARKER = /^archctx-acl-phase:([a-z]+)\r?$/;
 var WINDOWS_CONTROL_FILE_SCRIPT = String.raw`
+[Console]::Error.WriteLine('archctx-acl-phase:script')
 $ErrorActionPreference = 'Stop'
 # A pwsh -> Node/Bun -> powershell.exe launch inherits incompatible PS7 module paths.
 $env:PSModulePath = "$PSHOME\Modules"
@@ -34840,7 +34985,10 @@ function Test-PrivateAcl($stream, $sid) {
     $rule.PropagationFlags -eq [System.Security.AccessControl.PropagationFlags]::None)
 }
 try {
-  $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+  $text = [Console]::In.ReadToEnd()
+  [Console]::Error.WriteLine('archctx-acl-phase:input')
+  $request = $text | ConvertFrom-Json
+  [Console]::Error.WriteLine('archctx-acl-phase:parsed')
   $sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
   if ($request.operation -eq 'create') {
     $acl = New-Object System.Security.AccessControl.FileSecurity
@@ -34850,18 +34998,24 @@ try {
     $acl.AddAccessRule($rule)
     $stream = New-Object System.IO.FileStream($request.path, [System.IO.FileMode]::CreateNew, [System.Security.AccessControl.FileSystemRights]::FullControl, [System.IO.FileShare]::None, 4096, [System.IO.FileOptions]::None, $acl)
     $created = $true
+    [Console]::Error.WriteLine('archctx-acl-phase:opened')
     if (-not (Test-PrivateAcl $stream $sid)) { throw 'private ACL readback failed' }
+    [Console]::Error.WriteLine('archctx-acl-phase:verified')
     $bytes = [System.Text.Encoding]::UTF8.GetBytes([string]$request.body)
     $stream.Write($bytes, 0, $bytes.Length)
     $stream.Flush($true)
+    [Console]::Error.WriteLine('archctx-acl-phase:done')
     $result = @{ ok = $true }
   } elseif ($request.operation -eq 'read') {
     # Deny concurrent write/delete, validate the opened file, then read that same handle.
     $stream = New-Object System.IO.FileStream($request.path, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileShare]::Read)
+    [Console]::Error.WriteLine('archctx-acl-phase:opened')
     if (-not (Test-PrivateAcl $stream $sid)) { throw 'private ACL readback failed' }
+    [Console]::Error.WriteLine('archctx-acl-phase:verified')
     if ($stream.Length -gt 1048576) { throw 'control file exceeds read budget' }
     $reader = New-Object System.IO.StreamReader($stream, [System.Text.Encoding]::UTF8, $true, 4096, $true)
     try { $body = $reader.ReadToEnd() } finally { $reader.Dispose() }
+    [Console]::Error.WriteLine('archctx-acl-phase:done')
     $result = @{ ok = $true; body = $body }
   } else { throw 'unsupported operation' }
   [Console]::Out.Write(($result | ConvertTo-Json -Compress))
@@ -34903,8 +35057,9 @@ function windowsControlFile(operation, path, body) {
     const code = ["ETIMEDOUT", "ENOENT", "EACCES", "EPERM", "ENOBUFS"].includes(String(failure?.code)) ? String(failure?.code) : "UNKNOWN";
     const signal = ["SIGTERM", "SIGKILL", "SIGABRT", "SIGINT"].includes(String(failure?.signal)) ? String(failure?.signal) : null;
     const status = typeof failure?.status === "number" && Number.isInteger(failure.status) ? failure.status : null;
+    const phase = lastWindowsControlFilePhase(failure?.stderr);
     const elapsedMs = Math.round(performance.now() - startedAt);
-    throw new Error(`Windows native ACL operation failed: ${JSON.stringify({ operation, code, status, signal, elapsedMs })}`);
+    throw new Error(`Windows native ACL operation failed: ${JSON.stringify({ operation, code, status, signal, phase, elapsedMs })}`);
   }
   const result = JSON.parse(output);
   if (!result || typeof result !== "object" || !("ok" in result))
@@ -34919,6 +35074,18 @@ function windowsControlFile(operation, path, body) {
     return result.body;
   }
 }
+function lastWindowsControlFilePhase(stderr) {
+  let phase = "none";
+  if (typeof stderr !== "string")
+    return phase;
+  for (const line of stderr.split(`
+`)) {
+    const name = WINDOWS_CONTROL_FILE_PHASE_MARKER.exec(line)?.[1];
+    if (name && WINDOWS_CONTROL_FILE_PHASES.includes(name))
+      phase = name;
+  }
+  return phase;
+}
 function createPrivateControlFile(path, body) {
   if (process.platform === "win32") {
     windowsControlFile("create", path, body);
@@ -37988,7 +38155,7 @@ function readArchitectureDebtEvidence2(root, input) {
     capabilityByNodeId
   } };
 }
-function runArchitectureDebtCommand2(cwd, input = {}) {
+function runArchitectureDebtCommand2(cwd, input = {}, codeFactsOptions = {}) {
   let root;
   try {
     root = findRepositoryRoot(cwd);
@@ -37996,6 +38163,8 @@ function runArchitectureDebtCommand2(cwd, input = {}) {
     return failureEnvelope("debt", knownFailure("AC_REPO_NOT_FOUND", "git-worktree-required", { checks: ["ownership", "anchors"] }));
   }
   try {
+    if (codeGraphIndexAvailable(root))
+      assertRepositoryCodeFactsReady(root, codeFactsOptions);
     return okEnvelope("debt", readArchitectureDebt2(root, input));
   } catch (error) {
     return selectedProducerFailureEnvelope("debt", error, "debt");
@@ -42988,7 +43157,13 @@ class PracticeCheckpointService {
   }
   async prepareUnchecked(root, task, maxBytes = 12288, maxItems = 12, taskSessionId = "task_runtime") {
     this.assertRunning();
+    if (this.codeFacts.assertCanSync) {
+      root = findRepositoryRoot(root);
+      this.codeFacts.assertCanSync(root);
+    }
     const session = await this.openSession(root);
+    if (this.codeFacts.assertCanSync)
+      await this.codeFacts.ensureReady(session.workspace);
     const result = await prepareTask({
       workspace: session.workspace,
       task,
@@ -56409,7 +56584,7 @@ class ChangeSetAuthorityService {
       if (draft.base.worktreeDigest !== current)
         throw new FailureError("AC_PRECONDITION_FAILED", "apply-worktree-changed", { expectedWorktreeDigest: draft.base.worktreeDigest, actualWorktreeDigest: current });
       const currentModel = await this.readModelStore.validateModel(session.workspace);
-      const baseErrors = baseModelBlockingErrors(currentModel);
+      const baseErrors = changeSetBaseModelBlockingErrors(currentModel, draft);
       if (baseErrors.length > 0) {
         throw new FailureError("AC_PRECONDITION_FAILED", "apply-model-invalid", { issueCount: baseErrors.length });
       }
@@ -57684,6 +57859,10 @@ class ArchctxDaemon {
   async completeTaskUnchecked(root, input) {
     this.assertRunning();
     assertNoCallerProvidedAttestationFields(input, "complete-task");
+    if (this.codeFacts.assertCanSync) {
+      root = findRepositoryRoot(root);
+      this.codeFacts.assertCanSync(root);
+    }
     const session = await this.openSession(root);
     let currentHeadSha = input.headSha;
     try {
@@ -58554,6 +58733,7 @@ function completeTaskProjectionFreshness(root) {
 }
 
 // packages/local-runtime/codegraph-adapter/src/index.ts
+init_src();
 import { execFileSync as execFileSync11 } from "node:child_process";
 import { accessSync as accessSync2, closeSync as closeSync11, constants as fsConstants4, existsSync as existsSync33, openSync as openSync11, readFileSync as readFileSync30, readSync as readSync5, realpathSync as realpathSync12, statSync as statSync10 } from "node:fs";
 import { createRequire as createRequire5 } from "node:module";
@@ -58662,7 +58842,7 @@ function readProjectionCodeGraphStatus2(invocation, root, timeout, envOverrides)
 function projectionCodeGraphStatusIssues2(status, root, phase) {
   const issue = (code, text) => ({
     code,
-    message: `CodeGraph ${phase} ${text}`
+    message: phase === "repository" ? CODE_FACTS_ISSUE_MESSAGES[code] : `CodeGraph ${phase} ${text}`
   });
   if (!status.initialized)
     return [issue("not-initialized", "status is not initialized")];
@@ -58738,7 +58918,7 @@ function inspectRepositoryCodeFacts2(root, options = {}) {
       message: (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim().slice(0, 400)
     };
   }
-  const versionIssues = codeGraphVersion === REQUIRED_CODEGRAPH_VERSION2 ? [] : [{ code: "version-mismatch", message: `CodeGraph ${REQUIRED_CODEGRAPH_VERSION2} required, got actual binary ${codeGraphVersion || "unknown"}` }];
+  const versionIssues = codeGraphVersion === REQUIRED_CODEGRAPH_VERSION2 ? [] : [{ code: "version-mismatch", message: CODE_FACTS_ISSUE_MESSAGES["version-mismatch"] }];
   if (!indexPresent) {
     return { schemaVersion, state: "index-missing", indexPresent: false, requiredVersion: REQUIRED_CODEGRAPH_VERSION2, codeGraphVersion, issues: versionIssues };
   }
@@ -58768,7 +58948,7 @@ function inspectRepositoryCodeFacts2(root, options = {}) {
       current: status.index?.currentExtractionVersion ?? null
     },
     indexState: status.index?.state ?? null,
-    reindexRecommended: status.index?.reindexRecommended ?? null,
+    reindexRecommended: issues.some((issue) => issue.code !== "pending-source-changes"),
     pendingRefs: status.index?.pendingRefs ?? null,
     pendingChanges: pending ? { added: pending.added, modified: pending.modified, removed: pending.removed } : null,
     issues
@@ -59571,6 +59751,95 @@ function isExternalDocumentationResourceUri(uri) {
 function architectureBookResourceInput(uri) {
   return ARCHITECTURE_BOOK_RESOURCES.find((resource) => resource.uri === uri)?.input;
 }
+// schemas/repo/architecture-node.schema.json
+var architecture_node_schema_default2 = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://archctx.repoharness.com/schemas/repo/architecture-node.schema.json",
+  title: "ArchitectureNode",
+  type: "object",
+  additionalProperties: false,
+  required: ["schemaVersion", "id", "kind", "name", "status", "summary"],
+  properties: {
+    schemaVersion: { const: "archcontext.node/v2" },
+    id: { type: "string", pattern: "^([a-z][a-z0-9]*(\\.[a-z0-9][a-z0-9-]*)*::)?[a-z][a-z0-9]*(\\.[a-z0-9][a-z0-9-]*)+$" },
+    kind: {
+      type: "string",
+      enum: ["capability", "module", "component", "interface", "event", "datastore", "external-system", "deployment"]
+    },
+    name: { type: "string" },
+    status: { type: "string", enum: ["active", "planned", "deprecated", "removed"] },
+    parent: { type: "string", pattern: "^([a-z][a-z0-9]*(\\.[a-z0-9][a-z0-9-]*)*::)?[a-z][a-z0-9]*(\\.[a-z0-9][a-z0-9-]*)+$" },
+    summary: { type: "string" },
+    responsibilities: { type: "array", items: { type: "string" }, minItems: 1 },
+    source: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        include: { type: "array", items: { type: "string" } },
+        exclude: { type: "array", items: { type: "string" } },
+        entrypoints: {
+          type: "array",
+          items: {
+            type: "object",
+            additionalProperties: false,
+            required: ["id", "path", "symbols"],
+            properties: {
+              id: { type: "string", pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9][a-z0-9-]*)+$" },
+              path: { type: "string", minLength: 1 },
+              symbols: {
+                type: "array",
+                minItems: 1,
+                items: {
+                  type: "object",
+                  additionalProperties: false,
+                  required: ["name", "sinks"],
+                  properties: {
+                    name: { type: "string", minLength: 1 },
+                    sinks: {
+                      type: "array",
+                      minItems: 1,
+                      items: {
+                        type: "object",
+                        additionalProperties: false,
+                        required: ["id", "path", "symbol"],
+                        properties: {
+                          id: { type: "string", pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9][a-z0-9-]*)+$" },
+                          path: { type: "string", minLength: 1 },
+                          symbol: { type: "string", minLength: 1 }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    ownership: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        lifecycle: { type: "array", items: { type: "string" } },
+        data: { type: "array", items: { type: "string" } }
+      }
+    },
+    interfaces: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        provides: { type: "array", items: { type: "string" } },
+        consumes: { type: "array", items: { type: "string" } }
+      }
+    },
+    criticality: { type: "string", enum: ["low", "medium", "high", "critical"] },
+    riskDomains: { type: "array", items: { type: "string" } },
+    notes: { type: "array", items: { type: "string" } },
+    extensions: { type: "object", additionalProperties: true }
+  }
+};
+
 // packages/surfaces/cli/src/main.ts
 var [, , command, ...args] = process.argv;
 var CLI_ENTRY = fileURLToPath2(import.meta.url);
@@ -60244,7 +60513,7 @@ async function runCliUnchecked(command = "help", args = [], cwd, deps = {}) {
           const read = await readResolvePathsFrom(args, cwd, deps);
           if ("problem" in read)
             return errorEnvelope("resolve", "AC_SCHEMA_INVALID", read.problem);
-          const model = loadNativeModelFromArchContext(cwd);
+          const model = loadResolveModel(cwd);
           const outcomes = resolveArchitectureOwnersForPaths(model.nodes, read.paths);
           return okEnvelope("resolve", { results: outcomes.map((outcome, index) => resolveResultData(read.paths[index], outcome)) });
         }
@@ -60254,7 +60523,7 @@ async function runCliUnchecked(command = "help", args = [], cwd, deps = {}) {
         if (!isRepoRelativePosixPath(path)) {
           return errorEnvelope("resolve", "AC_SCHEMA_INVALID", "resolve --path must be a repository-relative POSIX path");
         }
-        const model = loadNativeModelFromArchContext(cwd);
+        const model = loadResolveModel(cwd);
         return okEnvelope("resolve", resolveResultData(path, resolveArchitectureOwnerForPath(model.nodes, path)));
       }
       case "help":
@@ -63267,6 +63536,37 @@ var CLI_RESOLVE_HELP = {
   result: "Each result carries path, matched, ambiguous and owningCapabilityId. A match adds stableId, kind, name, source and extensions of the most specific node. An ambiguous result adds candidates. owningCapabilityId is the nearest kind: capability node on the owner's parent chain (the owner itself when it is a capability), or null. For an ambiguous result it is set only when all candidates share one owning capability.",
   exitCodes: "--path: 0 matched, 1 no match or error, 2 ambiguous. --paths-from: 0 when no path is ambiguous (unowned paths included), 2 when any path is ambiguous, 1 on error."
 };
+function loadResolveModel(cwd) {
+  if (!existsSync34(join26(cwd, ".archcontext/manifest.yaml"))) {
+    throw new NativeContextError("native-context-model-missing", { path: ".archcontext/manifest.yaml" });
+  }
+  let model;
+  try {
+    model = loadNativeModelFromArchContext(cwd);
+  } catch (error) {
+    const cause = error;
+    if (typeof cause?.code === "string") {
+      throw new NativeContextError("native-context-input-unreadable", {
+        category: "open-or-read",
+        ...typeof cause.path === "string" ? { path: cause.path } : {}
+      });
+    }
+    throw new NativeContextError("native-context-model-invalid", { invariant: "model-parse" });
+  }
+  if (model.nodes.length === 0) {
+    throw new NativeContextError("native-context-model-missing", { category: "no-native-nodes" });
+  }
+  for (const node of model.nodes) {
+    const { issues } = validateJsonSchema(architecture_node_schema_default2, node);
+    if (issues.length > 0) {
+      throw new NativeContextError("native-context-model-invalid", {
+        issues: issues.slice(0, 32).map((issue) => ({ entityId: typeof node.id === "string" ? node.id : "(undeclared)", field: issue.path, invariant: issue.message })),
+        omittedDiagnosticCount: Math.max(0, issues.length - 32)
+      });
+    }
+  }
+  return model;
+}
 function resolveResultData(path, outcome) {
   if (outcome.status === "matched") {
     const node = outcome.node;
@@ -63579,6 +63879,8 @@ if (__require.main == __require.module) {
 `);
     if (result.ok === false)
       process.exitCode = 1;
+    if (command === "validate" && result.ok && result.data?.valid === false)
+      process.exitCode = 1;
     if (command === "resolve")
       process.exitCode = resolveCommandExitCode(result);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Local architecture context CLI for agentic coding workflows.",
   "private": false,
   "type": "module",

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."
+    }
+  }
+}