ark-runtime-kernel 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1496 @@
+/** Ark library version — single source of truth. */
+declare const version = "1.0.0";
+
+/**
+ * Core domain primitives for Ark.
+ * These types are the foundation for all governance concepts.
+ */
+/**
+ * Semantic intent names follow a convention:
+ * - Domain.* for domain events and entities
+ * - Application.* for use-cases / orchestration
+ * - Adapter.* for integration points
+ * - Workflow.* for sagas and processes
+ * - Job.* for background jobs and scheduling
+ * - Presentation.* for UI/API adapters
+ * - Reporting.* for read models and projections
+ * - Metadata.* for extensibility contracts
+ * - Security.* / Audit.* / Observability.* for cross-cutting kernel concerns
+ * - Kernel.* for Ark-owned governance signals
+ */
+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}`;
+type CorrelationId = string;
+interface EventMetadata {
+    occurredAt: string;
+    source: string;
+    kernelInstanceId?: string;
+    eventVersion?: string;
+    schemaVersion?: string;
+    allowInterception?: boolean;
+    interceptions?: Array<{
+        interceptorId: string;
+        timestamp: string;
+    }>;
+    correlationId?: CorrelationId;
+    causationId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    [key: string]: unknown;
+}
+interface DomainEvent<Name extends IntentName = IntentName, Payload = unknown> {
+    intent: Name;
+    payload: Payload;
+    metadata: EventMetadata;
+}
+
+/**
+ * Intent-specific types for the Ark kernel.
+ *
+ * Intents provide semantic naming for every important concept in the system
+ * (domain events, application operations, adapters, workflows).
+ */
+
+/**
+ * An IntentCreator is a callable that creates a strongly-typed DomainEvent
+ * when invoked with a payload.
+ *
+ * It also carries the semantic `name`.
+ *
+ * @example
+ * const OrderPlaced = defineIntent<'Domain.Order.OrderPlaced', { orderId: string }>('Domain.Order.OrderPlaced');
+ * const event = OrderPlaced({ orderId: 'o-1' });
+ */
+interface IntentCreator<Name extends IntentName, Payload = unknown> {
+    /**
+     * Creates a DomainEvent for this intent.
+     */
+    (payload: Payload): DomainEvent<Name, Payload>;
+    /**
+     * The fully-qualified semantic name of the intent (e.g. "Domain.Order.OrderPlaced").
+     */
+    readonly name: Name;
+}
+/** Kind of relationship between two intents. */
+type IntentRelationshipKind = 'dependsOn' | 'produces';
+/**
+ * Relationship declarations between intents.
+ * Used for dependency analysis and graph generation.
+ */
+interface IntentRelationship {
+    from: string;
+    to: string;
+    kind: IntentRelationshipKind;
+}
+
+/**
+ * IntentRegistry
+ *
+ * Central registry for semantic intents.
+ * Supports registration, duplicate prevention, and declared dependency relationships.
+ *
+ * This is a core building block for governance, dependency graphs, and policy enforcement.
+ */
+
+/**
+ * Options for declaring relationships when defining an intent.
+ */
+interface DefineIntentOptions {
+    /** Other intents this one depends on (semantic names) */
+    dependsOn?: IntentName[];
+    /** Intents that this one produces / triggers */
+    produces?: IntentName[];
+}
+/**
+ * IntentRegistry manages all registered intents and their declared relationships.
+ */
+declare class IntentRegistry {
+    private readonly intents;
+    private readonly dependencies;
+    private readonly productions;
+    /**
+     * Define/register a new intent.
+     *
+     * @param name - Semantic intent name following the convention (Domain.*, Application.*, etc.)
+     * @param options - Optional relationship declarations
+     * @throws Error if an intent with the same name is already registered
+     */
+    define<N extends IntentName, P = unknown>(name: N, options?: DefineIntentOptions): IntentCreator<N, P>;
+    /**
+     * Declare that one intent depends on / relates to another.
+     * This information is used by the DependencyGraph (future iterations) and for policy checks.
+     *
+     * @param from - The source intent (e.g. an Application operation)
+     * @param to - The target intent it depends on (e.g. a Domain event or concept)
+     */
+    declareDependency(from: string, to: string): void;
+    /**
+     * Declare that one intent produces / emits another (e.g. use case → domain event).
+     */
+    declareProduction(from: string, to: string): void;
+    /**
+     * Retrieve a previously defined intent creator by name.
+     */
+    get<N extends IntentName = IntentName, P = unknown>(name: string): IntentCreator<N, P> | undefined;
+    /**
+     * List all registered intent creators.
+     */
+    list(): IntentCreator<IntentName, unknown>[];
+    /**
+     * Get all declared dependencies for a given intent.
+     */
+    getDependencies(intentName: string): string[];
+    /**
+     * Get all intents produced / emitted by a given intent.
+     */
+    getProductions(intentName: string): string[];
+    /**
+     * Get all declared relationships (useful for graph generation).
+     */
+    getAllRelationships(): IntentRelationship[];
+    /**
+     * Check if an intent name has been registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Clear the registry. Primarily useful for tests.
+     */
+    clear(): void;
+}
+
+/**
+ * defineIntent
+ *
+ * The primary ergonomic function for declaring semantic intents.
+ *
+ * Uses a default shared registry for convenience, while still allowing
+ * isolated registries via `createIntentRegistry()`.
+ *
+ * Intents are the core of Ark's governance model. They give every
+ * architectural concept (domain events, use cases, adapter operations, workflows)
+ * an explicit, namespaced, machine-readable identity.
+ */
+
+/**
+ * Define a new semantic intent.
+ *
+ * This is the main entry point most users (and AI generators) will use.
+ *
+ * @example
+ * ```ts
+ * // Domain event
+ * const OrderPlaced = defineIntent<'Domain.Order.OrderPlaced', {
+ *   orderId: string;
+ *   amount: number;
+ * }>('Domain.Order.OrderPlaced');
+ *
+ * const event = OrderPlaced({ orderId: 'o-42', amount: 99.5 });
+ *
+ * // Application operation that declares a dependency at definition time
+ * const ConfirmOrder = defineIntent<'Application.ConfirmOrder', { orderId: string }>(
+ *   'Application.ConfirmOrder',
+ *   { dependsOn: ['Domain.Order.OrderPlaced'] }
+ * );
+ * ```
+ *
+ * @param name - Unique semantic name. Recommended convention:
+ *   - `Domain.*` for domain concepts and events
+ *   - `Application.*` for use cases / orchestration
+ *   - `Adapter.*` for external integrations
+ *   - `Workflow.*` for sagas and long-running processes
+ * @param options - Optional initial relationship declarations (`dependsOn`, `produces`)
+ */
+declare function defineIntent<N extends IntentName, P = unknown>(name: N, options?: DefineIntentOptions): IntentCreator<N, P>;
+/**
+ * Create an isolated IntentRegistry.
+ * Useful for testing, multiple bounded contexts, or advanced governance setups.
+ */
+declare function createIntentRegistry(): IntentRegistry;
+/**
+ * The default registry backing the top-level `defineIntent` calls.
+ * You can inspect it or use it directly if needed.
+ */
+declare const defaultIntentRegistry: IntentRegistry;
+
+/**
+ * Runtime validation for semantic intent naming conventions.
+ */
+interface IntentNameValidation {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Validate that an intent name follows Ark naming conventions.
+ */
+declare function validateIntentName(name: string): IntentNameValidation;
+
+/**
+ * Policy types for the Ark kernel.
+ *
+ * Policies allow declaring architectural rules that can be checked at runtime.
+ * Supports both hard policies (must never be violated) and soft policies (warnings).
+ */
+type PolicySeverity = 'hard' | 'soft';
+type PolicyEnforcementMode = 'runtime' | 'static' | 'runtime-and-static' | 'advisory';
+/**
+ * Represents a single violation of a policy.
+ */
+interface PolicyViolation {
+    /** Name of the policy that was violated */
+    policyName: string;
+    /** Severity level of the policy */
+    severity: PolicySeverity;
+    /** Human-readable explanation of the violation */
+    message: string;
+    /** Optional additional structured details */
+    details?: unknown;
+}
+/**
+ * A Policy defines a rule that can be evaluated against a context.
+ *
+ * @template Context - The shape of data the policy evaluates (e.g. { registry, events })
+ */
+interface Policy<Context = unknown> {
+    /** Unique name of the policy (used in violations and reporting) */
+    readonly name: string;
+    /** Whether this is a hard rule (enforced strictly) or soft (advisory) */
+    readonly severity: PolicySeverity;
+    /** Optional tags for policy classification (e.g. 'layer', 'naming') */
+    readonly tags?: readonly string[];
+    readonly owner?: string;
+    readonly version?: string;
+    readonly rationale?: string;
+    readonly enforcementMode?: PolicyEnforcementMode;
+    readonly deprecated?: boolean | string;
+    readonly replacedBy?: string;
+    /**
+     * Evaluates the policy against the given context.
+     * Return true / [] for pass, false / single violation / array for failure.
+     */
+    check(context: Context): boolean | PolicyViolation | PolicyViolation[];
+}
+
+/**
+ * PolicyEngine
+ *
+ * Evaluates collections of policies against a context.
+ * Supports hard and soft policies.
+ * - Hard policies: violations cause enforcement to throw.
+ * - Soft policies: violations are reported as warnings but do not throw.
+ */
+
+interface PolicyEvaluationResult {
+    passed: boolean;
+    violations: PolicyViolation[];
+    hardViolations: PolicyViolation[];
+    softViolations: PolicyViolation[];
+}
+/**
+ * The PolicyEngine is responsible for registering policies and evaluating
+ * them against a given context.
+ */
+declare class PolicyEngine<Context = unknown> {
+    private readonly policies;
+    constructor(initialPolicies?: Policy<Context>[]);
+    /**
+     * Adds a policy to the engine.
+     */
+    add(policy: Policy<Context>): void;
+    /**
+     * Returns all registered policies.
+     */
+    getPolicies(): Policy<Context>[];
+    /**
+     * Evaluates all policies against the provided context.
+     */
+    evaluate(context: Context): PolicyEvaluationResult;
+    /**
+     * Enforces all policies.
+     *
+     * - Soft violations are collected and can be observed (returned or logged).
+     * - Hard violations cause an error to be thrown (by default).
+     *
+     * @returns Evaluation result (including any soft violations)
+     * @throws Error if any hard policy is violated
+     */
+    enforce(context: Context): PolicyEvaluationResult;
+    /**
+     * Clears all registered policies.
+     */
+    clear(): void;
+}
+
+/**
+ * Typed error thrown when hard policies are violated.
+ */
+
+declare class PolicyViolationError extends Error {
+    readonly violations: PolicyViolation[];
+    constructor(violations: PolicyViolation[]);
+}
+
+/**
+ * definePolicy
+ *
+ * Factory function to create architectural policies in a declarative way.
+ */
+
+interface DefinePolicyOptions<Context = unknown> {
+    name: string;
+    severity?: PolicySeverity;
+    tags?: readonly string[];
+    owner?: string;
+    version?: string;
+    rationale?: string;
+    enforcementMode?: PolicyEnforcementMode;
+    deprecated?: boolean | string;
+    replacedBy?: string;
+    check: (context: Context) => boolean | PolicyViolation | PolicyViolation[];
+}
+/**
+ * Creates a Policy from a declarative configuration.
+ *
+ * The provided `check` function is called as-is. The PolicyEngine is responsible
+ * for normalizing results (booleans, single violations, arrays) into a consistent
+ * set of PolicyViolation objects.
+ *
+ * @example
+ * ```ts
+ * const noDomainToInfra = definePolicy({
+ *   name: 'Domain must not depend on infrastructure',
+ *   severity: 'hard',
+ *   check: (ctx) => {
+ *     const violations: PolicyViolation[] = [];
+ *     // ... logic using ctx.registry.getAllRelationships()
+ *     return violations.length > 0 ? violations : true;
+ *   }
+ * });
+ * ```
+ */
+declare function definePolicy<Context = unknown>(options: DefinePolicyOptions<Context>): Policy<Context>;
+
+/**
+ * Architecture layer profiles.
+ *
+ * A profile turns semantic names such as `Domain.Order.Placed` into governed
+ * layer names and dependency rules.
+ */
+interface ArchitectureLayer {
+    name: string;
+    prefixes: string[];
+    description?: string;
+    order?: number;
+}
+interface ArchitectureRule {
+    from: string;
+    to: string;
+    allowed: boolean;
+    message?: string;
+}
+interface ArchitectureProfile {
+    name: string;
+    layers: ArchitectureLayer[];
+    rules: ArchitectureRule[];
+    resolveLayer(name: string): string | undefined;
+}
+interface CreateArchitectureProfileOptions {
+    name: string;
+    layers: ArchitectureLayer[];
+    rules?: ArchitectureRule[];
+}
+interface ArchitectureLayerConfig {
+    name: string;
+    patterns: string[];
+    intentPrefixes: string[];
+    /** Optional layers do not warn when their patterns match no files. */
+    optional?: boolean;
+}
+interface ArkCheckConfig {
+    include: string[];
+    layers: ArchitectureLayerConfig[];
+    rules: ArchitectureRule[];
+}
+interface CreateElevenLayerArkConfigOptions {
+    /** Source root used in generated file patterns. Default: "src". */
+    rootDir?: string;
+    /** Include entries for ark-check. Default: [rootDir]. */
+    include?: string[];
+    /** Mark generated layers optional. Default: true. */
+    optionalLayers?: boolean;
+}
+
+declare function createArchitectureProfile(options: CreateArchitectureProfileOptions): ArchitectureProfile;
+declare const elevenLayerProfile: ArchitectureProfile;
+declare function createElevenLayerArkConfig(options?: CreateElevenLayerArkConfigOptions): ArkCheckConfig;
+
+/**
+ * Dependency Graph types.
+ *
+ * Used to model declared + observed relationships between intents,
+ * and to generate visualizations (Mermaid) and detect violations.
+ */
+
+interface GraphEdge {
+    from: string;
+    to: string;
+    kind?: 'declared' | 'observed' | 'produces';
+}
+interface GraphNode {
+    id: string;
+    kind?: string;
+}
+interface DependencyGraph {
+    /**
+     * Register a declared dependency between two semantic names.
+     */
+    registerDependency(from: string, to: string, kind?: GraphEdge['kind']): void;
+    /**
+     * Register an observed event flow (producer -> consumer).
+     */
+    registerEventFlow(producer: string, consumer: string): void;
+    /**
+     * Return all nodes.
+     */
+    getNodes(): GraphNode[];
+    /**
+     * Return all edges.
+     */
+    getEdges(): GraphEdge[];
+    /**
+     * Export as JSON.
+     */
+    toJSON(): {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    /**
+     * Export as Mermaid flowchart.
+     */
+    toMermaid(): string;
+    /**
+     * Export as Mermaid flowchart grouped into profile layers.
+     */
+    toLayerMermaid(profile: ArchitectureProfile): string;
+    /**
+     * Detect violations by running provided policies or simple rules.
+     * For simplicity here we accept predicates that return violation messages.
+     */
+    detectViolations(rules?: Array<(edges: GraphEdge[]) => string[]>): string[];
+}
+
+/**
+ * DependencyGraph implementation.
+ *
+ * Collects declared and observed relationships.
+ * Generates Mermaid diagrams and JSON.
+ * Supports simple violation detection via rule functions.
+ */
+
+declare function createDependencyGraph(): DependencyGraph;
+
+/**
+ * Bridge IntentRegistry relationships into a DependencyGraph.
+ */
+
+interface SyncRegistryOptions {
+    /** Skip edges whose target intent is not registered (default: false). */
+    requireRegisteredTargets?: boolean;
+}
+/**
+ * Sync declared intent relationships from a registry into a dependency graph.
+ *
+ * - `dependsOn` → `declared` edges
+ * - `produces` → `produces` edges
+ */
+declare function syncRegistryToGraph(registry: IntentRegistry, graph: DependencyGraph, options?: SyncRegistryOptions): void;
+
+/**
+ * Built-in architectural policy helpers.
+ */
+
+interface LayerFlowRule {
+    from: string;
+    to: string;
+    allowed: boolean;
+    message?: string;
+}
+interface LayerPolicyOptions {
+    name?: string;
+    severity?: 'hard' | 'soft';
+    /** Prefix rules — e.g. { from: 'Domain', to: 'Adapter', allowed: false } */
+    rules: LayerFlowRule[];
+    resolveLayer?: (name: string) => string | undefined;
+}
+/**
+ * Create a policy that enforces layer-crossing rules on graph edges or intent relationships.
+ */
+declare function defineLayerPolicy<Context extends {
+    edges?: GraphEdge[];
+    relationships?: IntentRelationship[];
+}>(options: LayerPolicyOptions): Policy<Context>;
+/** True when a policy requires graph/registry context to enforce layer rules. */
+declare function isLayerPolicy(policy: Policy): boolean;
+/** Preset architectural policy factories. */
+declare const architecturalPolicies: {
+    /**
+     * @deprecated Use cleanArchitectureMatrix() for full layer rules.
+     * Blocks Domain → Adapter declared dependencies only.
+     */
+    layerIsolation(): Policy<{
+        edges?: GraphEdge[];
+        relationships?: IntentRelationship[];
+    }>;
+    /**
+     * Clean-architecture dependency matrix (declared dependsOn / declared edges only).
+     * Does not block observed event flows (Domain events consumed by Application).
+     */
+    cleanArchitectureMatrix(): Policy<{
+        edges?: GraphEdge[];
+        relationships?: IntentRelationship[];
+    }>;
+};
+declare function defineArchitectureProfilePolicy<Context extends {
+    edges?: GraphEdge[];
+    relationships?: IntentRelationship[];
+}>(profile: ArchitectureProfile, options?: Omit<LayerPolicyOptions, 'rules' | 'resolveLayer'>): Policy<Context>;
+
+type MaybePromise<T> = T | Promise<T>;
+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';
+interface AuditRecord {
+    id: string;
+    type: AuditRecordType;
+    timestamp: string;
+    source?: string;
+    actor?: string;
+    intent?: string;
+    correlationId?: string;
+    causationId?: string;
+    subject?: string;
+    details?: unknown;
+}
+interface AuditRecordInput {
+    type: AuditRecordType;
+    timestamp?: string;
+    source?: string;
+    actor?: string;
+    intent?: string;
+    correlationId?: string;
+    causationId?: string;
+    subject?: string;
+    details?: unknown;
+}
+interface AuditQuery {
+    type?: AuditRecordType;
+    intent?: string;
+    correlationId?: string;
+    subject?: string;
+    since?: string;
+    until?: string;
+    limit?: number;
+}
+interface AuditStore {
+    append(record: AuditRecord): MaybePromise<void>;
+    query(query?: AuditQuery): MaybePromise<AuditRecord[]>;
+    clear(): MaybePromise<void>;
+}
+interface AuditTrail {
+    record(input: AuditRecordInput): Promise<AuditRecord>;
+    query(query?: AuditQuery): Promise<AuditRecord[]>;
+    clear(): Promise<void>;
+}
+interface CreateAuditTrailOptions {
+    store?: AuditStore;
+    maxRecords?: number;
+}
+
+declare class InMemoryAuditStore implements AuditStore {
+    private readonly maxRecords?;
+    private readonly records;
+    constructor(maxRecords?: number | undefined);
+    append(record: AuditRecord): void;
+    query(query?: AuditQuery): AuditRecord[];
+    clear(): void;
+}
+declare function createAuditTrail(options?: CreateAuditTrailOptions): AuditTrail;
+
+type EventSchemaFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'unknown';
+interface EventSchemaField {
+    type: EventSchemaFieldType;
+    required?: boolean;
+    description?: string;
+    /** Allowed literal values for this field. Compared with Object.is. */
+    enum?: unknown[];
+    /** Nested object fields when type is "object". */
+    fields?: EventPayloadSchema;
+    /** Array item schema when type is "array". */
+    items?: EventSchemaField;
+}
+type EventPayloadSchema = Record<string, EventSchemaField>;
+interface EventContract {
+    intent: IntentName;
+    version: string;
+    schema?: EventPayloadSchema;
+    owner?: string;
+    rationale?: string;
+    deprecated?: boolean | string;
+    allowAdditionalFields?: boolean;
+}
+interface EventContractIssue {
+    intent: string;
+    version?: string;
+    field?: string;
+    message: string;
+}
+interface EventContractValidationResult {
+    ok: boolean;
+    contract?: EventContract;
+    issues: EventContractIssue[];
+}
+interface EventContractRegistry {
+    register(contract: EventContract): void;
+    get(intent: string, version?: string): EventContract | undefined;
+    list(intent?: string): EventContract[];
+    validate(event: DomainEvent): EventContractValidationResult;
+    clear(): void;
+}
+
+declare class EventContractRegistryImpl implements EventContractRegistry {
+    private readonly contracts;
+    register(contract: EventContract): void;
+    get(intent: string, version?: string): EventContract | undefined;
+    list(intent?: string): EventContract[];
+    validate(event: DomainEvent): EventContractValidationResult;
+    clear(): void;
+    private key;
+}
+declare function createEventContractRegistry(): EventContractRegistry;
+
+type OutboxStatus = 'pending' | 'dispatched' | 'failed';
+interface OutboxRecord {
+    id: string;
+    event: DomainEvent;
+    status: OutboxStatus;
+    attempts: number;
+    createdAt: string;
+    updatedAt: string;
+    error?: string;
+}
+interface OutboxStore {
+    enqueue(event: DomainEvent): Promise<OutboxRecord>;
+    markDispatched(id: string): Promise<void>;
+    markFailed(id: string, error: unknown): Promise<void>;
+    list(status?: OutboxStatus): Promise<OutboxRecord[]>;
+    clear(): Promise<void>;
+}
+
+declare class InMemoryOutboxStore implements OutboxStore {
+    private readonly records;
+    enqueue(event: DomainEvent): Promise<OutboxRecord>;
+    markDispatched(id: string): Promise<void>;
+    markFailed(id: string, error: unknown): Promise<void>;
+    list(status?: OutboxStatus): Promise<OutboxRecord[]>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Event Bus types for the Ark kernel.
+ *
+ * The Event Bus is the central nervous system for Domain Events.
+ * It provides publish/subscribe, history for observability, and metadata handling.
+ */
+
+/** Standard trace record for observability and agent consumption. */
+type TraceRecordType = 'event.published' | 'event.rawPublish' | 'event.intercepted' | 'interceptor.error' | 'policy.hardViolation' | 'policy.softViolation' | 'layer.observedViolation' | 'handler.error' | 'hook.error';
+/**
+ * Runtime enforcement mode for observed producer→event layer flows.
+ * - 'off': flows are recorded (for drift reports) but never enforced.
+ * - 'soft': a `layer.observedViolation` trace + audit record is emitted; publish proceeds.
+ * - 'hard': publish throws `ObservedLayerFlowViolationError` before the event reaches
+ *   history, outbox, or subscribers.
+ */
+type ObservedLayerFlowMode = 'off' | 'soft' | 'hard';
+interface TraceRecord {
+    type: TraceRecordType;
+    timestamp: string;
+    intent: string;
+    correlationId?: string;
+    traceId?: string;
+    spanId?: string;
+    details?: unknown;
+}
+type TraceSink = (record: TraceRecord) => void;
+/**
+ * Options when creating an EventBus.
+ */
+interface EventBusOptions<Context = unknown> {
+    /** Optional hook called after every successful publish */
+    onPublish?: (event: DomainEvent) => void | Promise<void>;
+    /** Native audit trail used to persist publish, policy, and handler events. */
+    auditTrail?: AuditTrail;
+    /** Event contracts used to validate payload shape and event versions. */
+    eventContracts?: EventContractRegistry;
+    /** When true, events without a registered contract are rejected. */
+    strictEventContracts?: boolean;
+    /** When true, metadata.source must be explicit and not "unknown". */
+    requireKnownSource?: boolean;
+    /**
+     * Architecture profile used to enforce the OBSERVED producer→event layer flow at
+     * publish time. Required for `enforceObservedLayerFlow` to have effect.
+     */
+    architectureProfile?: ArchitectureProfile;
+    /**
+     * Enforce each published event's real producer→event flow (metadata.source → intent)
+     * against `architectureProfile` layer rules at runtime. Unlike the declared-model layer
+     * policy, this checks what the system actually did. Default: 'off'.
+     */
+    enforceObservedLayerFlow?: ObservedLayerFlowMode;
+    /** Optional outbox store for durable delivery handoff. */
+    outbox?: OutboxStore;
+    /** Stable id stamped into event metadata for this kernel/event bus instance. */
+    instanceId?: string;
+    /** Lightweight tracing hooks for OpenTelemetry or custom tracer bridges. */
+    traceSinks?: TraceSink[];
+    /** Called when soft policies produce violations (publish still proceeds). */
+    onSoftViolation?: (result: PolicyEvaluationResult, event: DomainEvent) => void | Promise<void>;
+    /** Called when a subscriber handler throws or rejects. */
+    onHandlerError?: (error: unknown, event: DomainEvent, intentName: string) => void | Promise<void>;
+    /** When true, rethrow handler errors after calling onHandlerError. Default: false. */
+    rethrowHandlerErrors?: boolean;
+    /**
+     * Policies to evaluate on every publish.
+     * If provided, they run before subscribers are notified.
+     * Hard violations will cause publish to throw.
+     */
+    policies?: Policy<Context>[];
+    /**
+     * Function to build the context object passed to policies for a given event.
+     * Default: { event }, or { event, relationships, edges } when registry/graph provided.
+     */
+    getPolicyContext?: (event: DomainEvent) => Context;
+    /**
+     * Intent registry whose relationships are injected into the default policy context.
+     * Enables layer policies (e.g. architecturalPolicies.layerIsolation) on publish.
+     */
+    intentRegistry?: IntentRegistry;
+    /**
+     * Dependency graph whose edges are injected into the default policy context.
+     */
+    dependencyGraph?: DependencyGraph;
+    /**
+     * Pre-configured PolicyEngine to use (alternative to policies array).
+     */
+    policyEngine?: PolicyEngine<Context>;
+    /**
+     * Maximum publish history entries to retain. Oldest evicted when exceeded.
+     * Default: unlimited.
+     */
+    maxHistorySize?: number;
+    /**
+     * When true (default: true if intentRegistry is provided), reject publish/subscribe
+     * for intents not registered in intentRegistry and optionally validate naming.
+     */
+    strictRegistry?: boolean;
+    /**
+     * When true (default: matches strictRegistry), validate intent names follow
+     * Domain.* / Application.* / Adapter.* / Workflow.* conventions at runtime.
+     */
+    validateIntentNaming?: boolean;
+}
+/**
+ * A subscriber is a function that receives events of a specific intent.
+ */
+type EventHandler<N extends IntentName, P = unknown> = (event: DomainEvent<N, P>) => void | Promise<void>;
+type EventPayloadPatch = Record<string, unknown> | unknown[];
+interface EventInterceptorContext<N extends IntentName = IntentName, P = unknown> {
+    readonly event: Readonly<DomainEvent<N, P>>;
+    intercept(patch: EventPayloadPatch): void;
+}
+type EventInterceptor<N extends IntentName = IntentName, P = unknown> = (context: EventInterceptorContext<N, P>) => void | Promise<void>;
+interface EventInterceptionInfo {
+    registrationId: string;
+    interceptorId: string;
+    intent: string;
+    createdAt: string;
+    lastInterceptedAt?: string;
+}
+/**
+ * Unsubscribe function returned by subscribe.
+ */
+type Unsubscribe = () => void;
+/**
+ * Record of a published event for observability.
+ */
+interface PublishedEventRecord {
+    event: DomainEvent;
+    publishedAt: string;
+    subscribersNotified: number;
+}
+interface EventPublisher {
+    readonly source: string;
+    publish<N extends IntentName, P>(intent: IntentCreator<N, P>, payload: P, metadata?: Partial<EventMetadata>): Promise<void>;
+}
+/**
+ * The public EventBus interface.
+ */
+interface EventBus {
+    /**
+     * Publish an event.
+     * Accepts either a pre-built DomainEvent or an IntentCreator + payload (plus optional metadata).
+     */
+    publish<N extends IntentName, P>(eventOrCreator: DomainEvent<N, P> | IntentCreator<N, P>, payloadOrMeta?: P | Partial<EventMetadata>, metadata?: Partial<EventMetadata>): Promise<void>;
+    /**
+     * Create a source-bound publisher capability. The returned publisher stamps
+     * metadata.source internally and rejects attempts to publish as another source.
+     */
+    createPublisher<N extends IntentName, P>(source: N | IntentCreator<N, P>): EventPublisher;
+    /**
+     * Subscribe to events for a specific intent (by name or creator).
+     * Returns an unsubscribe function.
+     */
+    subscribe<N extends IntentName, P>(intent: N | IntentCreator<N, P>, handler: EventHandler<N, P>): Unsubscribe;
+    /**
+     * Register an add-only interceptor for one intent.
+     * Interceptors may enrich payloads, but cannot overwrite existing payload fields.
+     */
+    registerInterceptor<N extends IntentName, P>(intent: N | IntentCreator<N, P>, interceptor: EventInterceptor<N, P>, interceptorId?: string): string;
+    /**
+     * Remove a registered interceptor by registration id.
+     */
+    unregisterInterceptor(registrationId: string): boolean;
+    /**
+     * List registered interceptors.
+     */
+    listInterceptors(intent?: string): EventInterceptionInfo[];
+    /**
+     * Returns the history of published events (for observability and testing).
+     */
+    getHistory(): PublishedEventRecord[];
+    /**
+     * Clears publish history (useful in tests).
+     */
+    clearHistory(): void;
+    /**
+     * Returns the observability trace (publish, soft violations, handler errors).
+     */
+    getTrace(): TraceRecord[];
+    /**
+     * Clears the observability trace.
+     */
+    clearTrace(): void;
+}
+
+/**
+ * EventBus implementation.
+ *
+ * Core publish/subscribe mechanics with:
+ * - Intent-aware typing via creators
+ * - Automatic metadata enrichment
+ * - Full publish history for observability
+ * - Strict registry validation (opt-in by default when registry provided)
+ */
+
+declare function createEventBus<Context = unknown>(options?: EventBusOptions<Context>): EventBus;
+
+/**
+ * Helpers for building policy evaluation context on event publish.
+ */
+
+/**
+ * Standard context for policies evaluated during event publish.
+ * Includes the event plus optional registry relationships and graph edges
+ * so layer policies (e.g. architecturalPolicies.layerIsolation) can run.
+ */
+interface PublishPolicyContext {
+    event: DomainEvent;
+    relationships?: IntentRelationship[];
+    edges?: GraphEdge[];
+}
+interface GraphPolicyContext {
+    relationships?: IntentRelationship[];
+    edges?: GraphEdge[];
+}
+interface BuildPublishPolicyContextOptions {
+    intentRegistry?: IntentRegistry;
+    dependencyGraph?: DependencyGraph;
+}
+/**
+ * Build a getPolicyContext function that feeds registry + graph data to policies.
+ *
+ * @example
+ * ```ts
+ * const bus = createEventBus({
+ *   intentRegistry: registry,
+ *   dependencyGraph: graph,
+ *   policies: [architecturalPolicies.layerIsolation()],
+ * });
+ * ```
+ */
+declare function buildPublishPolicyContext(options: BuildPublishPolicyContextOptions): (event: DomainEvent) => PublishPolicyContext;
+declare function definePublishPolicy(options: DefinePolicyOptions<PublishPolicyContext>): Policy<PublishPolicyContext>;
+
+/**
+ * Event bus governance errors.
+ */
+declare class UnregisteredIntentError extends Error {
+    readonly intentName: string;
+    constructor(intentName: string);
+}
+declare class InvalidIntentNameError extends Error {
+    readonly intentName: string;
+    readonly reason: string;
+    constructor(intentName: string, reason: string);
+}
+declare class LayerPolicyContextError extends Error {
+    constructor();
+}
+declare class EventContractViolationError extends Error {
+    readonly intentName: string;
+    readonly issues: unknown[];
+    constructor(intentName: string, issues: unknown[]);
+}
+declare class UnknownEventSourceError extends Error {
+    readonly intentName: string;
+    readonly source?: string;
+    constructor(intentName: string, source?: string);
+}
+declare class SourceMetadataOverrideError extends Error {
+    readonly boundSource: string;
+    readonly attemptedSource: string;
+    constructor(boundSource: string, attemptedSource: string);
+}
+/**
+ * Thrown when the OBSERVED producer→event flow crosses a forbidden layer boundary
+ * under `enforceObservedLayerFlow: 'hard'`. Unlike declared-model policy errors, this
+ * reflects what the running system actually did at publish time.
+ */
+declare class ObservedLayerFlowViolationError extends Error {
+    readonly source: string;
+    readonly intentName: string;
+    readonly fromLayer: string;
+    readonly toLayer: string;
+    constructor(source: string, intentName: string, fromLayer: string, toLayer: string, message?: string);
+}
+
+interface ObservabilityFlow {
+    from: string;
+    to: string;
+}
+interface ObservabilityDriftReport {
+    generatedAt: string;
+    declaredProductions: ObservabilityFlow[];
+    observedProductions: ObservabilityFlow[];
+    declaredButUnobserved: ObservabilityFlow[];
+    observedButUndeclared: ObservabilityFlow[];
+    unknownSources: ObservabilityFlow[];
+    unregisteredObservedSources: string[];
+    unregisteredObservedIntents: string[];
+    registeredButNeverObserved: string[];
+}
+interface ObservabilityReporter {
+    report(): ObservabilityDriftReport;
+}
+interface CreateObservabilityReporterOptions {
+    registry?: IntentRegistry;
+    eventBus?: EventBus;
+    graph?: DependencyGraph;
+}
+
+declare function createObservabilityReporter(options: CreateObservabilityReporterOptions): ObservabilityReporter;
+
+/**
+ * Metadata System (basic) for extensibility.
+ *
+ * Allows declaring entities, fields and simple rules/behaviors as data.
+ * This can be used by tools, codegen, or AI to understand the domain without hardcoding.
+ */
+interface FieldMeta {
+    type: string;
+    identity?: boolean;
+    required?: boolean;
+    description?: string;
+    relation?: {
+        entity: string;
+        kind?: 'one' | 'many';
+    };
+    readonly?: boolean;
+    deprecated?: boolean | string;
+    tags?: string[];
+    [key: string]: unknown;
+}
+interface EntityRuleMeta {
+    name: string;
+    description?: string;
+    severity?: 'hard' | 'soft';
+}
+interface EntityMeta {
+    name: string;
+    version?: string;
+    owner?: string;
+    layer?: string;
+    tags?: string[];
+    fields: Record<string, FieldMeta>;
+    rules?: EntityRuleMeta[];
+    /** Intent names this entity emits (domain events). */
+    emits?: string[];
+    /** Intent names this entity consumes / reacts to. */
+    consumes?: string[];
+    /** Read-model or projection names that derive from this entity. */
+    projections?: string[];
+    deprecated?: boolean | string;
+    [key: string]: unknown;
+}
+interface MetadataRegistrationOptions {
+    allowOverwrite?: boolean;
+}
+interface MetadataIssue {
+    entity: string;
+    field?: string;
+    message: string;
+}
+interface MetadataValidationResult {
+    ok: boolean;
+    issues: MetadataIssue[];
+}
+interface MetadataRegistry {
+    entity(name: string, meta: Omit<EntityMeta, 'name'>, options?: MetadataRegistrationOptions): EntityMeta;
+    getEntity(name: string): EntityMeta | undefined;
+    listEntities(): EntityMeta[];
+    findEntitiesByIntent(intentName: string): EntityMeta[];
+    validate(): MetadataValidationResult;
+    toJSON(): EntityMeta[];
+}
+
+/**
+ * Basic MetadataRegistry implementation.
+ */
+
+declare function createMetadataRegistry(): MetadataRegistry;
+
+interface ProjectionDefinition<State = unknown> {
+    name: string;
+    sourceIntents: IntentName[];
+    initialState: State | (() => State);
+    project(event: DomainEvent<IntentName, unknown>, state: State): MaybePromise<State>;
+}
+interface ProjectionCheckpoint {
+    projection: string;
+    appliedCount: number;
+    lastIntent?: string;
+    lastCorrelationId?: string;
+    updatedAt?: string;
+}
+interface ReadModelStore {
+    load<State = unknown>(name: string): MaybePromise<State | undefined>;
+    save<State = unknown>(name: string, state: State): MaybePromise<void>;
+    clear(name?: string): MaybePromise<void>;
+}
+interface ProjectionRegistry {
+    register<State>(definition: ProjectionDefinition<State>): void;
+    list(): ProjectionDefinition[];
+    apply(event: DomainEvent<IntentName, unknown>): Promise<string[]>;
+    getState<State = unknown>(name: string): Promise<State | undefined>;
+    getCheckpoint(name: string): ProjectionCheckpoint | undefined;
+    getCheckpoints(): ProjectionCheckpoint[];
+    clear(): Promise<void>;
+}
+interface CreateProjectionRegistryOptions {
+    store?: ReadModelStore;
+    auditTrail?: AuditTrail;
+}
+
+declare class InMemoryReadModelStore implements ReadModelStore {
+    private readonly states;
+    load<State = unknown>(name: string): State | undefined;
+    save<State = unknown>(name: string, state: State): void;
+    clear(name?: string): void;
+}
+declare function createProjectionRegistry(options?: CreateProjectionRegistryOptions): ProjectionRegistry;
+
+/**
+ * Machine-readable manifest types for agent and tooling consumption.
+ */
+
+interface ArkManifestIntent {
+    name: string;
+    dependencies: string[];
+    productions: string[];
+}
+interface ArkManifestPolicy {
+    /** Stable slug for agents (derived from policy name). */
+    id: string;
+    name: string;
+    severity: 'hard' | 'soft';
+    tags?: string[];
+    description?: string;
+    owner?: string;
+    version?: string;
+    rationale?: string;
+    enforcementMode?: PolicyEnforcementMode;
+    deprecated?: boolean | string;
+    replacedBy?: string;
+}
+interface ArkManifestEntityLink {
+    entity: string;
+    emits?: string[];
+    consumes?: string[];
+}
+interface ArkManifestGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+interface ArkManifestArchitecture {
+    profile: string;
+    layers: ArchitectureLayer[];
+    rules: ArchitectureRule[];
+}
+interface ArkManifestProjection {
+    name: string;
+    sourceIntents: string[];
+    checkpoint?: ProjectionCheckpoint;
+}
+interface ArkManifestData {
+    /** Manifest schema version for agent/tooling compatibility. */
+    schemaVersion: string;
+    version: string;
+    exportedAt: string;
+    intents: ArkManifestIntent[];
+    relationships: IntentRelationship[];
+    policies: ArkManifestPolicy[];
+    entities: EntityMeta[];
+    graph: ArkManifestGraph;
+    architecture?: ArkManifestArchitecture;
+    projections: ArkManifestProjection[];
+    eventContracts: EventContract[];
+    observability?: ObservabilityDriftReport;
+    /** Cross-registry links for agent contract discovery. */
+    links: {
+        entityIntents: ArkManifestEntityLink[];
+    };
+}
+interface ArkManifest {
+    toJSON(): ArkManifestData;
+}
+
+/** Current Ark manifest JSON schema version. */
+declare const MANIFEST_SCHEMA_VERSION = "1.0";
+
+/**
+ * Aggregates kernel registries into a single machine-readable manifest.
+ */
+
+interface CreateArkManifestOptions {
+    registry?: IntentRegistry;
+    policyEngine?: PolicyEngine;
+    metadata?: MetadataRegistry;
+    graph?: DependencyGraph;
+    profile?: ArchitectureProfile;
+    projections?: ProjectionRegistry;
+    eventContracts?: EventContractRegistry;
+    observability?: ObservabilityReporter;
+}
+/**
+ * Create a machine-readable snapshot of the current architectural contract.
+ * Intended for AI agents, codegen tools, and documentation generators.
+ */
+declare function createArkManifest(options?: CreateArkManifestOptions): ArkManifest;
+
+/**
+ * Workflow / Saga support.
+ */
+
+type SagaContext = Record<string, unknown>;
+type SagaStatus = 'idle' | 'running' | 'compensating' | 'completed' | 'failed';
+type WorkflowStatus = SagaStatus | 'waiting';
+interface RetryPolicy {
+    attempts: number;
+    delayMs?: number;
+}
+interface WorkflowStep<P extends SagaContext = SagaContext> {
+    name: string;
+    onEvent?: IntentName;
+    retry?: RetryPolicy;
+    timeoutMs?: number;
+    execute: (payload: P, bus: EventBus) => MaybePromise<Partial<P> | void>;
+    compensate?: (payload: P, bus: EventBus, error?: unknown) => MaybePromise<void>;
+}
+interface WorkflowStartTrigger<P extends SagaContext = SagaContext> {
+    intent: IntentName;
+    mapEventToPayload(event: DomainEvent<IntentName, unknown>): P;
+}
+interface WorkflowDefinition<P extends SagaContext = SagaContext> {
+    name: string;
+    steps: WorkflowStep<P>[];
+    startOn?: WorkflowStartTrigger<P>;
+}
+interface WorkflowSnapshot<P extends SagaContext = SagaContext> {
+    id: string;
+    workflowName: string;
+    status: WorkflowStatus;
+    context: P;
+    completedSteps: string[];
+    currentStep?: string;
+    failedStep?: string;
+    attempts: Record<string, number>;
+    startedAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    error?: string;
+}
+interface WorkflowStore {
+    save<P extends SagaContext>(snapshot: WorkflowSnapshot<P>): MaybePromise<void>;
+    get<P extends SagaContext = SagaContext>(id: string): MaybePromise<WorkflowSnapshot<P> | undefined>;
+    list(workflowName?: string): MaybePromise<WorkflowSnapshot[]>;
+    clear(): MaybePromise<void>;
+}
+interface WorkflowEngine {
+    register<P extends SagaContext>(definition: WorkflowDefinition<P>): void;
+    start<P extends SagaContext>(workflowName: string, initialPayload: P, options?: {
+        id?: string;
+    }): Promise<WorkflowSnapshot<P>>;
+    get<P extends SagaContext = SagaContext>(id: string): Promise<WorkflowSnapshot<P> | undefined>;
+    list(workflowName?: string): Promise<WorkflowSnapshot[]>;
+}
+interface CreateWorkflowEngineOptions {
+    store?: WorkflowStore;
+    auditTrail?: AuditTrail;
+    defaultRetry?: RetryPolicy;
+}
+interface SagaStep<P extends SagaContext = SagaContext> extends WorkflowStep<P> {
+}
+interface SagaDefinition<P extends SagaContext = SagaContext> {
+    name: string;
+    steps: SagaStep<P>[];
+}
+interface SagaInstance<P extends SagaContext = SagaContext> {
+    id: string;
+    definition: SagaDefinition<P>;
+    readonly status: SagaStatus;
+    readonly completedSteps: string[];
+    run(initialPayload: P): Promise<void>;
+}
+
+/**
+ * In-process workflow engine with durable-store seams.
+ */
+
+declare class InMemoryWorkflowStore implements WorkflowStore {
+    private readonly snapshots;
+    save<P extends SagaContext>(snapshot: WorkflowSnapshot<P>): void;
+    get<P extends SagaContext = SagaContext>(id: string): WorkflowSnapshot<P> | undefined;
+    list(workflowName?: string): WorkflowSnapshot[];
+    clear(): void;
+}
+declare function createWorkflowEngine(bus: EventBus, options?: CreateWorkflowEngineOptions): WorkflowEngine;
+declare function createSaga<P extends SagaContext = SagaContext>(def: SagaDefinition<P>, bus: EventBus, options?: CreateWorkflowEngineOptions & {
+    id?: string;
+}): SagaInstance<P>;
+
+interface ArkKernel {
+    instanceId: string;
+    profile: ArchitectureProfile;
+    registry: IntentRegistry;
+    graph: DependencyGraph;
+    metadata: MetadataRegistry;
+    auditTrail: AuditTrail;
+    eventContracts: EventContractRegistry;
+    outbox: OutboxStore;
+    projections: ProjectionRegistry;
+    policyEngine: PolicyEngine;
+    eventBus: EventBus;
+    workflowEngine: WorkflowEngine;
+    observability: ObservabilityReporter;
+    publisher<N extends IntentName, P>(source: N | IntentCreator<N, P>): EventPublisher;
+    syncGraph(): void;
+    manifest(): ArkManifest;
+}
+interface CreateArkKernelOptions {
+    /**
+     * When true (default), createArkKernel uses the hardened runtime defaults:
+     * strict event contracts and hard observed-layer enforcement.
+     * Set to false only for explicit migration/legacy paths.
+     */
+    strict?: boolean;
+    profile?: ArchitectureProfile;
+    policies?: Policy[];
+    auditTrail?: AuditTrail;
+    eventContracts?: EventContractRegistry;
+    outbox?: OutboxStore;
+    metadata?: MetadataRegistry;
+    projections?: ProjectionRegistry;
+    maxHistorySize?: number;
+    autoApplyProjections?: boolean;
+    strictEventContracts?: boolean;
+    requireKnownSource?: boolean;
+    /**
+     * Enforce observed producer→event layer flows against the profile at runtime.
+     * Defaults to 'hard' when strict is true and 'off' when strict is false.
+     */
+    enforceObservedLayerFlow?: ObservedLayerFlowMode;
+    instanceId?: string;
+}
+
+declare function createArkKernel(options?: CreateArkKernelOptions): ArkKernel;
+declare function createStrictArkKernel(options?: CreateArkKernelOptions): ArkKernel;
+declare function createLenientArkKernel(options?: CreateArkKernelOptions): ArkKernel;
+
+interface ArkTestSnapshot {
+    events: DomainEvent[];
+    traces: TraceRecord[];
+    audit: AuditRecord[];
+    outbox: OutboxRecord[];
+    observability: ObservabilityDriftReport;
+}
+interface ArkTestHarness {
+    events(intent?: string): DomainEvent[];
+    traces(type?: TraceRecordType): TraceRecord[];
+    audit(query?: AuditQuery): Promise<AuditRecord[]>;
+    outbox(status?: OutboxStatus): Promise<OutboxRecord[]>;
+    observability(): ObservabilityDriftReport;
+    snapshot(): Promise<ArkTestSnapshot>;
+    clear(): Promise<void>;
+}
+
+declare function createArkTestHarness(kernel: ArkKernel): ArkTestHarness;
+
+/**
+ * Ports & Adapters basic contracts.
+ */
+interface Port<T = unknown> {
+    readonly name: string;
+    readonly ownerLayer?: string;
+    readonly intent?: IntentName;
+    readonly allowedAdapters?: string[];
+    readonly __port?: T;
+}
+interface Adapter<T = unknown> {
+    readonly name?: string;
+    readonly layer?: string;
+    readonly intent?: IntentName;
+    readonly port: Port<T>;
+    readonly impl: T;
+}
+interface DefinePortOptions {
+    ownerLayer?: string;
+    intent?: IntentName;
+    allowedAdapters?: string[];
+}
+interface CreateAdapterOptions {
+    name?: string;
+    layer?: string;
+    intent?: IntentName;
+    requiredKeys?: string[];
+}
+/**
+ * Simple contract checker (duck typing + optional required keys).
+ */
+type ContractCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    missing: string[];
+};
+interface AdapterGovernanceIssue {
+    ruleId: 'ADAPTER_NOT_ALLOWED_FOR_PORT';
+    message: string;
+    port: string;
+    adapter?: string;
+}
+type AdapterGovernanceResult = {
+    ok: true;
+    issues: [];
+} | {
+    ok: false;
+    issues: AdapterGovernanceIssue[];
+};
+
+/**
+ * Ports and Adapters utilities.
+ *
+ * definePort + createAdapter with basic runtime contract validation.
+ */
+
+declare function definePort<T = unknown>(name: string, options?: DefinePortOptions): Port<T>;
+declare function createAdapter<T>(port: Port<T>, impl: T, requiredKeysOrOptions?: string[] | CreateAdapterOptions, adapterOptions?: CreateAdapterOptions): Adapter<T>;
+declare function checkContract(impl: unknown, requiredKeys?: string[]): ContractCheckResult;
+declare function checkAdapterGovernance(adapter: Adapter): AdapterGovernanceResult;
+
+/**
+ * AI Code Gate (basic).
+ *
+ * Allows validation of generated source code against the defined architecture.
+ */
+interface AICodeGateViolation {
+    /** Stable rule identifier for agents and CI pipelines. */
+    ruleId: string;
+    /** @deprecated Use ruleId — kept for backward compatibility. */
+    code: string;
+    message: string;
+    line?: number;
+    suggestion?: string;
+    source?: string;
+    filePath?: string;
+    target?: string;
+    fromLayer?: string;
+    toLayer?: string;
+    details?: unknown;
+}
+/** Extension point for external analyzers (AST, semantic, etc.). */
+interface AIGateExtension<Context = unknown> {
+    readonly name: string;
+    analyze(source: string, context?: Context): AICodeGateViolation[];
+}
+interface AICodeGateContext {
+    filePath?: string;
+    agentId?: string;
+    layer?: string;
+    [key: string]: unknown;
+}
+interface AICodeGateResult {
+    valid: boolean;
+    violations: AICodeGateViolation[];
+}
+interface AICodeGate<Context = AICodeGateContext> {
+    validate(source: string, context?: Context): AICodeGateResult;
+}
+
+/**
+ * Basic AI Code Gate implementation.
+ *
+ * Uses simple string heuristics + registered intent names to detect obvious
+ * architectural violations in generated code (e.g. direct infra imports from domain).
+ * Not a full static analyzer — documented limitation.
+ */
+
+interface AICodeGatePolicyContext<Context = AICodeGateContext> {
+    source: string;
+    context?: Context;
+}
+interface AICodeGateOptions<Context = AICodeGateContext> {
+    policies?: Policy<AICodeGatePolicyContext<Context>>[];
+    intents?: Array<string | Pick<IntentCreator<IntentName, unknown>, 'name'>>;
+    /**
+     * Additional forbidden patterns (regex or strings).
+     */
+    forbiddenPatterns?: Array<string | RegExp>;
+    /**
+     * External analyzer extensions (type-only contract; plug in AST tools later).
+     */
+    extensions?: AIGateExtension<Context>[];
+    /**
+     * Optional architecture profile for layer-aware generated-code checks.
+     * When context.layer is provided, intent references are checked against it.
+     */
+    architectureProfile?: ArchitectureProfile;
+    /**
+     * When true, flag string literals that look like intent names but are not registered.
+     */
+    enforceIntentAllowlist?: boolean;
+    /**
+     * Optional TypeScript module object. When provided, AICodeGate adds AST-backed checks
+     * for publish misuse without taking a runtime dependency on TypeScript.
+     */
+    typescript?: unknown;
+}
+declare function createAICodeGate<Context = AICodeGateContext>(options?: AICodeGateOptions<Context>): AICodeGate<Context>;
+
+export { type AICodeGate, type AICodeGateContext, type AICodeGateOptions, type AICodeGateResult, type AICodeGateViolation, type AIGateExtension, type Adapter, type AdapterGovernanceIssue, type AdapterGovernanceResult, type ArchitectureLayer, type ArchitectureLayerConfig, type ArchitectureProfile, type ArchitectureRule, type ArkCheckConfig, type ArkKernel, type ArkManifest, type ArkManifestArchitecture, type ArkManifestData, type ArkManifestEntityLink, type ArkManifestGraph, type ArkManifestIntent, type ArkManifestPolicy, type ArkManifestProjection, type ArkTestHarness, type ArkTestSnapshot, type AuditQuery, type AuditRecord, type AuditRecordInput, type AuditRecordType, type AuditStore, type AuditTrail, type BuildPublishPolicyContextOptions, type ContractCheckResult, type CorrelationId, type CreateAdapterOptions, type CreateArchitectureProfileOptions, type CreateArkKernelOptions, type CreateArkManifestOptions, type CreateAuditTrailOptions, type CreateElevenLayerArkConfigOptions, type CreateObservabilityReporterOptions, type CreateProjectionRegistryOptions, type CreateWorkflowEngineOptions, type DefineIntentOptions, type DefinePolicyOptions, type DefinePortOptions, type DependencyGraph, type DomainEvent, type EntityMeta, type EventBus, type EventBusOptions, type EventContract, type EventContractIssue, type EventContractRegistry, EventContractRegistryImpl, type EventContractValidationResult, EventContractViolationError, type EventHandler, type EventInterceptionInfo, type EventInterceptor, type EventInterceptorContext, type EventMetadata, type EventPayloadPatch, type EventPayloadSchema, type EventPublisher, type EventSchemaField, type EventSchemaFieldType, type FieldMeta, type GraphEdge, type GraphNode, type GraphPolicyContext, InMemoryAuditStore, InMemoryOutboxStore, InMemoryReadModelStore, InMemoryWorkflowStore, type IntentCreator, type IntentCreator as IntentDefinition, type IntentName, type IntentNameValidation, IntentRegistry, type IntentRelationship, type IntentRelationshipKind, InvalidIntentNameError, type LayerFlowRule, LayerPolicyContextError, type LayerPolicyOptions, MANIFEST_SCHEMA_VERSION, type MetadataRegistry, type ObservabilityDriftReport, type ObservabilityFlow, type ObservabilityReporter, type ObservedLayerFlowMode, ObservedLayerFlowViolationError, type OutboxRecord, type OutboxStatus, type OutboxStore, type Policy, type PolicyEnforcementMode, PolicyEngine, type PolicyEvaluationResult, type PolicySeverity, type PolicyViolation, PolicyViolationError, type Port, type ProjectionCheckpoint, type ProjectionDefinition, type ProjectionRegistry, type PublishPolicyContext, type PublishedEventRecord, type ReadModelStore, type RetryPolicy, type SagaDefinition, type SagaInstance, type SagaStatus, type SagaStep, SourceMetadataOverrideError, type SyncRegistryOptions, type TraceRecord, type TraceRecordType, type TraceSink, UnknownEventSourceError, UnregisteredIntentError, type Unsubscribe, type WorkflowDefinition, type WorkflowEngine, type WorkflowSnapshot, type WorkflowStatus, type WorkflowStep, type WorkflowStore, architecturalPolicies, buildPublishPolicyContext, checkAdapterGovernance, checkContract, createAICodeGate, createAdapter, createArchitectureProfile, createArkKernel, createArkManifest, createArkTestHarness, createAuditTrail, createDependencyGraph, createElevenLayerArkConfig, createEventBus, createEventContractRegistry, createIntentRegistry, createLenientArkKernel, createMetadataRegistry, createObservabilityReporter, createProjectionRegistry, createSaga, createStrictArkKernel, createWorkflowEngine, defaultIntentRegistry, defineArchitectureProfilePolicy, defineIntent, defineLayerPolicy, definePolicy, definePort, definePublishPolicy, elevenLayerProfile, isLayerPolicy, syncRegistryToGraph, validateIntentName, version };