@victframework/runtime 0.1.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgDA,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EAAE,gCAAgC,EAAE,MAAM,8BAA8B,CAAC;AAsChF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,6BAA6B;AAC7B,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACvF,OAAO,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAC;AAK1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,8BAA8B,EAC9B,qBAAqB,EACrB,8BAA8B,GAC/B,MAAM,uBAAuB,CAAC;AA8B/B,OAAO,EACL,gCAAgC,EAChC,8BAA8B,EAC9B,kBAAkB,EAClB,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,+BAA+B,EAC/B,yBAAyB,EACzB,4BAA4B,EAC5B,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,6BAA6B,EAC7B,yCAAyC,EACzC,qCAAqC,EACrC,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAmB/B,+EAA+E;AAC/E,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA8CvE,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,+BAA+B,EAC/B,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,EACnB,yBAAyB,EACzB,0BAA0B,EAC1B,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,iCAAiC,EACjC,wBAAwB,EACxB,0BAA0B,EAC1B,0BAA0B,EAC1B,0BAA0B,EAC1B,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EACL,gCAAgC,EAChC,sBAAsB,EACtB,0BAA0B,EAC1B,+BAA+B,EAC/B,8BAA8B,EAC9B,gCAAgC,EAChC,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,gFAAgF;AAChF,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,kCAAkC,EAClC,yBAAyB,EACzB,4BAA4B,EAC5B,+BAA+B,EAC/B,sBAAsB,EACtB,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAmB9B,OAAO,EACL,sCAAsC,EACtC,+BAA+B,GAChC,MAAM,0BAA0B,CAAC"}

