@fungi.computer/shiitake 0.0.0-stage → 0.0.1

package/dist/internal/extension-runtime.js

@@ -0,0 +1,1004 @@
+import { AttentionItemSchema, maximumExtensionAttention, } from "../session-attention.js";
+import { encodeDocument } from "./document-codec.js";
+import * as Cause from "effect/Cause";
+import * as Result from "effect/Result";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import { ShiitakeError } from "../errors.js";
+import { AdmissionError, ExtensionCommandError, ExtensionRead, ExtensionStateError, ExtensionStop, ExtensionTx, } from "../extensions.js";
+import { decodeClientSessionId } from "./client-boundary.js";
+import { AsyncExtensionTransactionError, invokeExtensionHook, invokeSyncHandler, } from "./extension-hook.js";
+import { setSessionAttention, clearSessionAttention, projectSessionAttention, readAttentionSessionPage, replaceAttentionGrants, hasStoredSession, hasPendingSessionSteer, hasSuccessfulToolResult, advanceCursor, declareSessionDocument, readSessionDocument, writeSessionDocument, deleteAllRecords, deleteRecord, deleteTimer, readAllRecords, readCursor, readDueTimers, readRecord, readRecordPage, readStateLedger, readStatus, readTimer, readTimerWake, writeRecord, writeStateLedger, writeStatus, writeTimer, } from "./woodstock/index.js";
+import { JsonValueSchema } from "./json-value.js";
+import { publishOwnerObservation } from "./observation-kernel.js";
+/** The settled consumer name core itself uses for mail and control repair. */
+export const coreConsumer = "core";
+const maximumKeyLength = 256;
+const maximumRecordBytes = 1024 * 1024;
+const maximumReasonLength = 512;
+const maximumPage = 64;
+const encoder = new TextEncoder();
+const decodePromptSections = Schema.decodeUnknownResult(Schema.Array(Schema.Struct({
+    name: Schema.String.pipe(Schema.check(Schema.isPattern(/^[a-z][A-Za-z0-9_-]{0,63}$/u))),
+    text: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.makeFilter((text) => encoder.encode(text).byteLength <= 8192))),
+})).pipe(Schema.check(Schema.isMaxLength(16))));
+/** A missing or failed pure migration cannot safely decode the new state. */
+class IncompatibleStateMigrationError extends Error {
+}
+function boundReason(reason) {
+    return reason.length <= maximumReasonLength
+        ? reason
+        : `${reason.slice(0, maximumReasonLength - 1)}…`;
+}
+const decodeStoredJson = Schema.decodeSync(Schema.fromJsonString(JsonValueSchema));
+function failureText(value) {
+    return value instanceof ExtensionStop
+        ? value.reason
+        : `${value._tag}: ${value.message}`;
+}
+function isExtensionFailure(value) {
+    return (value instanceof ExtensionStop ||
+        value instanceof ExtensionStateError ||
+        value instanceof AdmissionError ||
+        value instanceof ExtensionCommandError);
+}
+/** A bounded, caller-safe reason for one stopping cause. */
+function stopReason(hook, cause) {
+    const failure = Cause.findErrorOption(cause);
+    if (Option.isSome(failure)) {
+        const value = failure.value;
+        if (value instanceof ExtensionStop)
+            return boundReason(value.reason);
+        return boundReason(isExtensionFailure(value)
+            ? `${hook}: ${failureText(value)}`
+            : `${hook} failed`);
+    }
+    const defect = Result.getSuccess(Cause.findDefect(cause));
+    if (Option.isSome(defect)) {
+        if (defect.value instanceof Error)
+            return boundReason(defect.value.name === "AsyncFiberError"
+                ? `${hook} crossed an asynchronous boundary inside a core transaction`
+                : `${hook} defect: ${defect.value.message}`);
+        return boundReason(`${hook} defect`);
+    }
+    return boundReason(`${hook} was interrupted`);
+}
+function shouldStop(cause) {
+    const failure = Cause.findErrorOption(cause);
+    return Option.isNone(failure) || failure.value instanceof ExtensionStop;
+}
+function stateError(reason, message) {
+    return new ExtensionStateError({ reason, message });
+}
+function boundedKey(key, what) {
+    return key.length >= 1 && key.length <= maximumKeyLength
+        ? Effect.succeed(key)
+        : Effect.fail(stateError("bound", `${what} must be 1..256 characters`));
+}
+/** Map one typed extension command failure to Shiitake's public error. */
+function commandFailure(failure) {
+    const message = boundReason(failure.message);
+    if (failure instanceof ExtensionCommandError)
+        switch (failure.reason) {
+            case "invalid":
+                return new ShiitakeError("contract", "invalid", message);
+            case "conflict":
+                return new ShiitakeError("store", "conflict", message);
+            case "not_found":
+                return new ShiitakeError("store", "rejected", message);
+            case "rejected":
+                return new ShiitakeError("extensions", "rejected", message);
+        }
+    if (failure instanceof AdmissionError)
+        switch (failure.reason) {
+            case "invalid":
+                return new ShiitakeError("contract", "invalid", message);
+            case "conflict":
+                return new ShiitakeError("contract", "conflict", message);
+            case "closed":
+                return new ShiitakeError("runtime", "closed", message);
+        }
+    return failure.reason === "bound"
+        ? new ShiitakeError("contract", "invalid", message)
+        : new ShiitakeError("store", "unavailable", message);
+}
+/** Activate the admitted roster and bind it to core's doors and tables. */
+export function openExtensionRuntime(input) {
+    const { owner } = input;
+    const frames = new WeakMap();
+    const members = new Map();
+    const incompatibleMigrations = new Set();
+    let projecting;
+    const updating = new Set();
+    const transacting = new Set();
+    let documentFrame;
+    const readServiceFor = (id) => Object.freeze({ extensionId: id });
+    const requireRead = (id) => Effect.flatMap(ExtensionRead, (service) => service.extensionId === id
+        ? Effect.void
+        : Effect.die(new Error("Extension read used another extension's context")));
+    const requireFrame = (id) => Effect.flatMap(ExtensionTx, (service) => {
+        const frame = frames.get(service);
+        return frame?.extensionId === id
+            ? Effect.succeed(frame)
+            : Effect.die(new Error("Extension write used outside its own core transaction"));
+    });
+    const storeStep = (run) => Effect.try({
+        try: run,
+        catch: () => stateError("unavailable", "Extension state is unavailable"),
+    });
+    const grantGuard = (member, capability) => member.admitted.grants.has(capability)
+        ? Effect.void
+        : Effect.fail(stateError("unavailable", `Extension is not granted ${capability}`));
+    function collectionHandle(member, name, spec) {
+        const id = member.admitted.id;
+        const decode = Schema.decodeResult(Schema.fromJsonString(spec.schema));
+        const encode = Schema.encodeResult(spec.schema);
+        const decodeJson = (json) => {
+            const decoded = decode(json);
+            return decoded._tag === "Failure"
+                ? Effect.fail(stateError("decode", `Stored ${name} record is invalid`))
+                : Effect.succeed(decoded.success);
+        };
+        return Object.freeze({
+            peek: (key) => {
+                if (projecting !== id || !member.admitted.grants.has("state"))
+                    throw new Error("Extension read used outside its own projection");
+                const json = readRecord(owner, id, name, key);
+                if (json === undefined)
+                    return Option.none();
+                const decoded = decode(json);
+                if (decoded._tag === "Failure")
+                    throw stateError("decode", `Stored ${name} record is invalid`);
+                return Option.some(decoded.success);
+            },
+            peekPage: (query) => {
+                if (projecting !== id || !member.admitted.grants.has("state"))
+                    throw new Error("Extension read used outside its own projection");
+                if (!Number.isSafeInteger(query.limit) ||
+                    query.limit < 1 ||
+                    query.limit > maximumPage)
+                    throw stateError("bound", "Page limit must be 1..64");
+                return readRecordPage(owner, id, name, query).map((json) => {
+                    const decoded = decode(json);
+                    if (decoded._tag === "Failure")
+                        throw stateError("decode", `Stored ${name} record is invalid`);
+                    return decoded.success;
+                });
+            },
+            get: (key) => requireRead(id).pipe(Effect.andThen(grantGuard(member, "state")), Effect.andThen(storeStep(() => readRecord(owner, id, name, key))), Effect.flatMap((json) => json === undefined
+                ? Effect.succeed(Option.none())
+                : decodeJson(json).pipe(Effect.map(Option.some)))),
+            page: (query) => requireRead(id).pipe(Effect.andThen(grantGuard(member, "state")), Effect.andThen(Number.isSafeInteger(query.limit) &&
+                query.limit >= 1 &&
+                query.limit <= maximumPage
+                ? Effect.void
+                : Effect.fail(stateError("bound", "Page limit must be 1..64"))), Effect.andThen(storeStep(() => readRecordPage(owner, id, name, query))), Effect.flatMap((rows) => Effect.forEach(rows, decodeJson))),
+            put: (value) => requireFrame(id).pipe(Effect.andThen(grantGuard(member, "state")), Effect.andThen(Effect.suspend(() => {
+                const encoded = encode(value);
+                if (encoded._tag === "Failure")
+                    return Effect.fail(stateError("encode", `The ${name} record does not match its schema`));
+                const json = JSON.stringify(encoded.success);
+                if (encoder.encode(json).byteLength > maximumRecordBytes)
+                    return Effect.fail(stateError("bound", `The ${name} record exceeds 1 MiB`));
+                const index = spec.index?.(value) ?? null;
+                return Effect.all([
+                    boundedKey(spec.key(value), "A record key"),
+                    index === null
+                        ? Effect.succeed(null)
+                        : boundedKey(index, "A record index"),
+                ]).pipe(Effect.flatMap(([key, boundedIndex]) => storeStep(() => {
+                    writeRecord(owner, id, name, key, boundedIndex, json);
+                })));
+            }))),
+            remove: (key) => requireFrame(id).pipe(Effect.andThen(grantGuard(member, "state")), Effect.andThen(storeStep(() => {
+                deleteRecord(owner, id, name, key);
+            }))),
+        });
+    }
+    /** Synchronous collection operations exist only inside state.update. */
+    function updateCollection(member, name, spec) {
+        const id = member.admitted.id;
+        const decode = Schema.decodeResult(Schema.fromJsonString(spec.schema));
+        const encode = Schema.encodeResult(spec.schema);
+        const guard = () => {
+            if (!updating.has(id) || !member.admitted.grants.has("state"))
+                throw stateError("unavailable", "Extension state update is unavailable");
+        };
+        const key = (value) => {
+            if (value.length < 1 || value.length > maximumKeyLength)
+                throw stateError("bound", "A record key must be 1..256 characters");
+            return value;
+        };
+        const decoded = (json) => {
+            const result = decode(json);
+            if (result._tag === "Failure")
+                throw stateError("decode", `Stored ${name} record is invalid`);
+            return result.success;
+        };
+        return Object.freeze({
+            get: (recordKey) => {
+                guard();
+                const json = readRecord(owner, id, name, key(recordKey));
+                return json === undefined ? Option.none() : Option.some(decoded(json));
+            },
+            page: (query) => {
+                guard();
+                if (!Number.isSafeInteger(query.limit) ||
+                    query.limit < 1 ||
+                    query.limit > maximumPage)
+                    throw stateError("bound", "Page limit must be 1..64");
+                return readRecordPage(owner, id, name, query).map(decoded);
+            },
+            put: (value) => {
+                guard();
+                const result = encode(value);
+                if (result._tag === "Failure")
+                    throw stateError("encode", `The ${name} record does not match its schema`);
+                const json = JSON.stringify(result.success);
+                if (encoder.encode(json).byteLength > maximumRecordBytes)
+                    throw stateError("bound", `The ${name} record exceeds 1 MiB`);
+                const index = spec.index?.(value) ?? null;
+                if (index !== null)
+                    key(index);
+                writeRecord(owner, id, name, key(spec.key(value)), index, json);
+            },
+            remove: (recordKey) => {
+                guard();
+                deleteRecord(owner, id, name, key(recordKey));
+            },
+        });
+    }
+    function timersFor(member) {
+        const id = member.admitted.id;
+        return Object.freeze({
+            set: (key, dueAt) => requireFrame(id).pipe(Effect.tap(() => grantGuard(member, "timers")), Effect.tap(() => boundedKey(key, "A timer key")), Effect.tap(() => Number.isSafeInteger(dueAt) && dueAt >= 0
+                ? Effect.void
+                : Effect.fail(stateError("bound", "A timer instant is invalid"))), Effect.flatMap((frame) => storeStep(() => {
+                writeTimer(owner, id, key, dueAt);
+                frame.timersChanged = true;
+            }))),
+            cancel: (key) => requireFrame(id).pipe(Effect.tap(() => grantGuard(member, "timers")), Effect.flatMap((frame) => storeStep(() => {
+                deleteTimer(owner, id, key);
+                frame.timersChanged = true;
+            }))),
+            read: (key) => requireRead(id).pipe(Effect.andThen(grantGuard(member, "timers")), Effect.andThen(storeStep(() => readTimer(owner, id, key))), Effect.map(Option.fromNullishOr)),
+        });
+    }
+    function attentionFor(member) {
+        const id = member.admitted.id;
+        const mutate = (sessionId, write) => requireFrame(id).pipe(Effect.tap(() => grantGuard(member, "attention")), Effect.flatMap((frame) => Effect.try({
+            try: () => {
+                decodeClientSessionId(sessionId);
+                write();
+                projectSessionAttention(owner, sessionId, input.readQueueHead(sessionId));
+                frame.observed.add(sessionId);
+            },
+            catch: (error) => error instanceof ShiitakeError && error.cause === "invalid"
+                ? stateError("bound", error.message)
+                : stateError("unavailable", "Attention update is unavailable"),
+        })));
+        return {
+            set: (sessionId, item) => {
+                const decoded = Schema.decodeUnknownResult(AttentionItemSchema, {
+                    onExcessProperty: "error",
+                })(item);
+                return decoded._tag === "Failure"
+                    ? Effect.fail(stateError("bound", "Attention item is invalid"))
+                    : mutate(sessionId, () => {
+                        if (!hasStoredSession(owner, sessionId))
+                            throw new Error("Attention Session is unavailable");
+                        setSessionAttention(owner, sessionId, id, decoded.success);
+                    });
+            },
+            clear: (sessionId, itemId) => boundedKey(itemId, "An attention id").pipe(Effect.andThen(mutate(sessionId, () => {
+                clearSessionAttention(owner, sessionId, id, itemId);
+            }))),
+        };
+    }
+    function sendFor(member) {
+        const id = member.admitted.id;
+        return (request) => requireFrame(id).pipe(Effect.flatMap((frame) => member.admitted.grants.has("send")
+            ? Effect.try({
+                try: () => {
+                    const { requireExistingSession = false } = request;
+                    const result = frame.admit({
+                        sessionId: request.sessionId,
+                        requireExistingSession,
+                        command: {
+                            type: "prompt",
+                            requestId: request.prompt.requestId,
+                            delivery: request.prompt.delivery,
+                            text: request.prompt.text,
+                        },
+                        when: request.when,
+                        origin: {
+                            kind: "extension",
+                            extensionId: id,
+                            correlation: request.correlation ?? null,
+                        },
+                    });
+                    return result.status === "accepted"
+                        ? {
+                            _tag: "Accepted",
+                            commandId: result.commandId,
+                            delivery: result.delivery,
+                        }
+                        : { _tag: "NotReady" };
+                },
+                catch: (error) => new AdmissionError({
+                    reason: error instanceof ShiitakeError
+                        ? error.cause === "conflict"
+                            ? "conflict"
+                            : error.cause === "closed"
+                                ? "closed"
+                                : "invalid"
+                        : "invalid",
+                    message: error instanceof ShiitakeError
+                        ? error.message
+                        : "Session command is invalid",
+                }),
+            })
+            : Effect.fail(new AdmissionError({
+                reason: "closed",
+                message: "Extension is not granted send",
+            }))));
+    }
+    /**
+     * Run one extension body in its own owner transaction. A failed body rolls
+     * back only this transaction; its Exit is returned for the caller's policy.
+     */
+    function runTransaction(member, body, boundary) {
+        return Effect.suspend(() => {
+            let bodyExit;
+            let frame;
+            const rollback = new Error("Extension transaction rolled back");
+            return input.door
+                .transact((admit) => {
+                const service = readServiceFor(member.admitted.id);
+                frame = {
+                    extensionId: member.admitted.id,
+                    admit,
+                    observed: new Set(),
+                    timersChanged: false,
+                };
+                frames.set(service, frame);
+                transacting.add(member.admitted.id);
+                const previousDocumentFrame = documentFrame;
+                documentFrame = frame;
+                try {
+                    bodyExit = Effect.runSyncExit(body.pipe(Effect.provideService(ExtensionTx, service), Effect.provideService(ExtensionRead, service)));
+                }
+                finally {
+                    documentFrame = previousDocumentFrame;
+                    frames.delete(service);
+                    transacting.delete(member.admitted.id);
+                }
+                if (Exit.isFailure(bodyExit))
+                    throw rollback;
+                return bodyExit.value;
+            }, boundary)
+                .pipe(Effect.map(() => {
+                if (bodyExit === undefined)
+                    throw new Error("Extension transaction returned no exit");
+                return bodyExit;
+            }), Effect.catch((error) => bodyExit !== undefined && Exit.isFailure(bodyExit)
+                ? Effect.succeed(bodyExit)
+                : Effect.fail(error)), Effect.tap((exit) => Exit.isSuccess(exit) && frame !== undefined
+                ? Effect.gen(function* () {
+                    for (const sessionId of frame?.observed ?? [])
+                        publishOwnerObservation(owner, sessionId);
+                    if (boundary === "request" && frame?.timersChanged === true)
+                        yield* input.requestWake;
+                })
+                : Effect.void));
+        });
+    }
+    /** Refresh at most the extension's outstanding resource ceiling, in bounded pages. */
+    function refreshAttentionOwner(extensionId) {
+        let after = "";
+        for (let count = 0; count < maximumExtensionAttention; count += maximumPage) {
+            const sessions = readAttentionSessionPage(owner, extensionId, after);
+            for (const sessionId of sessions) {
+                projectSessionAttention(owner, sessionId, input.readQueueHead(sessionId));
+                // Only a latency hint: readers re-read after the synchronous transaction.
+                queueMicrotask(() => {
+                    publishOwnerObservation(owner, sessionId);
+                });
+            }
+            const last = sessions.at(-1);
+            if (sessions.length < maximumPage || last === undefined)
+                return;
+            after = last;
+        }
+    }
+    /**
+     * Record a stop and log the full cause. The in-memory stop applies
+     * immediately either way, so the extension stays isolated until the next
+     * open even when nothing durable landed. A failed durable write is never
+     * swallowed: it fails this Effect with a `store`/`unavailable`
+     * `ShiitakeError` so the operation that triggered the stop learns the
+     * record did not actually land.
+     */
+    function recordStop(member, reason, cause, within) {
+        const stoppedAt = Date.now();
+        member.status = "stopped";
+        member.reason = reason;
+        member.stoppedAt = stoppedAt;
+        const write = Effect.try({
+            try: () => {
+                const run = () => {
+                    writeStatus(owner, member.admitted.id, {
+                        status: "stopped",
+                        reason,
+                        stoppedAt,
+                        revision: member.admitted.revision,
+                    });
+                    refreshAttentionOwner(member.admitted.id);
+                };
+                if (within === "own-transaction")
+                    owner.transactionSync(run);
+                else
+                    run();
+            },
+            catch: (error) => new ShiitakeError("store", "unavailable", `Extension ${member.admitted.id} stop status is unavailable`, undefined, error),
+        });
+        return Effect.gen(function* () {
+            const exit = yield* Effect.exit(write);
+            yield* Effect.logError("shiitake_extension_stopped").pipe(Effect.annotateLogs({
+                extensionId: member.admitted.id,
+                reason,
+                cause: cause === undefined ? null : Redacted.make(cause),
+                durable: Exit.isSuccess(exit),
+            }));
+            return yield* exit;
+        });
+    }
+    /** Persist a synchronous stop, in or outside an enclosing owner transaction. */
+    function recordStopSynchronously(member, reason, within) {
+        member.status = "stopped";
+        member.reason = reason;
+        member.stoppedAt = Date.now();
+        const run = () => {
+            writeStatus(owner, member.admitted.id, {
+                status: "stopped",
+                reason,
+                stoppedAt: member.stoppedAt,
+                revision: member.admitted.revision,
+            });
+            refreshAttentionOwner(member.admitted.id);
+        };
+        try {
+            if (within === "own-transaction")
+                owner.transactionSync(run);
+            else
+                run();
+        }
+        catch (error) {
+            throw new ShiitakeError("store", "unavailable", `Extension ${member.admitted.id} stop status is unavailable`, undefined, error);
+        }
+    }
+    function documentHandle(member, name, spec) {
+        const check = (sessionId) => {
+            if (documentFrame?.extensionId !== member.admitted.id ||
+                !member.admitted.grants.has("state"))
+                throw stateError("unavailable", "Session documents require the extension's state transaction");
+            decodeClientSessionId(sessionId);
+            return documentFrame;
+        };
+        const read = (sessionId) => {
+            check(sessionId);
+            const json = readSessionDocument(owner, sessionId, member.admitted.id, name) ??
+                encodeDocument(spec, spec.initial);
+            if (encoder.encode(json).byteLength > spec.maxBytes)
+                throw stateError("bound", "Session document exceeds maxBytes");
+            const decoded = Schema.decodeUnknownResult(Schema.fromJsonString(spec.schema))(json);
+            if (decoded._tag === "Failure")
+                throw stateError("decode", "Stored session document does not match its schema");
+            const value = decoded.success;
+            return value;
+        };
+        const handle = {
+            read,
+            update: (sessionId, change) => {
+                const frame = check(sessionId);
+                const value = change(read(sessionId));
+                writeSessionDocument(owner, sessionId, member.admitted.id, name, encodeDocument(spec, value));
+                frame.observed.add(sessionId);
+            },
+        };
+        return Object.freeze(handle);
+    }
+    function contextFor(member) {
+        const observed = new Set();
+        const update = (body) => {
+            const id = member.admitted.id;
+            if (member.status !== "running" ||
+                !member.admitted.grants.has("state") ||
+                updating.has(id) ||
+                transacting.has(id) ||
+                projecting === id)
+                throw stateError("unavailable", "Extension state update is unavailable");
+            try {
+                const result = owner.transactionSync(() => {
+                    updating.add(id);
+                    try {
+                        return invokeSyncHandler(body, undefined);
+                    }
+                    finally {
+                        updating.delete(id);
+                    }
+                });
+                for (const sessionId of observed)
+                    publishOwnerObservation(owner, sessionId);
+                return result;
+            }
+            catch (error) {
+                if (!(error instanceof AsyncExtensionTransactionError))
+                    throw error;
+                const reason = error.message;
+                recordStopSynchronously(member, reason, "own-transaction");
+                throw new ExtensionStop({ reason });
+            }
+            finally {
+                observed.clear();
+            }
+        };
+        return Object.freeze({
+            collection: (name, spec) => collectionHandle(member, name, spec),
+            updateCollection: (name, spec) => updateCollection(member, name, spec),
+            document: (name, spec) => documentHandle(member, name, spec),
+            update,
+            observeUpdate: (sessionId) => {
+                if (!updating.has(member.admitted.id))
+                    throw stateError("unavailable", "Extension observation is unavailable");
+                observed.add(decodeClientSessionId(sessionId));
+            },
+            context: Object.freeze({
+                manifest: member.admitted.manifest,
+                revision: member.admitted.revision,
+                grants: Object.freeze([...member.admitted.grants]),
+                send: sendFor(member),
+                timers: timersFor(member),
+                attention: attentionFor(member),
+                hasPendingSteer: (run) => requireRead(member.admitted.id).pipe(Effect.andThen(grantGuard(member, "run_tools")), Effect.andThen(storeStep(() => hasPendingSessionSteer(owner, decodeClientSessionId(run.sessionId), run.workId)))),
+                hasSuccessfulToolResult: (run, toolCallId) => requireRead(member.admitted.id).pipe(Effect.andThen(grantGuard(member, "run_tools")), Effect.andThen(storeStep(() => hasSuccessfulToolResult(owner, decodeClientSessionId(run.sessionId), run.workId, toolCallId)))),
+                observe: (sessionId) => requireFrame(member.admitted.id).pipe(Effect.map((frame) => {
+                    frame.observed.add(sessionId);
+                })),
+                transact: (body) => {
+                    const run = member.status === "running"
+                        ? runTransaction(member, body, "request").pipe(Effect.orDie)
+                        : Effect.fail(new ExtensionStop({
+                            reason: member.reason ?? "Extension is stopped",
+                        }));
+                    return run.pipe(Effect.flatMap((exit) => {
+                        if (Exit.isSuccess(exit))
+                            return Effect.succeed(exit.value);
+                        if (!shouldStop(exit.cause))
+                            return Effect.failCause(exit.cause);
+                        const reason = stopReason("transact", exit.cause);
+                        return recordStop(member, reason, exit.cause, "own-transaction").pipe(Effect.flatMap(() => Effect.fail(new ExtensionStop({ reason }))));
+                    }));
+                },
+            }),
+        });
+    }
+    /** Pure per-version migrations, applied and re-decoded in one transaction. */
+    function migrate(member) {
+        const { id, definition, revision } = member.admitted;
+        const declared = definition.state.version;
+        owner.transactionSync(() => {
+            const ledger = readStateLedger(owner, id);
+            if (ledger !== undefined && ledger.version > declared)
+                throw new ShiitakeError("extensions", "conflict", `Stored ${id} state version ${String(ledger.version)} is newer than ${String(declared)}`);
+            if (ledger !== undefined && ledger.version < declared) {
+                let rows = readAllRecords(owner, id).map((row) => ({
+                    collection: row.collection,
+                    key: row.key,
+                    value: decodeStoredJson(row.valueJson),
+                }));
+                for (let version = ledger.version; version < declared; version += 1) {
+                    const step = definition.state.migrations[version];
+                    if (step === undefined)
+                        throw new IncompatibleStateMigrationError(`Missing ${id} state migration from ${String(version)}`);
+                    try {
+                        rows = rows.flatMap((row) => step(row));
+                    }
+                    catch (cause) {
+                        throw new IncompatibleStateMigrationError(`Failed ${id} state migration from ${String(version)}`, { cause });
+                    }
+                }
+                deleteAllRecords(owner, id);
+                for (const row of rows) {
+                    const declaredSpec = definition.state.collections[row.collection];
+                    if (declaredSpec === undefined)
+                        throw new IncompatibleStateMigrationError(`Migrated ${id} record names an undeclared collection`);
+                    const decoded = declaredSpec.indexFromEncoded(row.value);
+                    if (decoded._tag === "Failure")
+                        throw new IncompatibleStateMigrationError(`Migrated ${id} ${row.collection} record is invalid`);
+                    writeRecord(owner, id, row.collection, row.key, decoded.success, JSON.stringify(row.value));
+                }
+            }
+            writeStateLedger(owner, id, declared, revision);
+        });
+    }
+    function activateMember(member, scope) {
+        const context = contextFor(member);
+        return Effect.suspend(() => member.admitted.definition.activate(context)).pipe(Effect.provideService(Scope.Scope, scope), Effect.exit, Effect.flatMap((exit) => {
+            if (Exit.isSuccess(exit)) {
+                member.hooks = exit.value;
+                return Effect.void;
+            }
+            return recordStop(member, stopReason("activation", exit.cause), exit.cause, "own-transaction");
+        }));
+    }
+    const running = (capability) => [...members.values()].filter((member) => member.status === "running" &&
+        member.hooks !== undefined &&
+        member.admitted.grants.has(capability));
+    function statusOf(member) {
+        return Object.freeze({
+            id: member.admitted.id,
+            version: member.admitted.manifest.version,
+            revision: member.admitted.revision,
+            status: member.status,
+            reason: member.reason,
+            stoppedAt: member.stoppedAt,
+        });
+    }
+    function isRunParticipant(member) {
+        return (member.status === "running" &&
+            member.hooks !== undefined &&
+            (member.admitted.grants.has("run_tools") ||
+                member.admitted.grants.has("files") ||
+                member.admitted.grants.has("prompt") ||
+                member.admitted.grants.has("compaction_handoff")));
+    }
+    /** Run a read-only network or tool hook outside the write transaction. */
+    function runRead(member, hook, effect) {
+        return Effect.exit(effect.pipe(Effect.provideService(ExtensionRead, readServiceFor(member.admitted.id)))).pipe(Effect.flatMap((exit) => Exit.isSuccess(exit)
+            ? Effect.succeed(Option.some(exit.value))
+            : recordStop(member, stopReason(hook, exit.cause), exit.cause, "own-transaction").pipe(Effect.as(Option.none()))));
+    }
+    const stopFromExit = (member, hook, exit) => Exit.isFailure(exit)
+        ? recordStop(member, stopReason(hook, exit.cause), exit.cause, "own-transaction")
+        : Effect.void;
+    /**
+     * Run pending state migrations. A stored version newer than the declared one
+     * fails construction; any other failure stops only this extension.
+     */
+    function prepare(member) {
+        return Effect.try({
+            try: () => {
+                migrate(member);
+                owner.transactionSync(() => {
+                    for (const [name, spec] of Object.entries(member.admitted.documents))
+                        declareSessionDocument(owner, {
+                            extensionId: member.admitted.id,
+                            name,
+                            initialJson: encodeDocument(spec, spec.initial),
+                            fork: spec.fork,
+                            maxBytes: spec.maxBytes,
+                        });
+                });
+            },
+            catch: (error) => error,
+        }).pipe(Effect.as(true), Effect.catch((error) => {
+            if (error instanceof ShiitakeError)
+                return Effect.fail(error);
+            if (error instanceof IncompatibleStateMigrationError &&
+                (member.admitted.grants.has("run_tools") ||
+                    member.admitted.grants.has("files") ||
+                    member.admitted.grants.has("prompt") ||
+                    member.admitted.grants.has("compaction_handoff")))
+                incompatibleMigrations.add(member.admitted.id);
+            return recordStop(member, boundReason(error instanceof Error
+                ? `migration: ${error.message}`
+                : "migration failed"), Cause.die(error), "own-transaction").pipe(Effect.as(false));
+        }));
+    }
+    return Effect.gen(function* () {
+        const scope = yield* Scope.make();
+        for (const admitted of input.admitted) {
+            const stored = readStatus(owner, admitted.id);
+            const keepStopped = stored?.status === "stopped" && stored.revision === admitted.revision;
+            const member = {
+                admitted,
+                hooks: undefined,
+                status: keepStopped ? "stopped" : "running",
+                reason: keepStopped ? stored.reason : null,
+                stoppedAt: keepStopped ? stored.stoppedAt : null,
+            };
+            members.set(admitted.id, member);
+            // Every settled consumer has a cursor from its first roster on, so a
+            // later resume replays only what it missed.
+            yield* Effect.try({
+                try: () => {
+                    if (admitted.grants.has("settled"))
+                        owner.transactionSync(() => {
+                            if (readCursor(owner, admitted.id) === undefined)
+                                advanceCursor(owner, admitted.id, readCursor(owner, coreConsumer) ?? 0);
+                        });
+                },
+                catch: () => new ShiitakeError("store", "unavailable", "Settled cursor is unavailable"),
+            });
+            const prepared = yield* prepare(member).pipe(Effect.onError(() => Scope.close(scope, Exit.void)));
+            if (!prepared)
+                continue;
+            if (keepStopped)
+                continue;
+            yield* Effect.try({
+                try: () => {
+                    owner.transactionSync(() => {
+                        writeStatus(owner, admitted.id, {
+                            status: "running",
+                            reason: null,
+                            stoppedAt: null,
+                            revision: admitted.revision,
+                        });
+                        refreshAttentionOwner(admitted.id);
+                    });
+                },
+                catch: () => new ShiitakeError("store", "unavailable", "Extension status is unavailable"),
+            });
+            yield* activateMember(member, scope);
+        }
+        yield* Effect.try({
+            try: () => {
+                owner.transactionSync(() => {
+                    const changed = replaceAttentionGrants(owner, input.admitted
+                        .filter((member) => member.grants.has("attention"))
+                        .map((member) => member.id));
+                    for (const id of changed)
+                        refreshAttentionOwner(id);
+                });
+            },
+            catch: () => new ShiitakeError("store", "unavailable", "Attention grants are unavailable"),
+        });
+        const runtime = {
+            runParticipants: () => [...members.values()]
+                .filter(isRunParticipant)
+                .map((member) => [member.admitted.id, member.admitted.fingerprint]),
+            incompatibleMigrations: () => [...incompatibleMigrations],
+            modulesForRun: (run, captured) => Effect.forEach(running("run_tools"), (member) => {
+                const hook = member.hooks?.moduleForRun;
+                return !captured.has(member.admitted.id) || hook === undefined
+                    ? Effect.succeed(Option.none())
+                    : runRead(member, "moduleForRun", Effect.suspend(() => hook(run))).pipe(Effect.map(Option.flatten));
+            }).pipe(Effect.map((modules) => modules.flatMap(Option.toArray))),
+            filesForRun: (run, captured) => Effect.gen(function* () {
+                const member = running("files").find((entry) => captured.has(entry.admitted.id));
+                if (member === undefined)
+                    return [];
+                const hook = member.hooks?.filesForRun;
+                if (hook === undefined) {
+                    yield* recordStop(member, "files: granted capability has no handler", undefined, "own-transaction");
+                    return yield* Effect.fail(new ShiitakeError("extensions", "rejected", "Extension Files are unavailable"));
+                }
+                const result = yield* runRead(member, "filesForRun", Effect.suspend(() => hook(run)));
+                if (Option.isNone(result))
+                    return yield* Effect.fail(new ShiitakeError("extensions", "rejected", "Extension Files capture failed"));
+                return Object.freeze([...Option.getOrElse(result.value, () => [])]);
+            }),
+            promptSections: (run, captured) => Effect.gen(function* () {
+                const sections = [];
+                let totalBytes = 0;
+                for (const member of running("prompt")) {
+                    if (!captured.has(member.admitted.id))
+                        continue;
+                    const hook = member.hooks?.prompt;
+                    if (hook === undefined) {
+                        yield* recordStop(member, "prompt: granted capability has no handler", undefined, "own-transaction");
+                        return yield* Effect.fail(new ShiitakeError("extensions", "rejected", "Extension prompt is unavailable"));
+                    }
+                    const result = yield* Effect.exit(invokeExtensionHook(() => hook(run)).pipe(Effect.provideService(ExtensionRead, readServiceFor(member.admitted.id))));
+                    if (Exit.isFailure(result)) {
+                        yield* recordStop(member, stopReason("prompt", result.cause), result.cause, "own-transaction");
+                        return yield* Effect.fail(new ShiitakeError("extensions", "rejected", "Extension prompt failed"));
+                    }
+                    const decoded = decodePromptSections(result.value);
+                    const values = decoded._tag === "Success" ? decoded.success : [];
+                    totalBytes += values.reduce((size, section) => size + encoder.encode(section.text).byteLength, 0);
+                    if (decoded._tag === "Failure" ||
+                        new Set(values.map(({ name }) => name)).size !== values.length ||
+                        totalBytes > 65536) {
+                        yield* recordStop(member, "prompt: section is invalid or exceeds its bound", undefined, "own-transaction");
+                        return yield* Effect.fail(new ShiitakeError("extensions", "rejected", "Extension prompt is invalid"));
+                    }
+                    sections.push(...[...values]
+                        .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
+                        .map((section) => ({
+                        name: `${member.admitted.id}.${section.name}`,
+                        text: section.text,
+                    })));
+                }
+                return sections;
+            }),
+            compactionHandoff: (captured) => running("compaction_handoff").find(({ admitted }) => captured.has(admitted.id))?.hooks?.compactionHandoff,
+            settledConsumers: () => running("settled").map((member) => ({
+                id: member.admitted.id,
+                cursor: readCursor(owner, member.admitted.id) ?? 0,
+            })),
+            deliverSettled: (runs, throughSequence) => Effect.forEach(running("settled"), (member) => Effect.suspend(() => {
+                const cursor = readCursor(owner, member.admitted.id) ?? 0;
+                if (throughSequence <= cursor)
+                    return Effect.void;
+                const slice = runs.filter(({ sequence }) => sequence > cursor);
+                const hook = member.hooks?.onSettled;
+                const body = (hook === undefined || slice.length === 0
+                    ? Effect.void
+                    : hook(slice)).pipe(Effect.andThen(Effect.sync(() => {
+                    advanceCursor(owner, member.admitted.id, throughSequence);
+                })));
+                return runTransaction(member, body, "reconcile").pipe(Effect.flatMap((exit) => stopFromExit(member, "onSettled", exit)));
+            }), { discard: true }),
+            fireDueTimers: (now) => Effect.gen(function* () {
+                const ids = running("timers").map(({ admitted }) => admitted.id);
+                const due = readDueTimers(owner, ids, now, maximumPage);
+                for (const timer of due) {
+                    const member = members.get(timer.extensionId);
+                    if (member?.status !== "running")
+                        continue;
+                    const hook = member.hooks?.onTimer;
+                    const body = Effect.suspend(() => {
+                        if (readTimer(owner, timer.extensionId, timer.key) !== timer.dueAt)
+                            return Effect.void;
+                        deleteTimer(owner, timer.extensionId, timer.key);
+                        return hook === undefined
+                            ? Effect.void
+                            : hook({ key: timer.key, dueAt: timer.dueAt, firedAt: now });
+                    });
+                    const exit = yield* runTransaction(member, body, "reconcile");
+                    yield* stopFromExit(member, "onTimer", exit);
+                }
+                return due.length === maximumPage;
+            }),
+            timerWake: (now) => readTimerWake(owner, running("timers").map(({ admitted }) => admitted.id), now),
+            project: (sessionId) => {
+                const slots = {};
+                for (const member of members.values()) {
+                    const projects = member.admitted.grants.has("projection");
+                    let catalog = member.admitted.grants.has("commands")
+                        ? member.admitted.definition.catalog
+                        : undefined;
+                    if (!projects && catalog === undefined)
+                        continue;
+                    const revision = member.admitted.revision;
+                    const projection = member.admitted.definition.contract.projection;
+                    const hook = member.hooks?.project;
+                    if (member.status === "running" && member.hooks !== undefined) {
+                        const value = !projects || hook === undefined || projection === null
+                            ? Option.some(null)
+                            : (() => {
+                                let output = null;
+                                let failure;
+                                projecting = member.admitted.id;
+                                try {
+                                    const projected = invokeSyncHandler(() => hook(sessionId), undefined);
+                                    if (Option.isSome(projected)) {
+                                        const encoded = Schema.encodeResult(projection.schema)(projected.value);
+                                        if (encoded._tag === "Failure")
+                                            throw new Error("Extension projection is invalid");
+                                        const json = Schema.decodeUnknownResult(JsonValueSchema)(encoded.success);
+                                        if (json._tag === "Failure")
+                                            throw new Error("Extension projection is not JSON");
+                                        output = json.success;
+                                        const projectCatalog = member.hooks.projectCatalog;
+                                        if (catalog !== undefined &&
+                                            projectCatalog !== undefined)
+                                            catalog = Schema.decodeUnknownSync(JsonValueSchema)(invokeSyncHandler(() => projectCatalog(json.success), undefined));
+                                    }
+                                }
+                                catch (error) {
+                                    failure = error;
+                                }
+                                finally {
+                                    projecting = undefined;
+                                }
+                                if (failure !== undefined) {
+                                    recordStopSynchronously(member, boundReason(failure instanceof Error
+                                        ? `project defect: ${failure.message}`
+                                        : "project defect"), "enclosing-transaction");
+                                    return Option.none();
+                                }
+                                return Option.some(output);
+                            })();
+                        if (Option.isSome(value)) {
+                            slots[member.admitted.id] = Object.freeze(catalog === undefined
+                                ? { status: "running", revision, value: value.value }
+                                : {
+                                    status: "running",
+                                    revision,
+                                    value: value.value,
+                                    catalog,
+                                });
+                            continue;
+                        }
+                    }
+                    slots[member.admitted.id] = Object.freeze({
+                        status: "stopped",
+                        revision,
+                        reason: member.reason ?? "Extension did not activate",
+                    });
+                }
+                return Object.freeze(slots);
+            },
+            call: (target, extensionId, command, raw) => Effect.gen(function* () {
+                const member = members.get(extensionId);
+                if (member?.admitted.grants.has("commands") !== true)
+                    return yield* Effect.fail(new ShiitakeError("extensions", "unavailable", "Extension is unavailable"));
+                if (member.status !== "running" || member.hooks === undefined)
+                    return yield* Effect.fail(new ShiitakeError("extensions", "unavailable", `Extension ${extensionId} is stopped: ${member.reason ?? "not activated"}`));
+                const commands = member.admitted.definition.contract.commands;
+                const spec = Object.hasOwn(commands, command)
+                    ? commands[command]
+                    : undefined;
+                if (spec?.scope !== target.scope)
+                    return yield* Effect.fail(new ShiitakeError("contract", "invalid", "Extension command is unknown"));
+                const sessionId = target.scope === "session"
+                    ? yield* Effect.try({
+                        try: () => decodeClientSessionId(target.sessionId),
+                        catch: () => new ShiitakeError("contract", "invalid", "Session id is invalid"),
+                    })
+                    : null;
+                const handler = member.hooks.commands.get(command);
+                if (handler === undefined) {
+                    const decoded = Schema.decodeUnknownResult(spec.input, {
+                        onExcessProperty: "error",
+                    })(raw);
+                    if (decoded._tag === "Failure")
+                        return yield* Effect.fail(new ShiitakeError("contract", "invalid", "Extension command input is invalid"));
+                    yield* recordStop(member, `command ${command} has no handler`, undefined, "own-transaction");
+                    return yield* Effect.fail(new ShiitakeError("extensions", "unavailable", "Extension is stopped"));
+                }
+                const prepared = handler({ sessionId, input: raw });
+                if (prepared._tag === "Failure")
+                    return yield* Effect.fail(new ShiitakeError("contract", "invalid", "Extension command input is invalid"));
+                const body = prepared.success();
+                const exit = yield* runTransaction(member, body, "request");
+                if (Exit.isSuccess(exit))
+                    return exit.value;
+                const failure = Cause.findErrorOption(exit.cause);
+                if (Option.isSome(failure) && !shouldStop(exit.cause))
+                    return yield* Effect.fail(commandFailure(failure.value));
+                const reason = stopReason(`command ${command}`, exit.cause);
+                yield* recordStop(member, reason, exit.cause, "own-transaction");
+                return yield* Effect.fail(new ShiitakeError("extensions", "unavailable", `Extension ${extensionId} is stopped: ${reason}`));
+            }),
+            list: () => [...members.values()].map(statusOf),
+            resume: (id) => Effect.gen(function* () {
+                const member = members.get(id);
+                if (member === undefined)
+                    return yield* Effect.fail(new ShiitakeError("extensions", "unavailable", "Extension is unavailable"));
+                if (member.status === "stopped") {
+                    yield* Effect.try({
+                        try: () => {
+                            owner.transactionSync(() => {
+                                writeStatus(owner, member.admitted.id, {
+                                    status: "running",
+                                    reason: null,
+                                    stoppedAt: null,
+                                    revision: member.admitted.revision,
+                                });
+                                refreshAttentionOwner(member.admitted.id);
+                            });
+                        },
+                        catch: () => new ShiitakeError("store", "unavailable", "Extension status is unavailable"),
+                    });
+                    member.status = "running";
+                    member.reason = null;
+                    member.stoppedAt = null;
+                    if (member.hooks === undefined && (yield* prepare(member)))
+                        yield* activateMember(member, scope);
+                    yield* input.requestWake;
+                }
+                return statusOf(member);
+            }),
+            close: Scope.close(scope, Exit.void),
+        };
+        return Object.freeze(runtime);
+    });
+}