@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/dist/internal/effect-contracts.d.ts

@@ -0,0 +1,236 @@
+import type { HostMetaOptions } from "./host-meta.js";
+import type { ExtensionRosterV0 } from "../extensions.js";
+import type { Api, AssistantMessage, Model, MuleStreamFunction, RetryPolicy } from "@fungi.computer/mule/effect";
+import type { CapabilitySource, ExecutionOptions, ModuleRegistration } from "@fungi.computer/mycelium";
+import type { GrantsDelivery, GrantsDeliveryResult, ToolAccess } from "./contracts.js";
+import type { Sandbox } from "@fungi.computer/mycelium/effect";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import type * as Scope from "effect/Scope";
+import type { WatchdogError } from "@fungi.computer/watchdog";
+import type { WatchdogExecutionDecision, WatchdogRunningJob, ConcurrentWatchdogRuntimeEffect } from "@fungi.computer/watchdog/effect";
+import type { AbortCommand, Accepted, BranchCommand, OperatorCommand, TitleCommand, CancelCommand, CancelResult, ForkCommand, ForkedSession, CompactCommand, PromptCommand, PromptDelivery, ReadOptions, SessionCommand, SessionFrame, SessionSnapshot, SessionSummaryPage, SubscribeOptions, WatchOptions } from "../client.js";
+import type { ShiitakeError } from "../errors.js";
+import type { ExtensionStatusV0, Json } from "../extensions.js";
+import type { InstructionSnapshot, ModelDescription, RuntimePendingWork, SqliteOwner, StorageBudget, CompactionOptions } from "./contracts.js";
+import type { ModelPreference } from "./model-preference.js";
+/** Effect-native acquired Pi model and finalizer. */
+export type ModelAcquisitionEffect = Readonly<{
+    /** Exact Pi model selected for this run. */
+    model: Model<Api>;
+    /** Optional explicit Pi stream function for custom providers and tests. */
+    stream?: MuleStreamFunction;
+    /** Provider’s bounded Retry-After for a clean HTTP refusal, if reported. */
+    retryAfterMs?: (message: AssistantMessage) => number | undefined;
+    /** Effect finalizer for acquired model resources. */
+    release: Effect.Effect<void, ShiitakeError>;
+}>;
+/** Effect-native model acquisition owner. */
+export type ModelSourceEffect = Readonly<{
+    /** Acquire one selection and its request-scoped egress. */
+    acquire: (input: Readonly<{
+        sessionId: string;
+        preference: ModelPreference | null;
+    }>) => Effect.Effect<ModelAcquisitionEffect, ShiitakeError>;
+    /** Read the would-be selection's context window; absent leaves it unknown. */
+    describe?: (input: Readonly<{
+        sessionId: string;
+        preference: ModelPreference | null;
+    }>) => Effect.Effect<ModelDescription, ShiitakeError>;
+}>;
+/** Effect-native instruction snapshot owner. */
+export type InstructionSourceEffect = Readonly<{
+    /** Load the session's bounded instruction snapshot. */
+    load: (input: Readonly<{
+        sessionId: string;
+        commandId: string;
+    }>) => Effect.Effect<InstructionSnapshot, ShiitakeError, Scope.Scope>;
+}>;
+/** Effect-native Mycelium construction inputs. */
+export type ToolSourceEffect = Readonly<{
+    /** Host-owned limit for one scoped tool invocation. */
+    execution?: ExecutionOptions;
+    /** Mycelium module descriptors visible in the run scope. */
+    modules: readonly ModuleRegistration[];
+    /** Dynamic host capability projections acquired by Mycelium. */
+    sources: readonly CapabilitySource[];
+    /**
+     * Effect-native sandbox boundary for scoped capabilities. Adapt
+     * Promise-shaped work with Mycelium's `fromTypedSandbox`.
+     */
+    sandbox: Sandbox;
+    /**
+     * The Agent-wide access defaults for every tool of the run, as data. A
+     * Session's grants the host delivered with the owner's `grants.deliver` override
+     * the default key by key. Mycelium reads them at every call; Shiitake never
+     * interprets them. Absent is full access.
+     */
+    access?: ToolAccess;
+}>;
+/** Effect-native owner for scheduling the opaque durable reconciler. */
+export type RuntimeHostEffect = Readonly<{
+    /** Bind the one repeatable zero-input reconciliation program. */
+    bind: (input: Readonly<{
+        reconcile: Effect.Effect<void, ShiitakeError>;
+        pendingWork: Effect.Effect<RuntimePendingWork, ShiitakeError>;
+    }>) => Effect.Effect<Readonly<{
+        /** Commit owner mutations together with the host wake guarantee. No external I/O. */
+        commit: <A>(mutation: Effect.Effect<A, ShiitakeError>) => Effect.Effect<A, ShiitakeError>;
+        /** Request one later reconciliation without running it inline. */
+        requestWake: Effect.Effect<void, ShiitakeError>;
+        /** Stop callbacks and release the bound host registration. */
+        close: Effect.Effect<void, ShiitakeError>;
+    }>, ShiitakeError>;
+}>;
+/** Validated construction bag for owned Effect composition. */
+export type ShiitakeEffectOptions = Readonly<{
+    /**
+     * The schema of the opaque metadata this host attaches to prompts and
+     * operator lines. Shiitake checks, stores and returns it; it never reads it.
+     */
+    meta?: HostMetaOptions;
+    /** Native owner storage and synchronous transaction capability. */
+    store: SqliteOwner;
+    /** Disk budget for `store`; absent never refuses for storage pressure. */
+    storageBudget?: StorageBudget;
+    /** Compaction budgets; absent uses Pi's defaults for every model. */
+    compaction?: CompactionOptions;
+    /** One host lane in Shiitake's existing Watchdog, opened before recovery. */
+    hostJobs?: Readonly<{
+        lane: string;
+        /** Open the host executor before persisted work is recovered. */
+        open: (runtime: ConcurrentWatchdogRuntimeEffect) => Readonly<{
+            /** Execute a job claimed for this host lane. */
+            execute: (job: WatchdogRunningJob) => Effect.Effect<WatchdogExecutionDecision, WatchdogError>;
+        }>;
+    }>;
+    /** Effect-native Pi model owner. */
+    model: ModelSourceEffect;
+    /** Effect-native instruction snapshot owner. */
+    instructions: InstructionSourceEffect;
+    /** Effect-native scoped capability inputs, omitted when no tools exist. */
+    tools?: ToolSourceEffect;
+    /** Runtime owner that schedules the opaque durable reconciler. */
+    runtime: RuntimeHostEffect;
+    /**
+     * The host's explicit extension roster and grants. Required: a host with no
+     * extensions passes `{ roster: [], grants: [] }`.
+     */
+    extensions: ExtensionRosterV0;
+    /**
+     * Pi's bounded retry policy around each live assistant call. Omitted
+     * means `piCodingAgentRetryDefaults` (Pi coding-agent's own numbers).
+     */
+    retry?: RetryPolicy;
+    /**
+     * Maximum silence between live provider stream events, in milliseconds.
+     * Omitted means `piHttpIdleTimeoutMs` (Pi coding-agent's own default).
+     */
+    modelStreamIdleTimeoutMs?: number;
+}>;
+/** Effect-native race-safe watch result. */
+export type ShiitakeEffectWatch = Readonly<{
+    /** Race-safe durable baseline. */
+    snapshot: SessionSnapshot;
+    /** Live frames after the baseline boundary. */
+    changes: Stream.Stream<SessionFrame, ShiitakeError>;
+    /** Effect finalizer for the live observation. */
+    close: Effect.Effect<void, ShiitakeError>;
+}>;
+/** Effect-native addressable Session handle. */
+export type ShiitakeEffectCommandHandler = {
+    /** Accept one durable prompt command. */
+    (input: PromptCommand | CompactCommand): Effect.Effect<Accepted, ShiitakeError>;
+    /** Cancel one accepted command, or report that it is too late. */
+    (input: CancelCommand): Effect.Effect<CancelResult, ShiitakeError>;
+    /** Abort the active run, select a lineage leaf, or record an operator line. */
+    (input: AbortCommand | BranchCommand | OperatorCommand | TitleCommand): Effect.Effect<undefined, ShiitakeError>;
+    /** Fork one complete entry lineage into a new Session. */
+    (input: ForkCommand): Effect.Effect<ForkedSession, ShiitakeError>;
+    /** Execute an already-decoded command union. */
+    (input: SessionCommand): Effect.Effect<Accepted | CancelResult | ForkedSession | undefined, ShiitakeError>;
+};
+/** Delivery intent and an optional private retry key for Effect-native sending. */
+export type ShiitakeEffectSendOptions = Readonly<{
+    /** Images retained alongside text in the accepted user message. */
+    images?: PromptCommand["images"];
+    delivery?: PromptDelivery;
+    requestId?: string;
+}>;
+/** Effect-native addressable Session handle. */
+export type ShiitakeEffectSession = Readonly<{
+    /** Execute one retained type-discriminated Session command. */
+    command: ShiitakeEffectCommandHandler;
+    /** Cancel the running turn and all queued prompts, retaining their text. */
+    abort: Effect.Effect<void, ShiitakeError>;
+    /** Send text with one generated or explicitly supplied request identity. */
+    send: (text: string, options?: ShiitakeEffectSendOptions) => Effect.Effect<Accepted, ShiitakeError>;
+    /** Cancel exactly the accepted work named by its owner-issued identity. */
+    cancel: (input: {
+        commandId: string;
+        onlyIfPending?: boolean;
+    }) => Effect.Effect<CancelResult, ShiitakeError>;
+    /** Address one rostered extension's Session-scope commands. */
+    extension: (extensionId: string) => ShiitakeEffectSessionExtension;
+    /** Lineage-local selection used when the next run acquires its model. */
+    modelPreference: Readonly<{
+        /** Read the saved override; null selects the Agent default. */
+        read: Effect.Effect<ModelPreference | null, ShiitakeError>;
+        /** Save an override without starting a provider call. */
+        set: (preference: ModelPreference | null) => Effect.Effect<void, ShiitakeError>;
+    }>;
+    /** Read a bounded durable baseline. */
+    read: (input?: ReadOptions) => Effect.Effect<SessionSnapshot, ShiitakeError>;
+    /** Subscribe to strict-after replay and live frames. */
+    subscribe: (input: SubscribeOptions) => Stream.Stream<SessionFrame, ShiitakeError>;
+    /** Open a race-safe baseline plus live changes resource. */
+    watch: (input?: WatchOptions) => Effect.Effect<ShiitakeEffectWatch, ShiitakeError>;
+}>;
+/** Effect-native Session-scope extension commands. */
+export type ShiitakeEffectSessionExtension = Readonly<{
+    /** Run one command with its encoded input; succeeds with the encoded output. */
+    call: (command: string, input: Json) => Effect.Effect<Json, ShiitakeError>;
+}>;
+/** Effect-native Agent-scope extension controls. */
+export type ShiitakeEffectAgentExtensions = Readonly<{
+    /** Every rostered extension and whether it is running. */
+    list: Effect.Effect<readonly ExtensionStatusV0[], ShiitakeError>;
+    /** Resume a stopped extension; it replays its settled backlog once. */
+    resume: (extensionId: string) => Effect.Effect<ExtensionStatusV0, ShiitakeError>;
+    /** Run one Agent-scope command with its encoded input. */
+    call: (extensionId: string, command: string, input: Json) => Effect.Effect<Json, ShiitakeError>;
+}>;
+/** Effect-native durable harness. */
+export type ShiitakeEffectAgent = Readonly<{
+    /** Return the Session identity reserved for this request ID. */
+    createSession: (requestId: string) => Effect.Effect<string, ShiitakeError>;
+    /** Permanently delete one idle Session; false when it does not exist. */
+    deleteSession: (sessionId: string) => Effect.Effect<boolean, ShiitakeError>;
+    /** Read one bounded page of existing conversations through the store owner. */
+    listSessions: (after?: string) => Effect.Effect<SessionSummaryPage, ShiitakeError>;
+    /** List, resume and call rostered extensions. */
+    extensions: ShiitakeEffectAgentExtensions;
+    /** Address a session without performing I/O. */
+    session: (sessionId: string) => ShiitakeEffectSession;
+    /** Effect finalizer for the owned harness. */
+    close: Effect.Effect<void, ShiitakeError>;
+}>;
+/**
+ * The in-process owner of a durable harness. Only the host holds it, so only
+ * the host can write a Session's grants or attach metadata; no HTTP or
+ * remote client can.
+ */
+export type ShiitakeEffectOwner = ShiitakeEffectAgent & Readonly<{
+    /** Each Session's delivered tool grants, read at every call. */
+    grants: Readonly<{
+        /** Store one versioned delivery; versions only move forward. */
+        deliver: (sessionId: string, delivery: GrantsDelivery) => Effect.Effect<GrantsDeliveryResult, ShiitakeError>;
+        /** One Session's newest delivery; null when the host delivered none. */
+        read: (sessionId: string) => Effect.Effect<GrantsDelivery | null, ShiitakeError>;
+    }>;
+    /**
+     * The same Agent whose prompts and operator lines carry `meta`, checked
+     * against the host's metadata schema and stored beside each message.
+     */
+    withMeta: (meta: Json) => ShiitakeEffectAgent;
+}>;

