arkgate 4.8.23 → 4.8.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +7 -5
  3. package/bin/ark-check-runtime.mjs +24 -77
  4. package/bin/ark-dashboard.mjs +56 -53
  5. package/bin/ark-layer-match.mjs +596 -112
  6. package/bin/ark-mcp-runtime.mjs +412 -138
  7. package/bin/ark-mcp.mjs +68 -4
  8. package/bin/ark-shared.mjs +39 -0
  9. package/bin/ark.mjs +65 -97
  10. package/bin/lib/adapter-contract-types.mjs +5 -0
  11. package/bin/lib/adapter-contract.mjs +15 -0
  12. package/bin/lib/agent-projection-command.mjs +5 -1
  13. package/bin/lib/analysis-engine.mjs +15 -11
  14. package/bin/lib/architecture-scan.mjs +50 -6
  15. package/bin/lib/ark-order-doctor.mjs +1 -1
  16. package/bin/lib/ark-order-facts.mjs +410 -15
  17. package/bin/lib/ark-order-invariants.mjs +51 -9
  18. package/bin/lib/ark-order-sensors.mjs +28 -101
  19. package/bin/lib/ark-order-types.mjs +2 -0
  20. package/bin/lib/ark-run-doctor.mjs +14 -0
  21. package/bin/lib/ark-run-facts.mjs +434 -11
  22. package/bin/lib/ark-run-sensors.mjs +5 -3
  23. package/bin/lib/arkgate-pins.mjs +91 -0
  24. package/bin/lib/arkrules-sensors.mjs +50 -249
  25. package/bin/lib/check-args.mjs +23 -1
  26. package/bin/lib/ci-and-commands.mjs +16 -6
  27. package/bin/lib/class-source-scan.mjs +479 -0
  28. package/bin/lib/codex-home.mjs +4 -2
  29. package/bin/lib/config-contract-slices.mjs +701 -0
  30. package/bin/lib/config-contract.mjs +5 -493
  31. package/bin/lib/config-warnings.mjs +32 -0
  32. package/bin/lib/dashboard-cli.mjs +62 -0
  33. package/bin/lib/design-delta.mjs +1 -1
  34. package/bin/lib/diagnostic-catalog.mjs +16 -9
  35. package/bin/lib/doctor-advisories.mjs +25 -1
  36. package/bin/lib/doctor-next-actions.mjs +17 -2
  37. package/bin/lib/doctor-plan.mjs +6 -8
  38. package/bin/lib/effective-contract-load.mjs +121 -59
  39. package/bin/lib/enforcement-profiles.mjs +40 -4
  40. package/bin/lib/first-run-help.mjs +3 -2
  41. package/bin/lib/flat-parent-importers.mjs +137 -0
  42. package/bin/lib/flat-parent-pilot.mjs +40 -100
  43. package/bin/lib/gate-files.mjs +29 -2
  44. package/bin/lib/git-change-scope.mjs +109 -0
  45. package/bin/lib/github-enforcement.mjs +1 -1
  46. package/bin/lib/hook-templates.mjs +18 -16
  47. package/bin/lib/host-support-matrix.mjs +3 -1
  48. package/bin/lib/import-resolve.mjs +13 -1
  49. package/bin/lib/install-migrate.mjs +50 -73
  50. package/bin/lib/invariant-coverage.mjs +59 -11
  51. package/bin/lib/mcp-adoption.mjs +9 -1
  52. package/bin/lib/mcp-hook-payload.mjs +401 -61
  53. package/bin/lib/package-manager.mjs +59 -1
  54. package/bin/lib/passthrough-commands.mjs +83 -0
  55. package/bin/lib/persistence-write-hint.mjs +81 -0
  56. package/bin/lib/pin-dependent-gates.mjs +117 -0
  57. package/bin/lib/policy-delta-io.mjs +168 -10
  58. package/bin/lib/prepare-change.mjs +120 -6
  59. package/bin/lib/prepare-write.mjs +1 -0
  60. package/bin/lib/presets.mjs +3 -5
  61. package/bin/lib/remediation.mjs +23 -4
  62. package/bin/lib/resolved-candidate-facts.mjs +315 -55
  63. package/bin/lib/rules-inventory.mjs +22 -3
  64. package/bin/lib/rules-under-contract.mjs +179 -5
  65. package/bin/lib/scan-files.mjs +32 -0
  66. package/bin/lib/snippet-analysis.mjs +140 -6
  67. package/bin/lib/source-policy.mjs +34 -0
  68. package/bin/lib/stable-hash.mjs +90 -0
  69. package/bin/lib/start-install-recovery.mjs +71 -1
  70. package/bin/lib/start-preview.mjs +30 -0
  71. package/bin/lib/status-command.mjs +33 -4
  72. package/bin/lib/status-manifest.mjs +32 -4
  73. package/bin/lib/team-parliament-io.mjs +77 -75
  74. package/bin/lib/team-parliament.mjs +6 -1
  75. package/bin/lib/write-path-capabilities.mjs +4 -2
  76. package/dist/chunk-A5EIY3HI.cjs +5 -0
  77. package/dist/chunk-MBXCFLO4.js +16 -0
  78. package/dist/chunk-RNQHRDCQ.cjs +16 -0
  79. package/dist/chunk-SVSQVGFJ.js +5 -0
  80. package/dist/{configTypes-Bbf_MFGe.d.ts → configTypes-BJbaeoj4.d.cts} +18 -3
  81. package/dist/configTypes-BJbaeoj4.d.ts +246 -0
  82. package/dist/eslint/index.cjs +17 -4
  83. package/dist/eslint/index.d.cts +359 -0
  84. package/dist/eslint/index.d.ts +130 -156
  85. package/dist/eslint/index.js +10 -4
  86. package/dist/index.cjs +35 -34
  87. package/dist/index.d.cts +5475 -0
  88. package/dist/index.d.ts +3312 -299
  89. package/dist/index.js +35 -34
  90. package/dist/inspectorListen-6DQVJ4DC.js +1 -0
  91. package/dist/inspectorListen-KGMIQ2TF.cjs +1 -0
  92. package/dist/nestjs/index.cjs +1 -18
  93. package/dist/nestjs/index.d.cts +22 -0
  94. package/dist/nestjs/index.d.ts +1 -3
  95. package/dist/nestjs/index.js +1 -18
  96. package/dist/order/index.cjs +1 -1
  97. package/dist/order/index.d.cts +155 -0
  98. package/dist/order/index.d.ts +15 -3
  99. package/dist/order/index.js +1 -1
  100. package/dist/runtime/index.cjs +13 -30
  101. package/dist/{diagnosticCatalog-35mrwAHe.d.ts → runtime/index.d.cts} +804 -290
  102. package/dist/runtime/index.d.ts +2678 -108
  103. package/dist/runtime/index.js +13 -30
  104. package/dist/{types-Bdj32QwA.d.ts → types-DRinG-vT.d.cts} +576 -140
  105. package/dist/types-DRinG-vT.d.ts +1792 -0
  106. package/docs/README.md +2 -1
  107. package/docs/agent-guide.md +84 -15
  108. package/docs/ai-gates.md +160 -26
  109. package/docs/arkorder.md +32 -15
  110. package/docs/brownfield-adoption.md +5 -1
  111. package/docs/configuration.md +196 -26
  112. package/docs/develop.md +2 -1
  113. package/docs/diagnostics.md +96 -19
  114. package/docs/package-surface.md +31 -8
  115. package/docs/product-voice.md +1 -1
  116. package/package.json +59 -18
  117. package/schemas/ark.analysis-result.schema.json +15 -0
  118. package/schemas/ark.config.schema.json +47 -10
  119. package/schemas/ark.resolved-candidate-facts.schema.json +1 -1
  120. package/schemas/ark.status-manifest.schema.json +22 -0
  121. package/server.json +3 -9
  122. package/templates/agent-skills/README.md +1 -1
  123. package/templates/agent-skills/ark-adopt/SKILL.md +4 -1
  124. package/templates/agent-skills/ark-order/SKILL.md +4 -2
  125. package/templates/agent-skills/ark-runtime/SKILL.md +6 -1
  126. package/templates/arkrules/PersistenceAdapters.json +1 -1
  127. package/templates/arkrules/PresentationAdapters.json +1 -1
  128. package/templates/skills/ark-adopt.md +4 -1
  129. package/templates/skills/ark-order.md +4 -2
  130. package/templates/skills/ark-runtime.md +6 -1
  131. package/dist/types-Ik_OakcI.d.ts +0 -183
