arkgate 2.1.0

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 (64) hide show
  1. package/CHANGELOG.md +1249 -0
  2. package/LICENSE +21 -0
  3. package/README.md +218 -0
  4. package/SECURITY.md +39 -0
  5. package/bin/ark-check.mjs +5204 -0
  6. package/bin/ark-mcp.mjs +898 -0
  7. package/bin/ark-shared.mjs +1520 -0
  8. package/bin/ark.mjs +491 -0
  9. package/dist/eslint/index.cjs +222 -0
  10. package/dist/eslint/index.cjs.map +1 -0
  11. package/dist/eslint/index.d.cts +42 -0
  12. package/dist/eslint/index.d.ts +40 -0
  13. package/dist/eslint/index.js +193 -0
  14. package/dist/eslint/index.js.map +1 -0
  15. package/dist/index.cjs +3080 -0
  16. package/dist/index.cjs.map +1 -0
  17. package/dist/index.d.cts +577 -0
  18. package/dist/index.d.ts +577 -0
  19. package/dist/index.js +2998 -0
  20. package/dist/index.js.map +1 -0
  21. package/dist/nestjs/index.cjs +2332 -0
  22. package/dist/nestjs/index.cjs.map +1 -0
  23. package/dist/nestjs/index.d.cts +22 -0
  24. package/dist/nestjs/index.d.ts +22 -0
  25. package/dist/nestjs/index.js +2308 -0
  26. package/dist/nestjs/index.js.map +1 -0
  27. package/dist/types-DpdVN7Lm.d.cts +1023 -0
  28. package/dist/types-DpdVN7Lm.d.ts +1023 -0
  29. package/docs/agent-guide.md +490 -0
  30. package/docs/ai-gates.md +337 -0
  31. package/docs/ark-check-example.json +87 -0
  32. package/docs/assets/ark-write-gate.svg +28 -0
  33. package/docs/brownfield-adoption.md +87 -0
  34. package/docs/demos/01-write-gate-self-correction.md +74 -0
  35. package/docs/demos/02-brownfield-baseline-adoption.md +71 -0
  36. package/docs/demos/03-copilot-autopilot.md +83 -0
  37. package/docs/enthusiast/README.md +62 -0
  38. package/docs/enthusiast/explanation-application-shape.md +29 -0
  39. package/docs/enthusiast/how-to-agent-gates.md +36 -0
  40. package/docs/enthusiast/how-to-gallery-starter.md +27 -0
  41. package/docs/enthusiast/how-to-pick-shape.md +45 -0
  42. package/docs/enthusiast/how-to-policy-pack.md +37 -0
  43. package/docs/enthusiast/reference-archetypes.md +36 -0
  44. package/docs/enthusiast/reference-commands.md +50 -0
  45. package/docs/enthusiast/tutorial-first-project.md +86 -0
  46. package/docs/production-hardening.md +59 -0
  47. package/package.json +125 -0
  48. package/server.json +39 -0
  49. package/templates/architecture-playbook.json +339 -0
  50. package/templates/policy-packs/enthusiast-feature-sliced.json +20 -0
  51. package/templates/policy-packs/enthusiast-hexagonal.json +18 -0
  52. package/templates/policy-packs/enthusiast-layered.json +18 -0
  53. package/templates/policy-packs/enthusiast-monorepo.json +18 -0
  54. package/templates/skills/ark-adopt.md +103 -0
  55. package/templates/skills/ark-architect.md +90 -0
  56. package/templates/skills/ark-autopilot.md +95 -0
  57. package/templates/skills/ark-contract.md +98 -0
  58. package/templates/skills/ark-coverage.md +96 -0
  59. package/templates/skills/ark-explain.md +78 -0
  60. package/templates/skills/ark-fix.md +96 -0
  61. package/templates/skills/ark-loop.md +69 -0
  62. package/templates/skills/ark-place.md +68 -0
  63. package/templates/skills/ark-runtime.md +62 -0
  64. package/templates/skills/ark-upgrade.md +109 -0
