archctx-contracts 0.7.2 → 0.8.1

package/src/index.ts

@@ -1,15 +1,21 @@
 export * from "./control-plane-routes";
 export * from "./architecture";
+export * from "./architecture-debt";
 export * from "./docs-anchors";
 export * from "./external-docs";
 export * from "./github-governance";
 export * from "./ledger";
+export * from "./native-context";
 export * from "./ownership-dependencies";
 export * from "./ports";
 export * from "./practices";
 export * from "./projection";
+export * from "./projection-recovery";
 export * from "./projection-manifest";
 export * from "./product-version";
 export * from "./refactor";
 export * from "./schema";
+export * from "./failure";
 export * from "./validator";
+
+export * from "./changeset-recovery";

package/src/ledger.ts

@@ -600,14 +600,12 @@ export interface ProjectionTargetScopeV1 {
   entityKind?: string;
 }
 
-export interface ProjectionTargetV1 {
+interface ProjectionTargetBaseV1 {
   schemaVersion: typeof PROJECTION_TARGET_SCHEMA_VERSION;
   targetId: string;
   type: ProjectionTargetType;
   scope: ProjectionTargetScopeV1;
   path: string;
-  ownership: ProjectionTargetOwnership;
-  generatedRegion: ProjectionTargetGeneratedRegionV1;
   rendererVersion: string;
   format: ProjectionTargetFormat;
   sourceDigest: string;
@@ -615,6 +613,19 @@ export interface ProjectionTargetV1 {
   extensions?: Record<string, Json>;
 }
 
+/**
+ * A `mixed` target owns one marked region inside a human-owned document, so it carries the region
+ * markers. A `generated` target owns its whole file and carries no marker: the projection manifest
+ * row's `outputDigest` is what proves the file is projection output.
+ */
+export type ProjectionTargetV1 = ProjectionTargetBaseV1 & (
+  | { ownership: Extract<ProjectionTargetOwnership, "mixed">; generatedRegion: ProjectionTargetGeneratedRegionV1 }
+  | { ownership: Extract<ProjectionTargetOwnership, "generated">; generatedRegion?: never }
+);
+
+/** A target that owns one marked region inside a document. */
+export type ProjectionMixedTargetV1 = Extract<ProjectionTargetV1, { ownership: "mixed" }>;
+
 export interface RecommendationRunV1 {
   schemaVersion: typeof RECOMMENDATION_RUN_SCHEMA_VERSION;
   runId: string;

package/src/native-context.ts

@@ -0,0 +1,279 @@
+import { FailureError, knownFailure, toEnvelope, unclassifiedFailure } from "./failure";
+import { canonicalize, errorEnvelope, type ArchContextErrorCode, type Json, type JsonEnvelope } from "./schema";
+import { jsonSchemaResolver, validateJsonSchema, type JsonSchemaResolver } from "./validator";
+
+export const NATIVE_CONTEXT_SCHEMA_VERSION = "archcontext.native-context-export/v1" as const;
+export const NATIVE_CONTEXT_PROFILE = "repo-harness/v1" as const;
+export const NATIVE_CONTEXT_LIMITS = Object.freeze({
+  inputFiles: 10_000,
+  fileBytes: 8 * 1024 * 1024,
+  inputBytes: 32 * 1024 * 1024,
+  responseBytes: 64 * 1024 * 1024,
+  treeListingBytes: 32 * 1024 * 1024,
+  gitTimeoutMs: 10_000,
+  batchOverheadBytes: 2 * 1024 * 1024
+});
+
+export const NATIVE_CONTEXT_REASONS = [
+  "git-worktree-required", "native-context-arguments-invalid", "native-context-profile-invalid",
+  "native-context-model-missing", "native-context-model-invalid", "native-context-budget-invalid",
+  "native-context-profile-incomplete", "native-context-text-invalid", "native-context-input-ambiguous",
+  "native-context-path-unsafe", "native-context-entry-kind-unsupported", "native-context-ref-unsafe",
+  "native-context-ref-unavailable", "native-context-blob-unavailable", "native-context-input-missing",
+  "native-context-input-unreadable", "native-context-input-changed", "native-document-marker-invalid",
+  "native-document-section-ambiguous", "native-context-limit-exceeded", "native-context-git-read-failed"
+] as const;
+export type NativeContextReasonCode = (typeof NATIVE_CONTEXT_REASONS)[number];
+export type NativeModelRecord = Record<string, Json>;
+export interface NativeContextModel {
+  nodes: NativeModelRecord[];
+  relations: NativeModelRecord[];
+  flows: NativeModelRecord[];
+  sourcePaths: { nodes: Record<string, string>; relations: Record<string, string>; flows: Record<string, string> };
+}
+export interface NativeContextInput {
+  path: string;
+  role: "manifest" | "node" | "relation" | "flow" | "contract" | "document";
+  requirement: "required" | "declared" | "optional";
+  presence: "present" | "missing";
+  mode: "100644" | "100755" | null;
+  byteLength: number | null;
+  contentDigest: string | null;
+}
+export interface NativeTextRange {
+  startByte: number;
+  endByte: number;
+  startLine: number;
+  endLine: number;
+}
+export interface NativeHumanRegion extends NativeTextRange { text: string }
+export interface NativeDocumentSection {
+  state: "missing" | "absent" | "empty" | "present";
+  heading: { text: string; range: NativeTextRange } | null;
+  bodyRanges: NativeTextRange[];
+  body: string | null;
+}
+export interface NativeContextDocument {
+  path: string;
+  targetId: string;
+  capabilityNodeIds: string[];
+  presence: "present" | "missing";
+  markerState: "present" | "absent" | "missing";
+  humanRegions: NativeHumanRegion[];
+  section3: NativeDocumentSection;
+  backlog: NativeDocumentSection;
+}
+export interface NativeCapabilityProfile {
+  nodeId: string;
+  status: string;
+  domain: string;
+  name: string;
+  modulePath: string;
+  contractFiles: { agents: string; claude: string };
+  includeAnchors: string[];
+  lspProfile: string | null;
+  verification: string[] | null;
+  directChildNodeIds: string[];
+  componentNodeIds: string[];
+}
+export interface NativeContextContract {
+  path: string;
+  roles: ("agents" | "claude")[];
+  capabilityNodeIds: string[];
+  presence: "present" | "missing";
+  text: string | null;
+  byteLength: number | null;
+  byteDigest: string | null;
+}
+export type NativeContextSnapshot =
+  | { source: "ref"; commitSha: string; treeOid: string; validation: "immutable-tree" }
+  | { source: "worktree"; headSha: string; headTreeOid: string; validation: "stable-read" };
+export interface NativeContextExportV1 {
+  schemaVersion: typeof NATIVE_CONTEXT_SCHEMA_VERSION;
+  profile: typeof NATIVE_CONTEXT_PROFILE;
+  snapshot: NativeContextSnapshot;
+  inputDigest: string;
+  inputs: NativeContextInput[];
+  allowedNodeKinds: string[];
+  contextBudgetBytes: number;
+  model: NativeContextModel;
+  capabilityProfiles: NativeCapabilityProfile[];
+  contracts: NativeContextContract[];
+  documents: NativeContextDocument[];
+}
+
+const PATH_REASONS = new Set<NativeContextReasonCode>(["native-context-path-unsafe", "native-context-entry-kind-unsupported", "native-context-ref-unsafe"]);
+const PRECONDITION_REASONS = new Set<NativeContextReasonCode>(["native-context-ref-unavailable", "native-context-blob-unavailable", "native-context-input-missing", "native-context-input-unreadable", "native-context-input-changed", "native-context-limit-exceeded", "native-context-git-read-failed"]);
+
+/** Compatible native class, backed by the single strict failure authority. */
+export class NativeContextError extends FailureError {
+  constructor(reasonCode: NativeContextReasonCode, details: Record<string, Json> = {}) {
+    let failure;
+    try {
+      const code: ArchContextErrorCode = reasonCode === "git-worktree-required" ? "AC_REPO_NOT_FOUND"
+        : reasonCode === "native-context-model-missing" ? "AC_MODEL_ADOPTION_REQUIRED"
+        : PATH_REASONS.has(reasonCode) ? "AC_PATH_DENIED"
+        : PRECONDITION_REASONS.has(reasonCode) ? "AC_PRECONDITION_FAILED" : "AC_SCHEMA_INVALID";
+      failure = knownFailure(code, reasonCode, details);
+    } catch { failure = unclassifiedFailure("failure-metadata"); }
+    super(failure.code, failure.reasonCode, failure.details, failure);
+    this.name = "NativeContextError";
+  }
+}
+
+export function nativeContextErrorEnvelope(error: NativeContextError): JsonEnvelope {
+  return toEnvelope("export.native", error, "native-export") as JsonEnvelope;
+}
+
+export function assertNativeContextLimit(limit: keyof typeof NATIVE_CONTEXT_LIMITS, observed: number): void {
+  if (!Number.isSafeInteger(observed) || observed < 0 || observed > NATIVE_CONTEXT_LIMITS[limit]) {
+    throw new NativeContextError("native-context-limit-exceeded", { limit, maximum: NATIVE_CONTEXT_LIMITS[limit], observed });
+  }
+}
+
+/** A lexical contract. It does not expand globs, resolve ownership or open any path. */
+export function isNativeContextPath(path: string): boolean {
+  return path.length > 0 && !/^[A-Za-z]:/.test(path) && !path.startsWith("/")
+    && Buffer.from(path, "utf8").toString("utf8") === path
+    && !/[\\\u0000-\u001f\u007f-\u009f]/.test(path)
+    && path.split("/").every(segment => segment !== "" && segment !== "." && segment !== "..");
+}
+
+export function assertNativeContextPath(path: string): void {
+  if (!isNativeContextPath(path)) throw new NativeContextError("native-context-path-unsafe", { path });
+}
+
+export function nativeByteCompare(left: string, right: string): number {
+  return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+
+type SchemaDocument = Parameters<typeof validateJsonSchema>[0];
+export interface NativeContextSchemas { node: SchemaDocument; relation: SchemaDocument; flow: SchemaDocument }
+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 {
+  return jsonSchemaResolver([schemas.node, schemas.relation, schemas.flow]);
+}
+
+export function nativeAllowedNodeKinds(schemas: NativeContextSchemas): string[] {
+  const kinds = schemas.node.properties?.kind?.enum;
+  if (!kinds || kinds.some(kind => typeof kind !== "string")) throw new Error("canonical-node-kind-enum-unavailable");
+  return [...kinds] as string[];
+}
+
+/** 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 = (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) {
+    for (const record of records) {
+      const id = typeof record.id === "string" ? record.id : "(undeclared)";
+      // JSON Schema validates own data properties. Reject values the shared subset parser
+      // cannot represent losslessly as JSON, rather than serializing inherited fields away
+      // or coercing non-finite numbers to null. The shared parser itself is unchanged.
+      const pending: Array<{ value: unknown; field: string; exit?: boolean }> = [{ value: record, field: "$" }];
+      const active = new Set<object>();
+      const done = new Set<object>();
+      let jsonInvalid = false;
+      while (pending.length > 0) {
+        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(record, item.field, "non-json-number"); jsonInvalid = true; break; }
+        if (value === null || typeof value !== "object") continue;
+        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(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(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 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(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 chain = new Set<string>();
+    let cursor: NativeModelRecord | undefined = node;
+    while (cursor) {
+      const current = cursor.id as string;
+      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(cursor, "parent", "parent-node-missing"); break; }
+      cursor = parent;
+    }
+    for (const current of chain) checked.add(current);
+  }
+  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, "source", "path-unsafe");
+    for (const entry of source?.entrypoints ?? []) {
+      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, "source.entrypoints.symbols.sinks.path", "path-unsafe");
+          const selector = JSON.stringify([entry.id, symbol.name, sink.id]);
+          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, field, "relation-node-missing");
+  }
+  for (const flow of model.flows) {
+    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(flow, "participants.id", "participant-id-ambiguous");
+      participantIds.add(participant.id);
+      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(flow, "outcomes.id", "outcome-id-ambiguous");
+      outcomeIds.add(outcome.id);
+      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(flow, "steps", "step-participant-missing");
+      const definition = canonicalize(step);
+      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(flow, "steps.evidence", "selector-missing");
+    }
+  }
+  return issues;
+}

package/src/ownership-dependencies.ts

@@ -73,6 +73,27 @@ export const CAPABILITY_DEPENDENCIES_SCHEMA_VERSION = "archcontext.capability-de
 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;
+/**
+ * The relation kinds that declare an import dependency: every `archcontext.relation/v1` kind in
+ * which the source uses the target. `deployed-on` places a node on infrastructure and declares no
+ * code dependency. A kind added to the relation schema later declares nothing until it is listed.
+ *
+ * The rule: an import from a file owned by capability A into a file owned by capability B, A != B,
+ * is declared when the model has a relation of one of these kinds whose `source` rolls up to A and
+ * whose `target` rolls up to B. A node rolls up to itself when it is a capability, else to the
+ * nearest `kind: capability` ancestor on its `parent` chain, exactly like a file owner. Direction
+ * matters: a relation B -> A does not declare an import A -> B. A relation endpoint that rolls up
+ * to no capability declares nothing.
+ */
+export const CAPABILITY_DEPENDENCY_DECLARING_RELATION_KINDS = [
+  "calls",
+  "depends-on",
+  "implements",
+  "publishes",
+  "reads",
+  "subscribes",
+  "writes"
+] as const;
 
 export interface CapabilityDependencyCellV1 {
   /** Owning capability of the importing file. */
@@ -83,6 +104,15 @@ export interface CapabilityDependencyCellV1 {
   imports: number;
   /** Always `null` in v1: call edges are not read (see `calls`). */
   calls: null;
+  /**
+   * Whether the model declares this dependency (rule: CAPABILITY_DEPENDENCY_DECLARING_RELATION_KINDS).
+   * A cell with `from === to` stays inside one capability and needs no relation: it is always
+   * declared, with no relation ids. A cross-capability cell is declared exactly when
+   * `relationIds` is non-empty.
+   */
+  declared: boolean;
+  /** Ids of the relations that declare a cross-capability cell, sorted. Always empty when `from === to`. */
+  relationIds: string[];
 }
 
 export interface CapabilityDependencyEdgeV1 {
@@ -102,8 +132,16 @@ export interface CapabilityDependenciesV1 {
   /** Non-zero cells only, sorted by `from` then `to`. A cell with `from === to` counts edges inside one capability. */
   matrix: CapabilityDependencyCellV1[];
   imports: {
+    /**
+     * `archctx deps` never answers `unknown`: without code facts that attest to the measured tree it
+     * refuses with `AC_CODE_FACTS_UNAVAILABLE`, so an empty matrix always means no attributed edge.
+     */
     coverage: EvidenceCoverageLevelV2;
-    /** `code-facts-unavailable`, `code-facts-stale`, `code-facts-import-limit`, `code-facts-truncated`. */
+    /**
+     * `code-facts-import-limit` or `code-facts-truncated` on `archctx deps` output. An index that
+     * is missing or has pending changes measures as `code-facts-unavailable`, which `deps` turns
+     * into the `AC_CODE_FACTS_UNAVAILABLE` refusal.
+     */
     reasonCodes: string[];
     /** True when the index read is not the whole population for a reason other than the limit. */
     truncated: boolean;

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/practices.ts

@@ -389,6 +389,8 @@ export interface PracticeDeltaV1 {
 
 export interface PracticeCheckpointResultV1 {
   schemaVersion: "archcontext.practice-checkpoint/v1";
+  /** Runtime checkpoints attach the same read-only debt measurement as `archctx debt`. */
+  debt?: import("./architecture-debt").ArchitectureDebtReportV1;
   taskSessionId: string;
   event: PracticeCheckpointEvent;
   headSha: string;

package/src/product-version.ts

@@ -1,8 +1,8 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.7.2";
+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/v1";
+export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v2";
 export const ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
 
 export interface ProductVersionManifest {
@@ -41,7 +41,7 @@ export interface ProductVersionManifest {
     sqliteMigrations: string;
     codeGraph: {
       packageName: "@colbymchenry/codegraph";
-      requiredVersion: "1.6.1";
+      requiredVersion: "1.6.2";
       adapter: "codegraph-cli";
     };
   };
@@ -100,9 +100,42 @@ export function productVersionManifest(): ProductVersionManifest {
       sqliteMigrations: "0001_runtime_state..0012_explorer_projection_index",
       codeGraph: {
         packageName: "@colbymchenry/codegraph",
-        requiredVersion: "1.6.1",
+        requiredVersion: "1.6.2",
         adapter: "codegraph-cli"
       }
     }
   };
 }
+
+/**
+ * Whether a Node.js version (`process.versions.node`) satisfies `range`, a space-separated list of
+ * `>=`, `>`, `<=`, `<` or `=` comparators over `major[.minor[.patch]]` (missing parts are 0), the
+ * only form `ARCHCONTEXT_NODE_RANGE` uses. A version that does not start with `major.minor.patch`
+ * does not satisfy any range; a prerelease suffix is ignored, so `26.0.0-pre` counts as `26.0.0`
+ * and fails `<26`. A comparator outside that form throws: the range is product metadata, not input.
+ */
+export function nodeVersionSatisfiesRange(nodeVersion: string, range: string = ARCHCONTEXT_NODE_RANGE): boolean {
+  const comparators = range.trim().split(/\s+/).map((token) => {
+    const match = /^(>=|<=|>|<|=)?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(token);
+    if (!match) throw new Error(`unsupported node engine comparator: ${token}`);
+    return { operator: match[1] ?? "=", version: [Number(match[2]), Number(match[3] ?? 0), Number(match[4] ?? 0)] };
+  });
+  const parsed = /^v?(\d+)\.(\d+)\.(\d+)/.exec(nodeVersion);
+  if (!parsed) return false;
+  const version = [Number(parsed[1]), Number(parsed[2]), Number(parsed[3])];
+  return comparators.every(({ operator, version: bound }) => {
+    const order = compareVersionTriples(version, bound);
+    if (operator === ">=") return order >= 0;
+    if (operator === ">") return order > 0;
+    if (operator === "<=") return order <= 0;
+    if (operator === "<") return order < 0;
+    return order === 0;
+  });
+}
+
+function compareVersionTriples(left: number[], right: number[]): number {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] - right[index];
+  }
+  return 0;
+}