archctx-contracts 0.5.10 → 0.5.12

package/src/architecture.ts

@@ -71,3 +71,82 @@ export interface ArchitectureNotApplicableFlowV1 extends ArchitectureFlowBaseV1
   applicability: "not-applicable";
   rationale: string;
 }
+
+/**
+ * A `forbid-dependency` constraint (`archcontext.constraint/v1`), narrowed to the fields the
+ * dependency gate evaluates. A file owned by a `scope.nodes` node (or a descendant) must not
+ * import a file owned by a `rule.targets` node (or a descendant). v1 has no `allowedVia` escape.
+ */
+export interface DependencyConstraintV1 {
+  id: string;
+  severity: "error" | "warning";
+  scope: { nodes: string[] };
+  rule: { type: "forbid-dependency"; targets: string[] };
+  rationale: string;
+}
+
+export const DEPENDENCY_CONSTRAINT_STATUSES = ["not-applicable", "pass", "undetermined", "violated"] as const;
+export type DependencyConstraintStatus = (typeof DEPENDENCY_CONSTRAINT_STATUSES)[number];
+
+/**
+ * Why a dependency result is not a complete observation: no index answered, the index attested
+ * to a different worktree, the import dump hit its limit, a constrained file carries a
+ * repository-local import that resolved to no file, or the workspace package map could not be
+ * read, so no bare workspace specifier could be resolved.
+ */
+export const DEPENDENCY_CONSTRAINT_REASON_CODES = [
+  "code-facts-stale",
+  "code-facts-truncated",
+  "code-facts-unavailable",
+  "unresolved-import",
+  "workspace-resolution-failed"
+] as const;
+export type DependencyConstraintReasonCode = (typeof DEPENDENCY_CONSTRAINT_REASON_CODES)[number];
+
+export interface DependencyConstraintViolationV1 {
+  constraintId: string;
+  fromPath: string;
+  toPath: string;
+  fromNode: string;
+  toNode: string;
+  severity: "error" | "warning";
+}
+
+export interface DependencyConstraintEvaluationV1 {
+  schemaVersion: "archcontext.dependency-constraint-evaluation/v1";
+  status: DependencyConstraintStatus;
+  /** `complete` only when an index attested to the evaluated worktree and was not truncated. */
+  coverage: "complete" | "partial" | "unknown";
+  reasonCodes: DependencyConstraintReasonCode[];
+  constraintIds: string[];
+  /** Import observations the evaluation read; zero when the index did not attest to this tree. */
+  importEdgeCount: number;
+  /** Repository-local specifiers from constrained files that resolved to no file. */
+  unresolvedImports: { from: string; specifier: string }[];
+  violations: DependencyConstraintViolationV1[];
+}
+
+/**
+ * The closed `failOn` vocabulary of `.archcontext/policies/review.yaml`. A review finding in one
+ * of these categories blocks only when its category is listed; findings outside the vocabulary
+ * are never affected by the policy.
+ */
+export const REVIEW_FAIL_ON_CATEGORIES = [
+  "incomplete-intervention",
+  "invalid-schema",
+  "prohibited-dependency",
+  "stale-context",
+  "unjustified-compatibility"
+] as const;
+export type ReviewFailOnCategory = (typeof REVIEW_FAIL_ON_CATEGORIES)[number];
+
+/**
+ * The effective review policy. An error in a category missing from `failOn` is downgraded to a
+ * warning, with one exception: the task-snapshot HEAD-mismatch `stale-context` finding always stays
+ * an error, because a stale snapshot skips every other review gate.
+ */
+export interface ReviewPolicyV1 {
+  failOn: ReviewFailOnCategory[];
+  /** `default` when the policy file is missing or invalid in any way: every category blocks. */
+  source: "policy-file" | "default";
+}

package/src/ports.ts

@@ -140,13 +140,38 @@ export interface LocalStorePort {
   saveReviewResult(reviewId: string, result: unknown): Promise<void>;
 }
 
+export interface ModelValidationResult {
+  valid: boolean;
+  errors: string[];
+  /**
+   * The subset of `errors` that are cross-file references resolving to nothing, such as an ADR
+   * `appliesTo` id with no node. Omitted when empty.
+   */
+  referenceErrors?: string[];
+  /** Problems that do not invalidate the model, such as an ignored legacy setting. Omitted when empty. */
+  warnings?: string[];
+  modelDigest: string;
+}
+
 export interface ModelStorePort {
   loadManifest(workspace: WorkspaceRef): Promise<unknown>;
   loadModel(workspace: WorkspaceRef): Promise<unknown[]>;
-  validateModel(workspace: WorkspaceRef): Promise<{ valid: boolean; errors: string[]; modelDigest: string }>;
+  validateModel(workspace: WorkspaceRef): Promise<ModelValidationResult>;
   writeChangeSetPreview(changeSet: unknown): Promise<{ digest: string; summary: string }>;
 }
 
