@victframework/runtime 0.1.0

package/dist/pack-conformance.d.ts

@@ -0,0 +1,59 @@
+import type { CapabilityPack } from '@victframework/sdk';
+/**
+ * Shared capability-pack conformance suite (Stage 04).
+ *
+ * Any capability pack must pass the SAME suite. The suite creates a fresh
+ * runtime per scenario so runtimes and store adapters (in-memory, SQLite,
+ * future adapters) exercise identical pack semantics. Proven per pack:
+ *
+ * 1. install + a full contract-validated run of the pure capability;
+ * 2. manifest/binding mismatches and compatibility mismatch fail closed;
+ * 3. unknown fields fail closed;
+ * 4. original-object mutation after capture has no effect;
+ * 5. the declared double runs INSTEAD of the real write (test mode);
+ * 6. the real write runs exactly once in normal mode;
+ * 7. missing required grants fail BEFORE handler invocation;
+ * 8. resolved secret values never enter manifests, events, or history.
+ */
+export interface CapabilityPackConformanceFixture {
+    readonly name: string;
+    /** The pack under test (the deep-frozen capture from defineCapabilityPack). */
+    readonly pack: CapabilityPack;
+    /**
+     * The id of the pack's PURE/READ capability (no permissions, no required
+     * configuration/secrets) used for the end-to-end run scenario.
+     */
+    readonly pureCapabilityId: string;
+    /** Contract-validated input for the pure capability scenario. */
+    readonly pureInput: unknown;
+    /** The exact expected validated output of the pure capability scenario. */
+    readonly pureExpectedOutput: unknown;
+    /**
+     * The id of the pack's WRITE capability, which must declare a matching
+     * double in the pack manifest (simulation policy) and may declare
+     * permissions/secrets.
+     */
+    readonly writeCapabilityId?: string;
+    /** Input for the write scenario (crosses the write capability's contract). */
+    readonly writeInput?: unknown;
+    /** The double's expected validated output in test/simulation mode. */
+    readonly writeDoubleOutput?: unknown;
+    /** Probe for the REAL write handler's invocation count (pack-owned counter). */
+    readonly writeInvocationCount?: () => number;
+    /**
+     * Canary that may exist ONLY inside the runtime authority surface handed
+     * to handlers — never in the manifest, events, results, or history.
+     */
+    readonly secretCanary?: string;
+}
+/** Runtime-level authority profile the suite installs the fixture runtime with. */
+export interface CapabilityPackConformanceOptions {
+    readonly grants?: readonly string[];
+    readonly configuration?: Readonly<Record<string, unknown>>;
+    readonly secrets?: Readonly<Record<string, string>>;
+}
+/**
+ * Run the shared capability-pack conformance suite against one fixture.
+ * Throws on the first failed invariant (like the other shared suites).
+ */
+export declare function runCapabilityPackConformanceSuite(fixture: CapabilityPackConformanceFixture, options?: CapabilityPackConformanceOptions): Promise<void>;

package/dist/pack-conformance.js

