archctx-contracts 0.6.3 → 0.7.1

package/src/docs-anchors.ts

@@ -0,0 +1,126 @@
+/**
+ * `archctx docs anchors` (#298): a read-only signal for stale citations in human-owned text. It
+ * reads the human-owned regions of module documents and node prose (`summary`,
+ * `responsibilities`), and resolves each citation against the Git-visible tree and CodeGraph. It is
+ * a signal, not a gate: findings never change `ok`, freshness or the projection result.
+ */
+export const DOCS_ANCHORS_REPORT_SCHEMA_VERSION = "archcontext.docs-anchors/v1" as const;
+
+export const DOCS_ANCHOR_FINDING_KINDS = ["line-moved", "line-out-of-range", "missing-path", "missing-symbol"] as const;
+export type DocsAnchorFindingKind = (typeof DOCS_ANCHOR_FINDING_KINDS)[number];
+
+/** Why a citation was found but one of its checks could not run. */
+export const DOCS_ANCHOR_UNCHECKED_REASON_CODES = ["codegraph-unavailable", "language-unsupported", "path-ambiguous"] as const;
+export type DocsAnchorUncheckedReasonCode = (typeof DOCS_ANCHOR_UNCHECKED_REASON_CODES)[number];
+
+export const DOCS_ANCHOR_CODEGRAPH_UNAVAILABLE_REASON_CODES = ["index-missing", "index-open-failed"] as const;
+export type DocsAnchorCodeGraphUnavailableReasonCode = (typeof DOCS_ANCHOR_CODEGRAPH_UNAVAILABLE_REASON_CODES)[number];
+
+/** Where the citation is written: a human-owned document line, or a field of the node. */
+export type DocsAnchorOriginV1 =
+  | { kind: "document"; path: string; line: number }
+  | { kind: "node-summary" }
+  | { kind: "node-responsibility"; index: number };
+
+export interface DocsAnchorCitationV1 {
+  /** The inline code span as written, without the backticks. */
+  text: string;
+  /** The cited path as written. */
+  path?: string;
+  /** The Git-visible file or directory the path resolved to, when it differs from `path`. */
+  resolvedPath?: string;
+  line?: number;
+  endLine?: number;
+  symbol?: string;
+}
+
+export interface DocsAnchorFindingV1 {
+  kind: DocsAnchorFindingKind;
+  origin: DocsAnchorOriginV1;
+  citation: DocsAnchorCitationV1;
+  /** `line-out-of-range` only: the current line count of the cited file. */
+  lineCount?: number;
+  /** `line-moved` only: the current start lines of the cited symbol, sorted. */
+  currentLines?: number[];
+}
+
+export interface DocsAnchorUncheckedV1 {
+  reasonCode: DocsAnchorUncheckedReasonCode;
+  origin: DocsAnchorOriginV1;
+  citation: DocsAnchorCitationV1;
+}
+
+export interface DocsAnchorsNodeV1 {
+  nodeId: string;
+  /** The node's module document, when the active layout has one and it exists. */
+  documentPath?: string;
+  citationCount: number;
+  findings: DocsAnchorFindingV1[];
+  unchecked: DocsAnchorUncheckedV1[];
+}
+
+export type DocsAnchorsCodeGraphV1 =
+  | { availability: "ready" }
+  | { availability: "unavailable"; reasonCode: DocsAnchorCodeGraphUnavailableReasonCode };
+
+export interface DocsAnchorsReportV1 {
+  schemaVersion: typeof DOCS_ANCHORS_REPORT_SCHEMA_VERSION;
+  profile: "default" | "repo-harness/v1";
+  codeGraph: DocsAnchorsCodeGraphV1;
+  summary: {
+    /** Model nodes whose prose and module document were read. */
+    nodes: number;
+    /** Module documents read. */
+    documents: number;
+    citations: number;
+    findings: number;
+    unchecked: number;
+    byKind: Record<DocsAnchorFindingKind, number>;
+  };
+  /** Nodes with at least one citation, sorted by `nodeId`. */
+  nodes: DocsAnchorsNodeV1[];
+}
+
+export function docsAnchorsReportIssues(report: DocsAnchorsReportV1): string[] {
+  const issues: string[] = [];
+  const ids = report.nodes.map((node) => node.nodeId);
+  const sorted = [...new Set(ids)].sort();
+  if (sorted.length !== ids.length || sorted.some((id, index) => id !== ids[index])) issues.push("nodes.nodeId must be sorted and unique");
+  const findings = report.nodes.flatMap((node) => node.findings);
+  const unchecked = report.nodes.flatMap((node) => node.unchecked);
+  if (report.summary.citations !== report.nodes.reduce((total, node) => total + node.citationCount, 0)) issues.push("summary.citations must equal the sum of nodes[].citationCount");
+  if (report.summary.findings !== findings.length) issues.push("summary.findings must equal the number of findings");
+  if (report.summary.unchecked !== unchecked.length) issues.push("summary.unchecked must equal the number of unchecked citations");
+  for (const kind of DOCS_ANCHOR_FINDING_KINDS) {
+    if (report.summary.byKind[kind] !== findings.filter((finding) => finding.kind === kind).length) issues.push(`summary.byKind.${kind} must equal the number of ${kind} findings`);
+  }
+  for (const [index, node] of report.nodes.entries()) {
+    if (node.citationCount === 0) issues.push(`nodes[${index}] must have at least one citation`);
+    for (const [findingIndex, finding] of node.findings.entries()) {
+      issues.push(...docsAnchorFindingIssues(finding, `nodes[${index}].findings[${findingIndex}]`));
+    }
+  }
+  if (report.codeGraph.availability === "ready" && unchecked.some((entry) => entry.reasonCode === "codegraph-unavailable")) {
+    issues.push("codegraph-unavailable is reported only when codeGraph.availability is unavailable");
+  }
+  return issues;
+}
+
+function docsAnchorFindingIssues(finding: DocsAnchorFindingV1, prefix: string): string[] {
+  const issues: string[] = [];
+  const { citation } = finding;
+  if (finding.kind === "missing-path" && citation.path === undefined) issues.push(`${prefix} missing-path must name citation.path`);
+  if (finding.kind === "missing-symbol" && citation.symbol === undefined) issues.push(`${prefix} missing-symbol must name citation.symbol`);
+  if (finding.kind === "line-out-of-range" && (citation.line === undefined || finding.lineCount === undefined)) {
+    issues.push(`${prefix} line-out-of-range must name citation.line and lineCount`);
+  }
+  if ((finding.lineCount !== undefined) !== (finding.kind === "line-out-of-range")) issues.push(`${prefix}.lineCount is present only on line-out-of-range`);
+  if (finding.kind === "line-moved") {
+    const lines = finding.currentLines ?? [];
+    if (citation.line === undefined || citation.symbol === undefined) issues.push(`${prefix} line-moved must name citation.line and citation.symbol`);
+    if (lines.length === 0 || lines.some((line, index) => index > 0 && line <= lines[index - 1]!)) issues.push(`${prefix}.currentLines must be non-empty, sorted and unique`);
+  } else if (finding.currentLines !== undefined) {
+    issues.push(`${prefix}.currentLines is present only on line-moved`);
+  }
+  return issues;
+}