package/dist/operator-config.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Stage 07A work item 6 — the bounded protected operator-configuration
+ * resolution foundation (pre-Quellight).
+ *
+ * Quellight (Stage 07B+) will need to configure one pinned model-provider
+ * profile, store locations, and retention bounds through operator
+ * configuration. This module is the VICT-side FOUNDATION for that
+ * composition: typed resolution, name-pattern validation, and fail-closed
+ * credential handling — extending the Verified Stage 06A
+ * `protectCredentialPort`/`requireCredential` discipline (MSTR-011) to
+ * product-facing operator configuration.
+ *
+ * Scope guard (handoff work item 6): this is resolution types, a loader,
+ * validation, and tests ONLY. It is NOT a real provider integration, NOT a
+ * live-provider wrapper, and NOT any Quellight product code. No generalized
+ * secrets-management platform is created.
+ *
+ * Protected-credential discipline (SEC-003, MSTR-011, AI-004):
+ * - the operator configuration carries the provider credential VARIABLE
+ *   NAME (`credentialVar`) — NEVER a credential value;
+ * - credential VALUES enter only through `requireOperatorCredential`,
+ *   which resolves just-in time from the operator-provided environment
+ *   source and is never cached, logged, serialized, or persisted;
+ * - failures are stable and non-echoing: no provider content, no
+ *   environment content, and no credential value can enter an error, a
+ *   diagnostic, or the serialized configuration;
+ * - the serialized configuration surface (`serializeOperatorConfiguration`)
+ *   is structural: a configuration object HAS no credential-value field, so
+ *   no serialization path can leak one.
+ */
+import type { AgentCredentialPort } from './agent-types.js';
+/** The closed schema marker of the operator configuration foundation. */
+export declare const OPERATOR_CONFIG_SCHEMA: "vict.operator-config@1";
+/** Stable non-echoing operator-configuration failure codes. */
+export type OperatorConfigErrorCode = 'VICT_OPERATOR_CONFIG_INVALID' | 'VICT_OPERATOR_CREDENTIAL_UNAVAILABLE';
+/** Error thrown for operator-configuration failures (stable, non-echoing). */
+export declare class OperatorConfigError extends Error {
+    readonly code: OperatorConfigErrorCode;
+    constructor(code: OperatorConfigErrorCode, message: string);
+}
+/** Error thrown when a required operator credential cannot be resolved. */
+export declare class OperatorCredentialUnavailableError extends OperatorConfigError {
+    /** The credential VARIABLE NAME (never a value, never provider content). */
+    readonly credentialName: string;
+    constructor(credentialName: string);
+}
+/** One validated provider-profile selection (credential NAME only). */
+export interface ProviderProfileSelection {
+    /** Stable profile ID (the pinned preferred profile; rotation deferred, OQ4). */
+    readonly profileId: string;
+    /** Provider identifier intent (e.g. `offline-fixture`). */
+    readonly provider: string;
+    /** The pinned model-router intent string (`provider/model`). */
+    readonly routerModel: string;
+    /** The provider credential ENVIRONMENT-VARIABLE NAME — never a value. */
+    readonly credentialVar: string;
+}
+/** Validated store locations (bounded relative paths; never URLs). */
+export interface StoreLocationPlan {
+    /** VICT operational store location, when configured. */
+    readonly operationalStorePath?: string;
+    /** VICT application-domain store location, when configured. */
+    readonly applicationStorePath?: string;
+    /** Dedicated Mastra store location, when configured. */
+    readonly mastraStorePath?: string;
+}
+/** Validated retention bounds (positive finite safe integer milliseconds). */
+export interface RetentionBounds {
+    /** Conversation-message retention bound, when configured. */
+    readonly messagesMaxAgeMs?: number;
+    /** Thread retention bound, when configured. */
+    readonly threadsMaxAgeMs?: number;
+    /** Observability-span retention bound, when configured. */
+    readonly spansMaxAgeMs?: number;
+}
+/** One resolved, frozen operator configuration. */
+export interface OperatorConfiguration {
+    readonly schema: typeof OPERATOR_CONFIG_SCHEMA;
+    readonly profile: ProviderProfileSelection;
+    readonly stores: StoreLocationPlan;
+    readonly retention: RetentionBounds;
+}
+/** The operator input for one profile selection (credential NAME only). */
+export interface OperatorProfileInput {
+    readonly profileId: unknown;
+    readonly provider: unknown;
+    readonly routerModel: unknown;
+    readonly credentialVar: unknown;
+}
+/** The operator input for store locations. */
+export interface OperatorStoresInput {
+    readonly operationalStorePath?: unknown;
+    readonly applicationStorePath?: unknown;
+    readonly mastraStorePath?: unknown;
+}
+/** The operator input for retention bounds. */
+export interface OperatorRetentionInput {
+    readonly messagesMaxAgeMs?: unknown;
+    readonly threadsMaxAgeMs?: unknown;
+    readonly spansMaxAgeMs?: unknown;
+}
+/** The operator configuration input document. */
+export interface OperatorConfigInput {
+    readonly profile: unknown;
+    readonly stores?: unknown;
+    readonly retention?: unknown;
+}
+/**
+ * Resolve one provider-profile selection. Only the credential VARIABLE
+ * NAME is accepted; any value-shaped attempt is a structural rejection.
+ */
+export declare function resolveProviderProfileSelection(input: unknown): ProviderProfileSelection;
+/** Resolve the store-location plan. */
+export declare function resolveStoreLocationPlan(input: unknown): StoreLocationPlan;
+/** Resolve the retention bounds. */
+export declare function resolveRetentionBounds(input: unknown): RetentionBounds;
+/**
+ * Resolve the complete operator configuration from operator-supplied
+ * configuration data. Credential VALUES are structurally absent: the
+ * result carries the credential VARIABLE NAME only.
+ */
+export declare function resolveOperatorConfiguration(input: OperatorConfigInput): OperatorConfiguration;
+/**
+ * The deterministic, safe serialization surface of an operator
+ * configuration. Because the configuration object structurally HAS no
+ * credential-value field, no serialization of it can leak a credential
+ * value. The serialization is canonical (sorted keys) and bounded.
+ */
+export declare function serializeOperatorConfiguration(config: OperatorConfiguration): string;
+/** The minimal environment source: a credential VARIABLE NAME → value read. */
+export type OperatorCredentialEnvironment = AgentCredentialPort | Record<string, string | undefined>;
+/**
+ * Resolve the REQUIRED provider credential just in time through the
+ * protected discipline: the value is read from the operator-provided
+ * environment source, never cached, never logged, never serialized, and a
+ * missing value fails closed with the stable non-echoing
+ * `VICT_OPERATOR_CREDENTIAL_UNAVAILABLE` code. The error carries the
+ * credential VARIABLE NAME only — never a value, never environment
+ * content.
+ */
+export declare function requireOperatorCredential(config: OperatorConfiguration, environment: OperatorCredentialEnvironment): Promise<string>;