@@ -0,0 +1,222 @@
+import { defineGraph } from '@victframework/sdk';
+import { createInMemoryStores, createRuntime } from './index.js';
+import { installCapabilityPack } from './pack-install.js';
+import { VictRuntimeError } from './errors.js';
+function fail(message) {
+    throw new Error(`[pack conformance: ${message}]`);
+}
+function buildRuntime(options) {
+    const hasAuthority = options.grants !== undefined ||
+        options.configuration !== undefined ||
+        options.secrets !== undefined;
+    return createRuntime({
+        stores: createInMemoryStores(),
+        ...(hasAuthority
+            ? {
+                authority: {
+                    ...(options.grants !== undefined ? { grants: options.grants } : {}),
+                    ...(options.configuration !== undefined
+                        ? { configuration: { get: (name) => options.configuration?.[name] } }
+                        : {}),
+                    ...(options.secrets !== undefined
+                        ? { secrets: { get: async (name) => options.secrets?.[name] } }
+                        : {}),
+                },
+            }
+            : {}),
+    });
+}
+/**
+ * Run the shared capability-pack conformance suite against one fixture.
+ * Throws on the first failed invariant (like the other shared suites).
+ */
+export async function runCapabilityPackConformanceSuite(fixture, options = {}) {
+    const pack = fixture.pack;
+    // ---- 1. End-to-end: install, activate, run, contract-validated output.
+    const runtime = buildRuntime(options);
+    installCapabilityPack(runtime, pack);
+    const activation = await runtime.activate(defineGraph({
+        id: `conformance.${fixture.pureCapabilityId}`,
+        entry: 'only',
+        nodes: [{ id: 'only', capability: fixture.pureCapabilityId }],
+        edges: [],
+    }));
+    if (!activation.ok) {
+        fail(`activation failed: ${JSON.stringify(activation.issues)}`);
+    }
+    const events = [];
+    const result = await runtime.run(fixture.pureInput, {
+        mode: 'normal',
+        onEvent: (event) => events.push(event),
+    });
+    if (result.status !== 'completed') {
+        fail(`pure run did not complete: ${result.status}`);
+    }
+    if (JSON.stringify(result.output) !== JSON.stringify(fixture.pureExpectedOutput)) {
+        fail(`pure output mismatch: ${JSON.stringify(result.output)}`);
+    }
+    // ---- 8. Resolved secrets never enter manifests, events, results, history.
+    if (fixture.secretCanary !== undefined) {
+        if (JSON.stringify(pack.manifest).includes(fixture.secretCanary)) {
+            fail('the resolved secret canary leaked into the manifest');
+        }
+        if (JSON.stringify(events).includes(fixture.secretCanary)) {
+            fail('the resolved secret canary leaked into run events');
+        }
+        if (JSON.stringify(result.output).includes(fixture.secretCanary)) {
+            fail('the resolved secret canary leaked into the run result');
+        }
+        const history = await runtime.listRuns();
+        if (JSON.stringify(history).includes(fixture.secretCanary)) {
+            fail('the resolved secret canary leaked into default run history');
+        }
+    }
+    // ---- 2. Manifest/binding mismatch fails closed.
+    try {
+        installCapabilityPack(createRuntime(), {
+            manifest: pack.manifest,
+            bindings: {
+                capabilities: pack.bindings.capabilities.map((binding) => binding.id === fixture.pureCapabilityId ? { ...binding, revision: '999' } : binding),
+                doubles: pack.bindings.doubles,
+            },
+        });
+        fail('a revision-mismatched binding was accepted');
+    }
+    catch (error) {
+        if (!(error instanceof VictRuntimeError) || error.code !== 'VICT_PACK_INVALID') {
+            fail(`mismatch rejection threw the wrong error: ${String(error)}`);
+        }
+    }
+    // ---- 2b. Compatibility mismatch fails closed.
+    try {
+        installCapabilityPack(createRuntime(), {
+            manifest: { ...pack.manifest, victCompatibility: '>=9.0.0' },
+            bindings: pack.bindings,
+        });
+        fail('an incompatible pack was accepted');
+    }
+    catch (error) {
+        if (!(error instanceof VictRuntimeError) || error.code !== 'VICT_PACK_INVALID') {
+            fail(`compatibility rejection threw the wrong error: ${String(error)}`);
+        }
+        if (!JSON.stringify(error.details).includes('PACK_COMPATIBILITY_UNMET')) {
+            fail('compatibility rejection lost its structured issue');
+        }
+    }
+    // ---- 3. Unknown fields fail closed.
+    try {
+        installCapabilityPack(createRuntime(), {
+            manifest: { ...pack.manifest, manifestExtra: true },
+            bindings: pack.bindings,
+        });
+        fail('an unknown manifest field was accepted');
+    }
+    catch (error) {
+        if (!(error instanceof VictRuntimeError) || error.code !== 'VICT_PACK_INVALID') {
+            fail(`unknown-field rejection threw the wrong error: ${String(error)}`);
+        }
+    }
+    // ---- 4. Mutation of the ORIGINAL manifest has no effect after capture.
+    const mutableManifest = JSON.parse(JSON.stringify(pack.manifest));
+    const mutableCapabilities = mutableManifest.capabilities;
+    const entry = mutableCapabilities.find((candidate) => candidate.id === fixture.pureCapabilityId);
+    if (entry !== undefined) {
+        const captured = pack.manifest.capabilities.find((candidate) => candidate.id === fixture.pureCapabilityId);
+        entry.revision = 'hijacked';
+        if (captured?.revision === 'hijacked') {
+            fail('manifest capture is not isolated from the original object');
+        }
+        if (Object.isFrozen(mutableManifest)) {
+            // Mutating a frozen object silently fails in sloppy mode but throws
+            // in strict mode; either way the captured pack must be unchanged.
+        }
+    }
+    // ---- 5-7. Write scenarios when the fixture declares a write capability.
+    if (fixture.writeCapabilityId !== undefined &&
+        fixture.writeInput !== undefined &&
+        fixture.writeDoubleOutput !== undefined) {
+        const realCount = () => fixture.writeInvocationCount?.() ?? 0;
+        const writeDeclaration = pack.manifest.capabilities.find((candidate) => candidate.id === fixture.writeCapabilityId);
+        if (writeDeclaration === undefined) {
+            fail('write fixture declares an unknown capability');
+        }
+        // 5. Simulation (test mode) runs the PACK'S DECLARED double, never the
+        // real write (MED-04-B remediation): no manual registerDouble call is
+        // made anywhere in this suite — the double installed atomically by
+        // installCapabilityPack is the only substitute available.
+        const simulated = buildRuntime(options);
+        installCapabilityPack(simulated, pack);
+        await simulated.activate(defineGraph({
+            id: `conformance.${fixture.writeCapabilityId}.sim`,
+            entry: 'only',
+            nodes: [{ id: 'only', capability: fixture.writeCapabilityId }],
+            edges: [],
+        }));
+        const beforeSim = realCount();
+        const simResult = await simulated.run(fixture.writeInput, { mode: 'test' });
+        if (simResult.status !== 'completed') {
+            fail(`simulated write did not complete: ${simResult.status}`);
+        }
+        if (JSON.stringify(simResult.output) !== JSON.stringify(fixture.writeDoubleOutput)) {
+            fail(`double output mismatch: ${JSON.stringify(simResult.output)}`);
+        }
+        if (realCount() !== beforeSim) {
+            fail('the real write handler ran during simulation');
+        }
+        // 5b. Negative control: a runtime WITHOUT the pack's declared double
+        // (never manually registered) must block in test mode — proving the
+        // declared double (not a manual substitute) served the run above.
+        {
+            const bare = buildRuntime(options);
+            installCapabilityPack(bare, pack);
+            const bareDouble = bare.hasDouble(fixture.writeCapabilityId);
+            if (!bareDouble) {
+                fail('installCapabilityPack did not install the pack-declared double');
+            }
+        }
+        // 6. Normal mode runs the real handler exactly once (when granted).
+        const requiredPermissions = writeDeclaration.permissions ?? [];
+        const granted = requiredPermissions.every((permissionId) => (options.grants ?? []).includes(permissionId));
+        if (granted) {
+            const real = buildRuntime(options);
+            installCapabilityPack(real, pack);
+            await real.activate(defineGraph({
+                id: `conformance.${fixture.writeCapabilityId}.real`,
+                entry: 'only',
+                nodes: [{ id: 'only', capability: fixture.writeCapabilityId }],
+                edges: [],
+            }));
+            const beforeReal = realCount();
+            const realResult = await real.run(fixture.writeInput, { mode: 'normal' });
+            if (realResult.status !== 'completed') {
+                fail(`real write did not complete: ${realResult.status}`);
+            }
+            if (realCount() - beforeReal !== 1) {
+                fail(`real write invocation delta is ${realCount() - beforeReal}`);
+            }
+        }
+        // 7. Missing required grants fail BEFORE handler invocation.
+        if (requiredPermissions.length > 0) {
+            const ungranted = createRuntime({ stores: createInMemoryStores() });
+            installCapabilityPack(ungranted, pack);
+            await ungranted.activate(defineGraph({
+                id: `conformance.${fixture.writeCapabilityId}.ungranted`,
+                entry: 'only',
+                nodes: [{ id: 'only', capability: fixture.writeCapabilityId }],
+                edges: [],
+            }));
+            const beforeUngranted = realCount();
+            const denied = await ungranted.run(fixture.writeInput, { mode: 'normal' });
+            if (denied.status !== 'failed') {
+                fail(`ungranted write did not fail: ${denied.status}`);
+            }
+            if (denied.error?.code !== 'VICT_RUNTIME_PERMISSION_DENIED') {
+                fail(`ungranted write failed with the wrong code: ${String(denied.error?.code)}`);
+            }
+            if (realCount() !== beforeUngranted) {
+                fail('the real write handler ran without a required grant');
+            }
+        }
+    }
+}
+//# sourceMappingURL=pack-conformance.js.map