@@ -1,5 +1,450 @@
1
- import { e as CreateArchitectureProfileOptions, b as ArchitectureProfile, d as ArkCheckConfig, C as CreateArchitectureProfileFromArkConfigOptions, f as CreateElevenLayerArkConfigOptions, i as Policy, j as IntentCreator, I as IntentName } from './types-Ik_OakcI.js';
2
- import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-Bbf_MFGe.js';
1
+ import { a as AuditStore, b as AuditRecord, c as AuditQuery, d as CreateAuditTrailOptions, e as AuditTrail, f as CreateArchitectureProfileOptions, g as ArchitectureProfile, h as ArkCheckConfig, i as CreateArchitectureProfileFromArkConfigOptions, j as CreateElevenLayerArkConfigOptions, D as DependencyGraph, I as IntentRegistry, E as EventContractRegistry, k as EventContract, l as DomainEvent, m as EventContractValidationResult, n as IntentName, o as DefineIntentOptions, p as IntentCreator, M as MetadataRegistry, R as ReadModelStore, q as CreateProjectionRegistryOptions, P as ProjectionRegistry, r as PolicyViolation, s as PolicySeverity, t as PolicyEnforcementMode, u as Policy, G as GraphEdge, v as IntentRelationship, w as EventBufferStore, x as EventBufferRecord, y as EventBufferStatus, z as EventBusOptions, B as EventBus, F as CreateObservabilityReporterOptions, O as ObservabilityReporter, H as PolicyEngine, J as ArkManifest, W as WorkflowStore, S as SagaContext, K as WorkflowSnapshot, L as SagaDefinition, N as CreateWorkflowEngineOptions, Q as SagaInstance, T as WorkflowEngine, U as DependencyInformationPackage, C as CreateArkKernelOptions, A as ArkKernel, V as ArkKernelConfig, X as CreateArkKernelFromConfigOptions, Y as TraceRecordType, Z as TraceRecord, _ as OutboxStatus, $ as OutboxRecord, a0 as ObservabilityDriftReport, a1 as ArkConfig, a2 as ArkConfigLoadResult } from '../types-DRinG-vT.cjs';
2
+ export { a3 as ARK_RUN_COMPONENT_LIFETIMES, a4 as ARK_RUN_EPHEMERAL_DEFAULT, a5 as ARK_RUN_GRAPH_DEFAULT_SLICE, a6 as ARK_RUN_GRAPH_NODE_KINDS, a7 as ARK_RUN_GRAPH_PROCESS_EDGE_KINDS, a8 as ARK_RUN_GRAPH_SCHEMA_VERSION, a9 as ARK_RUN_GRAPH_SLICES, aa as ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS, ab as ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION, ac as ARK_RUN_INSPECTOR_DEFAULT_HOST, ad as ARK_RUN_INSPECTOR_DEFAULT_PORT, ae as ARK_RUN_INSPECTOR_EVENTS_PATH, af as ARK_RUN_INSPECTOR_GRAPH_PATH, ag as ARK_RUN_INSPECTOR_MONITOR_SAMPLE_LIMIT, ah as ARK_RUN_INSPECTOR_OUTBOX_PATH, ai as ARK_RUN_INSPECTOR_SCHEMA_VERSION, aj as ARK_RUN_INSPECTOR_SNAPSHOT_PATH, ak as ARK_RUN_INSPECTOR_SSE_EVENT, al as ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK, am as ARK_RUN_INSPECTOR_WORKFLOWS_PATH, an as ARK_RUN_TRANSPORT_KINDS, ao as ArchitectureLayer, ap as ArchitectureLayerConfig, aq as ArchitectureRule, ar as ArkManifestArchitecture, as as ArkManifestData, at as ArkManifestEntityLink, au as ArkManifestGraph, av as ArkManifestIntent, aw as ArkManifestPolicy, ax as ArkManifestProjection, ay as ArkRunBrokerAdapter, az as ArkRunComponentLifetime, aA as ArkRunDeliveredVia, aB as ArkRunExtendedInfo, aC as ArkRunGraph, aD as ArkRunGraphEdge, aE as ArkRunGraphEdgeKind, aF as ArkRunGraphMatch, aG as ArkRunGraphMatchInput, aH as ArkRunGraphNode, aI as ArkRunGraphNodeKind, aJ as ArkRunGraphProcessEdgeKind, aK as ArkRunGraphQuery, aL as ArkRunGraphResolvedQuery, aM as ArkRunGraphSlice, aN as ArkRunGraphTechnicalEdgeKind, aO as ArkRunInformationPackageComponent, aP as ArkRunInspectorBind, aQ as ArkRunInspectorBindError, aR as ArkRunInspectorBindInput, aS as ArkRunInspectorHandle, aT as ArkRunInspectorHardening, aU as ArkRunInspectorHardeningDurability, aV as ArkRunInspectorMonitorBuildOptions, aW as ArkRunInspectorOutboxMonitor, aX as ArkRunInspectorOutboxRecordSummary, aY as ArkRunInspectorProductionError, aZ as ArkRunInspectorSnapshot, a_ as ArkRunInspectorSnapshotInput, a$ as ArkRunInspectorSource, b0 as ArkRunInspectorStoreDurability, b1 as ArkRunInspectorStoreDurabilityKind, b2 as ArkRunInspectorStoreRole, b3 as ArkRunInspectorTransportFacts, b4 as ArkRunInspectorWorkflowSummary, b5 as ArkRunInspectorWorkflowsMonitor, b6 as ArkRunPublisher, b7 as ArkRunRegisterOptions, b8 as ArkRunRegistrationHandle, b9 as ArkRunSendOptions, ba as ArkRunSendPlan, bb as ArkRunSendPlanInput, bc as ArkRunSendResult, bd as ArkRunTransportKind, be as AuditRecordInput, bf as AuditRecordType, bg as CorrelationId, bh as EntityMeta, bi as EventContractIssue, bj as EventHandler, bk as EventInterceptionInfo, bl as EventInterceptor, bm as EventInterceptorContext, bn as EventMetadata, bo as EventPayloadPatch, bp as EventPayloadSchema, bq as EventPublisher, br as EventSchemaField, bs as EventSchemaFieldType, bt as FieldMeta, bu as GraphNode, bv as IntentRelationshipKind, bw as InvalidArkRunGraphQueryError, bx as InvalidArkRunSendOptionError, by as ObservabilityFlow, bz as ObservedLayerFlowMode, bA as OutboxStore, bB as PolicyEvaluationResult, bC as ProjectionCheckpoint, bD as ProjectionDefinition, bE as PublishedEventRecord, bF as RetryPolicy, bG as SagaStatus, bH as SagaStep, bI as StartArkRunInspectorOptions, bJ as TraceSink, bK as Unsubscribe, bL as WorkflowDefinition, bM as WorkflowStatus, bN as WorkflowStep, bO as appendDecisionTape, bP as arkRunGraphQueryFromSearchParams, bQ as arkRunInspectorUrl, bR as buildArkRunInspectorHardening, bS as buildArkRunInspectorOutboxMonitor, bT as buildArkRunInspectorSnapshot, bU as buildArkRunInspectorWorkflowsMonitor, bV as buildDependencyInformationPackage, bW as classifyArkRunInspectorStoreDurability, bX as closeArkRunGraphQuery, bY as closedArkRunEphemeral, bZ as closedArkRunTransportKind, b_ as formatArkRunGraphMermaid, b$ as formatArkRunInspectorSseEvent, c0 as isArkRunInspectorLoopbackHost, c1 as isArkRunInspectorProductionEnv, c2 as requestArkRunGraph, c3 as resolveArkRunInspectorBind, c4 as resolveArkRunSendPlan, c5 as startArkRunInspector, c6 as unavailableArkRunInspectorOutboxMonitor, c7 as unavailableArkRunInspectorWorkflowsMonitor } from '../types-DRinG-vT.cjs';
3
+
4
+ /**
5
+ * Reference in-process audit store. **Not production durability** — records do not
6
+ * survive process restarts. For production, inject an `AuditStore` that writes to your
7
+ * durable log/DB (see `docs/production-hardening.md`).
8
+ */
9
+ declare class InMemoryAuditStore implements AuditStore {
10
+ private readonly maxRecords?;
11
+ private readonly records;
12
+ constructor(maxRecords?: number | undefined);
13
+ append(record: AuditRecord): void;
14
+ query(query?: AuditQuery): AuditRecord[];
15
+ clear(): void;
16
+ }
17
+ /**
18
+ * Create an audit trail. Defaults to `InMemoryAuditStore` (**not** production durability).
19
+ * Pass `options.store` for a durable backend.
20
+ */
21
+ declare function createAuditTrail(options?: CreateAuditTrailOptions): AuditTrail;
22
+
23
+ declare function createArchitectureProfile(options: CreateArchitectureProfileOptions): ArchitectureProfile;
24
+ declare function createArchitectureProfileFromArkConfig(config: ArkCheckConfig, options?: CreateArchitectureProfileFromArkConfigOptions): ArchitectureProfile;
25
+ declare const elevenLayerProfile: ArchitectureProfile;
26
+ declare function createElevenLayerArkConfig(options?: CreateElevenLayerArkConfigOptions): ArkCheckConfig;
27
+
28
+ /**
29
+ * DependencyGraph implementation.
30
+ *
31
+ * Collects declared and observed relationships.
32
+ * Generates Mermaid diagrams and JSON.
33
+ * Supports simple violation detection via rule functions.
34
+ */
35
+
36
+ declare function createDependencyGraph(): DependencyGraph;
37
+
38
+ /**
39
+ * Bridge IntentRegistry relationships into a DependencyGraph.
40
+ */
41
+
42
+ interface SyncRegistryOptions {
43
+ /** Skip edges whose target intent is not registered (default: false). */
44
+ requireRegisteredTargets?: boolean;
45
+ }
46
+ /**
47
+ * Sync declared intent relationships from a registry into a dependency graph.
48
+ *
49
+ * - `dependsOn` → `declared` edges
50
+ * - `produces` → `produces` edges
51
+ */
52
+ declare function syncRegistryToGraph(registry: IntentRegistry, graph: DependencyGraph, options?: SyncRegistryOptions): void;
53
+
54
+ declare class EventContractRegistryImpl implements EventContractRegistry {
55
+ private readonly contracts;
56
+ register(contract: EventContract): void;
57
+ get(intent: string, version?: string): EventContract | undefined;
58
+ list(intent?: string): EventContract[];
59
+ validate(event: DomainEvent): EventContractValidationResult;
60
+ clear(): void;
61
+ private key;
62
+ }
63
+ declare function createEventContractRegistry(): EventContractRegistry;
64
+
65
+ /**
66
+ * defineIntent
67
+ *
68
+ * The primary ergonomic function for declaring semantic intents.
69
+ *
70
+ * Uses a default shared registry for convenience, while still allowing
71
+ * isolated registries via `createIntentRegistry()`.
72
+ *
73
+ * Intents are the core of Ark's governance model. They give every
74
+ * architectural concept (domain events, use cases, adapter operations, workflows)
75
+ * an explicit, namespaced, machine-readable identity.
76
+ */
77
+
78
+ /**
79
+ * Define a new semantic intent.
80
+ *
81
+ * This is the main entry point most users (and AI generators) will use.
82
+ *
83
+ * @example
84
+ * ```ts
85
+ * // Domain event
86
+ * const OrderPlaced = defineIntent<'Domain.Order.OrderPlaced', {
87
+ * orderId: string;
88
+ * amount: number;
89
+ * }>('Domain.Order.OrderPlaced');
90
+ *
91
+ * const event = OrderPlaced({ orderId: 'o-42', amount: 99.5 });
92
+ *
93
+ * // Application operation that declares a dependency at definition time
94
+ * const ConfirmOrder = defineIntent<'Application.ConfirmOrder', { orderId: string }>(
95
+ * 'Application.ConfirmOrder',
96
+ * { dependsOn: ['Domain.Order.OrderPlaced'] }
97
+ * );
98
+ * ```
99
+ *
100
+ * @param name - Unique semantic name. Recommended convention:
101
+ * - `Domain.*` for domain concepts and events
102
+ * - `Application.*` for use cases / orchestration
103
+ * - `Adapter.*` for external integrations
104
+ * - `Workflow.*` for sagas and long-running processes
105
+ * @param options - Optional initial relationship declarations (`dependsOn`, `produces`)
106
+ */
107
+ declare function defineIntent<N extends IntentName, P = unknown>(name: N, options?: DefineIntentOptions): IntentCreator<N, P>;
108
+ /**
109
+ * Create an isolated IntentRegistry.
110
+ * Useful for testing, multiple bounded contexts, or advanced governance setups.
111
+ */
112
+ declare function createIntentRegistry(): IntentRegistry;
113
+ /**
114
+ * The default registry backing the top-level `defineIntent` calls.
115
+ * You can inspect it or use it directly if needed.
116
+ */
117
+ declare const defaultIntentRegistry: IntentRegistry;
118
+
119
+ /**
120
+ * Runtime validation for semantic intent naming conventions.
121
+ */
122
+ interface IntentNameValidation {
123
+ valid: boolean;
124
+ reason?: string;
125
+ }
126
+ /**
127
+ * Validate that an intent name follows Ark naming conventions.
128
+ */
129
+ declare function validateIntentName(name: string): IntentNameValidation;
130
+
131
+ /**
132
+ * Basic MetadataRegistry implementation.
133
+ */
134
+
135
+ declare function createMetadataRegistry(): MetadataRegistry;
136
+
137
+ /**
138
+ * Reference in-process read-model store. **Not production durability.**
139
+ * See `docs/production-hardening.md`.
140
+ */
141
+ declare class InMemoryReadModelStore implements ReadModelStore {
142
+ private readonly states;
143
+ load<State = unknown>(name: string): State | undefined;
144
+ save<State = unknown>(name: string, state: State): void;
145
+ clear(name?: string): void;
146
+ }
147
+ declare function createProjectionRegistry(options?: CreateProjectionRegistryOptions): ProjectionRegistry;
148
+
149
+ /**
150
+ * Typed error thrown when hard policies are violated.
151
+ */
152
+
153
+ declare class PolicyViolationError extends Error {
154
+ readonly violations: PolicyViolation[];
155
+ constructor(violations: PolicyViolation[]);
156
+ }
157
+
158
+ /**
159
+ * definePolicy
160
+ *
161
+ * Factory function to create architectural policies in a declarative way.
162
+ */
163
+
164
+ interface DefinePolicyOptions<Context = unknown> {
165
+ name: string;
166
+ severity?: PolicySeverity;
167
+ tags?: readonly string[];
168
+ owner?: string;
169
+ version?: string;
170
+ rationale?: string;
171
+ enforcementMode?: PolicyEnforcementMode;
172
+ deprecated?: boolean | string;
173
+ replacedBy?: string;
174
+ check: (context: Context) => boolean | PolicyViolation | PolicyViolation[];
175
+ }
176
+ /**
177
+ * Creates a Policy from a declarative configuration.
178
+ *
179
+ * The provided `check` function is called as-is. The PolicyEngine is responsible
180
+ * for normalizing results (booleans, single violations, arrays) into a consistent
181
+ * set of PolicyViolation objects.
182
+ *
183
+ * @example
184
+ * ```ts
185
+ * const noDomainToInfra = definePolicy({
186
+ * name: 'Domain must not depend on infrastructure',
187
+ * severity: 'hard',
188
+ * check: (ctx) => {
189
+ * const violations: PolicyViolation[] = [];
190
+ * // ... logic using ctx.registry.getAllRelationships()
191
+ * return violations.length > 0 ? violations : true;
192
+ * }
193
+ * });
194
+ * ```
195
+ */
196
+ declare function definePolicy<Context = unknown>(options: DefinePolicyOptions<Context>): Policy<Context>;
197
+
198
+ /**
199
+ * Built-in architectural policy helpers.
200
+ */
201
+
202
+ interface LayerFlowRule {
203
+ from: string;
204
+ to: string;
205
+ allowed: boolean;
206
+ message?: string;
207
+ }
208
+ interface LayerPolicyOptions {
209
+ name?: string;
210
+ severity?: 'hard' | 'soft';
211
+ /** Prefix rules — e.g. { from: 'Domain', to: 'Adapter', allowed: false } */
212
+ rules: LayerFlowRule[];
213
+ resolveLayer?: (name: string) => string | undefined;
214
+ }
215
+ /**
216
+ * Create a policy that enforces layer-crossing rules on graph edges or intent relationships.
217
+ */
218
+ declare function defineLayerPolicy<Context extends {
219
+ edges?: GraphEdge[];
220
+ relationships?: IntentRelationship[];
221
+ }>(options: LayerPolicyOptions): Policy<Context>;
222
+ /** True when a policy requires graph/registry context to enforce layer rules. */
223
+ declare function isLayerPolicy(policy: Policy): boolean;
224
+ /** Preset architectural policy factories. */
225
+ declare const architecturalPolicies: {
226
+ /**
227
+ * @deprecated Use cleanArchitectureMatrix() for full layer rules.
228
+ * Blocks Domain → Adapter declared dependencies only.
229
+ */
230
+ layerIsolation(): Policy<{
231
+ edges?: GraphEdge[];
232
+ relationships?: IntentRelationship[];
233
+ }>;
234
+ /**
235
+ * Clean-architecture dependency matrix (declared dependsOn / declared edges only).
236
+ * Does not block observed event flows (Domain events consumed by Application).
237
+ */
238
+ cleanArchitectureMatrix(): Policy<{
239
+ edges?: GraphEdge[];
240
+ relationships?: IntentRelationship[];
241
+ }>;
242
+ };
243
+ declare function defineArchitectureProfilePolicy<Context extends {
244
+ edges?: GraphEdge[];
245
+ relationships?: IntentRelationship[];
246
+ }>(profile: ArchitectureProfile, options?: Omit<LayerPolicyOptions, 'rules' | 'resolveLayer'>): Policy<Context>;
247
+
248
+ interface InMemoryEventBufferOptions {
249
+ /**
250
+ * Maximum records retained. When exceeded, the oldest settled record
251
+ * (`dispatched` / `failed`) is evicted first; only when every record is still
252
+ * `pending` is the oldest pending record evicted, and `evictedPending` counts
253
+ * it so the loss is visible. A record evicted while still in flight that is
254
+ * settled afterwards (`markDispatched` / `markFailed`) was delivered, not lost,
255
+ * so it leaves the count. Default: unbounded (`Infinity`). Kernels built by
256
+ * `createArkKernel` pass `maxHistorySize` (default 1000).
257
+ */
258
+ maxRecords?: number;
259
+ }
260
+ /**
261
+ * Reference in-process event buffer. **Not production durability** — state is lost on
262
+ * process exit. Use only for tests/demos/local single-process work; inject a durable
263
+ * store for production. This is not an atomic outbox (see `docs/production-hardening.md`).
264
+ */
265
+ declare class InMemoryEventBuffer implements EventBufferStore {
266
+ private readonly records;
267
+ private readonly maxRecords;
268
+ /**
269
+ * Ids evicted while `pending`, oldest first. A later settle removes the id (the
270
+ * record was in flight, not lost). Bounded to {@link EVICTED_PENDING_TRACK_LIMIT}
271
+ * ids so the tracker itself cannot grow without limit; ids that fall off stay counted.
272
+ */
273
+ private readonly evictedPendingIds;
274
+ private evictedPendingCount;
275
+ constructor(options?: InMemoryEventBufferOptions);
276
+ /**
277
+ * Pending records dropped because the cap was reached with nothing settled to
278
+ * evict, and never settled afterwards. Records still in flight when evicted
279
+ * (e.g. fire-and-forget local handlers) leave the count once the kernel
280
+ * settles them.
281
+ */
282
+ get evictedPending(): number;
283
+ private trackEvictedPending;
284
+ /** A settle for an evicted in-flight record: delivered, so not a loss. */
285
+ private settleEvicted;
286
+ private evictOverflow;
287
+ enqueue(event: DomainEvent): Promise<EventBufferRecord>;
288
+ markDispatched(id: string): Promise<void>;
289
+ markFailed(id: string, error: unknown): Promise<void>;
290
+ list(status?: EventBufferStatus): Promise<EventBufferRecord[]>;
291
+ clear(): Promise<void>;
292
+ }
293
+ /** @deprecated Use InMemoryEventBuffer. */
294
+ declare const InMemoryOutboxStore: typeof InMemoryEventBuffer;
295
+
296
+ /**
297
+ * EventBus implementation — public surface + publish orchestration.
298
+ *
299
+ * Publish pipeline stages live in cohesive modules (R8):
300
+ * guards → interceptors → contract re-check → observed layer flow →
301
+ * policy → history/outbox/trace → handlers → onPublish hook
302
+ */
303
+
304
+ declare function createEventBus<Context = unknown>(options?: EventBusOptions<Context>): EventBus;
305
+
306
+ /**
307
+ * Helpers for building policy evaluation context on event publish.
308
+ */
309
+
310
+ /**
311
+ * Standard context for policies evaluated during event publish.
312
+ * Includes the event plus optional registry relationships and graph edges
313
+ * so layer policies (e.g. architecturalPolicies.layerIsolation) can run.
314
+ */
315
+ interface PublishPolicyContext {
316
+ event: DomainEvent;
317
+ relationships?: IntentRelationship[];
318
+ edges?: GraphEdge[];
319
+ }
320
+ interface GraphPolicyContext {
321
+ relationships?: IntentRelationship[];
322
+ edges?: GraphEdge[];
323
+ }
324
+ interface BuildPublishPolicyContextOptions {
325
+ intentRegistry?: IntentRegistry;
326
+ dependencyGraph?: DependencyGraph;
327
+ }
328
+ /**
329
+ * Build a getPolicyContext function that feeds registry + graph data to policies.
330
+ *
331
+ * @example
332
+ * ```ts
333
+ * const bus = createEventBus({
334
+ * intentRegistry: registry,
335
+ * dependencyGraph: graph,
336
+ * policies: [architecturalPolicies.layerIsolation()],
337
+ * });
338
+ * ```
339
+ */
340
+ declare function buildPublishPolicyContext(options: BuildPublishPolicyContextOptions): (event: DomainEvent) => PublishPolicyContext;
341
+ declare function definePublishPolicy(options: DefinePolicyOptions<PublishPolicyContext>): Policy<PublishPolicyContext>;
342
+
343
+ /**
344
+ * Event bus governance errors.
345
+ */
346
+ declare class UnregisteredIntentError extends Error {
347
+ readonly intentName: string;
348
+ constructor(intentName: string);
349
+ }
350
+ declare class InvalidIntentNameError extends Error {
351
+ readonly intentName: string;
352
+ readonly reason: string;
353
+ constructor(intentName: string, reason: string);
354
+ }
355
+ declare class LayerPolicyContextError extends Error {
356
+ constructor();
357
+ }
358
+ declare class EventContractViolationError extends Error {
359
+ readonly intentName: string;
360
+ readonly issues: unknown[];
361
+ constructor(intentName: string, issues: unknown[]);
362
+ }
363
+ declare class UnknownEventSourceError extends Error {
364
+ readonly intentName: string;
365
+ readonly source?: string;
366
+ constructor(intentName: string, source?: string);
367
+ }
368
+ declare class SourceMetadataOverrideError extends Error {
369
+ readonly boundSource: string;
370
+ readonly attemptedSource: string;
371
+ constructor(boundSource: string, attemptedSource: string);
372
+ }
373
+ /**
374
+ * Thrown when the OBSERVED producer→event flow crosses a forbidden layer boundary
375
+ * under `enforceObservedLayerFlow: 'hard'`. Unlike declared-model policy errors, this
376
+ * reflects what the running system actually did at publish time.
377
+ */
378
+ declare class ObservedLayerFlowViolationError extends Error {
379
+ readonly source: string;
380
+ readonly intentName: string;
381
+ readonly fromLayer: string;
382
+ readonly toLayer: string;
383
+ constructor(source: string, intentName: string, fromLayer: string, toLayer: string, message?: string);
384
+ }
385
+ /**
386
+ * A kernel built from an `ark.config.json` was explicitly asked for hard
387
+ * observed-layer-flow enforcement (`enforceObservedLayerFlow: 'hard'`), but some
388
+ * deny-rule layers declare no `intentPrefixes` and are not canonical 11-layer
389
+ * names (which get built-in prefixes), so no intent maps to them and the rule
390
+ * would be a silent no-op. With the strict default (hard implied, not passed),
391
+ * the kernel builds and records a `layer.observedFlowUnresolvable` audit record
392
+ * instead. Fix: add `intentPrefixes`, or pass `'soft' | 'off'`.
393
+ */
394
+ declare class ArkKernelConfigError extends Error {
395
+ readonly code: 'ARKRUN_LAYER_FLOW_UNRESOLVABLE';
396
+ readonly layers: string[];
397
+ constructor(layers: string[]);
398
+ }
399
+
400
+ declare function createObservabilityReporter(options: CreateObservabilityReporterOptions): ObservabilityReporter;
401
+
402
+ /** Current Ark manifest JSON schema version. */
403
+ declare const MANIFEST_SCHEMA_VERSION = "1.0";
404
+
405
+ /**
406
+ * Aggregates kernel registries into a single machine-readable manifest.
407
+ */
408
+
409
+ interface CreateArkManifestOptions {
410
+ registry?: IntentRegistry;
411
+ policyEngine?: PolicyEngine;
412
+ metadata?: MetadataRegistry;
413
+ graph?: DependencyGraph;
414
+ profile?: ArchitectureProfile;
415
+ projections?: ProjectionRegistry;
416
+ eventContracts?: EventContractRegistry;
417
+ observability?: ObservabilityReporter;
418
+ }
419
+ /**
420
+ * Create a machine-readable snapshot of the current architectural contract.
421
+ * Intended for AI agents, codegen tools, and documentation generators.
422
+ */
423
+ declare function createArkManifest(options?: CreateArkManifestOptions): ArkManifest;
424
+
425
+ /**
426
+ * In-process workflow engine with durable-store seams.
427
+ */
428
+
429
+ /**
430
+ * Reference in-process workflow store. **Not production durability.**
431
+ * See `docs/production-hardening.md`.
432
+ */
433
+ declare class InMemoryWorkflowStore implements WorkflowStore {
434
+ private readonly snapshots;
435
+ save<P extends SagaContext>(snapshot: WorkflowSnapshot<P>, _tx?: unknown): void;
436
+ get<P extends SagaContext = SagaContext>(id: string, _tx?: unknown): WorkflowSnapshot<P> | undefined;
437
+ list(workflowName?: string): WorkflowSnapshot[];
438
+ claim(workerId: string, timeoutMs: number, workflowName?: string): WorkflowSnapshot | undefined;
439
+ clear(): void;
440
+ }
441
+ declare function createWorkflowEngine(bus: EventBus, options?: CreateWorkflowEngineOptions): WorkflowEngine;
442
+ declare function createSaga<P extends SagaContext = SagaContext>(def: SagaDefinition<P>, bus: EventBus, options?: CreateWorkflowEngineOptions & {
443
+ id?: string;
444
+ }): SagaInstance<P>;
445
+
446
+ /** ArkGate library version — single source of truth. */
447
+ declare const version = "4.8.24";
3
448
 