+/**
+ * Errors that make a model unusable as the base of a write. Dangling references are excluded so
+ * that a change repairing them (for example restoring a deleted node) is not blocked; the
+ * after-apply model is still validated in full.
+ */
+export function baseModelBlockingErrors(result: ModelValidationResult): string[] {
+  if (result.valid) return [];
+  if (result.errors.length === 0) return ["unknown validation error"];
+  const references = new Set(result.referenceErrors ?? []);
+  return result.errors.filter((error) => !references.has(error));
+}
+
 export interface PolicyPort {
   evaluateChangeSet(changeSet: unknown): Promise<{ allowed: boolean; violations: string[] }>;
   evaluateReview(input: unknown): Promise<{ result: "pass" | "fail"; findings: unknown[] }>;
@@ -750,3 +775,66 @@ export interface ChatGptGaToolContract {
   requiresLocalConfirmationForWrite: boolean;
   disclosure: string;
 }
+
+export type DetachedReviewWorktreeReason =
+  | "HEAD_UNAVAILABLE"
+  | "HEAD_SHA_MISMATCH"
+  | "TREE_OID_MISMATCH"
+  | "WORKTREE_NOT_DETACHED"
+  | "WORKTREE_NOT_CLEAN";
+
+export interface DetachedReviewWorktreeVerification {
+  schemaVersion: "archcontext.detached-review-worktree-verification/v1";
+  accepted: boolean;
+  reasonCode?: DetachedReviewWorktreeReason;
+  expected: {
+    headSha: string;
+    headTreeOid?: string;
+  };
+  observed: {
+    headSha?: string;
+    headTreeOid?: string;
+    detached?: boolean;
+    clean?: boolean;
+  };
+}
+
+
+export interface ReviewCheckoutGitPort {
+  findRepositoryRoot(start: string): string;
+  readOriginUrl(root: string): string | null;
+  verifyDetachedWorktree(input: {
+    worktreeRoot: string;
+    expectedHeadSha: string;
+    expectedHeadTreeOid?: string;
+  }): DetachedReviewWorktreeVerification;
+}
+
+export interface NonLocalEgressChannel {
+  channel: "context7" | "agent-audit" | "github-issue-publishing" | "npm-update-check" | "codegraph-telemetry";
+  destination: string;
+  trigger: string;
+  data: string;
+  status: "enabled" | "declared-awaiting-user-consent" | "blocked-by-policy";
+}
+
+export interface LocalEgressReport {
+  ok: boolean;
+  policyMode: "configured" | "local-only";
+  enforcement: "application-admission";
+  defaultOutbound: "local-only";
+  effectiveOutbound: "local-only" | "non-local";
+  nonLocalEgress: NonLocalEgressChannel[];
+  cloudContentUpload: "deny";
+  secureMcpTunnel: "disabled-by-default";
+  thirdPartyTelemetry: "disabled" | "not-disabled-by-env";
+  codeGraph: {
+    provider: "codegraph";
+    telemetry: "disabled" | "not-disabled-by-env";
+    envVar: string;
+    configuredValue: string | null;
+    effectiveValue: string;
+    source: "archcontext-default" | "environment";
+  };
+  warnings: string[];
+}

package/src/product-version.ts

@@ -1,5 +1,5 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.5.10";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.5.12";
 export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.0";
 export const ARCHCONTEXT_NODE_RANGE = ">=22.22 <26";
 export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1";

package/src/projection.ts

@@ -8,6 +8,7 @@ export const PROJECTION_APPLY_RECOVERY_BINDING_SCHEMA_VERSION = "archcontext.pro
 export const PROJECTION_APPLY_RECOVERY_INTENT_SCHEMA_VERSION = "archcontext.projection-apply-recovery-intent/v1" as const;
 export const PROJECTION_APPLY_RECOVERY_PROOF_SCHEMA_VERSION = "archcontext.projection-apply-recovery-proof/v1" as const;
 export const PROJECTION_APPLY_RECOVERY_RESULT_SCHEMA_VERSION = "archcontext.projection-apply-recovery-result/v1" as const;
+export const PROJECTION_APPLY_READBACK_RESULT_SCHEMA_VERSION = "archcontext.projection-apply-readback-result/v1" as const;
 export const ARCHITECTURE_REFRESH_SIGNAL_SCHEMA_VERSION = "archcontext.architecture-refresh-signal/v1" as const;
 export const ARCHCTX_CAPABILITIES_SCHEMA_VERSION = "archcontext.capabilities/v1" as const;
 export const ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v4" as const;
@@ -60,6 +61,7 @@ export const ARCHCTX_FEATURES = [
   "architecture-docs-renderer-v2",
   "architecture-refresh-signal-v1",
   "module-statistics-v1",
+  "projection-apply-readback-v1",
   "projection-apply-receipt-v1",
   "projection-apply-recovery-v1",
   "projection-prior-committed-applies-v1",
@@ -291,6 +293,28 @@ export interface ProjectionApplyRecoveryResultV1 {
   refreshSignals: ArchitectureRefreshSignalV1[];
 }
 
+/** Non-consuming receipt retrieval; current state is rebuilt for every response. */
+export interface ProjectionApplyReadbackResultV1 {
+  schemaVersion: typeof PROJECTION_APPLY_READBACK_RESULT_SCHEMA_VERSION;
+  requestId: string;
+  requestDigest: Sha256Digest;
+  receipt: ProjectionApplyReceiptV1;
+  current: ProjectionApplyRecoveryProofV1["current"];
+  readbackDigest: Sha256Digest;
+}
+
+/** Exact-request absence observed under the same writer boundary used by apply. */
+export interface ProjectionApplyAbsenceV1 {
+  schemaVersion: "archcontext.projection-apply-absence/v1";
+  requestId: string;
+  requestDigest: Sha256Digest;
+  lookupKey: Sha256Digest;
+  current: ProjectionExpectedSnapshotV1;
+  absenceDigest: Sha256Digest;
+}
+
+export type ProjectionApplyReadbackV1 = ProjectionApplyReadbackResultV1 | ProjectionApplyAbsenceV1;
+
 export interface ArchctxCapabilitiesV1 {
   schemaVersion: typeof ARCHCTX_CAPABILITIES_SCHEMA_VERSION;
   package: {
@@ -550,6 +574,89 @@ export function projectionApplyRecoveryBindingInvariantIssues(
   return issues;
 }
 
+/** Readback carries the original accepted apply request, never caller-authored receipt data. */
+export function projectionApplyReadbackRequestInvariantIssues(request: ProjectionRequestV1): string[] {
+  const issues = projectionRequestInvariantIssues(request);
+  const allowed = new Set(["schemaVersion", "requestId", "profile", "mode", "targets", "changedPaths", "expected", "acceptedChange"]);
+  if (Object.keys(request).some((key) => !allowed.has(key))) issues.push("readback request contains unsupported fields");
+  if (request.mode !== "apply" || !request.acceptedChange) issues.push("readback requires an accepted apply request");
+  if (request.schemaVersion !== PROJECTION_REQUEST_SCHEMA_VERSION || request.profile !== "repo-harness/v1") issues.push("readback request protocol is invalid");
+  if (typeof request.requestId !== "string"
+    || request.targets.some((target) => !(PROJECTION_TARGETS as readonly string[]).includes(target))
+    || request.changedPaths.some((path) => typeof path !== "string" || !isRepoRelativePosixPath(path))) issues.push("readback request fields are invalid");
+  const expectedKeys = ["repositoryId", "workspaceId", "headSha", "worktreeDigest"];
+  if (Object.keys(request.expected).some((key) => !expectedKeys.includes(key))
+    || expectedKeys.some((key) => typeof request.expected[key as keyof ProjectionExpectedSnapshotV1] !== "string")
+    || !request.expected.repositoryId || !request.expected.workspaceId
+    || !/^[a-f0-9]{40}$/.test(request.expected.headSha)
+    || !SHA256_DIGEST.test(request.expected.worktreeDigest)) issues.push("readback expected snapshot is invalid");
+  if (request.acceptedChange && Object.keys(request.acceptedChange).some((key) => !["changeSetId", "eventId", "reasonCodes", "affectedNodeIds"].includes(key))) {
+    issues.push("readback accepted change contains unsupported fields");
+  }
+  return issues;
+}
+
+export function projectionApplyAbsenceInvariantIssues(input: ProjectionApplyAbsenceV1, request: ProjectionRequestV1): string[] {
+  const issues = projectionApplyReadbackRequestInvariantIssues(request);
+  if (input.schemaVersion !== "archcontext.projection-apply-absence/v1") issues.push("absence schemaVersion is invalid");
+  if (Object.keys(input).some((key) => !["schemaVersion", "requestId", "requestDigest", "lookupKey", "current", "absenceDigest"].includes(key))) issues.push("absence contains unsupported fields");
+  const { absenceDigest, ...body } = input;
+  if (absenceDigest !== digestJson(body as unknown as Json)) issues.push("absenceDigest must bind the complete absence result");
+  if (input.requestId !== request.requestId || input.requestDigest !== digestJson(request as unknown as Json)) issues.push("absence request identity mismatch");
+  if (digestJson(input.current as unknown as Json) !== digestJson(request.expected as unknown as Json)) issues.push("absence current snapshot differs from request");
+  if (!request.acceptedChange || input.lookupKey !== projectionApplyLookupKey({
+    repositoryId: request.expected.repositoryId, workspaceId: request.expected.workspaceId, acceptedChange: request.acceptedChange
+  })) issues.push("absence lookup identity mismatch");
+  return issues;
+}
+
+export function projectionApplyReadbackResultDigest(input: Omit<ProjectionApplyReadbackResultV1, "readbackDigest">): Sha256Digest {
+  return digestJson(input as unknown as Json) as Sha256Digest;
+}
+
+export function projectionApplyReadbackResultInvariantIssues(
+  input: ProjectionApplyReadbackResultV1,
+  request?: ProjectionRequestV1
+): string[] {
+  const issues = projectionApplyReceiptInvariantIssues(input.receipt);
+  const { readbackDigest, ...body } = input;
+  if (input.schemaVersion !== PROJECTION_APPLY_READBACK_RESULT_SCHEMA_VERSION) issues.push("readback schemaVersion is invalid");
+  if (projectionApplyReadbackResultDigest(body) !== readbackDigest) issues.push("readbackDigest must bind the complete readback result");
+  if (!/^[a-zA-Z0-9_.:-]+$/.test(input.requestId)) issues.push("readback requestId is invalid");
+  for (const value of [input.requestDigest, input.current.ownedOutputDigest, input.current.fixedPointDigest]) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(value)) issues.push("readback digest is invalid");
+  }
+  const receipt = input.receipt;
+  if (receipt.schemaVersion !== PROJECTION_APPLY_RECEIPT_SCHEMA_VERSION) issues.push("readback receipt schemaVersion is invalid");
+  const binding = receipt.recovery;
+  if (!binding) return [...issues, "committed receipt lacks its original recovery binding"];
+  for (const field of ["repositoryId", "workspaceId", "headSha", "worktreeDigest"] as const) {
+    if (input.current.snapshot[field] !== binding.originalExpectedSnapshot[field]) issues.push(`readback current ${field} differs from approval`);
+  }
+  if (input.current.snapshot.generatedFrom.codeGraphStatus !== "ready"
+    || input.current.snapshot.rendererVersion !== binding.rendererVersion
+    || input.current.snapshot.layoutVersion !== binding.layoutVersion
+    || input.current.snapshot.projectionInputDigest !== receipt.result.outputSnapshot.projectionInputDigest
+    || input.current.snapshot.codeGraphDigest !== receipt.result.outputSnapshot.codeGraphDigest
+    || digestJson(input.current.snapshot.generatedFrom as unknown as Json) !== digestJson(binding.generatedFrom as unknown as Json)
+    || digestJson(input.current.resultingDigests as unknown as Json) !== digestJson(binding.expectedResultingDigests as unknown as Json)
+    || input.current.ownedOutputDigest !== binding.ownedOutputDigest) {
+    issues.push("readback current state differs from committed recovery binding");
+  }
+  if (input.requestId !== receipt.result.requestId) issues.push("readback requestId differs from committed request");
+  if (request) {
+    issues.push(...projectionApplyReadbackRequestInvariantIssues(request));
+    if (input.requestDigest !== digestJson(request as unknown as Json) || input.requestId !== request.requestId) issues.push("readback request identity mismatch");
+    if (digestJson(request.expected as unknown as Json) !== digestJson(binding.originalExpectedSnapshot as unknown as Json)
+      || digestJson(request.acceptedChange as unknown as Json) !== digestJson(receipt.identity.acceptedChange as unknown as Json)
+      || digestJson(request.targets as unknown as Json) !== digestJson(binding.targets as unknown as Json)
+      || digestJson(request.changedPaths as unknown as Json) !== digestJson(binding.changedPaths as unknown as Json)) {
+      issues.push("readback request differs from committed approval binding");
+    }
+  }
+  return issues;
+}
+
 export function projectionApplyRecoveryIntentInvariantIssues(input: ProjectionApplyRecoveryIntentV1): string[] {
   const issues: string[] = [];
   if (input.schemaVersion !== PROJECTION_APPLY_RECOVERY_INTENT_SCHEMA_VERSION) issues.push("recovery intent schemaVersion is invalid");