arkgate 4.8.10 → 4.8.13

package/CHANGELOG.md

@@ -3,6 +3,79 @@
 All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are documented here or
 in the immutable pre-2.0 archive linked below.
 
+## Unreleased
+
+## 4.8.13 — 2026-09-06
+
+**Patch** over **4.8.12**. Publish gate: remaining ArkOrder doctor/deny branches so
+`test:confidence` / `release:npm` clears the 81% floor. Tag `v4.8.12` stands;
+this is the ship. **Write. Check. Ship.** **No required config migration.** No
+`schemaVersion` bump. Does not close `K01` / `Z09`. No new skill names. This
+mother `ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: prepared** (tree candidate; npm `latest` remains **4.8.11** until the
+signed-tag provenance workflow succeeds).
+
+### Fixed
+- Confidence coverage: remaining ArkOrder doctor/deny `Next:` and HTML/doctor
+  residual paths so the publish job is not blocked by a 0.03-point branch miss.
+
+## 4.8.12 — 2026-09-05
+
+**Patch** over **4.8.11**. First-contact honesty for the optional ArkOrder extra.
+Sensors, valve, and `arkgate/order` already shipped on 4.8.11; this projects
+them through doctor / start / status / the check label, in plain words.
+**Write. Check. Ship.** **No required config migration.** No `schemaVersion` bump.
+Does not close `K01` / `Z09`. No new skill names. This mother `ark.config.json`
+still does **not** turn `arkOrder` on.
+
+**Status: prepared** (tree candidate; npm `latest` remains **4.8.11** until the
+signed-tag provenance workflow succeeds).
+
+### Added
+- Doctor / HTML / status `arkOrder` section (`notAScore`), same envelope as
+  ArkRun. Absence is a silent row. When on: one-breath + named choices + leftover count.
+- Check prints `[ArkOrder]` on `ARKORDER_*` denies (and `[ArkRun]` on
+  `ARKRUN_*`) so rewriting `plan` like a seat count reads as clearly as a bad import.
+- `ark start` preview says extras stay off — layers only, they stop bad imports.
+
+### Changed
+- Merge-planes honesty now names enforced ArkOrder skip findings. The stamp
+  already claimed this plane; `failMergeWhen` now matches.
+- First-contact copy (README, use, doctor, deny `Next:`, start, gallery) uses
+  the one-minute breath. No ξ / Haken / slaving on the first screen.
+
+## 4.8.11 — 2026-09-02
+
+**Patch** over **4.8.10**. Nested `--config` with `--root` stays inside that
+tree. Library Shape splits `adapterContract` and `agentProjection` so the AI
+edits one concern at a time. **Write. Check. Ship.** **No required config migration.**
+No `schemaVersion` bump. Does not close `K01` / `Z09`. No new skill names.
+
+**Status: published** (on npm `latest`; see `docs/releases/4.8.11.md`).
+
+### Fixed
+- Nested `--config` is a file path: `ark-check --root examples/app --config
+  examples/app/ark.config.json` no longer treats the nested config as a
+  walk-up filename and no longer scans the invoker `cwd` (`include` is relative
+  to `--root`). Basename walk-up still applies when `--config` is
+  `ark.config.json`.
+- `doctorResidentWarm` CI budget ceiling is 680ms (~12% headroom after the
+  adapterContract split). Still far below one-shot doctor.
+
+### Changed
+- Domain Shape: `adapterContract` types/schema and finding-ref helpers are
+  their own modules; the public facade stays under the god-module floors.
+  Callers still import `src/domain/adapterContract.ts`. CLI pure helpers follow
+  the DF03 split.
+- Domain Shape: `agentProjection` types/markers, body/meta formatters, and
+  merge/stamp are their own modules; the public facade re-exports. Callers still
+  import `src/domain/agentProjection.ts`. Generated CLI children stay in
+  DomainModel so the facade does not import Tooling.
+- Dev-tree pins: `browserslist` 4.28.8 (GHSA-73wf-gq98-2v4g) and `fast-uri`
+  3.1.7 (GHSA-5jgf-p345-68v8 and siblings). These are lock/override pins, not a
+  consumer API change.
+
 ## 4.8.10 — 2026-09-02
 
 **Patch** over **4.8.9**. Amarilla first-aggregate sensors. Incomplete analysis
@@ -10,8 +83,7 @@ never looks green: an enforced sensor that cannot see its scope is not a pass.
 **Write. Check. Ship.** **No required config migration.** No `schemaVersion` bump.
 Does not close `K01` / `Z09`. No new skill names.
 
-**Status: prepared** (tree candidate; npm `latest` remains **4.8.9** until the
-signed-tag provenance workflow succeeds).
+**Status: published** (on npm `latest`; see `docs/releases/4.8.10.md`).
 
 ### Added
 - `arkgate report` / `ark report` on the existing dual bins: draft an upstream GitHub issue for

package/README.md

@@ -37,15 +37,15 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.10** is prepared on this tree; npm `latest` remains **4.8.9**.
+> **ArkGate 4.8.13** is prepared on this tree; npm `latest` remains **4.8.11**.
 > Write. Check. Ship. Adopted = required GitHub
 > status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance.
 > Status is compact (`arkgate-check --doctor`; `--all` for Details). Optional **ArkRun**
 > (`arkgate/runtime`) is an in-memory runtime — not Postgres. Optional **ArkOrder**
-> (`arkgate/order`) stops the agent rewriting the few slow product decisions as CRUD;
-> later pattern change is `proposeRelease` then `apply`.
+> (`arkgate/order`) stops rewriting a big product choice — like the billing plan —
+> as if it were a seat count. Change those choices through a valve, not a generic update.
 > `@arkgate/runtime` is deprecated.
-> [4.8.10 prepared](docs/releases/4.8.10.md) · [4.8.9 published](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
+> [4.8.13 prepared](CHANGELOG.md) · [4.8.11 published](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
 
 ---
 
@@ -114,7 +114,7 @@ once you adopt. The other three are optional.
 | **Before merge** | `arkgate-check` as a **required** CI status | Always (ArkGate) |
 | **ArkRules** | Optional policies *inside* a layer | When you ask |
 | **ArkRun** | Optional experimental runtime (`arkgate/runtime`) | Off unless you turn it on |
-| **ArkOrder** | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`). Valve: first `release()`, later ξ is `proposeRelease` then `apply` | Off unless you turn it on |
+| **ArkOrder** | Stops rewriting a big product choice (like billing plan) as if it were a seat count. Change it through a valve, not a generic update (`arkgate/order`) | Off unless you turn it on |
 
 Layers (who may import whom) always run. ArkRules, ArkRun, and ArkOrder change no
 inter-layer verdict when absent. Label leftovers **`[Layer]`** vs **`[ArkRules]`** vs
