arkgate 3.9.2 → 4.0.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as ArkConfigRule, b as ArkConfigSchemaVersion, c as ArkConfigLoadResult, d as ArkConfigLayer, A as ArkConfig } from './configTypes-DAPvBqK6.js';
+import { a as ArkConfigRule, b as ArkConfigSchemaVersion, c as ArkConfigLoadResult, d as ArkConfigLayer, A as ArkConfig, e as ArkConfigIssue } from './configTypes-CC0FEXoF.js';
 
 /**
  * Canonical, pure contract for ark.config.json.
@@ -8,6 +8,7 @@ import { a as ArkConfigRule, b as ArkConfigSchemaVersion, c as ArkConfigLoadResu
  * The standalone CLI artifact is generated into bin/lib/config-contract.mjs.
  */
 
+/** Current published ark.config.json schema version (ADR 0012: 1.1 adds optional arkRules). */
 declare const ARK_CONFIG_SCHEMA_VERSION: ArkConfigSchemaVersion;
 declare const ARK_CONFIG_SCHEMA: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
@@ -26,8 +27,8 @@ declare const ARK_CONFIG_SCHEMA: {
         };
         readonly schemaVersion: {
             readonly type: "string";
-            readonly const: "1.0";
-            readonly default: "1.0";
+            readonly const: "1.1";
+            readonly default: "1.1";
         };
         readonly name: {
             readonly type: "string";
@@ -97,6 +98,15 @@ declare const ARK_CONFIG_SCHEMA: {
                 readonly allowDisabledPeerIsolation: false;
             };
         };
