arkgate 4.7.6 → 4.8.1

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 (67) hide show
  1. package/CHANGELOG.md +37 -3
  2. package/README.md +8 -9
  3. package/bin/lib/analysis-engine.mjs +6 -6
  4. package/bin/lib/architecture-scan.mjs +7 -2
  5. package/bin/lib/ark-order-error.mjs +18 -0
  6. package/bin/lib/ark-order-facts.mjs +53 -0
  7. package/bin/lib/ark-order-invariants.mjs +160 -0
  8. package/bin/lib/ark-order-sensors.mjs +118 -0
  9. package/bin/lib/ark-order-types.mjs +11 -0
  10. package/bin/lib/ark-run-sensors.mjs +13 -5
  11. package/bin/lib/config-contract.mjs +16 -72
  12. package/bin/lib/config-extras.mjs +151 -0
  13. package/bin/lib/diagnostic-catalog.mjs +7 -2
  14. package/bin/lib/extra-merge-teeth.mjs +8 -2
  15. package/bin/lib/install-migrate.mjs +4 -2
  16. package/bin/lib/invariant-coverage-io.mjs +61 -24
  17. package/bin/lib/invariant-coverage.mjs +4 -1
  18. package/bin/lib/managed-upgrade.mjs +1 -1
  19. package/bin/lib/mcp-adoption.mjs +9 -3
  20. package/bin/lib/policy-delta-io.mjs +8 -2
  21. package/bin/lib/remediation.mjs +48 -9
  22. package/bin/lib/resolved-candidate-facts.mjs +43 -0
  23. package/bin/lib/rules-under-contract.mjs +8 -2
  24. package/bin/lib/skill-install.mjs +17 -2
  25. package/bin/lib/start-preview.mjs +1 -0
  26. package/bin/lib/status-manifest.mjs +1 -1
  27. package/bin/lib/write-path-capabilities.mjs +2 -2
  28. package/dist/{configTypes-CgJimx9o.d.ts → configTypes-BdCe_gvv.d.ts} +22 -6
  29. package/dist/diagnosticCatalog-CSF4N3w8.d.ts +2313 -0
  30. package/dist/eslint/index.cjs +7 -6
  31. package/dist/eslint/index.d.ts +33 -2
  32. package/dist/eslint/index.js +7 -6
  33. package/dist/index.cjs +35 -35
  34. package/dist/index.d.ts +271 -2554
  35. package/dist/index.js +35 -35
  36. package/dist/nestjs/index.cjs +18 -0
  37. package/dist/nestjs/index.d.ts +24 -0
  38. package/dist/nestjs/index.js +18 -0
  39. package/dist/order/index.cjs +1 -0
  40. package/dist/order/index.d.ts +79 -0
  41. package/dist/order/index.js +1 -0
  42. package/dist/runtime/index.cjs +25 -0
  43. package/dist/runtime/index.d.ts +497 -0
  44. package/dist/runtime/index.js +25 -0
  45. package/dist/types-C9KApBzX.d.ts +1237 -0
  46. package/dist/types-DCSlrRnV.d.ts +181 -0
  47. package/docs/README.md +4 -4
  48. package/docs/agent-guide.md +1 -1
  49. package/docs/ai-gates.md +9 -2
  50. package/docs/configuration.md +13 -6
  51. package/docs/develop.md +4 -3
  52. package/docs/diagnostics.md +57 -3
  53. package/docs/package-surface.md +20 -16
  54. package/docs/product-voice.md +2 -1
  55. package/package.json +21 -2
  56. package/schemas/ark.config.schema.json +54 -2
  57. package/schemas/ark.resolved-candidate-facts.schema.json +1 -1
  58. package/server.json +2 -2
  59. package/templates/agent-skills/README.md +1 -1
  60. package/templates/agent-skills/ark-adopt/SKILL.md +2 -2
  61. package/templates/agent-skills/ark-contract/SKILL.md +1 -1
  62. package/templates/agent-skills/ark-place/SKILL.md +15 -6
  63. package/templates/agent-skills/ark-runtime/SKILL.md +10 -15
  64. package/templates/skills/ark-adopt.md +2 -2
  65. package/templates/skills/ark-contract.md +1 -1
  66. package/templates/skills/ark-place.md +15 -6
  67. package/templates/skills/ark-runtime.md +10 -15