package/dist/internal/effect-contracts.js

@@ -0,0 +1,2 @@
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";

package/dist/internal/extension-command-registry.d.ts

@@ -0,0 +1,11 @@
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import type { AdmissionError, CommandHandlersV0, CommandsV0, ExtensionCommandError, ExtensionRead, ExtensionStateError, ExtensionTx, Json } from "../extensions.js";
+/** A parsed invocation retains its typed handler until the transaction runs. */
+export type RegisteredExtensionCommandV0 = (frame: Readonly<{
+    sessionId: string | null;
+    input: Json;
+}>) => Result.Result<() => Effect.Effect<Json, ExtensionCommandError | ExtensionStateError | AdmissionError, ExtensionTx | ExtensionRead>, Schema.SchemaError>;
+/** Capture each declared command's schemas and matching handler at activation. */
+export declare function registerExtensionCommands<C extends CommandsV0>(specs: C, handlers: CommandHandlersV0<C>): ReadonlyMap<string, RegisteredExtensionCommandV0>;

package/dist/internal/extension-command-registry.js

@@ -0,0 +1,29 @@
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { invokeTransactionHook } from "./extension-hook.js";
+import { JsonValueSchema } from "./json-value.js";
+const sessionSchemas = {
+    agent: Schema.Null,
+    session: Schema.String,
+};
+function bindCommand(spec, handler) {
+    const session = sessionSchemas[spec.scope];
+    const decodeSession = Schema.decodeUnknownResult(session);
+    const decodeInput = Schema.decodeUnknownResult(spec.input, {
+        onExcessProperty: "error",
+    });
+    return (frame) => Result.flatMap(decodeSession(frame.sessionId), (sessionId) => Result.map(decodeInput(frame.input), (input) => () => invokeTransactionHook(() => handler({ sessionId, input })).pipe(Effect.flatMap((output) => Schema.encodeEffect(spec.output)(output).pipe(Effect.flatMap(Schema.decodeUnknownEffect(JsonValueSchema)), Effect.orDie)))));
+}
+/** Capture each declared command's schemas and matching handler at activation. */
+export function registerExtensionCommands(specs, handlers) {
+    const registry = new Map();
+    for (const name of Object.keys(handlers)) {
+        const spec = specs[name];
+        const handler = handlers[name];
+        if (spec === undefined || handler === undefined)
+            continue;
+        registry.set(name, bindCommand(spec, handler));
+    }
+    return registry;
+}

