arkgate 4.8.22 → 4.8.24

package/dist/{types-yDNEQ603.d.ts → types-DRinG-vT.d.cts}

@@ -1,128 +1,355 @@
-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-fQ9-KrBj.js';
-
+type MaybePromise<T> = T | Promise<T>;
+type AuditRecordType = 'event.published' | 'event.rawPublish' | 'event.handoffFailed' | 'event.intercepted' | 'interceptor.error' | 'policy.softViolation' | 'policy.hardViolation' | 'layer.observedViolation' | 'layer.observedFlowUnresolvable' | 'handler.error' | 'hook.error' | 'workflow.started' | 'workflow.step.completed' | 'workflow.step.failed' | 'workflow.compensation.completed' | 'workflow.completed' | 'workflow.failed' | 'projection.applied' | 'metadata.changed';
+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;
+}
 /**
- * PolicyEngine
+ * Pluggable persistence for audit records.
  *
- * 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.
+ * **Durability stance (R9):** Default is `InMemoryAuditStore` — reference only, not
+ * production durability (lost on restart). Implement this interface for durable audit.
+ * See `docs/production-hardening.md`.
  */
-
-interface PolicyEvaluationResult {
-    passed: boolean;
-    violations: PolicyViolation[];
-    hardViolations: PolicyViolation[];
-    softViolations: PolicyViolation[];
+interface AuditStore {
+    append(record: AuditRecord): MaybePromise<void>;
+    query(query?: AuditQuery): MaybePromise<AuditRecord[]>;
+    clear(): MaybePromise<void>;
 }
 /**
- * The PolicyEngine is responsible for registering policies and evaluating
- * them against a given context.
+ * High-level audit API used by the event bus / kernel.
+ * Durability is that of the injected `AuditStore` (default in-memory).
  */
-declare class PolicyEngine<Context = unknown> {
-    private readonly policies;
-    constructor(initialPolicies?: Policy<Context>[]);
+interface AuditTrail {
+    record(input: AuditRecordInput): Promise<AuditRecord>;
+    query(query?: AuditQuery): Promise<AuditRecord[]>;
+    clear(): Promise<void>;
+}
+interface CreateAuditTrailOptions {
+    /** Durable store when provided; otherwise `InMemoryAuditStore` (not production durability). */
+    store?: AuditStore;
+    maxRecords?: number;
+}
+
+/**
+ * Type vocabulary for the ark.config.json contract (U02 pilot 1).
+ *
+ * Pure declarations only — no runtime values. The loader/validator logic and the
+ * published JSON Schema live in ./configContract.ts. Extra defaulting lives in
+ * ./configExtras.ts (generated sibling `config-extras.mjs`). Type-only imports
+ * from this file are erased on transpile.
+ */
+type ArkConfigSchemaVersion = '1.0' | '1.1' | '1.2' | '1.3';
+type ArkConfigCyclePolicy = 'strict' | 'soft' | 'framework-soft' | 'off';
+type ArkConfigLayerCapabilities = {
+    deny?: string[];
+};
+/** Who this folder is for. Metadata — not import-rule teeth. Absence is silent. */
+type ArkConfigLayerTrustBoundary = 'public' | 'auth' | 'admin' | 'internal';
+type ArkConfigLayer = {
+    name: string;
+    patterns: string[];
+    exclude?: string[];
+    intentPrefixes?: string[];
     /**
-     * Adds a policy to the engine.
+     * App-context caption for this layer.
+     * Metadata — excluded from policy hash. Absence is silent.
      */
-    add(policy: Policy<Context>): void;
+    description?: string;
     /**
-     * Returns all registered policies.
+     * Who this folder is for: public | auth | admin | internal.
+     * Metadata — excluded from policy hash. Absence is silent. Not host/CI TLS.
      */
-    getPolicies(): Policy<Context>[];
+    trustBoundary?: ArkConfigLayerTrustBoundary;
     /**
-     * Evaluates all policies against the provided context.
+     * Who owns this house: GitHub handles or emails (same identity as stewards).
+     * Metadata — excluded from policy hash. Absence is silent unless
+     * `requireLayerOwners` is true. Not import-rule teeth.
      */
-    evaluate(context: Context): PolicyEvaluationResult;
+    owners?: string[];
+    forbiddenGlobals?: string[];
+    /** ADR 0009 D2 — opt-in effect-capability walls; absence changes no verdict. */
+    capabilities?: ArkConfigLayerCapabilities;
+    /** Dual-depth sugar: `pure: true` denies all seven capabilities. */
+    pure?: boolean;
+    mayImportInfrastructure?: boolean;
+    optional?: boolean;
     /**
-     * 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
+     * Future house: empty globs are expected. `--strict-config` must not fail.
+     * Typo warning (`CONFIG_LAYER_PATTERN_NO_MATCHES`) is skipped.
      */
-    enforce(context: Context): PolicyEvaluationResult;
+    reserved?: boolean;
+    /** Alias of reserved — empty pattern matches are allowed. */
+    allowEmpty?: boolean;
+};
+/** How a starred `sliceFolders` prefix is named. Absent equals `path`. */
+type ArkConfigSliceIdentity = 'path' | 'stars';
+type ArkConfigRule = {
+    from: string;
+    to: string;
+    allowed: boolean;
+    message?: string;
+    peerIsolation?: boolean;
+    sliceFolders?: string[];
     /**
-     * Clears all registered policies.
+     * How a starred `sliceFolders` prefix is named.
+     * Absent and `path` keep today's ids. `stars` is the last literal plus every
+     * star binding (a star before the last literal is kept too).
      */
-    clear(): void;
-}
-
-/**
- * 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;
+    sliceIdentity?: ArkConfigSliceIdentity;
+    /** Roots the repo declares shared on purpose — evidence, not unclassifiable. */
+    sharedRoots?: string[];
+    /** Directed slice→slice edges the repo declares on purpose. */
+    allowedCrossSlice?: ArkConfigCrossSliceEdge[];
     /**
-     * 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
+     * `"deny"` blocks a shared root from importing a slice.
+     * `"deny-cross-parent"` leaves that hop allowed and asks the whole-graph
+     * check to report a slice that reaches another universe through shared.
+     * The object form carries `stopAt`: composition roots the walk never
+     * passes through.
      */
-    define<N extends IntentName, P = unknown>(name: N, options?: DefineIntentOptions): IntentCreator<N, P>;
+    sharedImportsSlice?: ArkConfigSharedImportsSlice;
     /**
-     * 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)
+     * Optional inner wall. Absent keeps today's universe-wall output.
+     * `siblings` defaults to deny. An object keeps that default and lists enforced subtrees.
+     * `parentMayImportChild` defaults to false.
      */
-    declareDependency(from: string, to: string): void;
+    childSlices?: ArkConfigChildSlices;
+};
+type ArkConfigSharedImportsSlice = 'deny' | 'deny-cross-parent' | {
+    mode: 'deny-cross-parent';
+    stopAt: string[];
+};
+type ArkConfigChildSlices = {
+    sliceFolders: string[];
+    sliceIdentity?: ArkConfigSliceIdentity;
+    commonFolders?: string[];
     /**
-     * Declare that one intent produces / emits another (e.g. use case → domain event).
+     * `ratchet` on the object form: absent turns the anti-growth ratchet on only
+     * when the baseline already records an advisory crossing of this rule;
+     * `true` always; `false` measures only.
      */
-    declareProduction(from: string, to: string): void;
+    siblings?: 'deny' | 'advisory' | {
+        default: 'deny' | 'advisory';
+        enforce?: string[];
+        ratchet?: boolean;
+    };
+    parentMayImportChild?: boolean;
+    /** Text for inner-wall findings (sibling, common → child). Absent: ArkGate default, never the rule message. */
+    message?: string;
     /**
-     * Retrieve a previously defined intent creator by name.
+     * Directed child-slice allowances. `*` is one whole path segment.
+     * Clears a sibling crossing only. The universe `allowedCrossSlice` does not read this list.
      */
-    get<N extends IntentName = IntentName, P = unknown>(name: string): IntentCreator<N, P> | undefined;
+    allowedCrossSlice?: ArkConfigCrossSliceEdge[];
     /**
-     * List all registered intent creators.
+     * Files outside the slice trees, borrowed onto a child id until they move.
+     * `to` is the universe id plus one child segment.
      */
-    list(): IntentCreator<IntentName, unknown>[];
+    sliceAliases?: ArkConfigSliceAlias[];
+};
+type ArkConfigSliceAlias = {
+    from: string;
+    to: string;
+};
+type ArkConfigCrossSliceEdge = {
+    from: string;
+    to: string;
+};
+type ArkConfigSafety = {
+    maxTsSuppressions?: number;
+    maxAnyCasts?: number;
+    allowInMemory?: boolean;
+    allowDisabledPeerIsolation?: boolean;
+};
+/**
+ * Optional invariant-coverage scan controls. Absence keeps the built-in
+ * defaults (test-name heuristic, 400-file budget) and changes no verdict.
+ */
+type ArkConfigCoverage = {
+    /** Globs that decide which files count as tests (replaces the name heuristic). */
+    testGlobs?: string[];
+    /** Max files loaded as coverage evidence before the budget is exhausted. */
+    maxFiles?: number;
     /**
-     * Get all declared dependencies for a given intent.
+     * Path prefixes where this project declares its test runner actually executes
+     * tests. ArkGate never runs anything: this is a second declaration to compare
+     * the coverage scan against, so a covering test found outside them is reported
+     * (INVARIANT_COVERAGE_OUTSIDE_ROOTS) instead of silently certifying the
+     * invariant. Absence is silent unless any catalogued invariant is enforced —
+     * then missing roots fail closed (INVARIANT_COVERAGE_ROOTS_MISSING).
      */
-    getDependencies(intentName: string): string[];
+    coverageRoots?: string[];
+};
+/**
+ * ADR 0012 — optional map of layer name → project-relative ArkRules file path.
+ * Absence changes no inter-layer verdict.
+ */
+type ArkConfigArkRulesRefs = Record<string, string>;
+/** ADR 0020 — advisory never adds merge teeth; enforced is the extra's merge plane. */
+type ArkConfigArkRunMode = 'advisory' | 'enforced';
+/**
+ * ADR 0020 — optional inline ArkRun extra (schema 1.2+). Absence is silent.
+ * Present objects are fully defaulted by the loader.
+ */
+type ArkConfigArkRun = {
+    mode: ArkConfigArkRunMode;
+    compositionRoots: string[];
+    kernelRoots?: string[];
+    managedLayers: string[];
+    requireDeclarations: boolean;
+    ignoreDirectNewForErrors?: boolean;
+};
+/** ADR 0027 — advisory never adds merge teeth; enforced is the extra's merge plane. */
+type ArkConfigArkOrderMode = 'advisory' | 'enforced';
+/**
+ * ADR 0027 — optional inline ArkOrder extra (schema 1.3+). Absence is silent.
+ * Present objects are fully defaulted by the loader.
+ */
+type ArkConfigArkOrder = {
+    mode: ArkConfigArkOrderMode;
+    planeRoots: string[];
+    managedLayers: string[];
     /**
-     * Get all intents produced / emitted by a given intent.
+     * Haken cap on one `release()` / `assertXiKeyCap` (default 7).
+     * Not a cap on the `xiKeys` watchlist length.
      */
-    getProductions(intentName: string): string[];
+    maxXiKeys: number;
     /**
-     * Get all declared relationships (useful for graph generation).
+     * Slow product keys the team can already name (plan, cost code, protocol).
+     * Optional. Empty → `ARKORDER_XI_FIELD_WRITE` stays silent.
+     * Repo-wide watchlist — not compared to `maxXiKeys`.
      */
-    getAllRelationships(): IntentRelationship[];
+    xiKeys: string[];
     /**
-     * Check if an intent name has been registered.
+     * Optional globs that narrow ξ field-write observation inside `managedLayers`.
+     * Same glob engine as `layers[].patterns`. Absence or empty → every file in
+     * those layers. Non-empty → emit only when the layer is managed AND the file
+     * matches at least one glob.
      */
-    has(name: string): boolean;
+    appliesTo?: string[];
+};
+type ArkConfig = {
+    $schema: string;
+    schemaVersion: ArkConfigSchemaVersion;
+    name?: string;
+    include: string[];
+    exclude?: string[];
+    excludeGenerated?: boolean;
+    frameworkOverlay?: string;
+    layers: ArkConfigLayer[];
+    rules: ArkConfigRule[];
+    cyclePolicy?: ArkConfigCyclePolicy;
+    dynamicImportAllowlist?: string[];
+    safety?: ArkConfigSafety;
     /**
-     * Clear the registry. Primarily useful for tests.
+     * Invariant-coverage scan controls (test globs + file budget).
+     * Absence keeps the defaults; it never turns coverage on by itself.
      */
-    clear(): void;
+    coverage?: ArkConfigCoverage;
+    /** ADR 0012 — modular ArkRules references (schema 1.1+). */
+    arkRules?: ArkConfigArkRulesRefs;
+    /** ADR 0020 — optional ArkRun extra (schema 1.2+). Absence changes no Layers/ArkRules verdict. */
+    arkRun?: ArkConfigArkRun;
+    /** ADR 0027 — optional ArkOrder extra (schema 1.3+). Absence changes no Layers/ArkRules/ArkRun verdict. */
+    arkOrder?: ArkConfigArkOrder;
+    /**
+     * Optional GitHub handles or emails who may loosen the contract or grow the baseline.
+     * Metadata — excluded from policy hash. Absence means no steward lock (policy-ack still applies).
+     */
+    stewards?: string[];
+    /**
+     * When true, every non-reserved layer must name `owners`. Absence/false is
+     * silent. This flag is policy teeth (stays in policyHash). Owners themselves
+     * stay metadata.
+     */
+    requireLayerOwners?: boolean;
+};
+/** Original input version when the loader rewrote schemaVersion toward current. */
+type ArkConfigMigratedFrom = 'unversioned' | '1.0' | '1.1' | '1.2' | null;
+type ArkConfigLoadResult = {
+    config: ArkConfig;
+    migratedFrom: ArkConfigMigratedFrom;
+};
+
+/**
+ * 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[];
+    /**
+     * Custom matcher for teams whose intent names don't follow prefix conventions.
+     * Checked before any prefix matching, in layer declaration order. A layer may
+     * use `match` alone (with `prefixes: []`), prefixes alone, or both.
+     */
+    match?: (name: string) => boolean;
+    description?: string;
+    trustBoundary?: 'public' | 'auth' | 'admin' | 'internal';
+    owners?: string[];
+    order?: number;
+}
+type ArchitectureRule = ArkConfigRule;
+interface ArchitectureProfile {
+    name: string;
+    layers: ArchitectureLayer[];
+    rules: ArchitectureRule[];
+    resolveLayer(name: string): string | undefined;
+}
+interface CreateArchitectureProfileOptions {
+    name: string;
+    layers: ArchitectureLayer[];
+    rules?: ArchitectureRule[];
+}
+interface CreateArchitectureProfileFromArkConfigOptions {
+    /** Runtime profile name. Default: config.name or "ark.config.json". */
+    name?: string;
+}
+type ArchitectureLayerConfig = ArkConfigLayer;
+type ArkCheckConfig = Omit<ArkConfig, '$schema' | 'schemaVersion' | 'rules'> & {
+    $schema?: string;
+    schemaVersion?: ArkConfig['schemaVersion'];
+    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;
 }
 
 /**
@@ -180,65 +407,161 @@ interface DependencyGraph {
     detectViolations(rules?: Array<(edges: GraphEdge[]) => string[]>): string[];
 }
 
-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;
+/**
+ * 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;
-    subject?: string;
-    details?: unknown;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    [key: string]: 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 DomainEvent<Name extends IntentName = IntentName, Payload = unknown> {
+    intent: Name;
+    payload: Payload;
+    metadata: EventMetadata;
 }
+
 /**
- * Pluggable persistence for audit records.
+ * Intent-specific types for the Ark kernel.
  *
- * **Durability stance (R9):** Default is `InMemoryAuditStore` — reference only, not
- * production durability (lost on restart). Implement this interface for durable audit.
- * See `docs/production-hardening.md`.
+ * Intents provide semantic naming for every important concept in the system
+ * (domain events, application operations, adapters, workflows).
  */