package/dist/operator-config.js

@@ -0,0 +1,289 @@
+/**
+ * Stage 07A work item 6 — the bounded protected operator-configuration
+ * resolution foundation (pre-Quellight).
+ *
+ * Quellight (Stage 07B+) will need to configure one pinned model-provider
+ * profile, store locations, and retention bounds through operator
+ * configuration. This module is the VICT-side FOUNDATION for that
+ * composition: typed resolution, name-pattern validation, and fail-closed
+ * credential handling — extending the Verified Stage 06A
+ * `protectCredentialPort`/`requireCredential` discipline (MSTR-011) to
+ * product-facing operator configuration.
+ *
+ * Scope guard (handoff work item 6): this is resolution types, a loader,
+ * validation, and tests ONLY. It is NOT a real provider integration, NOT a
+ * live-provider wrapper, and NOT any Quellight product code. No generalized
+ * secrets-management platform is created.
+ *
+ * Protected-credential discipline (SEC-003, MSTR-011, AI-004):
+ * - the operator configuration carries the provider credential VARIABLE
+ *   NAME (`credentialVar`) — NEVER a credential value;
+ * - credential VALUES enter only through `requireOperatorCredential`,
+ *   which resolves just-in time from the operator-provided environment
+ *   source and is never cached, logged, serialized, or persisted;
+ * - failures are stable and non-echoing: no provider content, no
+ *   environment content, and no credential value can enter an error, a
+ *   diagnostic, or the serialized configuration;
+ * - the serialized configuration surface (`serializeOperatorConfiguration`)
+ *   is structural: a configuration object HAS no credential-value field, so
+ *   no serialization path can leak one.
+ */
+import { protectCredentialPort } from './agent-governance.js';
+/** The closed schema marker of the operator configuration foundation. */
+export const OPERATOR_CONFIG_SCHEMA = 'vict.operator-config@1';
+/** Error thrown for operator-configuration failures (stable, non-echoing). */
+export class OperatorConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'OperatorConfigError';
+        this.code = code;
+    }
+}
+/** Error thrown when a required operator credential cannot be resolved. */
+export class OperatorCredentialUnavailableError extends OperatorConfigError {
+    /** The credential VARIABLE NAME (never a value, never provider content). */
+    credentialName;
+    constructor(credentialName) {
+        super('VICT_OPERATOR_CREDENTIAL_UNAVAILABLE', `Credential '${credentialName}' could not be resolved through the protected operator configuration.`);
+        this.name = 'OperatorCredentialUnavailableError';
+        this.credentialName = credentialName;
+    }
+}
+/** Bounded identifier: the same accepted ID discipline as the runtime. */
+const ID_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const MAX_ID_LENGTH = 128;
+/** Environment-variable NAME pattern (never a value): `OPENAI_API_KEY`. */
+const CREDENTIAL_VAR_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_CREDENTIAL_VAR_LENGTH = 128;
+/** Model-router intent string: `provider/model`, both bounded identifiers. */
+const ROUTER_MODEL_PATTERN = /^[a-z][a-z0-9-]*(?:[.-][a-z0-9]+)*\/[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const MAX_ROUTER_MODEL_LENGTH = 200;
+/** Relative store-location discipline: bounded POSIX-style relative path. */
+const STORE_PATH_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,500}$/;
+const MAX_STORE_PATH_LENGTH = 512;
+function invalid(reason) {
+    // The reason is a FIXED structural description — never operator content.
+    throw new OperatorConfigError('VICT_OPERATOR_CONFIG_INVALID', reason);
+}
+/** Require a bounded identifier string. */
+function requireId(value, field) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > MAX_ID_LENGTH) {
+        invalid(`${field} must be a bounded non-empty identifier string`);
+    }
+    if (!ID_PATTERN.test(value)) {
+        invalid(`${field} must match the bounded VICT identifier pattern`);
+    }
+    return value;
+}
+/** Require an environment-variable NAME (credential values are unnameable). */
+function requireCredentialVar(value) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > MAX_CREDENTIAL_VAR_LENGTH ||
+        !CREDENTIAL_VAR_PATTERN.test(value)) {
+        invalid('credentialVar must be an environment-variable NAME matching [A-Za-z_][A-Za-z0-9_]*');
+    }
+    return value;
+}
+/** Require a bounded `provider/model` router intent string. */
+function requireRouterModel(value) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > MAX_ROUTER_MODEL_LENGTH ||
+        !ROUTER_MODEL_PATTERN.test(value)) {
+        invalid('routerModel must be a bounded provider/model intent string');
+    }
+    return value;
+}
+/** Require an optional bounded relative store path (never a URL). */
+function requireOptionalStorePath(value, field) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > MAX_STORE_PATH_LENGTH ||
+        value.includes('://') ||
+        value.includes('\\') ||
+        value.includes('//') ||
+        !STORE_PATH_PATTERN.test(value) ||
+        value.includes('..')) {
+        invalid(`${field} must be a bounded relative store path without URL schemes or traversal`);
+    }
+    return value;
+}
+/** Require an optional positive-finite-safe-integer millisecond bound. */
+function requireOptionalRetentionMs(value, field) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        invalid(`${field} must be a positive safe-integer millisecond bound`);
+    }
+    return value;
+}
+/**
+ * Require the input document to be a PLAIN canonical object with EXACTLY
+ * the accepted field set: own enumerable string-keyed DATA properties,
+ * `Object.prototype` or null prototype, no symbol keys. Unknown fields are
+ * rejected (fail closed) — a configuration can never smuggle, for example,
+ * a `credential` or `apiKey` VALUE field past this boundary.
+ */
+function requirePlainObjectWithFields(value, what, acceptedFields) {
+    if (typeof value !== 'object' || value === null) {
+        invalid(`${what} must be a plain object`);
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+        invalid(`${what} must have Object.prototype or a null prototype`);
+    }
+    const ownKeys = Reflect.ownKeys(value);
+    for (const key of ownKeys) {
+        if (typeof key !== 'string') {
+            invalid(`${what} must not carry symbol-keyed fields`);
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined) {
+            invalid(`${what} structure could not be proven`);
+        }
+        if (!Object.prototype.propertyIsEnumerable.call(value, key) ||
+            descriptor.get ||
+            descriptor.set) {
+            invalid(`${what} fields must be own enumerable data properties`);
+        }
+    }
+    for (const key of ownKeys) {
+        if (!acceptedFields.includes(key)) {
+            invalid(`${what} carries an unknown field (closed field set)`);
+        }
+    }
+    return value;
+}
+/**
+ * Resolve one provider-profile selection. Only the credential VARIABLE
+ * NAME is accepted; any value-shaped attempt is a structural rejection.
+ */
+export function resolveProviderProfileSelection(input) {
+    const record = requirePlainObjectWithFields(input, 'profile', [
+        'profileId',
+        'provider',
+        'routerModel',
+        'credentialVar',
+    ]);
+    const selection = Object.freeze({
+        profileId: requireId(record.profileId, 'profile.profileId'),
+        provider: requireId(record.provider, 'profile.provider'),
+        routerModel: requireRouterModel(record.routerModel),
+        credentialVar: requireCredentialVar(record.credentialVar),
+    });
+    return selection;
+}
+/** Resolve the store-location plan. */
+export function resolveStoreLocationPlan(input) {
+    const record = requirePlainObjectWithFields(input, 'stores', [
+        'operationalStorePath',
+        'applicationStorePath',
+        'mastraStorePath',
+    ]);
+    return Object.freeze({
+        operationalStorePath: requireOptionalStorePath(record.operationalStorePath, 'stores.operationalStorePath'),
+        applicationStorePath: requireOptionalStorePath(record.applicationStorePath, 'stores.applicationStorePath'),
+        mastraStorePath: requireOptionalStorePath(record.mastraStorePath, 'stores.mastraStorePath'),
+    });
+}
+/** Resolve the retention bounds. */
+export function resolveRetentionBounds(input) {
+    const record = requirePlainObjectWithFields(input, 'retention', [
+        'messagesMaxAgeMs',
+        'threadsMaxAgeMs',
+        'spansMaxAgeMs',
+    ]);
+    return Object.freeze({
+        messagesMaxAgeMs: requireOptionalRetentionMs(record.messagesMaxAgeMs, 'retention.messagesMaxAgeMs'),
+        threadsMaxAgeMs: requireOptionalRetentionMs(record.threadsMaxAgeMs, 'retention.threadsMaxAgeMs'),
+        spansMaxAgeMs: requireOptionalRetentionMs(record.spansMaxAgeMs, 'retention.spansMaxAgeMs'),
+    });
+}
+/**
+ * Resolve the complete operator configuration from operator-supplied
+ * configuration data. Credential VALUES are structurally absent: the
+ * result carries the credential VARIABLE NAME only.
+ */
+export function resolveOperatorConfiguration(input) {
+    const document = requirePlainObjectWithFields(input, 'operator configuration', [
+        'profile',
+        'stores',
+        'retention',
+    ]);
+    const profile = resolveProviderProfileSelection(document.profile);
+    const stores = document.stores === undefined
+        ? Object.freeze({})
+        : resolveStoreLocationPlan(document.stores);
+    const retention = document.retention === undefined
+        ? Object.freeze({})
+        : resolveRetentionBounds(document.retention);
+    return Object.freeze({
+        schema: OPERATOR_CONFIG_SCHEMA,
+        profile,
+        stores,
+        retention,
+    });
+}
+/**
+ * The deterministic, safe serialization surface of an operator
+ * configuration. Because the configuration object structurally HAS no
+ * credential-value field, no serialization of it can leak a credential
+ * value. The serialization is canonical (sorted keys) and bounded.
+ */
+export function serializeOperatorConfiguration(config) {
+    if (config.schema !== OPERATOR_CONFIG_SCHEMA) {
+        invalid('operator configuration carries an unknown schema marker');
+    }
+    const ordered = {
+        profile: {
+            credentialVar: config.profile.credentialVar,
+            profileId: config.profile.profileId,
+            provider: config.profile.provider,
+            routerModel: config.profile.routerModel,
+        },
+        retention: { ...config.retention },
+        schema: config.schema,
+        stores: { ...config.stores },
+    };
+    return JSON.stringify(ordered);
+}
+function asCredentialPort(environment) {
+    if (typeof environment.get === 'function') {
+        return protectCredentialPort(environment);
+    }
+    const record = environment;
+    return protectCredentialPort({
+        async get(name) {
+            return record[name];
+        },
+    });
+}
+/**
+ * Resolve the REQUIRED provider credential just in time through the
+ * protected discipline: the value is read from the operator-provided
+ * environment source, never cached, never logged, never serialized, and a
+ * missing value fails closed with the stable non-echoing
+ * `VICT_OPERATOR_CREDENTIAL_UNAVAILABLE` code. The error carries the
+ * credential VARIABLE NAME only — never a value, never environment
+ * content.
+ */
+export async function requireOperatorCredential(config, environment) {
+    const port = asCredentialPort(environment);
+    // Protected resolution: provider failures collapse to `undefined` (never
+    // propagated provider content), then the value passes the same
+    // just-in-time, non-caching, non-echoing requirement as every other
+    // protected credential read. The failure carries the credential VARIABLE
+    // NAME only.
+    const value = await port.get(config.profile.credentialVar).catch(() => undefined);
+    if (value === undefined || typeof value !== 'string') {
+        throw new OperatorCredentialUnavailableError(config.profile.credentialVar);
+    }
+    return value;
+}
+//# sourceMappingURL=operator-config.js.map