package/dist/internal/extension-command-tools.d.ts

@@ -0,0 +1,17 @@
+import type { OperationRegistration } from "@fungi.computer/mycelium";
+import type { CommandsV0, ExtensionContextV0, Json, RunIdentityV0 } from "../extensions.js";
+import type { RegisteredExtensionCommandV0 } from "./extension-command-registry.js";
+/** How one command appears to the model when exposed as a tool. */
+export type CommandToolOptionsV0 = Readonly<{
+    /** Discovery text for the model. */
+    description: string;
+}>;
+/** Expose declared commands as model tools, bound to the current run's Session. */
+export type CommandToolsV0<C extends CommandsV0> = Readonly<{
+    /** The named command as one Mycelium operation running the same handler. */
+    tool: (name: keyof C & string, options: CommandToolOptionsV0) => OperationRegistration;
+}>;
+/** Build the model-facing tool for each command, bound to one run. */
+export declare function commandTools<C extends CommandsV0>(specs: C | undefined, registered: () => ReadonlyMap<string, RegisteredExtensionCommandV0>, transact: ExtensionContextV0<Readonly<Record<never, never>>, Json>["transact"], run: RunIdentityV0, 
+/** Whether the host granted `commands`; the model door matches the member door. */
+granted: boolean): CommandToolsV0<C>;

