arkgate 4.8.23 → 4.8.25

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 (201) hide show
  1. package/CHANGELOG.md +153 -0
  2. package/README.md +7 -5
  3. package/bin/ark-check-runtime.mjs +41 -91
  4. package/bin/ark-dashboard.mjs +56 -53
  5. package/bin/ark-layer-match.mjs +707 -121
  6. package/bin/ark-mcp-runtime.mjs +448 -169
  7. package/bin/ark-mcp.mjs +68 -4
  8. package/bin/ark-shared.mjs +42 -22
  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/adoption-stance.mjs +2 -2
  13. package/bin/lib/adr-path.mjs +3 -3
  14. package/bin/lib/agent-gates.mjs +0 -61
  15. package/bin/lib/agent-homes.mjs +12 -21
  16. package/bin/lib/agent-projection-command.mjs +9 -5
  17. package/bin/lib/ambient-state.mjs +9 -30
  18. package/bin/lib/analysis-engine.mjs +15 -11
  19. package/bin/lib/architecture-scan.mjs +61 -15
  20. package/bin/lib/ark-order-doctor.mjs +4 -29
  21. package/bin/lib/ark-order-facts.mjs +319 -17
  22. package/bin/lib/ark-order-sensors.mjs +28 -101
  23. package/bin/lib/ark-order-types.mjs +3 -2
  24. package/bin/lib/ark-run-doctor.mjs +17 -28
  25. package/bin/lib/ark-run-facts.mjs +461 -48
  26. package/bin/lib/ark-run-sensors.mjs +6 -4
  27. package/bin/lib/arkgate-pins.mjs +91 -0
  28. package/bin/lib/arkrule-file-hints.mjs +2 -47
  29. package/bin/lib/arkrules-contract.mjs +124 -133
  30. package/bin/lib/arkrules-sensors.mjs +55 -252
  31. package/bin/lib/check-args.mjs +85 -1
  32. package/bin/lib/ci-and-commands.mjs +24 -78
  33. package/bin/lib/ci-merge-boundary.mjs +1 -1
  34. package/bin/lib/class-source-scan.mjs +479 -0
  35. package/bin/lib/clone-detection.mjs +474 -0
  36. package/bin/lib/codex-home.mjs +5 -3
  37. package/bin/lib/config-contract-slices.mjs +739 -0
  38. package/bin/lib/config-contract.mjs +42 -607
  39. package/bin/lib/config-extras.mjs +16 -22
  40. package/bin/lib/config-warnings.mjs +32 -0
  41. package/bin/lib/contract-smells.mjs +33 -15
  42. package/bin/lib/core-ratchet.mjs +0 -2
  43. package/bin/lib/dashboard-cli.mjs +62 -0
  44. package/bin/lib/deep-module-coach.mjs +2 -4
  45. package/bin/lib/deploy-path.mjs +13 -38
  46. package/bin/lib/design-delta.mjs +1 -1
  47. package/bin/lib/design-smells.mjs +2 -2
  48. package/bin/lib/diagnostic-catalog.mjs +23 -9
  49. package/bin/lib/doctor-advisories.mjs +78 -8
  50. package/bin/lib/doctor-green-cite.mjs +1 -1
  51. package/bin/lib/doctor-human.mjs +1 -1
  52. package/bin/lib/doctor-next-actions.mjs +19 -4
  53. package/bin/lib/doctor-plan.mjs +9 -13
  54. package/bin/lib/duplication-io.mjs +572 -0
  55. package/bin/lib/effective-contract-load.mjs +282 -83
  56. package/bin/lib/enforcement-profiles.mjs +40 -4
  57. package/bin/lib/entry-points-io.mjs +424 -0
  58. package/bin/lib/extra-merge-teeth.mjs +36 -0
  59. package/bin/lib/field-install.mjs +38 -14
  60. package/bin/lib/first-run-help.mjs +10 -5
  61. package/bin/lib/flat-parent-importers.mjs +139 -0
  62. package/bin/lib/flat-parent-pilot.mjs +40 -100
  63. package/bin/lib/gate-files.mjs +58 -90
  64. package/bin/lib/git-change-scope.mjs +109 -0
  65. package/bin/lib/github-enforcement.mjs +166 -29
  66. package/bin/lib/golden-pattern.mjs +1 -1
  67. package/bin/lib/hook-templates.mjs +17 -15
  68. package/bin/lib/host-support-matrix.mjs +3 -1
  69. package/bin/lib/html-report-advisories.mjs +4 -0
  70. package/bin/lib/html-report-depth.mjs +2 -2
  71. package/bin/lib/html-report.mjs +2 -2
  72. package/bin/lib/import-graph-projection.mjs +112 -0
  73. package/bin/lib/import-resolve.mjs +13 -1
  74. package/bin/lib/improvement-compass-doctor.mjs +1 -24
  75. package/bin/lib/install-migrate.mjs +50 -73
  76. package/bin/lib/invariant-coverage-io.mjs +4 -3
  77. package/bin/lib/invariant-coverage.mjs +85 -11
  78. package/bin/lib/invariant-probe-cli.mjs +347 -0
  79. package/bin/lib/invariant-probe-io.mjs +165 -0
  80. package/bin/lib/invariant-probe-runner.mjs +268 -0
  81. package/bin/lib/invariant-probe-sites.mjs +174 -0
  82. package/bin/lib/invariant-probe-workspace.mjs +183 -0
  83. package/bin/lib/invariant-probe.mjs +461 -0
  84. package/bin/lib/invariant-tests-path.mjs +16 -22
  85. package/bin/lib/literal-path-drift.mjs +4 -2
  86. package/bin/lib/managed-upgrade.mjs +2 -8
  87. package/bin/lib/mcp-adoption.mjs +13 -6
  88. package/bin/lib/mcp-hook-payload.mjs +403 -63
  89. package/bin/lib/orphan-modules-io.mjs +458 -0
  90. package/bin/lib/orphan-modules.mjs +251 -0
  91. package/bin/lib/outside-importers.mjs +197 -0
  92. package/bin/lib/package-manager.mjs +60 -2
  93. package/bin/lib/parse-health.mjs +1 -1
  94. package/bin/lib/passthrough-commands.mjs +83 -0
  95. package/bin/lib/persistence-write-hint.mjs +106 -0
  96. package/bin/lib/pin-dependent-gates.mjs +117 -0
  97. package/bin/lib/policy-delta-io.mjs +219 -14
  98. package/bin/lib/post-green-path.mjs +1 -1
  99. package/bin/lib/prepare-change.mjs +115 -7
  100. package/bin/lib/prepare-write.mjs +2 -2
  101. package/bin/lib/presets.mjs +59 -73
  102. package/bin/lib/product-copy.mjs +1 -6
  103. package/bin/lib/project-root.mjs +31 -62
  104. package/bin/lib/remediation.mjs +23 -4
  105. package/bin/lib/resolved-candidate-facts.mjs +405 -117
  106. package/bin/lib/rules-inventory.mjs +22 -3
  107. package/bin/lib/rules-under-contract.mjs +247 -9
  108. package/bin/lib/scan-files.mjs +36 -4
  109. package/bin/lib/schema-validation.mjs +130 -0
  110. package/bin/lib/sensor-promote-cli.mjs +2 -11
  111. package/bin/lib/sensor-promote-io.mjs +33 -22
  112. package/bin/lib/sensor-promotion.mjs +1 -1
  113. package/bin/lib/skill-catalog-apply.mjs +1 -1
  114. package/bin/lib/skill-install.mjs +42 -38
  115. package/bin/lib/snippet-analysis.mjs +140 -6
  116. package/bin/lib/source-policy.mjs +34 -0
  117. package/bin/lib/start-install-recovery.mjs +72 -2
  118. package/bin/lib/start-preview.mjs +31 -1
  119. package/bin/lib/states-transitions-presence.mjs +3 -3
  120. package/bin/lib/status-command.mjs +35 -22
  121. package/bin/lib/status-manifest.mjs +50 -30
  122. package/bin/lib/status-transition-catalog.mjs +0 -6
  123. package/bin/lib/suggestions.mjs +3 -3
  124. package/bin/lib/team-parliament-io.mjs +76 -88
  125. package/bin/lib/team-parliament.mjs +21 -10
  126. package/bin/lib/upgrade-behavior-changes.mjs +2 -2
  127. package/bin/lib/upgrade-command.mjs +2 -24
  128. package/bin/lib/upgrade-outcome.mjs +1 -1
  129. package/bin/lib/upstream-report.mjs +21 -10
  130. package/bin/lib/violations.mjs +10 -9
  131. package/bin/lib/weakest-link.mjs +13 -0
  132. package/bin/lib/write-path-capabilities.mjs +6 -4
  133. package/dist/chunk-A5EIY3HI.cjs +5 -0
  134. package/dist/chunk-AHACEKSV.js +16 -0
  135. package/dist/chunk-SVSQVGFJ.js +5 -0
  136. package/dist/chunk-UN5EH4QV.cjs +16 -0
  137. package/dist/{configTypes-Bbf_MFGe.d.ts → configTypes-GPvvdleM.d.cts} +30 -4
  138. package/dist/configTypes-GPvvdleM.d.ts +257 -0
  139. package/dist/eslint/index.cjs +18 -5
  140. package/dist/eslint/index.d.cts +368 -0
  141. package/dist/eslint/index.d.ts +139 -156
  142. package/dist/eslint/index.js +11 -5
  143. package/dist/index.cjs +36 -35
  144. package/dist/index.d.cts +5547 -0
  145. package/dist/index.d.ts +3283 -198
  146. package/dist/index.js +36 -35
  147. package/dist/inspectorListen-6DQVJ4DC.js +1 -0
  148. package/dist/inspectorListen-KGMIQ2TF.cjs +1 -0
  149. package/dist/nestjs/index.cjs +1 -18
  150. package/dist/nestjs/index.d.cts +22 -0
  151. package/dist/nestjs/index.d.ts +1 -3
  152. package/dist/nestjs/index.js +1 -18
  153. package/dist/order/index.cjs +1 -1
  154. package/dist/order/index.d.cts +155 -0
  155. package/dist/order/index.d.ts +15 -3
  156. package/dist/order/index.js +1 -1
  157. package/dist/runtime/index.cjs +13 -30
  158. package/dist/{diagnosticCatalog-35mrwAHe.d.ts → runtime/index.d.cts} +828 -276
  159. package/dist/runtime/index.d.ts +2741 -133
  160. package/dist/runtime/index.js +13 -30
  161. package/dist/{types-Bdj32QwA.d.ts → types-CnauMQQL.d.cts} +607 -163
  162. package/dist/types-CnauMQQL.d.ts +1800 -0
  163. package/docs/README.md +3 -1
  164. package/docs/agent-guide.md +217 -16
  165. package/docs/ai-gates.md +174 -26
  166. package/docs/arkorder.md +32 -15
  167. package/docs/brownfield-adoption.md +5 -1
  168. package/docs/configuration.md +230 -31
  169. package/docs/develop.md +2 -1
  170. package/docs/diagnostics.md +212 -19
  171. package/docs/package-surface.md +35 -9
  172. package/docs/product-voice.md +7 -1
  173. package/package.json +69 -19
  174. package/schemas/ark.analysis-result.schema.json +15 -0
  175. package/schemas/ark.config.schema.json +77 -12
  176. package/schemas/ark.invariant-probe.schema.json +368 -0
  177. package/schemas/ark.resolved-candidate-facts.schema.json +1 -1
  178. package/schemas/ark.status-manifest.schema.json +22 -0
  179. package/server.json +3 -9
  180. package/templates/agent-skills/README.md +1 -1
  181. package/templates/agent-skills/ark-adopt/SKILL.md +5 -1
  182. package/templates/agent-skills/ark-contract/SKILL.md +17 -0
  183. package/templates/agent-skills/ark-coverage/SKILL.md +2 -0
  184. package/templates/agent-skills/ark-explore/SKILL.md +7 -0
  185. package/templates/agent-skills/ark-fix/SKILL.md +20 -0
  186. package/templates/agent-skills/ark-order/SKILL.md +4 -2
  187. package/templates/agent-skills/ark-place/SKILL.md +8 -0
  188. package/templates/agent-skills/ark-runtime/SKILL.md +6 -1
  189. package/templates/arkrules/PersistenceAdapters.json +1 -1
  190. package/templates/arkrules/PresentationAdapters.json +1 -1
  191. package/templates/skills/ark-adopt.md +5 -1
  192. package/templates/skills/ark-contract.md +17 -0
  193. package/templates/skills/ark-coverage.md +2 -0
  194. package/templates/skills/ark-explore.md +7 -0
  195. package/templates/skills/ark-fix.md +20 -0
  196. package/templates/skills/ark-order.md +4 -2
  197. package/templates/skills/ark-place.md +8 -0
  198. package/templates/skills/ark-runtime.md +6 -1
  199. package/bin/lib/ark-order-error.mjs +0 -18
  200. package/bin/lib/ark-order-invariants.mjs +0 -346
  201. package/dist/types-Ik_OakcI.d.ts +0 -183