@@ -231,7 +231,7 @@ expectation.
 | Placement + preflight for multi-file changes | ✅ | ❌ |
 | Honest governed % + dual plan (edges vs shape) | ✅ | ❌ |
 | Opt-in intra-layer ArkRules (structure + invariants) | ✅ | ❌ |
-| Stops agents rewriting slow product decisions as CRUD (ArkOrder) | ✅ | ❌ |
+| Stops rewriting a big product choice like billing plan (ArkOrder) | ✅ | ❌ |
 | Incomplete analysis cannot look green | ✅ | varies |
 
 ---
@@ -302,31 +302,20 @@ interfaces for production. Details: [docs/production-hardening.md](docs/producti
 
 ## Optional ArkOrder
 
-Layers stop a bad import. They do not stop a *legal* import that overwrites the
-billing plan.
-
-If the product can name a few slow decisions in an afternoon — plan, cycle,
-tenancy; a clinical protocol; match rules — an agent will still ship one PUT
-that changes them together with seats and invoices. The write gate stays green
-because “what may be the plan” was never a rule.
-
-**ArkOrder** (`arkgate/order`) is that rule. Off unless you add `arkOrder`.
-Name the slow keys (`xiKeys`: plan, protocol, cost-code bound — not `projectId`).
-A status you can recompute from data you already have is not a slow decision. Derive it. Do not freeze it.
-Posting an invoice is absorbed. Changing plan is `proposeRelease` then `apply`.
-`refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`;
-capacity pack as data; in-memory `ReleaseStore`; `ingestTravelAction`; ArkRun
-`decisionTape`. A generic `update` of the plan does not land. A use-case that
-PATCHes those keys through Prisma is named. Same npm package.
-In-memory. Not durable. Does not replace ArkRun.
-**ArkOrder freezes the pattern through a valve. ArkRun is how the residual travels.**
-
-The billing gallery (`plan` / `cycle` / `tenancy`) lives on GitHub, not in the
-npm tarball:
+Layers stop a bad import. ArkOrder stops rewriting a big product choice — like
+the billing plan — as if it were a seat count. Change those choices through a
+valve, not a generic update.
+
+Off unless you add `arkOrder`. Same npm package (`arkgate/order`). In-memory.
+Not a service. Does not replace ArkGate or ArkRun.
+
+Name the few choices (`xiKeys`: plan, cycle, tenancy — not seat counts). First
+freeze is `release()`. Later change is `proposeRelease` then `apply`. A generic
+`update` does not land.
+
+The billing gallery lives on GitHub, not in the npm tarball:
 [examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing).
-Rename the three keys. Compact starters leave it off. Details:
-[ArkOrder](docs/arkorder.md) · [configuration](docs/configuration.md) ·
-[package surface](docs/package-surface.md).
+Compact starters leave it off. Details: [ArkOrder](docs/arkorder.md).
 
 ---
 
@@ -342,8 +331,10 @@ Rename the three keys. Compact starters leave it off. Details:
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Prepared (4.8.10; not published) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.8.9 on npm `latest`) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |
+| Prepared (4.8.13; not published) | [CHANGELOG](CHANGELOG.md) |
+| Current published (4.8.11 on npm `latest`) | [docs/releases/4.8.11.md](docs/releases/4.8.11.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.8.10) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.8.9) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.7) | [docs/releases/4.8.7.md](docs/releases/4.8.7.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.6) | [docs/releases/4.8.6.md](docs/releases/4.8.6.md) |
 | Prior published (4.8.5) | [docs/releases/4.8.5.md](docs/releases/4.8.5.md) |