package/dist/internal/extension-command-tools.js

@@ -0,0 +1,50 @@
+// The runtime-free entry keeps extensions bundleable into hosted isolates.
+import { Mycelium } from "@fungi.computer/mycelium/define";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { ShiitakeError } from "../errors.js";
+import { JsonValueSchema } from "./json-value.js";
+const decodeJson = Schema.decodeUnknownEffect(JsonValueSchema);
+/** Build the model-facing tool for each command, bound to one run. */
+export function commandTools(specs, registered, transact, run, 
+/** Whether the host granted `commands`; the model door matches the member door. */
+granted) {
+    return Object.freeze({
+        tool: (name, options) => {
+            const spec = specs?.[name];
+            if (spec === undefined)
+                throw new Error(`Extension declares no command named ${name}`);
+            // Mycelium owns the model-facing JSON (the codec's JSON form); the
+            // command door owns its wire form. Cross between them through the
+            // command's own codecs, then run the same registered handler.
+            const encodeInput = Schema.encodeUnknownEffect(spec.input);
+            const decodeOutput = Schema.decodeUnknownEffect(spec.output);
+            // A command is a write and declares no idempotency, so its tool is
+            // never replayed: replay is always "unsafe".
+            const commandOperation = Mycelium.operation({
+                description: options.description,
+                replay: "unsafe",
+                input: spec.input,
+                output: spec.output,
+                execute: (input) => Effect.runPromise(Effect.gen(function* () {
+                    if (!granted)
+                        return yield* Effect.fail(new ShiitakeError("extensions", "unavailable", "Extension is unavailable"));
+                    const command = registered().get(name);
+                    if (command === undefined)
+                        return yield* Effect.die(new Error(`Command ${name} has no handler`));
+                    const wire = yield* encodeInput(input).pipe(Effect.flatMap(decodeJson));
+                    const invocation = command({
+                        sessionId: spec.scope === "session" ? run.sessionId : null,
+                        input: wire,
+                    });
+                    if (Result.isFailure(invocation))
+                        return yield* Effect.fail(invocation.failure);
+                    const output = yield* transact(invocation.success());
+                    return yield* decodeOutput(output);
+                })),
+            });
+            return commandOperation;
+        },
+    });
+}

