arkgate 4.2.0 → 4.3.0

package/dist/index.d.ts

@@ -244,11 +244,17 @@ 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 = "4.2.0";
+declare const version = "4.3.0";
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
-/** 1.4 adds optional evidence.arkruleId + evidence.arkruleSource (ADR 0012 / AR03). */
-declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.4";
+/**
+ * 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).
+ */
+declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.5";
+/** Repo-relative diagnostics docs path (parity with ACS02 diagnostic catalog). */
+declare const ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH: "docs/diagnostics.md";
 type AdapterSeverity = 'error' | 'warning';
 type AnalysisCompleteness = 'complete' | 'partial' | 'unavailable';
 type AnalysisMode = 'lexical-compatibility' | 'resolved-candidate-facts';
@@ -313,6 +319,23 @@ type AdapterDiagnostic = {
     };
     /** Added in schema 1.1; optional in TypeScript so 1.0 consumer-owned values remain valid. */
     nextAction?: string;
+    /**
+     * ACS06 / schema 1.5 — compact stable id for multi-turn re-address
+     * (`fnv1a-` + hex). Always derived from `targetKey`. Optional so 1.0–1.4
+     * consumer-owned diagnostics remain assignable.
+     */
+    findingRef?: string;
+    /**
+     * ACS06 / schema 1.5 — baseline-compatible freeze identity
+     * (`ruleId|file|fromLayer|toLayer|target`, with occurrence `#N` suffixes in lists).
+     * Must match `baselineKey` / `baselineOccurrenceKeys` so refs never orphan baselines.
+     */
+    targetKey?: string;
+    /**
+     * ACS06 / schema 1.5 — package-relative docs path with rule anchor
+     * (`docs/diagnostics.md#RULE_ID`). Optional for legacy consumer-owned values.
+     */
+    docsCodePath?: string;
 };
 type LegacyAdapterResult = {
     schemaVersion: '1.0' | '1.1';
@@ -366,7 +389,30 @@ type CurrentAdapterResult = (CurrentAdapterResultBase & Partial<ResolvedAdapterE
     completeness: 'unavailable';
 });
 type AdapterResult = LegacyAdapterResult | Version12AdapterResult | CurrentAdapterResult;
-declare function toAdapterDiagnostic(violation: AdapterViolationInput, fallbackSeverity?: AdapterSeverity): AdapterDiagnostic;
+/**
+ * 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>`.
+ */
+declare function adapterFindingTargetKey(violation: AdapterViolationInput): string;
+/**
+ * Occurrence-aware target keys for a violation list (parity with baselineOccurrenceKeys).
+ * First occurrence keeps the historical base key; duplicates get `#N`.
+ */
+declare function adapterFindingOccurrenceTargetKeys(violations: readonly AdapterViolationInput[]): string[];
+/** FNV-1a finding ref from a baseline-compatible targetKey (not a security hash). */
+declare function adapterFindingRefFromTargetKey(targetKey: string): string;
+/** Package-relative docs path with fragment for a public ruleId. */
+declare function adapterDocsCodePath(ruleId: string): string;
+declare function toAdapterDiagnostic(violation: AdapterViolationInput, fallbackSeverity?: AdapterSeverity, 
+/**
+ * Optional precomputed baseline-compatible targetKey (e.g. occurrence-aware from
+ * `adapterFindingOccurrenceTargetKeys`). When omitted, uses the first-occurrence key.
+ */
+targetKeyOverride?: string): AdapterDiagnostic;
 declare function createAdapterResult(input: {
     valid: boolean;
     completeness?: AnalysisCompleteness;
@@ -443,7 +489,7 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
     }];
     readonly properties: {
         readonly schemaVersion: {
-            readonly const: "1.4";
+            readonly const: "1.5";
         };
         readonly mode: {
             readonly enum: readonly ["lexical-compatibility", "resolved-candidate-facts"];
@@ -582,6 +628,25 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
                         readonly type: "string";
                         readonly minLength: 1;
                     };
+                    /** ACS06 — compact multi-turn id; always derived from targetKey when emitted. */
+                    readonly findingRef: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly pattern: "^fnv1a-[0-9a-f]{8}$";
+                    };
+                    /**
+                     * ACS06 — baseline-compatible freeze identity
+                     * (`ruleId|file|from|to|target` with optional `#N` occurrence suffix).
+                     */
+                    readonly targetKey: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    /** ACS06 — package-relative diagnostics anchor path. */
+                    readonly docsCodePath: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
                 };
             };
         };