package/bin/ark-check-runtime.mjs

@@ -1066,6 +1066,12 @@ function applyConfigRootWalkUp(args) {
   args.configRoot = effective.configRoot;
   args.configFound = effective.configFound;
   args.writeRoot = effective.writeRoot;
+  // Nested relative --config (`examples/app/ark.config.json`) must stay a resolved
+  // file path under --root. Leaving the relative string makes readConfig join it
+  // again and miss; walk-up used to latch the parent instead.
+  if (effective.configFound && typeof effective.configPath === 'string') {
+    args.config = effective.configPath;
+  }
   if (effective.walkedUp && effective.root !== path.resolve(args.root)) {
     // Read paths (or write + --follow-config-root): adopt discovered config root.
     args.root = effective.root;
@@ -1815,6 +1821,7 @@ async function main() {
         mode: fitness.mode,
         improvementCompass: reportCompass,
         arkRun: designDepth?.arkRun ?? null,
+        arkOrder: designDepth?.arkOrder ?? null,
       }),
       leftoverDesignWork: designDepth?.designFitness?.designWeak === true,
     };
@@ -1857,6 +1864,7 @@ async function main() {
           ? { deepModuleCoach: designDepth.deepModuleCoach }
           : {}),
         ...(designDepth?.arkRun ? { arkRun: designDepth.arkRun } : {}),
+        ...(designDepth?.arkOrder ? { arkOrder: designDepth.arkOrder } : {}),
       },
     };
     const html = args.beginner

package/bin/ark-check.mjs