package/dist/internal/extension-context.d.ts

@@ -0,0 +1,25 @@
+import type { EmptyExtensionFieldsV0, CollectionSpecV0, CollectionsV0, CollectionV0, ExtensionContextV0, Json, StateHandleV0, UpdateCollectionV0 } from "../extensions.js";
+import type { DocumentsV0, DocumentSpecV0, DocumentHandleV0, DocumentHandlesV0 } from "../session-documents.js";
+/** Core retains only these erased results; the author retains each concrete factory. */
+export type CollectionBindingV0 = Readonly<{
+    read: Omit<CollectionV0<unknown>, "put"> & Pick<CollectionV0<never>, "put">;
+    update: Omit<UpdateCollectionV0<unknown>, "put"> & Pick<UpdateCollectionV0<never>, "put">;
+}>;
+/** State operations capture their typed declaration before entering core. */
+export type ExtensionRuntimePortV0 = Readonly<{
+    context: Omit<ExtensionContextV0<EmptyExtensionFieldsV0, Json, EmptyExtensionFieldsV0>, "config" | "state" | "documents">;
+    /** Build read/write operations for the declaring collection and schema. */
+    collection: <A, I>(name: string, spec: CollectionSpecV0<A, I>) => CollectionV0<A>;
+    /** Build synchronous operations guarded by the owner's state transaction. */
+    updateCollection: <A, I>(name: string, spec: CollectionSpecV0<A, I>) => UpdateCollectionV0<A>;
+    /** Build a Session document handle using its own codec and byte bound. */
+    document: <A, I>(name: string, spec: DocumentSpecV0<A, I>) => DocumentHandleV0<A>;
+    /** Execute a synchronous mutation in the declaring extension's transaction. */
+    update: <A>(body: () => A) => A;
+    /** Publish a Session only after its state mutation commits. */
+    observeUpdate: (sessionId: string) => void;
+}>;
+/** Each collection factory is new even when two names share the same declaration. */
+export declare function bindExtensionState<S extends CollectionsV0>(collections: S, port: ExtensionRuntimePortV0): StateHandleV0<S>;
+/** Capture the document codec before handing its name to the runtime. */
+export declare function bindExtensionDocuments<D extends DocumentsV0>(documents: D, port: ExtensionRuntimePortV0): DocumentHandlesV0<D>;