@@ -2732,4 +2797,662 @@ 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, ARK_PROJECT_IDENTITY_SCHEMA, ARK_PROJECT_IDENTITY_SCHEMA_URL, ARK_PROJECT_IDENTITY_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, PROJECT_BINDING_SCHEMA, PROJECT_EXPECTATION_SCHEMA, type PolicyDelta, type PolicyDeltaAcknowledgement, type PolicyDeltaAnalysis, type PolicyDeltaClassification, type PolicyDeltaFinding, type PreflightResolvedChangeInput, type PreparedChangeFile, type ProjectBinding, type ProjectExpectation, type ProjectIdentity, 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, createProjectId, createProjectIdentity, 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 };
+/**
+ * Public diagnostic code catalog (ACS02).
+ *
+ * Closed vocabulary of stable `ruleId` values emitted by ArkGate adapters with
+ * human/agent `why` / `fix` anchors and docs fragment ids. Cataloguing only —
+ * no new rule semantics, no LLM verdict, no enforcement from prose.
+ *
+ * **Canonical** for docs, agent projection (ACS04), and finding refs (ACS06).
+ * Runtime remediation remains in `remediation.ts`; parity tests bind the two.
+ *
+ * Zero Node I/O. Optional CLI surface: generated `bin/lib/diagnostic-catalog.mjs`.
+ *
+ * @see docs/diagnostics.md
+ * @see docs/plans/agent-contract-surface-4.3/README.md
+ */
+/** Product-relative docs path (shipped in the npm tarball when listed in package files). */
+declare const DIAGNOSTIC_DOCS_RELATIVE_PATH: "docs/diagnostics.md";
+/** Schema id for serializing the catalog snapshot (agents / install projection). */
+declare const DIAGNOSTIC_CATALOG_SCHEMA_VERSION: "1.0";
+type DiagnosticCategory = 'layer' | 'capability' | 'publish' | 'safety' | 'arkrules' | 'preflight' | 'analysis' | 'snippet-policy' | 'config' | 'adapter' | 'meta';
+type DiagnosticCatalogEntry = {
+    /** Stable public violation / diagnostic id. */
+    ruleId: string;
+    /** Short title for indexes and agent projection. */
+    title: string;
+    /** Why this finding exists (contract intent). */
+    why: string;
+    /**
+     * Canonical fix guidance (agent + human). Contextual nextAction on live
+     * findings may specialize this (e.g. type-only vs value layer import).
+     */
+    fix: string;
+    /** Markdown fragment id for docs/diagnostics.md (without leading #). */
+    docsAnchor: string;
+    category: DiagnosticCategory;
+    /**
+     * When true, finding is commonly advisory / non-blocking in default profiles
+     * (doctor/config warnings, type-only placement debt, empty ArkRule scope).
+     * Not a severity bit for the engine — documentation only.
+     */
+    oftenAdvisory?: boolean;
+};
+/**
+ * Closed public catalog. Order is stable (category groups, then ruleId) for
+ * deterministic serialization and docs generation.
+ *
+ * Every production-emitted `ruleId` must appear here. Remediation switch cases
+ * and adapter nextAction branches are parity-tested against this list.
+ */
+declare const DIAGNOSTIC_CATALOG: readonly DiagnosticCatalogEntry[];
+/** All public ruleIds in catalog order. */
+declare const DIAGNOSTIC_RULE_IDS: readonly string[];
+declare function isKnownDiagnosticCode(ruleId: string | null | undefined): boolean;
+/**
+ * True when the code is catalogued or is an ArkRule-family id handled by the
+ * ARKRULE_* prefix fallback in remediation (structure sensors may add members later
+ * only via catalog + ROADMAP — prefix alone is not a license for free-form ids).
+ */
+declare function isCataloguedOrArkRuleFamily(ruleId: string | null | undefined): boolean;
+declare function getDiagnosticCatalogEntry(ruleId: string | null | undefined): DiagnosticCatalogEntry | undefined;
+/** Fragment for docs links, e.g. `#LAYER_IMPORT_VIOLATION`. */
+declare function diagnosticDocsFragment(ruleId: string): string;
+/**
+ * Repo-relative docs path with fragment (for agents and JSON).
+ * Package consumers resolve against the installed package root or GitHub tree.
+ */
+declare function diagnosticDocsPath(ruleId: string): string;
+/** Catalog snapshot for JSON export / agent projection (stable field order). */
+declare function serializeDiagnosticCatalog(): {
+    schemaVersion: typeof DIAGNOSTIC_CATALOG_SCHEMA_VERSION;
+    docsPath: typeof DIAGNOSTIC_DOCS_RELATIVE_PATH;
+    codes: readonly DiagnosticCatalogEntry[];
+};
+/**
+ * Static catalog fix for a ruleId when no live violation context is available.
+ * Live adapters should still use deterministicNextAction for specialized edges.
+ */
+declare function catalogFixForRuleId(ruleId: string | null | undefined): string | undefined;
+/**
+ * Static catalog why for a ruleId (agent “why” surface).
+ */
+declare function catalogWhyForRuleId(ruleId: string | null | undefined): string | undefined;
+
+/**
+ * Public status manifest (ACS03).
+ *
+ * One machine-readable session/project snapshot for agents: project identity
+ * binding, honest write-path activation, last-check summary, ArkRules residual
+ * counts, and a primary next action. Binary facts only — never a numeric score,
+ * never an LLM verdict, never a prompt.
+ *
+ * **Canonical** for `ark status --json`, MCP `ark_status`, and schema export.
+ * Tooling gathers filesystem evidence; this module only assembles pure facts.
+ *
+ * @see docs/plans/agent-contract-surface-4.3/README.md
+ */
+
+declare const ARK_STATUS_MANIFEST_SCHEMA_VERSION: "1.0";
+declare const ARK_STATUS_MANIFEST_SCHEMA_URL = "https://unpkg.com/arkgate@4/schemas/ark.status-manifest.schema.json";
+/** Write-path honesty class for agents (not a host capability claim by itself). */
+type StatusWritePathClass = 'hard' | 'advisory' | 'unavailable';
+/** Last architecture check verdict when evidence exists. */
+type StatusCheckVerdict = 'pass' | 'fail' | 'incomplete' | null;
+type StatusProjectIdentitySlice = {
+    projectId: string | null;
+    resolvedRoot: string;
+    resolvedConfigPath: string | null;
+    /** Binding status: matched | unverified | mismatch (same vocabulary as MCP). */
+    binding: ProjectBinding['status'];
+    authoritative: boolean;
+    code?: ProjectBinding['code'];
+    message?: string;
+};
+type StatusActivationSlice = {
+    writePath: StatusWritePathClass;
+    host: string | null;
+    honestLabel: string;
+};
+type StatusLastCheckSlice = {
+    at: string | null;
+    verdict: StatusCheckVerdict;
+    activeViolations: number | null;
+    frozenResidual: number | null;
+};
+type StatusRulesSlice = {
+    arkRulesLoaded: boolean;
+    inventoried: number | null;
+    underContract: number | null;
+    frozenResidual: number | null;
+};
+type StatusNextAction = {
+    id: string;
+    summary: string;
+};
+type StatusManifest = {
+    schemaVersion: typeof ARK_STATUS_MANIFEST_SCHEMA_VERSION;
+    arkgateVersion: string;
+    projectIdentity: StatusProjectIdentitySlice;
+    activation: StatusActivationSlice;
+    lastCheck: StatusLastCheckSlice;
+    rules: StatusRulesSlice;
+    nextAction: StatusNextAction;
+};
+/**
+ * Pure facts supplied by Tooling after path canonicalization and I/O.
+ * Domain never opens files or prompts.
+ */
+type StatusManifestFacts = {
+    arkgateVersion: string;
+    resolvedRoot: string;
+    resolvedConfigPath?: string | null;
+    projectId?: string | null;
+    /**
+     * Optional agent expectation (same shape as MCP `project`).
+     * Omitted → binding reflects local CLI session (matched when a project root resolved).
+     */
+    expectation?: ProjectExpectation | null;
+    /**
+     * Precomputed root relation when expectation.expectedRoot is set.
+     * Tooling must canonicalize before comparing.
+     * - exact: expectedRoot === resolvedRoot
+     * - descendant: expected is inside project but not the root
+     * - outside: not within this project
+     * - unknown: could not evaluate (fail closed → unverified)
+     */
+    expectedRootRelation?: 'exact' | 'descendant' | 'outside' | 'unknown' | null;
+    /** Active agent host id (claude, cursor, codex, …) or null/unknown. */
+    activeHost?: string | null;
+    /** Evidence-backed hard local write for this invocation. */
+    hardWriteActive?: boolean;
+    /** Host is soft-write only (Cursor/Codex/OpenCode class). */
+    softWriteHost?: boolean;
+    /** Package/host write boundary could not be analyzed. */
+    writePathUnavailable?: boolean;
+    honestLabel?: string | null;
+    lastCheckAt?: string | null;
+    lastCheckVerdict?: StatusCheckVerdict;
+    activeViolations?: number | null;
+    frozenResidual?: number | null;
+    arkRulesLoaded?: boolean;
+    rulesInventoried?: number | null;
+    rulesUnderContract?: number | null;
+    rulesFrozenResidual?: number | null;
+    /** Optional override when Tooling already computed productHonesty next action. */
+    nextActionOverride?: StatusNextAction | null;
+};
+/**
+ * Evaluate project binding for status without filesystem.
+ * Paths must already be canonical absolute strings when compared.
+ */
+declare function evaluateStatusBinding(input: {
+    resolvedRoot: string;
+    projectId: string | null | undefined;
+    expectation?: ProjectExpectation | null;
+    expectedRootRelation?: StatusManifestFacts['expectedRootRelation'];
+}): ProjectBinding;
+/**
+ * Map write-path evidence to the closed activation writePath vocabulary.
+ * Soft hosts never become hard; missing analysis → unavailable.
+ */
+declare function classifyStatusWritePath(input: {
+    hardWriteActive?: boolean;
+    softWriteHost?: boolean;
+    writePathUnavailable?: boolean;
+    activeHost?: string | null;
+}): StatusWritePathClass;
+declare function defaultHonestLabel(writePath: StatusWritePathClass, host: string | null): string;
+/**
+ * Deterministic next action from residual facts (no LLM).
+ * Prefer explicit override from productHonesty when provided.
+ */
+declare function resolveStatusNextAction(facts: StatusManifestFacts, binding: ProjectBinding, activation: StatusActivationSlice, lastCheck: StatusLastCheckSlice, rules: StatusRulesSlice): StatusNextAction;
+declare function buildStatusManifest(facts: StatusManifestFacts): StatusManifest;
+/** JSON Schema for the public status manifest (package export + agents). */
+declare const ARK_STATUS_MANIFEST_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://unpkg.com/arkgate@4/schemas/ark.status-manifest.schema.json";
+    readonly title: "ArkGate status manifest";
+    readonly description: "Unified session/project status snapshot for agents (identity, activation honesty, last check, rules counts, next action). Not a score.";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schemaVersion", "arkgateVersion", "projectIdentity", "activation", "lastCheck", "rules", "nextAction"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly const: "1.0";
+        };
+        readonly arkgateVersion: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly projectIdentity: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["projectId", "resolvedRoot", "resolvedConfigPath", "binding", "authoritative"];
+            readonly properties: {
+                readonly projectId: {
+                    readonly anyOf: readonly [{
+                        readonly type: "string";
+                        readonly pattern: "^sha256:[a-f0-9]{64}$";
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly resolvedRoot: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly resolvedConfigPath: {
+                    readonly anyOf: readonly [{
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly binding: {
+                    readonly enum: readonly ["matched", "unverified", "mismatch"];
+                };
+                readonly authoritative: {
+                    readonly type: "boolean";
+                };
+                readonly code: {
+                    readonly enum: readonly ["PROJECT_ROOT_MISMATCH", "PROJECT_ID_MISMATCH", "INVALID_PROJECT_EXPECTATION"];
+                };
+                readonly message: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly activation: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["writePath", "host", "honestLabel"];
+            readonly properties: {
+                readonly writePath: {
+                    readonly enum: readonly ["hard", "advisory", "unavailable"];
+                };
+                readonly host: {
+                    readonly anyOf: readonly [{
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly honestLabel: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly lastCheck: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["at", "verdict", "activeViolations", "frozenResidual"];
+            readonly properties: {
+                readonly at: {
+                    readonly anyOf: readonly [{
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly verdict: {
+                    readonly anyOf: readonly [{
+                        readonly enum: readonly ["pass", "fail", "incomplete"];
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly activeViolations: {
+                    readonly anyOf: readonly [{
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly frozenResidual: {
+                    readonly anyOf: readonly [{
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+            };
+        };
+        readonly rules: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["arkRulesLoaded", "inventoried", "underContract", "frozenResidual"];
+            readonly properties: {
+                readonly arkRulesLoaded: {
+                    readonly type: "boolean";
+                };
+                readonly inventoried: {
+                    readonly anyOf: readonly [{
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly underContract: {
+                    readonly anyOf: readonly [{
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly frozenResidual: {
+                    readonly anyOf: readonly [{
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+            };
+        };
+        readonly nextAction: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["id", "summary"];
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly summary: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+        };
+    };
+};
+
+/**
+ * Version-matched agent contract projection (ACS04).
+ *
+ * Compact agent-facing markdown (plus meta) derived from the installed package
+ * version and an effective project contract summary. Explicitly **non-authoritative**:
+ * enforcement is ark-check / hooks / CI — never this projection, AGENTS.md, or skills.
+ *
+ * **Canonical** for `ark agents-md`, install/upgrade AGENTS embedding, and drift tests.
+ * Tooling gathers filesystem facts; this module only formats pure inputs.
+ *
+ * Zero Node I/O. Optional CLI surface: generated `bin/lib/agent-projection.mjs`.
+ *
+ * @see docs/plans/agent-contract-surface-4.3/README.md
+ */
+declare const ARK_AGENT_PROJECTION_SCHEMA_VERSION: "1.0";
+/** Begin marker for the managed projection region inside AGENTS.md (or equivalent). */
+declare const AGENT_PROJECTION_BEGIN_MARKER: "<!-- arkgate:agent-projection:begin";
+/** End marker for the managed projection region. */
+declare const AGENT_PROJECTION_END_MARKER: "<!-- arkgate:agent-projection:end -->";
+/**
+ * Non-enforcement label — must appear in every generated projection body.
+ * Agents and humans must not treat the projection as a pass/fail authority.
+ */
+declare const AGENT_PROJECTION_NON_ENFORCEMENT_LABEL: "This projection is **non-authoritative**. Enforcement is `ark-check` / host write hooks / required CI (`--strict-merge`), not AGENTS.md, skills, or this block.";
+/** Surfaces that actually enforce (closed vocabulary for meta + docs). */
+declare const AGENT_PROJECTION_ENFORCEMENT_SURFACES: readonly ["ark-check", "host-write-hooks", "ci-strict-merge"];
+/**
+ * High-signal public ruleIds for the compact catalog short list in the projection.
+ * Full catalog remains `docs/diagnostics.md` / `DIAGNOSTIC_CATALOG` (ACS02).
+ * Titles are supplied by Tooling from the catalog when available.
+ */
+declare const DEFAULT_AGENT_PROJECTION_RULE_IDS: readonly string[];
+type AgentProjectionLayerSummary = {
+    name: string;
+    patterns?: readonly string[];
+    intentPrefixes?: readonly string[];
+};
+type AgentProjectionCatalogEntry = {
+    ruleId: string;
+    title: string;
+};
+type AgentProjectionProfile = 'compact' | 'full';
+/**
+ * Pure facts supplied by Tooling after reading package version + ark.config.
+ * Domain never opens files or prompts.
+ */
+type AgentProjectionFacts = {
+    /** Installed / shipping arkgate package version (stamped into the projection). */
+    arkgateVersion: string;
+    /** Project check command hint (e.g. `npm run check:architecture`). */
+    checkCommand?: string | null;
+    /** Effective layers from ark.config.json (null/empty → stock note). */
+    layers?: readonly AgentProjectionLayerSummary[] | null;
+    /** Short diagnostic catalog lines (ruleId + title). */
+    catalogShortList?: readonly AgentProjectionCatalogEntry[] | null;
+    /** Active host id when known (compact router context). */
+    host?: string | null;
+    /** full = placement + catalog short list; compact = thinner primary path. */
+    profile?: AgentProjectionProfile | null;
+    /** Docs path for the full diagnostic catalog (relative). */
+    diagnosticsDocsPath?: string | null;
+};
+type AgentProjectionMeta = {
+    schemaVersion: typeof ARK_AGENT_PROJECTION_SCHEMA_VERSION;
+    arkgateVersion: string;
+    /** Always true — projection is never a gate input. */
+    nonAuthoritative: true;
+    enforcementSurfaces: readonly string[];
+    /** Content identity of the projection body (markers excluded). */
+    contentIdentity: string;
+    layerCount: number;
+    catalogCodeCount: number;
+    profile: AgentProjectionProfile;
+};
+type AgentProjectionMergeAction = 'created' | 'block-replaced' | 'block-inserted' | 'unchanged';
+type AgentProjectionMergeResult = {
+    content: string;
+    action: AgentProjectionMergeAction;
+    previousBlock: string | null;
+    contentIdentity: string;
+    /** True when customized text outside the managed block was preserved. */
+    preservedOutsideBlock: boolean;
+};
+/** FNV-1a identity — portable, no Node crypto (same family as stableHash). */
+declare function agentProjectionContentIdentity(body: string): string;
+/**
+ * Build the managed begin marker line (includes version + nonAuthoritative stamp).
+ */
+declare function buildAgentProjectionBeginMarker(facts: {
+    arkgateVersion: string;
+    schemaVersion?: string;
+}): string;
+/**
+ * Layer placement rows for the projection (compact markdown table).
+ */
+declare function formatAgentProjectionLayers(layers: readonly AgentProjectionLayerSummary[] | null | undefined): string;
+/**
+ * Catalog short-list bullets (ruleId + title). Empty list → pointer only.
+ */
+declare function formatAgentProjectionCatalogShortList(entries: readonly AgentProjectionCatalogEntry[] | null | undefined, docsPath: string): string;
+/**
+ * Projection **body** only (no begin/end markers). Used for content-identity.
+ */
+declare function buildAgentProjectionBody(facts: AgentProjectionFacts): string;
+/**
+ * Full managed block: begin marker + body + end marker.
+ */
+declare function buildAgentProjectionBlock(facts: AgentProjectionFacts): string;
+/**
+ * Machine meta for CLI `--json` / tests (never a gate input).
+ */
+declare function buildAgentProjectionMeta(facts: AgentProjectionFacts): AgentProjectionMeta;
+/**
+ * Extract the managed projection block from a document (AGENTS.md or equivalent).
+ */
+declare function extractAgentProjectionBlock(document: string): {
+    block: string | null;
+    body: string | null;
+    before: string;
+    after: string;
+    beginAttrs: string | null;
+};
+/**
+ * Parse stamps from a projection begin marker or full block/document.
+ */
+declare function parseAgentProjectionStamp(source: string): {
+    arkgateVersion: string | null;
+    schemaVersion: string | null;
+    nonAuthoritative: boolean;
+};
+/**
+ * True when the document/block stamps the given package version.
+ */
+declare function projectionMatchesPackageVersion(source: string, packageVersion: string): boolean;
+/**
+ * True when body text carries the non-enforcement label (substring match).
+ */
+declare function projectionHasNonEnforcementLabel(bodyOrBlock: string): boolean;
+/**
+ * Merge a desired projection block into an existing document without rewriting
+ * customized content **outside** the managed markers.
+ *
+ * - Missing document → create `# Ark Enforcement` + block
+ * - Existing markers → replace block when content-identity differs; else unchanged
+ * - No markers → insert block after the first markdown H1 (or at top)
+ */
+declare function mergeAgentProjectionDocument(existing: string | null | undefined, desiredBlock: string): AgentProjectionMergeResult;
+
+/**
+ * Agent Skills packaging contract (ACS05).
+ *
+ * Closed catalog of the **existing 13** `/ark-*` skill names and pure validation
+ * for Agent Skills–compatible layout (`<name>/SKILL.md` with YAML frontmatter).
+ *
+ * **No new skill names** — the freeze list is the product contract. Packaging is
+ * distribution only; enforcement remains ark-check / hooks / CI, never skills alone.
+ *
+ * Canonical authoring source remains flat `templates/skills/<name>.md`. The
+ * Agent Skills layout is the generated twin at `templates/agent-skills/<name>/SKILL.md`.
+ *
+ * Zero Node I/O. Optional CLI surface: generated `bin/lib/agent-skills-package.mjs`.
+ *
+ * @see docs/plans/agent-contract-surface-4.3/README.md
+ * @see https://agentskills.io/specification
+ */
+declare const ARK_AGENT_SKILLS_PACKAGE_SCHEMA_VERSION: "1.0";
+/**
+ * Relative package-root path of the Agent Skills–compatible skill package.
+ * Install via skills ecosystem: `npx skills add <path-to-this-dir>`.
+ */
+declare const AGENT_SKILLS_PACKAGE_RELATIVE_ROOT: "templates/agent-skills";
+/** Relative package-root path of flat skill templates (Ark install source). */
+declare const FLAT_SKILL_TEMPLATES_RELATIVE_ROOT: "templates/skills";
+/** Required entry filename inside each skill directory (Agent Skills standard). */
+declare const AGENT_SKILL_ENTRY_FILENAME: "SKILL.md";
+/**
+ * Closed skill-name freeze (ACS / ADR skill freeze). Exactly these 13 names ship.
+ * Sorted alphabetically for deterministic inventory diffs.
+ */
+declare const ARK_SKILL_NAMES: readonly ["ark-adopt", "ark-architect", "ark-autopilot", "ark-contract", "ark-coverage", "ark-explain", "ark-explore", "ark-fix", "ark-loop", "ark-place", "ark-runtime", "ark-think", "ark-upgrade"];
+type ArkSkillName = (typeof ARK_SKILL_NAMES)[number];
+/** Count of frozen skill names (must stay 13 until a ROADMAP item lifts the freeze). */
+declare const ARK_SKILL_NAME_COUNT: 13;
+/**
+ * Agent Skills `name` field rules (agentskills.io):
+ * - 1–64 characters
+ * - lowercase a–z, digits, hyphens only
+ * - no leading/trailing hyphen; no consecutive hyphens
+ */
+declare function isValidAgentSkillName(name: string): boolean;
+/** True when `name` is one of the frozen 13 Ark skill names. */
+declare function isArkSkillName(name: string): name is ArkSkillName;
+type ParsedSkillFrontmatter = {
+    /** Raw frontmatter keys (string values; nested YAML not supported). */
+    fields: Readonly<Record<string, string>>;
+    name: string | null;
+    description: string | null;
+    license: string | null;
+};
+type ParseSkillDocumentResult = {
+    /** True when opening `---` / closing `---` frontmatter fences were found. */
+    hasFrontmatter: boolean;
+    frontmatter: ParsedSkillFrontmatter | null;
+    /** Markdown body after the frontmatter block (may be empty). */
+    body: string;
+};
+/**
+ * Parse a skill markdown document with optional YAML frontmatter.
+ * Supports the simple `key: value` / `key: "quoted"` form used by Ark templates
+ * (no nested maps, no multi-line YAML).
+ */
+declare function parseSkillDocument(content: string): ParseSkillDocumentResult;
+type AgentSkillValidationIssue = {
+    code: 'MISSING_FRONTMATTER' | 'INVALID_NAME' | 'NAME_DIRECTORY_MISMATCH' | 'MISSING_DESCRIPTION' | 'DESCRIPTION_TOO_LONG' | 'EMPTY_BODY' | 'UNKNOWN_SKILL_NAME' | 'DUPLICATE_SKILL' | 'MISSING_SKILL' | 'EXTRA_SKILL' | 'CONTENT_MISMATCH';
+    message: string;
+    skillName?: string;
+};
+type ValidateAgentSkillDocumentInput = {
+    /** Parent directory name (must match frontmatter `name`). */
+    directoryName: string;
+    /** Full SKILL.md / template content. */
+    content: string;
+    /**
+     * When true (default), require `directoryName` / frontmatter name to be in
+     * {@link ARK_SKILL_NAMES}. Set false only for generic Agent Skills checks.
+     */
+    requireArkSkillName?: boolean;
+    /** When true (default), require a non-empty markdown body after frontmatter. */
+    requireBody?: boolean;
+};
+/**
+ * Validate one skill document against the Agent Skills spec (+ optional Ark freeze).
+ */
+declare function validateAgentSkillDocument(input: ValidateAgentSkillDocumentInput): AgentSkillValidationIssue[];
+type AgentSkillPackageEntry = {
+    /** Skill directory / frozen name. */
+    name: string;
+    /** Full SKILL.md content for the Agent Skills layout. */
+    content: string;
+    /** Optional flat-template content for byte-identity parity checks. */
+    flatTemplateContent?: string | null;
+};
+type ValidateAgentSkillsPackageResult = {
+    ok: boolean;
+    issues: AgentSkillValidationIssue[];
+    /** Sorted names present in the package input. */
+    names: string[];
+    expectedCount: number;
+    presentCount: number;
+};
+/**
+ * Validate a full Agent Skills package inventory against the frozen 13-name catalog.
+ * Detects missing, extra, duplicate, invalid, and (when supplied) flat-template drift.
+ */
+declare function validateAgentSkillsPackage(entries: readonly AgentSkillPackageEntry[]): ValidateAgentSkillsPackageResult;
+/**
+ * Normalize skill file content for identity compare (LF newlines, strip BOM).
+ * Does not strip or rewrite frontmatter — Agent Skills export is 1:1 with flat templates.
+ */
+declare function normalizeSkillContent(content: string): string;
+/**
+ * Relative path of one skill entry inside the Agent Skills package root.
+ * Example: `ark-place/SKILL.md`
+ */
+declare function agentSkillEntryRelativePath(skillName: string): string;
+/**
+ * Relative path from package root for one Agent Skills entry.
+ * Example: `templates/agent-skills/ark-place/SKILL.md`
+ */
+declare function agentSkillPackageFileRelativePath(skillName: string): string;
+/**
+ * Relative path from package root for one flat template.
+ * Example: `templates/skills/ark-place.md`
+ */
+declare function flatSkillTemplateFileRelativePath(skillName: string): string;
+
+export { ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH, AGENT_PROJECTION_BEGIN_MARKER, AGENT_PROJECTION_END_MARKER, AGENT_PROJECTION_ENFORCEMENT_SURFACES, AGENT_PROJECTION_NON_ENFORCEMENT_LABEL, AGENT_SKILLS_PACKAGE_RELATIVE_ROOT, AGENT_SKILL_ENTRY_FILENAME, type AICodeGate, type AICodeGateContext, type AICodeGateOptions, type AICodeGateResult, type AICodeGateViolation, type AIGateExtension, ANALYSIS_IR_SCHEMA_VERSION, ARK_AGENT_PROJECTION_SCHEMA_VERSION, ARK_AGENT_SKILLS_PACKAGE_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_PROJECT_IDENTITY_SCHEMA, ARK_PROJECT_IDENTITY_SCHEMA_URL, ARK_PROJECT_IDENTITY_SCHEMA_VERSION, ARK_RULES_SCHEMA, ARK_RULES_SCHEMA_VERSION, ARK_RULE_SENSORS, ARK_SKILL_NAMES, ARK_SKILL_NAME_COUNT, ARK_STATUS_MANIFEST_SCHEMA, ARK_STATUS_MANIFEST_SCHEMA_URL, ARK_STATUS_MANIFEST_SCHEMA_VERSION, type AdapterCompletenessReason, type AdapterDiagnostic, type AdapterResult, type AdapterSeverity, type AdapterViolationInput, type AgentProjectionCatalogEntry, type AgentProjectionFacts, type AgentProjectionLayerSummary, type AgentProjectionMergeAction, type AgentProjectionMergeResult, type AgentProjectionMeta, type AgentProjectionProfile, type AgentSkillPackageEntry, type AgentSkillValidationIssue, 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 ArkSkillName, type ChangePreflightResult, type ClassShapeFact, type CollectAnalysisConfigWarningsInput, type CreateArchitectureProfileFromArkConfigOptions, type CreateArchitectureProfileOptions, type CreateElevenLayerArkConfigOptions, DEFAULT_AGENT_PROJECTION_RULE_IDS, DIAGNOSTIC_CATALOG, DIAGNOSTIC_CATALOG_SCHEMA_VERSION, DIAGNOSTIC_DOCS_RELATIVE_PATH, DIAGNOSTIC_RULE_IDS, type DesignDeltaChange, type DesignDeltaIdentity, type DesignSmellEvidence, type DesignSmellFinding, type DesignSmellId, type DiagnosticCatalogEntry, type DiagnosticCategory, type EffectiveArkRules, type EffectiveContract, EffectiveContractError, type EffectiveContractWarning, type EnforcementBoundaryState, type EnforcementEvidence, type EnforcementEvidenceField, type EnforcementVerification, type EvaluateArchitectureGraphInput, FLAT_SKILL_TEMPLATES_RELATIVE_ROOT, type ForbiddenCapabilityUse, type InvariantCoverageEvidence, POLICY_DELTA_SCHEMA_VERSION, PROJECT_BINDING_SCHEMA, PROJECT_EXPECTATION_SCHEMA, type ParseSkillDocumentResult, type ParsedSkillFrontmatter, type PolicyDelta, type PolicyDeltaAcknowledgement, type PolicyDeltaAnalysis, type PolicyDeltaClassification, type PolicyDeltaFinding, type PreflightResolvedChangeInput, type PreparedChangeFile, type ProjectBinding, type ProjectExpectation, type ProjectIdentity, 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, type StatusActivationSlice, type StatusCheckVerdict, type StatusLastCheckSlice, type StatusManifest, type StatusManifestFacts, type StatusNextAction, type StatusProjectIdentitySlice, type StatusRulesSlice, type StatusWritePathClass, type ValidateAgentSkillDocumentInput, type ValidateAgentSkillsPackageResult, adapterDocsCodePath, adapterFindingOccurrenceTargetKeys, adapterFindingRefFromTargetKey, adapterFindingTargetKey, agentProjectionContentIdentity, agentSkillEntryRelativePath, agentSkillPackageFileRelativePath, analyzeArchitectureConvergence, analyzeChange, analyzePolicyDelta, analyzeProject, analyzeResolvedProject, buildAgentProjectionBeginMarker, buildAgentProjectionBlock, buildAgentProjectionBody, buildAgentProjectionMeta, buildArkRuleFileHints, buildEffectiveArkRules, buildRulesInventory, buildStatusManifest, canPromoteInvariant, catalogFixForRuleId, catalogWhyForRuleId, classifyArkPolicyDelta, classifyStatusWritePath, collectAnalysisConfigWarnings, collectEmptyAppliesToFindings, collectForbiddenCapabilityUses, createAICodeGate, createAdapterResult, createArchitectureProfile, createArchitectureProfileFromArkConfig, createElevenLayerArkConfig, createProjectId, createProjectIdentity, createResolvedCandidateFacts, defaultHonestLabel, deriveArkRuleFileHints, detectArchitectureCycles, deterministicHash, diagnosticDocsFragment, diagnosticDocsPath, effectiveContractPolicyPayload, elevenLayerProfile, emptyEffectiveArkRules, evaluateArchitectureGraph, evaluateArkRuleSensors, evaluateInvariantCoverage, evaluateStatusBinding, explainViolation, extractAgentProjectionBlock, extractClassShapesFromSource, extractSemanticDependencies, flatSkillTemplateFileRelativePath, formatAgentProjectionCatalogShortList, formatAgentProjectionLayers, getDiagnosticCatalogEntry, inventoryToExtractionCard, isArkSkillName, isCataloguedOrArkRuleFamily, isKnownDiagnosticCode, isValidAgentSkillName, loadArkConfigContract, loadArkRulesContract, loadContract, loadResolvedCandidateFacts, mergeAgentProjectionDocument, normalizeSkillContent, parseAgentProjectionStamp, parseArkConfigJson, parseArkRulesJson, parseSkillDocument, policyDeltaAcknowledgementMatches, preflightChange, preflightResolvedChange, projectionHasNonEnforcementLabel, projectionMatchesPackageVersion, resolveEffectiveContract, resolveStatusNextAction, resolvedFactsEvidenceRequirementsHash, serializeDiagnosticCatalog, stableSerialize, toAdapterDiagnostic, validateAgentSkillDocument, validateAgentSkillsPackage, version };