+        /** ADR 0012 — layer name → relative path to arkrules/<Layer>.json */
+        readonly arkRules: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly default: {};
+        };
     };
     readonly $defs: {
         readonly layer: {
@@ -234,10 +244,11 @@ declare function loadArkConfigContract(input: unknown, source?: string): ArkConf
 declare function parseArkConfigJson(json: string, source?: string): ArkConfigLoadResult;
 
 /** ArkGate library version — single source of truth. */
-declare const version = "3.9.2";
+declare const version = "4.0.0";
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
-declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.3";
+/** 1.4 adds optional evidence.arkruleId + evidence.arkruleSource (ADR 0012 / AR03). */
+declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.4";
 type AdapterSeverity = 'error' | 'warning';
 type AnalysisCompleteness = 'complete' | 'partial' | 'unavailable';
 type AnalysisMode = 'lexical-compatibility' | 'resolved-candidate-facts';
@@ -267,6 +278,10 @@ type AdapterViolationInput = {
     nextAction?: unknown;
     /** U04: the denied capability id on CAPABILITY_VIOLATION. */
     capability?: unknown;
+    /** AR03: ArkRule identity for structure/invariant diagnostics. */
+    arkruleId?: unknown;
+    /** AR03: project-relative ArkRules source file that declared the rule. */
+    arkruleSource?: unknown;
 };
 type AdapterDiagnostic = {
     ruleId: string;
@@ -289,6 +304,10 @@ type AdapterDiagnostic = {
         peerIsolation?: boolean;
         capability?: string;
         edgeKind?: string;
+        /** AR03 — ArkRule id (structure or invariant). */
+        arkruleId?: string;
+        /** AR03 — ArkRules source file path. */
+        arkruleSource?: string;
     };
     /** Added in schema 1.1; optional in TypeScript so 1.0 consumer-owned values remain valid. */
     nextAction?: string;
@@ -422,7 +441,7 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
     }];
     readonly properties: {
         readonly schemaVersion: {
-            readonly const: "1.3";
+            readonly const: "1.4";
         };
         readonly mode: {
             readonly enum: readonly ["lexical-compatibility", "resolved-candidate-facts"];
@@ -547,6 +566,14 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
                                 readonly type: "string";
                                 readonly minLength: 1;
                             };
+                            readonly arkruleId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly arkruleSource: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
                         };
                     };
                     readonly nextAction: {
@@ -879,7 +906,8 @@ declare function stableSerialize(value: unknown): string;
  * Pure declarations + schema version identity. Create/load live in
  * resolvedCandidateFacts.ts; JSON Schema lives in resolvedCandidateFactsSchema.ts.
  */
-declare const RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION: "1.0";
+/** 1.1 adds optional classShapes[] (ADR 0013). 1.0 payloads remain loadable. */
+declare const RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION: "1.1";
 type ResolvedFactsCompleteness = 'complete' | 'partial' | 'unavailable';
 type ResolvedDependencyKind = 'import' | 'export' | 'dynamic-import' | 'require';
 type ResolvedDependencyState = 'resolved-project' | 'resolved-external' | 'unresolved' | 'dynamic';
@@ -898,6 +926,21 @@ type ResolvedFileFact = {
     typeOnlyExportNames: string[];
     hasTopLevelSideEffects: boolean;
 };
+/** ADR 0013 class-shape evidence for ArkRules structure sensors. */
+type ResolvedClassShapeFact = {
+    file: string;
+    className: string;
+    exported: boolean;
+    hasPublicMutableFields: boolean;
+    hasPublicSetters: boolean;
+    hasPublicConstructor: boolean;
+    hasStaticFactory: boolean;
+    mutatingMethods: readonly {
+        name: string;
+        referencesGuardOrPublish: boolean;
+    }[];
+    dataOnly?: boolean;
+};
 type ResolvedDependencyFact = {
     from: string;
     specifier?: string;
@@ -947,7 +990,7 @@ type ResolvedSafetyFact = {
     symbol?: string;
 };
 type ResolvedCandidateFactsInput = {
-    schemaVersion: typeof RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION;
+    schemaVersion: '1.0' | typeof RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION;
     completeness: ResolvedFactsCompleteness;
     completenessReasons: readonly ResolvedFactsReason[];
     resolverIdentity: string;
@@ -963,8 +1006,11 @@ type ResolvedCandidateFactsInput = {
     publishCalls: readonly ResolvedPublishFact[];
     intentReferences: readonly ResolvedIntentReferenceFact[];
     safetyUses: readonly ResolvedSafetyFact[];
+    /** ADR 0013 — optional on 1.0; default [] on load. */
+    classShapes?: readonly ResolvedClassShapeFact[];
 };
-type ResolvedCandidateFacts = Omit<ResolvedCandidateFactsInput, 'candidateTreeHash'> & {
+type ResolvedCandidateFacts = Omit<ResolvedCandidateFactsInput, 'candidateTreeHash' | 'classShapes'> & {
+    schemaVersion: typeof RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION;
     completenessReasons: ResolvedFactsReason[];
     candidateTreeHash: string;
     files: ResolvedFileFact[];
@@ -974,6 +1020,7 @@ type ResolvedCandidateFacts = Omit<ResolvedCandidateFactsInput, 'candidateTreeHa
     publishCalls: ResolvedPublishFact[];
     intentReferences: ResolvedIntentReferenceFact[];
     safetyUses: ResolvedSafetyFact[];
+    classShapes: ResolvedClassShapeFact[];
     factsHash: string;
 };
 
@@ -998,7 +1045,7 @@ declare const RESOLVED_CANDIDATE_FACTS_SCHEMA: {
     readonly required: readonly ["schemaVersion", "completeness", "completenessReasons", "resolverIdentity", "compilerIdentity", "compilerOptionsHash", "tsconfigHash", "candidateTreeHash", "evidenceRequirementsHash", "files", "dependencies", "capabilityUses", "ambientUses", "publishCalls", "intentReferences", "safetyUses", "factsHash"];
     readonly properties: {
         readonly schemaVersion: {
-            readonly const: "1.0";
+            readonly enum: readonly ["1.0", "1.1"];
         };
         readonly completeness: {
             readonly enum: readonly ["complete", "partial", "unavailable"];
@@ -1363,6 +1410,60 @@ declare const RESOLVED_CANDIDATE_FACTS_SCHEMA: {
                 }];
             };
         };
+        readonly classShapes: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["file", "className", "exported", "hasPublicMutableFields", "hasPublicSetters", "hasPublicConstructor", "hasStaticFactory", "mutatingMethods"];
+                readonly properties: {
+                    readonly file: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly pattern: "^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$";
+                    };
+                    readonly className: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly exported: {
+                        readonly type: "boolean";
+                    };
+                    readonly hasPublicMutableFields: {
+                        readonly type: "boolean";
+                    };
+                    readonly hasPublicSetters: {
+                        readonly type: "boolean";
+                    };
+                    readonly hasPublicConstructor: {
+                        readonly type: "boolean";
+                    };
+                    readonly hasStaticFactory: {
+                        readonly type: "boolean";
+                    };
+                    readonly dataOnly: {
+                        readonly type: "boolean";
+                    };
+                    readonly mutatingMethods: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["name", "referencesGuardOrPublish"];
+                            readonly properties: {
+                                readonly name: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly referencesGuardOrPublish: {
+                                    readonly type: "boolean";
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
         readonly factsHash: {
             readonly type: "string";
             readonly minLength: 1;
@@ -1566,6 +1667,209 @@ declare function extractSemanticDependencies(ts: any, sourceFile: any): Semantic
 /** Resolve forbidden ambient capabilities through symbols, aliases, globalThis, and static keys. */
 declare function collectForbiddenCapabilityUses(ts: any, sourceFile: any, forbidden: readonly string[]): ForbiddenCapabilityUse[];
 
+/**
+ * Type vocabulary for ArkRules files (ADR 0012).
+ *
+ * Pure declarations only — runtime validation and the published JSON Schema live in
+ * ./arkRulesContract.ts so generate:cli-pure can emit a self-contained artifact.
+ */
+/** Closed sensor vocabulary (ADR 0013). Unknown sensors fail closed at load time. */
+declare const ARK_RULE_SENSOR_IDS: readonly ["aggregate-private-state", "always-valid-factory", "domain-event-on-mutation", "orchestration-only", "thin-adapter", "no-anemic-model", "invariant-coverage"];
+type ArkRuleSensorId = (typeof ARK_RULE_SENSOR_IDS)[number];
+type ArkRuleMode = 'advisory' | 'enforced';
+type ArkRuleStructureEntry = {
+    id: string;
+    sensor: ArkRuleSensorId;
+    mode?: ArkRuleMode;
+    appliesTo?: string[];
+    description?: string;
+};
+type ArkRuleInvariantCoverage = {
+    test?: boolean;
+    symbol?: string;
+};
+type ArkRuleInvariantEntry = {
+    id: string;
+    description: string;
+    aggregate?: string;
+    coverage?: ArkRuleInvariantCoverage;
+    mode?: ArkRuleMode;
+    appliesTo?: string[];
+};
+type ArkRulesFile = {
+    $schema?: string;
+    schemaVersion: '1.0';
+    layer: string;
+    structure?: ArkRuleStructureEntry[];
+    invariants?: ArkRuleInvariantEntry[];
+};
+type ArkRuleProvenance = {
+    sourceFile: string;
+    ruleId: string;
+    layer: string;
+};
+type EffectiveStructureRule = ArkRuleStructureEntry & {
+    mode: ArkRuleMode;
+    provenance: ArkRuleProvenance;
+};
+type EffectiveInvariantRule = ArkRuleInvariantEntry & {
+    mode: ArkRuleMode;
+    provenance: ArkRuleProvenance;
+};
+type EffectiveArkRules = {
+    schemaVersion: '1.0';
+    byLayer: Record<string, {
+        sourceFile: string;
+        structure: EffectiveStructureRule[];
+        invariants: EffectiveInvariantRule[];
+    }>;
+    structure: EffectiveStructureRule[];
+    invariants: EffectiveInvariantRule[];
+};
+
+/**
+ * Pure invariant coverage evidence (ADR 0014 / AR09–AR10).
+ *
+ * Mines test titles and symbol presence against the Effective ArkRules catalog.
+ * No filesystem — Tooling supplies file contents and test globs.
+ */
+
+type InvariantCoverageEvidence = {
+    invariantId: string;
+    layer: string;
+    sourceFile: string;
+    mode: 'advisory' | 'enforced';
+    covered: boolean;
+    evidence: Array<'test-title' | 'symbol'>;
+    /** When no test globs were supplied, coverage cannot be proven. */
+    partial: boolean;
+    description: string;
+};
+type InvariantCoverageViolation = {
+    ruleId: 'INVARIANT_UNCOVERED';
+    message: string;
+    file: string;
+    line: number;
+    arkruleId: string;
+    arkruleSource: string;
+    fromLayer: string;
+    severity: 'error' | 'warning';
+    failsStrict: boolean;
+};
+type EvaluateInvariantCoverageInput = {
+    arkRules: EffectiveArkRules;
+    /** Project-relative path → file contents (tests + domain sources). */
+    fileContents: Readonly<Record<string, string>>;
+    /** Paths considered tests (already filtered by Tooling via globs). */
+    testFiles?: readonly string[];
+    /** When true, missing test files make coverage partial (never green covered). */
+    testGlobsMissing?: boolean;
+};
+declare function evaluateInvariantCoverage(input: EvaluateInvariantCoverageInput): {
+    coverage: InvariantCoverageEvidence[];
+    violations: InvariantCoverageViolation[];
+    partial: boolean;
+};
+/**
+ * Deterministic promotion gate: refuse advisory→enforced when invariant is uncovered.
+ */
+declare function canPromoteInvariant(coverage: InvariantCoverageEvidence | undefined): {
+    ok: boolean;
+    reason: string;
+};
+
+/**
+ * Pure ArkRules structure sensor evaluation (ADR 0013).
+ *
+ * Consumes closed class-shape / file facts + Effective ArkRules. Emits violations with
+ * arkrule provenance. No filesystem, no TypeScript compiler.
+ */
+
+type ClassShapeFact = {
+    file: string;
+    className: string;
+    exported: boolean;
+    hasPublicMutableFields: boolean;
+    hasPublicSetters: boolean;
+    hasPublicConstructor: boolean;
+    hasStaticFactory: boolean;
+    mutatingMethods: readonly {
+        name: string;
+        referencesGuardOrPublish: boolean;
+    }[];
+    /** Heuristic: data-only class (fields, no methods beyond accessors). */
+    dataOnly?: boolean;
+};
+type ArkRuleSensorViolation = {
+    ruleId: string;
+    code: string;
+    message: string;
+    file: string;
+    line: number;
+    fromLayer?: string;
+    arkruleId: string;
+    arkruleSource: string;
+    severity: 'error' | 'warning';
+    sensor: ArkRuleSensorId;
+    /** When true, advisory surfaces only (does not fail strict). */
+    failsStrict: boolean;
+};
+type EvaluateArkRuleSensorsInput = {
+    arkRules: EffectiveArkRules;
+    classShapes: readonly ClassShapeFact[];
+    /** Project-relative paths in scope for the analysis. */
+    files: readonly string[];
+    /**
+     * Optional layer membership: path → layer name. When omitted, structure rules
+     * apply by appliesTo globs only (or all files when appliesTo is absent).
+     */
+    layerForFile?: (path: string) => string | null | undefined;
+    /**
+     * Optional thin/orchestration heuristic flags per file (Tooling-supplied).
+     */
+    fileHints?: Readonly<Record<string, {
+        orchestrationHeavy?: boolean;
+        adapterThick?: boolean;
+    }>>;
+};
+/**
+ * Evaluate all structure sensors. Empty Effective Contract → no findings (byte-for-byte parity).
+ */
+declare function evaluateArkRuleSensors(input: EvaluateArkRuleSensorsInput): ArkRuleSensorViolation[];
+/**
+ * ADR 0012 D3 — a structure rule whose appliesTo matches zero governed files is
+ * never silent green. Advisory → warning; enforced → failsStrict.
+ * Rules without appliesTo (whole-layer) never emit this signal.
+ */
+declare function collectEmptyAppliesToFindings(arkRules: EffectiveArkRules, files: readonly string[]): ArkRuleSensorViolation[];
+/**
+ * Pure Tooling/Domain heuristic for orchestration-only / thin-adapter fileHints.
+ * Prefers false negatives over false positives (ADR 0013 discipline).
+ * Returns null when neither flag is set (callers may omit the path).
+ */
+declare function deriveArkRuleFileHints(_file: string, content: string): {
+    orchestrationHeavy?: boolean;
+    adapterThick?: boolean;
+} | null;
+/**
+ * Build fileHints map from path→content. Omits paths with no flags (sparse map).
+ */
+declare function buildArkRuleFileHints(fileContents: Readonly<Record<string, string>>): Record<string, {
+    orchestrationHeavy?: boolean;
+    adapterThick?: boolean;
+}>;
+/**
+ * Lightweight class-shape extraction from TypeScript source text (no compiler).
+ * Conservative: prefers false negatives over false positives for mutability.
+ * Tooling may replace with TypeScript-API facts; sensors consume the same shape.
+ *
+ * Limitation (AR05/AR06): only `export class` / `export abstract class` forms.
+ * `export default class`, re-exported classes, and non-exported aggregates are
+ * invisible — enforced structure sensors stay silent (false negative). Silence
+ * is never proof of compliance.
+ */
+declare function extractClassShapesFromSource(file: string, content: string): ClassShapeFact[];
+
 declare const POLICY_DELTA_SCHEMA_VERSION: "1.0";
 type PolicyDeltaClassification = 'strengthening' | 'neutral' | 'judgment-required' | 'weakening';
 type PolicyDeltaFinding = {
@@ -1589,22 +1893,35 @@ type PolicyDeltaAcknowledgement = {
     findingIds: readonly string[];
     reason: string;
 };
-declare function classifyArkPolicyDelta(base: ArkConfig, candidate: ArkConfig): PolicyDelta;
+type ClassifyArkPolicyDeltaOptions = {
+    baseArkRules?: EffectiveArkRules;
+    candidateArkRules?: EffectiveArkRules;
+    /**
+     * AR11 — coverage evidence for candidate invariants. Required to auto-allow
+     * advisory→enforced promotion; without it (or when uncovered), promotion is
+     * judgment-required / refused.
+     */
+    candidateInvariantCoverage?: readonly InvariantCoverageEvidence[];
+};
+declare function classifyArkPolicyDelta(base: ArkConfig, candidate: ArkConfig, options?: ClassifyArkPolicyDeltaOptions): PolicyDelta;
 declare function policyDeltaAcknowledgementMatches(acknowledgement: PolicyDeltaAcknowledgement | undefined, expected: {
     basePolicyHash: string;
     candidatePolicyHash: string;
     findingIds: readonly string[];
 }): boolean;
 
-/**
- * Public type vocabulary of the canonical analysis API (U02 pilot 2).
- *
- * Declarations only — the C02 entry point src/kernel/analysis.ts re-exports
- * everything here, so consumer import paths never change.
- */
-
 type AnalysisContract = ArkConfigLoadResult & {
     policyHash: string;
+    /**
+     * ADR 0012 Effective ArkRules (empty when arkRules is absent).
+     * Included in policyHash when non-empty so arkrules edits invalidate identity.
+     */
+    arkRules?: EffectiveArkRules;
+    /**
+     * ADR 0013 class-shape facts for ArkRules sensors (Tooling-supplied).
+     * Empty / absent when ArkRules are not active.
+     */
+    classShapes?: ClassShapeFact[];
 };
 type AnalyzeProjectInput = {
     contract: AnalysisContract;
@@ -1625,6 +1942,25 @@ type AnalysisResult = {
 type AnalyzeResolvedProjectInput = {
     contract: AnalysisContract;
     facts: unknown;
+    /**
+     * AR10 — Tooling-supplied contents for invariant coverage evidence.
+     * When omitted and the Effective Contract has invariants, coverage is partial
+     * (never false green covered).
+     */
+    coverageInputs?: {
+        fileContents: Readonly<Record<string, string>>;
+        testFiles?: readonly string[];
+        testGlobsMissing?: boolean;
+    };
+    /**
+     * AR07 — Tooling-supplied orchestration/thin-adapter heuristics per file.
+     * Prefer deriveArkRuleFileHints / buildArkRuleFileHints (Domain pure).
+     * When omitted, orchestration-only and thin-adapter sensors stay silent.
+     */
+    fileHints?: Readonly<Record<string, {
+        orchestrationHeavy?: boolean;
+        adapterThick?: boolean;
+    }>>;
 };
 type PreflightResolvedChangeInput = {
     contract: AnalysisContract;
@@ -1723,6 +2059,14 @@ type AnalyzePolicyDeltaInput = {
     acknowledgement?: PolicyDeltaAcknowledgement;
     baseSource?: string;
     candidateSource?: string;
+    /** Optional pre-resolved Effective ArkRules for each side (ADR 0012 / AR02). */
+    baseArkRules?: EffectiveArkRules;
+    candidateArkRules?: EffectiveArkRules;
+    /**
+     * AR11 — optional coverage evidence for candidate invariants.
+     * When omitted, advisory→enforced promotion is judgment-required (refuse auto-allow).
+     */
+    candidateInvariantCoverage?: readonly InvariantCoverageEvidence[];
 };
 type PolicyDeltaAnalysis = {
     schemaVersion: '1.0';
@@ -1812,13 +2156,164 @@ type CollectAnalysisConfigWarningsInput = {
     };
 };
 
+/**
+ * Canonical, pure contract for arkrules/<Layer>.json (ADR 0012).
+ *
+ * Tooling adapters own filesystem I/O; this module owns JSON parsing, validation,
+ * diagnostics, and the published JSON Schema. The standalone CLI artifact is generated
+ * into bin/lib/arkrules-contract.mjs + schemas/ark.arkrules.schema.json.
+ */
+
+declare const ARK_RULES_SCHEMA_VERSION: "1.0";
+/** Closed sensor vocabulary — keep in lockstep with arkRulesTypes.ARK_RULE_SENSOR_IDS. */
+declare const ARK_RULE_SENSORS: readonly ["aggregate-private-state", "always-valid-factory", "domain-event-on-mutation", "orchestration-only", "thin-adapter", "no-anemic-model", "invariant-coverage"];
+declare const ARK_RULES_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json";
+    readonly title: "ArkGate ArkRules (intra-layer contract)";
+    readonly description: "Per-layer structure sensors and invariant catalog consumed by the ArkGate Effective Contract.";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schemaVersion", "layer"];
+    readonly properties: {
+        readonly $schema: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly default: "https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json";
+        };
+        readonly schemaVersion: {
+            readonly type: "string";
+            readonly const: "1.0";
+            readonly default: "1.0";
+        };
+        readonly layer: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly structure: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly items: {
+                readonly $ref: "#/$defs/structureEntry";
+            };
+        };
+        readonly invariants: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly items: {
+                readonly $ref: "#/$defs/invariantEntry";
+            };
+        };
+    };
+    readonly $defs: {
+        readonly structureEntry: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["id", "sensor"];
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly sensor: {
+                    readonly type: "string";
+                    readonly enum: readonly ["aggregate-private-state", "always-valid-factory", "domain-event-on-mutation", "orchestration-only", "thin-adapter", "no-anemic-model", "invariant-coverage"];
+                };
+                readonly mode: {
+                    readonly type: "string";
+                    readonly enum: readonly ["advisory", "enforced"];
+                    readonly default: "advisory";
+                };
+                readonly appliesTo: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly uniqueItems: true;
+                };
+                readonly description: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly invariantEntry: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["id", "description"];
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly description: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly aggregate: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly coverage: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly test: {
+                            readonly type: "boolean";
+                        };
+                        readonly symbol: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                    };
+                };
+                readonly mode: {
+                    readonly type: "string";
+                    readonly enum: readonly ["advisory", "enforced"];
+                    readonly default: "advisory";
+                };
+                readonly appliesTo: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly uniqueItems: true;
+                };
+            };
+        };
+    };
+};
+declare function loadArkRulesContract(input: unknown, source?: string, expectedLayer?: string): {
+    config: ArkRulesFile;
+};
+declare function parseArkRulesJson(json: string, source?: string, expectedLayer?: string): {
+    config: ArkRulesFile;
+};
+/**
+ * Build the Effective Contract from already-validated ArkRules files.
+ * Callers supply `{ layer → { sourceFile, file } }` after resolving references.
+ */
+declare function buildEffectiveArkRules(parts: ReadonlyArray<{
+    layer: string;
+    sourceFile: string;
+    file: ArkRulesFile;
+}>): EffectiveArkRules;
+/** Empty Effective Contract used when `arkRules` is absent (byte-for-byte verdict parity). */
+declare function emptyEffectiveArkRules(): EffectiveArkRules;
+
 /**
  * Contract loading, project/change analysis, and policy-delta analysis
  * (U02 pilot 2). Reached through the src/kernel/analysis.ts facade; consumer
  * import paths never change.
  */
 
-declare function loadContract(input: unknown, source?: string): AnalysisContract;
+type LoadContractOptions = {
+    /** Pre-resolved Effective ArkRules (from resolveEffectiveContract). */
+    arkRules?: EffectiveArkRules;
+};
+declare function loadContract(input: unknown, source?: string, options?: LoadContractOptions): AnalysisContract;
 declare function analyzePolicyDelta(input: AnalyzePolicyDeltaInput): PolicyDeltaAnalysis;
 declare function analyzeProject(input: AnalyzeProjectInput): AnalysisResult;
 declare function analyzeChange(input: AnalyzeChangeInput): AnalysisResult;
@@ -1856,6 +2351,106 @@ declare function preflightResolvedChange(input: PreflightResolvedChangeInput): R
 /** Canonical config diagnostics over repo-relative file paths. */
 declare function collectAnalysisConfigWarnings(input: CollectAnalysisConfigWarningsInput): ArchitectureEngineViolation[];
 
+/**
+ * Pure Effective Contract composition (ADR 0012).
+ *
+ * Resolves `arkRules` references against a supplied file-content map (Tooling owns I/O),
+ * validates each part, and returns one in-memory contract with per-rule provenance.
+ * The serialized effective rules feed policyHash via the analysis contract loader.
+ */
+
+type EffectiveContractWarning = {
+    path: string;
+    message: string;
+    /** advisory | error — errors fail closed; warnings surface drift (unreferenced files). */
+    severity: 'advisory' | 'error';
+};
+type EffectiveContract = {
+    config: ArkConfig;
+    arkRules: EffectiveArkRules;
+    warnings: EffectiveContractWarning[];
+};
+type ResolveEffectiveContractInput = {
+    config: ArkConfig;
+    /**
+     * Project-relative path → file contents. Missing keys mean the file is absent.
+     * Paths must use forward slashes and match the arkRules map values exactly.
+     */
+    fileContents: Readonly<Record<string, string>>;
+    /**
+     * Optional inventory of files under arkrules/ (or other dirs) used only to
+     * detect unreferenced ArkRules files (advisory drift).
+     */
+    discoveredArkRulesFiles?: readonly string[];
+};
+declare class EffectiveContractError extends Error {
+    readonly issues: ArkConfigIssue[];
+    readonly source: string;
+    constructor(source: string, issues: ArkConfigIssue[]);
+}
+/**
+ * Resolve arkRules references into a single Effective Contract.
+ * Fail-closed for missing, unparsable, or schema-invalid referenced files.
+ */
+declare function resolveEffectiveContract(input: ResolveEffectiveContractInput, source?: string): EffectiveContract;
+/**
+ * Canonical payload for policyHash: root config + sorted effective ArkRules.
+ * Absence of arkRules yields the same payload shape with empty structure/invariants.
+ */
+declare function effectiveContractPolicyPayload(contract: EffectiveContract): unknown;
+
+/**
+ * Deterministic brownfield rules inventory (AR13).
+ *
+ * Scans supplied file contents for spaghetti rule candidates:
+ * validation-in-controller, magic business constants, anemic entities.
+ * Confidence is direct-evidence | heuristic — never a numeric score.
+ */
+type RulesInventoryConfidence = 'direct-evidence' | 'heuristic';
+type RulesInventoryCandidate = {
+    id: string;
+    kind: 'validation-in-controller' | 'magic-business-constant' | 'anemic-entity' | 'mutation-without-guard';
+    file: string;
+    line: number;
+    message: string;
+    confidence: RulesInventoryConfidence;
+    suggestedArkRule?: {
+        layer: string;
+        structureId?: string;
+        sensor?: string;
+        invariantId?: string;
+    };
+    neverMechanicalSafe: true;
+};
+type RulesInventoryResult = {
+    candidates: RulesInventoryCandidate[];
+    inventoried: number;
+    underContract: number;
+    frozen: number;
+    notAScore: true;
+};
+type BuildRulesInventoryInput = {
+    fileContents: Readonly<Record<string, string>>;
+    /** Invariant / structure ids already under contract (to compute underContract count). */
+    contractedRuleIds?: readonly string[];
+    /** Baseline keys currently frozen for arkrule residual. */
+    frozenKeys?: readonly string[];
+};
+declare function buildRulesInventory(input: BuildRulesInventoryInput): RulesInventoryResult;
+/** Build a pilotLoop extraction card for the top inventory candidate (AR14). */
+declare function inventoryToExtractionCard(candidate: RulesInventoryCandidate): {
+    pilot: string;
+    pilotTarget: string;
+    smellId: string;
+    move: string;
+    doNot: string[];
+    successSignal: string;
+    killSwitch: string;
+    neverMechanicalSafe: true;
+    class: 'judgment';
+    next: string;
+};
+
 /** Public, evidence-backed enforcement state shared by doctor adapters. */
 declare const ARK_ENFORCEMENT_STATE_SCHEMA_VERSION: "1.1";
 type EnforcementVerification = boolean | 'unverified';
@@ -1943,4 +2538,4 @@ type ArkDesignDeltaResult = {
     error?: string;
 };
 
-export { type AICodeGate, type AICodeGateContext, type AICodeGateOptions, type AICodeGateResult, type AICodeGateViolation, type AIGateExtension, ANALYSIS_IR_SCHEMA_VERSION, ARK_ANALYSIS_RESULT_SCHEMA, ARK_ANALYSIS_RESULT_SCHEMA_VERSION, ARK_CONFIG_SCHEMA, ARK_CONFIG_SCHEMA_VERSION, ARK_DESIGN_DELTA_SCHEMA_VERSION, ARK_ENFORCEMENT_STATE_SCHEMA_VERSION, type AdapterCompletenessReason, type AdapterDiagnostic, type AdapterResult, type AdapterSeverity, type AdapterViolationInput, type AnalysisCapabilityUse, type AnalysisCompilerOptions, type AnalysisCompleteness, type AnalysisContract, type AnalysisEvidence, type AnalysisFile, type AnalysisFileChange, type AnalysisFileInput, type AnalysisImportEdge, type AnalysisIr, type AnalysisMode, type AnalysisResult, type AnalysisViolation, type AnalyzeArchitectureConvergenceInput, type AnalyzeChangeInput, type AnalyzePolicyDeltaInput, type AnalyzeProjectInput, type AnalyzeResolvedProjectInput, type ArchitectureActualChange, type ArchitectureChangeMap, type ArchitectureChangeMapContract, type ArchitectureChangeMapDependency, type ArchitectureChangeMapFile, type ArchitectureChangeOperation, type ArchitectureConvergenceClassification, type ArchitectureConvergenceFinding, type ArchitectureConvergenceResult, type ArchitectureDependency, type ArchitectureEngineEdge, type ArchitectureEngineResult, type ArchitectureEngineViolation, type ArchitectureLayer, type ArchitectureLayerConfig, type ArchitectureProfile, type ArchitectureRule, type ArkCheckConfig, ArkConfig, ArkConfigLoadResult, type ArkDesignDeltaResult, type ArkEnforcementHost, type ArkEnforcementState, type ChangePreflightResult, type CollectAnalysisConfigWarningsInput, type CreateArchitectureProfileFromArkConfigOptions, type CreateArchitectureProfileOptions, type CreateElevenLayerArkConfigOptions, type DesignDeltaChange, type DesignDeltaIdentity, type DesignSmellEvidence, type DesignSmellFinding, type DesignSmellId, type EnforcementBoundaryState, type EnforcementEvidence, type EnforcementEvidenceField, type EnforcementVerification, type EvaluateArchitectureGraphInput, type ForbiddenCapabilityUse, POLICY_DELTA_SCHEMA_VERSION, type PolicyDelta, type PolicyDeltaAcknowledgement, type PolicyDeltaAnalysis, type PolicyDeltaClassification, type PolicyDeltaFinding, type PreflightResolvedChangeInput, type PreparedChangeFile, RESOLVED_CANDIDATE_FACTS_SCHEMA, RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION, type ResolvedAmbientFact, type ResolvedAnalysisFile, type ResolvedAnalysisIr, type ResolvedAnalysisResult, type ResolvedCandidateFacts, type ResolvedCandidateFactsInput, type ResolvedCapability, type ResolvedCapabilityFact, type ResolvedChangePreflightResult, type ResolvedDependencyFact, type ResolvedDependencyKind, type ResolvedDependencyState, type ResolvedFactsCompleteness, type ResolvedFactsReason, type ResolvedFileFact, type ResolvedIntentReferenceFact, type ResolvedPublishFact, type ResolvedSafetyFact, type ResolvedSafetyKind, type ResolvedSafetyReport, type SemanticDependency, type SemanticDependencyKind, analyzeArchitectureConvergence, analyzeChange, analyzePolicyDelta, analyzeProject, analyzeResolvedProject, classifyArkPolicyDelta, collectAnalysisConfigWarnings, collectForbiddenCapabilityUses, createAICodeGate, createAdapterResult, createArchitectureProfile, createArchitectureProfileFromArkConfig, createElevenLayerArkConfig, createResolvedCandidateFacts, detectArchitectureCycles, deterministicHash, elevenLayerProfile, evaluateArchitectureGraph, explainViolation, extractSemanticDependencies, loadArkConfigContract, loadContract, loadResolvedCandidateFacts, parseArkConfigJson, policyDeltaAcknowledgementMatches, preflightChange, preflightResolvedChange, resolvedFactsEvidenceRequirementsHash, stableSerialize, toAdapterDiagnostic, version };
+export { type AICodeGate, type AICodeGateContext, type AICodeGateOptions, type AICodeGateResult, type AICodeGateViolation, type AIGateExtension, ANALYSIS_IR_SCHEMA_VERSION, ARK_ANALYSIS_RESULT_SCHEMA, ARK_ANALYSIS_RESULT_SCHEMA_VERSION, ARK_CONFIG_SCHEMA, ARK_CONFIG_SCHEMA_VERSION, ARK_DESIGN_DELTA_SCHEMA_VERSION, ARK_ENFORCEMENT_STATE_SCHEMA_VERSION, ARK_RULES_SCHEMA, ARK_RULES_SCHEMA_VERSION, ARK_RULE_SENSORS, type AdapterCompletenessReason, type AdapterDiagnostic, type AdapterResult, type AdapterSeverity, type AdapterViolationInput, type AnalysisCapabilityUse, type AnalysisCompilerOptions, type AnalysisCompleteness, type AnalysisContract, type AnalysisEvidence, type AnalysisFile, type AnalysisFileChange, type AnalysisFileInput, type AnalysisImportEdge, type AnalysisIr, type AnalysisMode, type AnalysisResult, type AnalysisViolation, type AnalyzeArchitectureConvergenceInput, type AnalyzeChangeInput, type AnalyzePolicyDeltaInput, type AnalyzeProjectInput, type AnalyzeResolvedProjectInput, type ArchitectureActualChange, type ArchitectureChangeMap, type ArchitectureChangeMapContract, type ArchitectureChangeMapDependency, type ArchitectureChangeMapFile, type ArchitectureChangeOperation, type ArchitectureConvergenceClassification, type ArchitectureConvergenceFinding, type ArchitectureConvergenceResult, type ArchitectureDependency, type ArchitectureEngineEdge, type ArchitectureEngineResult, type ArchitectureEngineViolation, type ArchitectureLayer, type ArchitectureLayerConfig, type ArchitectureProfile, type ArchitectureRule, type ArkCheckConfig, ArkConfig, ArkConfigLoadResult, type ArkDesignDeltaResult, type ArkEnforcementHost, type ArkEnforcementState, type ArkRuleSensorViolation, type ArkRulesFile, type ChangePreflightResult, type ClassShapeFact, type CollectAnalysisConfigWarningsInput, type CreateArchitectureProfileFromArkConfigOptions, type CreateArchitectureProfileOptions, type CreateElevenLayerArkConfigOptions, type DesignDeltaChange, type DesignDeltaIdentity, type DesignSmellEvidence, type DesignSmellFinding, type DesignSmellId, type EffectiveArkRules, type EffectiveContract, EffectiveContractError, type EffectiveContractWarning, type EnforcementBoundaryState, type EnforcementEvidence, type EnforcementEvidenceField, type EnforcementVerification, type EvaluateArchitectureGraphInput, type ForbiddenCapabilityUse, type InvariantCoverageEvidence, POLICY_DELTA_SCHEMA_VERSION, type PolicyDelta, type PolicyDeltaAcknowledgement, type PolicyDeltaAnalysis, type PolicyDeltaClassification, type PolicyDeltaFinding, type PreflightResolvedChangeInput, type PreparedChangeFile, RESOLVED_CANDIDATE_FACTS_SCHEMA, RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION, type ResolvedAmbientFact, type ResolvedAnalysisFile, type ResolvedAnalysisIr, type ResolvedAnalysisResult, type ResolvedCandidateFacts, type ResolvedCandidateFactsInput, type ResolvedCapability, type ResolvedCapabilityFact, type ResolvedChangePreflightResult, type ResolvedDependencyFact, type ResolvedDependencyKind, type ResolvedDependencyState, type ResolvedFactsCompleteness, type ResolvedFactsReason, type ResolvedFileFact, type ResolvedIntentReferenceFact, type ResolvedPublishFact, type ResolvedSafetyFact, type ResolvedSafetyKind, type ResolvedSafetyReport, type RulesInventoryCandidate, type RulesInventoryResult, type SemanticDependency, type SemanticDependencyKind, analyzeArchitectureConvergence, analyzeChange, analyzePolicyDelta, analyzeProject, analyzeResolvedProject, buildArkRuleFileHints, buildEffectiveArkRules, buildRulesInventory, canPromoteInvariant, classifyArkPolicyDelta, collectAnalysisConfigWarnings, collectEmptyAppliesToFindings, collectForbiddenCapabilityUses, createAICodeGate, createAdapterResult, createArchitectureProfile, createArchitectureProfileFromArkConfig, createElevenLayerArkConfig, createResolvedCandidateFacts, deriveArkRuleFileHints, detectArchitectureCycles, deterministicHash, effectiveContractPolicyPayload, elevenLayerProfile, emptyEffectiveArkRules, evaluateArchitectureGraph, evaluateArkRuleSensors, evaluateInvariantCoverage, explainViolation, extractClassShapesFromSource, extractSemanticDependencies, inventoryToExtractionCard, loadArkConfigContract, loadArkRulesContract, loadContract, loadResolvedCandidateFacts, parseArkConfigJson, parseArkRulesJson, policyDeltaAcknowledgementMatches, preflightChange, preflightResolvedChange, resolveEffectiveContract, resolvedFactsEvidenceRequirementsHash, stableSerialize, toAdapterDiagnostic, version };