package/dist/internal/extension-context.js

@@ -0,0 +1,35 @@
+import * as Struct from "effect/Struct";
+import { invokeSyncHandler } from "./extension-hook.js";
+function invokeNamedFactories(factories) {
+    const names = new WeakMap();
+    for (const [name, factory] of Object.entries(factories))
+        names.set(factory, name);
+    return Struct.map(factories, Struct.lambda((factory) => {
+        const name = names.get(factory);
+        if (name === undefined)
+            throw new Error("Extension handle factory is not registered");
+        return factory(name);
+    }));
+}
+/** Each collection factory is new even when two names share the same declaration. */
+export function bindExtensionState(collections, port) {
+    const factories = Struct.map(collections, Struct.lambda((spec) => (name) => spec.bind(port, name)));
+    const bindings = invokeNamedFactories(factories);
+    const state = Struct.map(bindings, Struct.lambda((binding) => binding.read));
+    const updateState = Object.freeze({
+        ...Struct.map(bindings, Struct.lambda((binding) => binding.update)),
+        observe: port.observeUpdate,
+    });
+    // A separate frozen view: `read` must not be able to write.
+    const readState = Object.freeze(Struct.map(bindings, Struct.lambda((binding) => Object.freeze({ get: binding.update.get, page: binding.update.page }))));
+    return Object.freeze({
+        ...state,
+        /** Execute a synchronous mutation in the declaring extension's transaction. */
+        update: (handler) => port.update(() => invokeSyncHandler(handler, updateState)),
+        read: (handler) => port.update(() => invokeSyncHandler(handler, readState)),
+    });
+}
+/** Capture the document codec before handing its name to the runtime. */
+export function bindExtensionDocuments(documents, port) {
+    return Object.freeze(invokeNamedFactories(Struct.map(documents, Struct.lambda((spec) => (name) => port.document(name, spec)))));
+}

package/dist/internal/extension-definitions.d.ts

@@ -0,0 +1,5 @@
+import type { AnyExtensionDefinitionV0, RosteredExtensionV0 } from "../extensions.js";
+/** The typed reader remains usable across two loaded copies of Shiitake. */
+export declare const definitionReader: unique symbol;
+/** Read the definition captured when the author registered this roster entry. */
+export declare function readDefinition(rostered: RosteredExtensionV0): AnyExtensionDefinitionV0 | undefined;

package/dist/internal/extension-definitions.js

@@ -0,0 +1,6 @@
+/** The typed reader remains usable across two loaded copies of Shiitake. */
+export const definitionReader = Symbol.for("@fungi.computer/shiitake/extension-definition-reader");
+/** Read the definition captured when the author registered this roster entry. */
+export function readDefinition(rostered) {
+    return rostered[definitionReader]?.();
+}

package/dist/internal/extension-hook.d.ts