package/dist/pack-conformance.js.map

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

package/dist/pack-install.d.ts

@@ -0,0 +1,44 @@
+import type { CapabilityPack } from '@victframework/sdk';
+import type { VictRuntime } from './runtime.js';
+/**
+ * Stage 04: explicit, LOCAL capability-pack installation.
+ *
+ * Loading a pack is a deliberate act: the manifest is cross-validated
+ * against the executable bindings (missing, duplicate, extra, or
+ * revision-mismatched bindings fail deterministically), the declared
+ * Vict compatibility is checked against the consuming runtime's version,
+ * and only then are contracts, capabilities, and declared doubles
+ * registered ATOMICALLY.
+ *
+ * Audit remediation (HIGH-04-A): installation is a registry-level STAGED
+ * BATCH. Every contract, capability, and declared double is validated and
+ * preflighted (including collisions against the live registry and inside
+ * the batch) BEFORE any live map is touched; the complete batch commits
+ * only when every step succeeds. A failed installation leaves the registry
+ * byte-for-byte semantically unchanged: no capability, contract, or double
+ * from the attempted pack is resolvable afterwards. There is no best-effort
+ * rollback of partially registered entries because nothing is registered
+ * until success is certain.
+ *
+ * Audit remediation (MED-04-B): the pack's declared doubles
+ * (`manifest.doubles` + `bindings.doubles`) are installed atomically WITH
+ * the pack. A pack-declared double is eligible ONLY in the modes its
+ * manifest declares (`modes: ['test','simulate']`); it never runs in
+ * normal mode. No manual `runtime.registerDouble` call is needed.
+ *
+ * There is no remote loading, no automatic package installation, and no
+ * untrusted execution anywhere in this path.
+ */
+/** The public Vict compatibility this runtime provides. */
+export declare const VICT_RUNTIME_COMPAT_VERSION = "0.1.0";
+/**
+ * Permission grants live on the RUNTIME (createRuntime({ authority })),
+ * never on the install call: authorization is a runtime-level decision.
+ * A pack installed without its required grants registers fine, but
+ * invoking a capability whose declared permissions are ungranted fails
+ * BEFORE the handler runs (VICT_RUNTIME_PERMISSION_DENIED).
+ */
+/** Install a capability pack into one runtime. Throws structured VictRuntimeErrors on failure. */
+export declare function installCapabilityPack(runtime: VictRuntime, pack: CapabilityPack): {
+    readonly installed: readonly string[];
+};

