@vibesdotdev/runnable 0.0.0-stage → 1.0.0-rc.1

package/dist/client.js

@@ -0,0 +1,1181 @@
+/**
+ * RunnableClient — canonical `runtime/client` for the runnable module.
+ *
+ * Resolves the runnable-web ingest endpoint from a per-runtime host context,
+ * then defers to `createRunner()` for the actual
+ * batched-POST telemetry transport. Producers use:
+ *
+ * ```ts
+ * import { getVibesRunnableClient } from '@vibesdotdev/runnable/client';
+ *
+ * const runnable = await getVibesRunnableClient(context.runtime);
+ * const run = await runnable.createRun({ type: 'cgn-train', name: 'tiny-2pass' });
+ * await run.start({ N: 32, k: 64 });
+ * await run.metric('reward', 0.42);
+ * await run.done();
+ * ```
+ *
+ * The host supplies `runnable/host`; no process/global URL fallback exists.
+ */
+import { CapabilityError, CaughtFailureSchema, captureRuntimeWorkspace, isCapabilityError, valueFreeFailure } from '@vibesdotdev/kernel';
+import { getRuntimeMemoRevision } from '@vibesdotdev/kernel/memo-revision';
+import { hashHex } from '@vibesdotdev/crypto/hash';
+import { JsonObjectSchema, JsonValueSchema, JsonValueFromReaderSchema } from '@vibesdotdev/kernel/schemas/json';
+import { RunnableDescriptorSchema, RunnableTypeDescriptorSchema, RunnableTelemetryDescriptorSchema, RunnableVisualizationDescriptorSchema } from "./schemas/descriptors.js";
+import { OutcomeSchema, done } from "./schemas/outcome.js";
+import { MemoIdentitySchema, RunRecordSchema, RunExecutionReferenceSchema, RunCompletedPayloadSchema, RUN_COMPLETED_EVENT, RunnableNativeExecutionSchema, RunnableNativeExecutionStateSchema, RunnableNativeObservationSchema, RUN_NATIVE_EXECUTION_METADATA_KEY, RunnableReadQuerySchema } from "./schemas/runs.js";
+import { BaseRuntimeClient } from "@vibesdotdev/kernel/client";
+import { canonical } from "./identity.js";
+import { runEventEnvelopeSchema } from "./schemas/events.js";
+import { captureRunAdmission, mergeRunEventMetadata, RUN_ADMISSION_METADATA_KEY, RUN_INPUT_ADMISSION_METADATA_KEY } from "./records/authority.js";
+import { readInputAdmission } from "./input-admission.js";
+import { createRunner } from "./runner.js";
+import { recordRunHandle } from "./recording.js";
+import { getRunnableInvocation, withRunnableInvocation } from "./invocation.js";
+import { RunnableExecutionInputSchema, RunnableSpawnRequestSchema, RunnableStartInputSchema, RunnablePreparedInputSchema, RunnableControlActionSchema, RunnableControlInputSchema } from "./schemas/contracts.js";
+import { RUNNABLE_HOST_CONTEXT_ID, RUNNABLE_STATE_HOST_CONTEXT_ID } from "./host.js";
+import { RUNNABLE_SUPERVISOR_ID } from "./execution.contract.js";
+import { RunnableSnapshotSchema, RunnableTrackedRunSchema, RunnableCatalogRunSchema, RunnableWatchProjectionSchema } from "./schemas/runs.js";
+import { watchRunnableSnapshots } from "./watch.js";
+import { RunnableDescriptionSchema, RunnableDescriptionSchemasSchema } from "./schemas/description.js";
+import { bindRunContext, latestRunObservation, runContextBindings, runContextReferenceId } from "./context.js";
+import { RunnableNativeCompletionOutboxSchema, RUN_NATIVE_COMPLETION_METADATA_KEY } from "./schemas/runs.js";
+import { assertRunWrite } from "./records/authority.js";
+const EVENTS_PATH = "/api/events";
+export class RunnableClient extends BaseRuntimeClient {
+    resolvedUrl = null;
+    request;
+    directRun;
+    nativeObservers = new Map();
+    nativeFinalizers = new Map();
+    /** Parsed configs for record generations still being re-read. The oldest leaves. */
+    admittedConfigs = new Map();
+    constructor(descriptor = { id: "runnable", kind: "runtime/client" }, context, runtime) {
+        super(descriptor, context, runtime);
+    }
+    async onLoad() {
+        await super.onLoad();
+        const host = await this.runtime.context(RUNNABLE_HOST_CONTEXT_ID);
+        if (host.transport === 'in-process') {
+            this.directRun = options => host.createRun(options);
+            return;
+        }
+        this.request = host.request;
+        let url;
+        try {
+            url = new URL(host.eventsUrl);
+        }
+        catch (error) {
+            throw new CapabilityError('Runnable host supplied invalid eventsUrl.', 'INVALID_INPUT', { reason: 'runnable-events-url-invalid', cause: error });
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new CapabilityError('Runnable eventsUrl must use http or https.', 'INVALID_INPUT', { reason: 'runnable-events-url-protocol-invalid', details: { protocol: url.protocol } });
+        }
+        this.resolvedUrl = url.pathname !== '/'
+            ? url.toString()
+            : new URL(EVENTS_PATH, url).toString();
+    }
+    /** Resolved events URL after `load()`. Throws if not yet loaded. */
+    get eventsUrl() {
+        if (this.directRun) {
+            throw new CapabilityError('The selected in-process host has no HTTP event endpoint.', 'UNAVAILABLE', { reason: 'runnable-events-url-unavailable' });
+        }
+        if (!this.resolvedUrl) {
+            throw new CapabilityError('Runnable client is not loaded.', 'INTERNAL', { reason: 'runnable-client-not-loaded' });
+        }
+        return this.resolvedUrl;
+    }
+    /**
+     * Create a run-emitter handle. The mandatory `type` matches a
+     * registered `runnable/type` descriptor; the runtime client resolves
+     * the ingest URL once and passes it to the underlying runner.
+     */
+    async createRun(options) {
+        await this.ensureLoaded();
+        if (this.directRun)
+            return this.directRun(options);
+        return createRunner({ ...options, url: this.eventsUrl, lifecycle: this.runtime.lifecycle, request: this.request });
+    }
+    async start(input) {
+        const parsedInput = RunnableStartInputSchema.safeParse(input);
+        if (!parsedInput.success) {
+            throw new CapabilityError('Runnable start input is invalid.', 'INVALID_INPUT', {
+                reason: 'runnable-start-input-invalid',
+                retryable: false
+            });
+        }
+        const start = parsedInput.data;
+        await this.ensureLoaded();
+        const executorQuery = this.runtime
+            .query('runnable/executor')
+            .withId(start.typeId);
+        if (executorQuery.descriptors().length === 0)
+            return { runId: start.runId, spawned: false };
+        const executor = await executorQuery.resolve();
+        const request = await executor.execute({ runId: start.runId, config: start.config, configUnit: start.configUnit });
+        if (!request)
+            return { runId: start.runId, spawned: false };
+        const task = OutcomeSchema.safeParse(request);
+        if (task.success)
+            return { runId: start.runId, spawned: false, outcome: task.data };
+        const parsedRequest = RunnableSpawnRequestSchema.safeParse(request);
+        if (!parsedRequest.success) {
+            throw new CapabilityError('Runnable executor returned an invalid spawn request.', 'INVALID_INPUT', {
+                reason: 'runnable-spawn-request-invalid',
+                retryable: false
+            });
+        }
+        const supervisor = await this.supervisor();
+        return supervisor.spawn(start.runId, parsedRequest.data, start.ingestCredential);
+    }
+    async select(query) {
+        return (await this.runtime.query('runnable/runnable').enabled().descriptorsAsync())
+            .map((descriptor) => RunnableDescriptorSchema.parse(descriptor))
+            .filter((descriptor) => descriptor.roles.includes(query.role) &&
+            (!query.entity || !descriptor.entities || descriptor.entities.includes(query.entity)))
+            .sort((left, right) => left.cost - right.cost || left.id.localeCompare(right.id));
+    }
+    async run(id, input, options) {
+        return (await this.runRecorded(id, input, options)).outcome;
+    }
+    async runAll(query, input, options) {
+        const candidates = await this.select(query);
+        return Promise.all(candidates.map((candidate) => this.run(candidate.id, input, options)));
+    }
+    async runBest(query, input, options) {
+        const candidate = (await this.select(query))[0];
+        if (!candidate) {
+            throw new CapabilityError('No runnable covers the requested role and entity.', 'UNAVAILABLE', { reason: 'runnable-selection-empty' });
+        }
+        const selected = await this.selectNamed(candidate.id);
+        return (await this.executeRecorded(selected.descriptor, input, options, { coldStart: true, cost: selected.descriptor.cost }, selected.impl)).outcome;
+    }
+    async runRecorded(id, input, options) {
+        const selected = await this.selectNamed(id);
+        return this.executeRecorded(selected.descriptor, input, options, { named: true }, selected.impl);
+    }
+    /** Receive an already admitted native execution through this same record owner, without dispatching another job. */
+    async recordNativeExecution(id, input, execute, options, nativeExecution) {
+        const selected = await this.selectNamed(id);
+        if (selected.descriptor.execution !== 'native') {
+            throw new CapabilityError('Receiving execution must belong to a native Runnable.', 'INVALID_INPUT', { reason: 'runnable-native-admission-invalid' });
+        }
+        const owner = { execute };
+        if (selected.impl.prepareInput)
+            owner.prepareInput = selected.impl.prepareInput.bind(selected.impl);
+        return this.executeRecorded({ ...selected.descriptor, memo: false }, input, options, { named: true }, owner, nativeExecution);
+    }
+    /** Attach the receiving owner's receipt to the producer's certified, frozen input record. */
+    async recordPreparedExecution(runId, execute, nativeExecution, options) {
+        const receipt = RunnableNativeExecutionSchema.parse(nativeExecution);
+        const held = options?.held?.record.id === runId ? options.held : await this.inputAdmission(runId);
+        if (!held || held.admission.owner.kind !== 'runnable/runnable') {
+            throw new CapabilityError('Prepared native execution needs its selected owner admission.', 'PERMISSION_DENIED', { reason: 'runnable-input-admission-mismatch' });
+        }
+        assertRunWrite(held.record, captureRunAdmission(this.runtime), await this.scopeIdentity());
+        const selected = await this.runtime.query('runnable/runnable').withId(held.admission.owner.id).select();
+        if (!selected)
+            throw new CapabilityError('The prepared native owner is unavailable.', 'UNAVAILABLE', { reason: 'runnable-native-owner-unavailable' });
+        const descriptor = RunnableDescriptorSchema.parse(selected.descriptor);
+        if (descriptor.id !== held.record.runnableId || descriptor.execution !== 'native') {
+            throw new CapabilityError('The receiving owner differs from its prepared admission.', 'PERMISSION_DENIED', { reason: 'runnable-native-execution-mismatch' });
+        }
+        return this.executeRecorded({ ...descriptor, memo: false, nativeResult: receipt.result.mode }, held.record.metadata['runnable.submittedInput'] ?? null, {
+            signal: options?.signal, configUnit: RunnableExecutionInputSchema.shape.configUnit.parse(held.record.metadata.configUnit)
+        }, { named: true }, { execute }, receipt, held.record);
+    }
+    async selectNamed(id) {
+        const selected = await this.runtime.query('runnable/runnable').withId(id).enabled().select();
+        if (!selected) {
+            throw new CapabilityError(`Runnable '${id}' is not registered.`, 'UNAVAILABLE', { reason: 'runnable-unknown' });
+        }
+        return { descriptor: RunnableDescriptorSchema.parse(selected.descriptor), impl: selected.impl };
+    }
+    async describe(id, receive) {
+        const selected = await this.selectNamed(id);
+        const executor = selected.descriptor.execution === 'native' ? null : await this.runtime
+            .query('runnable/executor')
+            .enabled().filter(candidate => candidate.runnableType === selected.descriptor.type).select();
+        const described = executor
+            ? await executor.impl.describe?.(selected.descriptor.settings)
+            : await selected.impl.describe?.();
+        const description = RunnableDescriptionSchema.parse(JsonValueFromReaderSchema.parse({
+            descriptor: selected.descriptor,
+            ...RunnableDescriptionSchemasSchema.parse(described ?? {})
+        }));
+        if (receive)
+            await receive(description);
+        else
+            return description;
+    }
+    /** Validated only after the record owner's authorized by-ID read. */
+    async inputAdmission(runId, expectedConfig) {
+        const record = await this.storedRecord(runId);
+        if (!record)
+            return null;
+        const admission = await readInputAdmission(this.runtime, record);
+        if (admission && expectedConfig !== undefined && admission.configDigest !== await hashHex(this.runtime, 'sha256', canonical(expectedConfig))) {
+            throw new CapabilityError('Queued input differs from the owner-admitted config.', 'PERMISSION_DENIED', { reason: 'runnable-input-admission-mismatch' });
+        }
+        return admission ? { record, admission } : null;
+    }
+    /** Receiving execution must also possess the persistence owner's write authority. */
+    async attachInputAdmission(runId, config, jobId, known) {
+        if (known?.record.id === runId && known.admission.configDigest !== await hashHex(this.runtime, 'sha256', canonical(config))) {
+            throw new CapabilityError('Queued input differs from the owner-admitted config.', 'PERMISSION_DENIED', { reason: 'runnable-input-admission-mismatch' });
+        }
+        const held = known?.record.id === runId ? known : await this.inputAdmission(runId, config);
+        if (!held || held.record.ref?.jobId !== jobId) {
+            throw new CapabilityError(held ? 'Execution reference differs from its input admission.' : 'Execution input admission is unavailable to this owner.', 'PERMISSION_DENIED', {
+                reason: 'runnable-input-admission-mismatch',
+                details: {
+                    runId, jobId, admissionPresent: held !== null,
+                    admittedJobId: held?.record.ref?.jobId ?? null
+                }
+            });
+        }
+        await (await this.records()).save(held.record);
+        return held;
+    }
+    /** Reuse the authorized record's emitter; this does not admit another execution or start event. */
+    async attachHandle(runId) {
+        const record = await this.record(runId);
+        if (!record)
+            throw new CapabilityError('The execution record is unavailable.', 'NOT_FOUND', { reason: 'runnable-run-not-found' });
+        const records = await this.records();
+        await records.save(record);
+        const native = record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] === undefined
+            ? undefined : RunnableNativeExecutionStateSchema.parse(record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY]);
+        const attempt = native?.attempts.at(-1);
+        if (native && (!attempt || attempt.generation !== native.generation)) {
+            throw new CapabilityError('Native handle has no admitted physical attempt.', 'UNAVAILABLE', { reason: 'runnable-native-attempt-unavailable' });
+        }
+        // A retained handle belongs to this admission even after another attempt starts.
+        const emitter = await this.createRun({ runId: record.id, type: record.runnableType, name: record.name ?? record.runnableId,
+            executionGeneration: native?.generation, executionAttempt: attempt?.attempt });
+        return recordRunHandle(emitter, record, records).handle;
+    }
+    async scopeIdentity() {
+        let workspace = null;
+        if (this.runtime.hasContext('runtime/workspace-path')) {
+            try {
+                workspace = await this.runtime.context('runtime/workspace-path');
+            }
+            catch (error) {
+                if (!(error instanceof Error && CapabilityError.isAbsenceOf(error, 'context', 'runtime/workspace-path')))
+                    throw error;
+            }
+        }
+        // Only principal-declaring hosts call requestPrincipal; an inactive invocation is a real refusal.
+        // Identity contains no JWT or session credential.
+        const principal = this.runtime.scope.capabilities?.requestPrincipals === true ? this.runtime.requestPrincipal() : null;
+        let caller = null;
+        if (principal?.kind === 'user') {
+            caller = JsonValueSchema.parse({
+                kind: principal.kind, userId: principal.userId, orgId: principal.orgId ?? null,
+                projectId: principal.projectId ?? null, agentId: principal.agentPrincipal?.agentId ?? null,
+                agentOwner: principal.agentPrincipal?.owner ?? null,
+                agentKeyId: principal.agentPrincipal?.keyId ?? null,
+                agentScopes: [...(principal.agentPrincipal?.scopes ?? [])].sort(),
+                roles: [...(principal.roles ?? [])].sort(),
+                orgs: principal.orgs ? [...principal.orgs].sort((left, right) => left.id.localeCompare(right.id)) : [],
+                staff: principal.staff ?? null, isSuperuser: principal.isSuperuser ?? null
+            });
+        }
+        else if (principal?.kind === 'service') {
+            caller = JsonValueSchema.parse({
+                kind: principal.kind, caller: principal.caller, onBehalfOf: principal.onBehalfOf ?? null,
+                delegation: principal.delegation ?? null
+            });
+        }
+        else if (principal) {
+            caller = principal;
+        }
+        const invocation = captureRuntimeWorkspace(this.runtime);
+        const workspaceIdentity = invocation ? {
+            id: invocation.id ?? null,
+            target: invocation.target ?? null,
+            remoteHostId: invocation.remoteHostId ?? null,
+            access: invocation.access ?? null
+        } : null;
+        const scope = invocation
+            ? { ...this.runtime.scope, workspace: { root: invocation.root, access: invocation.access } }
+            : this.runtime.scope;
+        return canonical({ scope, workspace, ...(workspaceIdentity ? { workspaceIdentity } : {}), caller });
+    }
+    async runs(input) {
+        const query = RunnableReadQuerySchema.strict().parse(input);
+        const { status, ...ownerQuery } = query;
+        const host = await this.stateHost();
+        const rows = host.tracking ? await host.tracking.list(ownerQuery) : host.reads?.list ? await host.reads.list(ownerQuery) : null;
+        if (rows) {
+            const views = await Promise.all(rows.map(record => this.trackingView(record)));
+            return views.filter(record => status === undefined || record.outcome?.status === status);
+        }
+        if (query.type !== undefined || query.under !== undefined || query.host !== undefined || query.input !== undefined || query.about !== undefined) {
+            throw new CapabilityError('The selected Runnable host does not support scoped read queries.', 'UNAVAILABLE', { reason: 'runnable-read-query-unavailable' });
+        }
+        const records = await this.records();
+        const scope = await this.scopeIdentity();
+        const views = await Promise.all((await records.list({ ...ownerQuery, scope })).map(record => this.trackingView(record)));
+        return views.filter(record => status === undefined || record.outcome?.status === status);
+    }
+    /** Read by identifier through the persistence owner's actual admission boundary. */
+    async record(input) {
+        const record = await this.storedRecord(input);
+        if (!record)
+            return null;
+        const observation = await this.observeNative(record);
+        return observation ? this.nativeView(record, observation) : record;
+    }
+    /** Status is parsed every read. Config is reused while the input digest is unchanged. */
+    admittedConfig(id, inputDigest, config) {
+        const key = `${id}:${inputDigest}`;
+        const remembered = this.admittedConfigs.get(key);
+        if (remembered) {
+            this.admittedConfigs.delete(key);
+            this.admittedConfigs.set(key, remembered);
+            return remembered;
+        }
+        const parsed = JsonObjectSchema.parse(config);
+        this.admittedConfigs.set(key, parsed);
+        while (this.admittedConfigs.size > 64) {
+            const oldest = this.admittedConfigs.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.admittedConfigs.delete(oldest);
+        }
+        return parsed;
+    }
+    async storedRecord(input) {
+        const id = RunRecordSchema.shape.id.parse(input);
+        const host = await this.stateHost();
+        const raw = host.reads
+            ? await host.reads.get(id)
+            : (await (await this.records()).list({ scope: await this.scopeIdentity(), id })).find(record => record.id === id) ?? null;
+        if (!raw)
+            return null;
+        const shell = RunRecordSchema.omit({ config: true }).parse(raw);
+        return { ...shell, config: this.admittedConfig(shell.id, shell.inputDigest, raw.config) };
+    }
+    async resolveNativeOwner(owner) {
+        return this.runtime.query(owner.kind).withId(owner.id).resolve();
+    }
+    nativeObserverView(owner, implementation) {
+        if (!implementation.observe)
+            throw new CapabilityError('The admitted native owner cannot observe its receipt.', 'UNAVAILABLE', {
+                reason: 'runnable-native-observation-unavailable'
+            });
+        return {
+            owner,
+            observe: implementation.observe.bind(implementation),
+            subscribeObservation: implementation.subscribeObservation?.bind(implementation)
+        };
+    }
+    async nativeObserver(record) {
+        const execution = RunnableNativeExecutionStateSchema.parse(record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY]);
+        if (execution.observer) {
+            return this.nativeObserverView(execution.observer, await this.resolveNativeOwner(execution.observer));
+        }
+        const native = await this.runtime.query('runnable/runnable')
+            .withId(record.runnableId).enabled().select();
+        if (native?.impl.observe)
+            return this.nativeObserverView({ kind: 'runnable/runnable', id: native.descriptor.id }, native.impl);
+        const executor = await this.runtime.query('runnable/executor')
+            .enabled().filter(owner => owner.runnableType === record.runnableType).select();
+        if (!executor?.impl.observe)
+            throw new CapabilityError('The native execution owner does not provide receipt observation.', 'UNAVAILABLE', { reason: 'runnable-native-observation-unavailable' });
+        return this.nativeObserverView({ kind: 'runnable/executor', id: executor.descriptor.id }, executor.impl);
+    }
+    async observeNative(record) {
+        if (record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] === undefined)
+            return null;
+        return RunnableNativeObservationSchema.parse(await (await this.nativeObserver(record)).observe(record));
+    }
+    /** Explicit admitted execution repair. Read APIs never call this operation. */
+    async reconcileNativeExecution(runId) {
+        const pending = this.nativeFinalizers.get(runId);
+        if (pending) {
+            const record = await this.storedRecord(runId);
+            if (!record)
+                throw new CapabilityError('Native execution record is unavailable.', 'NOT_FOUND', { reason: 'runnable-run-not-found' });
+            assertRunWrite(record, captureRunAdmission(this.runtime), await this.scopeIdentity());
+            return pending;
+        }
+        const work = this.reconcileNativeOnce(runId);
+        this.nativeFinalizers.set(runId, work);
+        try {
+            return await work;
+        }
+        finally {
+            if (this.nativeFinalizers.get(runId) === work)
+                this.nativeFinalizers.delete(runId);
+        }
+    }
+    async reconcileNativeOnce(runId) {
+        let record = await this.storedRecord(runId);
+        if (!record)
+            throw new CapabilityError('Native execution record is unavailable.', 'NOT_FOUND', { reason: 'runnable-run-not-found' });
+        assertRunWrite(record, captureRunAdmission(this.runtime), await this.scopeIdentity());
+        const observed = await this.observeNative(record);
+        if (!observed)
+            throw new CapabilityError('Run has no admitted native execution reference.', 'INVALID_INPUT', { reason: 'runnable-native-execution-absent' });
+        // The body persists its attempt evidence before the queue commits its
+        // receipt. Refresh that evidence after observing the terminal receipt.
+        record = await this.storedRecord(runId);
+        if (!record)
+            throw new CapabilityError('Native execution record is unavailable.', 'NOT_FOUND', { reason: 'runnable-run-not-found' });
+        assertRunWrite(record, captureRunAdmission(this.runtime), await this.scopeIdentity());
+        const execution = RunnableNativeExecutionStateSchema.parse(record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY]);
+        if (observed.terminal && execution.generation !== observed.generation) {
+            throw new CapabilityError('Native execution changed while its terminal receipt was being observed.', 'CONFLICT', { reason: 'runnable-native-execution-changed' });
+        }
+        const outbox = RunnableNativeCompletionOutboxSchema.parse(record.metadata[RUN_NATIVE_COMPLETION_METADATA_KEY] ?? []);
+        const records = await this.records();
+        if (observed.terminal && !outbox.some(completion => completion.receiptId === observed.receiptId)) {
+            if (!observed.outcome)
+                throw new CapabilityError('Terminal native receipt has no task outcome.', 'UNAVAILABLE', { reason: 'runnable-native-outcome-unavailable' });
+            const attempt = execution.attempts.at(-1);
+            if (!attempt || attempt.generation !== observed.generation)
+                throw new CapabilityError('Terminal native receipt has no admitted attempt.', 'UNAVAILABLE', { reason: 'runnable-native-attempt-unavailable' });
+            const view = this.nativeView(record, observed);
+            const eventId = `completion-${await hashHex(this.runtime, 'sha256', canonical({ runId, receipt: observed.receiptId }))}`;
+            outbox.push({
+                receiptId: observed.receiptId,
+                eventId, generation: observed.generation, attempt: attempt.attempt,
+                timestamp: observed.endedAt ?? Date.now(), delivered: false,
+                payload: RunCompletedPayloadSchema.parse(JsonValueFromReaderSchema.parse({ runId, occurrenceId: eventId, generation: observed.generation, attempt: attempt.attempt, runnableId: view.runnableId, status: view.status, outcome: observed.outcome, parentRunId: view.parentRunId }))
+            });
+            view.metadata[RUN_NATIVE_COMPLETION_METADATA_KEY] = JsonValueFromReaderSchema.parse(outbox);
+            await records.save(view);
+        }
+        for (const completion of outbox.filter(occurrence => !occurrence.delivered)) {
+            const emitter = await this.createRun({ runId, type: record.runnableType, name: record.name ?? record.runnableId,
+                executionGeneration: completion.generation, executionAttempt: completion.attempt });
+            await emitter.event(RUN_COMPLETED_EVENT, JsonObjectSchema.parse(completion.payload), { eventId: completion.eventId, timestamp: completion.timestamp });
+            await emitter.event('status', { status: completion.payload.status }, { eventId: `${completion.eventId}:status`, timestamp: completion.timestamp });
+            await this.runtime.hooks('runnable.run').emit('completed', completion.payload);
+            // Another native generation may have started while delivery waited.
+            // Only acknowledge this occurrence on that latest admitted snapshot.
+            const latest = await this.storedRecord(runId);
+            if (!latest)
+                throw new CapabilityError('Native execution record is unavailable.', 'NOT_FOUND', { reason: 'runnable-run-not-found' });
+            assertRunWrite(latest, captureRunAdmission(this.runtime), await this.scopeIdentity());
+            const pending = RunnableNativeCompletionOutboxSchema.parse(latest.metadata[RUN_NATIVE_COMPLETION_METADATA_KEY] ?? []);
+            const delivered = pending.find(occurrence => occurrence.receiptId === completion.receiptId);
+            if (!delivered || canonical({ ...delivered, delivered: false }) !== canonical({ ...completion, delivered: false })) {
+                throw new CapabilityError('Native completion occurrence changed during delivery.', 'CONFLICT', { reason: 'runnable-native-completion-changed' });
+            }
+            delivered.delivered = true;
+            latest.metadata[RUN_NATIVE_COMPLETION_METADATA_KEY] = JsonValueFromReaderSchema.parse(pending);
+            await records.save(latest);
+        }
+        return observed;
+    }
+    async followNativeCompletion(record) {
+        const execution = RunnableNativeExecutionStateSchema.parse(record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY]);
+        const observerId = `${record.id}:${execution.generation}`;
+        if (this.nativeObservers.has(observerId))
+            return;
+        const owner = await this.nativeObserver(record);
+        if (!owner.subscribeObservation)
+            throw new CapabilityError('The native execution owner cannot subscribe to its durable receipt.', 'UNAVAILABLE', { reason: 'runnable-native-subscription-unavailable' });
+        const subscribe = owner.subscribeObservation.bind(owner);
+        const invocation = this.runtime.captureInvocation();
+        const ready = Promise.withResolvers();
+        const work = this.runtime.lifecycle.own(() => invocation.run(async () => {
+            let changed = Promise.withResolvers();
+            const stop = await subscribe(record, () => changed.resolve());
+            try {
+                ready.resolve();
+                for (;;) {
+                    const notified = changed.promise;
+                    if ((await this.reconcileNativeExecution(record.id)).terminal)
+                        return;
+                    const signal = this.runtime.lifecycle.signal;
+                    await new Promise(resolve => {
+                        const cancelled = () => resolve();
+                        if (signal.aborted)
+                            resolve();
+                        else
+                            signal.addEventListener('abort', cancelled, { once: true });
+                        void notified.then(() => {
+                            signal.removeEventListener('abort', cancelled);
+                            resolve();
+                        });
+                    });
+                    if (signal.aborted)
+                        return;
+                    changed = Promise.withResolvers();
+                }
+            }
+            finally {
+                await stop();
+            }
+        }));
+        this.nativeObservers.set(observerId, work);
+        void work.catch(error => {
+            ready.reject(error);
+            const caught = CaughtFailureSchema.parse(error);
+            if (!(this.runtime.lifecycle.signal.aborted && isCapabilityError(caught) && caught.code === 'CANCELLED')) {
+                this.runtime.diagnostics.error('Native Runnable completion observation failed', { scope: 'runnable:native-completion', plugin: 'runnable', error: caught });
+            }
+        }).finally(() => this.nativeObservers.delete(observerId));
+        await ready.promise;
+    }
+    nativeView(record, observation) {
+        const view = RunRecordSchema.parse(record);
+        view.status = observation.status;
+        if (observation.progress !== undefined)
+            view.progress = observation.progress;
+        if (observation.outcome !== undefined)
+            view.outcome = observation.outcome;
+        else
+            delete view.outcome;
+        if (observation.endedAt !== undefined)
+            view.endedAt = observation.endedAt;
+        else
+            delete view.endedAt;
+        return view;
+    }
+    /** Display-only fallback for older rows, from the declared owner rather than an inferred ID. */
+    namedRun(run) {
+        if (run.name)
+            return run;
+        const declared = this.runtime.query('runnable/runnable').withId(run.runnableId).descriptors()[0];
+        return declared ? { ...run, name: RunnableDescriptorSchema.parse(declared).name } : run;
+    }
+    async trackingView(input) {
+        const record = this.namedRun(RunnableTrackedRunSchema.parse(JsonValueFromReaderSchema.parse(input)));
+        const binding = runContextBindings(this.runtime).find(binding => binding.runnables.includes(record.runnableId));
+        if (binding) {
+            const value = JsonValueFromReaderSchema.parse(record);
+            const referenceId = runContextReferenceId(value, binding);
+            const reference = referenceId ? await this.storedRecord(referenceId) : null;
+            record.context = bindRunContext(value, binding, reference ? JsonValueFromReaderSchema.parse(reference) : undefined);
+        }
+        if (record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] === undefined)
+            return record;
+        const strict = RunRecordSchema.parse(record);
+        const observation = await this.observeNative(strict);
+        return observation ? RunnableTrackedRunSchema.parse({ ...this.nativeView(strict, observation), context: record.context }) : record;
+    }
+    /**
+     * List replacement. Direct children are the matched rows that name a parent
+     * in this same read. Persisted telemetry stays on `snapshot`.
+     */
+    async catalogSnapshots(query) {
+        const matched = await this.runs(query);
+        const children = new Map();
+        for (const run of matched) {
+            if (!run.parentRunId)
+                continue;
+            const listed = children.get(run.parentRunId);
+            if (listed)
+                listed.push(run);
+            else
+                children.set(run.parentRunId, [run]);
+        }
+        return matched.map(run => ({
+            run,
+            metrics: [],
+            logs: [],
+            artifacts: [],
+            children: children.get(run.id) ?? []
+        }));
+    }
+    /** Recorded list state is a distinct projection; full evidence and native observation stay on detail reads. */
+    async watchCatalog(input, listener, failureOrOptions) {
+        return this.runtime.runInvocation(async () => {
+            const query = RunnableReadQuerySchema.strict().parse(input);
+            const options = typeof failureOrOptions === 'function' ? { onError: failureOrOptions } : failureOrOptions ?? {};
+            return this.openReadWatch(query, listener, async () => {
+                const host = await this.stateHost();
+                const source = host.tracking ?? host.reads;
+                if (!source?.list)
+                    throw new CapabilityError('Runnable host does not provide catalog reads.', 'UNAVAILABLE', {
+                        reason: 'runnable-catalog-unavailable'
+                    });
+                const rows = source.listCatalog
+                    ? await source.listCatalog(query)
+                    : await Promise.all((await source.list(query)).map(async (run) => {
+                        const binding = runContextBindings(this.runtime).find(binding => binding.runnables.includes(run.runnableId));
+                        const value = JsonValueFromReaderSchema.parse(run);
+                        const referenceId = binding ? runContextReferenceId(value, binding) : undefined;
+                        const reference = referenceId ? await this.storedRecord(referenceId) : null;
+                        return RunnableCatalogRunSchema.parse({ ...run, ...(binding ? { context: bindRunContext(value, binding, reference ? JsonValueFromReaderSchema.parse(reference) : undefined) } : {}) });
+                    }));
+                const runs = rows.map(run => this.namedRun(run));
+                const children = new Map();
+                for (const run of runs) {
+                    if (!run.parentRunId)
+                        continue;
+                    const group = children.get(run.parentRunId) ?? [];
+                    group.push(run);
+                    children.set(run.parentRunId, group);
+                }
+                return runs.map(run => ({ run, children: children.get(run.id) ?? [] }));
+            }, options, 'catalog');
+        });
+    }
+    /** Append producer or caller evidence through this record’s admitted writer. */
+    async appendEvent(runId, type, payload) {
+        const event = runEventEnvelopeSchema.safeParse({ ...payload, type });
+        if (!event.success || type.startsWith('runnable.')) {
+            throw new CapabilityError('Caller evidence must be an extension event outside the reserved Runnable protocol.', 'INVALID_INPUT', { reason: 'runnable-caller-event-invalid' });
+        }
+        const record = await this.record(runId);
+        if (!record)
+            throw new CapabilityError('Run not found.', 'NOT_FOUND', { reason: 'runnable-run-not-found' });
+        assertRunWrite(record, captureRunAdmission(this.runtime), await this.scopeIdentity());
+        if (record.endedAt !== undefined || ['completed', 'stopped', 'error'].includes(record.status)) {
+            throw new CapabilityError('This execution has ended and cannot receive new events.', 'CONFLICT', { reason: 'runnable-execution-ended' });
+        }
+        const handle = await this.attachHandle(runId);
+        await handle.event(type, JsonObjectSchema.parse(payload));
+    }
+    /** Read the full owner snapshot, including persisted telemetry and direct children. */
+    async snapshot(runId) {
+        const host = await this.stateHost();
+        const run = host.tracking ? await host.tracking.get(runId) : await this.storedRecord(runId);
+        if (!run)
+            throw new CapabilityError('Run not found.', 'NOT_FOUND', { reason: 'runnable-run-not-found' });
+        const telemetry = host.telemetry;
+        if (!telemetry)
+            throw new CapabilityError('Runnable host does not provide persisted telemetry reads.', 'UNAVAILABLE', { reason: 'runnable-telemetry-reads-unavailable' });
+        const evidence = await telemetry.read(runId);
+        const declarations = this.runtime.query('runnable/telemetry').enabled().descriptors().map(descriptor => RunnableTelemetryDescriptorSchema.parse(descriptor));
+        return RunnableSnapshotSchema.parse(JsonValueFromReaderSchema.parse({ run: await this.trackingView(run), ...evidence,
+            children: await this.runs({ parentRunId: runId }), observation: latestRunObservation(evidence.logs, declarations) }));
+    }
+    async watch(input, listener, failureOrOptions, nativeOptions) {
+        return this.runtime.runInvocation(() => this.openWatch(input, listener, failureOrOptions, nativeOptions));
+    }
+    async openWatch(input, listener, failureOrOptions, nativeOptions) {
+        const query = RunnableReadQuerySchema.strict().parse(input);
+        const options = typeof failureOrOptions === 'function'
+            ? { ...nativeOptions, onError: failureOrOptions }
+            : { ...nativeOptions, ...failureOrOptions };
+        const projection = RunnableWatchProjectionSchema.optional().parse(options.projection) ?? 'snapshot';
+        let nativeJobs;
+        const dependencies = (snapshots) => {
+            // An unlisted record can enter a native status query without a persisted write.
+            if (query.status !== undefined || snapshots.length === 0)
+                return undefined;
+            const jobs = new Set();
+            for (const snapshot of snapshots) {
+                for (const run of [snapshot.run, ...snapshot.children]) {
+                    const native = run.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY];
+                    const admitted = native === undefined ? undefined : RunnableNativeExecutionStateSchema.safeParse(native);
+                    const reference = admitted === undefined ? run.ref : admitted.success ? admitted.data.reference : undefined;
+                    if (reference?.jobId === undefined)
+                        return undefined;
+                    jobs.add(reference.jobId);
+                }
+            }
+            return jobs;
+        };
+        return this.openReadWatch(query, listener, async () => {
+            try {
+                const snapshots = projection === 'records' ? await this.catalogSnapshots(query)
+                    : await Promise.all((await this.runs(query)).map(run => this.snapshot(run.id)));
+                nativeJobs = dependencies(snapshots);
+                return snapshots;
+            }
+            catch (cause) {
+                nativeJobs = undefined;
+                throw cause;
+            }
+        }, options, 'native', jobId => nativeJobs === undefined || nativeJobs.has(jobId));
+    }
+    async openReadWatch(query, listener, read, options, purpose = 'native', nativeJobRelevant) {
+        const host = await this.stateHost();
+        const source = host.tracking ?? host.reads;
+        const subscription = purpose === 'catalog' ? source?.subscribeCatalog ?? source?.subscribe : source?.subscribe;
+        const subscribe = subscription?.bind(source);
+        if (!subscribe)
+            throw new CapabilityError('Runnable host does not provide live tracking subscriptions.', 'UNAVAILABLE', {
+                reason: 'runnable-watch-unavailable'
+            });
+        const inherited = await getRunnableInvocation(this.runtime);
+        const signals = [this.runtime.lifecycle.signal, this.runtime.invocationSignal, inherited?.signal, options.signal]
+            .filter((value) => value !== undefined);
+        const signal = AbortSignal.any(signals);
+        return watchRunnableSnapshots(this.runtime, {
+            read,
+            subscribe: changed => subscribe(query, reference => {
+                if (!nativeJobRelevant || reference === undefined) {
+                    changed();
+                    return;
+                }
+                const native = RunExecutionReferenceSchema.safeParse(reference);
+                if (!native.success || native.data.jobId === undefined || nativeJobRelevant(native.data.jobId))
+                    changed();
+            }),
+            failed: async (cause) => {
+                if (options.onError)
+                    await options.onError(this.failureFacts(cause));
+                else
+                    this.runtime.diagnostics.error('Runnable watch failed', { scope: 'runnable:watch', plugin: 'runnable', error: cause });
+            }
+        }, listener, signal);
+    }
+    /** Resolve panels from explicit producer declarations, independent of feature names. */
+    async visualizations(query) {
+        let selection;
+        if ('runId' in query) {
+            const [record] = await this.runs({ id: query.runId });
+            if (!record)
+                throw new CapabilityError('Run not found.', 'NOT_FOUND', { reason: 'runnable-run-not-found' });
+            selection = {
+                type: record.runnableType,
+                runnableId: record.runnableId,
+                reportedTelemetry: RunnableDescriptorSchema.shape.telemetry.parse(record.metadata.telemetry) ?? []
+            };
+        }
+        else {
+            selection = query;
+        }
+        const type = this.runtime.hasKind('runnable/type')
+            ? await this.runtime.query('runnable/type').withId(selection.type).enabled().firstDescriptorAsync()
+            : null;
+        const runnable = selection.runnableId && this.runtime.hasKind('runnable/runnable')
+            ? await this.runtime.query('runnable/runnable').withId(selection.runnableId).enabled().firstDescriptorAsync()
+            : null;
+        const telemetry = new Set([
+            ...(type ? RunnableTypeDescriptorSchema.parse(type).telemetry ?? [] : []),
+            ...(runnable ? RunnableDescriptorSchema.parse(runnable).telemetry ?? [] : []),
+            ...(selection.reportedTelemetry ?? [])
+        ]);
+        if (telemetry.size > 0) {
+            const declared = this.runtime.hasKind('runnable/telemetry')
+                ? await this.runtime.query('runnable/telemetry').enabled().filter(descriptor => telemetry.has(descriptor.id)).descriptorsAsync()
+                : [];
+            const available = new Set(declared.map(descriptor => RunnableTelemetryDescriptorSchema.parse(descriptor).id));
+            const missing = [...telemetry].filter(id => !available.has(id));
+            if (missing.length > 0) {
+                throw new CapabilityError('Run telemetry declarations are unavailable.', 'UNAVAILABLE', {
+                    reason: 'runnable-telemetry-unavailable', details: { telemetry: missing }
+                });
+            }
+        }
+        if (!this.runtime.hasKind('runnable/visualization'))
+            return [];
+        return (await this.runtime.query('runnable/visualization').enabled().descriptorsAsync())
+            .map(descriptor => RunnableVisualizationDescriptorSchema.parse(descriptor))
+            .filter(descriptor => descriptor.telemetryId === '*' || telemetry.has(descriptor.telemetryId));
+    }
+    async records() {
+        const records = (await this.stateHost()).records;
+        if (!records) {
+            throw new CapabilityError('Runnable host does not provide durable run records.', 'UNAVAILABLE', { reason: 'runnable-records-unavailable' });
+        }
+        return records;
+    }
+    failureFacts(error) {
+        const caught = CaughtFailureSchema.parse(error);
+        const facts = valueFreeFailure(caught);
+        const failure = { name: facts.name, code: facts.code ?? 'ERROR', message: facts.name };
+        if (facts.reason !== undefined)
+            failure.reason = facts.reason;
+        if (isCapabilityError(caught)) {
+            failure.message = caught.message;
+            failure.retryable = caught.retryable;
+            if (caught.recoveryHint !== undefined)
+                failure.recoveryHint = caught.recoveryHint;
+            if (caught.details !== undefined)
+                failure.details = JsonValueSchema.parse(JSON.parse(JSON.stringify(caught.details)));
+        }
+        return failure;
+    }
+    executeRecorded(descriptor, input, options, rankReason, implementation, nativeExecution, preparedRecord) {
+        return this.runtime.runInvocation(() => this.executeRecordedInInvocation(descriptor, input, options, rankReason, implementation, nativeExecution, preparedRecord));
+    }
+    async executeRecordedInInvocation(descriptor, input, options, rankReason, implementation, nativeExecution, preparedRecord) {
+        const inherited = await getRunnableInvocation(this.runtime);
+        const signals = [this.runtime.invocationSignal, inherited?.signal, options?.signal].filter((value) => value !== undefined);
+        const signal = signals.length === 0 ? undefined : AbortSignal.any(signals);
+        signal?.throwIfAborted();
+        const submittedInput = JsonValueSchema.parse(input);
+        const submittedObject = JsonObjectSchema.safeParse(submittedInput);
+        let config = submittedObject.success ? submittedObject.data : { input: submittedInput };
+        const parentRunId = options?.parentRunId ?? inherited?.runId;
+        const completionHooks = this.runtime.hooks('runnable.run');
+        const records = await this.records();
+        const scope = await this.scopeIdentity();
+        const received = nativeExecution === undefined ? undefined : RunnableNativeExecutionSchema.parse(nativeExecution);
+        const receivedRunId = preparedRecord?.id ?? (received === undefined ? undefined : `native-${await hashHex(this.runtime, 'sha256', canonical({ scope, execution: received.id }))}`);
+        const previous = preparedRecord ?? (receivedRunId === undefined ? null : await this.storedRecord(receivedRunId));
+        if (preparedRecord && !previous)
+            throw new CapabilityError('The prepared native record is unavailable.', 'NOT_FOUND', { reason: 'runnable-run-not-found' });
+        const previousExecution = previous?.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] === undefined ? undefined : RunnableNativeExecutionStateSchema.parse(previous.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY]);
+        const previousAdmission = previous ? await readInputAdmission(this.runtime, previous) : null;
+        if (previous && received) {
+            const sameReference = previous.ref !== undefined && previous.ref.jobId === received.reference.jobId && Object.entries(previous.ref).every(([key, value]) => received.reference[key] === value);
+            if (!previousAdmission || previous.runnableId !== descriptor.id || !sameReference ||
+                canonical(previous.metadata['runnable.submittedInput']) !== canonical(submittedInput) ||
+                (!previousExecution && !preparedRecord) ||
+                (previousExecution && (canonical(previousExecution.reference) !== canonical(received.reference) || previousExecution.id !== received.id ||
+                    canonical(previousExecution.owner) !== canonical(received.owner) || canonical(previousExecution.result) !== canonical(received.result))) ||
+                (options?.configUnit !== undefined && previous.metadata.configUnit !== options.configUnit)) {
+                throw new CapabilityError('Native execution differs from its recorded input admission.', 'PERMISSION_DENIED', { reason: 'runnable-native-execution-mismatch' });
+            }
+            const last = previousExecution?.attempts.at(-1);
+            if (last && (received.generation < last.generation || (received.generation === last.generation && received.attempt < last.attempt))) {
+                throw new CapabilityError('Native execution attempt has already been admitted.', 'CONFLICT', { reason: 'runnable-native-execution-attempt-stale' });
+            }
+        }
+        const identity = options?.memoIdentity ? MemoIdentitySchema.parse(options.memoIdentity) : undefined;
+        let configUnit = RunnableExecutionInputSchema.shape.configUnit.parse(options?.configUnit ?? inherited?.configUnit);
+        const executorQuery = this.runtime.query('runnable/executor')
+            .enabled().filter((executor) => executor.runnableType === descriptor.type);
+        const selectedExecutor = descriptor.execution === 'native' ? null : await executorQuery.select();
+        const preparationOwner = selectedExecutor
+            ? { kind: 'runnable/executor', id: selectedExecutor.descriptor.id }
+            : { kind: 'runnable/runnable', id: descriptor.id };
+        let preparationContext;
+        let preparationFailure;
+        try {
+            const prepared = previous ? {
+                config: previous.config, context: previousAdmission?.context,
+                configUnit: RunnableExecutionInputSchema.shape.configUnit.parse(previous.metadata.configUnit)
+            } : selectedExecutor
+                ? await selectedExecutor.impl.prepareInput?.({ config, settings: descriptor.settings, configUnit }, { signal, configUnit })
+                : await implementation.prepareInput?.(submittedInput, { signal, configUnit });
+            if (prepared !== undefined) {
+                const admitted = RunnablePreparedInputSchema.parse(prepared);
+                config = admitted.config;
+                preparationContext = admitted.context;
+                configUnit = admitted.configUnit ?? configUnit;
+            }
+            signal?.throwIfAborted();
+        }
+        catch (cause) {
+            preparationFailure = { cause };
+        }
+        const memoUnits = options?.memoUnits === undefined ? undefined : [...new Set([...options.memoUnits, ...(configUnit === undefined ? [] : [configUnit])])];
+        if (identity && identity.scope !== scope) {
+            throw new CapabilityError('Memo identity belongs to another invocation scope.', 'INVALID_INPUT', { reason: 'runnable-memo-scope-mismatch' });
+        }
+        let runtimeRevision;
+        let memoDiagnostic;
+        if (descriptor.memo) {
+            if (memoUnits === undefined) {
+                memoDiagnostic = 'configuration-units-undeclared';
+            }
+            else {
+                try {
+                    runtimeRevision = await getRuntimeMemoRevision(this.runtime, { units: memoUnits });
+                }
+                catch (error) {
+                    const failure = CaughtFailureSchema.parse(error);
+                    if (isCapabilityError(failure) && ['runtime-memo-revision-unavailable', 'runtime-memo-revision-unstable'].includes(failure.reason ?? '')) {
+                        memoDiagnostic = failure.reason;
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
+        }
+        const inputDigest = previous?.inputDigest ?? await hashHex(this.runtime, 'sha256', canonical({ input: config, configUnit: configUnit ?? null, identity: identity ?? null, runtimeRevision: runtimeRevision ?? null }));
+        let reused;
+        if (!preparationFailure && descriptor.memo && runtimeRevision) {
+            reused = (await records.list({ scope, runnable: descriptor.id, inputDigest, status: 'done' }))
+                .map((record) => RunRecordSchema.parse(record))
+                .find((record) => record.outcome?.status === 'done' && record.metadata.memoEligible === true);
+        }
+        const emitter = await this.createRun({ runId: receivedRunId, type: descriptor.type, name: descriptor.name ?? descriptor.id,
+            executionGeneration: received?.generation, executionAttempt: received?.attempt });
+        const record = previous ? RunRecordSchema.parse(previous) : RunRecordSchema.parse({
+            id: emitter.runId, scope, status: 'running', runnableType: descriptor.type, runnableId: descriptor.id, name: descriptor.name ?? descriptor.id, config,
+            progress: 0, startedAt: Date.now(), metadata: { ...mergeRunEventMetadata({}, options?.metadata ?? {}), [RUN_ADMISSION_METADATA_KEY]: captureRunAdmission(this.runtime) }, inputDigest, rankReason
+        });
+        record.metadata['runnable.submittedInput'] = submittedInput;
+        if (!preparationFailure && !previous) {
+            record.metadata[RUN_INPUT_ADMISSION_METADATA_KEY] = {
+                version: 1, runId: record.id, runnableId: descriptor.id, inputDigest,
+                configDigest: await hashHex(this.runtime, 'sha256', canonical(config)), owner: preparationOwner,
+                ...(preparationContext === undefined ? {} : { context: preparationContext }),
+                ...(inherited?.runId === undefined ? {} : { enclosingRunId: inherited.runId })
+            };
+        }
+        if (received) {
+            const previousAttempts = previousExecution?.attempts ?? [];
+            const reentry = previousAttempts.some(attempt => attempt.generation === received.generation && attempt.attempt === received.attempt);
+            record.ref = { ...record.ref, ...received.reference };
+            record.status = 'running';
+            delete record.outcome;
+            delete record.endedAt;
+            record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] = JsonObjectSchema.parse({
+                id: received.id, owner: received.owner, generation: received.generation, reference: received.reference, result: previousExecution?.result ?? received.result,
+                attempts: reentry ? previousAttempts : [...previousAttempts, { generation: received.generation, attempt: received.attempt, maxAttempts: received.maxAttempts, startedAt: Date.now() }]
+            });
+            const execution = RunnableNativeExecutionStateSchema.parse(record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY]);
+            execution.observer = previousExecution?.observer ?? (await this.nativeObserver(record)).owner;
+            record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] = JsonObjectSchema.parse(execution);
+        }
+        if (parentRunId && !previous)
+            record.parentRunId = parentRunId;
+        if (options?.about !== undefined)
+            record.metadata.about = JsonValueSchema.parse(options.about);
+        if (configUnit !== undefined)
+            record.metadata.configUnit = configUnit;
+        if (descriptor.memo)
+            record.metadata.memoEligible = false;
+        if (memoDiagnostic)
+            record.metadata.memo = memoDiagnostic;
+        if (reused) {
+            record.metadata.reusedRunId = reused.id;
+            if (reused.ref)
+                record.ref = reused.ref;
+            if (reused.approval)
+                record.approval = reused.approval;
+        }
+        const recording = recordRunHandle(emitter, record, records, () => this.storedRecord(record.id));
+        const handle = recording.handle;
+        await recording.save();
+        if (received)
+            await this.followNativeCompletion(record);
+        let outcome;
+        let executionStatus = 'completed';
+        let producerFailure;
+        try {
+            await handle.start(config);
+            if (preparationFailure)
+                throw preparationFailure.cause;
+            if (memoDiagnostic)
+                await handle.log('info', 'Authoritative memo identity unavailable; executing without cached reuse.', { reason: memoDiagnostic });
+            if (reused?.outcome) {
+                outcome = OutcomeSchema.parse(reused.outcome);
+            }
+            else {
+                if (selectedExecutor) {
+                    const executor = selectedExecutor.impl;
+                    const result = await withRunnableInvocation(this.runtime, { runId: handle.runId, signal, configUnit }, () => executor.execute({ runId: handle.runId, config, settings: descriptor.settings, configUnit }, handle, { signal }));
+                    const task = OutcomeSchema.safeParse(result);
+                    if (task.success) {
+                        outcome = task.data;
+                    }
+                    else {
+                        const request = RunnableSpawnRequestSchema.parse(result);
+                        const supervisor = await this.supervisor();
+                        if (!supervisor.run) {
+                            throw new CapabilityError('Runnable supervisor cannot await process completion.', 'UNAVAILABLE', { reason: 'runnable-completion-unavailable' });
+                        }
+                        outcome = OutcomeSchema.parse(await supervisor.run(handle.runId, request, undefined, { signal }));
+                    }
+                }
+                else {
+                    const result = await withRunnableInvocation(this.runtime, { runId: handle.runId, signal, configUnit }, () => implementation.execute(config, handle, { signal, configUnit }));
+                    if (descriptor.nativeResult === 'void') {
+                        if (result !== undefined)
+                            throw new CapabilityError('Void runnable returned a value.', 'INVALID_INPUT', { reason: 'runnable-native-result-invalid' });
+                        outcome = done(null);
+                    }
+                    else if (descriptor.nativeResult === 'outcome') {
+                        outcome = OutcomeSchema.parse(result);
+                    }
+                    else {
+                        outcome = done(JsonValueSchema.parse(result));
+                    }
+                }
+            }
+            signal?.throwIfAborted();
+            outcome = OutcomeSchema.parse(outcome);
+            if (outcome.status === 'skipped' && outcome.cause.kind === 'cancelled')
+                executionStatus = 'stopped';
+        }
+        catch (error) {
+            producerFailure = { cause: error };
+            const failure = this.failureFacts(error);
+            if (signal?.aborted || failure.code === 'CANCELLED') {
+                executionStatus = 'stopped';
+                outcome = {
+                    status: 'skipped', reason: 'Runnable invocation cancelled.',
+                    cause: { kind: 'cancelled', provenance: JsonValueSchema.parse(failure) }
+                };
+            }
+            else {
+                executionStatus = 'error';
+                outcome = { status: 'not-done', reason: 'Runnable execution failed.', failure };
+            }
+        }
+        let revisionRefusal;
+        if (descriptor.memo && runtimeRevision && outcome.status === 'done') {
+            try {
+                const current = await getRuntimeMemoRevision(this.runtime, { units: memoUnits });
+                record.metadata.memoEligible = canonical(current) === canonical(runtimeRevision);
+                if (!record.metadata.memoEligible)
+                    record.metadata.memo = 'revision-changed-during-execution';
+            }
+            catch (error) {
+                const failure = CaughtFailureSchema.parse(error);
+                if (isCapabilityError(failure) && ['runtime-memo-revision-unavailable', 'runtime-memo-revision-unstable'].includes(failure.reason ?? '')) {
+                    record.metadata.memo = failure.reason ?? 'revision-unavailable-after-execution';
+                }
+                else {
+                    revisionRefusal = { error };
+                }
+            }
+        }
+        if (!received) {
+            const attached = await recording.handoff();
+            if (attached) {
+                await this.followNativeCompletion(attached);
+                const execution = RunnableNativeExecutionStateSchema.parse(attached.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY]);
+                await this.nativeObservers.get(`${record.id}:${execution.generation}`);
+                const completed = await this.storedRecord(record.id);
+                if (!completed?.outcome)
+                    throw new CapabilityError('The native execution has no completed receipt.', 'UNAVAILABLE', { reason: 'runnable-native-outcome-unavailable' });
+                if (descriptor.memo) {
+                    completed.metadata.memoEligible = record.metadata.memoEligible ?? false;
+                    if (record.metadata.memo !== undefined)
+                        completed.metadata.memo = record.metadata.memo;
+                    await records.save(completed);
+                }
+                if (revisionRefusal)
+                    throw revisionRefusal.error;
+                if (producerFailure && completed.status === 'completed')
+                    throw producerFailure.cause;
+                return { runId: record.id, outcome: OutcomeSchema.parse(completed.outcome) };
+            }
+        }
+        record.outcome = outcome;
+        record.endedAt = Date.now();
+        record.status = executionStatus;
+        record.progress = 1;
+        if (received) {
+            const execution = RunnableNativeExecutionStateSchema.parse(record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY]);
+            const attempt = execution.attempts.at(-1);
+            attempt.endedAt = record.endedAt;
+            attempt.outcome = outcome;
+            record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] = JsonObjectSchema.parse(execution);
+            delete record.outcome;
+            delete record.endedAt;
+            record.status = 'running';
+            await recording.save();
+            return { runId: record.id, outcome: outcome };
+        }
+        await recording.save();
+        const completed = RunCompletedPayloadSchema.parse({
+            runId: record.id,
+            runnableId: descriptor.id,
+            status: record.status,
+            outcome,
+            parentRunId: record.parentRunId
+        });
+        await handle.event(RUN_COMPLETED_EVENT, completed);
+        if (executionStatus === 'completed')
+            await handle.done();
+        else
+            await handle.status(executionStatus);
+        await completionHooks.emit('completed', completed);
+        if (revisionRefusal)
+            throw revisionRefusal.error;
+        return { runId: record.id, outcome: outcome };
+    }
+    async hydrateState() {
+        const host = await this.stateHost();
+        await host.hydrateOnce();
+    }
+    async getState() {
+        return (await this.stateHost()).state;
+    }
+    async executionController(record) {
+        const native = record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] === undefined
+            ? undefined : RunnableNativeExecutionStateSchema.parse(record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY]);
+        const owner = native?.observer ?? (await readInputAdmission(this.runtime, record))?.owner;
+        return owner ? this.resolveNativeOwner(owner) : null;
+    }
+    async controlRecord(runId) {
+        if (!this.runtime.hasContext(RUNNABLE_STATE_HOST_CONTEXT_ID))
+            return null;
+        const host = await this.stateHost();
+        if (!host.reads && !host.records)
+            return null;
+        return this.storedRecord(runId);
+    }
+    async controls(runId) {
+        const record = await this.controlRecord(runId);
+        if (record) {
+            const owner = await this.executionController(record);
+            if (owner?.controls)
+                return RunnableControlActionSchema.array().parse(await owner.controls(record));
+            if (record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] !== undefined)
+                return [];
+        }
+        return await this.isSupervised(runId) ? ['stop', 'pause', 'resume'] : [];
+    }
+    async control(input) {
+        const request = RunnableControlInputSchema.parse(input);
+        const record = await this.controlRecord(request.runId);
+        if (!record)
+            return (await this.supervisor()).control(request.runId, request.action);
+        assertRunWrite(record, captureRunAdmission(this.runtime), await this.scopeIdentity());
+        const owner = await this.executionController(record);
+        const actions = owner?.controls ? RunnableControlActionSchema.array().parse(await owner.controls(record)) : [];
+        if (owner?.control && actions.includes(request.action)) {
+            const { runId: _runId, ...control } = request;
+            return owner.control(record, control);
+        }
+        if (record.metadata[RUN_NATIVE_EXECUTION_METADATA_KEY] === undefined && await this.isSupervised(request.runId)) {
+            return (await this.supervisor()).control(request.runId, request.action);
+        }
+        throw new CapabilityError('The admitted owner does not support this Runnable control.', 'UNAVAILABLE', {
+            reason: 'runnable-control-unavailable', details: { action: request.action }
+        });
+    }
+    async isSupervised(runId) {
+        return (await this.supervisor()).isSupervised(runId);
+    }
+    async status(runId) {
+        return (await this.supervisor()).status(runId);
+    }
+    /**
+     * The supervisor's loader is consumer-scoped, so on any other declared
+     * hardware resolution fails instead of this client inventing an idle or
+     * unspawned answer.
+     */
+    supervisor() {
+        return this.runtime
+            .query('runnable/supervisor')
+            .withId(RUNNABLE_SUPERVISOR_ID).resolve();
+    }
+    stateHost() {
+        return this.runtime.context(RUNNABLE_STATE_HOST_CONTEXT_ID);
+    }
+}
+/**
+ * The `runnable` runtime client of the runtime the caller was handed. The
+ * runtime is required: there is no ambient fallback to a process-global
+ * runtime (RC02, D39), and no on-demand plugin registration. A missing
+ * client kind or client is refused typed.
+ */
+export async function getVibesRunnableClient(runtime) {
+    if (!runtime.hasKind('runtime/client')) {
+        throw new CapabilityError("Runtime kind 'runtime/client' is not registered; compose the runtime-client and runnable plugins before resolving runnable.", 'UNAVAILABLE', { reason: 'runnable-client-unavailable', retryable: false });
+    }
+    let client;
+    try {
+        client = await runtime.query('runtime/client').withId('runnable').resolve();
+    }
+    catch (error) {
+        if (error instanceof Error && CapabilityError.isAbsenceOf(error, 'runtime/client', 'runnable')) {
+            throw new CapabilityError('No runtime client registered with id "runnable". Compose the runnable plugin before use.', 'UNAVAILABLE', {
+                reason: 'runnable-client-unavailable',
+                retryable: false
+            });
+        }
+        throw error;
+    }
+    if (!client) {
+        throw new CapabilityError('No runtime client registered with id "runnable". Compose the runnable plugin before use.', 'UNAVAILABLE', {
+            reason: 'runnable-client-unavailable',
+            retryable: false
+        });
+    }
+    return client;
+}
+export default RunnableClient;
+//# sourceMappingURL=client.js.map