@@ -0,0 +1,1237 @@
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-DCSlrRnV.js';
2
+
3
+ /**
4
+ * PolicyEngine
5
+ *
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.
10
+ */
11
+
12
+ interface PolicyEvaluationResult {
13
+ passed: boolean;
14
+ violations: PolicyViolation[];
15
+ hardViolations: PolicyViolation[];
16
+ softViolations: PolicyViolation[];
17
+ }
18
+ /**
19
+ * The PolicyEngine is responsible for registering policies and evaluating
20
+ * them against a given context.
21
+ */
22
+ declare class PolicyEngine<Context = unknown> {
23
+ private readonly policies;
24
+ constructor(initialPolicies?: Policy<Context>[]);
25
+ /**
26
+ * Adds a policy to the engine.
27
+ */
28
+ add(policy: Policy<Context>): void;
29
+ /**
30
+ * Returns all registered policies.
31
+ */
32
+ getPolicies(): Policy<Context>[];
33
+ /**
34
+ * Evaluates all policies against the provided context.
35
+ */
36
+ evaluate(context: Context): PolicyEvaluationResult;
37
+ /**
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
45
+ */
46
+ enforce(context: Context): PolicyEvaluationResult;
47
+ /**
48
+ * Clears all registered policies.
49
+ */
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;
78
+ /**
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
84
+ */
85
+ define<N extends IntentName, P = unknown>(name: N, options?: DefineIntentOptions): IntentCreator<N, P>;
86
+ /**
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)
92
+ */
93
+ declareDependency(from: string, to: string): void;
94
+ /**
95
+ * Declare that one intent produces / emits another (e.g. use case → domain event).
96
+ */
97
+ declareProduction(from: string, to: string): void;
98
+ /**
99
+ * Retrieve a previously defined intent creator by name.
100
+ */
101
+ get<N extends IntentName = IntentName, P = unknown>(name: string): IntentCreator<N, P> | undefined;
102
+ /**
103
+ * List all registered intent creators.
104
+ */
105
+ list(): IntentCreator<IntentName, unknown>[];
106
+ /**
107
+ * Get all declared dependencies for a given intent.
108
+ */
109
+ getDependencies(intentName: string): string[];
110
+ /**
111
+ * Get all intents produced / emitted by a given intent.
112
+ */
113
+ getProductions(intentName: string): string[];
114
+ /**
115
+ * Get all declared relationships (useful for graph generation).
116
+ */
117
+ getAllRelationships(): IntentRelationship[];
118
+ /**
119
+ * Check if an intent name has been registered.
120
+ */
121
+ has(name: string): boolean;
122
+ /**
123
+ * Clear the registry. Primarily useful for tests.
124
+ */
125
+ clear(): void;
126
+ }
127
+
128
+ /**
129
+ * Dependency Graph types.
130
+ *
131
+ * Used to model declared + observed relationships between intents,
132
+ * and to generate visualizations (Mermaid) and detect violations.
133
+ */
134
+
135
+ interface GraphEdge {
136
+ from: string;
137
+ to: string;
138
+ kind?: 'declared' | 'observed' | 'produces';
139
+ }
140
+ interface GraphNode {
141
+ id: string;
142
+ kind?: string;
143
+ }
144
+ interface DependencyGraph {
145
+ /**
146
+ * Register a declared dependency between two semantic names.
147
+ */
148
+ registerDependency(from: string, to: string, kind?: GraphEdge['kind']): void;
149
+ /**
150
+ * Register an observed event flow (producer -> consumer).
151
+ */
152
+ registerEventFlow(producer: string, consumer: string): void;
153
+ /**
154
+ * Return all nodes.
155
+ */
156
+ getNodes(): GraphNode[];
157
+ /**
158
+ * Return all edges.
159
+ */
160
+ getEdges(): GraphEdge[];
161
+ /**
162
+ * Export as JSON.
163
+ */
164
+ toJSON(): {
165
+ nodes: GraphNode[];
166
+ edges: GraphEdge[];
167
+ };
168
+ /**
169
+ * Export as Mermaid flowchart.
170
+ */
171
+ toMermaid(): string;
172
+ /**
173
+ * Export as Mermaid flowchart grouped into profile layers.
174
+ */
175
+ toLayerMermaid(profile: ArchitectureProfile): string;
176
+ /**
177
+ * Detect violations by running provided policies or simple rules.
178
+ * For simplicity here we accept predicates that return violation messages.
179
+ */
180
+ detectViolations(rules?: Array<(edges: GraphEdge[]) => string[]>): string[];
181
+ }
182
+
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;
204
+ causationId?: string;
205
+ subject?: string;
206
+ details?: unknown;
207
+ }
208
+ interface AuditQuery {
209
+ type?: AuditRecordType;
210
+ intent?: string;
211
+ correlationId?: string;
212
+ subject?: string;
213
+ since?: string;
214
+ until?: string;
215
+ limit?: number;
216
+ }
217
+ /**
218
+ * Pluggable persistence for audit records.
219
+ *
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`.
223
+ */
224
+ interface AuditStore {
225
+ append(record: AuditRecord): MaybePromise<void>;
226
+ query(query?: AuditQuery): MaybePromise<AuditRecord[]>;
227
+ clear(): MaybePromise<void>;
228
+ }
229
+ /**
230
+ * High-level audit API used by the event bus / kernel.
231
+ * Durability is that of the injected `AuditStore` (default in-memory).
232
+ */
233
+ interface AuditTrail {
234
+ record(input: AuditRecordInput): Promise<AuditRecord>;
235
+ query(query?: AuditQuery): Promise<AuditRecord[]>;
236
+ clear(): Promise<void>;
237
+ }
238
+ interface CreateAuditTrailOptions {
239
+ /** Durable store when provided; otherwise `InMemoryAuditStore` (not production durability). */
240
+ store?: AuditStore;
241
+ maxRecords?: number;
242
+ }
243
+
244
+ type EventSchemaFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'unknown';
245
+ interface EventSchemaField {
246
+ type: EventSchemaFieldType;
247
+ required?: boolean;
248
+ description?: string;
249
+ /** Allowed literal values for this field. Compared with Object.is. */
250
+ enum?: unknown[];
251
+ /** Nested object fields when type is "object". */
252
+ fields?: EventPayloadSchema;
253
+ /** Array item schema when type is "array". */
254
+ items?: EventSchemaField;
255
+ }
256
+ type EventPayloadSchema = Record<string, EventSchemaField>;
257
+ /**
258
+ * Minimal Standard Schema interface (https://standardschema.dev).
259
+ * Any zod/valibot/arktype (or other spec-compliant) schema satisfies this,
260
+ * so Ark stays zero-dependency while accepting the validators you already use.
261
+ */
262
+ interface StandardSchemaV1<Input = unknown, Output = Input> {
263
+ readonly '~standard': {
264
+ readonly version: 1;
265
+ readonly vendor: string;
266
+ readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
267
+ readonly types?: {
268
+ readonly input: Input;
269
+ readonly output: Output;
270
+ } | undefined;
271
+ };
272
+ }
273
+ type StandardSchemaResult<Output> = {
274
+ readonly value: Output;
275
+ readonly issues?: undefined;
276
+ } | {
277
+ readonly issues: ReadonlyArray<StandardSchemaIssue>;
278
+ };
279
+ interface StandardSchemaIssue {
280
+ readonly message: string;
281
+ readonly path?: ReadonlyArray<PropertyKey | {
282
+ readonly key: PropertyKey;
283
+ }> | undefined;
284
+ }
285
+ interface EventContract {
286
+ intent: IntentName;
287
+ version: string;
288
+ schema?: EventPayloadSchema;
289
+ /**
290
+ * A Standard Schema validator (zod, valibot, arktype, ...) for the payload.
291
+ * Runs in addition to `schema` when both are present. Must validate
292
+ * synchronously — async validators produce a contract issue.
293
+ */
294
+ standardSchema?: StandardSchemaV1;
295
+ owner?: string;
296
+ rationale?: string;
297
+ deprecated?: boolean | string;
298
+ allowAdditionalFields?: boolean;
299
+ }
300
+ interface EventContractIssue {
301
+ intent: string;
302
+ version?: string;
303
+ field?: string;
304
+ message: string;
305
+ }
306
+ interface EventContractValidationResult {
307
+ ok: boolean;
308
+ contract?: EventContract;
309
+ issues: EventContractIssue[];
310
+ }
311
+ interface EventContractRegistry {
312
+ register(contract: EventContract): void;
313
+ get(intent: string, version?: string): EventContract | undefined;
314
+ list(intent?: string): EventContract[];
315
+ validate(event: DomainEvent): EventContractValidationResult;
316
+ clear(): void;
317
+ }
318
+
319
+ /**
320
+ * Metadata System (basic) for extensibility.
321
+ *
322
+ * Allows declaring entities, fields and simple rules/behaviors as data.
323
+ * This can be used by tools, codegen, or AI to understand the domain without hardcoding.
324
+ */
325
+ interface FieldMeta {
326
+ type: string;
327
+ identity?: boolean;
328
+ required?: boolean;
329
+ description?: string;
330
+ relation?: {
331
+ entity: string;
332
+ kind?: 'one' | 'many';
333
+ };
334
+ readonly?: boolean;
335
+ deprecated?: boolean | string;
336
+ tags?: string[];
337
+ [key: string]: unknown;
338
+ }
339
+ interface EntityRuleMeta {
340
+ name: string;
341
+ description?: string;
342
+ severity?: 'hard' | 'soft';
343
+ }
344
+ interface EntityMeta {
345
+ name: string;
346
+ version?: string;
347
+ owner?: string;
348
+ layer?: string;
349
+ tags?: string[];
350
+ fields: Record<string, FieldMeta>;
351
+ rules?: EntityRuleMeta[];
352
+ /** Intent names this entity emits (domain events). */
353
+ emits?: string[];
354
+ /** Intent names this entity consumes / reacts to. */
355
+ consumes?: string[];
356
+ /** Read-model or projection names that derive from this entity. */
357
+ projections?: string[];
358
+ deprecated?: boolean | string;
359
+ [key: string]: unknown;
360
+ }
361
+ interface MetadataRegistrationOptions {
362
+ allowOverwrite?: boolean;
363
+ }
364
+ interface MetadataIssue {
365
+ entity: string;
366
+ field?: string;
367
+ message: string;
368
+ }
369
+ interface MetadataValidationResult {
370
+ ok: boolean;
371
+ issues: MetadataIssue[];
372
+ }
373
+ interface MetadataRegistry {
374
+ entity(name: string, meta: Omit<EntityMeta, 'name'>, options?: MetadataRegistrationOptions): EntityMeta;
375
+ getEntity(name: string): EntityMeta | undefined;
376
+ listEntities(): EntityMeta[];
377
+ findEntitiesByIntent(intentName: string): EntityMeta[];
378
+ validate(): MetadataValidationResult;
379
+ toJSON(): EntityMeta[];
380
+ }
381
+
382
+ interface ProjectionDefinition<State = unknown> {
383
+ name: string;
384
+ sourceIntents: IntentName[];
385
+ initialState: State | (() => State);
386
+ project(event: DomainEvent<IntentName, unknown>, state: State): MaybePromise<State>;
387
+ }
388
+ interface ProjectionCheckpoint {
389
+ projection: string;
390
+ appliedCount: number;
391
+ lastIntent?: string;
392
+ lastCorrelationId?: string;
393
+ updatedAt?: string;
394
+ }
395
+ /**
396
+ * Pluggable projection/read-model state.
397
+ *
398
+ * **Durability stance (R9):** Default `InMemoryReadModelStore` is reference-only (not
399
+ * production durability). Inject a durable store for production. See
400
+ * `docs/production-hardening.md`.
401
+ */
402
+ interface ReadModelStore {
403
+ load<State = unknown>(name: string): MaybePromise<State | undefined>;
404
+ save<State = unknown>(name: string, state: State): MaybePromise<void>;
405
+ clear(name?: string): MaybePromise<void>;
406
+ }
407
+ interface ProjectionRegistry {
408
+ register<State>(definition: ProjectionDefinition<State>): void;
409
+ list(): ProjectionDefinition[];
410
+ apply(event: DomainEvent<IntentName, unknown>): Promise<string[]>;
411
+ getState<State = unknown>(name: string): Promise<State | undefined>;
412
+ getCheckpoint(name: string): ProjectionCheckpoint | undefined;
413
+ getCheckpoints(): ProjectionCheckpoint[];
414
+ clear(): Promise<void>;
415
+ }
416
+ interface CreateProjectionRegistryOptions {
417
+ store?: ReadModelStore;
418
+ auditTrail?: AuditTrail;
419
+ }
420
+
421
+ type EventBufferStatus = 'pending' | 'dispatched' | 'failed';
422
+ interface EventBufferRecord {
423
+ id: string;
424
+ event: DomainEvent;
425
+ status: EventBufferStatus;
426
+ attempts: number;
427
+ createdAt: string;
428
+ updatedAt: string;
429
+ error?: string;
430
+ ownerId?: string;
431
+ expiresAt?: string;
432
+ }
433
+ /**
434
+ * Pluggable transactional event buffer for publish handoff (Outbox pattern).
435
+ *
436
+ * Provides agnostic primitives (tx parameter, claim leases) to allow production implementations
437
+ * to safely handle concurrency, atomic handoffs, and background processing.
438
+ *
439
+ * **Durability stance (R9):** ArkGate ships only a reference in-process store
440
+ * (`InMemoryEventBuffer`) for tests, demos, and single-process development — it does
441
+ * not survive process restarts and is **not production durability**. Inject your own
442
+ * for a transactional outbox. See `docs/production-hardening.md`.
443
+ */
444
+ interface EventBufferStore {
445
+ enqueue(event: DomainEvent, tx?: unknown): Promise<EventBufferRecord>;
446
+ claim?(workerId: string, timeoutMs: number): Promise<EventBufferRecord | undefined>;
447
+ markDispatched(id: string, tx?: unknown): Promise<void>;
448
+ markFailed(id: string, error: unknown, tx?: unknown): Promise<void>;
449
+ list(status?: EventBufferStatus): Promise<EventBufferRecord[]>;
450
+ clear(): Promise<void>;
451
+ }
452
+ /** @deprecated Use EventBufferStatus. */
453
+ type OutboxStatus = EventBufferStatus;
454
+ /** @deprecated Use EventBufferRecord. */
455
+ type OutboxRecord = EventBufferRecord;
456
+ /** @deprecated Use EventBufferStore. */
457
+ type OutboxStore = EventBufferStore;
458
+
459
+ /**
460
+ * Event Bus types for the Ark kernel.
461
+ *
462
+ * The Event Bus is the central nervous system for Domain Events.
463
+ * It provides publish/subscribe, history for observability, and metadata handling.
464
+ */
465
+
466
+ /** 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';
468
+ /**
469
+ * Runtime enforcement mode for observed producer→event layer flows.
470
+ * - 'off': flows are recorded (for drift reports) but never enforced.
471
+ * - 'soft': a `layer.observedViolation` trace + audit record is emitted; publish proceeds.
472
+ * - 'hard': publish throws `ObservedLayerFlowViolationError` before the event reaches
473
+ * history, outbox, or subscribers.
474
+ */
475
+ type ObservedLayerFlowMode = 'off' | 'soft' | 'hard';
476
+ interface TraceRecord {
477
+ type: TraceRecordType;
478
+ timestamp: string;
479
+ intent: string;
480
+ correlationId?: string;
481
+ traceId?: string;
482
+ spanId?: string;
483
+ details?: unknown;
484
+ }
485
+ type TraceSink = (record: TraceRecord) => void;
486
+ /**
487
+ * Options when creating an EventBus.
488
+ */
489
+ interface EventBusOptions<Context = unknown> {
490
+ /** Optional hook called after every successful publish */
491
+ onPublish?: (event: DomainEvent) => void | Promise<void>;
492
+ /** Native audit trail used to persist publish, policy, and handler events. */
493
+ auditTrail?: AuditTrail;
494
+ /** Event contracts used to validate payload shape and event versions. */
495
+ eventContracts?: EventContractRegistry;
496
+ /** When true, events without a registered contract are rejected. */
497
+ strictEventContracts?: boolean;
498
+ /** When true, metadata.source must be explicit and not "unknown". */
499
+ requireKnownSource?: boolean;
500
+ /**
501
+ * Architecture profile used to enforce the OBSERVED producer→event layer flow at
502
+ * publish time. Required for `enforceObservedLayerFlow` to have effect.
503
+ */
504
+ architectureProfile?: ArchitectureProfile;
505
+ /**
506
+ * Enforce each published event's real producer→event flow (metadata.source → intent)
507
+ * against `architectureProfile` layer rules at runtime. Unlike the declared-model layer
508
+ * policy, this checks what the system actually did. Default: 'off'.
509
+ */
510
+ enforceObservedLayerFlow?: ObservedLayerFlowMode;
511
+ /** Optional non-atomic event buffer for dispatch handoff. */
512
+ eventBuffer?: EventBufferStore;
513
+ /** @deprecated Use eventBuffer. */
514
+ outbox?: EventBufferStore;
515
+ /** Stable id stamped into event metadata for this kernel/event bus instance. */
516
+ instanceId?: string;
517
+ /** Lightweight tracing hooks for OpenTelemetry or custom tracer bridges. */
518
+ traceSinks?: TraceSink[];
519
+ /** Called when soft policies produce violations (publish still proceeds). */
520
+ onSoftViolation?: (result: PolicyEvaluationResult, event: DomainEvent) => void | Promise<void>;
521
+ /** Called when a subscriber handler throws or rejects. */
522
+ onHandlerError?: (error: unknown, event: DomainEvent, intentName: string) => void | Promise<void>;
523
+ /** When true, rethrow handler errors after calling onHandlerError. Default: false. */
524
+ rethrowHandlerErrors?: boolean;
525
+ /**
526
+ * Policies to evaluate on every publish.
527
+ * If provided, they run before subscribers are notified.
528
+ * Hard violations will cause publish to throw.
529
+ */
530
+ policies?: Policy<Context>[];
531
+ /**
532
+ * Function to build the context object passed to policies for a given event.
533
+ * Default: { event }, or { event, relationships, edges } when registry/graph provided.
534
+ */
535
+ getPolicyContext?: (event: DomainEvent) => Context;
536
+ /**
537
+ * Intent registry whose relationships are injected into the default policy context.
538
+ * Enables layer policies (e.g. architecturalPolicies.layerIsolation) on publish.
539
+ */
540
+ intentRegistry?: IntentRegistry;
541
+ /**
542
+ * Dependency graph whose edges are injected into the default policy context.
543
+ */
544
+ dependencyGraph?: DependencyGraph;
545
+ /**
546
+ * Pre-configured PolicyEngine to use (alternative to policies array).
547
+ */
548
+ policyEngine?: PolicyEngine<Context>;
549
+ /**
550
+ * Maximum publish history entries to retain. Oldest evicted when exceeded.
551
+ * Default: unlimited.
552
+ */
553
+ maxHistorySize?: number;
554
+ /**
555
+ * When true (default: true if intentRegistry is provided), reject publish/subscribe
556
+ * for intents not registered in intentRegistry and optionally validate naming.
557
+ */
558
+ strictRegistry?: boolean;
559
+ /**
560
+ * When true (default: matches strictRegistry), validate intent names follow
561
+ * Domain.* / Application.* / Adapter.* / Workflow.* conventions at runtime.
562
+ */
563
+ validateIntentNaming?: boolean;
564
+ }
565
+ /**
566
+ * A subscriber is a function that receives events of a specific intent.
567
+ */
568
+ type EventHandler<N extends IntentName, P = unknown> = (event: DomainEvent<N, P>) => void | Promise<void>;
569
+ type EventPayloadPatch = Record<string, unknown> | unknown[];
570
+ interface EventInterceptorContext<N extends IntentName = IntentName, P = unknown> {
571
+ readonly event: Readonly<DomainEvent<N, P>>;
572
+ intercept(patch: EventPayloadPatch): void;
573
+ }
574
+ type EventInterceptor<N extends IntentName = IntentName, P = unknown> = (context: EventInterceptorContext<N, P>) => void | Promise<void>;
575
+ interface EventInterceptionInfo {
576
+ registrationId: string;
577
+ interceptorId: string;
578
+ intent: string;
579
+ createdAt: string;
580
+ lastInterceptedAt?: string;
581
+ }
582
+ /**
583
+ * Unsubscribe function returned by subscribe.
584
+ */
585
+ type Unsubscribe = () => void;
586
+ /**
587
+ * Record of a published event for observability.
588
+ */
589
+ interface PublishedEventRecord {
590
+ event: DomainEvent;
591
+ publishedAt: string;
592
+ subscribersNotified: number;
593
+ }
594
+ interface EventPublisher {
595
+ readonly source: string;
596
+ publish<N extends IntentName, P>(intent: IntentCreator<N, P>, payload: P, metadata?: Partial<EventMetadata>, control?: EventDispatchControl): Promise<void>;
597
+ }
598
+ /**
599
+ * Internal dispatch control for ArkRun send ports.
600
+ * `publish()` keeps historical defaults (notify + await handlers).
601
+ */
602
+ interface EventDispatchControl {
603
+ notifySubscribers?: boolean;
604
+ awaitHandlers?: boolean;
605
+ runOnPublish?: boolean;
606
+ tx?: unknown;
607
+ }
608
+ /**
609
+ * The public EventBus interface.
610
+ */
611
+ interface EventBus {
612
+ /**
613
+ * Publish an event.
614
+ * Accepts either a pre-built DomainEvent or an IntentCreator + payload (plus optional metadata).
615
+ */
616
+ publish<N extends IntentName, P>(eventOrCreator: DomainEvent<N, P> | IntentCreator<N, P>, payloadOrMeta?: P | Partial<EventMetadata>, metadata?: Partial<EventMetadata>, control?: EventDispatchControl): Promise<void>;
617
+ /**
618
+ * Create a source-bound publisher capability. The returned publisher stamps
619
+ * metadata.source internally and rejects attempts to publish as another source.
620
+ */
621
+ createPublisher<N extends IntentName, P>(source: N | IntentCreator<N, P>): EventPublisher;
622
+ /**
623
+ * Subscribe to events for a specific intent (by name or creator).
624
+ * Returns an unsubscribe function.
625
+ */
626
+ subscribe<N extends IntentName, P>(intent: N | IntentCreator<N, P>, handler: EventHandler<N, P>): Unsubscribe;
627
+ /**
628
+ * Register an add-only interceptor for one intent.
629
+ * Interceptors may enrich payloads, but cannot overwrite existing payload fields.
630
+ */
631
+ registerInterceptor<N extends IntentName, P>(intent: N | IntentCreator<N, P>, interceptor: EventInterceptor<N, P>, interceptorId?: string): string;
632
+ /**
633
+ * Remove a registered interceptor by registration id.
634
+ */
635
+ unregisterInterceptor(registrationId: string): boolean;
636
+ /**
637
+ * List registered interceptors.
638
+ */
639
+ listInterceptors(intent?: string): EventInterceptionInfo[];
640
+ /**
641
+ * Returns the history of published events (for observability and testing).
642
+ */
643
+ getHistory(): PublishedEventRecord[];
644
+ /**
645
+ * Clears publish history (useful in tests).
646
+ */
647
+ clearHistory(): void;
648
+ /**
649
+ * Returns the observability trace (publish, soft violations, handler errors).
650
+ */
651
+ getTrace(): TraceRecord[];
652
+ /**
653
+ * Clears the observability trace.
654
+ */
655
+ clearTrace(): void;
656
+ }
657
+
658
+ interface ObservabilityFlow {
659
+ from: string;
660
+ to: string;
661
+ }
662
+ interface ObservabilityDriftReport {
663
+ generatedAt: string;
664
+ declaredProductions: ObservabilityFlow[];
665
+ observedProductions: ObservabilityFlow[];
666
+ declaredButUnobserved: ObservabilityFlow[];
667
+ observedButUndeclared: ObservabilityFlow[];
668
+ unknownSources: ObservabilityFlow[];
669
+ unregisteredObservedSources: string[];
670
+ unregisteredObservedIntents: string[];
671
+ registeredButNeverObserved: string[];
672
+ }
673
+ interface ObservabilityReporter {
674
+ report(): ObservabilityDriftReport;
675
+ }
676
+ interface CreateObservabilityReporterOptions {
677
+ registry?: IntentRegistry;
678
+ eventBus?: EventBus;
679
+ graph?: DependencyGraph;
680
+ }
681
+
682
+ /**
683
+ * Machine-readable manifest types for agent and tooling consumption.
684
+ */
685
+
686
+ interface ArkManifestIntent {
687
+ name: string;
688
+ dependencies: string[];
689
+ productions: string[];
690
+ }
691
+ interface ArkManifestPolicy {
692
+ /** Stable slug for agents (derived from policy name). */
693
+ id: string;
694
+ name: string;
695
+ severity: 'hard' | 'soft';
696
+ tags?: string[];
697
+ description?: string;
698
+ owner?: string;
699
+ version?: string;
700
+ rationale?: string;
701
+ enforcementMode?: PolicyEnforcementMode;
702
+ deprecated?: boolean | string;
703
+ replacedBy?: string;
704
+ }
705
+ interface ArkManifestEntityLink {
706
+ entity: string;
707
+ emits?: string[];
708
+ consumes?: string[];
709
+ }
710
+ interface ArkManifestGraph {
711
+ nodes: GraphNode[];
712
+ edges: GraphEdge[];
713
+ }
714
+ interface ArkManifestArchitecture {
715
+ profile: string;
716
+ layers: ArchitectureLayer[];
717
+ rules: ArchitectureRule[];
718
+ }
719
+ interface ArkManifestProjection {
720
+ name: string;
721
+ sourceIntents: string[];
722
+ checkpoint?: ProjectionCheckpoint;
723
+ }
724
+ interface ArkManifestData {
725
+ /** Manifest schema version for agent/tooling compatibility. */
726
+ schemaVersion: string;
727
+ version: string;
728
+ exportedAt: string;
729
+ intents: ArkManifestIntent[];
730
+ relationships: IntentRelationship[];
731
+ policies: ArkManifestPolicy[];
732
+ entities: EntityMeta[];
733
+ graph: ArkManifestGraph;
734
+ architecture?: ArkManifestArchitecture;
735
+ projections: ArkManifestProjection[];
736
+ eventContracts: EventContract[];
737
+ observability?: ObservabilityDriftReport;
738
+ /** Cross-registry links for agent contract discovery. */
739
+ links: {
740
+ entityIntents: ArkManifestEntityLink[];
741
+ };
742
+ }
743
+ interface ArkManifest {
744
+ toJSON(): ArkManifestData;
745
+ }
746
+
747
+ /**
748
+ * Workflow / Saga support.
749
+ */
750
+
751
+ type SagaContext = Record<string, unknown>;
752
+ type SagaStatus = 'idle' | 'running' | 'compensating' | 'completed' | 'failed';
753
+ type WorkflowStatus = SagaStatus | 'waiting';
754
+ interface RetryPolicy {
755
+ attempts: number;
756
+ delayMs?: number;
757
+ }
758
+ interface WorkflowStep<P extends SagaContext = SagaContext> {
759
+ name: string;
760
+ onEvent?: IntentName;
761
+ retry?: RetryPolicy;
762
+ timeoutMs?: number;
763
+ /**
764
+ * Execute one step. The signal is aborted when `timeoutMs` elapses; implementations
765
+ * performing I/O must pass it to the underlying client for cooperative cancellation.
766
+ */
767
+ execute: (payload: P, bus: EventBus, signal: AbortSignal) => MaybePromise<Partial<P> | void>;
768
+ compensate?: (payload: P, bus: EventBus, error?: unknown) => MaybePromise<void>;
769
+ }
770
+ interface WorkflowStartTrigger<P extends SagaContext = SagaContext> {
771
+ intent: IntentName;
772
+ mapEventToPayload(event: DomainEvent<IntentName, unknown>): P;
773
+ }
774
+ interface WorkflowDefinition<P extends SagaContext = SagaContext> {
775
+ name: string;
776
+ steps: WorkflowStep<P>[];
777
+ startOn?: WorkflowStartTrigger<P>;
778
+ }
779
+ interface WorkflowSnapshot<P extends SagaContext = SagaContext> {
780
+ id: string;
781
+ version?: number;
782
+ workflowName: string;
783
+ status: WorkflowStatus;
784
+ context: P;
785
+ completedSteps: string[];
786
+ currentStep?: string;
787
+ failedStep?: string;
788
+ attempts: Record<string, number>;
789
+ startedAt: string;
790
+ updatedAt: string;
791
+ completedAt?: string;
792
+ error?: string;
793
+ ownerId?: string;
794
+ expiresAt?: string;
795
+ }
796
+ /**
797
+ * Pluggable saga/workflow snapshot store with OCC and leases.
798
+ *
799
+ * **Durability stance (R9):** Default `InMemoryWorkflowStore` is reference-only (not
800
+ * production durability). Inject a durable store for production. See
801
+ * `docs/production-hardening.md`.
802
+ */
803
+ interface WorkflowStore {
804
+ save<P extends SagaContext>(snapshot: WorkflowSnapshot<P>, tx?: unknown): MaybePromise<void>;
805
+ get<P extends SagaContext = SagaContext>(id: string, tx?: unknown): MaybePromise<WorkflowSnapshot<P> | undefined>;
806
+ list(workflowName?: string): MaybePromise<WorkflowSnapshot[]>;
807
+ claim?(workerId: string, timeoutMs: number, workflowName?: string): MaybePromise<WorkflowSnapshot | undefined>;
808
+ clear(): MaybePromise<void>;
809
+ }
810
+ interface WorkflowEngine {
811
+ register<P extends SagaContext>(definition: WorkflowDefinition<P>): void;
812
+ start<P extends SagaContext>(workflowName: string, initialPayload: P, options?: {
813
+ id?: string;
814
+ tx?: unknown;
815
+ }): Promise<WorkflowSnapshot<P>>;
816
+ resume<P extends SagaContext>(id: string, options?: {
817
+ tx?: unknown;
818
+ }): Promise<WorkflowSnapshot<P> | undefined>;
819
+ get<P extends SagaContext = SagaContext>(id: string, tx?: unknown): Promise<WorkflowSnapshot<P> | undefined>;
820
+ list(workflowName?: string): Promise<WorkflowSnapshot[]>;
821
+ }
822
+ interface CreateWorkflowEngineOptions {
823
+ store?: WorkflowStore;
824
+ auditTrail?: AuditTrail;
825
+ defaultRetry?: RetryPolicy;
826
+ }
827
+ interface SagaStep<P extends SagaContext = SagaContext> extends WorkflowStep<P> {
828
+ }
829
+ interface SagaDefinition<P extends SagaContext = SagaContext> {
830
+ name: string;
831
+ steps: SagaStep<P>[];
832
+ }
833
+ interface SagaInstance<P extends SagaContext = SagaContext> {
834
+ id: string;
835
+ definition: SagaDefinition<P>;
836
+ readonly status: SagaStatus;
837
+ readonly completedSteps: string[];
838
+ run(initialPayload: P): Promise<void>;
839
+ }
840
+
841
+ /**
842
+ * Serializable ArkRun information package (ADR 0023 D4).
843
+ * Tooling snapshot only — never a gate verdict. Strips factories, live
844
+ * instances, and input DTOs so inspectors cannot reach construction.
845
+ */
846
+ declare const ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION: "1.0";
847
+ declare const ARK_RUN_COMPONENT_LIFETIMES: readonly ["singleton", "transient"];
848
+ type ArkRunComponentLifetime = (typeof ARK_RUN_COMPONENT_LIFETIMES)[number];
849
+ type ArkRunExtendedInfo = {
850
+ label?: string;
851
+ architectureKind?: string;
852
+ tags?: string[];
853
+ group?: string;
854
+ metadata?: Record<string, string | number | boolean | null>;
855
+ };
856
+ type ArkRunInformationPackageComponent = {
857
+ id: string;
858
+ lifetime: ArkRunComponentLifetime;
859
+ uses: string[];
860
+ reactsTo: string[];
861
+ raises: string[];
862
+ sends: string[];
863
+ extendedInfo?: ArkRunExtendedInfo;
864
+ };
865
+ type DependencyInformationPackage = {
866
+ schemaVersion: typeof ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION;
867
+ kernelInstanceId: string;
868
+ components: ArkRunInformationPackageComponent[];
869
+ };
870
+ /**
871
+ * Build a JSON-serializable snapshot from unknown component records.
872
+ * Only id, lifetime, the four declaration lists, and optional extendedInfo
873
+ * survive — extra keys (factory, instance, DTO payloads) are dropped.
874
+ */
875
+ declare function buildDependencyInformationPackage(input: {
876
+ kernelInstanceId?: unknown;
877
+ components?: unknown;
878
+ }): DependencyInformationPackage;
879
+
880
+ /**
881
+ * ArkRun requestGraph slices (RN13). Tooling only — never a gate verdict.
882
+ * Consumes the information package so factories and live instances cannot leak.
883
+ */
884
+
885
+ declare const ARK_RUN_GRAPH_SCHEMA_VERSION: "1.0";
886
+ declare const ARK_RUN_GRAPH_DEFAULT_SLICE: "process";
887
+ declare const ARK_RUN_GRAPH_SLICES: readonly ["process", "technical"];
888
+ declare const ARK_RUN_GRAPH_NODE_KINDS: readonly ["component", "interaction"];
889
+ declare const ARK_RUN_GRAPH_PROCESS_EDGE_KINDS: readonly ["raises", "reactsTo", "sends"];
890
+ declare const ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS: readonly ["uses"];
891
+ type ArkRunGraphSlice = (typeof ARK_RUN_GRAPH_SLICES)[number];
892
+ type ArkRunGraphNodeKind = (typeof ARK_RUN_GRAPH_NODE_KINDS)[number];
893
+ type ArkRunGraphProcessEdgeKind = (typeof ARK_RUN_GRAPH_PROCESS_EDGE_KINDS)[number];
894
+ type ArkRunGraphTechnicalEdgeKind = (typeof ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS)[number];
895
+ type ArkRunGraphEdgeKind = ArkRunGraphProcessEdgeKind | ArkRunGraphTechnicalEdgeKind;
896
+ declare class InvalidArkRunGraphQueryError extends Error {
897
+ readonly option: 'slice' | 'degreesOfSeparation' | 'nodeIds' | 'include' | 'exclude';
898
+ constructor(option: InvalidArkRunGraphQueryError['option'], detail?: string);
899
+ }
900
+ type ArkRunGraphMatch = {
901
+ tokens: string[];
902
+ ids: string[];
903
+ labels: string[];
904
+ tags: string[];
905
+ groups: string[];
906
+ architectureKinds: string[];
907
+ };
908
+ type ArkRunGraphResolvedQuery = {
909
+ slice: ArkRunGraphSlice;
910
+ nodeIds: string[];
911
+ degreesOfSeparation: number | null;
912
+ include: ArkRunGraphMatch;
913
+ exclude: ArkRunGraphMatch;
914
+ };
915
+ type ArkRunGraphQuery = {
916
+ slice?: ArkRunGraphSlice;
917
+ nodeIds?: readonly string[];
918
+ degreesOfSeparation?: number;
919
+ include?: string | readonly string[] | ArkRunGraphMatchInput;
920
+ exclude?: string | readonly string[] | ArkRunGraphMatchInput;
921
+ };
922
+ type ArkRunGraphMatchInput = {
923
+ ids?: readonly string[];
924
+ labels?: readonly string[];
925
+ tags?: readonly string[];
926
+ groups?: readonly string[];
927
+ architectureKinds?: readonly string[];
928
+ };
929
+ type ArkRunGraphNode = {
930
+ id: string;
931
+ kind: ArkRunGraphNodeKind;
932
+ lifetime?: ArkRunComponentLifetime;
933
+ label?: string;
934
+ group?: string;
935
+ architectureKind?: string;
936
+ tags?: string[];
937
+ };
938
+ type ArkRunGraphEdge = {
939
+ from: string;
940
+ to: string;
941
+ kind: ArkRunGraphEdgeKind;
942
+ };
943
+ type ArkRunGraph = {
944
+ schemaVersion: typeof ARK_RUN_GRAPH_SCHEMA_VERSION;
945
+ kernelInstanceId: string;
946
+ slice: ArkRunGraphSlice;
947
+ query: ArkRunGraphResolvedQuery;
948
+ nodes: ArkRunGraphNode[];
949
+ edges: ArkRunGraphEdge[];
950
+ mermaid: string;
951
+ };
952
+ declare function closeArkRunGraphQuery(input?: unknown): ArkRunGraphResolvedQuery;
953
+ declare function arkRunGraphQueryFromSearchParams(params: {
954
+ slice?: string | null;
955
+ nodeIds?: string | null;
956
+ degreesOfSeparation?: string | null;
957
+ include?: string | null;
958
+ exclude?: string | null;
959
+ }): ArkRunGraphQuery;
960
+ /**
961
+ * Render a closed ArkRun graph as Mermaid flowchart text.
962
+ * Process slices are left-to-right; technical slices are top-down.
963
+ */
964
+ declare function formatArkRunGraphMermaid(graph: Pick<ArkRunGraph, 'slice' | 'nodes' | 'edges'>): string;
965
+ /**
966
+ * Slice the information package into a process or technical graph.
967
+ * Optional nodeIds + degreesOfSeparation keep a neighborhood; include/exclude
968
+ * are closed token or field queries. Never a score.
969
+ */
970
+ declare function requestArkRunGraph(pkgInput?: unknown, queryInput?: unknown): ArkRunGraph;
971
+
972
+ /**
973
+ * Closed ArkRun send-port vocabulary (ADR 0024).
974
+ * Pure plan only — delivery is Kernel. Not a durability claim.
975
+ */
976
+ declare const ARK_RUN_TRANSPORT_KINDS: readonly ["local", "localBlocking", "broker"];
977
+ type ArkRunTransportKind = (typeof ARK_RUN_TRANSPORT_KINDS)[number];
978
+ type ArkRunDeliveredVia = 'local' | 'broker';
979
+ /** Await local recording / adapter handoff before `send()` resolves. Not durability. */
980
+ declare const ARK_RUN_EPHEMERAL_DEFAULT = true;
981
+ declare class InvalidArkRunSendOptionError extends Error {
982
+ readonly option: 'transport' | 'ephemeral';
983
+ constructor(option: 'transport' | 'ephemeral');
984
+ }
985
+ type ArkRunSendPlan = {
986
+ transport: ArkRunTransportKind;
987
+ ephemeral: boolean;
988
+ deliveredVia: ArkRunDeliveredVia;
989
+ fallbackToLocal: boolean;
990
+ notifySubscribers: boolean;
991
+ awaitHandlers: boolean;
992
+ awaitHandoff: boolean;
993
+ };
994
+ type ArkRunSendPlanInput = {
995
+ transport?: unknown;
996
+ ephemeral?: unknown;
997
+ brokerBound: boolean;
998
+ };
999
+ declare function closedArkRunTransportKind(value: unknown): ArkRunTransportKind;
1000
+ declare function closedArkRunEphemeral(value: unknown): boolean;
1001
+ /**
1002
+ * Decide where a send goes and what `send()` waits for.
1003
+ * Missing broker → in-process local fallback (not cloud portability).
1004
+ */
1005
+ declare function resolveArkRunSendPlan(input: ArkRunSendPlanInput): ArkRunSendPlan;
1006
+
1007
+ /**
1008
+ * Closed ArkRun inspector bind + snapshot vocabulary (RN12).
1009
+ * Pure plan only — HTTP listen is Kernel. Not a durability claim.
1010
+ */
1011
+
1012
+ declare const ARK_RUN_INSPECTOR_SCHEMA_VERSION: "1.0";
1013
+ declare const ARK_RUN_INSPECTOR_DEFAULT_HOST = "127.0.0.1";
1014
+ declare const ARK_RUN_INSPECTOR_DEFAULT_PORT = 0;
1015
+ declare const ARK_RUN_INSPECTOR_SNAPSHOT_PATH = "/snapshot";
1016
+ declare const ARK_RUN_INSPECTOR_EVENTS_PATH = "/events";
1017
+ declare const ARK_RUN_INSPECTOR_GRAPH_PATH = "/graph";
1018
+ declare const ARK_RUN_INSPECTOR_SSE_EVENT = "snapshot";
1019
+ declare const ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK: "in-process-local";
1020
+ declare class ArkRunInspectorProductionError extends Error {
1021
+ constructor();
1022
+ }
1023
+ declare class ArkRunInspectorBindError extends Error {
1024
+ constructor(host: string);
1025
+ }
1026
+ type ArkRunInspectorBind = {
1027
+ host: string;
1028
+ port: number;
1029
+ };
1030
+ type ArkRunInspectorTransportFacts = {
1031
+ kinds: ArkRunTransportKind[];
1032
+ ephemeralDefault: boolean;
1033
+ brokerBound: boolean;
1034
+ cloudSdksShipped: false;
1035
+ fallback: typeof ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK;
1036
+ };
1037
+ type ArkRunInspectorSnapshot = {
1038
+ schemaVersion: typeof ARK_RUN_INSPECTOR_SCHEMA_VERSION;
1039
+ kernelInstanceId: string;
1040
+ bind: {
1041
+ host: string;
1042
+ port: number;
1043
+ loopback: true;
1044
+ };
1045
+ package: DependencyInformationPackage;
1046
+ transport: ArkRunInspectorTransportFacts;
1047
+ observability: unknown;
1048
+ };
1049
+ type ArkRunInspectorBindInput = {
1050
+ host?: unknown;
1051
+ port?: unknown;
1052
+ nodeEnv?: unknown;
1053
+ processNodeEnv?: unknown;
1054
+ };
1055
+ type ArkRunInspectorSnapshotInput = {
1056
+ kernelInstanceId?: unknown;
1057
+ host?: unknown;
1058
+ port?: unknown;
1059
+ package?: unknown;
1060
+ observability?: unknown;
1061
+ ephemeralDefault?: unknown;
1062
+ brokerBound?: unknown;
1063
+ };
1064
+ declare function isArkRunInspectorProductionEnv(nodeEnv: unknown): boolean;
1065
+ declare function isArkRunInspectorLoopbackHost(host: unknown): boolean;
1066
+ declare function resolveArkRunInspectorBind(input?: ArkRunInspectorBindInput): ArkRunInspectorBind;
1067
+ declare function arkRunInspectorUrl(host: string, port: number, path: string): string;
1068
+ declare function buildArkRunInspectorSnapshot(input?: ArkRunInspectorSnapshotInput): ArkRunInspectorSnapshot;
1069
+ declare function formatArkRunInspectorSseEvent(snapshot: unknown): string;
1070
+
1071
+ /**
1072
+ * Per-kernel managed-component registry. Factories stay private so the
1073
+ * information package cannot observe construction (ADR 0023 D4).
1074
+ */
1075
+
1076
+ type ArkRunRegisterOptions<T = unknown> = {
1077
+ id: string;
1078
+ lifetime?: ArkRunComponentLifetime;
1079
+ uses?: readonly string[];
1080
+ reactsTo?: readonly string[];
1081
+ raises?: readonly string[];
1082
+ sends?: readonly string[];
1083
+ extendedInfo?: ArkRunExtendedInfo;
1084
+ factory?: () => T;
1085
+ };
1086
+ type ArkRunRegistrationHandle = ArkRunInformationPackageComponent;
1087
+
1088
+ type ArkRunInspectorHandle = {
1089
+ host: string;
1090
+ port: number;
1091
+ url: string;
1092
+ snapshotUrl: string;
1093
+ eventsUrl: string;
1094
+ graphUrl: string;
1095
+ close(): Promise<void>;
1096
+ };
1097
+
1098
+ /**
1099
+ * Opt-in ArkRun inspector. HTTP is dynamically imported so constructing a
1100
+ * kernel does not bind a port or load `node:http`.
1101
+ */
1102
+
1103
+ type StartArkRunInspectorOptions = {
1104
+ host?: string;
1105
+ port?: number;
1106
+ /** Participates in the production veto together with process NODE_ENV. */
1107
+ nodeEnv?: string;
1108
+ sseIntervalMs?: number;
1109
+ };
1110
+ type ArkRunInspectorSource = {
1111
+ getInspectorSnapshot(bind: ArkRunInspectorBind): ArkRunInspectorSnapshot;
1112
+ requestGraph(query?: ArkRunGraphQuery): ArkRunGraph;
1113
+ };
1114
+ declare function startArkRunInspector(source: ArkRunInspectorSource, options?: StartArkRunInspectorOptions): Promise<ArkRunInspectorHandle>;
1115
+
1116
+ /**
1117
+ * ArkRun send ports (ADR 0024): local / localBlocking / broker-with-local-fallback.
1118
+ * Consumers inject broker adapters. This package does not ship cloud SDKs.
1119
+ * Fallback is in-process local delivery — not cloud portability.
1120
+ */
1121
+
1122
+ /**
1123
+ * Consumer-owned broker handoff. Resolving means the adapter accepted the
1124
+ * message, not that downstream consumers processed it. Not a durability claim.
1125
+ */
1126
+ interface ArkRunBrokerAdapter {
1127
+ send(event: DomainEvent): void | Promise<void>;
1128
+ }
1129
+ interface ArkRunSendOptions {
1130
+ transport?: ArkRunTransportKind;
1131
+ /** Override kernel `ephemeral`. Default remains true when both are omitted. */
1132
+ ephemeral?: boolean;
1133
+ source?: string;
1134
+ metadata?: Partial<EventMetadata>;
1135
+ }
1136
+ type ArkRunSendResult = ArkRunSendPlan;
1137
+
1138
+ interface ArkKernel {
1139
+ instanceId: string;
1140
+ profile: ArchitectureProfile;
1141
+ registry: IntentRegistry;
1142
+ graph: DependencyGraph;
1143
+ metadata: MetadataRegistry;
1144
+ auditTrail: AuditTrail;
1145
+ eventContracts: EventContractRegistry;
1146
+ eventBuffer: EventBufferStore;
1147
+ /** @deprecated Use eventBuffer. */
1148
+ outbox: EventBufferStore;
1149
+ projections: ProjectionRegistry;
1150
+ policyEngine: PolicyEngine;
1151
+ eventBus: EventBus;
1152
+ workflowEngine: WorkflowEngine;
1153
+ observability: ObservabilityReporter;
1154
+ publisher<N extends IntentName, P>(source: N | IntentCreator<N, P>): ArkRunPublisher;
1155
+ /**
1156
+ * One send site for local / localBlocking / broker (ADR 0024).
1157
+ * Missing broker falls back to in-process local delivery — not cloud portability.
1158
+ */
1159
+ send<N extends IntentName, P>(intent: IntentCreator<N, P>, payload: P, options?: ArkRunSendOptions): Promise<ArkRunSendResult>;
1160
+ /** Handle is declaration metadata only; the factory never leaves the registry. */
1161
+ register<T>(options: ArkRunRegisterOptions<T>): ArkRunRegistrationHandle;
1162
+ resolve<T = unknown>(id: string): T;
1163
+ resolveSingleton<T = unknown>(id: string): T;
1164
+ /** Tooling snapshot of ids, lifetime, and declarations — never construction. */
1165
+ getDependencyInformationPackage(): DependencyInformationPackage;
1166
+ /**
1167
+ * Process or technical graph slice of the information package.
1168
+ * Optional nodeIds, degreesOfSeparation, and include/exclude query.
1169
+ * Mermaid is a helper string on the result — never a score.
1170
+ */
1171
+ requestGraph(query?: ArkRunGraphQuery): ArkRunGraph;
1172
+ /**
1173
+ * Inspector snapshot (package + transport facts + observability). Never
1174
+ * includes factories, live instances, broker adapters, or input DTOs.
1175
+ */
1176
+ getInspectorSnapshot(bind?: ArkRunInspectorBind): ArkRunInspectorSnapshot;
1177
+ /**
1178
+ * Opt-in loopback inspector. Refuses NODE_ENV=production and public binds.
1179
+ * Loads HTTP only when called.
1180
+ */
1181
+ startInspector(options?: StartArkRunInspectorOptions): Promise<ArkRunInspectorHandle>;
1182
+ syncGraph(): void;
1183
+ manifest(): ArkManifest;
1184
+ }
1185
+ interface CreateArkKernelOptions {
1186
+ /**
1187
+ * When true (default), createArkKernel uses the hardened runtime defaults:
1188
+ * strict event contracts and hard observed-layer enforcement.
1189
+ * Set to false only for explicit migration/legacy paths.
1190
+ */
1191
+ strict?: boolean;
1192
+ profile?: ArchitectureProfile;
1193
+ policies?: Policy[];
1194
+ auditTrail?: AuditTrail;
1195
+ eventContracts?: EventContractRegistry;
1196
+ eventBuffer?: EventBufferStore;
1197
+ /** @deprecated Use eventBuffer. */
1198
+ outbox?: EventBufferStore;
1199
+ metadata?: MetadataRegistry;
1200
+ projections?: ProjectionRegistry;
1201
+ /**
1202
+ * Cap for in-memory event history, trace, and audit records.
1203
+ * Defaults to DEFAULT_MAX_HISTORY_SIZE (1000); oldest records are evicted
1204
+ * first. Pass Infinity for unbounded retention (pre-1.6 behavior).
1205
+ */
1206
+ maxHistorySize?: number;
1207
+ autoApplyProjections?: boolean;
1208
+ strictEventContracts?: boolean;
1209
+ requireKnownSource?: boolean;
1210
+ /**
1211
+ * Enforce observed producer→event layer flows against the profile at runtime.
1212
+ * Defaults to 'hard' when strict is true and 'off' when strict is false.
1213
+ */
1214
+ enforceObservedLayerFlow?: ObservedLayerFlowMode;
1215
+ instanceId?: string;
1216
+ /**
1217
+ * Consumer-injected broker adapter. Absence is normal: broker sends fall back
1218
+ * to in-process local delivery. Not cloud portability. This package does not
1219
+ * ship cloud SDKs.
1220
+ */
1221
+ broker?: ArkRunBrokerAdapter;
1222
+ /**
1223
+ * Await local bus recording / broker adapter handoff before `send()` resolves.
1224
+ * Default true (CLI, tests, short-lived workers). Not a durability claim.
1225
+ */
1226
+ ephemeral?: boolean;
1227
+ }
1228
+ interface ArkRunPublisher extends EventPublisher {
1229
+ send<N extends IntentName, P>(intent: IntentCreator<N, P>, payload: P, options?: Omit<ArkRunSendOptions, 'source'>): Promise<ArkRunSendResult>;
1230
+ }
1231
+ interface CreateArkKernelFromConfigOptions extends Omit<CreateArkKernelOptions, 'profile'> {
1232
+ /** Runtime profile name. Default: config.name or "ark.config.json". */
1233
+ profileName?: string;
1234
+ }
1235
+ type ArkKernelConfig = ArkCheckConfig;
1236
+
1237
+ export { ARK_RUN_INSPECTOR_GRAPH_PATH as $, type ArkKernel as A, type OutboxRecord as B, type CreateArkKernelOptions as C, type DefineIntentOptions as D, type EventContractRegistry as E, type ObservabilityDriftReport as F, type GraphEdge as G, ARK_RUN_COMPONENT_LIFETIMES as H, IntentRegistry as I, ARK_RUN_EPHEMERAL_DEFAULT as J, ARK_RUN_GRAPH_DEFAULT_SLICE as K, ARK_RUN_GRAPH_NODE_KINDS as L, type MetadataRegistry as M, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as N, type ObservabilityReporter as O, type ProjectionRegistry as P, ARK_RUN_GRAPH_SCHEMA_VERSION as Q, type ReadModelStore as R, type SagaContext as S, type TraceRecordType as T, ARK_RUN_GRAPH_SLICES as U, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as V, type WorkflowStore as W, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as X, ARK_RUN_INSPECTOR_DEFAULT_HOST as Y, ARK_RUN_INSPECTOR_DEFAULT_PORT as Z, ARK_RUN_INSPECTOR_EVENTS_PATH as _, type DependencyGraph as a, InvalidArkRunSendOptionError as a$, ARK_RUN_INSPECTOR_SCHEMA_VERSION as a0, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as a1, ARK_RUN_INSPECTOR_SSE_EVENT as a2, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as a3, ARK_RUN_TRANSPORT_KINDS as a4, type ArkManifestArchitecture as a5, type ArkManifestData as a6, type ArkManifestEntityLink as a7, type ArkManifestGraph as a8, type ArkManifestIntent as a9, type ArkRunInspectorSource as aA, type ArkRunInspectorTransportFacts as aB, type ArkRunPublisher as aC, type ArkRunRegisterOptions as aD, type ArkRunRegistrationHandle as aE, type ArkRunSendOptions as aF, type ArkRunSendPlan as aG, type ArkRunSendPlanInput as aH, type ArkRunSendResult as aI, type ArkRunTransportKind as aJ, type AuditRecordInput as aK, type AuditRecordType as aL, type DependencyInformationPackage as aM, type EntityMeta as aN, type EventContractIssue as aO, type EventHandler as aP, type EventInterceptionInfo as aQ, type EventInterceptor as aR, type EventInterceptorContext as aS, type EventPayloadPatch as aT, type EventPayloadSchema as aU, type EventPublisher as aV, type EventSchemaField as aW, type EventSchemaFieldType as aX, type FieldMeta as aY, type GraphNode as aZ, InvalidArkRunGraphQueryError as a_, type ArkManifestPolicy as aa, type ArkManifestProjection as ab, type ArkRunBrokerAdapter as ac, type ArkRunComponentLifetime as ad, type ArkRunDeliveredVia as ae, type ArkRunExtendedInfo as af, type ArkRunGraph as ag, type ArkRunGraphEdge as ah, type ArkRunGraphEdgeKind as ai, type ArkRunGraphMatch as aj, type ArkRunGraphMatchInput as ak, type ArkRunGraphNode as al, type ArkRunGraphNodeKind as am, type ArkRunGraphProcessEdgeKind as an, type ArkRunGraphQuery as ao, type ArkRunGraphResolvedQuery as ap, type ArkRunGraphSlice as aq, type ArkRunGraphTechnicalEdgeKind as ar, type ArkRunInformationPackageComponent as as, type ArkRunInspectorBind as at, ArkRunInspectorBindError as au, type ArkRunInspectorBindInput as av, type ArkRunInspectorHandle as aw, ArkRunInspectorProductionError as ax, type ArkRunInspectorSnapshot as ay, type ArkRunInspectorSnapshotInput as az, type AuditStore as b, type ObservabilityFlow as b0, type ObservedLayerFlowMode as b1, type OutboxStore as b2, type PolicyEvaluationResult as b3, type ProjectionCheckpoint as b4, type ProjectionDefinition as b5, type PublishedEventRecord as b6, type RetryPolicy as b7, type SagaStatus as b8, type SagaStep as b9, type StartArkRunInspectorOptions as ba, type TraceSink as bb, type Unsubscribe as bc, type WorkflowDefinition as bd, type WorkflowStatus as be, type WorkflowStep as bf, arkRunGraphQueryFromSearchParams as bg, arkRunInspectorUrl as bh, buildArkRunInspectorSnapshot as bi, buildDependencyInformationPackage as bj, closeArkRunGraphQuery as bk, closedArkRunEphemeral as bl, closedArkRunTransportKind as bm, formatArkRunGraphMermaid as bn, formatArkRunInspectorSseEvent as bo, isArkRunInspectorLoopbackHost as bp, isArkRunInspectorProductionEnv as bq, requestArkRunGraph as br, resolveArkRunInspectorBind as bs, resolveArkRunSendPlan as bt, startArkRunInspector as bu, 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 ArkKernelConfig as w, type CreateArkKernelFromConfigOptions as x, type TraceRecord as y, type OutboxStatus as z };