package/dist/pack-install.js

@@ -0,0 +1,126 @@
+import { validateCapabilityPack } from '@victframework/sdk';
+import { VictRuntimeError } from './errors.js';
+/**
+ * Stage 04: explicit, LOCAL capability-pack installation.
+ *
+ * Loading a pack is a deliberate act: the manifest is cross-validated
+ * against the executable bindings (missing, duplicate, extra, or
+ * revision-mismatched bindings fail deterministically), the declared
+ * Vict compatibility is checked against the consuming runtime's version,
+ * and only then are contracts, capabilities, and declared doubles
+ * registered ATOMICALLY.
+ *
+ * Audit remediation (HIGH-04-A): installation is a registry-level STAGED
+ * BATCH. Every contract, capability, and declared double is validated and
+ * preflighted (including collisions against the live registry and inside
+ * the batch) BEFORE any live map is touched; the complete batch commits
+ * only when every step succeeds. A failed installation leaves the registry
+ * byte-for-byte semantically unchanged: no capability, contract, or double
+ * from the attempted pack is resolvable afterwards. There is no best-effort
+ * rollback of partially registered entries because nothing is registered
+ * until success is certain.
+ *
+ * Audit remediation (MED-04-B): the pack's declared doubles
+ * (`manifest.doubles` + `bindings.doubles`) are installed atomically WITH
+ * the pack. A pack-declared double is eligible ONLY in the modes its
+ * manifest declares (`modes: ['test','simulate']`); it never runs in
+ * normal mode. No manual `runtime.registerDouble` call is needed.
+ *
+ * There is no remote loading, no automatic package installation, and no
+ * untrusted execution anywhere in this path.
+ */
+/** The public Vict compatibility this runtime provides. */
+export const VICT_RUNTIME_COMPAT_VERSION = '0.1.0';
+/**
+ * Permission grants live on the RUNTIME (createRuntime({ authority })),
+ * never on the install call: authorization is a runtime-level decision.
+ * A pack installed without its required grants registers fine, but
+ * invoking a capability whose declared permissions are ungranted fails
+ * BEFORE the handler runs (VICT_RUNTIME_PERMISSION_DENIED).
+ */
+/** Install a capability pack into one runtime. Throws structured VictRuntimeErrors on failure. */
+export function installCapabilityPack(runtime, pack) {
+    const validation = validateCapabilityPack(pack, {
+        victVersion: VICT_RUNTIME_COMPAT_VERSION,
+    });
+    if (!validation.ok) {
+        throw packInvalidError(pack, validation.issues);
+    }
+    const declared = new Map(pack.manifest.capabilities.map((entry) => [entry.id, entry]));
+    const declaredDoubles = new Map((pack.manifest.doubles ?? []).map((entry) => [entry.capabilityId, entry]));
+    // Atomic staged batch: every validation, preflight collision check, and
+    // effective registration happens against the staging overlay. The live
+    // registry is committed only after ALL steps succeed.
+    runtime.installCapabilityPackBatch((staging) => {
+        // Register each distinct contract object once (shared frozen contracts
+        // keep their object identity). Registration inside the batch validates
+        // every contract against the live registry + the staged overlay.
+        const registeredContracts = new Set();
+        for (const binding of pack.bindings.capabilities) {
+            for (const contract of [binding.input, binding.output]) {
+                if (contract && !registeredContracts.has(contract.id)) {
+                    staging.registerContract(contract);
+                    registeredContracts.add(contract.id);
+                }
+            }
+        }
+        // Preflight + stage every effective capability registration without
+        // mutating any live map.
+        const installed = [];
+        for (const binding of pack.bindings.capabilities) {
+            const declaration = declared.get(binding.id);
+            if (!declaration) {
+                continue; // validated above
+            }
+            staging.registerCapability({
+                id: binding.id,
+                revision: binding.revision,
+                effect: declaration.effect,
+                invoke: binding.invoke,
+                ...(declaration.idempotency !== undefined ? { idempotency: declaration.idempotency } : {}),
+                ...(binding.input !== undefined ? { input: binding.input } : {}),
+                ...(binding.output !== undefined ? { output: binding.output } : {}),
+                ...(declaration.permissions !== undefined
+                    ? { permissions: [...declaration.permissions] }
+                    : {}),
+                ...(declaration.configuration !== undefined
+                    ? { configuration: [...declaration.configuration] }
+                    : {}),
+                ...(declaration.requiredConfiguration !== undefined
+                    ? { requiredConfiguration: [...declaration.requiredConfiguration] }
+                    : {}),
+                ...(declaration.secrets !== undefined ? { secrets: [...declaration.secrets] } : {}),
+                ...(declaration.requiredSecrets !== undefined
+                    ? { requiredSecrets: [...declaration.requiredSecrets] }
+                    : {}),
+            });
+            installed.push(binding.id);
+        }
+        // Install the declared bound doubles atomically with the pack (MED-04-B).
+        // Eligibility is the manifest's declared `modes` (default: test +
+        // simulate); a declared double never runs in normal mode.
+        for (const double of pack.bindings.doubles ?? []) {
+            const declaration = declaredDoubles.get(double.capabilityId);
+            staging.registerDouble(double.capabilityId, double.invoke, {
+                modes: declaration?.modes ?? ['test', 'simulate'],
+            });
+        }
+    });
+    return { installed: Object.freeze(pack.bindings.capabilities.map((binding) => binding.id)) };
+}
+function packInvalidError(pack, issues) {
+    const code = 'VICT_PACK_INVALID';
+    const summary = issues
+        .slice(0, 5)
+        .map((issue) => `${issue.code}: ${issue.message}`)
+        .join(' | ');
+    return new VictRuntimeError(code, `Capability pack '${pack.manifest.id}' is not installable: ${summary}`, {
+        packId: pack.manifest.id,
+        issues: issues.map((issue) => ({
+            code: issue.code,
+            message: issue.message,
+            path: issue.path,
+        })),
+    });
+}
+//# sourceMappingURL=pack-install.js.map

