@angriff36/manifest 2.18.0

package/dist/manifest/runtime-engine.d.ts

@@ -0,0 +1,1019 @@
+import { IR, IRProvenance, IREntity, IRCommand, IRPolicy, IRExpression, ConstraintOutcome, OverrideRequest, ConcurrencyConflict, JobQueue, JobRecord } from './ir';
+import type { IRSchedule } from './ir';
+/**
+ * Spec-guaranteed runtime context bindings (see docs/spec/semantics.md
+ * § "Runtime Context Schema" and docs/spec/builtins.md § "Context Member
+ * Access"). Every typed field is optional at the type level; per spec,
+ * tenant-scoped commands MUST fail closed with `MISSING_TENANT_CONTEXT`
+ * when `tenantId` is absent and `requireTenantContext` is set on
+ * RuntimeOptions.
+ *
+ * The index signature is preserved for backwards compatibility — existing
+ * callers may attach ad-hoc keys without a type-level change.
+ */
+export interface RuntimeContext {
+    /** Active tenant identifier. Required for tenant-scoped commands. */
+    tenantId?: string;
+    /** Active organization identifier (e.g. Clerk orgId). */
+    orgId?: string;
+    /** Acting user identifier. */
+    actorId?: string;
+    /** Caller-supplied request id; surfaces in diagnostics and emitted events. */
+    requestId?: string;
+    /** Origin surface: 'route' | 'job' | 'cli' | 'test' | 'ui' | 'workflow' (or other). */
+    source?: string;
+    /** If true, adapter actions throw ManifestEffectBoundaryError. options.deterministicMode wins if both set. */
+    deterministic?: boolean;
+    /** Legacy actor shorthand. Prefer `actorId` for new code. */
+    user?: {
+        id: string;
+        role?: string;
+        [key: string]: unknown;
+    };
+    /** Open extension surface; legacy callers still rely on free keys. */
+    [key: string]: unknown;
+}
+/**
+ * Pluggable encryption provider for field-level encryption.
+ * When supplied via RuntimeOptions.encryptionProvider, properties with the
+ * `encrypted` modifier are transparently encrypted on write and decrypted
+ * on read at the store boundary. The envelope format supports key rotation:
+ * `{"v":1,"kid":"<keyId>","ct":"<ciphertext>"}`.
+ */
+export interface EncryptionProvider {
+    encrypt(plaintext: string): Promise<{
+        ciphertext: string;
+        keyId: string;
+    }>;
+    decrypt(ciphertext: string, keyId: string): Promise<string>;
+}
+/**
+ * Middleware hook types. Each corresponds to a lifecycle point in command
+ * execution where middleware can observe, patch context, or short-circuit.
+ */
+export type MiddlewareHook = 'before-policy' | 'before-guard' | 'before-action' | 'after-emit';
+/**
+ * Context passed to middleware handlers at each lifecycle points.
+ */
+export interface MiddlewareContext {
+    /** Which lifecycle hook triggered this middleware call */
+    hook: MiddlewareHook;
+    /** The IR command being executed */
+    command: IRCommand;
+    /** The current expression evaluation context (read/write via contextPatch) */
+    evalContext: Record<string, unknown>;
+    /** The original input to the command */
+    input: Record<string, unknown>;
+    /** The runtime context (user, tenantId, etc.) */
+    runtimeContext: RuntimeContext;
+    /** Entity name, if applicable */
+    entityName?: string;
+    /** Instance ID, if applicable */
+    instanceId?: string;
+    /** Events emitted so far (populated in after-emit hook) */
+    emittedEvents: EmittedEvent[];
+}
+/**
+ * Result returned by a middleware handler.
+ * - Empty object `{}` means "continue normally".
+ * - `contextPatch` merges additional values into the evalContext.
+ * - `shortCircuit` immediately returns the provided CommandResult.
+ */
+export interface MiddlewareResult {
+    contextPatch?: Record<string, unknown>;
+    shortCircuit?: boolean;
+    result?: CommandResult;
+}
+/**
+ * A middleware instance: declares which hooks it participates in and
+ * a handler function called at each matching lifecycle points.
+ */
+export interface Middleware {
+    hooks: MiddlewareHook[];
+    handler: (ctx: MiddlewareContext) => Promise<MiddlewareResult>;
+}
+export interface RuntimeOptions {
+    generateId?: () => string;
+    now?: () => number;
+    /**
+     * Optional middleware pipeline. Middleware are executed in declaration order
+     * at each matching lifecycle hook during command execution.
+     */
+    middleware?: Middleware[];
+    /**
+     * If true, runtime will verify IR integrity hash before execution.
+     * When an IR hash doesn't match, the runtime will throw an error.
+     * Set to false for development/debugging mode.
+     *
+     * @default
+     * - `true` in production (NODE_ENV=production)
+     * - `false` in development
+     *
+     * Explicit dev override: Set to `false` to disable verification in production for debugging.
+     */
+    requireValidProvenance?: boolean;
+    /**
+     * Optional: expected IR hash for verification. If provided and requireValidProvenance is true,
+     * the runtime will verify the IR's hash matches this value.
+     * If not provided, the runtime will verify the IR's self-reported hash.
+     */
+    expectedIRHash?: string;
+    /**
+     * Optional function to provide custom store implementations for entities.
+     * Called with the entity name and should return a Store instance or undefined.
+     * If undefined is returned, the runtime will use its default store initialization.
+     *
+     * This allows using server-side stores like PostgresStore and SupabaseStore from stores.node.ts.
+     *
+     * @example
+     * ```typescript
+     * import { PostgresStore } from './stores.node.js';
+     *
+     * const runtime = new RuntimeEngine(ir, context, {
+     *   storeProvider: (entityName) => {
+     *     if (entityName === 'User' || entityName === 'Post') {
+     *       return new PostgresStore({
+     *         connectionString: process.env.DATABASE_URL,
+     *         tableName: entityName.toLowerCase()
+     *       });
+     *     }
+     *     return undefined; // Use default store
+     *   }
+     * });
+     * ```
+     */
+    storeProvider?: (entityName: string) => Store | undefined;
+    /** Caller-provided idempotency store for command deduplication */
+    idempotencyStore?: IdempotencyStore;
+    /**
+     * If true, adapter actions (persist/publish/effect) throw ManifestEffectBoundaryError
+     * instead of the default no-op behavior. Use for conformance testing and replay validation.
+     * See docs/spec/adapters.md for the normative exception.
+     */
+    deterministicMode?: boolean;
+    /** Optional complexity limits for expression evaluation */
+    evaluationLimits?: EvaluationLimits;
+    /**
+     * If true, any `runCommand` invocation MUST fail closed with diagnostic
+     * `MISSING_TENANT_CONTEXT` when `context.tenantId` is absent or empty.
+     * Use to enforce tenant-scoped command semantics in multi-tenant apps.
+     * Default: false (backwards compatible — legacy callers unaffected).
+     */
+    requireTenantContext?: boolean;
+    /**
+     * Optional custom builtin functions from plugins or project configuration.
+     * These are merged with core builtins; core builtins always take precedence
+     * on name collision. Populated by the plugin loader from BuiltinFunctionPlugin
+     * registrations.
+     *
+     * @see plugin-api.ts BuiltinFunctionPlugin
+     */
+    customBuiltins?: Map<string, (...args: unknown[]) => unknown>;
+    /**
+     * Optional AuditSink for durable audit records.
+     * When supplied, the runtime is contracted to call sink.emit() exactly
+     * once per command invocation. Contract: src/manifest/audit/audit-sink.ts.
+     * Wire-in is contract-only in this release; actual emission lands in
+     * the audit/outbox implementation follow-on.
+     */
+    auditSink?: import('./audit/audit-sink').AuditSink;
+    /**
+     * Optional OutboxStore for transactional event persistence.
+     * Contract: src/manifest/outbox/outbox-store.ts. Contract-only wire-in
+     * in this release; transactional integration lands in the follow-on.
+     */
+    outboxStore?: import('./outbox/outbox-store').OutboxStore;
+    /**
+     * Optional durable ApprovalStore for multi-stage approval persistence.
+     * When supplied, pending approval requests, stage grants, and denials are
+     * read from and written to this store, so an approval created by one
+     * engine instance is visible to a freshly-constructed engine (the normal
+     * stateless-per-request pattern). When omitted, approval state lives in an
+     * in-process Map (single-process / test use only).
+     * Contract: src/manifest/approval/approval-store.ts. Memory + Postgres
+     * adapters ship via "./approval/memory" and "./approval/postgres".
+     */
+    approvalStore?: import('./approval/approval-store').ApprovalStore;
+    /**
+     * Optional feature flag provider function.
+     * Called with a flag name and returns the flag value (boolean, string, number, or object).
+     * Enables the `flag(name)` built-in to resolve feature flags declaratively
+     * from any provider (LaunchDarkly, Unleash, JSON file, etc.).
+     *
+     * When not provided, `flag(name)` returns `false` (safe default — features off).
+     *
+     * @example
+     * ```typescript
+     * const runtime = new RuntimeEngine(ir, context, {
+     *   flagProvider: (name) => launchDarklyClient.variation(name, false),
+     * });
+     * ```
+     */
+    flagProvider?: (name: string) => unknown;
+    /**
+     * Optional JobQueue for async command execution.
+     * When an async command is invoked, the runtime enqueues a job and returns
+     * a JobId immediately. Use `drainJobs()` for deterministic testing.
+     */
+    jobQueue?: JobQueue;
+    /**
+     * Optional WASM expression evaluator for near-native execution speed.
+     * When provided, the runtime will use the WASM module for expression
+     * evaluation and constraint validation. Falls back to the TypeScript
+     * evaluator transparently if the WASM module fails to load or evaluate.
+     *
+     * The WASM evaluator maintains identical semantics to the TypeScript
+     * implementation, so swapping in/out is safe and observable only via
+     * performance characteristics.
+     *
+     * @see src/manifest/wasm/wasm-evaluator.ts
+     */
+    wasmEvaluator?: import('./wasm/wasm-evaluator').WasmExpressionEvaluator;
+    /**
+     * Optional encryption provider for field-level encryption.
+     * When supplied, properties with the `encrypted` modifier are transparently
+     * encrypted before store writes and decrypted after store reads.
+     * No-op when omitted (plaintext stored — safe for dev/test).
+     */
+    encryptionProvider?: EncryptionProvider;
+    /**
+     * Optional profiling configuration. When enabled, the runtime collects
+     * per-phase timing data for each command execution. Profiles are
+     * accessible via `engine.getProfiles()`.
+     */
+    profiling?: import('./profiling').ProfilingOptions;
+    /** Optional per-action trace hook for @angriff36/manifest/debug CommandTraceRecorder */
+    actionTraceHook?: (info: {
+        index: number;
+        kind: string;
+        target?: string;
+        entityName?: string;
+        instanceId?: string;
+    }) => void | Promise<void>;
+    /** Injectable sleep for deterministic retry backoff in tests/adapters */
+    sleep?: (ms: number) => Promise<void>;
+    /** Deterministic jitter override for retry delays (used when retry.jitter is true) */
+    retryJitter?: (delayMs: number) => number;
+}
+export type { AuditSink, AuditRecord, CommandOutcome } from './audit/audit-sink';
+export type { OutboxStore, OutboxEntry, OutboxEntryStatus } from './outbox/outbox-store';
+export type { ApprovalStore } from './approval/approval-store';
+export type { JobQueue, JobRecord } from './ir';
+export interface EntityInstance {
+    id: string;
+    /** For optimistic concurrency control (optional) */
+    version?: number;
+    /** Timestamp of last version change (optional) */
+    versionAt?: number;
+    [key: string]: unknown;
+}
+export interface CommandResult {
+    success: boolean;
+    result?: unknown;
+    instance?: EntityInstance;
+    error?: string;
+    deniedBy?: string;
+    guardFailure?: GuardFailure;
+    policyDenial?: PolicyDenial;
+    /** All constraint evaluation outcomes (vNext) */
+    constraintOutcomes?: ConstraintOutcome[];
+    /** Pending override requests (vNext) */
+    overrideRequests?: OverrideRequest[];
+    /** Concurrency conflict details (vNext) */
+    concurrencyConflict?: ConcurrencyConflict;
+    /** Approval workflow required before command can execute */
+    approvalRequired?: ApprovalRequiredInfo;
+    /** Caller-supplied correlation ID grouping related events across a workflow */
+    correlationId?: string;
+    /** Caller-supplied ID of the event/command that caused this command execution */
+    causationId?: string;
+    emittedEvents: EmittedEvent[];
+    /** Retry metadata when command declares a retry policy */
+    retry?: {
+        attempts: number;
+        exhausted: boolean;
+        lastErrorCode?: string;
+        delaysMs: number[];
+    };
+    /** Rate limit denial when a command or policy rate limiter blocks execution */
+    rateLimitDenial?: {
+        scope: 'user' | 'tenant' | 'global';
+        scopeKey: string;
+        limit: number;
+        windowMs: number;
+        retryAfterMs: number;
+    };
+}
+export interface GuardFailure {
+    index: number;
+    expression: IRExpression;
+    formatted: string;
+    resolved?: GuardResolvedValue[];
+}
+export interface PolicyDenial {
+    policyName: string;
+    expression: IRExpression;
+    formatted: string;
+    message?: string;
+    contextKeys: string[];
+    /** Resolved values from the policy expression evaluation */
+    resolved?: GuardResolvedValue[];
+}
+export interface GuardResolvedValue {
+    expression: string;
+    value: unknown;
+}
+export interface ConstraintFailure {
+    constraintName: string;
+    expression: IRExpression;
+    formatted: string;
+    message?: string;
+    resolved?: GuardResolvedValue[];
+}
+export interface ApprovalGrant {
+    stage: string;
+    by: string;
+    at: number;
+}
+export interface ApprovalRequestState {
+    entity: string;
+    instanceId: string;
+    approvalName: string;
+    command: string;
+    status: 'pending' | 'granted' | 'denied' | 'expired';
+    /** Stages whose `when` condition evaluated true (or had no `when`) */
+    requiredStages: string[];
+    grants: ApprovalGrant[];
+    requestedAt: number;
+    expiresAt?: number;
+    deniedReason?: string;
+    deniedBy?: string;
+}
+/**
+ * Identity of a user approving a stage. A bare string is the legacy form
+ * where the userId doubles as the role (kept for backward compatibility).
+ * Prefer the object form to express real RBAC — `role`/`roles`/permissions
+ * are made available to the stage policy as `user.*`, independent of `id`.
+ */
+export type ApprovalApprover = string | {
+    id: string;
+    role?: string;
+    roles?: string[];
+    [key: string]: unknown;
+};
+export interface ApprovalRequiredInfo {
+    approvalName: string;
+    pendingStages: string[];
+    requestKey: string;
+}
+/**
+ * Canonical subject metadata identifying the originating entity, command,
+ * and target instance for an emitted event. Populated by the runtime during
+ * `runCommand` so downstream consumers can reliably route and correlate
+ * events without inspecting payload internals.
+ */
+export interface EventSubject {
+    /** The Manifest entity name associated with the command, when available. */
+    entity?: string;
+    /** The Manifest command name that emitted the event. */
+    command: string;
+    /** The canonical target instance id, resolved deterministically. */
+    id?: string;
+}
+export interface EmittedEvent {
+    name: string;
+    channel: string;
+    payload: unknown;
+    timestamp: number;
+    /** Canonical subject metadata for the originating entity/command/instance. */
+    subject?: EventSubject;
+    /** Provenance information from the IR at the time of event emission */
+    provenance?: {
+        contentHash: string;
+        compilerVersion: string;
+        schemaVersion: string;
+    };
+    /** Caller-supplied correlation ID grouping related events across a workflow */
+    correlationId?: string;
+    /** Caller-supplied ID of the event/command that caused this emission */
+    causationId?: string;
+    /** Zero-based index of this event within the current runCommand invocation. Per-command only. */
+    emitIndex?: number;
+}
+export interface SagaStepResult {
+    step: string;
+    command: string;
+    /**
+     * - `completed`           — forward command succeeded
+     * - `failed`              — forward command failed (the step that triggered compensation)
+     * - `compensated`         — forward command was successfully reversed by its compensation
+     * - `compensation_failed` — a compensation was attempted but failed its guard/policy or threw;
+     *                           the step is NOT considered reversed (potential dangling state)
+     * - `skipped`             — completed step had no compensation declared (nothing to reverse)
+     */
+    status: 'completed' | 'failed' | 'compensated' | 'compensation_failed' | 'skipped';
+    result?: CommandResult;
+    compensation?: CommandResult;
+    error?: string;
+}
+export interface SagaResult {
+    saga: string;
+    success: boolean;
+    status: 'completed' | 'compensated' | 'aborted';
+    steps: SagaStepResult[];
+    emittedEvents: EmittedEvent[];
+    failedStep?: string;
+    error?: string;
+}
+export interface Store<T extends EntityInstance = EntityInstance> {
+    getAll(): Promise<T[]>;
+    getById(id: string): Promise<T | undefined>;
+    create(data: Partial<T>): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<T | undefined>;
+    delete(id: string): Promise<boolean>;
+    clear(): Promise<void>;
+}
+export interface IdempotencyStore {
+    /** Check if a command with this key has already been executed */
+    has(key: string): Promise<boolean>;
+    /** Record a command result for an idempotency key */
+    set(key: string, result: CommandResult): Promise<void>;
+    /** Retrieve the cached result for an idempotency key */
+    get(key: string): Promise<CommandResult | undefined>;
+}
+/**
+ * Thrown when an adapter action (persist/publish/effect) is executed in deterministicMode.
+ * This is a programming error, not a domain failure.
+ * See docs/spec/adapters.md for the normative exception to default no-op behavior.
+ */
+export declare class ManifestEffectBoundaryError extends Error {
+    readonly actionKind: string;
+    constructor(actionKind: string);
+}
+/**
+ * Thrown when reaction cascading exceeds the maximum depth (default: 10).
+ * Indicates a potential infinite loop in reaction chains.
+ * See docs/spec/semantics.md § "Reactions".
+ */
+export declare class ManifestReactionDepthError extends Error {
+    readonly depth: number;
+    readonly triggerEvent: string;
+    readonly targetCommand: string;
+    constructor(depth: number, triggerEvent: string, targetCommand: string);
+}
+/**
+ * In-memory JobQueue implementation for async commands.
+ * Suitable for testing and development. Production deployments should
+ * provide a durable implementation (e.g. database-backed).
+ */
+export declare class MemoryJobQueue implements JobQueue {
+    private jobs;
+    enqueue(job: JobRecord): Promise<void>;
+    drainPending(): Promise<JobRecord[]>;
+    updateStatus(jobId: string, status: JobRecord['status'], detail?: {
+        result?: unknown;
+        error?: string;
+    }): Promise<void>;
+    /** Test utility: get all jobs */
+    getAll(): JobRecord[];
+}
+/**
+ * Thrown when expression evaluation exceeds configured depth or step limits.
+ * This is a domain failure (caught and converted to CommandResult), not a programming error.
+ * See docs/spec/manifest-vnext.md § "Diagnostic Payload Bounding".
+ */
+export declare class EvaluationBudgetExceededError extends Error {
+    readonly limitType: 'depth' | 'steps';
+    readonly limit: number;
+    constructor(limitType: 'depth' | 'steps', limit: number);
+}
+/**
+ * Optional complexity limits for expression evaluation.
+ * Defaults are permissive — no existing programs should be affected.
+ */
+export interface EvaluationLimits {
+    /** Maximum expression nesting depth. Default: 64 */
+    maxExpressionDepth?: number;
+    /** Maximum total evaluation steps per entry point. Default: 10_000 */
+    maxEvaluationSteps?: number;
+}
+type EventListener = (event: EmittedEvent) => void;
+export interface ProvenanceVerificationResult {
+    valid: boolean;
+    expectedHash?: string;
+    computedHash?: string;
+    error?: string;
+}
+export declare class RuntimeEngine {
+    private ir;
+    private context;
+    private options;
+    private stores;
+    private eventListeners;
+    private eventLog;
+    /** Current reaction nesting depth to prevent infinite loops */
+    private reactionDepth;
+    private static readonly MAX_REACTION_DEPTH;
+    /** Index of relationships for efficient lookup during expression evaluation */
+    private relationshipIndex;
+    /** Memoization cache for resolved relationships to avoid repeated store queries */
+    private relationshipMemoCache;
+    /** Index of roles by name for O(1) permission checks */
+    private roleIndex;
+    /** Track whether version has been incremented for the current command execution */
+    private versionIncrementedForCommand;
+    /** Track instances that were just created (to prevent version increment on subsequent mutate actions) */
+    private justCreatedInstanceIds;
+    /**
+     * Command-scoped write buffer. While set, mutate/compute actions apply their
+     * changes to an in-memory working copy (`instance`) and accumulate a single
+     * store-form `patch` instead of issuing one store read + write per action.
+     * The buffer is flushed in one `store.update` at the end of the action loop,
+     * then cleared — so a command that mutates N fields performs one read and one
+     * write rather than N. Scoped to the command's target instance only; nested
+     * (reaction/fan-out) commands save and restore the outer buffer.
+     */
+    private commandBuffer;
+    /** Last transition validation error (set by updateInstance, checked by _executeCommandInternal) */
+    private lastTransitionError;
+    /** Last concurrency conflict (set by updateInstance, checked by _executeCommandInternal) */
+    private lastConcurrencyConflict;
+    /** Per-engine sliding-window rate limiter (in-memory; durable store is a follow-up) */
+    private rateLimiter;
+    private readonly profilingBridge;
+    private actionTraceCounter;
+    /**
+     * In-process approval request cache, keyed by
+     * `${entity}:${instanceId}:${approvalName}`. Always maintained as a mirror
+     * so the synchronous `getApprovalRequest`/`expireApprovals` accessors work.
+     * When `options.approvalStore` is set, that store is the source of truth and
+     * this Map is just a write-through mirror; otherwise this Map IS the store.
+     */
+    private approvalRequests;
+    /**
+     * Load an approval request, preferring the durable store when configured.
+     * Refreshes the in-process mirror so synchronous accessors stay coherent.
+     */
+    private loadApprovalState;
+    /**
+     * Persist an approval request to the durable store (when configured) and
+     * always mirror it in-process so a later synchronous read sees it.
+     */
+    private saveApprovalState;
+    /** Per-entry-point evaluation budget for bounded complexity enforcement */
+    private evalBudget;
+    /** Cache for computed property values, keyed by "entityName:instanceId:propertyName" */
+    private computedPropertyCache;
+    /** Request-scoped cache for computed properties (cleared per command) */
+    private computedPropertyRequestCache;
+    /**
+     * Initialize evaluation budget if not already active (re-entrant safe).
+     * Returns true if this call initialized the budget (caller must clear it in finally).
+     * Returns false if budget was already active (caller should NOT clear it).
+     */
+    private initEvalBudget;
+    /** Clear evaluation budget (only call if initEvalBudget returned true) */
+    private clearEvalBudget;
+    /**
+     * Returns the set of property names marked `encrypted` for the given entity.
+     * Cached per entity name since IR is immutable at runtime.
+     */
+    private encryptedPropertyNamesCache;
+    private encryptedPropertyNames;
+    /**
+     * Encrypt property values before a store write.
+     * Returns a shallow copy with encrypted fields replaced by envelope JSON.
+     * No-op when encryptionProvider is not configured or entity has no encrypted fields.
+     */
+    private encryptProperties;
+    /**
+     * Decrypt property values after a store read.
+     * Returns a shallow copy with encrypted envelope JSON replaced by plaintext.
+     * No-op when encryptionProvider is not configured or entity has no encrypted fields.
+     */
+    private decryptProperties;
+    /**
+     * Resolve the active tenant value from runtime context using the IR tenant
+     * config's contextPath. Returns undefined when no tenant declaration exists
+     * in the IR or the context lacks the value.
+     */
+    private resolveTenantValue;
+    constructor(ir: IR, context?: RuntimeContext, options?: RuntimeOptions);
+    private initializeStores;
+    /**
+     * Build an index of all relationships for efficient lookup during expression evaluation.
+     * Maps "EntityName.relationshipName" to relationship metadata.
+     */
+    private buildRelationshipIndex;
+    private buildRoleIndex;
+    /**
+     * Check if a role has a specific permission.
+     * Uses precomputed effectivePermissions for O(1) lookup.
+     * Unknown role → false (no permissive default, per house style).
+     */
+    private roleHasPermission;
+    /**
+     * Clear the relationship memoization cache.
+     * Called at the start of each command execution to ensure fresh data.
+     */
+    private clearMemoCache;
+    /**
+     * Resolve a relationship for a given instance.
+     * Uses memoization cache to avoid repeated store queries within a single command execution.
+     * @param entityName - The source entity name
+     * @param instance - The source instance (must have an id)
+     * @param relationshipName - The relationship name to resolve
+     * @returns For hasMany: array of related instances; for hasOne/belongsTo/ref: single instance or null
+     */
+    private resolveRelationship;
+    private getNow;
+    /**
+     * Generate a unique identifier for runtime-internal records (audit
+     * records, outbox entry ids). Uses the caller-supplied generator from
+     * RuntimeOptions when present; otherwise falls back to crypto.randomUUID.
+     * Distinct from `getBuiltins().uuid` only by intent — keeping a named
+     * helper avoids leaking the fallback chain across call sites.
+     */
+    private nextRuntimeId;
+    private getBuiltins;
+    getIR(): IR;
+    /**
+     * Get the provenance metadata from the IR
+     */
+    getProvenance(): IRProvenance | undefined;
+    /**
+     * Log provenance information at startup
+     * This can be called by UI code to display provenance
+     */
+    logProvenance(): void;
+    /**
+     * Verify the IR integrity by checking that the computed hash matches the expected hash.
+     * Returns true if verification passes, false otherwise.
+     *
+     * @param expectedHash - Optional expected hash. If not provided, uses the IR's self-reported irHash
+     * @returns true if hash matches or if no hash is available to verify
+     */
+    verifyIRHash(expectedHash?: string): Promise<boolean>;
+    /**
+     * Verify IR and throw if invalid. Use this when requireValidProvenance is true.
+     * @throws Error if IR hash verification fails
+     */
+    assertValidProvenance(): Promise<void>;
+    getContext(): RuntimeContext;
+    setContext(ctx: Partial<RuntimeContext>): void;
+    replaceContext(ctx: RuntimeContext): void;
+    getEntities(): IREntity[];
+    getEntity(name: string): IREntity | undefined;
+    getCommands(): IRCommand[];
+    getCommand(name: string, entityName?: string): IRCommand | undefined;
+    getPolicies(): IRPolicy[];
+    /** Return all schedule declarations from the compiled IR. */
+    getSchedules(): IRSchedule[];
+    /**
+     * Run a named schedule: evaluate bound params and dispatch the target command.
+     * Sets context.source to 'schedule' and context.scheduleName for the invocation.
+     */
+    runSchedule(scheduleName: string, options?: {
+        correlationId?: string;
+        causationId?: string;
+    }): Promise<CommandResult>;
+    getStore(entityName: string): Store | undefined;
+    /**
+     * Get collected command profiles when profiling is enabled.
+     * Returns an empty array when profiling is not configured.
+     */
+    getProfiles(): import('./profiling').CommandProfile[];
+    /**
+     * Execute middleware registered for a given hook.
+     * Returns a short-circuit result if any middleware short-circuits,
+     * or undefined to continue normal execution.
+     */
+    private runMiddleware;
+    /**
+     * Public read surface: tenant filter → decrypt → mask (read-projection only).
+     * Execution paths (guards, actions, policies, computed properties, relationship
+     * resolution) use getAllInstancesRaw and always see real values.
+     */
+    getAllInstances(entityName: string): Promise<EntityInstance[]>;
+    /** Internal read path: tenant filter + decryption, NO masking. */
+    private getAllInstancesRaw;
+    /**
+     * Public read surface: tenant filter → decrypt → mask (read-projection only).
+     * Execution paths use getInstanceRaw and always see real values.
+     */
+    getInstance(entityName: string, id: string): Promise<EntityInstance | undefined>;
+    /** Internal read path: tenant filter + decryption, NO masking. */
+    private getInstanceRaw;
+    /** Cache of properties carrying maskStrategy, per entity (IR is immutable at runtime). */
+    private maskedPropertiesCache;
+    private maskedProperties;
+    /**
+     * Apply read-time masking to an instance (after decryption and tenant filtering).
+     * - `private` wins over `masked`: the property is excluded entirely.
+     * - `null`/`undefined` pass through unmasked.
+     * - `unmaskWhen` falsy or throwing ⇒ value stays masked (secure by default).
+     *   An evaluation error additionally surfaces a diagnostic; it never changes
+     *   the masked outcome (diagnostics explain, never compensate).
+     */
+    private applyMasking;
+    /**
+     * Check entity constraints against instance data
+     * Returns array of constraint failures (empty if all pass)
+     * Useful for diagnostic purposes without mutating state
+     */
+    checkConstraints(entityName: string, data: Record<string, unknown>): Promise<ConstraintOutcome[]>;
+    /**
+     * Evaluate all entity constraints against instance data, returning every outcome
+     * (both passed and failed). Useful for diagnostic UIs that show full constraint status.
+     */
+    evaluateAllConstraints(entityName: string, data: Record<string, unknown>): Promise<ConstraintOutcome[]>;
+    createInstance(entityName: string, data: Partial<EntityInstance>): Promise<EntityInstance | undefined>;
+    private prepareCreateData;
+    private reportConstraintOutcomes;
+    private createInstanceWithOutcomes;
+    /** Date/time primitive write-time validation (docs/spec/semantics.md, Date/Time Types). */
+    private validateDateTimeTypes;
+    private persistPreparedCreate;
+    updateInstance(entityName: string, id: string, data: Partial<EntityInstance>): Promise<EntityInstance | undefined>;
+    /**
+     * Mark cached computed properties as stale when their dependencies are mutated.
+     * Scans the entity's computed properties for any that depend on the changed properties,
+     * and sets their cache entries' stale flag to true. Handles transitive staleness.
+     */
+    private markComputedPropertiesStale;
+    deleteInstance(entityName: string, id: string): Promise<boolean>;
+    runCommand(commandName: string, input: Record<string, unknown>, options?: {
+        entityName?: string;
+        instanceId?: string;
+        overrideRequests?: OverrideRequest[];
+        /** Correlation ID for workflow event grouping */
+        correlationId?: string;
+        /** Causation ID linking this command to its trigger */
+        causationId?: string;
+        /** Caller-provided idempotency key for dedup. Required if idempotencyStore is configured. */
+        idempotencyKey?: string;
+    }): Promise<CommandResult>;
+    /**
+     * Execute a saga: run steps in declaration order, compensating completed
+     * steps in reverse order on failure (when onFailure === 'compensate').
+     * Each step dispatches via `runCommand` — all policies, guards, and
+     * constraints of the step's command still apply.
+     */
+    runSaga(sagaName: string, stepInputs?: Record<string, {
+        input?: Record<string, unknown>;
+        instanceId?: string;
+    }>, options?: {
+        correlationId?: string;
+    }): Promise<SagaResult>;
+    /**
+     * Compensate completed saga steps in reverse order (best-effort).
+     * Compensation failures are recorded but do not throw — all remaining
+     * compensations still execute.
+     */
+    private compensateSagaSteps;
+    /**
+     * Emit a saga lifecycle event (SagaStarted, SagaCompleted, SagaFailed,
+     * SagaStepCompleted) only if declared in the saga's `emits` array.
+     */
+    private emitSagaLifecycle;
+    /**
+     * Map a CommandResult and any thrown error into a CommandOutcome for the
+     * AuditRecord. The mapping mirrors the exit paths inside runCommand and
+     * _executeCommandInternal — keep them in lock-step when adding new
+     * failure modes.
+     */
+    private classifyOutcome;
+    /**
+     * Build and emit a single AuditRecord through the configured sink.
+     * Sink errors are caught and logged — audit emission MUST NOT alter
+     * command-execution behavior. This is the documented fail-open policy
+     * (see docs/spec/adapters.md § "Audit Sink").
+     */
+    private emitAudit;
+    /**
+     * Enqueue emitted events into the configured OutboxStore as a batch.
+     * Wraps the call in try/catch and logs failures — outbox failures MUST
+     * NOT alter the CommandResult shape callers already received.
+     *
+     * Non-transactional caveat: the in-memory runtime does not yet expose a
+     * shared transaction boundary, so a successful command followed by an
+     * outbox enqueue failure leaves state mutated without an outbox row.
+     * Durable adapters MUST honor the `tx` parameter and enqueue inside the
+     * same transaction that mutated state.
+     */
+    private enqueueOutbox;
+    /**
+     * Validate an async command synchronously (policies, constraints, guards)
+     * without executing actions. Used for fail-fast before enqueuing a job.
+     */
+    private _validateAsyncCommand;
+    /**
+     * Drain all pending jobs from the job queue and execute them.
+     * Returns an array of CommandResults, one per drained job.
+     * For deterministic testing: executes jobs synchronously in FIFO order.
+     *
+     * For each job:
+     * - Sets context.source = 'job' to bypass the async enqueue branch
+     * - Executes the full command body (actions + emits)
+     * - Emits completion or failure event on the synthesized channel
+     * - Updates job status in the queue
+     */
+    drainJobs(): Promise<CommandResult[]>;
+    private _executeCommandInternal;
+    private buildEvalContext;
+    private checkPolicies;
+    /**
+     * Validate entity constraints against instance data
+     * Returns array of constraint failures (empty if all pass)
+     *
+     * Constraint semantics:
+     * - Expression evaluates to TRUE → condition is met → constraint PASSES
+     * - Expression evaluates to FALSE → condition is not met → constraint FAILS
+     *
+     * Severity affects what gets reported as failures:
+     * - severity='block': Failed constraints are returned as failures (block execution)
+     * - severity='warn': Failed constraints are NOT returned as failures (informational only)
+     * - severity='ok': Failed constraints are NOT returned as failures (informational only)
+     *
+     * CONSTRAINT SEMANTICS (vNext hybrid support):
+     * - Positive constraints (default): Expression describes what MUST be true for validity
+     *   - When FALSE → constraint FAILS (e.g., "amount >= 0" fails when amount = -1)
+     *   - When TRUE → constraint PASSES
+     * - Negative constraints (detected by "severity" prefix): Expression describes BAD state
+     *   - When TRUE → constraint FIRES (e.g., "status == 'cancelled'" fires when cancelled)
+     *   - When FALSE → constraint PASSES (no bad state present)
+     */
+    private validateConstraints;
+    private extractContextKeys;
+    private formatExpression;
+    private formatValue;
+    private resolveExpressionValues;
+    private notifyActionTrace;
+    private executeAction;
+    evaluateExpression(expr: IRExpression, context: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Check whether an expression can be safely evaluated by the WASM module.
+     * Pure computational expressions (no entity relationships, no async effects)
+     * are compatible. The check is conservative — when in doubt, return false
+     * to ensure the TypeScript evaluator is used.
+     */
+    private isWasmCompatible;
+    private evaluateBinaryOp;
+    private evaluateUnaryOp;
+    private irValueToJs;
+    private getDefaultForType;
+    evaluateComputed(entityName: string, instanceId: string, propertyName: string): Promise<unknown>;
+    /**
+     * Evaluate a computed property and return metadata including cache status and staleness.
+     * Returns { value, stale, cached } or undefined if the entity/property/instance doesn't exist.
+     */
+    evaluateComputedWithMeta(entityName: string, instanceId: string, propertyName: string): Promise<{
+        value: unknown;
+        stale: boolean;
+        cached: boolean;
+    } | undefined>;
+    /**
+     * Look up a cached computed property value based on the configured cache strategy.
+     * Returns the cache entry if valid, or undefined if cache miss or expired.
+     */
+    private getCachedComputedValue;
+    /**
+     * Store a computed property value in the appropriate cache based on strategy.
+     */
+    private setCachedComputedValue;
+    private evaluateComputedInternal;
+    /**
+     * vNext: Interpolate template placeholders with values from context
+     * Supports {placeholder} syntax where placeholders are resolved from:
+     * 1. details mapping (if present)
+     * 2. resolved expression values (by expression string)
+     * 3. evaluation context (direct property access)
+     */
+    private interpolateTemplate;
+    /**
+     * vNext: Evaluate a single constraint and return detailed outcome
+     */
+    private evaluateConstraint;
+    /**
+     * vNext: Evaluate command constraints with override support
+     * Returns allowed flag, all constraint outcomes, and any OverrideApplied events.
+     * Per spec (manifest-vnext.md § OverrideApplied Event Shape):
+     * OverrideApplied events MUST be included in CommandResult.emittedEvents.
+     */
+    private evaluateCommandConstraints;
+    /**
+     * vNext: Validate override authorization via policy or default admin check
+     */
+    private validateOverrideAuthorization;
+    /**
+     * vNext: Build OverrideApplied event for auditing.
+     * Per spec (manifest-vnext.md § OverrideApplied Event Shape):
+     * payload MUST contain: constraintCode, reason, authorizedBy, timestamp, commandName,
+     * and optionally entityName, instanceId.
+     * The event is a runtime-synthesized event included in CommandResult.emittedEvents.
+     */
+    private buildOverrideAppliedEvent;
+    /**
+     * vNext: Emit ConcurrencyConflict event
+     */
+    private emitConcurrencyConflictEvent;
+    /**
+     * vNext: Get provenance info for events
+     */
+    private getProvenanceInfo;
+    onEvent(listener: EventListener): () => void;
+    /**
+     * Subscribe to events for a single entity (docs/spec/semantics.md,
+     * "Realtime Entities"). Convenience over onEvent: the listener receives
+     * only events whose `subject.entity === entityName`. Events WITHOUT a
+     * subject entity are NOT delivered — use onEvent for the unfiltered
+     * firehose. Returns an unsubscribe function. Exists regardless of any
+     * entity's `realtime` flag (the flag is a projection hint only).
+     */
+    subscribe(entityName: string, listener: EventListener): () => void;
+    private notifyListeners;
+    getEventLog(): EmittedEvent[];
+    clearEventLog(): void;
+    serialize(): Promise<{
+        ir: IR;
+        context: RuntimeContext;
+        stores: Record<string, EntityInstance[]>;
+    }>;
+    restore(data: {
+        stores: Record<string, EntityInstance[]>;
+    }): Promise<void>;
+    /**
+     * Static factory method to create a RuntimeEngine with optional provenance verification.
+     * This is useful when you want to verify IR integrity before execution.
+     *
+     * In production mode (NODE_ENV=production), provenance verification is enabled by default.
+     * Set `requireValidProvenance: false` to explicitly disable.
+     *
+     * @param ir - The IR to execute
+     * @param context - Runtime context (user, etc.)
+     * @param options - Runtime options including requireValidProvenance
+     * @returns A tuple of [runtime, verificationResult]
+     *
+     * @example
+     * ```ts
+     * // Production: verification enabled by default
+     * const [runtime, result] = await RuntimeEngine.create(ir, context);
+     * if (!result.valid) {
+     *   throw new Error(`Invalid IR: ${result.error}`);
+     * }
+     *
+     * // Development: explicitly disable verification
+     * const [runtime] = await RuntimeEngine.create(ir, context, { requireValidProvenance: false });
+     * ```
+     */
+    /**
+     * Build an approval-request key for the Map.
+     */
+    private approvalKey;
+    /**
+     * Find approval declarations on an entity that gate a given command name.
+     */
+    private findApprovalsForCommand;
+    /**
+     * Check the approval gate for a command. Returns a CommandResult (blocked)
+     * if the command requires approval that hasn't been granted yet, or
+     * undefined if the command may proceed.
+     */
+    private checkApprovalGate;
+    /**
+     * Get the list of stages that still need approvals.
+     */
+    private getPendingStages;
+    /**
+     * Request approval for a command on an entity instance.
+     * Creates or returns the existing approval request state.
+     */
+    requestApproval(entityName: string, instanceId: string, approvalName: string): Promise<ApprovalRequestState>;
+    /**
+     * Grant approval for a specific stage. Evaluates the stage policy to verify
+     * the approver is authorized. When all required stages are satisfied, marks
+     * the approval as 'granted'.
+     */
+    approveStage(entityName: string, instanceId: string, approvalName: string, stageName: string, approver: ApprovalApprover): Promise<ApprovalRequestState>;
+    /**
+     * Deny an approval request.
+     */
+    denyApproval(entityName: string, instanceId: string, approvalName: string, deniedBy: string, reason?: string): Promise<ApprovalRequestState>;
+    /**
+     * Expire any pending approvals that have exceeded their timeout.
+     * Approvals with `onTimeout: 'cancel'` are set to 'expired'.
+     * Approvals with `onTimeout: 'escalate'` are flagged but kept pending (future).
+     *
+     * Operates on the in-process request set. In durable mode
+     * (`options.approvalStore` configured), run set-based expiry across all
+     * stored requests via `approvalStore.expire(now)` from a cron/worker; this
+     * synchronous accessor only sees requests this engine has touched.
+     */
+    expireApprovals(now?: number): ApprovalRequestState[];
+    /**
+     * Get the current approval request state for an entity instance.
+     */
+    getApprovalRequest(entityName: string, instanceId: string, approvalName: string): ApprovalRequestState | undefined;
+    static create(ir: IR, context?: RuntimeContext, options?: RuntimeOptions): Promise<[RuntimeEngine, ProvenanceVerificationResult]>;
+}
+//# sourceMappingURL=runtime-engine.d.ts.map