@@ -1,128 +1,366 @@
1
- import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-Ik_OakcI.js';
2
-
1
+ type MaybePromise<T> = T | Promise<T>;
2
+ type AuditRecordType = 'event.published' | 'event.rawPublish' | 'event.handoffFailed' | 'event.intercepted' | 'interceptor.error' | 'policy.softViolation' | 'policy.hardViolation' | 'layer.observedViolation' | 'layer.observedFlowUnresolvable' | 'handler.error' | 'hook.error' | 'workflow.started' | 'workflow.step.completed' | 'workflow.step.failed' | 'workflow.compensation.completed' | 'workflow.completed' | 'workflow.failed' | 'projection.applied' | 'metadata.changed';
3
+ interface AuditRecord {
4
+ id: string;
5
+ type: AuditRecordType;
6
+ timestamp: string;
7
+ source?: string;
8
+ actor?: string;
9
+ intent?: string;
10
+ correlationId?: string;
11
+ causationId?: string;
12
+ subject?: string;
13
+ details?: unknown;
14
+ }
15
+ interface AuditRecordInput {
16
+ type: AuditRecordType;
17
+ timestamp?: string;
18
+ source?: string;
19
+ actor?: string;
20
+ intent?: string;
21
+ correlationId?: string;
22
+ causationId?: string;
23
+ subject?: string;
24
+ details?: unknown;
25
+ }
26
+ interface AuditQuery {
27
+ type?: AuditRecordType;
28
+ intent?: string;
29
+ correlationId?: string;
30
+ subject?: string;
31
+ since?: string;
32
+ until?: string;
33
+ limit?: number;
34
+ }
3
35
  /**
4
- * PolicyEngine
36
+ * Pluggable persistence for audit records.
5
37
  *
6
- * Evaluates collections of policies against a context.
7
- * Supports hard and soft policies.
8
- * - Hard policies: violations cause enforcement to throw.
9
- * - Soft policies: violations are reported as warnings but do not throw.
38
+ * **Durability stance (R9):** Default is `InMemoryAuditStore` — reference only, not
39
+ * production durability (lost on restart). Implement this interface for durable audit.
40
+ * See `docs/production-hardening.md`.
10
41
  */