package/src/index.ts

@@ -1,11 +1,14 @@
 export * from "./control-plane-routes";
 export * from "./architecture";
+export * from "./docs-anchors";
 export * from "./external-docs";
 export * from "./github-governance";
 export * from "./ledger";
+export * from "./ownership-dependencies";
 export * from "./ports";
 export * from "./practices";
 export * from "./projection";
+export * from "./projection-manifest";
 export * from "./product-version";
 export * from "./refactor";
 export * from "./schema";

package/src/ledger.ts

@@ -2,6 +2,7 @@ import type { ArchitectureMajorChangeReasonCode } from "./projection";
 import type {
   ArchitectureTargetDeltaV1,
   RefactorKillListEntryV1,
+  RefactorObservationEvidenceV1,
   RefactorObservationKind,
   RefactorScale,
   RefactorTargetOutcomeV1
@@ -30,16 +31,18 @@ export type ArchitectureLedgerMode = "yaml" | "dual" | "dual-compare" | "ledger-
 export type ArchitectureActorKind = "developer" | "daemon" | "hook" | "cli" | "mcp" | "subagent" | "migration" | "system";
 export type ArchitectureActorSource = "cli" | "mcp" | "manual" | "daemon" | "system" | "subagent";
 export type RecommendationCategory = (typeof RECOMMENDATION_CATEGORIES)[number];
-export type RecommendationStatus =
-  | "open"
-  | "acknowledged"
-  | "accepted"
-  | "rejected"
-  | "deferred"
-  | "waived"
-  | "resolved"
-  | "superseded"
-  | "expired";
+export const RECOMMENDATION_STATUSES = [
+  "open",
+  "acknowledged",
+  "accepted",
+  "rejected",
+  "deferred",
+  "waived",
+  "resolved",
+  "superseded",
+  "expired"
+] as const;
+export type RecommendationStatus = (typeof RECOMMENDATION_STATUSES)[number];
 export type ArchitectureEventSource =
   | "prepare_task"
   | "checkpoint"
@@ -695,12 +698,25 @@ export interface PracticeRecommendationPayloadV1 {
   baselineDigest: string | null;
 }
 
+/**
+ * Self-contained: `metrics`, `signalIds` and `evidence` are copied verbatim from the assessed
+ * `RefactorObservationV1`, so a reader never has to join a recorded record back to an in-memory
+ * assessment by kind and subject. None of them is part of the fingerprint.
+ *
+ * A record written by archctx 0.6.3 or earlier (before #262) has none of the three, and the ledger
+ * keeps it as written, so `recommendations show` and `list` can return it. A reader detects such a
+ * record by the absence of `evidence`. It does not validate against
+ * `schemas/runtime/recommendation-v3.schema.json`, which describes the record 0.7.0 writes.
+ */
 export interface StructuralObservationPayloadV1 {
   assessmentDigest: string;
   kind: RefactorObservationKind;
   affectedNodeIds: string[];
   baselineSnapshotDigest: string;
   derivedOutcomes: RefactorTargetOutcomeV1[];
+  metrics: Record<string, number | null>;
+  signalIds: string[];
+  evidence: RefactorObservationEvidenceV1;
 }
 
 export interface RefactorProposalPayloadV1 {

package/src/ownership-dependencies.ts

@@ -0,0 +1,129 @@
+import type { EvidenceCoverageLevelV2 } from "./ledger";
+
+// --- ChangeSet ownership delta (plan preview) ---
+//
+// `archctx plan` and `archcontext_plan_update` add `preview.ownershipDelta` when a planned
+// ChangeSet writes a node file. It compares file ownership before and after the planned model over
+// the files the HEAD tree carries, with the parent-chain rule `refactor scan` uses
+// (module-statistics `resolveOwnership`). It is read-only: nothing is written to compute it.
+
+export const CHANGESET_OWNERSHIP_DELTA_SCHEMA_VERSION = "archcontext.changeset-ownership-delta/v1" as const;
+/** Upper bound on the paths one ownership delta category lists. `count` always holds the full total. */
+export const CHANGESET_OWNERSHIP_DELTA_PATH_LIMIT = 50;
+
+export interface OwnershipDeltaSummaryV1 {
+  ownedFileCount: number;
+  /** Owned files whose claimants do not sit on one `parent` chain. */
+  multiplyOwnedFileCount: number;
+  /** Unclaimed files under a declared source root that no node excludes. */
+  unownedFileCount: number;
+}
+
+export interface OwnershipDeltaFileV1 {
+  path: string;
+  /** Owning node ids before the plan, sorted. More than one id means the claim is contested. */
+  before: string[];
+  /** Owning node ids after the plan, sorted. */
+  after: string[];
+}
+
+export interface OwnershipDeltaCategoryV1 {
+  /** Every file in this category. */
+  count: number;
+  /** The first `pathLimit` files, sorted by path. */
+  files: OwnershipDeltaFileV1[];
+  /** `count - files.length`. */
+  omittedCount: number;
+}
+
+export interface ChangeSetOwnershipDeltaComputedV1 {
+  schemaVersion: typeof CHANGESET_OWNERSHIP_DELTA_SCHEMA_VERSION;
+  status: "computed";
+  ownershipRule: "parent-chain";
+  fileUniverse: "head-tracked-files";
+  trackedFileCount: number;
+  /** Node ids whose `source.include`, `source.exclude` or `parent` differ, or that the plan creates or deletes. */
+  changedNodeIds: string[];
+  pathLimit: number;
+  before: OwnershipDeltaSummaryV1;
+  after: OwnershipDeltaSummaryV1;
+  /** Unowned before, owned by exactly one node after. */
+  becameOwned: OwnershipDeltaCategoryV1;
+  /** Not contested before, contested (multiply owned) after. */
+  becameContested: OwnershipDeltaCategoryV1;
+  /** Owned before, owned by a different node set after, and not newly contested. */
+  ownerChanged: OwnershipDeltaCategoryV1;
+  /** Owned before, unowned after. */
+  becameUnowned: OwnershipDeltaCategoryV1;
+}
+
+export interface ChangeSetOwnershipDeltaUnavailableV1 {
+  schemaVersion: typeof CHANGESET_OWNERSHIP_DELTA_SCHEMA_VERSION;
+  status: "unavailable";
+  /** Why no delta was computed, for example a planned node body that does not parse. */
+  reason: string;
+}
+
+export type ChangeSetOwnershipDeltaV1 = ChangeSetOwnershipDeltaComputedV1 | ChangeSetOwnershipDeltaUnavailableV1;
+
+// --- Capability dependency matrix (`archctx deps`) ---
+
+export const CAPABILITY_DEPENDENCIES_SCHEMA_VERSION = "archcontext.capability-dependencies/v1" as const;
+/** Default number of file-level edges `archctx deps` lists. `edges.count` always holds the full total. */
+export const CAPABILITY_DEPENDENCIES_EDGE_LIMIT = 200;
+/** The CodeGraph adapter has no bounded repository-wide call-edge read, so calls are not counted. */
+export const CAPABILITY_DEPENDENCIES_CALLS_UNAVAILABLE_REASON = "call-edges-not-exposed" as const;
+
+export interface CapabilityDependencyCellV1 {
+  /** Owning capability of the importing file. */
+  from: string;
+  /** Owning capability of the imported file. */
+  to: string;
+  /** Distinct file-to-file import edges from `from` into `to`. */
+  imports: number;
+  /** Always `null` in v1: call edges are not read (see `calls`). */
+  calls: null;
+}
+
+export interface CapabilityDependencyEdgeV1 {
+  fromPath: string;
+  toPath: string;
+  fromCapability: string;
+  toCapability: string;
+}
+
+export interface CapabilityDependenciesV1 {
+  schemaVersion: typeof CAPABILITY_DEPENDENCIES_SCHEMA_VERSION;
+  ownershipRule: "parent-chain";
+  /** `--from` / `--into` node ids, or `null`. A node matches a file when it or a descendant owns it. */
+  filter: { from: string | null; into: string | null };
+  /** Every `kind: capability` node id in the model, sorted. */
+  capabilities: string[];
+  /** Non-zero cells only, sorted by `from` then `to`. A cell with `from === to` counts edges inside one capability. */
+  matrix: CapabilityDependencyCellV1[];
+  imports: {
+    coverage: EvidenceCoverageLevelV2;
+    /** `code-facts-unavailable`, `code-facts-stale`, `code-facts-import-limit`, `code-facts-truncated`. */
+    reasonCodes: string[];
+    /** True when the index read is not the whole population for a reason other than the limit. */
+    truncated: boolean;
+    importNodeCount: number | null;
+    importNodeLimit: number;
+    importNodeLimitExceeded: boolean;
+    /** Distinct file-to-file edges that passed the filters, attributed or not. */
+    edgeCount: number;
+    /**
+     * Repository-local import specifiers (relative, or naming a workspace package) from filtered
+     * files that resolved to no repository file. Always 0 with `--into`: such an edge has no target.
+     */
+    unresolvedCount: number;
+    /** Edges left out of `matrix` because one endpoint has no single owning capability. */
+    unattributed: { unownedEndpoint: number; contestedEndpoint: number; noCapabilityEndpoint: number };
+  };
+  calls: {
+    coverage: "unknown";
+    reasonCodes: [typeof CAPABILITY_DEPENDENCIES_CALLS_UNAVAILABLE_REASON];
+  };
+  /** Attributed file-level edges behind `matrix`, sorted by path. */
+  edges: { limit: number; count: number; omittedCount: number; items: CapabilityDependencyEdgeV1[] };
+}

package/src/product-version.ts

@@ -1,6 +1,6 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.6.3";
-export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.0";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.7.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/v1";
 export const ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";