@@ -0,0 +1,577 @@
1
+ import { I as IntentRegistry, a as IntentName, D as DefineIntentOptions, b as IntentCreator, P as PolicyViolation, c as PolicySeverity, d as PolicyEnforcementMode, e as Policy, C as CreateArchitectureProfileOptions, A as ArchitectureProfile, f as ArkCheckConfig, g as CreateArchitectureProfileFromArkConfigOptions, h as CreateElevenLayerArkConfigOptions, i as DependencyGraph, G as GraphEdge, j as IntentRelationship, k as AuditStore, l as AuditRecord, m as AuditQuery, n as CreateAuditTrailOptions, o as AuditTrail, E as EventContractRegistry, p as EventContract, q as DomainEvent, r as EventContractValidationResult, O as OutboxStore, s as OutboxRecord, t as OutboxStatus, u as EventBusOptions, v as EventBus, w as CreateObservabilityReporterOptions, x as ObservabilityReporter, M as MetadataRegistry, R as ReadModelStore, y as CreateProjectionRegistryOptions, z as ProjectionRegistry, B as PolicyEngine, F as ArkManifest, W as WorkflowStore, S as SagaContext, H as WorkflowSnapshot, J as SagaDefinition, K as CreateWorkflowEngineOptions, L as SagaInstance, N as WorkflowEngine, Q as CreateArkKernelOptions, T as ArkKernel, U as ArkKernelConfig, V as CreateArkKernelFromConfigOptions, X as TraceRecordType, Y as TraceRecord, Z as ObservabilityDriftReport } from './types-DpdVN7Lm.cjs';
2
+ export { _ as ArchitectureLayer, $ as ArchitectureLayerConfig, a0 as ArchitectureRule, a1 as ArkManifestArchitecture, a2 as ArkManifestData, a3 as ArkManifestEntityLink, a4 as ArkManifestGraph, a5 as ArkManifestIntent, a6 as ArkManifestPolicy, a7 as ArkManifestProjection, a8 as AuditRecordInput, a9 as AuditRecordType, aa as CorrelationId, ab as EntityMeta, ac as EventContractIssue, ad as EventHandler, ae as EventInterceptionInfo, af as EventInterceptor, ag as EventInterceptorContext, ah as EventMetadata, ai as EventPayloadPatch, aj as EventPayloadSchema, ak as EventPublisher, al as EventSchemaField, am as EventSchemaFieldType, an as FieldMeta, ao as GraphNode, ap as IntentRelationshipKind, aq as ObservabilityFlow, ar as ObservedLayerFlowMode, as as PolicyEvaluationResult, at as ProjectionCheckpoint, au as ProjectionDefinition, av as PublishedEventRecord, aw as RetryPolicy, ax as SagaStatus, ay as SagaStep, az as TraceSink, aA as Unsubscribe, aB as WorkflowDefinition, aC as WorkflowStatus, aD as WorkflowStep } from './types-DpdVN7Lm.cjs';
3
+
4
+ /** ArkGate library version — single source of truth. */
5
+ declare const version = "2.1.0";
6
+
7
+ /**
8
+ * defineIntent
9
+ *
10
+ * The primary ergonomic function for declaring semantic intents.
11
+ *
12
+ * Uses a default shared registry for convenience, while still allowing
13
+ * isolated registries via `createIntentRegistry()`.
14
+ *
15
+ * Intents are the core of Ark's governance model. They give every
16
+ * architectural concept (domain events, use cases, adapter operations, workflows)
17
+ * an explicit, namespaced, machine-readable identity.
18
+ */
19
+
20
+ /**
21
+ * Define a new semantic intent.
22
+ *
23
+ * This is the main entry point most users (and AI generators) will use.
24
+ *
25
+ * @example
26
+ * ```ts
27
+ * // Domain event
28
+ * const OrderPlaced = defineIntent<'Domain.Order.OrderPlaced', {
29
+ * orderId: string;
30
+ * amount: number;
31
+ * }>('Domain.Order.OrderPlaced');
32
+ *
33
+ * const event = OrderPlaced({ orderId: 'o-42', amount: 99.5 });
34
+ *
35
+ * // Application operation that declares a dependency at definition time
36
+ * const ConfirmOrder = defineIntent<'Application.ConfirmOrder', { orderId: string }>(
37
+ * 'Application.ConfirmOrder',
38
+ * { dependsOn: ['Domain.Order.OrderPlaced'] }
39
+ * );
40
+ * ```
41
+ *
42
+ * @param name - Unique semantic name. Recommended convention:
43
+ * - `Domain.*` for domain concepts and events
44
+ * - `Application.*` for use cases / orchestration
45
+ * - `Adapter.*` for external integrations
46
+ * - `Workflow.*` for sagas and long-running processes
47
+ * @param options - Optional initial relationship declarations (`dependsOn`, `produces`)
48
+ */
49
+ declare function defineIntent<N extends IntentName, P = unknown>(name: N, options?: DefineIntentOptions): IntentCreator<N, P>;
50
+ /**
51
+ * Create an isolated IntentRegistry.
52
+ * Useful for testing, multiple bounded contexts, or advanced governance setups.
53
+ */
54
+ declare function createIntentRegistry(): IntentRegistry;
55
+ /**
56
+ * The default registry backing the top-level `defineIntent` calls.
57
+ * You can inspect it or use it directly if needed.
58
+ */
59
+ declare const defaultIntentRegistry: IntentRegistry;
60
+
61
+ /**
62
+ * Runtime validation for semantic intent naming conventions.
63
+ */
64
+ interface IntentNameValidation {
65
+ valid: boolean;
66
+ reason?: string;
67
+ }
68
+ /**
69
+ * Validate that an intent name follows Ark naming conventions.
70
+ */
71
+ declare function validateIntentName(name: string): IntentNameValidation;
72
+
73
+ /**
74
+ * Typed error thrown when hard policies are violated.
75
+ */
76
+
77
+ declare class PolicyViolationError extends Error {
78
+ readonly violations: PolicyViolation[];
79
+ constructor(violations: PolicyViolation[]);
80
+ }
81
+
82
+ /**
83
+ * definePolicy
84
+ *
85
+ * Factory function to create architectural policies in a declarative way.
86
+ */
87
+
88
+ interface DefinePolicyOptions<Context = unknown> {
89
+ name: string;
90
+ severity?: PolicySeverity;
91
+ tags?: readonly string[];
92
+ owner?: string;
93
+ version?: string;
94
+ rationale?: string;
95
+ enforcementMode?: PolicyEnforcementMode;
96
+ deprecated?: boolean | string;
97
+ replacedBy?: string;
98
+ check: (context: Context) => boolean | PolicyViolation | PolicyViolation[];
99
+ }
100
+ /**
101
+ * Creates a Policy from a declarative configuration.
102
+ *
103
+ * The provided `check` function is called as-is. The PolicyEngine is responsible
104
+ * for normalizing results (booleans, single violations, arrays) into a consistent
105
+ * set of PolicyViolation objects.
106
+ *
107
+ * @example
108
+ * ```ts
109
+ * const noDomainToInfra = definePolicy({
110
+ * name: 'Domain must not depend on infrastructure',
111
+ * severity: 'hard',
112
+ * check: (ctx) => {
113
+ * const violations: PolicyViolation[] = [];
114
+ * // ... logic using ctx.registry.getAllRelationships()
115
+ * return violations.length > 0 ? violations : true;
116
+ * }
117
+ * });
118
+ * ```
119
+ */
120
+ declare function definePolicy<Context = unknown>(options: DefinePolicyOptions<Context>): Policy<Context>;
121
+
122
+ declare function createArchitectureProfile(options: CreateArchitectureProfileOptions): ArchitectureProfile;
123
+ declare function createArchitectureProfileFromArkConfig(config: ArkCheckConfig, options?: CreateArchitectureProfileFromArkConfigOptions): ArchitectureProfile;
124
+ declare const elevenLayerProfile: ArchitectureProfile;
125
+ declare function createElevenLayerArkConfig(options?: CreateElevenLayerArkConfigOptions): ArkCheckConfig;
126
+
127
+ /**
128
+ * DependencyGraph implementation.
129
+ *
130
+ * Collects declared and observed relationships.
131
+ * Generates Mermaid diagrams and JSON.
132
+ * Supports simple violation detection via rule functions.
133
+ */
134
+
135
+ declare function createDependencyGraph(): DependencyGraph;
136
+
137
+ /**
138
+ * Bridge IntentRegistry relationships into a DependencyGraph.
139
+ */
140
+
141
+ interface SyncRegistryOptions {
142
+ /** Skip edges whose target intent is not registered (default: false). */
143
+ requireRegisteredTargets?: boolean;
144
+ }
145
+ /**
146
+ * Sync declared intent relationships from a registry into a dependency graph.
147
+ *
148
+ * - `dependsOn` → `declared` edges
149
+ * - `produces` → `produces` edges
150
+ */
151
+ declare function syncRegistryToGraph(registry: IntentRegistry, graph: DependencyGraph, options?: SyncRegistryOptions): void;
152
+
153
+ /**
154
+ * Built-in architectural policy helpers.
155
+ */
156
+
157
+ interface LayerFlowRule {
158
+ from: string;
159
+ to: string;
160
+ allowed: boolean;
161
+ message?: string;
162
+ }
163
+ interface LayerPolicyOptions {
164
+ name?: string;
165
+ severity?: 'hard' | 'soft';
166
+ /** Prefix rules — e.g. { from: 'Domain', to: 'Adapter', allowed: false } */
167
+ rules: LayerFlowRule[];
168
+ resolveLayer?: (name: string) => string | undefined;
169
+ }
170
+ /**
171
+ * Create a policy that enforces layer-crossing rules on graph edges or intent relationships.
172
+ */
173
+ declare function defineLayerPolicy<Context extends {
174
+ edges?: GraphEdge[];
175
+ relationships?: IntentRelationship[];
176
+ }>(options: LayerPolicyOptions): Policy<Context>;
177
+ /** True when a policy requires graph/registry context to enforce layer rules. */
178
+ declare function isLayerPolicy(policy: Policy): boolean;
179
+ /** Preset architectural policy factories. */
180
+ declare const architecturalPolicies: {
181
+ /**
182
+ * @deprecated Use cleanArchitectureMatrix() for full layer rules.
183
+ * Blocks Domain → Adapter declared dependencies only.
184
+ */
185
+ layerIsolation(): Policy<{
186
+ edges?: GraphEdge[];
187
+ relationships?: IntentRelationship[];
188
+ }>;
189
+ /**
190
+ * Clean-architecture dependency matrix (declared dependsOn / declared edges only).
191
+ * Does not block observed event flows (Domain events consumed by Application).
192
+ */
193
+ cleanArchitectureMatrix(): Policy<{
194
+ edges?: GraphEdge[];
195
+ relationships?: IntentRelationship[];
196
+ }>;
197
+ };
198
+ declare function defineArchitectureProfilePolicy<Context extends {
199
+ edges?: GraphEdge[];
200
+ relationships?: IntentRelationship[];
201
+ }>(profile: ArchitectureProfile, options?: Omit<LayerPolicyOptions, 'rules' | 'resolveLayer'>): Policy<Context>;
202
+
203
+ declare class InMemoryAuditStore implements AuditStore {
204
+ private readonly maxRecords?;
205
+ private readonly records;
206
+ constructor(maxRecords?: number | undefined);
207
+ append(record: AuditRecord): void;
208
+ query(query?: AuditQuery): AuditRecord[];
209
+ clear(): void;
210
+ }
211
+ declare function createAuditTrail(options?: CreateAuditTrailOptions): AuditTrail;
212
+
213
+ declare class EventContractRegistryImpl implements EventContractRegistry {
214
+ private readonly contracts;
215
+ register(contract: EventContract): void;
216
+ get(intent: string, version?: string): EventContract | undefined;
217
+ list(intent?: string): EventContract[];
218
+ validate(event: DomainEvent): EventContractValidationResult;
219
+ clear(): void;
220
+ private key;
221
+ }
222
+ declare function createEventContractRegistry(): EventContractRegistry;
223
+
224
+ declare class InMemoryOutboxStore implements OutboxStore {
225
+ private readonly records;
226
+ enqueue(event: DomainEvent): Promise<OutboxRecord>;
227
+ markDispatched(id: string): Promise<void>;
228
+ markFailed(id: string, error: unknown): Promise<void>;
229
+ list(status?: OutboxStatus): Promise<OutboxRecord[]>;
230
+ clear(): Promise<void>;
231
+ }
232
+
233
+ /**
234
+ * EventBus implementation.
235
+ *
236
+ * Core publish/subscribe mechanics with:
237
+ * - Intent-aware typing via creators
238
+ * - Automatic metadata enrichment
239
+ * - Full publish history for observability
240
+ * - Strict registry validation (opt-in by default when registry provided)
241
+ */
242
+
243
+ declare function createEventBus<Context = unknown>(options?: EventBusOptions<Context>): EventBus;
244
+
245
+ /**
246
+ * Helpers for building policy evaluation context on event publish.
247
+ */
248
+
249
+ /**
250
+ * Standard context for policies evaluated during event publish.
251
+ * Includes the event plus optional registry relationships and graph edges
252
+ * so layer policies (e.g. architecturalPolicies.layerIsolation) can run.
253
+ */
254
+ interface PublishPolicyContext {
255
+ event: DomainEvent;
256
+ relationships?: IntentRelationship[];
257
+ edges?: GraphEdge[];
258
+ }
259
+ interface GraphPolicyContext {
260
+ relationships?: IntentRelationship[];
261
+ edges?: GraphEdge[];
262
+ }
263
+ interface BuildPublishPolicyContextOptions {
264
+ intentRegistry?: IntentRegistry;
265
+ dependencyGraph?: DependencyGraph;
266
+ }
267
+ /**
268
+ * Build a getPolicyContext function that feeds registry + graph data to policies.
269
+ *
270
+ * @example
271
+ * ```ts
272
+ * const bus = createEventBus({
273
+ * intentRegistry: registry,
274
+ * dependencyGraph: graph,
275
+ * policies: [architecturalPolicies.layerIsolation()],
276
+ * });
277
+ * ```
278
+ */
279
+ declare function buildPublishPolicyContext(options: BuildPublishPolicyContextOptions): (event: DomainEvent) => PublishPolicyContext;
280
+ declare function definePublishPolicy(options: DefinePolicyOptions<PublishPolicyContext>): Policy<PublishPolicyContext>;
281
+
282
+ /**
283
+ * Event bus governance errors.
284
+ */
285
+ declare class UnregisteredIntentError extends Error {
286
+ readonly intentName: string;
287
+ constructor(intentName: string);
288
+ }
289
+ declare class InvalidIntentNameError extends Error {
290
+ readonly intentName: string;
291
+ readonly reason: string;
292
+ constructor(intentName: string, reason: string);
293
+ }
294
+ declare class LayerPolicyContextError extends Error {
295
+ constructor();
296
+ }
297
+ declare class EventContractViolationError extends Error {
298
+ readonly intentName: string;
299
+ readonly issues: unknown[];
300
+ constructor(intentName: string, issues: unknown[]);
301
+ }
302
+ declare class UnknownEventSourceError extends Error {
303
+ readonly intentName: string;
304
+ readonly source?: string;
305
+ constructor(intentName: string, source?: string);
306
+ }
307
+ declare class SourceMetadataOverrideError extends Error {
308
+ readonly boundSource: string;
309
+ readonly attemptedSource: string;
310
+ constructor(boundSource: string, attemptedSource: string);
311
+ }
312
+ /**
313
+ * Thrown when the OBSERVED producer→event flow crosses a forbidden layer boundary
314
+ * under `enforceObservedLayerFlow: 'hard'`. Unlike declared-model policy errors, this
315
+ * reflects what the running system actually did at publish time.
316
+ */
317
+ declare class ObservedLayerFlowViolationError extends Error {
318
+ readonly source: string;
319
+ readonly intentName: string;
320
+ readonly fromLayer: string;
321
+ readonly toLayer: string;
322
+ constructor(source: string, intentName: string, fromLayer: string, toLayer: string, message?: string);
323
+ }
324
+
325
+ declare function createObservabilityReporter(options: CreateObservabilityReporterOptions): ObservabilityReporter;
326
+
327
+ /**
328
+ * Basic MetadataRegistry implementation.
329
+ */
330
+
331
+ declare function createMetadataRegistry(): MetadataRegistry;
332
+
333
+ declare class InMemoryReadModelStore implements ReadModelStore {
334
+ private readonly states;
335
+ load<State = unknown>(name: string): State | undefined;
336
+ save<State = unknown>(name: string, state: State): void;
337
+ clear(name?: string): void;
338
+ }
339
+ declare function createProjectionRegistry(options?: CreateProjectionRegistryOptions): ProjectionRegistry;
340
+
341
+ /** Current Ark manifest JSON schema version. */
342
+ declare const MANIFEST_SCHEMA_VERSION = "1.0";
343
+
344
+ /**
345
+ * Aggregates kernel registries into a single machine-readable manifest.
346
+ */
347
+
348
+ interface CreateArkManifestOptions {
349
+ registry?: IntentRegistry;
350
+ policyEngine?: PolicyEngine;
351
+ metadata?: MetadataRegistry;
352
+ graph?: DependencyGraph;
353
+ profile?: ArchitectureProfile;
354
+ projections?: ProjectionRegistry;
355
+ eventContracts?: EventContractRegistry;
356
+ observability?: ObservabilityReporter;
357
+ }
358
+ /**
359
+ * Create a machine-readable snapshot of the current architectural contract.
360
+ * Intended for AI agents, codegen tools, and documentation generators.
361
+ */
362
+ declare function createArkManifest(options?: CreateArkManifestOptions): ArkManifest;
363
+
364
+ /**
365
+ * In-process workflow engine with durable-store seams.
366
+ */
367
+
368
+ declare class InMemoryWorkflowStore implements WorkflowStore {
369
+ private readonly snapshots;
370
+ save<P extends SagaContext>(snapshot: WorkflowSnapshot<P>): void;
371
+ get<P extends SagaContext = SagaContext>(id: string): WorkflowSnapshot<P> | undefined;
372
+ list(workflowName?: string): WorkflowSnapshot[];
373
+ clear(): void;
374
+ }
375
+ declare function createWorkflowEngine(bus: EventBus, options?: CreateWorkflowEngineOptions): WorkflowEngine;
376
+ declare function createSaga<P extends SagaContext = SagaContext>(def: SagaDefinition<P>, bus: EventBus, options?: CreateWorkflowEngineOptions & {
377
+ id?: string;
378
+ }): SagaInstance<P>;
379
+
380
+ /**
381
+ * Default cap for in-memory history, trace, and audit records. Without a cap a
382
+ * long-running process grows without bound on every publish. Pass
383
+ * `maxHistorySize: Infinity` to explicitly opt back into unbounded retention.
384
+ */
385
+ declare const DEFAULT_MAX_HISTORY_SIZE = 1000;
386
+ declare function createArkKernel(options?: CreateArkKernelOptions): ArkKernel;
387
+ declare function createStrictArkKernel(options?: CreateArkKernelOptions): ArkKernel;
388
+ declare function createArkKernelFromConfig(config: ArkKernelConfig, options?: CreateArkKernelFromConfigOptions): ArkKernel;
389
+ declare function createStrictArkKernelFromConfig(config: ArkKernelConfig, options?: CreateArkKernelFromConfigOptions): ArkKernel;
390
+ declare function createLenientArkKernelFromConfig(config: ArkKernelConfig, options?: CreateArkKernelFromConfigOptions): ArkKernel;
391
+ declare function createLenientArkKernel(options?: CreateArkKernelOptions): ArkKernel;
392
+
393
+ interface ArkTestSnapshot {
394
+ events: DomainEvent[];
395
+ traces: TraceRecord[];
396
+ audit: AuditRecord[];
397
+ outbox: OutboxRecord[];
398
+ observability: ObservabilityDriftReport;
399
+ }
400
+ interface ArkTestHarness {
401
+ events(intent?: string): DomainEvent[];
402
+ traces(type?: TraceRecordType): TraceRecord[];
403
+ audit(query?: AuditQuery): Promise<AuditRecord[]>;
404
+ outbox(status?: OutboxStatus): Promise<OutboxRecord[]>;
405
+ observability(): ObservabilityDriftReport;
406
+ snapshot(): Promise<ArkTestSnapshot>;
407
+ clear(): Promise<void>;
408
+ }
409
+
410
+ declare function createArkTestHarness(kernel: ArkKernel): ArkTestHarness;
411
+
412
+ /**
413
+ * Ports & Adapters basic contracts.
414
+ */
415
+ interface Port<T = unknown> {
416
+ readonly name: string;
417
+ readonly ownerLayer?: string;
418
+ readonly intent?: IntentName;
419
+ readonly allowedAdapters?: string[];
420
+ readonly __port?: T;
421
+ }
422
+ interface Adapter<T = unknown> {
423
+ readonly name?: string;
424
+ readonly layer?: string;
425
+ readonly intent?: IntentName;
426
+ readonly port: Port<T>;
427
+ readonly impl: T;
428
+ }
429
+ interface DefinePortOptions {
430
+ ownerLayer?: string;
431
+ intent?: IntentName;
432
+ allowedAdapters?: string[];
433
+ }
434
+ interface CreateAdapterOptions {
435
+ name?: string;
436
+ layer?: string;
437
+ intent?: IntentName;
438
+ requiredKeys?: string[];
439
+ }
440
+ /**
441
+ * Simple contract checker (duck typing + optional required keys).
442
+ */
443
+ type ContractCheckResult = {
444
+ ok: true;
445
+ } | {
446
+ ok: false;
447
+ missing: string[];
448
+ };
449
+ interface AdapterGovernanceIssue {
450
+ ruleId: 'ADAPTER_NOT_ALLOWED_FOR_PORT';
451
+ message: string;
452
+ port: string;
453
+ adapter?: string;
454
+ }
455
+ type AdapterGovernanceResult = {
456
+ ok: true;
457
+ issues: [];
458
+ } | {
459
+ ok: false;
460
+ issues: AdapterGovernanceIssue[];
461
+ };
462
+
463
+ /**
464
+ * Ports and Adapters utilities.
465
+ *
466
+ * definePort + createAdapter with basic runtime contract validation.
467
+ */
468
+
469
+ declare function definePort<T = unknown>(name: string, options?: DefinePortOptions): Port<T>;
470
+ declare function createAdapter<T>(port: Port<T>, impl: T, requiredKeysOrOptions?: string[] | CreateAdapterOptions, adapterOptions?: CreateAdapterOptions): Adapter<T>;
471
+ declare function checkContract(impl: unknown, requiredKeys?: string[]): ContractCheckResult;
472
+ declare function checkAdapterGovernance(adapter: Adapter): AdapterGovernanceResult;
473
+
474
+ /**
475
+ * AI Code Gate (basic).
476
+ *
477
+ * Allows validation of generated source code against the defined architecture.
478
+ */
479
+ interface AICodeGateViolation {
480
+ /** Stable rule identifier for agents and CI pipelines. */
481
+ ruleId: string;
482
+ /** @deprecated Use ruleId — kept for backward compatibility. */
483
+ code: string;
484
+ message: string;
485
+ line?: number;
486
+ suggestion?: string;
487
+ source?: string;
488
+ filePath?: string;
489
+ target?: string;
490
+ fromLayer?: string;
491
+ toLayer?: string;
492
+ details?: unknown;
493
+ }
494
+ /** Extension point for external analyzers (AST, semantic, etc.). */
495
+ interface AIGateExtension<Context = unknown> {
496
+ readonly name: string;
497
+ analyze(source: string, context?: Context): AICodeGateViolation[];
498
+ }
499
+ interface AICodeGateContext {
500
+ filePath?: string;
501
+ agentId?: string;
502
+ layer?: string;
503
+ [key: string]: unknown;
504
+ }
505
+ interface AICodeGateResult {
506
+ valid: boolean;
507
+ violations: AICodeGateViolation[];
508
+ }
509
+ interface AICodeGate<Context = AICodeGateContext> {
510
+ validate(source: string, context?: Context): AICodeGateResult;
511
+ }
512
+
513
+ /**
514
+ * Basic AI Code Gate implementation.
515
+ *
516
+ * Uses simple string heuristics + registered intent names to detect obvious
517
+ * architectural violations in generated code (e.g. direct infra imports from domain).
518
+ * Not a full static analyzer — documented limitation.
519
+ */
520
+
521
+ interface AICodeGatePolicyContext<Context = AICodeGateContext> {
522
+ source: string;
523
+ context?: Context;
524
+ }
525
+ interface AICodeGateOptions<Context = AICodeGateContext> {
526
+ policies?: Policy<AICodeGatePolicyContext<Context>>[];
527
+ intents?: Array<string | Pick<IntentCreator<IntentName, unknown>, 'name'>>;
528
+ /**
529
+ * Additional forbidden patterns (regex or strings).
530
+ */
531
+ forbiddenPatterns?: Array<string | RegExp>;
532
+ /**
533
+ * External analyzer extensions (type-only contract; plug in AST tools later).
534
+ */
535
+ extensions?: AIGateExtension<Context>[];
536
+ /**
537
+ * Optional architecture profile for layer-aware generated-code checks.
538
+ * When context.layer is provided, intent references are checked against it.
539
+ */
540
+ architectureProfile?: ArchitectureProfile;
541
+ /**
542
+ * When true, flag string literals that look like intent names but are not registered.
543
+ */
544
+ enforceIntentAllowlist?: boolean;
545
+ /**
546
+ * Optional TypeScript module object. When provided, AICodeGate adds AST-backed checks
547
+ * for publish misuse without taking a runtime dependency on TypeScript.
548
+ */
549
+ typescript?: unknown;
550
+ /**
551
+ * Ambient globals forbidden per layer (layer name → entries such as "fetch" or
552
+ * "Date.now"). Checked only when `typescript` is provided and context.layer resolves
553
+ * to a listed layer — mirrors ark-check's FORBIDDEN_GLOBAL rule.
554
+ */
555
+ forbiddenGlobals?: Record<string, string[]>;
556
+ /**
557
+ * Layer names whose role is infrastructure and may therefore import infrastructure
558
+ * (a persistence adapter importing the DB is correct, not a violation). The built-in
559
+ * infra-import heuristics are suppressed for these layers and for any layer whose
560
+ * name matches the conventional infra tokens. Populate from ark.config.json layers
561
+ * flagged `mayImportInfrastructure: true`, so unconventionally-named infra layers
562
+ * opt in explicitly. User-supplied `forbiddenPatterns` still apply everywhere.
563
+ */
564
+ infrastructureLayers?: string[];
565
+ /**
566
+ * Resolve an import specifier to the architecture layer of its TARGET file, if that target
567
+ * is governed by a declared layer (else undefined). When provided, the gate lets the
568
+ * layer RULES decide a governed edge instead of the infrastructure path-heuristic — so the
569
+ * write gate honors `ark.config.json` exactly like `ark-check`, and the heuristic only
570
+ * applies to ungoverned targets (external packages, paths no layer covers). The caller
571
+ * (ark-mcp) supplies this using the config's layer globs + tsconfig path aliases.
572
+ */
573
+ resolveImportLayer?: (specifier: string, fromFilePath?: string) => string | undefined;
574
+ }
575
+ declare function createAICodeGate<Context = AICodeGateContext>(options?: AICodeGateOptions<Context>): AICodeGate<Context>;
576
+
577
+ export { type AICodeGate, type AICodeGateContext, type AICodeGateOptions, type AICodeGateResult, type AICodeGateViolation, type AIGateExtension, type Adapter, type AdapterGovernanceIssue, type AdapterGovernanceResult, ArchitectureProfile, ArkCheckConfig, ArkKernel, ArkKernelConfig, ArkManifest, type ArkTestHarness, type ArkTestSnapshot, AuditQuery, AuditRecord, AuditStore, AuditTrail, type BuildPublishPolicyContextOptions, type ContractCheckResult, type CreateAdapterOptions, CreateArchitectureProfileFromArkConfigOptions, CreateArchitectureProfileOptions, CreateArkKernelFromConfigOptions, CreateArkKernelOptions, type CreateArkManifestOptions, CreateAuditTrailOptions, CreateElevenLayerArkConfigOptions, CreateObservabilityReporterOptions, CreateProjectionRegistryOptions, CreateWorkflowEngineOptions, DEFAULT_MAX_HISTORY_SIZE, DefineIntentOptions, type DefinePolicyOptions, type DefinePortOptions, DependencyGraph, DomainEvent, EventBus, EventBusOptions, EventContract, EventContractRegistry, EventContractRegistryImpl, EventContractValidationResult, EventContractViolationError, GraphEdge, type GraphPolicyContext, InMemoryAuditStore, InMemoryOutboxStore, InMemoryReadModelStore, InMemoryWorkflowStore, IntentCreator, IntentCreator as IntentDefinition, IntentName, type IntentNameValidation, IntentRegistry, IntentRelationship, InvalidIntentNameError, type LayerFlowRule, LayerPolicyContextError, type LayerPolicyOptions, MANIFEST_SCHEMA_VERSION, MetadataRegistry, ObservabilityDriftReport, ObservabilityReporter, ObservedLayerFlowViolationError, OutboxRecord, OutboxStatus, OutboxStore, Policy, PolicyEnforcementMode, PolicyEngine, PolicySeverity, PolicyViolation, PolicyViolationError, type Port, ProjectionRegistry, type PublishPolicyContext, ReadModelStore, SagaDefinition, SagaInstance, SourceMetadataOverrideError, type SyncRegistryOptions, TraceRecord, TraceRecordType, UnknownEventSourceError, UnregisteredIntentError, WorkflowEngine, WorkflowSnapshot, WorkflowStore, architecturalPolicies, buildPublishPolicyContext, checkAdapterGovernance, checkContract, createAICodeGate, createAdapter, createArchitectureProfile, createArchitectureProfileFromArkConfig, createArkKernel, createArkKernelFromConfig, createArkManifest, createArkTestHarness, createAuditTrail, createDependencyGraph, createElevenLayerArkConfig, createEventBus, createEventContractRegistry, createIntentRegistry, createLenientArkKernel, createLenientArkKernelFromConfig, createMetadataRegistry, createObservabilityReporter, createProjectionRegistry, createSaga, createStrictArkKernel, createStrictArkKernelFromConfig, createWorkflowEngine, defaultIntentRegistry, defineArchitectureProfilePolicy, defineIntent, defineLayerPolicy, definePolicy, definePort, definePublishPolicy, elevenLayerProfile, isLayerPolicy, syncRegistryToGraph, validateIntentName, version };