4
449
  /** Versioned public result contract types + JSON Schema (adapter envelope). */
5
450
  /**
@@ -8,8 +453,6 @@ import { A as ArkConfig, c as ArkConfigLoadResult } from './configTypes-Bbf_MFGe
8
453
  * 1.4 added optional evidence.arkruleId + evidence.arkruleSource (ADR 0012 / AR03).
9
454
  */
10
455
  declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.5";
11
- /** Repo-relative diagnostics docs path (parity with ACS02 diagnostic catalog). */
12
- declare const ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH: "docs/diagnostics.md";
13
456
  type AdapterSeverity = 'error' | 'warning';
14
457
  type AnalysisCompleteness = 'complete' | 'partial' | 'unavailable';
15
458
  type AnalysisMode = 'lexical-compatibility' | 'resolved-candidate-facts';
@@ -77,6 +520,12 @@ type AdapterDiagnostic = {
77
520
  arkruleId?: string;
78
521
  /** AR03 — ArkRules source file path. */
79
522
  arkruleSource?: string;
523
+ /** Nested-wall reason. Not part of the baseline key. */
524
+ reasonId?: 'CROSS_PARENT_SLICE' | 'CROSS_SIBLING_SLICE' | 'CROSS_PARENT_VIA_SHARED';
525
+ /** Last segment of the importer universe id, with a reasonId. */
526
+ universeFrom?: string;
527
+ /** Last segment of the importee universe id, with a reasonId. */
528
+ universeTo?: string;
80
529
  };