@@ -41,6 +41,9 @@ function residentArgs(argv) {
   // Same monorepo walk-up as full runtime (NEW-MONOREPO-CWD-WALKUP).
   const effective = resolveEffectiveProjectRoot(args.root, { configName: args.config });
   args.configRoot = effective.configRoot;
+  if (effective.configFound && typeof effective.configPath === 'string') {
+    args.config = effective.configPath;
+  }
   if (effective.walkedUp) {
     args.root = effective.root;
     args.configWalkedUp = true;

package/bin/lib/adapter-contract-types.mjs

@@ -0,0 +1,137 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/adapterContractTypes.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/adapter-contract-types.mjs). Zero Node I/O.
+ */
+
+/**
+ * 1.5 adds stable finding refs on every factory-emitted diagnostic (ACS06):
+ * `findingRef`, `targetKey` (baseline-compatible), `docsCodePath`.
+ * 1.4 added optional evidence.arkruleId + evidence.arkruleSource (ADR 0012 / AR03).
+ */
+export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.5';
+/** Repo-relative diagnostics docs path (parity with ACS02 diagnostic catalog). */
+export const ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH = 'docs/diagnostics.md';
+export const ARK_ANALYSIS_RESULT_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://unpkg.com/arkgate@3/schemas/ark.analysis-result.schema.json',
+    title: 'ArkGate analysis result',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schemaVersion',
+        'mode',
+        'valid',
+        'completeness',
+        'completenessReasons',
+        'diagnostics',
+    ],
+    allOf: [
+        {
+            if: {
+                properties: { completeness: { enum: ['partial', 'unavailable'] } },
+                required: ['completeness'],
+            },
+            then: { properties: { valid: { const: false } } },
+        },
+        {
+            if: {
+                properties: {
+                    mode: { const: 'resolved-candidate-facts' },
+                    completeness: { enum: ['complete', 'partial'] },
+                },
+                required: ['mode', 'completeness'],
+            },
+            then: {
+                required: ['policyHash', 'resolverIdentity', 'factsHash', 'candidateTreeHash'],
+            },
+        },
+        {
+            if: {
+                properties: { completeness: { const: 'complete' } },
+                required: ['completeness'],
+            },
+            then: { properties: { completenessReasons: { maxItems: 0 } } },
+            else: { properties: { completenessReasons: { minItems: 1 } } },
+        },
+    ],
+    properties: {
+        schemaVersion: { const: ARK_ANALYSIS_RESULT_SCHEMA_VERSION },
+        mode: { enum: ['lexical-compatibility', 'resolved-candidate-facts'] },
+        valid: { type: 'boolean' },
+        completeness: { enum: ['complete', 'partial', 'unavailable'] },
+        completenessReasons: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['code', 'message'],
+                properties: {
+                    code: { type: 'string', minLength: 1 },
+                    message: { type: 'string', minLength: 1 },
+                    file: { type: 'string', minLength: 1 },
+                },
+            },
+        },
+        policyHash: { type: 'string', minLength: 1 },
+        resolverIdentity: { type: 'string', minLength: 1 },
+        factsHash: { type: 'string', minLength: 1 },
+        candidateTreeHash: { type: 'string', minLength: 1 },
+        diagnostics: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['ruleId', 'severity', 'message', 'location', 'evidence'],
+                properties: {
+                    ruleId: { type: 'string', minLength: 1 },
+                    severity: { enum: ['error', 'warning'] },
+                    message: { type: 'string', minLength: 1 },
+                    location: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['file', 'line', 'column'],
+                        properties: {
+                            file: { type: 'string', minLength: 1 },
+                            line: { type: 'integer', minimum: 1 },
+                            column: { type: 'integer', minimum: 1 },
+                        },
+                    },
+                    evidence: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            target: { type: 'string' },
+                            fromLayer: { type: 'string' },
+                            toLayer: { type: 'string' },
+                            typeOnly: { type: 'boolean' },
+                            targetTypeOnlyExports: { type: 'boolean' },
+                            sourcePureTypeModule: { type: 'boolean' },
+                            namedBindingsTypeOnly: { type: 'boolean' },
+                            portProofEligible: { type: 'boolean' },
+                            peerIsolation: { type: 'boolean' },
+                            capability: { type: 'string', minLength: 1 },
+                            edgeKind: { type: 'string', minLength: 1 },
+                            arkruleId: { type: 'string', minLength: 1 },
+                            arkruleSource: { type: 'string', minLength: 1 },
+                        },
+                    },
+                    nextAction: { type: 'string', minLength: 1 },
+                    /** ACS06 — compact multi-turn id; always derived from targetKey when emitted. */
+                    findingRef: { type: 'string', minLength: 1, pattern: '^fnv1a-[0-9a-f]{8}$' },
+                    /**
+                     * ACS06 — baseline-compatible freeze identity
+                     * (`ruleId|file|from|to|target` with optional `#N` occurrence suffix).
+                     */
+                    targetKey: { type: 'string', minLength: 1 },
+                    /** ACS06 — package-relative diagnostics anchor path. */
+                    docsCodePath: { type: 'string', minLength: 1 },
+                },
+            },
+        },
+    },
+};