@@ -0,0 +1,25 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+declare const ExtensionHookError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ExtensionHookError";
+} & Readonly<A>;
+/** An outside handler rejected or threw before Shiitake could use its result. */
+export declare class ExtensionHookError extends ExtensionHookError_base<{
+    cause: unknown;
+}> {
+}
+/** Lift an outside handler once, outside any synchronous write transaction. */
+export declare function invokeExtensionHook<A, E = never, R = never>(handler: () => A | Promise<A> | Effect.Effect<A, E, R>): Effect.Effect<A, E | ExtensionHookError, R>;
+/** A write callback must resolve before the owner commits its SQLite transaction. */
+export type SyncResult<A> = A extends Option.Option<unknown> ? A : A extends Promise<unknown> | Effect.Effect<unknown, unknown, unknown> ? never : A;
+/** Public state-update shape: infer the return *before* rejecting async results. */
+export type StateUpdate<Tx> = <A>(handler: (tx: Tx) => SyncResult<A>) => A;
+/** Raised before SQLite commits when an untyped handler returns async work. */
+export declare class AsyncExtensionTransactionError extends Error {
+    constructor();
+}
+/** Reject a runtime-invalid handler before the surrounding transaction commits. */
+export declare function invokeSyncHandler<Tx, A>(handler: (tx: Tx) => A, tx: Tx): A;
+/** Adapt a synchronous callback or a synchronously executed Effect to the owner transaction. */
+export declare function invokeTransactionHook<A, E, R>(handler: () => A | Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
+export {};

package/dist/internal/extension-hook.js

@@ -0,0 +1,46 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+/** An outside handler rejected or threw before Shiitake could use its result. */
+export class ExtensionHookError extends Data.TaggedError("ExtensionHookError") {
+}
+/** Lift an outside handler once, outside any synchronous write transaction. */
+export function invokeExtensionHook(handler) {
+    return Effect.suspend(() => {
+        const result = handler();
+        if (Effect.isEffect(result))
+            return result;
+        return Effect.tryPromise({
+            try: () => Promise.resolve(result),
+            catch: (cause) => new ExtensionHookError({ cause }),
+        });
+    });
+}
+/** Raised before SQLite commits when an untyped handler returns async work. */
+export class AsyncExtensionTransactionError extends Error {
+    constructor() {
+        super("Extension transaction handler must return synchronously");
+        this.name = "AsyncExtensionTransactionError";
+    }
+}
+/** Reject a runtime-invalid handler before the surrounding transaction commits. */
+export function invokeSyncHandler(handler, tx) {
+    const value = handler(tx);
+    if (value instanceof Promise ||
+        (Effect.isEffect(value) && !Option.isOption(value)))
+        throw new AsyncExtensionTransactionError();
+    return value;
+}
+/** Adapt a synchronous callback or a synchronously executed Effect to the owner transaction. */
+export function invokeTransactionHook(handler) {
+    return Effect.suspend(() => {
+        const result = handler();
+        if (result instanceof Promise)
+            throw new AsyncExtensionTransactionError();
+        if (Option.isOption(result))
+            return Effect.succeed(result);
+        if (Effect.isEffect(result))
+            return result;
+        return Effect.succeed(result);
+    });
+}

package/dist/internal/extension-roster.d.ts

@@ -0,0 +1,23 @@
+import type { DocumentsV0 } from "../session-documents.js";
+import * as Effect from "effect/Effect";
+import { ShiitakeError } from "../errors.js";
+import type { AnyExtensionDefinitionV0, ExtensionCapabilityV0, ExtensionFingerprint, ExtensionId, ExtensionManifestV0, ExtensionRosterV0, ExtensionRevision } from "../extensions.js";
+/** One validated roster member with its core-derived identity. */
+export type AdmittedExtensionV0 = Readonly<{
+    id: ExtensionId;
+    manifest: ExtensionManifestV0;
+    definition: AnyExtensionDefinitionV0;
+    documents: DocumentsV0;
+    grants: ReadonlySet<ExtensionCapabilityV0>;
+    revision: ExtensionRevision;
+    fingerprint: ExtensionFingerprint;
+}>;
+/** Validate a host roster and grants, then derive each revision and fingerprint. */
+export declare function admitExtensionRosterV0(input: ExtensionRosterV0 | undefined): Effect.Effect<readonly AdmittedExtensionV0[], ShiitakeError>;
+/**
+ * Hex digest of the core run protocol a run is admitted under, plus the
+ * captured Files direct-tool names. It changes when core's
+ * run-contract semantics change or the Files tool set changes, never with a
+ * roster: the branded Files names are captured separately from fingerprints.
+ */
+export declare function coreProtocolDigest(fileToolNames: readonly string[]): Effect.Effect<string, ShiitakeError>;