81
530
  /** Added in schema 1.1; optional in TypeScript so 1.0 consumer-owned values remain valid. */
82
531
  nextAction?: string;
@@ -347,6 +796,17 @@ declare const ARK_ANALYSIS_RESULT_SCHEMA: {
347
796
  readonly type: "string";
348
797
  readonly minLength: 1;
349
798
  };
799
+ readonly reasonId: {
800
+ readonly enum: readonly ["CROSS_PARENT_SLICE", "CROSS_SIBLING_SLICE", "CROSS_PARENT_VIA_SHARED"];
801
+ };
802
+ readonly universeFrom: {
803
+ readonly type: "string";
804
+ readonly minLength: 1;
805
+ };
806
+ readonly universeTo: {
807
+ readonly type: "string";
808
+ readonly minLength: 1;
809
+ };
350
810
  };
351
811
  };
352
812
  readonly nextAction: {
@@ -397,8 +857,137 @@ declare function createAdapterResult(input: {
397
857
  warnings?: readonly AdapterViolationInput[];
398
858
  }): CurrentAdapterResult;
399
859
 
400
- /** ArkGate library version — single source of truth. */
401
- declare const version = "4.8.23";
860
+ /**
861
+ * In-memory shadow / replay / compare for ArkRun information packages (XP07 / ADR 0033).
862
+ * Not durable. Not a second bus. Stripped snapshots only.
863
+ */
864
+
865
+ type InformationPackageDiff = {
866
+ readonly path: string;
867
+ readonly left: unknown;
868
+ readonly right: unknown;
869
+ };
870
+ type InformationPackageCompare = {
871
+ readonly equal: boolean;
872
+ readonly diffs: readonly InformationPackageDiff[];
873
+ };
874
+ /** Shadow: identity snapshot. The live kernel is not copied. */
875
+ declare function shadowInformationPackage(pack: DependencyInformationPackage): DependencyInformationPackage;
876
+ declare function compareInformationPackages(left: DependencyInformationPackage, right: DependencyInformationPackage): InformationPackageCompare;
877
+ /**
878
+ * Replay: apply sequential snapshots as the "tape". Each step is compared to
879
+ * the previous shadow. No bus, no store, no time travel across processes.
880
+ */
881
+ declare function replayInformationPackages(tape: readonly DependencyInformationPackage[]): InformationPackageCompare[];
882
+
883
+ /**
884
+ * Default cap for in-memory history, trace, audit, and default event-buffer
885
+ * records. Without a cap a long-running process grows without bound on every
886
+ * publish. Pass `maxHistorySize: Infinity` to explicitly opt back into unbounded
887
+ * retention. An injected `eventBuffer` owns its own retention.
888
+ */
889
+ declare const DEFAULT_MAX_HISTORY_SIZE = 1000;
890
+ declare function createArkKernel(options?: CreateArkKernelOptions): ArkKernel;
891
+ /**
892
+ * Preferred ArkRun factory. Each call is a new isolated instance — there is no
893
+ * process-wide singleton.
894
+ */
895
+ declare function createStrictArkKernel(options?: CreateArkKernelOptions): ArkKernel;
896
+ declare function createArkKernelFromConfig(config: ArkKernelConfig, options?: CreateArkKernelFromConfigOptions): ArkKernel;
897
+ /**
898
+ * Strict kernel whose runtime layer profile comes from `ark.config.json`.
899
+ * Hard observed-layer-flow needs every layer a deny rule names to resolve an
900
+ * intent: declared `intentPrefixes`, or a canonical 11-layer name (`DomainModel`,
901
+ * `ApplicationOrchestration`, … — what `ark init` writes) which gets the built-in
902
+ * prefixes. A custom-named deny layer without prefixes is recorded as a
903
+ * `layer.observedFlowUnresolvable` audit record (`ARKRUN_LAYER_FLOW_UNRESOLVABLE`);
904
+ * passing `enforceObservedLayerFlow: 'hard'` explicitly throws `ArkKernelConfigError`
905
+ * instead.
906
+ */
907
+ declare function createStrictArkKernelFromConfig(config: ArkKernelConfig, options?: CreateArkKernelFromConfigOptions): ArkKernel;
908
+ declare function createLenientArkKernelFromConfig(config: ArkKernelConfig, options?: CreateArkKernelFromConfigOptions): ArkKernel;
909
+ declare function createLenientArkKernel(options?: CreateArkKernelOptions): ArkKernel;
910
+
911
+ interface ArkTestSnapshot {
912
+ events: DomainEvent[];
913
+ traces: TraceRecord[];
914
+ audit: AuditRecord[];
915
+ outbox: OutboxRecord[];
916
+ observability: ObservabilityDriftReport;
917
+ }
918
+ interface ArkTestHarness {
919
+ events(intent?: string): DomainEvent[];
920
+ traces(type?: TraceRecordType): TraceRecord[];
921
+ audit(query?: AuditQuery): Promise<AuditRecord[]>;
922
+ outbox(status?: OutboxStatus): Promise<OutboxRecord[]>;
923
+ observability(): ObservabilityDriftReport;
924
+ snapshot(): Promise<ArkTestSnapshot>;
925
+ clear(): Promise<void>;
926
+ }
927
+
928
+ declare function createArkTestHarness(kernel: ArkKernel): ArkTestHarness;
929
+
930
+ /**
931
+ * Ports & Adapters basic contracts.
932
+ */
933
+ interface Port<T = unknown> {
934
+ readonly name: string;
935
+ readonly ownerLayer?: string;
936
+ readonly intent?: IntentName;
937
+ readonly allowedAdapters?: string[];
938
+ readonly __port?: T;
939
+ }
940
+ interface Adapter<T = unknown> {
941
+ readonly name?: string;
942
+ readonly layer?: string;
943
+ readonly intent?: IntentName;
944
+ readonly port: Port<T>;
945
+ readonly impl: T;
946
+ }
947
+ interface DefinePortOptions {
948
+ ownerLayer?: string;
949
+ intent?: IntentName;
950
+ allowedAdapters?: string[];
951
+ }
952
+ interface CreateAdapterOptions {
953
+ name?: string;
954
+ layer?: string;
955
+ intent?: IntentName;
956
+ requiredKeys?: string[];
957
+ }
958
+ /**
959
+ * Simple contract checker (duck typing + optional required keys).
960
+ */
961
+ type ContractCheckResult = {
962
+ ok: true;
963
+ } | {
964
+ ok: false;
965
+ missing: string[];
966
+ };
967
+ interface AdapterGovernanceIssue {
968
+ ruleId: 'ADAPTER_NOT_ALLOWED_FOR_PORT';
969
+ message: string;
970
+ port: string;
971
+ adapter?: string;
972
+ }
973
+ type AdapterGovernanceResult = {
974
+ ok: true;
975
+ issues: [];
976
+ } | {
977
+ ok: false;
978
+ issues: AdapterGovernanceIssue[];
979
+ };
980
+
981
+ /**
982
+ * Ports and Adapters utilities.
983
+ *
984
+ * definePort + createAdapter with basic runtime contract validation.
985
+ */
986
+
987
+ declare function definePort<T = unknown>(name: string, options?: DefinePortOptions): Port<T>;
988
+ declare function createAdapter<T>(port: Port<T>, impl: T, requiredKeysOrOptions?: string[] | CreateAdapterOptions, adapterOptions?: CreateAdapterOptions): Adapter<T>;
989
+ declare function checkContract(impl: unknown, requiredKeys?: string[]): ContractCheckResult;
990
+ declare function checkAdapterGovernance(adapter: Adapter): AdapterGovernanceResult;
402
991
 
403
992
  /**
404
993
  * AI Code Gate (basic).
@@ -420,6 +1009,12 @@ interface AICodeGateViolation {
420
1009
  toLayer?: string;
421
1010
  /** Nested-wall reason. Absent on a classic layer deny and on a child-only parent import. */
422
1011
  reasonId?: string;
1012
+ /** Last segment of the importer universe id, with a reasonId. */
1013
+ universeFrom?: string;
1014
+ /** Last segment of the importee universe id, with a reasonId. */
1015
+ universeTo?: string;
1016
+ /** True when a peerIsolation rule produced this finding (also mirrored in details). */
1017
+ peerIsolation?: boolean;
423
1018
  /** False for an advisory sibling crossing. Omitted findings still block the snippet. */
424
1019
  failsStrict?: boolean;
425
1020
  details?: unknown;
@@ -451,11 +1046,6 @@ interface AICodeGate<Context = AICodeGateContext> {
451
1046
  validate(source: string, context?: Context): AICodeGateResult;
452
1047
  }
453
1048
 
454
- declare function createArchitectureProfile(options: CreateArchitectureProfileOptions): ArchitectureProfile;
455
- declare function createArchitectureProfileFromArkConfig(config: ArkCheckConfig, options?: CreateArchitectureProfileFromArkConfigOptions): ArchitectureProfile;
456
- declare const elevenLayerProfile: ArchitectureProfile;
457
- declare function createElevenLayerArkConfig(options?: CreateElevenLayerArkConfigOptions): ArkCheckConfig;
458
-
459
1049
  /**
460
1050
  * Basic AI Code Gate implementation.
461
1051
  *
@@ -551,6 +1141,10 @@ declare function deterministicHash(value: string): string;
551
1141
  /** Serialize JSON-like values with sorted object keys for reproducible hashes. */
552
1142
  declare function stableSerialize(value: unknown): string;
553
1143
 
1144
+ /**
1145
+ * ArkOrder resolver-fact extraction (ADR 0029). Syntax only — no verdicts.
1146
+ */
1147
+
554
1148
  type ResolvedArkOrderPlaneCallFact = {
555
1149
  file: string;
556
1150
  line: number;
@@ -580,6 +1174,18 @@ type ResolvedArkOrderReleaseKeyCountFact = {
580
1174
  line: number;
581
1175
  keyCount: number;
582
1176
  };
1177
+ /** A freshness key (ttl/freshUntil/maxAge) inside the ξ literal of plane.release / proposeRelease. */
1178
+ type ResolvedArkOrderXiTtlFact = {
1179
+ file: string;
1180
+ line: number;
1181
+ key: string;
1182
+ };
1183
+ /** A literal `allowedKinds` entry that a literal `informationBudget.cannotObserve` denies. */
1184
+ type ResolvedArkOrderBudgetLeakFact = {
1185
+ file: string;
1186
+ line: number;
1187
+ kind: string;
1188
+ };
583
1189
 
584
1190
  /**
585
1191
  * Versioned type vocabulary for resolved candidate facts (schema 1.0).
@@ -655,6 +1261,8 @@ type ResolvedClassShapeFact = {
655
1261
  referencesGuardOrPublish: boolean;
656
1262
  }[];
657
1263
  dataOnly?: boolean;
1264
+ /** Source offset where the class-shape scan stopped (unwalkable body/header). */
1265
+ truncatedUntil?: number;
658
1266
  };
659
1267
  type ResolvedDependencyFact = {
660
1268
  from: string;
@@ -734,8 +1342,10 @@ type ResolvedCandidateFactsInput = {
734
1342
  arkOrderXiFieldWrites?: readonly ResolvedArkOrderXiFieldWriteFact[];
735
1343
  arkOrderIngestWritesXi?: readonly ResolvedArkOrderIngestWriteFact[];
736
1344
  arkOrderReleaseKeyCounts?: readonly ResolvedArkOrderReleaseKeyCountFact[];
1345
+ arkOrderXiTtlKeys?: readonly ResolvedArkOrderXiTtlFact[];
1346
+ arkOrderBudgetLeaks?: readonly ResolvedArkOrderBudgetLeakFact[];
737
1347
  };
738
- type ResolvedCandidateFacts = Omit<ResolvedCandidateFactsInput, 'candidateTreeHash' | 'classShapes' | 'arkRunKernelCalls' | 'arkOrderPlaneCalls' | 'arkOrderGenericUpdates' | 'arkOrderXiFieldWrites' | 'arkOrderIngestWritesXi' | 'arkOrderReleaseKeyCounts' | 'arkOrderRootHits' | 'arkRunManagedNews' | 'arkRunCompositionRootHits' | 'arkRunDeclarations'> & {
1348
+ type ResolvedCandidateFacts = Omit<ResolvedCandidateFactsInput, 'candidateTreeHash' | 'classShapes' | 'arkRunKernelCalls' | 'arkOrderPlaneCalls' | 'arkOrderGenericUpdates' | 'arkOrderXiFieldWrites' | 'arkOrderIngestWritesXi' | 'arkOrderReleaseKeyCounts' | 'arkOrderXiTtlKeys' | 'arkOrderBudgetLeaks' | 'arkOrderRootHits' | 'arkRunManagedNews' | 'arkRunCompositionRootHits' | 'arkRunDeclarations'> & {
739
1349
  schemaVersion: typeof RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION;
740
1350
  completenessReasons: ResolvedFactsReason[];
741
1351
  candidateTreeHash: string;
@@ -757,6 +1367,8 @@ type ResolvedCandidateFacts = Omit<ResolvedCandidateFactsInput, 'candidateTreeHa
757
1367
  arkOrderXiFieldWrites: ResolvedArkOrderXiFieldWriteFact[];
758
1368
  arkOrderIngestWritesXi: ResolvedArkOrderIngestWriteFact[];
759
1369
  arkOrderReleaseKeyCounts: ResolvedArkOrderReleaseKeyCountFact[];
1370
+ arkOrderXiTtlKeys: ResolvedArkOrderXiTtlFact[];
1371
+ arkOrderBudgetLeaks: ResolvedArkOrderBudgetLeakFact[];
760
1372
  factsHash: string;
761
1373
  };
762
1374
 
@@ -1180,6 +1792,10 @@ declare const RESOLVED_CANDIDATE_FACTS_SCHEMA: {
1180
1792
  readonly dataOnly: {
1181
1793
  readonly type: "boolean";
1182
1794
  };
1795
+ readonly truncatedUntil: {
1796
+ readonly type: "integer";
1797
+ readonly minimum: 0;
1798
+ };
1183
1799
  readonly mutatingMethods: {
1184
1800
  readonly type: "array";
1185
1801
  readonly items: {
@@ -1466,6 +2082,52 @@ declare const RESOLVED_CANDIDATE_FACTS_SCHEMA: {
1466
2082
  };
1467
2083
  };
1468
2084
  };
2085
+ readonly arkOrderXiTtlKeys: {
2086
+ readonly type: "array";
2087
+ readonly items: {
2088
+ readonly type: "object";
2089
+ readonly additionalProperties: false;
2090
+ readonly required: readonly ["file", "line", "key"];
2091
+ readonly properties: {
2092
+ readonly file: {
2093
+ readonly type: "string";
2094
+ readonly minLength: 1;
2095
+ readonly pattern: "^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$";
2096
+ };
2097
+ readonly line: {
2098
+ readonly type: "integer";
2099
+ readonly minimum: 1;
2100
+ };
2101
+ readonly key: {
2102
+ readonly type: "string";
2103
+ readonly minLength: 1;
2104
+ };
2105
+ };
2106
+ };
2107
+ };
2108
+ readonly arkOrderBudgetLeaks: {
2109
+ readonly type: "array";
2110
+ readonly items: {
2111
+ readonly type: "object";
2112
+ readonly additionalProperties: false;
2113
+ readonly required: readonly ["file", "line", "kind"];
2114
+ readonly properties: {
2115
+ readonly file: {
2116
+ readonly type: "string";
2117
+ readonly minLength: 1;
2118
+ readonly pattern: "^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$";
2119
+ };
2120
+ readonly line: {
2121
+ readonly type: "integer";
2122
+ readonly minimum: 1;
2123
+ };
2124
+ readonly kind: {
2125
+ readonly type: "string";
2126
+ readonly minLength: 1;
2127
+ };
2128
+ };
2129
+ };
2130
+ };
1469
2131
  readonly factsHash: {
1470
2132
  readonly type: "string";
1471
2133
  readonly minLength: 1;
@@ -1698,13 +2360,6 @@ type ArkRuleInvariantEntry = {
1698
2360
  mode?: ArkRuleMode;
1699
2361
  appliesTo?: string[];
1700
2362
  };
1701
- type ArkRulesFile = {
1702
- $schema?: string;
1703
- schemaVersion: '1.0';
1704
- layer: string;
1705
- structure?: ArkRuleStructureEntry[];
1706
- invariants?: ArkRuleInvariantEntry[];
1707
- };
1708
2363
  type ArkRuleProvenance = {
1709
2364
  sourceFile: string;
1710
2365
  ruleId: string;
@@ -1744,53 +2399,6 @@ type EffectiveArkRules = {
1744
2399
  * method.
1745
2400
  */
1746
2401
  type DeclarationShape = 'function' | 'class' | 'const' | 'method' | 'type' | 'interface' | 'enum';
1747
- /** Where a bare mention of an id or symbol sat. Never coverage. */
1748
- type MentionContext = 'test-body' | 'comment' | 'string' | 'import';
1749
- /**
1750
- * One coverage verdict. Best evidence wins: test-title, then declaration,
1751
- * then mention-only, then none. A comment in another file, when the symbol
1752
- * still occurs in code, is `declaration-miss` and does not count.
1753
- * Regexes, the test-file vs source split, and `Aggregate.method` lookup stay
1754
- * behind this value.
1755
- */
1756
- type CoverageEvidence = {
1757
- kind: 'test-title';
1758
- file: string;
1759
- title: string;
1760
- } | {
1761
- kind: 'declaration';
1762
- file: string;
1763
- shape: DeclarationShape;
1764
- } | {
1765
- kind: 'mention-only';
1766
- file: string;
1767
- context: MentionContext;
1768
- } | {
1769
- kind: 'declaration-miss';
1770
- symbol: string;
1771
- } | {
1772
- kind: 'none';
1773
- };
1774
- /** Invariant fields the classifier reads. A full catalog entry is assignable. */
1775
- type CoverageInvariant = {
1776
- id: string;
1777
- coverage?: {
1778
- test?: boolean;
1779
- symbol?: string;
1780
- } | null;
1781
- };
1782
- /** File set the classifier reads. Tooling has already loaded the contents. */
1783
- type CoverageFiles = {
1784
- /** Project-relative path → file contents (tests and sources). */
1785
- fileContents: Readonly<Record<string, string>>;
1786
- /** Paths already classified as tests. */
1787
- testFiles?: readonly string[];
1788
- /**
1789
- * Declared runner roots. A test title inside a root beats one outside it.
1790
- * The outside-roots finding stays a separate verdict.
1791
- */
1792
- coverageRoots?: readonly string[];
1793
- };
1794
2402
  type InvariantCoverageEvidence = {
1795
2403
  invariantId: string;
1796
2404
  layer: string;
@@ -1829,48 +2437,6 @@ type InvariantCoverageEvidence = {
1829
2437
  */
1830
2438
  coverageRootsDeclared?: boolean;
1831
2439
  };
1832
- type InvariantUncoveredKind = 'never-had-tests' | 'tests-disappeared';
1833
- type InvariantCoverageRuleId = 'INVARIANT_UNCOVERED' | 'INVARIANT_COVERAGE_OUTSIDE_ROOTS';
1834
- type InvariantCoverageViolation = {
1835
- ruleId: InvariantCoverageRuleId;
1836
- message: string;
1837
- file: string;
1838
- line: number;
1839
- arkruleId: string;
1840
- arkruleSource: string;
1841
- fromLayer: string;
1842
- severity: 'error' | 'warning';
1843
- failsStrict: boolean;
1844
- /**
1845
- * Adopt residual (no test suite) vs regression (suite exists, coverage gone).
1846
- * Only INVARIANT_UNCOVERED carries it: an outside-roots finding is about
1847
- * WHERE the covering test lives, not about whether one exists.
1848
- */
1849
- kind?: InvariantUncoveredKind;
1850
- };
1851
- type EvaluateInvariantCoverageInput = {
1852
- arkRules: EffectiveArkRules;
1853
- /** Project-relative path → file contents (tests + domain sources). */
1854
- fileContents: Readonly<Record<string, string>>;
1855
- /** Paths considered tests (already filtered by Tooling via globs). */
1856
- testFiles?: readonly string[];
1857
- /** When true, missing test files make coverage partial (never green covered). */
1858
- testGlobsMissing?: boolean;
1859
- /**
1860
- * Tooling hit MAX_COVERAGE_FILES. Partial must not claim the repo never had tests —
1861
- * the suite may exist outside the scan budget.
1862
- */
1863
- coverageBudgetExhausted?: boolean;
1864
- /** Numbers behind the scan: what was loaded, what was discarded and why. */
1865
- coverageStats?: InvariantCoverageStats;
1866
- /**
1867
- * Declared (`coverage.coverageRoots`) path prefixes where the project says its
1868
- * runner actually executes tests. ArkGate never executes anything: this is a
1869
- * second DECLARATION to compare the first against. Absent or empty means no
1870
- * declaration was made, so no outside-roots claim is possible.
1871
- */
1872
- coverageRoots?: readonly string[];
1873
- };
1874
2440
  /**
1875
2441
  * What the Tooling scan actually saw. Every discard has a counted reason —
1876
2442
  * a silent drop would make an uncovered verdict unexplainable.
@@ -1911,31 +2477,6 @@ type InvariantCoverageStats = {
1911
2477
  outOfRoot: number;
1912
2478
  };
1913
2479
  };
1914
- /**
1915
- * Best coverage evidence for `invariant` in `files`.
1916
- * test-title beats a declaration; a declaration beats a bare mention; a bare
1917
- * mention beats silence. Callers do not re-scan to explain the verdict.
1918
- */
1919
- declare function classifyCoverage(invariant: CoverageInvariant, files: CoverageFiles): CoverageEvidence;
1920
- /**
1921
- * Policy: a test title or any declaration counts, including type, interface,
1922
- * and enum. A mention-only verdict never counts. `none` does not count.
1923
- */
1924
- declare function countsAsCoverage(ev: CoverageEvidence): boolean;
1925
- /** Sentence for the verdict. `INVARIANT_UNCOVERED` prints this; it does not re-derive it. */
1926
- declare function describeCoverage(invariant: CoverageInvariant, ev: CoverageEvidence): string;
1927
- declare function evaluateInvariantCoverage(input: EvaluateInvariantCoverageInput): {
1928
- coverage: InvariantCoverageEvidence[];
1929
- violations: InvariantCoverageViolation[];
1930
- partial: boolean;
1931
- };
1932
- /**
1933
- * Deterministic promotion gate: refuse advisory→enforced when invariant is uncovered.
1934
- */
1935
- declare function canPromoteInvariant(coverage: InvariantCoverageEvidence | undefined): {
1936
- ok: boolean;
1937
- reason: string;
1938
- };
1939
2480
 
1940
2481
  /**
1941
2482
  * Pure ArkRules structure sensor evaluation (ADR 0013).
@@ -1958,85 +2499,37 @@ type ClassShapeFact = {
1958
2499
  }[];
1959
2500
  /** Heuristic: data-only class (fields, no methods beyond accessors). */
1960
2501
  dataOnly?: boolean;
1961
- };
1962
- type ArkRuleSensorViolation = {
1963
- ruleId: string;
1964
- code: string;
1965
- message: string;
1966
- file: string;
1967
- line: number;
1968
- fromLayer?: string;
1969
- arkruleId: string;
1970
- arkruleSource: string;
1971
- severity: 'error' | 'warning';
1972
- sensor: ArkRuleSensorId;
1973
- /** When true, advisory surfaces only (does not fail strict). */
1974
- failsStrict: boolean;
1975
- };
1976
- type EvaluateArkRuleSensorsInput = {
1977
- arkRules: EffectiveArkRules;
1978
- classShapes: readonly ClassShapeFact[];
1979
- /** Project-relative paths in scope for the analysis. */
1980
- files: readonly string[];
1981
2502
  /**
1982
- * Optional layer membership: path → layer name. When omitted, structure rules
1983
- * apply by appliesTo globs only (or all files when appliesTo is absent).
2503
+ * Set when the scanner could not walk the class to its end: the character
2504
+ * offset (in the source file) where analysis stopped. Enumerable on purpose so
2505
+ * it survives fact canonicalisation and serialisation; enforced structure
2506
+ * sensors report it instead of passing in silence.
1984
2507
  */
1985
- layerForFile?: (path: string) => string | null | undefined;
1986
- /**
1987
- * Optional thin/orchestration heuristic flags per file (Tooling-supplied).
1988
- */
1989
- fileHints?: Readonly<Record<string, {
1990
- orchestrationHeavy?: boolean;
1991
- adapterThick?: boolean;
1992
- persistenceWrite?: boolean;
1993
- }>>;
1994
- };
1995
- /**
1996
- * Evaluate all structure sensors. Empty Effective Contract → no findings (byte-for-byte parity).
1997
- */
1998
- declare function evaluateArkRuleSensors(input: EvaluateArkRuleSensorsInput): ArkRuleSensorViolation[];
1999
- /**
2000
- * ADR 0012 D3 — a structure rule whose appliesTo matches zero governed files is
2001
- * never silent green. Advisory → warning; enforced → failsStrict.
2002
- * Rules without appliesTo (whole-layer) never emit this signal.
2003
- */
2004
- declare function collectEmptyAppliesToFindings(arkRules: EffectiveArkRules, files: readonly string[]): ArkRuleSensorViolation[];
2005
- /** Optional resolved-import facts when the collector already classified the specifier. */
2006
- type ResolvedPersistenceImportFact = {
2007
- specifier?: string;
2008
- resolvedFile?: string;
2009
- layer?: string | null;
2508
+ truncatedUntil?: number;
2010
2509
  };
2510
+
2011
2511
  /**
2012
- * Pure Tooling/Domain heuristic for orchestration-only / thin-adapter fileHints.
2013
- * Prefers false negatives over false positives (ADR 0013 discipline).
2014
- * Returns null when neither flag is set (callers may omit the path).
2015
- */
2016
- declare function deriveArkRuleFileHints(_file: string, content: string, resolvedImports?: readonly ResolvedPersistenceImportFact[]): {
2017
- orchestrationHeavy?: boolean;
2018
- adapterThick?: boolean;
2019
- persistenceWrite?: boolean;
2020
- } | null;
2021
- /**
2022
- * Build fileHints map from path→content. Omits paths with no flags (sparse map).
2023
- */
2024
- declare function buildArkRuleFileHints(fileContents: Readonly<Record<string, string>>, resolvedImportsByFile?: Readonly<Record<string, readonly ResolvedPersistenceImportFact[]>>): Record<string, {
2025
- orchestrationHeavy?: boolean;
2026
- adapterThick?: boolean;
2027
- persistenceWrite?: boolean;
2028
- }>;
2029
- /**
2030
- * Lightweight class-shape extraction from TypeScript source text (no compiler).
2031
- * Conservative: prefers false negatives over false positives for mutability.
2032
- * Tooling may replace with TypeScript-API facts; sensors consume the same shape.
2512
+ * Config-key version floors plus pin evidence (#338).
2033
2513
  *
2034
- * Limitation (AR05/AR06): only `export class` / `export abstract class` forms.
2035
- * `export default class`, re-exported classes, and non-exported aggregates are
2036
- * invisible — enforced structure sensors stay silent (false negative). Silence
2037
- * is never proof of compliance.
2514
+ * A slice key such as `childSlices` is rejected at config load by an older
2515
+ * arkgate (the rule schema sets `additionalProperties: false`). ArkGate warns
2516
+ * about that only with evidence that this repo pins such an older arkgate: an
2517
+ * exact package.json dependency, the installed copy, the lockfile, a hook
2518
+ * script, or a CI workflow. Without evidence it stays silent.
2519
+ *
2520
+ * Pure: Tooling reads the files and passes their text here.
2038
2521
  */
2039
- declare function extractClassShapesFromSource(file: string, content: string): ClassShapeFact[];
2522
+ /** Where a pin was found. */
2523
+ type ArkgatePinSource = 'package-json' | 'package-lock' | 'installed' | 'hook' | 'ci';
2524
+ type ArkgatePinEvidence = {
2525
+ /** Repo-relative file that pins arkgate. */
2526
+ file: string;
2527
+ /** 1-based line of the pin. */
2528
+ line: number;
2529
+ /** Pinned version, without a leading `v`. */
2530
+ version: string;
2531
+ source: ArkgatePinSource;
2532
+ };
2040
2533
 
2041
2534
  declare const POLICY_DELTA_SCHEMA_VERSION: "1.0";
2042
2535
  type PolicyDeltaClassification = 'strengthening' | 'neutral' | 'judgment-required' | 'weakening';
@@ -2116,6 +2609,10 @@ type AnalysisResult = {
2116
2609
  type AnalyzeResolvedProjectInput = {
2117
2610
  contract: AnalysisContract;
2118
2611
  facts: unknown;
2612
+ /** Tooling FS evidence of arkgate pins. Omitted: version-floor warnings stay silent. */
2613
+ arkgatePins?: readonly ArkgatePinEvidence[];
2614
+ /** The running arkgate version, for the version-floor nextAction. */
2615
+ runningArkgateVersion?: string;
2119
2616
  /**
2120
2617
  * D0 adopted or --require-gates / --strict-merge. When true, a missing
2121
2618
  * domain-invariant tests path fails closed. Omitted stays silent.
@@ -2158,12 +2655,20 @@ type AnalyzeResolvedProjectInput = {
2158
2655
  persistenceWrite?: boolean;
2159
2656
  }>>;
2160
2657
  };
2658
+ /** Tooling-supplied analysis evidence for one side (base or candidate) of a preflight. */
2659
+ type ResolvedAnalysisSideInputs = Pick<AnalyzeResolvedProjectInput, 'adopted' | 'invariantTestsPathPresent' | 'coverageRootsPresent' | 'coverageInputs' | 'fileHints'>;
2161
2660
  type PreflightResolvedChangeInput = {
2162
2661
  contract: AnalysisContract;
2163
2662
  baseFacts: unknown;
2164
2663
  candidateFacts: unknown;
2165
2664
  changes: readonly AnalysisFileChange[];
2166
2665
  changeMap?: ArchitectureChangeMapContract;
2666
+ /**
2667
+ * ArkRules evidence (coverage contents, structural hints) for the on-disk base and
2668
+ * the in-memory candidate, so preflight runs the same engine inputs as ark-check.
2669
+ */
2670
+ baseAnalysisInputs?: ResolvedAnalysisSideInputs;
2671
+ candidateAnalysisInputs?: ResolvedAnalysisSideInputs;
2167
2672
  };
2168
2673
  type ResolvedAnalysisFile = ResolvedFileFact & {
2169
2674
  layer: string | null;
@@ -2342,6 +2847,13 @@ type CollectAnalysisConfigWarningsInput = {
2342
2847
  config: ArkConfig;
2343
2848
  rules: ArkConfig['rules'];
2344
2849
  files: readonly string[];
2850
+ /**
2851
+ * Tooling FS evidence of arkgate pins in this repo (package.json, lockfile,
2852
+ * installed copy, hook scripts, CI). Omitted: version-floor warnings stay silent.
2853
+ */
2854
+ arkgatePins?: readonly ArkgatePinEvidence[];
2855
+ /** The running arkgate version. The version-floor nextAction targets it when newer. */
2856
+ runningArkgateVersion?: string;
2345
2857
  manifest?: {
2346
2858
  architecture?: {
2347
2859
  layers?: readonly {
@@ -2390,6 +2902,8 @@ declare function analyzeResolvedProject(input: AnalyzeResolvedProjectInput): Res
2390
2902
  */
2391
2903
  declare function preflightChange(input: AnalyzeChangeInput): ChangePreflightResult;
2392
2904
 
2905
+ /** Atomic preflight over one validated base/candidate facts pair (ADR 0011). */
2906
+
2393
2907
  /**
2394
2908
  * Validate that the supplied candidate is exactly the declared in-memory
2395
2909
  * overlay, then return its canonical resolved verdict. No project file is read
@@ -2400,6 +2914,89 @@ declare function preflightResolvedChange(input: PreflightResolvedChangeInput): R
2400
2914
  /** Canonical config diagnostics over repo-relative file paths. */
2401
2915
  declare function collectAnalysisConfigWarnings(input: CollectAnalysisConfigWarningsInput): ArchitectureEngineViolation[];
2402
2916
 
2917
+ /**
2918
+ * Public diagnostic code catalog (ACS02).
2919
+ *
2920
+ * Closed vocabulary of stable `ruleId` values emitted by ArkGate adapters with
2921
+ * human/agent `why` / `fix` anchors and docs fragment ids. Cataloguing only —
2922
+ * no new rule semantics, no LLM verdict, no enforcement from prose.
2923
+ *
2924
+ * **Canonical** for docs, agent projection (ACS04), and finding refs (ACS06).
2925
+ * Runtime remediation remains in `remediation.ts`; parity tests bind the two.
2926
+ *
2927
+ * Zero Node I/O. Optional CLI surface: generated `bin/lib/diagnostic-catalog.mjs`.
2928
+ *
2929
+ * @see docs/diagnostics.md
2930
+ * @see docs/plans/agent-contract-surface-4.3/README.md
2931
+ */
2932
+ /** Product-relative docs path (shipped in the npm tarball when listed in package files). */
2933
+ declare const DIAGNOSTIC_DOCS_RELATIVE_PATH: "docs/diagnostics.md";
2934
+ /** Schema id for serializing the catalog snapshot (agents / install projection). */
2935
+ declare const DIAGNOSTIC_CATALOG_SCHEMA_VERSION: "1.0";
2936
+ type DiagnosticCategory = 'layer' | 'capability' | 'publish' | 'safety' | 'arkrules' | 'arkrun' | 'arkorder' | 'preflight' | 'analysis' | 'drift' | 'snippet-policy' | 'config' | 'adapter' | 'meta';
2937
+ type DiagnosticCatalogEntry = {
2938
+ /** Stable public violation / diagnostic id. */
2939
+ ruleId: string;
2940
+ /** Short title for indexes and agent projection. */
2941
+ title: string;
2942
+ /** Why this finding exists (contract intent). */
2943
+ why: string;
2944
+ /**
2945
+ * Canonical fix guidance (agent + human). Contextual nextAction on live
2946
+ * findings may specialize this (e.g. type-only vs value layer import).
2947
+ */
2948
+ fix: string;
2949
+ /** Markdown fragment id for docs/diagnostics.md (without leading #). */
2950
+ docsAnchor: string;
2951
+ category: DiagnosticCategory;
2952
+ /**
2953
+ * When true, finding is commonly advisory / non-blocking in default profiles
2954
+ * (doctor/config warnings, type-only placement debt, empty ArkRule scope).
2955
+ * Not a severity bit for the engine — documentation only.
2956
+ */
2957
+ oftenAdvisory?: boolean;
2958
+ };
2959
+ /**
2960
+ * Closed public catalog. Order is stable (category groups, then ruleId) for
2961
+ * deterministic serialization and docs generation.
2962
+ *
2963
+ * Every production-emitted `ruleId` must appear here. Remediation switch cases
2964
+ * and adapter nextAction branches are parity-tested against this list.
2965
+ */
2966
+ declare const DIAGNOSTIC_CATALOG: readonly DiagnosticCatalogEntry[];
2967
+ /** All public ruleIds in catalog order. */
2968
+ declare const DIAGNOSTIC_RULE_IDS: readonly string[];
2969
+ declare function isKnownDiagnosticCode(ruleId: string | null | undefined): boolean;
2970
+ /**
2971
+ * True when the code is catalogued or is an ArkRule-family id handled by the
2972
+ * ARKRULE_* prefix fallback in remediation (structure sensors may add members later
2973
+ * only via catalog + ROADMAP — prefix alone is not a license for free-form ids).
2974
+ */
2975
+ declare function isCataloguedOrArkRuleFamily(ruleId: string | null | undefined): boolean;
2976
+ declare function getDiagnosticCatalogEntry(ruleId: string | null | undefined): DiagnosticCatalogEntry | undefined;
2977
+ /** Fragment for docs links, e.g. `#LAYER_IMPORT_VIOLATION`. */
2978
+ declare function diagnosticDocsFragment(ruleId: string): string;
2979
+ /**
2980
+ * Repo-relative docs path with fragment (for agents and JSON).
2981
+ * Package consumers resolve against the installed package root or GitHub tree.
2982
+ */
2983
+ declare function diagnosticDocsPath(ruleId: string): string;
2984
+ /** Catalog snapshot for JSON export / agent projection (stable field order). */
2985
+ declare function serializeDiagnosticCatalog(): {
2986
+ schemaVersion: typeof DIAGNOSTIC_CATALOG_SCHEMA_VERSION;
2987
+ docsPath: typeof DIAGNOSTIC_DOCS_RELATIVE_PATH;
2988
+ codes: readonly DiagnosticCatalogEntry[];
2989
+ };
2990
+ /**
2991
+ * Static catalog fix for a ruleId when no live violation context is available.
2992
+ * Live adapters should still use deterministicNextAction for specialized edges.
2993
+ */
2994
+ declare function catalogFixForRuleId(ruleId: string | null | undefined): string | undefined;
2995
+ /**
2996
+ * Static catalog why for a ruleId (agent “why” surface).
2997
+ */
2998
+ declare function catalogWhyForRuleId(ruleId: string | null | undefined): string | undefined;
2999
+
2403
3000
  /** Public, evidence-backed enforcement state shared by doctor adapters. */
2404
3001
  declare const ARK_ENFORCEMENT_STATE_SCHEMA_VERSION: "1.1";
2405
3002
  type EnforcementVerification = boolean | 'unverified';
@@ -2490,87 +3087,4 @@ type ArkDesignDeltaResult = {
2490
3087
  error?: string;
2491
3088
  };
2492
3089
 
2493
- /**
2494
- * Public diagnostic code catalog (ACS02).
2495
- *
2496
- * Closed vocabulary of stable `ruleId` values emitted by ArkGate adapters with
2497
- * human/agent `why` / `fix` anchors and docs fragment ids. Cataloguing only —
2498
- * no new rule semantics, no LLM verdict, no enforcement from prose.
2499
- *
2500
- * **Canonical** for docs, agent projection (ACS04), and finding refs (ACS06).
2501
- * Runtime remediation remains in `remediation.ts`; parity tests bind the two.
2502
- *
2503
- * Zero Node I/O. Optional CLI surface: generated `bin/lib/diagnostic-catalog.mjs`.
2504
- *
2505
- * @see docs/diagnostics.md
2506
- * @see docs/plans/agent-contract-surface-4.3/README.md
2507
- */
2508
- /** Product-relative docs path (shipped in the npm tarball when listed in package files). */
2509
- declare const DIAGNOSTIC_DOCS_RELATIVE_PATH: "docs/diagnostics.md";
2510
- /** Schema id for serializing the catalog snapshot (agents / install projection). */
2511
- declare const DIAGNOSTIC_CATALOG_SCHEMA_VERSION: "1.0";
2512
- type DiagnosticCategory = 'layer' | 'capability' | 'publish' | 'safety' | 'arkrules' | 'arkrun' | 'arkorder' | 'preflight' | 'analysis' | 'drift' | 'snippet-policy' | 'config' | 'adapter' | 'meta';
2513
- type DiagnosticCatalogEntry = {
2514
- /** Stable public violation / diagnostic id. */
2515
- ruleId: string;
2516
- /** Short title for indexes and agent projection. */
2517
- title: string;
2518
- /** Why this finding exists (contract intent). */
2519
- why: string;
2520
- /**
2521
- * Canonical fix guidance (agent + human). Contextual nextAction on live
2522
- * findings may specialize this (e.g. type-only vs value layer import).
2523
- */
2524
- fix: string;
2525
- /** Markdown fragment id for docs/diagnostics.md (without leading #). */
2526
- docsAnchor: string;
2527
- category: DiagnosticCategory;
2528
- /**
2529
- * When true, finding is commonly advisory / non-blocking in default profiles
2530
- * (doctor/config warnings, type-only placement debt, empty ArkRule scope).
2531
- * Not a severity bit for the engine — documentation only.
2532
- */
2533
- oftenAdvisory?: boolean;
2534
- };
2535
- /**
2536
- * Closed public catalog. Order is stable (category groups, then ruleId) for
2537
- * deterministic serialization and docs generation.
2538
- *
2539
- * Every production-emitted `ruleId` must appear here. Remediation switch cases
2540
- * and adapter nextAction branches are parity-tested against this list.
2541
- */
2542
- declare const DIAGNOSTIC_CATALOG: readonly DiagnosticCatalogEntry[];
2543
- /** All public ruleIds in catalog order. */
2544
- declare const DIAGNOSTIC_RULE_IDS: readonly string[];
2545
- declare function isKnownDiagnosticCode(ruleId: string | null | undefined): boolean;
2546
- /**
2547
- * True when the code is catalogued or is an ArkRule-family id handled by the
2548
- * ARKRULE_* prefix fallback in remediation (structure sensors may add members later
2549
- * only via catalog + ROADMAP — prefix alone is not a license for free-form ids).
2550
- */
2551
- declare function isCataloguedOrArkRuleFamily(ruleId: string | null | undefined): boolean;
2552
- declare function getDiagnosticCatalogEntry(ruleId: string | null | undefined): DiagnosticCatalogEntry | undefined;
2553
- /** Fragment for docs links, e.g. `#LAYER_IMPORT_VIOLATION`. */
2554
- declare function diagnosticDocsFragment(ruleId: string): string;
2555
- /**
2556
- * Repo-relative docs path with fragment (for agents and JSON).
2557
- * Package consumers resolve against the installed package root or GitHub tree.
2558
- */
2559
- declare function diagnosticDocsPath(ruleId: string): string;
2560
- /** Catalog snapshot for JSON export / agent projection (stable field order). */
2561
- declare function serializeDiagnosticCatalog(): {
2562
- schemaVersion: typeof DIAGNOSTIC_CATALOG_SCHEMA_VERSION;
2563
- docsPath: typeof DIAGNOSTIC_DOCS_RELATIVE_PATH;
2564
- codes: readonly DiagnosticCatalogEntry[];
2565
- };
2566
- /**
2567
- * Static catalog fix for a ruleId when no live violation context is available.
2568
- * Live adapters should still use deterministicNextAction for specialized edges.
2569
- */
2570
- declare function catalogFixForRuleId(ruleId: string | null | undefined): string | undefined;
2571
- /**
2572
- * Static catalog why for a ruleId (agent “why” surface).
2573
- */
2574
- declare function catalogWhyForRuleId(ruleId: string | null | undefined): string | undefined;
2575
-
2576
- export { type ArchitectureChangeMapFile as $, type AdapterViolationInput as A, type AdapterResult as B, type AdapterSeverity as C, type AnalysisCapabilityUse as D, type EffectiveArkRules as E, type AnalysisCompilerOptions as F, type AnalysisCompleteness as G, type AnalysisContract as H, type AnalysisEvidence as I, type AnalysisFile as J, type AnalysisFileChange as K, type AnalysisFileInput as L, type AnalysisImportEdge as M, type AnalysisIr as N, type AnalysisMode as O, type AnalysisResult as P, type AnalysisViolation as Q, type ResolvedArkRunKernelCallKind as R, type AnalyzeArchitectureConvergenceInput as S, type AnalyzeChangeInput as T, type AnalyzePolicyDeltaInput as U, type AnalyzeProjectInput as V, type AnalyzeResolvedProjectInput as W, type ArchitectureActualChange as X, type ArchitectureChangeMap as Y, type ArchitectureChangeMapContract as Z, type ArchitectureChangeMapDependency as _, type ArkRulesFile as a, type ResolvedPublishFact as a$, type ArchitectureChangeOperation as a0, type ArchitectureConvergenceClassification as a1, type ArchitectureConvergenceFinding as a2, type ArchitectureConvergenceResult as a3, type ArchitectureDependency as a4, type ArchitectureEngineEdge as a5, type ArchitectureEngineResult as a6, type ArchitectureEngineViolation as a7, type ArkDesignDeltaResult as a8, type ArkEnforcementHost as a9, type ForbiddenCapabilityUse as aA, type InvariantCoverageEvidence as aB, type MentionContext as aC, POLICY_DELTA_SCHEMA_VERSION as aD, type PolicyDelta as aE, type PolicyDeltaAcknowledgement as aF, type PolicyDeltaAnalysis as aG, type PolicyDeltaClassification as aH, type PolicyDeltaFinding as aI, type PreflightResolvedChangeInput as aJ, type PreparedChangeFile as aK, RESOLVED_CANDIDATE_FACTS_SCHEMA as aL, RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION as aM, type ResolvedAmbientFact as aN, type ResolvedAnalysisFile as aO, type ResolvedAnalysisIr as aP, type ResolvedAnalysisResult as aQ, type ResolvedCandidateFacts as aR, type ResolvedCandidateFactsInput as aS, type ResolvedCapability as aT, type ResolvedCapabilityFact as aU, type ResolvedChangePreflightResult as aV, type ResolvedDependencyKind as aW, type ResolvedDependencyState as aX, type ResolvedFactsCompleteness as aY, type ResolvedFileFact as aZ, type ResolvedIntentReferenceFact as a_, type ArkEnforcementState as aa, type ArkRuleSensorViolation as ab, type ChangePreflightResult as ac, type ClassShapeFact as ad, type CollectAnalysisConfigWarningsInput as ae, type CoverageEvidence as af, type CoverageFiles as ag, type CoverageInvariant as ah, DIAGNOSTIC_CATALOG as ai, DIAGNOSTIC_CATALOG_SCHEMA_VERSION as aj, DIAGNOSTIC_DOCS_RELATIVE_PATH as ak, DIAGNOSTIC_RULE_IDS as al, type DeclarationShape as am, type DesignDeltaChange as an, type DesignDeltaEnforcementScope as ao, type DesignDeltaIdentity as ap, type DesignSmellEvidence as aq, type DesignSmellFinding as ar, type DesignSmellId as as, type DiagnosticCatalogEntry as at, type DiagnosticCategory as au, type EnforcementBoundaryState as av, type EnforcementEvidence as aw, type EnforcementEvidenceField as ax, type EnforcementVerification as ay, type EvaluateArchitectureGraphInput as az, type ResolvedArkRunDeclarationFact as b, type ResolvedSafetyFact as b0, type ResolvedSafetyKind as b1, type ResolvedSafetyReport as b2, type SemanticDependency as b3, type SemanticDependencyKind as b4, analyzeArchitectureConvergence as b5, analyzeChange as b6, analyzePolicyDelta as b7, analyzeProject as b8, analyzeResolvedProject as b9, explainViolation as bA, extractClassShapesFromSource as bB, extractSemanticDependencies as bC, getDiagnosticCatalogEntry as bD, isCataloguedOrArkRuleFamily as bE, isKnownDiagnosticCode as bF, loadContract as bG, loadResolvedCandidateFacts as bH, policyDeltaAcknowledgementMatches as bI, preflightChange as bJ, preflightResolvedChange as bK, resolvedFactsEvidenceRequirementsHash as bL, serializeDiagnosticCatalog as bM, stableSerialize as bN, toAdapterDiagnostic as bO, version as bP, buildArkRuleFileHints as ba, canPromoteInvariant as bb, catalogFixForRuleId as bc, catalogWhyForRuleId as bd, classifyArkPolicyDelta as be, classifyCoverage as bf, collectAnalysisConfigWarnings as bg, collectEmptyAppliesToFindings as bh, collectForbiddenCapabilityUses as bi, countsAsCoverage as bj, createAICodeGate as bk, createAdapterResult as bl, createArchitectureProfile as bm, createArchitectureProfileFromArkConfig as bn, createElevenLayerArkConfig as bo, createResolvedCandidateFacts as bp, deriveArkRuleFileHints as bq, describeCoverage as br, detectArchitectureCycles as bs, deterministicHash as bt, diagnosticDocsFragment as bu, diagnosticDocsPath as bv, elevenLayerProfile as bw, evaluateArchitectureGraph as bx, evaluateArkRuleSensors as by, evaluateInvariantCoverage as bz, type ResolvedArkRunKernelCallFact as c, type ResolvedArkRunManagedNewFact as d, type ResolvedDependencyFact as e, type ResolvedArkRunCompositionRootHitFact as f, type ResolvedFactsReason as g, type ResolvedArkOrderPlaneCallFact as h, type ResolvedArkOrderGenericUpdateFact as i, type ResolvedArkOrderRootHitFact as j, type ResolvedArkOrderXiFieldWriteFact as k, type ResolvedArkOrderIngestWriteFact as l, ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH as m, type AICodeGate as n, type AICodeGateContext as o, type AICodeGateOptions as p, type AICodeGateResult as q, type AICodeGateViolation as r, type AIGateExtension as s, ANALYSIS_IR_SCHEMA_VERSION as t, ARK_ANALYSIS_RESULT_SCHEMA as u, ARK_ANALYSIS_RESULT_SCHEMA_VERSION as v, ARK_DESIGN_DELTA_SCHEMA_VERSION as w, ARK_ENFORCEMENT_STATE_SCHEMA_VERSION as x, type AdapterCompletenessReason as y, type AdapterDiagnostic as z };
3090
+ 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_DESIGN_DELTA_SCHEMA_VERSION, ARK_ENFORCEMENT_STATE_SCHEMA_VERSION, type Adapter, type AdapterCompletenessReason, type AdapterDiagnostic, type AdapterGovernanceIssue, type AdapterGovernanceResult, 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, ArchitectureProfile, ArkCheckConfig, type ArkDesignDeltaResult, type ArkEnforcementHost, type ArkEnforcementState, ArkKernel, ArkKernelConfig, ArkKernelConfigError, ArkManifest, type ArkTestHarness, type ArkTestSnapshot, AuditQuery, AuditRecord, AuditStore, AuditTrail, type BuildPublishPolicyContextOptions, type ChangePreflightResult, type CollectAnalysisConfigWarningsInput, type ContractCheckResult, type CreateAdapterOptions, CreateArchitectureProfileFromArkConfigOptions, CreateArchitectureProfileOptions, CreateArkKernelFromConfigOptions, CreateArkKernelOptions, type CreateArkManifestOptions, CreateAuditTrailOptions, CreateElevenLayerArkConfigOptions, CreateObservabilityReporterOptions, CreateProjectionRegistryOptions, CreateWorkflowEngineOptions, DEFAULT_MAX_HISTORY_SIZE, DIAGNOSTIC_CATALOG, DIAGNOSTIC_CATALOG_SCHEMA_VERSION, DIAGNOSTIC_DOCS_RELATIVE_PATH, DIAGNOSTIC_RULE_IDS, DefineIntentOptions, type DefinePolicyOptions, type DefinePortOptions, DependencyGraph, DependencyInformationPackage, type DesignDeltaChange, type DesignDeltaEnforcementScope, type DesignDeltaIdentity, type DesignSmellEvidence, type DesignSmellFinding, type DesignSmellId, type DiagnosticCatalogEntry, type DiagnosticCategory, DomainEvent, type EnforcementBoundaryState, type EnforcementEvidence, type EnforcementEvidenceField, type EnforcementVerification, type EvaluateArchitectureGraphInput, EventBufferRecord, EventBufferStatus, EventBufferStore, EventBus, EventBusOptions, EventContract, EventContractRegistry, EventContractRegistryImpl, EventContractValidationResult, EventContractViolationError, type ForbiddenCapabilityUse, GraphEdge, type GraphPolicyContext, InMemoryAuditStore, InMemoryEventBuffer, type InMemoryEventBufferOptions, InMemoryOutboxStore, InMemoryReadModelStore, InMemoryWorkflowStore, type InformationPackageCompare, type InformationPackageDiff, IntentCreator, IntentCreator as IntentDefinition, IntentName, type IntentNameValidation, IntentRegistry, IntentRelationship, InvalidIntentNameError, type LayerFlowRule, LayerPolicyContextError, type LayerPolicyOptions, MANIFEST_SCHEMA_VERSION, MetadataRegistry, ObservabilityDriftReport, ObservabilityReporter, ObservedLayerFlowViolationError, OutboxRecord, OutboxStatus, POLICY_DELTA_SCHEMA_VERSION, Policy, type PolicyDelta, type PolicyDeltaAcknowledgement, type PolicyDeltaAnalysis, type PolicyDeltaClassification, type PolicyDeltaFinding, PolicyEnforcementMode, PolicyEngine, PolicySeverity, PolicyViolation, PolicyViolationError, type Port, type PreflightResolvedChangeInput, type PreparedChangeFile, ProjectionRegistry, type PublishPolicyContext, RESOLVED_CANDIDATE_FACTS_SCHEMA, RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION, ReadModelStore, type ResolvedAmbientFact, type ResolvedAnalysisFile, type ResolvedAnalysisIr, type ResolvedAnalysisResult, type ResolvedArkRunCompositionRootHitFact, type ResolvedArkRunDeclarationFact, type ResolvedArkRunKernelCallFact, type ResolvedArkRunKernelCallKind, type ResolvedArkRunManagedNewFact, 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, SagaDefinition, SagaInstance, type SemanticDependency, type SemanticDependencyKind, SourceMetadataOverrideError, type SyncRegistryOptions, TraceRecord, TraceRecordType, UnknownEventSourceError, UnregisteredIntentError, WorkflowEngine, WorkflowSnapshot, WorkflowStore, analyzeArchitectureConvergence, analyzeChange, analyzePolicyDelta, analyzeProject, analyzeResolvedProject, architecturalPolicies, buildPublishPolicyContext, catalogFixForRuleId, catalogWhyForRuleId, checkAdapterGovernance, checkContract, classifyArkPolicyDelta, collectAnalysisConfigWarnings, collectForbiddenCapabilityUses, compareInformationPackages, createAICodeGate, createAdapter, createAdapterResult, createArchitectureProfile, createArchitectureProfileFromArkConfig, createArkKernel, createArkKernelFromConfig, createArkManifest, createArkTestHarness, createAuditTrail, createDependencyGraph, createElevenLayerArkConfig, createEventBus, createEventContractRegistry, createIntentRegistry, createLenientArkKernel, createLenientArkKernelFromConfig, createMetadataRegistry, createObservabilityReporter, createProjectionRegistry, createResolvedCandidateFacts, createSaga, createStrictArkKernel, createStrictArkKernelFromConfig, createWorkflowEngine, defaultIntentRegistry, defineArchitectureProfilePolicy, defineIntent, defineLayerPolicy, definePolicy, definePort, definePublishPolicy, detectArchitectureCycles, deterministicHash, diagnosticDocsFragment, diagnosticDocsPath, elevenLayerProfile, evaluateArchitectureGraph, explainViolation, extractSemanticDependencies, getDiagnosticCatalogEntry, isCataloguedOrArkRuleFamily, isKnownDiagnosticCode, isLayerPolicy, loadContract, loadResolvedCandidateFacts, policyDeltaAcknowledgementMatches, preflightChange, preflightResolvedChange, replayInformationPackages, resolvedFactsEvidenceRequirementsHash, serializeDiagnosticCatalog, shadowInformationPackage, stableSerialize, syncRegistryToGraph, toAdapterDiagnostic, validateIntentName, version };