package/bin/lib/adapter-contract.mjs

@@ -9,73 +9,16 @@
  */
 
 import { deterministicNextAction } from './remediation.mjs';
-/** Versioned public result contract shared by every ArkGate enforcement adapter. */
-/**
- * 1.5 adds stable finding refs on every factory-emitted diagnostic (ACS06):
- * `findingRef`, `targetKey` (baseline-compatible), `docsCodePath`.
- * 1.4 added optional evidence.arkruleId + evidence.arkruleSource (ADR 0012 / AR03).
- */
-export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.5';
-/** Repo-relative diagnostics docs path (parity with ACS02 diagnostic catalog). */
-export const ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH = 'docs/diagnostics.md';
+import { ARK_ANALYSIS_RESULT_SCHEMA_VERSION, } from './adapter-contract-types.mjs';
+import { adapterDocsCodePath, adapterFindingOccurrenceTargetKeys, adapterFindingRefFromTargetKey, adapterFindingTargetKey, } from './adapter-finding-refs.mjs';
+export { ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH, ARK_ANALYSIS_RESULT_SCHEMA, ARK_ANALYSIS_RESULT_SCHEMA_VERSION, } from './adapter-contract-types.mjs';
+export { adapterDocsCodePath, adapterFindingOccurrenceTargetKeys, adapterFindingRefFromTargetKey, adapterFindingTargetKey, } from './adapter-finding-refs.mjs';
 function text(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 function positiveInteger(value, fallback) {
     return Number.isInteger(value) && Number(value) > 0 ? Number(value) : fallback;
 }
-/**
- * Baseline-compatible target key for a violation input.
- * Field order and empty-string fallbacks **must** match `baselineKey` in
- * `baselineKey.ts` — parity tests guard this so finding refs never orphan freezes.
- *
- * Note: uses raw ruleId/file strings (including empty) the same way baseline does;
- * display `ruleId` / `location.file` may still normalize to ARK_UNKNOWN / `<unknown>`.
- */
-export function adapterFindingTargetKey(violation) {
-    const ruleId = typeof violation.ruleId === 'string'
-        ? violation.ruleId
-        : typeof violation.code === 'string'
-            ? violation.code
-            : undefined;
-    const file = typeof violation.file === 'string' ? violation.file : undefined;
-    const fromLayer = typeof violation.fromLayer === 'string' ? violation.fromLayer : undefined;
-    const toLayer = typeof violation.toLayer === 'string' ? violation.toLayer : undefined;
-    const target = typeof violation.target === 'string' ? violation.target : undefined;
-    return [
-        ruleId,
-        file,
-        fromLayer ?? '',
-        toLayer ?? '',
-        target ?? '',
-    ].join('|');
-}
-/**
- * Occurrence-aware target keys for a violation list (parity with baselineOccurrenceKeys).
- * First occurrence keeps the historical base key; duplicates get `#N`.
- */
-export function adapterFindingOccurrenceTargetKeys(violations) {
-    const counts = new Map();
-    return violations.map((violation) => {
-        const base = adapterFindingTargetKey(violation);
-        const occurrence = (counts.get(base) ?? 0) + 1;
-        counts.set(base, occurrence);
-        return occurrence === 1 ? base : `${base}#${occurrence}`;
-    });
-}
-/** FNV-1a finding ref from a baseline-compatible targetKey (not a security hash). */
-export function adapterFindingRefFromTargetKey(targetKey) {
-    let hash = 0x811c9dc5;
-    for (let index = 0; index < targetKey.length; index += 1) {
-        hash ^= targetKey.charCodeAt(index);
-        hash = Math.imul(hash, 0x01000193);
-    }
-    return `fnv1a-${(hash >>> 0).toString(16).padStart(8, '0')}`;
-}
-/** Package-relative docs path with fragment for a public ruleId. */
-export function adapterDocsCodePath(ruleId) {
-    return `${ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH}#${ruleId}`;
-}
 function nextActionForDiagnostic(ruleId, evidence, violation) {
     return deterministicNextAction({
         ruleId,
@@ -240,122 +183,3 @@ export function createAdapterResult(input) {
     }
     return { ...base, mode, valid: false, completeness, ...evidence };
 }
-export const ARK_ANALYSIS_RESULT_SCHEMA = {
-    $schema: 'https://json-schema.org/draft/2020-12/schema',
-    $id: 'https://unpkg.com/arkgate@3/schemas/ark.analysis-result.schema.json',
-    title: 'ArkGate analysis result',
-    type: 'object',
-    additionalProperties: false,
-    required: [
-        'schemaVersion',
-        'mode',
-        'valid',
-        'completeness',
-        'completenessReasons',
-        'diagnostics',
-    ],
-    allOf: [
-        {
-            if: {
-                properties: { completeness: { enum: ['partial', 'unavailable'] } },
-                required: ['completeness'],
-            },
-            then: { properties: { valid: { const: false } } },
-        },
-        {
-            if: {
-                properties: {
-                    mode: { const: 'resolved-candidate-facts' },
-                    completeness: { enum: ['complete', 'partial'] },
-                },
-                required: ['mode', 'completeness'],
-            },
-            then: {
-                required: ['policyHash', 'resolverIdentity', 'factsHash', 'candidateTreeHash'],
-            },
-        },
-        {
-            if: {
-                properties: { completeness: { const: 'complete' } },
-                required: ['completeness'],
-            },
-            then: { properties: { completenessReasons: { maxItems: 0 } } },
-            else: { properties: { completenessReasons: { minItems: 1 } } },
-        },
-    ],
-    properties: {
-        schemaVersion: { const: ARK_ANALYSIS_RESULT_SCHEMA_VERSION },
-        mode: { enum: ['lexical-compatibility', 'resolved-candidate-facts'] },
-        valid: { type: 'boolean' },
-        completeness: { enum: ['complete', 'partial', 'unavailable'] },
-        completenessReasons: {
-            type: 'array',
-            items: {
-                type: 'object',
-                additionalProperties: false,
-                required: ['code', 'message'],
-                properties: {
-                    code: { type: 'string', minLength: 1 },
-                    message: { type: 'string', minLength: 1 },
-                    file: { type: 'string', minLength: 1 },
-                },
-            },
-        },
-        policyHash: { type: 'string', minLength: 1 },
-        resolverIdentity: { type: 'string', minLength: 1 },
-        factsHash: { type: 'string', minLength: 1 },
-        candidateTreeHash: { type: 'string', minLength: 1 },
-        diagnostics: {
-            type: 'array',
-            items: {
-                type: 'object',
-                additionalProperties: false,
-                required: ['ruleId', 'severity', 'message', 'location', 'evidence'],
-                properties: {
-                    ruleId: { type: 'string', minLength: 1 },
-                    severity: { enum: ['error', 'warning'] },
-                    message: { type: 'string', minLength: 1 },
-                    location: {
-                        type: 'object',
-                        additionalProperties: false,
-                        required: ['file', 'line', 'column'],
-                        properties: {
-                            file: { type: 'string', minLength: 1 },
-                            line: { type: 'integer', minimum: 1 },
-                            column: { type: 'integer', minimum: 1 },
-                        },
-                    },
-                    evidence: {
-                        type: 'object',
-                        additionalProperties: false,
-                        properties: {
-                            target: { type: 'string' },
-                            fromLayer: { type: 'string' },
-                            toLayer: { type: 'string' },
-                            typeOnly: { type: 'boolean' },
-                            targetTypeOnlyExports: { type: 'boolean' },
-                            sourcePureTypeModule: { type: 'boolean' },
-                            namedBindingsTypeOnly: { type: 'boolean' },
-                            portProofEligible: { type: 'boolean' },
-                            peerIsolation: { type: 'boolean' },
-                            capability: { type: 'string', minLength: 1 },
-                            edgeKind: { type: 'string', minLength: 1 },
-                            arkruleId: { type: 'string', minLength: 1 },
-                            arkruleSource: { type: 'string', minLength: 1 },
-                        },
-                    },
-                    nextAction: { type: 'string', minLength: 1 },
-                    /** ACS06 — compact multi-turn id; always derived from targetKey when emitted. */
-                    findingRef: { type: 'string', minLength: 1, pattern: '^fnv1a-[0-9a-f]{8}$' },
-                    /**
-                     * ACS06 — baseline-compatible freeze identity
-                     * (`ruleId|file|from|to|target` with optional `#N` occurrence suffix).
-                     */
-                    targetKey: { type: 'string', minLength: 1 },
-                    /** ACS06 — package-relative diagnostics anchor path. */
-                    docsCodePath: { type: 'string', minLength: 1 },
-                },
-            },
-        },
-    },
-};

package/bin/lib/adapter-finding-refs.mjs

@@ -0,0 +1,63 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/adapterFindingRefs.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/adapter-finding-refs.mjs). Zero Node I/O.
+ */
+
+import { ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH, } from './adapter-contract-types.mjs';
+/**
+ * Baseline-compatible target key for a violation input.
+ * Field order and empty-string fallbacks **must** match `baselineKey` in
+ * `baselineKey.ts` — parity tests guard this so finding refs never orphan freezes.
+ *
+ * Note: uses raw ruleId/file strings (including empty) the same way baseline does;
+ * display `ruleId` / `location.file` may still normalize to ARK_UNKNOWN / `<unknown>`.
+ */
+export function adapterFindingTargetKey(violation) {
+    const ruleId = typeof violation.ruleId === 'string'
+        ? violation.ruleId
+        : typeof violation.code === 'string'
+            ? violation.code
+            : undefined;
+    const file = typeof violation.file === 'string' ? violation.file : undefined;
+    const fromLayer = typeof violation.fromLayer === 'string' ? violation.fromLayer : undefined;
+    const toLayer = typeof violation.toLayer === 'string' ? violation.toLayer : undefined;
+    const target = typeof violation.target === 'string' ? violation.target : undefined;
+    return [
+        ruleId,
+        file,
+        fromLayer ?? '',
+        toLayer ?? '',
+        target ?? '',
+    ].join('|');
+}
+/**
+ * Occurrence-aware target keys for a violation list (parity with baselineOccurrenceKeys).
+ * First occurrence keeps the historical base key; duplicates get `#N`.
+ */
+export function adapterFindingOccurrenceTargetKeys(violations) {
+    const counts = new Map();
+    return violations.map((violation) => {
+        const base = adapterFindingTargetKey(violation);
+        const occurrence = (counts.get(base) ?? 0) + 1;
+        counts.set(base, occurrence);
+        return occurrence === 1 ? base : `${base}#${occurrence}`;
+    });
+}
+/** FNV-1a finding ref from a baseline-compatible targetKey (not a security hash). */
+export function adapterFindingRefFromTargetKey(targetKey) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < targetKey.length; index += 1) {
+        hash ^= targetKey.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+/** Package-relative docs path with fragment for a public ruleId. */
+export function adapterDocsCodePath(ruleId) {
+    return `${ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH}#${ruleId}`;
+}