11
-
12
- interface PolicyEvaluationResult {
13
- passed: boolean;
14
- violations: PolicyViolation[];
15
- hardViolations: PolicyViolation[];
16
- softViolations: PolicyViolation[];
42
+ interface AuditStore {
43
+ append(record: AuditRecord): MaybePromise<void>;
44
+ query(query?: AuditQuery): MaybePromise<AuditRecord[]>;
45
+ clear(): MaybePromise<void>;
17
46
  }
18
47
  /**
19
- * The PolicyEngine is responsible for registering policies and evaluating
20
- * them against a given context.
48
+ * High-level audit API used by the event bus / kernel.
49
+ * Durability is that of the injected `AuditStore` (default in-memory).
21
50
  */
22
- declare class PolicyEngine<Context = unknown> {
23
- private readonly policies;
24
- constructor(initialPolicies?: Policy<Context>[]);
51
+ interface AuditTrail {
52
+ record(input: AuditRecordInput): Promise<AuditRecord>;
53
+ query(query?: AuditQuery): Promise<AuditRecord[]>;
54
+ clear(): Promise<void>;
55
+ }
56
+ interface CreateAuditTrailOptions {
57
+ /** Durable store when provided; otherwise `InMemoryAuditStore` (not production durability). */
58
+ store?: AuditStore;
59
+ maxRecords?: number;
60
+ }
61
+
62
+ /**
63
+ * Type vocabulary for the ark.config.json contract (U02 pilot 1).
64
+ *
65
+ * Pure declarations only — no runtime values. The loader/validator logic and the
66
+ * published JSON Schema live in ./configContract.ts. Extra defaulting lives in
67
+ * ./configExtras.ts (generated sibling `config-extras.mjs`). Type-only imports
68
+ * from this file are erased on transpile.
69
+ */
70
+ type ArkConfigSchemaVersion = '1.0' | '1.1' | '1.2' | '1.3';
71
+ type ArkConfigCyclePolicy = 'strict' | 'soft' | 'framework-soft' | 'off';
72
+ type ArkConfigLayerCapabilities = {
73
+ deny?: string[];
74
+ };
75
+ /** Who this folder is for. Metadata — not import-rule teeth. Absence is silent. */
76
+ type ArkConfigLayerTrustBoundary = 'public' | 'auth' | 'admin' | 'internal';
77
+ type ArkConfigLayer = {
78
+ name: string;
79
+ patterns: string[];
80
+ exclude?: string[];
81
+ intentPrefixes?: string[];
25
82
  /**
26
- * Adds a policy to the engine.
83
+ * App-context caption for this layer.
84
+ * Metadata — excluded from policy hash. Absence is silent.
27
85
  */
28
- add(policy: Policy<Context>): void;
86
+ description?: string;
29
87
  /**
30
- * Returns all registered policies.
88
+ * Who this folder is for: public | auth | admin | internal.
89
+ * Metadata — excluded from policy hash. Absence is silent. Not host/CI TLS.
31
90
  */
32
- getPolicies(): Policy<Context>[];
91
+ trustBoundary?: ArkConfigLayerTrustBoundary;
33
92
  /**
34
- * Evaluates all policies against the provided context.
93
+ * Who owns this house: GitHub handles or emails (same identity as stewards).
94
+ * Metadata — excluded from policy hash. Absence is silent unless
95
+ * `requireLayerOwners` is true. Not import-rule teeth.
35
96
  */
36
- evaluate(context: Context): PolicyEvaluationResult;
97
+ owners?: string[];
98
+ forbiddenGlobals?: string[];
99
+ /** ADR 0009 D2 — opt-in effect-capability walls; absence changes no verdict. */
100
+ capabilities?: ArkConfigLayerCapabilities;
101
+ /** Dual-depth sugar: `pure: true` denies all seven capabilities. */
102
+ pure?: boolean;
103
+ mayImportInfrastructure?: boolean;
104
+ optional?: boolean;
37
105
  /**
38
- * Enforces all policies.
39
- *
40
- * - Soft violations are collected and can be observed (returned or logged).
41
- * - Hard violations cause an error to be thrown (by default).
42
- *
43
- * @returns Evaluation result (including any soft violations)
44
- * @throws Error if any hard policy is violated
106
+ * Future house: empty globs are expected. `--strict-config` must not fail.
107
+ * Typo warning (`CONFIG_LAYER_PATTERN_NO_MATCHES`) is skipped.
45
108
  */
46
- enforce(context: Context): PolicyEvaluationResult;
109
+ reserved?: boolean;
110
+ /** Alias of reserved — empty pattern matches are allowed. */
111
+ allowEmpty?: boolean;
112
+ };
113
+ /** How a starred `sliceFolders` prefix is named. Absent equals `path`. */
114
+ type ArkConfigSliceIdentity = 'path' | 'stars';
115
+ type ArkConfigRule = {
116
+ from: string;
117
+ to: string;
118
+ allowed: boolean;
119
+ message?: string;
120
+ peerIsolation?: boolean;
121
+ sliceFolders?: string[];
47
122
  /**
48
- * Clears all registered policies.
123
+ * How a starred `sliceFolders` prefix is named.
124
+ * Absent and `path` keep today's ids. `stars` is the last literal plus every
125
+ * star binding (a star before the last literal is kept too).
49
126
  */
50
- clear(): void;
51
- }
52
-
53
- /**
54
- * IntentRegistry
55
- *
56
- * Central registry for semantic intents.
57
- * Supports registration, duplicate prevention, and declared dependency relationships.
58
- *
59
- * This is a core building block for governance, dependency graphs, and policy enforcement.
60
- */
61
-
62
- /**
63
- * Options for declaring relationships when defining an intent.
64
- */
65
- interface DefineIntentOptions {
66
- /** Other intents this one depends on (semantic names) */
67
- dependsOn?: IntentName[];
68
- /** Intents that this one produces / triggers */
69
- produces?: IntentName[];
70
- }
71
- /**
72
- * IntentRegistry manages all registered intents and their declared relationships.
73
- */
74
- declare class IntentRegistry {
75
- private readonly intents;
76
- private readonly dependencies;
77
- private readonly productions;
127
+ sliceIdentity?: ArkConfigSliceIdentity;
128
+ /** Roots the repo declares shared on purpose — evidence, not unclassifiable. */
129
+ sharedRoots?: string[];
130
+ /** Directed slice→slice edges the repo declares on purpose. */
131
+ allowedCrossSlice?: ArkConfigCrossSliceEdge[];
78
132
  /**
79
- * Define/register a new intent.
80
- *
81
- * @param name - Semantic intent name following the convention (Domain.*, Application.*, etc.)
82
- * @param options - Optional relationship declarations
83
- * @throws Error if an intent with the same name is already registered
133
+ * `"deny"` blocks a shared root from importing a slice.
134
+ * `"deny-cross-parent"` leaves that hop allowed and asks the whole-graph
135
+ * check to report a slice that reaches another universe through shared.
136
+ * The object form carries `stopAt`: composition roots the walk never
137
+ * passes through.
84
138
  */
85
- define<N extends IntentName, P = unknown>(name: N, options?: DefineIntentOptions): IntentCreator<N, P>;
139
+ sharedImportsSlice?: ArkConfigSharedImportsSlice;
86
140
  /**
87
- * Declare that one intent depends on / relates to another.
88
- * This information is used by the DependencyGraph (future iterations) and for policy checks.
89
- *
90
- * @param from - The source intent (e.g. an Application operation)
91
- * @param to - The target intent it depends on (e.g. a Domain event or concept)
141
+ * Optional inner wall. Absent keeps today's universe-wall output.
142
+ * `siblings` defaults to deny. An object keeps that default and lists enforced subtrees.
143
+ * `parentMayImportChild` defaults to false.
92
144
  */
93
- declareDependency(from: string, to: string): void;
145
+ childSlices?: ArkConfigChildSlices;
146
+ };
147
+ type ArkConfigSharedImportsSlice = 'deny' | 'deny-cross-parent' | {
148
+ mode: 'deny-cross-parent';
149
+ stopAt: string[];
150
+ };
151
+ type ArkConfigChildSlices = {
152
+ sliceFolders: string[];
153
+ sliceIdentity?: ArkConfigSliceIdentity;
154
+ commonFolders?: string[];
94
155
  /**
95
- * Declare that one intent produces / emits another (e.g. use case → domain event).
156
+ * `ratchet` on the object form: absent turns the anti-growth ratchet on only
157
+ * when the baseline already records an advisory crossing of this rule;
158
+ * `true` always; `false` measures only.
96
159
  */
97
- declareProduction(from: string, to: string): void;
160
+ siblings?: 'deny' | 'advisory' | {
161
+ default: 'deny' | 'advisory';
162
+ enforce?: string[];
163
+ ratchet?: boolean;
164
+ };
165
+ parentMayImportChild?: boolean;
166
+ /** Text for inner-wall findings (sibling, common → child). Absent: ArkGate default, never the rule message. */
167
+ message?: string;
98
168
  /**
99
- * Retrieve a previously defined intent creator by name.
169
+ * Directed child-slice allowances. `*` is one whole path segment.
170
+ * Clears a sibling crossing only. The universe `allowedCrossSlice` does not read this list.
100
171
  */
101
- get<N extends IntentName = IntentName, P = unknown>(name: string): IntentCreator<N, P> | undefined;
172
+ allowedCrossSlice?: ArkConfigCrossSliceEdge[];
102
173
  /**
103
- * List all registered intent creators.
174
+ * Files outside the slice trees, borrowed onto a child id until they move.
175
+ * `to` is the universe id plus one child segment.
104
176
  */
105
- list(): IntentCreator<IntentName, unknown>[];
177
+ sliceAliases?: ArkConfigSliceAlias[];
106
178
  /**
107
- * Get all declared dependencies for a given intent.
179
+ * Filename at each child slice root. `<Layer>` is the only token.
180
+ * Example: `arkrules.<Layer>.json`.
108
181
  */
109
- getDependencies(intentName: string): string[];
182
+ arkRulesFile?: string;
183
+ };
184
+ type ArkConfigSliceAlias = {
185
+ from: string;
186
+ to: string;
187
+ /** True: the path stays. It is not an owed move and does not clear other honesty debt. */
188
+ pinned?: boolean;
189
+ /** Doctor label, such as `framework-route`. A label alone does not pin. */
190
+ reason?: string;
191
+ };
192
+ type ArkConfigCrossSliceEdge = {
193
+ from: string;
194
+ to: string;
195
+ };
196
+ type ArkConfigSafety = {
197
+ maxTsSuppressions?: number;
198
+ maxAnyCasts?: number;
199
+ allowInMemory?: boolean;
200
+ allowDisabledPeerIsolation?: boolean;
201
+ };
202
+ /**
203
+ * Optional invariant-coverage scan controls. Absence keeps the built-in
204
+ * defaults (test-name heuristic, 400-file budget) and changes no verdict.
205
+ */
206
+ type ArkConfigCoverage = {
207
+ /** Globs that decide which files count as tests (replaces the name heuristic). */
208
+ testGlobs?: string[];
209
+ /** Max files loaded as coverage evidence before the budget is exhausted. */
210
+ maxFiles?: number;
110
211
  /**
111
- * Get all intents produced / emitted by a given intent.
212
+ * Path prefixes where this project declares its test runner actually executes
213
+ * tests. ArkGate never runs anything: this is a second declaration to compare
214
+ * the coverage scan against, so a covering test found outside them is reported
215
+ * (INVARIANT_COVERAGE_OUTSIDE_ROOTS) instead of silently certifying the
216
+ * invariant. Absence is silent unless any catalogued invariant is enforced —
217
+ * then missing roots fail closed (INVARIANT_COVERAGE_ROOTS_MISSING).
112
218
  */
113
- getProductions(intentName: string): string[];
219
+ coverageRoots?: string[];
220
+ };
221
+ /**
222
+ * ADR 0012 — optional map of layer name → project-relative ArkRules file path.
223
+ * Absence changes no inter-layer verdict.
224
+ */
225
+ /** One path, or several paths merged into that layer's catalog. */
226
+ type ArkConfigArkRulesRef = string | string[];
227
+ type ArkConfigArkRulesRefs = Record<string, ArkConfigArkRulesRef>;
228
+ /** ADR 0020 — advisory never adds merge teeth; enforced is the extra's merge plane. */
229
+ type ArkConfigArkRunMode = 'advisory' | 'enforced';
230
+ /**
231
+ * ADR 0020 — optional inline ArkRun extra (schema 1.2+). Absence is silent.
232
+ * Present objects are fully defaulted by the loader.
233
+ */
234
+ type ArkConfigArkRun = {
235
+ mode: ArkConfigArkRunMode;
236
+ compositionRoots: string[];
237
+ kernelRoots?: string[];
238
+ managedLayers: string[];
239
+ requireDeclarations: boolean;
240
+ ignoreDirectNewForErrors?: boolean;
241
+ };
242
+ /** ADR 0027 — advisory never adds merge teeth; enforced is the extra's merge plane. */
243
+ type ArkConfigArkOrderMode = 'advisory' | 'enforced';
244
+ /**
245
+ * ADR 0027 — optional inline ArkOrder extra (schema 1.3+). Absence is silent.
246
+ * Present objects are fully defaulted by the loader.
247
+ */
248
+ type ArkConfigArkOrder = {
249
+ mode: ArkConfigArkOrderMode;
250
+ planeRoots: string[];
251
+ managedLayers: string[];
114
252
  /**
115
- * Get all declared relationships (useful for graph generation).
253
+ * Haken cap on one `release()` / `assertXiKeyCap` (default 7).
254
+ * Not a cap on the `xiKeys` watchlist length.
116
255
  */
117
- getAllRelationships(): IntentRelationship[];
256
+ maxXiKeys: number;
118
257
  /**
119
- * Check if an intent name has been registered.
258
+ * Slow product keys the team can already name (plan, cost code, protocol).
259
+ * Optional. Empty → `ARKORDER_XI_FIELD_WRITE` stays silent.
260
+ * Repo-wide watchlist — not compared to `maxXiKeys`.
120
261
  */
121
- has(name: string): boolean;
262
+ xiKeys: string[];
122
263
  /**
123
- * Clear the registry. Primarily useful for tests.
264
+ * Optional globs that narrow ξ field-write observation inside `managedLayers`.
265
+ * Same glob engine as `layers[].patterns`. Absence or empty → every file in
266
+ * those layers. Non-empty → emit only when the layer is managed AND the file
267
+ * matches at least one glob.
124
268
  */
125
- clear(): void;
269
+ appliesTo?: string[];
270
+ };
271
+ type ArkConfig = {
272
+ $schema: string;
273
+ schemaVersion: ArkConfigSchemaVersion;
274
+ name?: string;
275
+ include: string[];
276
+ exclude?: string[];
277
+ excludeGenerated?: boolean;
278
+ frameworkOverlay?: string;
279
+ layers: ArkConfigLayer[];
280
+ rules: ArkConfigRule[];
281
+ cyclePolicy?: ArkConfigCyclePolicy;
282
+ dynamicImportAllowlist?: string[];
283
+ safety?: ArkConfigSafety;
284
+ /**
285
+ * Invariant-coverage scan controls (test globs + file budget).
286
+ * Absence keeps the defaults; it never turns coverage on by itself.
287
+ */
288
+ coverage?: ArkConfigCoverage;
289
+ /** ADR 0012 — modular ArkRules references (schema 1.1+). */
290
+ arkRules?: ArkConfigArkRulesRefs;
291
+ /** ADR 0020 — optional ArkRun extra (schema 1.2+). Absence changes no Layers/ArkRules verdict. */
292
+ arkRun?: ArkConfigArkRun;
293
+ /** ADR 0027 — optional ArkOrder extra (schema 1.3+). Absence changes no Layers/ArkRules/ArkRun verdict. */
294
+ arkOrder?: ArkConfigArkOrder;
295
+ /**
296
+ * Optional GitHub handles or emails who may loosen the contract or grow the baseline.
297
+ * Metadata — excluded from policy hash. Absence means no steward lock (policy-ack still applies).
298
+ */
299
+ stewards?: string[];
300
+ /**
301
+ * When true, every non-reserved layer must name `owners`. Absence/false is
302
+ * silent. This flag is policy teeth (stays in policyHash). Owners themselves
303
+ * stay metadata.
304
+ */
305
+ requireLayerOwners?: boolean;
306
+ };
307
+ /** Original input version when the loader rewrote schemaVersion toward current. */
308
+ type ArkConfigMigratedFrom = 'unversioned' | '1.0' | '1.1' | '1.2' | null;
309
+ type ArkConfigLoadResult = {
310
+ config: ArkConfig;
311
+ migratedFrom: ArkConfigMigratedFrom;
312
+ };
313
+
314
+ /**
315
+ * Architecture layer profiles.
316
+ *
317
+ * A profile turns semantic names such as `Domain.Order.Placed` into governed
318
+ * layer names and dependency rules.
319
+ */
320
+
321
+ interface ArchitectureLayer {
322
+ name: string;
323
+ prefixes: string[];
324
+ /**
325
+ * Custom matcher for teams whose intent names don't follow prefix conventions.
326
+ * Checked before any prefix matching, in layer declaration order. A layer may
327
+ * use `match` alone (with `prefixes: []`), prefixes alone, or both.
328
+ */
329
+ match?: (name: string) => boolean;
330
+ description?: string;
331
+ trustBoundary?: 'public' | 'auth' | 'admin' | 'internal';
332
+ owners?: string[];
333
+ order?: number;
334
+ }
335
+ type ArchitectureRule = ArkConfigRule;
336
+ interface ArchitectureProfile {
337
+ name: string;
338
+ layers: ArchitectureLayer[];
339
+ rules: ArchitectureRule[];
340
+ resolveLayer(name: string): string | undefined;
341
+ }
342
+ interface CreateArchitectureProfileOptions {
343
+ name: string;
344
+ layers: ArchitectureLayer[];
345
+ rules?: ArchitectureRule[];
346
+ }
347
+ interface CreateArchitectureProfileFromArkConfigOptions {
348
+ /** Runtime profile name. Default: config.name or "ark.config.json". */
349
+ name?: string;
350
+ }
351
+ type ArchitectureLayerConfig = ArkConfigLayer;
352
+ type ArkCheckConfig = Omit<ArkConfig, '$schema' | 'schemaVersion' | 'rules'> & {
353
+ $schema?: string;
354
+ schemaVersion?: ArkConfig['schemaVersion'];
355
+ rules?: ArchitectureRule[];
356
+ };
357
+ interface CreateElevenLayerArkConfigOptions {
358
+ /** Source root used in generated file patterns. Default: "src". */
359
+ rootDir?: string;
360
+ /** Include entries for ark-check. Default: [rootDir]. */
361
+ include?: string[];
362
+ /** Mark generated layers optional. Default: true. */
363
+ optionalLayers?: boolean;
126
364
  }
127
365
 
128
366
  /**
@@ -180,65 +418,161 @@ interface DependencyGraph {
180
418
  detectViolations(rules?: Array<(edges: GraphEdge[]) => string[]>): string[];
181
419
  }
182
420
 
183
- type MaybePromise<T> = T | Promise<T>;
184
- type AuditRecordType = 'event.published' | 'event.rawPublish' | 'event.intercepted' | 'interceptor.error' | 'policy.softViolation' | 'policy.hardViolation' | 'layer.observedViolation' | 'handler.error' | 'hook.error' | 'workflow.started' | 'workflow.step.completed' | 'workflow.step.failed' | 'workflow.compensation.completed' | 'workflow.completed' | 'workflow.failed' | 'projection.applied' | 'metadata.changed';
185
- interface AuditRecord {
186
- id: string;
187
- type: AuditRecordType;
188
- timestamp: string;
189
- source?: string;
190
- actor?: string;
191
- intent?: string;
192
- correlationId?: string;
193
- causationId?: string;
194
- subject?: string;
195
- details?: unknown;
196
- }
197
- interface AuditRecordInput {
198
- type: AuditRecordType;
199
- timestamp?: string;
200
- source?: string;
201
- actor?: string;
202
- intent?: string;
203
- correlationId?: string;
421
+ /**
422
+ * Core domain primitives for Ark.
423
+ * These types are the foundation for all governance concepts.
424
+ */
425
+ /**
426
+ * Semantic intent names follow a convention:
427
+ * - Domain.* for domain events and entities
428
+ * - Application.* for use-cases / orchestration
429
+ * - Adapter.* for integration points
430
+ * - Workflow.* for sagas and processes
431
+ * - Job.* for background jobs and scheduling
432
+ * - Presentation.* for UI/API adapters
433
+ * - Reporting.* for read models and projections
434
+ * - Metadata.* for extensibility contracts
435
+ * - Security.* / Audit.* / Observability.* for cross-cutting kernel concerns
436
+ * - Kernel.* for Ark-owned governance signals
437
+ */
438
+ type IntentName = `Domain.${string}` | `Application.${string}` | `Adapter.${string}` | `Workflow.${string}` | `Job.${string}` | `Presentation.${string}` | `Reporting.${string}` | `Metadata.${string}` | `Security.${string}` | `Audit.${string}` | `Observability.${string}` | `Kernel.${string}`;
439
+ type CorrelationId = string;
440
+ interface EventMetadata {
441
+ occurredAt: string;
442
+ source: string;
443
+ kernelInstanceId?: string;
444
+ eventVersion?: string;
445
+ schemaVersion?: string;
446
+ allowInterception?: boolean;
447
+ interceptions?: Array<{
448
+ interceptorId: string;
449
+ timestamp: string;
450
+ }>;
451
+ correlationId?: CorrelationId;
204
452
  causationId?: string;
205
- subject?: string;
206
- details?: unknown;
453
+ traceId?: string;
454
+ spanId?: string;
455
+ parentSpanId?: string;
456
+ [key: string]: unknown;
207
457
  }
208
- interface AuditQuery {
209
- type?: AuditRecordType;
210
- intent?: string;
211
- correlationId?: string;
212
- subject?: string;
213
- since?: string;
214
- until?: string;
215
- limit?: number;
458
+ interface DomainEvent<Name extends IntentName = IntentName, Payload = unknown> {
459
+ intent: Name;
460
+ payload: Payload;
461
+ metadata: EventMetadata;
216
462
  }
463
+
217
464
  /**
218
- * Pluggable persistence for audit records.
465
+ * Intent-specific types for the Ark kernel.
219
466
  *
220
- * **Durability stance (R9):** Default is `InMemoryAuditStore` — reference only, not
221
- * production durability (lost on restart). Implement this interface for durable audit.
222
- * See `docs/production-hardening.md`.
467
+ * Intents provide semantic naming for every important concept in the system
468
+ * (domain events, application operations, adapters, workflows).
223
469
  */
224
- interface AuditStore {
225
- append(record: AuditRecord): MaybePromise<void>;
226
- query(query?: AuditQuery): MaybePromise<AuditRecord[]>;
227
- clear(): MaybePromise<void>;
470
+
471
+ /**
472
+ * An IntentCreator is a callable that creates a strongly-typed DomainEvent
473
+ * when invoked with a payload.
474
+ *
475
+ * It also carries the semantic `name`.
476
+ *
477
+ * @example
478
+ * const OrderPlaced = defineIntent<'Domain.Order.OrderPlaced', { orderId: string }>('Domain.Order.OrderPlaced');
479
+ * const event = OrderPlaced({ orderId: 'o-1' });
480
+ */
481
+ interface IntentCreator<Name extends IntentName, Payload = unknown> {
482
+ /**
483
+ * Creates a DomainEvent for this intent.
484
+ */
485
+ (payload: Payload): DomainEvent<Name, Payload>;
486
+ /**
487
+ * The fully-qualified semantic name of the intent (e.g. "Domain.Order.OrderPlaced").
488
+ */
489
+ readonly name: Name;
228
490
  }
491
+ /** Kind of relationship between two intents. */
492
+ type IntentRelationshipKind = 'dependsOn' | 'produces';
229
493
  /**
230
- * High-level audit API used by the event bus / kernel.
231
- * Durability is that of the injected `AuditStore` (default in-memory).
494
+ * Relationship declarations between intents.
495
+ * Used for dependency analysis and graph generation.
232
496
  */
233
- interface AuditTrail {
234
- record(input: AuditRecordInput): Promise<AuditRecord>;
235
- query(query?: AuditQuery): Promise<AuditRecord[]>;
236
- clear(): Promise<void>;
497
+ interface IntentRelationship {
498
+ from: string;
499
+ to: string;
500
+ kind: IntentRelationshipKind;
237
501
  }
238
- interface CreateAuditTrailOptions {
239
- /** Durable store when provided; otherwise `InMemoryAuditStore` (not production durability). */
240
- store?: AuditStore;
241
- maxRecords?: number;
502
+
503
+ /**
504
+ * IntentRegistry
505
+ *
506
+ * Central registry for semantic intents.
507
+ * Supports registration, duplicate prevention, and declared dependency relationships.
508
+ *
509
+ * This is a core building block for governance, dependency graphs, and policy enforcement.
510
+ */
511
+
512
+ /**
513
+ * Options for declaring relationships when defining an intent.
514
+ */
515
+ interface DefineIntentOptions {
516
+ /** Other intents this one depends on (semantic names) */
517
+ dependsOn?: IntentName[];
518
+ /** Intents that this one produces / triggers */
519
+ produces?: IntentName[];
520
+ }
521
+ /**
522
+ * IntentRegistry manages all registered intents and their declared relationships.
523
+ */
524
+ declare class IntentRegistry {
525
+ private readonly intents;
526
+ private readonly dependencies;
527
+ private readonly productions;
528
+ /**
529
+ * Define/register a new intent.
530
+ *
531
+ * @param name - Semantic intent name following the convention (Domain.*, Application.*, etc.)
532
+ * @param options - Optional relationship declarations
533
+ * @throws Error if an intent with the same name is already registered
534
+ */
535
+ define<N extends IntentName, P = unknown>(name: N, options?: DefineIntentOptions): IntentCreator<N, P>;
536
+ /**
537
+ * Declare that one intent depends on / relates to another.
538
+ * This information is used by the DependencyGraph (future iterations) and for policy checks.
539
+ *
540
+ * @param from - The source intent (e.g. an Application operation)
541
+ * @param to - The target intent it depends on (e.g. a Domain event or concept)
542
+ */
543
+ declareDependency(from: string, to: string): void;
544
+ /**
545
+ * Declare that one intent produces / emits another (e.g. use case → domain event).
546
+ */
547
+ declareProduction(from: string, to: string): void;
548
+ /**
549
+ * Retrieve a previously defined intent creator by name.
550
+ */
551
+ get<N extends IntentName = IntentName, P = unknown>(name: string): IntentCreator<N, P> | undefined;
552
+ /**
553
+ * List all registered intent creators.
554
+ */
555
+ list(): IntentCreator<IntentName, unknown>[];
556
+ /**
557
+ * Get all declared dependencies for a given intent.
558
+ */
559
+ getDependencies(intentName: string): string[];
560
+ /**
561
+ * Get all intents produced / emitted by a given intent.
562
+ */
563
+ getProductions(intentName: string): string[];
564
+ /**
565
+ * Get all declared relationships (useful for graph generation).
566
+ */
567
+ getAllRelationships(): IntentRelationship[];
568
+ /**
569
+ * Check if an intent name has been registered.
570
+ */
571
+ has(name: string): boolean;
572
+ /**
573
+ * Clear the registry. Primarily useful for tests.
574
+ */
575
+ clear(): void;
242
576
  }
243
577
 
244
578
  type EventSchemaFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'unknown';
@@ -418,6 +752,102 @@ interface CreateProjectionRegistryOptions {
418
752
  auditTrail?: AuditTrail;
419
753
  }
420
754
 
755
+ /**
756
+ * Policy types for the Ark kernel.
757
+ *
758
+ * Policies allow declaring architectural rules that can be checked at runtime.
759
+ * Supports both hard policies (must never be violated) and soft policies (warnings).
760
+ */
761
+ type PolicySeverity = 'hard' | 'soft';
762
+ type PolicyEnforcementMode = 'runtime' | 'static' | 'runtime-and-static' | 'advisory';
763
+ /**
764
+ * Represents a single violation of a policy.
765
+ */
766
+ interface PolicyViolation {
767
+ /** Name of the policy that was violated */
768
+ policyName: string;
769
+ /** Severity level of the policy */
770
+ severity: PolicySeverity;
771
+ /** Human-readable explanation of the violation */
772
+ message: string;
773
+ /** Optional additional structured details */
774
+ details?: unknown;
775
+ }
776
+ /**
777
+ * A Policy defines a rule that can be evaluated against a context.
778
+ *
779
+ * @template Context - The shape of data the policy evaluates (e.g. { registry, events })
780
+ */
781
+ interface Policy<Context = unknown> {
782
+ /** Unique name of the policy (used in violations and reporting) */
783
+ readonly name: string;
784
+ /** Whether this is a hard rule (enforced strictly) or soft (advisory) */
785
+ readonly severity: PolicySeverity;
786
+ /** Optional tags for policy classification (e.g. 'layer', 'naming') */
787
+ readonly tags?: readonly string[];
788
+ readonly owner?: string;
789
+ readonly version?: string;
790
+ readonly rationale?: string;
791
+ readonly enforcementMode?: PolicyEnforcementMode;
792
+ readonly deprecated?: boolean | string;
793
+ readonly replacedBy?: string;
794
+ /**
795
+ * Evaluates the policy against the given context.
796
+ * Return true / [] for pass, false / single violation / array for failure.
797
+ */
798
+ check(context: Context): boolean | PolicyViolation | PolicyViolation[];
799
+ }
800
+
801
+ /**
802
+ * PolicyEngine
803
+ *
804
+ * Evaluates collections of policies against a context.
805
+ * Supports hard and soft policies.
806
+ * - Hard policies: violations cause enforcement to throw.
807
+ * - Soft policies: violations are reported as warnings but do not throw.
808
+ */
809
+
810
+ interface PolicyEvaluationResult {
811
+ passed: boolean;
812
+ violations: PolicyViolation[];
813
+ hardViolations: PolicyViolation[];
814
+ softViolations: PolicyViolation[];
815
+ }
816
+ /**
817
+ * The PolicyEngine is responsible for registering policies and evaluating
818
+ * them against a given context.
819
+ */
820
+ declare class PolicyEngine<Context = unknown> {
821
+ private readonly policies;
822
+ constructor(initialPolicies?: Policy<Context>[]);
823
+ /**
824
+ * Adds a policy to the engine.
825
+ */
826
+ add(policy: Policy<Context>): void;
827
+ /**
828
+ * Returns all registered policies.
829
+ */
830
+ getPolicies(): Policy<Context>[];
831
+ /**
832
+ * Evaluates all policies against the provided context.
833
+ */
834
+ evaluate(context: Context): PolicyEvaluationResult;
835
+ /**
836
+ * Enforces all policies.
837
+ *
838
+ * - Soft violations are collected and can be observed (returned or logged).
839
+ * - Hard violations cause an error to be thrown (by default).
840
+ *
841
+ * @returns Evaluation result (including any soft violations)
842
+ * @throws Error if any hard policy is violated
843
+ */
844
+ enforce(context: Context): PolicyEvaluationResult;
845
+ /**
846
+ * Clears all registered policies.
847
+ */
848
+ clear(): void;
849
+ }
850
+
421
851
  type EventBufferStatus = 'pending' | 'dispatched' | 'failed';
422
852
  interface EventBufferRecord {
423
853
  id: string;
@@ -464,7 +894,7 @@ type OutboxStore = EventBufferStore;
464
894
  */
465
895
 
466
896
  /** Standard trace record for observability and agent consumption. */
467
- type TraceRecordType = 'event.published' | 'event.rawPublish' | 'event.intercepted' | 'interceptor.error' | 'policy.hardViolation' | 'policy.softViolation' | 'layer.observedViolation' | 'handler.error' | 'hook.error';
897
+ type TraceRecordType = 'event.published' | 'event.rawPublish' | 'event.handoffFailed' | 'event.intercepted' | 'interceptor.error' | 'policy.hardViolation' | 'policy.softViolation' | 'layer.observedViolation' | 'handler.error' | 'hook.error';
468
898
  /**
469
899
  * Runtime enforcement mode for observed producer→event layer flows.
470
900
  * - 'off': flows are recorded (for drift reports) but never enforced.
@@ -510,6 +940,15 @@ interface EventBusOptions<Context = unknown> {
510
940
  enforceObservedLayerFlow?: ObservedLayerFlowMode;
511
941
  /** Optional non-atomic event buffer for dispatch handoff. */
512
942
  eventBuffer?: EventBufferStore;
943
+ /**
944
+ * When true, the event-buffer record written for a publish is marked
945
+ * `dispatched` once local delivery finishes (handlers + onPublish), or `failed`
946
+ * when a rethrown handler error aborts it. Use only when no external relay
947
+ * drains the buffer. Default: false — records stay `pending` for a
948
+ * consumer-owned relay (`claim` / `markDispatched`). `createArkKernel` turns
949
+ * this on for its default in-memory buffer only.
950
+ */
951
+ settleBufferOnLocalDelivery?: boolean;
513
952
  /** @deprecated Use eventBuffer. */
514
953
  outbox?: EventBufferStore;
515
954
  /** Stable id stamped into event metadata for this kernel/event bus instance. */
@@ -604,6 +1043,14 @@ interface EventDispatchControl {
604
1043
  awaitHandlers?: boolean;
605
1044
  runOnPublish?: boolean;
606
1045
  tx?: unknown;
1046
+ /**
1047
+ * When false, skip local-delivery settlement of the buffer record even if the
1048
+ * bus settles on local delivery (the caller owns the outcome, e.g. a broker
1049
+ * handoff). Default: the bus `settleBufferOnLocalDelivery` option.
1050
+ */
1051
+ settleBufferOnLocalDelivery?: boolean;
1052
+ /** Receives the event-buffer record written for this publish, when any. */
1053
+ onBufferRecord?: (record: EventBufferRecord) => void;
607
1054
  }
608
1055
  /**
609
1056
  * The public EventBus interface.
@@ -1188,6 +1635,24 @@ type ArkRunRegisterOptions<T = unknown> = {
1188
1635
  };
1189
1636
  type ArkRunRegistrationHandle = ArkRunInformationPackageComponent;
1190
1637
 
1638
+ type ArkRunInspectorListenSource = {
1639
+ getInspectorSnapshot(bind: ArkRunInspectorBind): ArkRunInspectorSnapshot;
1640
+ requestGraph(query?: ArkRunGraphQuery): ArkRunGraph;
1641
+ /** OD04: pending/failed outbox summaries (EventBufferStore.list). */
1642
+ listInspectorOutbox?(): Promise<ArkRunInspectorOutboxMonitor>;
1643
+ /** OD04: workflow/saga summaries (WorkflowEngine.list). */
1644
+ listInspectorWorkflows?(): Promise<ArkRunInspectorWorkflowsMonitor>;
1645
+ /** Duck-typed kernel ports when explicit list* helpers are absent. */
1646
+ outbox?: {
1647
+ list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
1648
+ };
1649
+ eventBuffer?: {
1650
+ list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
1651
+ };
1652
+ workflowEngine?: {
1653
+ list(workflowName?: string): Promise<unknown[]>;
1654
+ };
1655
+ };
1191
1656
  type ArkRunInspectorHandle = {
1192
1657
  host: string;
1193
1658
  port: number;
@@ -1200,11 +1665,6 @@ type ArkRunInspectorHandle = {
1200
1665
  close(): Promise<void>;
1201
1666
  };
1202
1667
 
1203
- /**
1204
- * Opt-in ArkRun inspector. HTTP is dynamically imported so constructing a
1205
- * kernel does not bind a port or load `node:http`.
1206
- */
1207
-
1208
1668
  type StartArkRunInspectorOptions = {
1209
1669
  host?: string;
1210
1670
  port?: number;
@@ -1212,24 +1672,8 @@ type StartArkRunInspectorOptions = {
1212
1672
  nodeEnv?: string;
1213
1673
  sseIntervalMs?: number;
1214
1674
  };
1215
- type ArkRunInspectorSource = {
1216
- getInspectorSnapshot(bind: ArkRunInspectorBind): ArkRunInspectorSnapshot;
1217
- requestGraph(query?: ArkRunGraphQuery): ArkRunGraph;
1218
- /** OD04: pending/failed outbox summaries (EventBufferStore.list). */
1219
- listInspectorOutbox?(): Promise<ArkRunInspectorOutboxMonitor>;
1220
- /** OD04: workflow/saga summaries (WorkflowEngine.list). */
1221
- listInspectorWorkflows?(): Promise<ArkRunInspectorWorkflowsMonitor>;
1222
- /** Duck-typed kernel ports when explicit list* helpers are absent. */
1223
- outbox?: {
1224
- list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
1225
- };
1226
- eventBuffer?: {
1227
- list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
1228
- };
1229
- workflowEngine?: {
1230
- list(workflowName?: string): Promise<unknown[]>;
1231
- };
1232
- };
1675
+ /** What the inspector reads: snapshot, graph, and optional outbox / workflow monitors. */
1676
+ type ArkRunInspectorSource = ArkRunInspectorListenSource;
1233
1677
  declare function startArkRunInspector(source: ArkRunInspectorSource, options?: StartArkRunInspectorOptions): Promise<ArkRunInspectorHandle>;
1234
1678
 
1235
1679
  /**
@@ -1353,4 +1797,4 @@ interface CreateArkKernelFromConfigOptions extends Omit<CreateArkKernelOptions,
1353
1797
  }
1354
1798
  type ArkKernelConfig = ArkCheckConfig;
1355
1799
 
1356
- export { ARK_RUN_INSPECTOR_EVENTS_PATH as $, type ArkKernel as A, type OutboxStatus as B, type CreateArkKernelOptions as C, type DefineIntentOptions as D, type EventContractRegistry as E, type OutboxRecord as F, type GraphEdge as G, type ObservabilityDriftReport as H, IntentRegistry as I, ARK_RUN_COMPONENT_LIFETIMES as J, ARK_RUN_EPHEMERAL_DEFAULT as K, ARK_RUN_GRAPH_DEFAULT_SLICE as L, type MetadataRegistry as M, ARK_RUN_GRAPH_NODE_KINDS as N, type ObservabilityReporter as O, type ProjectionRegistry as P, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as Q, type ReadModelStore as R, type SagaContext as S, type TraceRecordType as T, ARK_RUN_GRAPH_SCHEMA_VERSION as U, ARK_RUN_GRAPH_SLICES as V, type WorkflowStore as W, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as X, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as Y, ARK_RUN_INSPECTOR_DEFAULT_HOST as Z, ARK_RUN_INSPECTOR_DEFAULT_PORT as _, type DependencyGraph as a, type EventContractIssue as a$, ARK_RUN_INSPECTOR_GRAPH_PATH as a0, ARK_RUN_INSPECTOR_MONITOR_SAMPLE_LIMIT as a1, ARK_RUN_INSPECTOR_OUTBOX_PATH as a2, ARK_RUN_INSPECTOR_SCHEMA_VERSION as a3, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as a4, ARK_RUN_INSPECTOR_SSE_EVENT as a5, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as a6, ARK_RUN_INSPECTOR_WORKFLOWS_PATH as a7, ARK_RUN_TRANSPORT_KINDS as a8, type ArkManifestArchitecture as a9, type ArkRunInspectorHandle as aA, type ArkRunInspectorHardening as aB, type ArkRunInspectorHardeningDurability as aC, type ArkRunInspectorMonitorBuildOptions as aD, type ArkRunInspectorOutboxMonitor as aE, type ArkRunInspectorOutboxRecordSummary as aF, ArkRunInspectorProductionError as aG, type ArkRunInspectorSnapshot as aH, type ArkRunInspectorSnapshotInput as aI, type ArkRunInspectorSource as aJ, type ArkRunInspectorStoreDurability as aK, type ArkRunInspectorStoreDurabilityKind as aL, type ArkRunInspectorStoreRole as aM, type ArkRunInspectorTransportFacts as aN, type ArkRunInspectorWorkflowSummary as aO, type ArkRunInspectorWorkflowsMonitor as aP, type ArkRunPublisher as aQ, type ArkRunRegisterOptions as aR, type ArkRunRegistrationHandle as aS, type ArkRunSendOptions as aT, type ArkRunSendPlan as aU, type ArkRunSendPlanInput as aV, type ArkRunSendResult as aW, type ArkRunTransportKind as aX, type AuditRecordInput as aY, type AuditRecordType as aZ, type EntityMeta as a_, type ArkManifestData as aa, type ArkManifestEntityLink as ab, type ArkManifestGraph as ac, type ArkManifestIntent as ad, type ArkManifestPolicy as ae, type ArkManifestProjection as af, type ArkRunBrokerAdapter as ag, type ArkRunComponentLifetime as ah, type ArkRunDeliveredVia as ai, type ArkRunExtendedInfo as aj, type ArkRunGraph as ak, type ArkRunGraphEdge as al, type ArkRunGraphEdgeKind as am, type ArkRunGraphMatch as an, type ArkRunGraphMatchInput as ao, type ArkRunGraphNode as ap, type ArkRunGraphNodeKind as aq, type ArkRunGraphProcessEdgeKind as ar, type ArkRunGraphQuery as as, type ArkRunGraphResolvedQuery as at, type ArkRunGraphSlice as au, type ArkRunGraphTechnicalEdgeKind as av, type ArkRunInformationPackageComponent as aw, type ArkRunInspectorBind as ax, ArkRunInspectorBindError as ay, type ArkRunInspectorBindInput as az, type AuditStore as b, type EventHandler as b0, type EventInterceptionInfo as b1, type EventInterceptor as b2, type EventInterceptorContext as b3, type EventPayloadPatch as b4, type EventPayloadSchema as b5, type EventPublisher as b6, type EventSchemaField as b7, type EventSchemaFieldType as b8, type FieldMeta as b9, buildDependencyInformationPackage as bA, classifyArkRunInspectorStoreDurability as bB, closeArkRunGraphQuery as bC, closedArkRunEphemeral as bD, closedArkRunTransportKind as bE, formatArkRunGraphMermaid as bF, formatArkRunInspectorSseEvent as bG, isArkRunInspectorLoopbackHost as bH, isArkRunInspectorProductionEnv as bI, requestArkRunGraph as bJ, resolveArkRunInspectorBind as bK, resolveArkRunSendPlan as bL, startArkRunInspector as bM, unavailableArkRunInspectorOutboxMonitor as bN, unavailableArkRunInspectorWorkflowsMonitor as bO, type GraphNode as ba, InvalidArkRunGraphQueryError as bb, InvalidArkRunSendOptionError as bc, type ObservabilityFlow as bd, type ObservedLayerFlowMode as be, type OutboxStore as bf, type PolicyEvaluationResult as bg, type ProjectionCheckpoint as bh, type ProjectionDefinition as bi, type PublishedEventRecord as bj, type RetryPolicy as bk, type SagaStatus as bl, type SagaStep as bm, type StartArkRunInspectorOptions as bn, type TraceSink as bo, type Unsubscribe as bp, type WorkflowDefinition as bq, type WorkflowStatus as br, type WorkflowStep as bs, appendDecisionTape as bt, arkRunGraphQueryFromSearchParams as bu, arkRunInspectorUrl as bv, buildArkRunInspectorHardening as bw, buildArkRunInspectorOutboxMonitor as bx, buildArkRunInspectorSnapshot as by, buildArkRunInspectorWorkflowsMonitor as bz, type AuditRecord as c, type AuditQuery as d, type CreateAuditTrailOptions as e, type AuditTrail as f, type EventContract as g, type EventContractValidationResult as h, type CreateProjectionRegistryOptions as i, type EventBufferStore as j, type EventBufferRecord as k, type EventBufferStatus as l, type EventBusOptions as m, type EventBus as n, type CreateObservabilityReporterOptions as o, PolicyEngine as p, type ArkManifest as q, type WorkflowSnapshot as r, type SagaDefinition as s, type CreateWorkflowEngineOptions as t, type SagaInstance as u, type WorkflowEngine as v, type DependencyInformationPackage as w, type ArkKernelConfig as x, type CreateArkKernelFromConfigOptions as y, type TraceRecord as z };
1800
+ export { type TraceRecord as $, type ArkKernel as A, type EventBus as B, type CreateArkKernelOptions as C, type DependencyGraph as D, type EventContractRegistry as E, type CreateObservabilityReporterOptions as F, type GraphEdge as G, PolicyEngine as H, IntentRegistry as I, type ArkManifest as J, type WorkflowSnapshot as K, type SagaDefinition as L, type MetadataRegistry as M, type CreateWorkflowEngineOptions as N, type ObservabilityReporter as O, type ProjectionRegistry as P, type SagaInstance as Q, type ReadModelStore as R, type SagaContext as S, type WorkflowEngine as T, type ArkConfig as U, type ArkConfigLoadResult as V, type WorkflowStore as W, type DependencyInformationPackage as X, type ArkKernelConfig as Y, type CreateArkKernelFromConfigOptions as Z, type TraceRecordType as _, type AuditStore as a, type ArkRunInspectorSource as a$, type OutboxStatus as a0, type OutboxRecord as a1, type ObservabilityDriftReport as a2, ARK_RUN_COMPONENT_LIFETIMES as a3, ARK_RUN_EPHEMERAL_DEFAULT as a4, ARK_RUN_GRAPH_DEFAULT_SLICE as a5, ARK_RUN_GRAPH_NODE_KINDS as a6, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as a7, ARK_RUN_GRAPH_SCHEMA_VERSION as a8, ARK_RUN_GRAPH_SLICES as a9, type ArkRunDeliveredVia as aA, type ArkRunExtendedInfo as aB, type ArkRunGraph as aC, type ArkRunGraphEdge as aD, type ArkRunGraphEdgeKind as aE, type ArkRunGraphMatch as aF, type ArkRunGraphMatchInput as aG, type ArkRunGraphNode as aH, type ArkRunGraphNodeKind as aI, type ArkRunGraphProcessEdgeKind as aJ, type ArkRunGraphQuery as aK, type ArkRunGraphResolvedQuery as aL, type ArkRunGraphSlice as aM, type ArkRunGraphTechnicalEdgeKind as aN, type ArkRunInformationPackageComponent as aO, type ArkRunInspectorBind as aP, ArkRunInspectorBindError as aQ, type ArkRunInspectorBindInput as aR, type ArkRunInspectorHandle as aS, type ArkRunInspectorHardening as aT, type ArkRunInspectorHardeningDurability as aU, type ArkRunInspectorMonitorBuildOptions as aV, type ArkRunInspectorOutboxMonitor as aW, type ArkRunInspectorOutboxRecordSummary as aX, ArkRunInspectorProductionError as aY, type ArkRunInspectorSnapshot as aZ, type ArkRunInspectorSnapshotInput as a_, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as aa, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as ab, ARK_RUN_INSPECTOR_DEFAULT_HOST as ac, ARK_RUN_INSPECTOR_DEFAULT_PORT as ad, ARK_RUN_INSPECTOR_EVENTS_PATH as ae, ARK_RUN_INSPECTOR_GRAPH_PATH as af, ARK_RUN_INSPECTOR_MONITOR_SAMPLE_LIMIT as ag, ARK_RUN_INSPECTOR_OUTBOX_PATH as ah, ARK_RUN_INSPECTOR_SCHEMA_VERSION as ai, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as aj, ARK_RUN_INSPECTOR_SSE_EVENT as ak, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as al, ARK_RUN_INSPECTOR_WORKFLOWS_PATH as am, ARK_RUN_TRANSPORT_KINDS as an, type ArchitectureLayer as ao, type ArchitectureLayerConfig as ap, type ArchitectureRule as aq, type ArkManifestArchitecture as ar, type ArkManifestData as as, type ArkManifestEntityLink as at, type ArkManifestGraph as au, type ArkManifestIntent as av, type ArkManifestPolicy as aw, type ArkManifestProjection as ax, type ArkRunBrokerAdapter as ay, type ArkRunComponentLifetime as az, type AuditRecord as b, formatArkRunInspectorSseEvent as b$, type ArkRunInspectorStoreDurability as b0, type ArkRunInspectorStoreDurabilityKind as b1, type ArkRunInspectorStoreRole as b2, type ArkRunInspectorTransportFacts as b3, type ArkRunInspectorWorkflowSummary as b4, type ArkRunInspectorWorkflowsMonitor as b5, type ArkRunPublisher as b6, type ArkRunRegisterOptions as b7, type ArkRunRegistrationHandle as b8, type ArkRunSendOptions as b9, type OutboxStore as bA, type PolicyEvaluationResult as bB, type ProjectionCheckpoint as bC, type ProjectionDefinition as bD, type PublishedEventRecord as bE, type RetryPolicy as bF, type SagaStatus as bG, type SagaStep as bH, type StartArkRunInspectorOptions as bI, type TraceSink as bJ, type Unsubscribe as bK, type WorkflowDefinition as bL, type WorkflowStatus as bM, type WorkflowStep as bN, appendDecisionTape as bO, arkRunGraphQueryFromSearchParams as bP, arkRunInspectorUrl as bQ, buildArkRunInspectorHardening as bR, buildArkRunInspectorOutboxMonitor as bS, buildArkRunInspectorSnapshot as bT, buildArkRunInspectorWorkflowsMonitor as bU, buildDependencyInformationPackage as bV, classifyArkRunInspectorStoreDurability as bW, closeArkRunGraphQuery as bX, closedArkRunEphemeral as bY, closedArkRunTransportKind as bZ, formatArkRunGraphMermaid as b_, type ArkRunSendPlan as ba, type ArkRunSendPlanInput as bb, type ArkRunSendResult as bc, type ArkRunTransportKind as bd, type AuditRecordInput as be, type AuditRecordType as bf, type CorrelationId as bg, type EntityMeta as bh, type EventContractIssue as bi, type EventHandler as bj, type EventInterceptionInfo as bk, type EventInterceptor as bl, type EventInterceptorContext as bm, type EventMetadata as bn, type EventPayloadPatch as bo, type EventPayloadSchema as bp, type EventPublisher as bq, type EventSchemaField as br, type EventSchemaFieldType as bs, type FieldMeta as bt, type GraphNode as bu, type IntentRelationshipKind as bv, InvalidArkRunGraphQueryError as bw, InvalidArkRunSendOptionError as bx, type ObservabilityFlow as by, type ObservedLayerFlowMode as bz, type AuditQuery as c, isArkRunInspectorLoopbackHost as c0, isArkRunInspectorProductionEnv as c1, requestArkRunGraph as c2, resolveArkRunInspectorBind as c3, resolveArkRunSendPlan as c4, startArkRunInspector as c5, unavailableArkRunInspectorOutboxMonitor as c6, unavailableArkRunInspectorWorkflowsMonitor as c7, type CreateAuditTrailOptions as d, type AuditTrail as e, type CreateArchitectureProfileOptions as f, type ArchitectureProfile as g, type ArkCheckConfig as h, type CreateArchitectureProfileFromArkConfigOptions as i, type CreateElevenLayerArkConfigOptions as j, type EventContract as k, type DomainEvent as l, type EventContractValidationResult as m, type IntentName as n, type DefineIntentOptions as o, type IntentCreator as p, type CreateProjectionRegistryOptions as q, type PolicyViolation as r, type PolicySeverity as s, type PolicyEnforcementMode as t, type Policy as u, type IntentRelationship as v, type EventBufferStore as w, type EventBufferRecord as x, type EventBufferStatus as y, type EventBusOptions as z };