-interface AuditStore {
-    append(record: AuditRecord): MaybePromise<void>;
-    query(query?: AuditQuery): MaybePromise<AuditRecord[]>;
-    clear(): MaybePromise<void>;
+
+/**
+ * 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';
 /**
- * High-level audit API used by the event bus / kernel.
- * Durability is that of the injected `AuditStore` (default in-memory).
+ * Relationship declarations between intents.
+ * Used for dependency analysis and graph generation.
  */
-interface AuditTrail {
-    record(input: AuditRecordInput): Promise<AuditRecord>;
-    query(query?: AuditQuery): Promise<AuditRecord[]>;
-    clear(): Promise<void>;
+interface IntentRelationship {
+    from: string;
+    to: string;
+    kind: IntentRelationshipKind;
 }
-interface CreateAuditTrailOptions {
-    /** Durable store when provided; otherwise `InMemoryAuditStore` (not production durability). */
-    store?: AuditStore;
-    maxRecords?: number;
+
+/**
+ * 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;
 }
 
 type EventSchemaFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'unknown';
@@ -418,6 +741,102 @@ interface CreateProjectionRegistryOptions {
     auditTrail?: AuditTrail;
 }
 
+/**
+ * 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;
+}
+
 type EventBufferStatus = 'pending' | 'dispatched' | 'failed';
 interface EventBufferRecord {
     id: string;
@@ -464,7 +883,7 @@ type OutboxStore = EventBufferStore;
  */
 
 /** 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';
+type TraceRecordType = 'event.published' | 'event.rawPublish' | 'event.handoffFailed' | '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.
@@ -510,6 +929,15 @@ interface EventBusOptions<Context = unknown> {
     enforceObservedLayerFlow?: ObservedLayerFlowMode;
     /** Optional non-atomic event buffer for dispatch handoff. */
     eventBuffer?: EventBufferStore;
+    /**
+     * When true, the event-buffer record written for a publish is marked
+     * `dispatched` once local delivery finishes (handlers + onPublish), or `failed`
+     * when a rethrown handler error aborts it. Use only when no external relay
+     * drains the buffer. Default: false — records stay `pending` for a
+     * consumer-owned relay (`claim` / `markDispatched`). `createArkKernel` turns
+     * this on for its default in-memory buffer only.
+     */
+    settleBufferOnLocalDelivery?: boolean;
     /** @deprecated Use eventBuffer. */
     outbox?: EventBufferStore;
     /** Stable id stamped into event metadata for this kernel/event bus instance. */
@@ -604,6 +1032,14 @@ interface EventDispatchControl {
     awaitHandlers?: boolean;
     runOnPublish?: boolean;
     tx?: unknown;
+    /**
+     * When false, skip local-delivery settlement of the buffer record even if the
+     * bus settles on local delivery (the caller owns the outcome, e.g. a broker
+     * handoff). Default: the bus `settleBufferOnLocalDelivery` option.
+     */
+    settleBufferOnLocalDelivery?: boolean;
+    /** Receives the event-buffer record written for this publish, when any. */
+    onBufferRecord?: (record: EventBufferRecord) => void;
 }
 /**
  * The public EventBus interface.
@@ -1353,4 +1789,4 @@ interface CreateArkKernelFromConfigOptions extends Omit<CreateArkKernelOptions,
 }
 type ArkKernelConfig = ArkCheckConfig;
 
-export { ARK_RUN_INSPECTOR_EVENTS_PATH as $, type ArkKernel as A, type OutboxStatus as B, type CreateArkKernelOptions as C, type DefineIntentOptions as D, type EventContractRegistry as E, type OutboxRecord as F, type GraphEdge as G, type ObservabilityDriftReport as H, IntentRegistry as I, ARK_RUN_COMPONENT_LIFETIMES as J, ARK_RUN_EPHEMERAL_DEFAULT as K, ARK_RUN_GRAPH_DEFAULT_SLICE as L, type MetadataRegistry as M, ARK_RUN_GRAPH_NODE_KINDS as N, type ObservabilityReporter as O, type ProjectionRegistry as P, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as Q, type ReadModelStore as R, type SagaContext as S, type TraceRecordType as T, ARK_RUN_GRAPH_SCHEMA_VERSION as U, ARK_RUN_GRAPH_SLICES as V, type WorkflowStore as W, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as X, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as Y, ARK_RUN_INSPECTOR_DEFAULT_HOST as Z, ARK_RUN_INSPECTOR_DEFAULT_PORT as _, type DependencyGraph as a, type EventContractIssue as a$, ARK_RUN_INSPECTOR_GRAPH_PATH as a0, ARK_RUN_INSPECTOR_MONITOR_SAMPLE_LIMIT as a1, ARK_RUN_INSPECTOR_OUTBOX_PATH as a2, ARK_RUN_INSPECTOR_SCHEMA_VERSION as a3, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as a4, ARK_RUN_INSPECTOR_SSE_EVENT as a5, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as a6, ARK_RUN_INSPECTOR_WORKFLOWS_PATH as a7, ARK_RUN_TRANSPORT_KINDS as a8, type ArkManifestArchitecture as a9, type ArkRunInspectorHandle as aA, type ArkRunInspectorHardening as aB, type ArkRunInspectorHardeningDurability as aC, type ArkRunInspectorMonitorBuildOptions as aD, type ArkRunInspectorOutboxMonitor as aE, type ArkRunInspectorOutboxRecordSummary as aF, ArkRunInspectorProductionError as aG, type ArkRunInspectorSnapshot as aH, type ArkRunInspectorSnapshotInput as aI, type ArkRunInspectorSource as aJ, type ArkRunInspectorStoreDurability as aK, type ArkRunInspectorStoreDurabilityKind as aL, type ArkRunInspectorStoreRole as aM, type ArkRunInspectorTransportFacts as aN, type ArkRunInspectorWorkflowSummary as aO, type ArkRunInspectorWorkflowsMonitor as aP, type ArkRunPublisher as aQ, type ArkRunRegisterOptions as aR, type ArkRunRegistrationHandle as aS, type ArkRunSendOptions as aT, type ArkRunSendPlan as aU, type ArkRunSendPlanInput as aV, type ArkRunSendResult as aW, type ArkRunTransportKind as aX, type AuditRecordInput as aY, type AuditRecordType as aZ, type EntityMeta as a_, type ArkManifestData as aa, type ArkManifestEntityLink as ab, type ArkManifestGraph as ac, type ArkManifestIntent as ad, type ArkManifestPolicy as ae, type ArkManifestProjection as af, type ArkRunBrokerAdapter as ag, type ArkRunComponentLifetime as ah, type ArkRunDeliveredVia as ai, type ArkRunExtendedInfo as aj, type ArkRunGraph as ak, type ArkRunGraphEdge as al, type ArkRunGraphEdgeKind as am, type ArkRunGraphMatch as an, type ArkRunGraphMatchInput as ao, type ArkRunGraphNode as ap, type ArkRunGraphNodeKind as aq, type ArkRunGraphProcessEdgeKind as ar, type ArkRunGraphQuery as as, type ArkRunGraphResolvedQuery as at, type ArkRunGraphSlice as au, type ArkRunGraphTechnicalEdgeKind as av, type ArkRunInformationPackageComponent as aw, type ArkRunInspectorBind as ax, ArkRunInspectorBindError as ay, type ArkRunInspectorBindInput as az, type AuditStore as b, type EventHandler as b0, type EventInterceptionInfo as b1, type EventInterceptor as b2, type EventInterceptorContext as b3, type EventPayloadPatch as b4, type EventPayloadSchema as b5, type EventPublisher as b6, type EventSchemaField as b7, type EventSchemaFieldType as b8, type FieldMeta as b9, buildDependencyInformationPackage as bA, classifyArkRunInspectorStoreDurability as bB, closeArkRunGraphQuery as bC, closedArkRunEphemeral as bD, closedArkRunTransportKind as bE, formatArkRunGraphMermaid as bF, formatArkRunInspectorSseEvent as bG, isArkRunInspectorLoopbackHost as bH, isArkRunInspectorProductionEnv as bI, requestArkRunGraph as bJ, resolveArkRunInspectorBind as bK, resolveArkRunSendPlan as bL, startArkRunInspector as bM, unavailableArkRunInspectorOutboxMonitor as bN, unavailableArkRunInspectorWorkflowsMonitor as bO, type GraphNode as ba, InvalidArkRunGraphQueryError as bb, InvalidArkRunSendOptionError as bc, type ObservabilityFlow as bd, type ObservedLayerFlowMode as be, type OutboxStore as bf, type PolicyEvaluationResult as bg, type ProjectionCheckpoint as bh, type ProjectionDefinition as bi, type PublishedEventRecord as bj, type RetryPolicy as bk, type SagaStatus as bl, type SagaStep as bm, type StartArkRunInspectorOptions as bn, type TraceSink as bo, type Unsubscribe as bp, type WorkflowDefinition as bq, type WorkflowStatus as br, type WorkflowStep as bs, appendDecisionTape as bt, arkRunGraphQueryFromSearchParams as bu, arkRunInspectorUrl as bv, buildArkRunInspectorHardening as bw, buildArkRunInspectorOutboxMonitor as bx, buildArkRunInspectorSnapshot as by, buildArkRunInspectorWorkflowsMonitor as bz, type AuditRecord as c, type AuditQuery as d, type CreateAuditTrailOptions as e, type AuditTrail as f, type EventContract as g, type EventContractValidationResult as h, type CreateProjectionRegistryOptions as i, type EventBufferStore as j, type EventBufferRecord as k, type EventBufferStatus as l, type EventBusOptions as m, type EventBus as n, type CreateObservabilityReporterOptions as o, PolicyEngine as p, type ArkManifest as q, type WorkflowSnapshot as r, type SagaDefinition as s, type CreateWorkflowEngineOptions as t, type SagaInstance as u, type WorkflowEngine as v, type DependencyInformationPackage as w, type ArkKernelConfig as x, type CreateArkKernelFromConfigOptions as y, type TraceRecord as z };
+export { type OutboxRecord as $, type ArkKernel as A, type EventBus as B, type CreateArkKernelOptions as C, type DependencyGraph as D, type EventContractRegistry as E, type CreateObservabilityReporterOptions as F, type GraphEdge as G, PolicyEngine as H, IntentRegistry as I, type ArkManifest as J, type WorkflowSnapshot as K, type SagaDefinition as L, type MetadataRegistry as M, type CreateWorkflowEngineOptions as N, type ObservabilityReporter as O, type ProjectionRegistry as P, type SagaInstance as Q, type ReadModelStore as R, type SagaContext as S, type WorkflowEngine as T, type DependencyInformationPackage as U, type ArkKernelConfig as V, type WorkflowStore as W, type CreateArkKernelFromConfigOptions as X, type TraceRecordType as Y, type TraceRecord as Z, type OutboxStatus as _, type AuditStore as a, type ArkRunInspectorSource as a$, type ObservabilityDriftReport as a0, type ArkConfig as a1, type ArkConfigLoadResult as a2, ARK_RUN_COMPONENT_LIFETIMES as a3, ARK_RUN_EPHEMERAL_DEFAULT as a4, ARK_RUN_GRAPH_DEFAULT_SLICE as a5, ARK_RUN_GRAPH_NODE_KINDS as a6, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as a7, ARK_RUN_GRAPH_SCHEMA_VERSION as a8, ARK_RUN_GRAPH_SLICES as a9, type ArkRunDeliveredVia as aA, type ArkRunExtendedInfo as aB, type ArkRunGraph as aC, type ArkRunGraphEdge as aD, type ArkRunGraphEdgeKind as aE, type ArkRunGraphMatch as aF, type ArkRunGraphMatchInput as aG, type ArkRunGraphNode as aH, type ArkRunGraphNodeKind as aI, type ArkRunGraphProcessEdgeKind as aJ, type ArkRunGraphQuery as aK, type ArkRunGraphResolvedQuery as aL, type ArkRunGraphSlice as aM, type ArkRunGraphTechnicalEdgeKind as aN, type ArkRunInformationPackageComponent as aO, type ArkRunInspectorBind as aP, ArkRunInspectorBindError as aQ, type ArkRunInspectorBindInput as aR, type ArkRunInspectorHandle as aS, type ArkRunInspectorHardening as aT, type ArkRunInspectorHardeningDurability as aU, type ArkRunInspectorMonitorBuildOptions as aV, type ArkRunInspectorOutboxMonitor as aW, type ArkRunInspectorOutboxRecordSummary as aX, ArkRunInspectorProductionError as aY, type ArkRunInspectorSnapshot as aZ, type ArkRunInspectorSnapshotInput as a_, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as aa, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as ab, ARK_RUN_INSPECTOR_DEFAULT_HOST as ac, ARK_RUN_INSPECTOR_DEFAULT_PORT as ad, ARK_RUN_INSPECTOR_EVENTS_PATH as ae, ARK_RUN_INSPECTOR_GRAPH_PATH as af, ARK_RUN_INSPECTOR_MONITOR_SAMPLE_LIMIT as ag, ARK_RUN_INSPECTOR_OUTBOX_PATH as ah, ARK_RUN_INSPECTOR_SCHEMA_VERSION as ai, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as aj, ARK_RUN_INSPECTOR_SSE_EVENT as ak, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as al, ARK_RUN_INSPECTOR_WORKFLOWS_PATH as am, ARK_RUN_TRANSPORT_KINDS as an, type ArchitectureLayer as ao, type ArchitectureLayerConfig as ap, type ArchitectureRule as aq, type ArkManifestArchitecture as ar, type ArkManifestData as as, type ArkManifestEntityLink as at, type ArkManifestGraph as au, type ArkManifestIntent as av, type ArkManifestPolicy as aw, type ArkManifestProjection as ax, type ArkRunBrokerAdapter as ay, type ArkRunComponentLifetime as az, type AuditRecord as b, formatArkRunInspectorSseEvent as b$, type ArkRunInspectorStoreDurability as b0, type ArkRunInspectorStoreDurabilityKind as b1, type ArkRunInspectorStoreRole as b2, type ArkRunInspectorTransportFacts as b3, type ArkRunInspectorWorkflowSummary as b4, type ArkRunInspectorWorkflowsMonitor as b5, type ArkRunPublisher as b6, type ArkRunRegisterOptions as b7, type ArkRunRegistrationHandle as b8, type ArkRunSendOptions as b9, type OutboxStore as bA, type PolicyEvaluationResult as bB, type ProjectionCheckpoint as bC, type ProjectionDefinition as bD, type PublishedEventRecord as bE, type RetryPolicy as bF, type SagaStatus as bG, type SagaStep as bH, type StartArkRunInspectorOptions as bI, type TraceSink as bJ, type Unsubscribe as bK, type WorkflowDefinition as bL, type WorkflowStatus as bM, type WorkflowStep as bN, appendDecisionTape as bO, arkRunGraphQueryFromSearchParams as bP, arkRunInspectorUrl as bQ, buildArkRunInspectorHardening as bR, buildArkRunInspectorOutboxMonitor as bS, buildArkRunInspectorSnapshot as bT, buildArkRunInspectorWorkflowsMonitor as bU, buildDependencyInformationPackage as bV, classifyArkRunInspectorStoreDurability as bW, closeArkRunGraphQuery as bX, closedArkRunEphemeral as bY, closedArkRunTransportKind as bZ, formatArkRunGraphMermaid as b_, type ArkRunSendPlan as ba, type ArkRunSendPlanInput as bb, type ArkRunSendResult as bc, type ArkRunTransportKind as bd, type AuditRecordInput as be, type AuditRecordType as bf, type CorrelationId as bg, type EntityMeta as bh, type EventContractIssue as bi, type EventHandler as bj, type EventInterceptionInfo as bk, type EventInterceptor as bl, type EventInterceptorContext as bm, type EventMetadata as bn, type EventPayloadPatch as bo, type EventPayloadSchema as bp, type EventPublisher as bq, type EventSchemaField as br, type EventSchemaFieldType as bs, type FieldMeta as bt, type GraphNode as bu, type IntentRelationshipKind as bv, InvalidArkRunGraphQueryError as bw, InvalidArkRunSendOptionError as bx, type ObservabilityFlow as by, type ObservedLayerFlowMode as bz, type AuditQuery as c, isArkRunInspectorLoopbackHost as c0, isArkRunInspectorProductionEnv as c1, requestArkRunGraph as c2, resolveArkRunInspectorBind as c3, resolveArkRunSendPlan as c4, startArkRunInspector as c5, unavailableArkRunInspectorOutboxMonitor as c6, unavailableArkRunInspectorWorkflowsMonitor as c7, type CreateAuditTrailOptions as d, type AuditTrail as e, type CreateArchitectureProfileOptions as f, type ArchitectureProfile as g, type ArkCheckConfig as h, type CreateArchitectureProfileFromArkConfigOptions as i, type CreateElevenLayerArkConfigOptions as j, type EventContract as k, type DomainEvent as l, type EventContractValidationResult as m, type IntentName as n, type DefineIntentOptions as o, type IntentCreator as p, type CreateProjectionRegistryOptions as q, type PolicyViolation as r, type PolicySeverity as s, type PolicyEnforcementMode as t, type Policy as u, type IntentRelationship as v, type EventBufferStore as w, type EventBufferRecord as x, type EventBufferStatus as y, type EventBusOptions as z };