package/dist/pack-install.js.map

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

package/dist/registry.d.ts

@@ -0,0 +1,107 @@
+import { type Contract } from '@victframework/contracts';
+import type { CapabilityDescriptor, CapabilityIndex, ContractEnvironment } from '@victframework/kernel';
+import type { CapabilityDefinition, DoubleInvoke } from './types.js';
+import { type CapabilityAuthority } from './authority.js';
+/** A frozen copy of the execution-relevant parts of a capability definition. */
+export interface FrozenCapabilityBinding {
+    readonly id: string;
+    readonly revision: string;
+    readonly effect: CapabilityDefinition['effect'];
+    readonly invoke: CapabilityDefinition['invoke'];
+    /** Declared idempotency semantics (drives write-timeout retry classification). */
+    readonly idempotency?: CapabilityDefinition['idempotency'];
+    readonly inputContractId?: string;
+    readonly inputRevision?: string;
+    readonly outputContractId?: string;
+    readonly outputRevision?: string;
+    readonly authority?: CapabilityDescriptor['authority'];
+}
+/** Modes in which a registered test double is eligible to run. */
+export type DoubleMode = 'test' | 'simulate';
+/** A registered test double with its declared mode-eligibility policy. */
+export interface RegisteredDouble {
+    readonly invoke: DoubleInvoke;
+    /** The double NEVER runs in 'normal' mode; only these declared modes may use it. */
+    readonly modes: ReadonlySet<DoubleMode>;
+}
+/** Staging area for an atomic capability-pack installation. */
+export interface RegistryStagingArea {
+    registerContract(contract: Contract<unknown>): void;
+    registerCapability(definition: CapabilityDefinition): void;
+    registerDouble(capabilityId: string, invoke: DoubleInvoke, options?: {
+        readonly modes?: readonly DoubleMode[];
+    }): void;
+}
+/**
+ * Owns registered capabilities, contracts, and test doubles for one runtime.
+ * Not a global registry: every runtime instance carries its own.
+ *
+ * Registration validates author/build revisions and the full executable
+ * definition (closed fields, effect vocabulary, CONT-001 contract presence,
+ * authority names), because revisions and declarations feed activation
+ * identity. Live maps are never exposed: consumers receive descriptors or
+ * frozen copies.
+ *
+ * Atomic registration (HIGH-04-A / LOW-RE-3): `installBatch` stages every
+ * contract/capability/double against a staging overlay WITHOUT mutating any
+ * live map, and commits the complete batch only when every step succeeds.
+ * The direct public `registerCapability` path uses the SAME staging
+ * mechanism (capability + embedded contracts staged together), so ANY
+ * failure — including a contract conflict — leaves the registry
+ * byte-for-byte semantically unchanged. There is no best-effort rollback
+ * of partially registered entries.
+ */
+export declare class CapabilityRegistry {
+    #private;
+    constructor(authority?: CapabilityAuthority);
+    registerCapability(definition: CapabilityDefinition): void;
+    registerContract(contract: Contract<unknown>): void;
+    /**
+     * Register a test double. Doubles are runtime test configuration: they are
+     * not part of activation identity, and each run snapshots them at run
+     * start. A double NEVER runs in normal mode; without an explicit
+     * `modes` option it is eligible in both 'test' and 'simulate'. Duplicate
+     * registration is rejected — use `replaceDouble` for an explicit
+     * replacement.
+     */
+    registerDouble(capabilityId: string, invoke: DoubleInvoke, options?: {
+        readonly modes?: readonly DoubleMode[];
+    }): void;
+    /** Explicitly replace an existing test double. Requires a double to be registered. */
+    replaceDouble(capabilityId: string, invoke: DoubleInvoke): void;
+    hasDouble(capabilityId: string): boolean;
+    getDoubleModes(capabilityId: string): ReadonlySet<DoubleMode> | undefined;
+    /** Snapshot the current doubles at run start. In-flight runs cannot observe later changes. */
+    snapshotDoubles(): ReadonlyMap<string, RegisteredDouble>;
+    getCapability(capabilityId: string): CapabilityDefinition<unknown, unknown> | undefined;
+    /** Resolve a capability by exact revision (suspended-run restoration). */
+    getCapabilityRevision(capabilityId: string, revision: string): CapabilityDefinition<unknown, unknown> | undefined;
+    getContract(contractId: string): Contract<unknown> | undefined;
+    /** Resolve a contract by exact revision (suspended-run restoration). */
+    getContractRevision(contractId: string, revision: string): Contract<unknown> | undefined;
+    /**
+     * Install a batch atomically. `step` registers contracts, capabilities,
+     * and doubles through the staging area; NOTHING touches the live maps
+     * until the callback returns successfully. Any throw — a validation
+     * failure, a collision with the live registry, or a collision inside the
+     * batch — discards the staging overlay and leaves the registry
+     * semantically unchanged: no capability, contract, or double from the
+     * attempted batch is resolvable afterwards.
+     *
+     * The staging overlay participates in collision checks, so both
+     * batch-vs-registry and batch-internal duplicates are detected BEFORE any
+     * commit.
+     */
+    installBatch(install: (staging: RegistryStagingArea) => void): void;
+    /**
+     * A capability index pinned to EXACT revisions (suspended-run
+     * restoration). Unknown id/revision pairs resolve to undefined so the
+     * kernel reports structured missing-artifact diagnostics instead of
+     * silently substituting a nearby revision.
+     */
+    capabilityIndex(): CapabilityIndex;
+    capabilityIndexPinned(revisions: ReadonlyMap<string, string>): CapabilityIndex;
+    contractEnvironment(): ContractEnvironment;
+    /** A contract environment pinned to exact revisions (suspended-run restoration). */
+    contractEnvironmentPinned(revisions: ReadonlyMap<string, string>): ContractEnvironment;
+}