package/dist/operator-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-config.js","sourceRoot":"","sources":["../src/operator-config.ts"],"names":[],"mappings":"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"}

package/dist/orchestration-activation.d.ts

@@ -0,0 +1,116 @@
+import { type CompiledGraph, type GraphIssue } from '@victframework/kernel';
+import type { ActivationManifest, StoredActivation } from './store-types.js';
+import type { CapabilityRegistry, FrozenCapabilityBinding } from './registry.js';
+/**
+ * Exact-activation resolution for Stage 03 (handoff §17).
+ *
+ * A suspended run resolves its graph and bindings ONLY from the stored
+ * manifest of its pinned activationVersion, rebuilt against the registry's
+ * revision-pinned lookups. Missing artifacts produce structured unavailable
+ * errors — never a nearby/substitute revision. Multiple immutable
+ * snapshots can coexist, cached by activationVersion.
+ */
+/** A frozen contract parsing handle captured at resolution time. */
+export interface FrozenContractHandle {
+    readonly id: string;
+    readonly revision: string;
+    readonly expected: string;
+    readonly parse: (input: unknown) => {
+        readonly ok: boolean;
+        readonly value?: unknown;
+        readonly issues?: readonly {
+            code: string;
+            path: string;
+            message: string;
+        }[];
+    };
+}
+export interface ResolvedBindings {
+    readonly bindings: ReadonlyMap<string, FrozenCapabilityBinding>;
+    readonly contracts: ReadonlyMap<string, FrozenContractHandle>;
+}
+export type ActivationResolution<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+export interface ActivationResolverDeps {
+    readonly catalog: {
+        get(activationVersion: string): Promise<StoredActivation | undefined>;
+    };
+    readonly registry: CapabilityRegistry;
+}
+/** Load and validate the stored manifest for an activation version. */
+export declare function loadManifest(deps: Pick<ActivationResolverDeps, 'catalog'>, activationVersion: string): Promise<ActivationManifest>;
+/**
+ * Rebuild the exact compiled graph for a stored activation from the
+ * registry's revision-pinned lookups. Cache by activationVersion is the
+ * caller's concern (immutable results).
+ */
+export declare function resolveGraphForActivation(deps: ActivationResolverDeps, activationVersion: string): Promise<CompiledGraphResolution>;
+export interface CompiledGraphResolution {
+    readonly ok: boolean;
+    readonly graph?: CompiledGraph;
+    readonly code?: string;
+    readonly message?: string;
+    readonly issues?: readonly GraphIssue[];
+}
+/**
+ * Resolve the exact execution bindings (invoke handles + captured contract
+ * parsing handles) for a run's pinned activation.
+ */
+export declare function resolveBindings(deps: ActivationResolverDeps, activationVersion: string): Promise<ResolvedBindingsResolution>;
+export interface ResolvedBindingsResolution {
+    readonly ok: boolean;
+    readonly bindings?: ReadonlyMap<string, FrozenCapabilityBinding>;
+    readonly contracts?: ReadonlyMap<string, FrozenContractHandle>;
+    readonly code?: string;
+    readonly message?: string;
+}
+/** Stable opaque idempotency key from durable identity (handoff §12.2). */
+export declare function deriveIdempotencyKey(parts: {
+    runId: string;
+    activationVersion: string;
+    lineage: string;
+    nodeId: string;
+    invocationId: string;
+}): string;
+/** Deterministic logical invocation id: invariant across retries and restarts. */
+export declare function deriveInvocationId(parts: {
+    runId: string;
+    activationVersion: string;
+    lineage: string;
+    nodeId: string;
+}): string;
+export declare function deriveAttemptId(invocationId: string, attemptNumber: number): string;
+/** Deterministic token ids from stable run/node/branch identity. */
+export declare function rootTokenId(runId: string): string;
+export declare function forkChildTokenId(runId: string, forkId: string, branchKey: string): string;
+export declare function joinTokenId(runId: string, joinId: string): string;
+export declare function waitIdFor(runId: string, lineage: string, nodeId: string): string;
+export declare function canonicalBranchLineage(parentLineage: string, forkId: string, branchKey: string): string;
+/** Branch lineage of the post-join continuation: the fork's own lineage. */
+export declare function forkLineageOf(childLineage: string, forkId: string, branchKey: string): string;
+export declare function signalCommandHash(command: {
+    runId: string;
+    waitId: string;
+    signalId: string;
+    signalName?: string;
+    payload: unknown;
+}): string;
+export declare function cancellationCommandHash(command: {
+    runId: string;
+    requestId: string;
+    reasonCode: string;
+}): string;
+export declare function resolutionCommandHash(command: {
+    runId: string;
+    resolutionId: string;
+    action: string;
+    reasonCode: string;
+    expectedRunRevision?: number;
+    hasOutput: boolean;
+}): string;