stitchkit 0.103.12 → 0.104.0

package/dist/tools/runtime-tool.d.ts

@@ -1,71 +1,20 @@
-import type { CallToolResult } from '@modelcontextprotocol/server';
 import type { Tool } from 'ai';
 import type { ZodObject, ZodType, z } from 'zod';
-import type { HttpMethod, ToolTransport } from '../contract/define.js';
-import type { McpCallContext, RuntimeContext } from '../contract/runtime-context.js';
-import type { EndpointMcpPolicy, EndpointToolAnnotations, EndpointUiMeta } from '../contract/tool-options.js';
-import type { LocalStepDurability } from '../durability/contract.js';
+import type { HttpMethod } from '../contract/define.js';
+import type { EndpointMcpPolicy } from '../contract/tool-options.js';
 import { type SurfaceAgentRuntimeToolDefinition } from './internal/surface-projector.js';
 import type { MountableTool } from './mount.js';
-export interface RuntimeToolIdentity {
-    serviceName: string;
-    action: string;
-    scope?: string;
-    /** Semantic operation verb for lifecycle and RequestEvent attribution. */
-    method: HttpMethod;
-    meta?: Record<string, unknown>;
-}
-export type RuntimeMcpInput<TMcp extends EndpointMcpPolicy | undefined> = TMcp extends EndpointMcpPolicy<infer TRequests> ? {
-    mcpInput?: {
-        [Request in TRequests[number] as Request['key']]: z.output<Request['schema']>;
-    };
-} : unknown;
-export type RuntimeToolHandlerContext<TInput extends ZodObject, TMcp extends EndpointMcpPolicy | undefined = undefined> = RuntimeContext & {
-    params: undefined;
-    input: z.output<TInput>;
-    step?: LocalStepDurability['step'];
-    sleep?: LocalStepDurability['sleep'];
-    waitFor?: LocalStepDurability['waitFor'];
-} & RuntimeMcpInput<TMcp>;
-export type RuntimeToolOutput<TOutput extends ZodType | undefined> = TOutput extends ZodType ? z.output<TOutput> : undefined;
-/** Parsed application context plus the canonical runtime-tool input fields. */
-export type RuntimeToolFactoryHandlerContext<TContext extends ZodObject, TInput extends ZodObject, TMcp extends EndpointMcpPolicy | undefined = undefined> = Omit<RuntimeContext, 'input' | 'params' | 'mcp'> & Omit<z.output<TContext>, 'input' | 'params' | 'mcp'> & {
-    params: undefined;
-    input: z.output<TInput>;
-    mcp?: McpCallContext;
-} & RuntimeMcpInput<TMcp>;
-/** MCP-owned fields; validation and error state are always supplied by Stitchkit. */
-export type RuntimeMcpPresentation = Omit<CallToolResult, 'structuredContent' | 'isError'> & {
-    structuredContent?: never;
-    isError?: never;
-};
+import type { RuntimeToolDefinitionWithoutOutput, RuntimeToolExecution, RuntimeToolExecutionWithOutput, RuntimeToolFactoryHandlerContext } from './runtime-tool-execution.js';
+import type { RuntimeMcpToolPresenters } from './runtime-tool-mcp.js';
+export type { RuntimeMcpInput, RuntimeToolDefinitionBase, RuntimeToolDefinitionWithoutOutput, RuntimeToolFactoryHandlerContext, RuntimeToolHandlerContext, RuntimeToolIdentity, RuntimeToolOutput, } from './runtime-tool-execution.js';
+export type { RuntimeMcpPresentation } from './runtime-tool-mcp.js';
 export type RuntimeAgentModelOutput = Awaited<ReturnType<NonNullable<Tool<unknown, unknown>['toModelOutput']>>>;
-export interface RuntimeToolPresenters<TOutput> {
-    mcp?: (output: TOutput) => RuntimeMcpPresentation | Promise<RuntimeMcpPresentation>;
+export interface RuntimeToolPresenters<TOutput> extends RuntimeMcpToolPresenters<TOutput> {
     agent?: (output: TOutput) => RuntimeAgentModelOutput | PromiseLike<RuntimeAgentModelOutput>;
 }
-export interface RuntimeToolDefinitionBase<TInput extends ZodObject, TMcp extends EndpointMcpPolicy | undefined = undefined> {
-    name: string;
-    description: string;
-    identity: RuntimeToolIdentity;
-    input: TInput;
-    /** Default: MCP and AGENT. CLI is always explicit opt-in. */
-    transports?: readonly ToolTransport[];
-    annotations?: EndpointToolAnnotations;
-    ui?: EndpointUiMeta;
-    /** Opt-in multi-round input gate on the MCP transport only. */
-    mcp?: TMcp;
-}
-export interface RuntimeToolDefinitionWithOutput<TInput extends ZodObject, TOutput extends ZodType, TMcp extends EndpointMcpPolicy | undefined = undefined> extends RuntimeToolDefinitionBase<TInput, TMcp> {
-    output: TOutput;
-    handler: (context: RuntimeToolHandlerContext<TInput, TMcp>) => z.output<TOutput> | Promise<z.output<TOutput>>;
+export interface RuntimeToolDefinitionWithOutput<TInput extends ZodObject, TOutput extends ZodType, TMcp extends EndpointMcpPolicy | undefined = undefined> extends RuntimeToolExecutionWithOutput<TInput, TOutput, TMcp> {
     present?: RuntimeToolPresenters<z.output<TOutput>>;
 }
-export interface RuntimeToolDefinitionWithoutOutput<TInput extends ZodObject, TMcp extends EndpointMcpPolicy | undefined = undefined> extends RuntimeToolDefinitionBase<TInput, TMcp> {
-    output?: never;
-    handler: (context: RuntimeToolHandlerContext<TInput, TMcp>) => void | Promise<void>;
-    present?: never;
-}
 export type RuntimeToolDefinition = RuntimeToolDefinitionWithOutput<ZodObject, ZodType, EndpointMcpPolicy | undefined> | RuntimeToolDefinitionWithoutOutput<ZodObject, EndpointMcpPolicy | undefined>;
 export interface RuntimeToolFactoryConfig<TContext extends ZodObject> {
     serviceName: string;
@@ -96,7 +45,7 @@ export declare function defineRuntimeTool<TInput extends ZodObject, const TMcp e
  * call while keeping execution in the canonical tool runner.
  */
 export declare function createRuntimeToolFactory<TContext extends ZodObject>(config: RuntimeToolFactoryConfig<TContext>): RuntimeToolFactory<TContext>;
-export declare function runtimeToolMountable(definition: RuntimeToolDefinition, assertName?: boolean): MountableTool;
+export declare function runtimeToolMountable(definition: RuntimeToolExecution, assertName?: boolean): MountableTool;
 /**
  * Agent-only public declarations use a peer-free structural tool definition.
  * Construction validates executable functions before this boundary restores

package/dist/tools/runtime-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-tool.d.ts","sourceRoot":"","sources":["../../src/tools/runtime-tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime-tool.d.ts","sourceRoot":"","sources":["../../src/tools/runtime-tool.ts"],"names":[],"mappings":"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"}

package/dist/tools/surface.d.ts

@@ -1,35 +1,33 @@
 import type { ToolTransport } from '../contract/define.js';
-import type { ServiceDef } from '../server/types.js';
-import { type ProjectedTool } from './internal/surface-projector.js';
+import { type ProjectedTool, type ToolSurfaceProjection } from './internal/surface-projector.js';
 import { type CollectToolsConfig, type MountableTool } from './mount.js';
 import { type RuntimeToolDefinition } from './runtime-tool.js';
+import type { RuntimeToolExecution } from './runtime-tool-execution.js';
 /** Contract and pathless runtime operations that form one tool surface. */
-export interface ToolSurfaceDefinition {
-    services?: readonly ServiceDef[];
-    runtimeTools?: readonly RuntimeToolDefinition[];
+export interface ToolSurfaceDefinition<TRuntime extends RuntimeToolExecution = RuntimeToolDefinition> extends ToolSurfaceProjection<TRuntime> {
 }
-interface CollectedContractTool {
+interface CollectedContractTool<TRuntime extends RuntimeToolExecution> {
     kind: 'contract';
     service: string;
     action: string;
     mountable: MountableTool;
-    projection: Extract<ProjectedTool<RuntimeToolDefinition>, {
+    projection: Extract<ProjectedTool<TRuntime>, {
         kind: 'contract';
     }>;
 }
-interface CollectedRuntimeTool {
+interface CollectedRuntimeTool<TRuntime extends RuntimeToolExecution> {
     kind: 'runtime';
     service: string;
     action: string;
     mountable: MountableTool;
-    definition: RuntimeToolDefinition;
-    projection: Extract<ProjectedTool<RuntimeToolDefinition>, {
+    definition: TRuntime;
+    projection: Extract<ProjectedTool<TRuntime>, {
         kind: 'runtime';
     }>;
 }
-export type CollectedToolSurfaceEntry = CollectedContractTool | CollectedRuntimeTool;
-export interface CollectToolSurfaceConfig extends CollectToolsConfig {
-    surface: ToolSurfaceDefinition;
+export type CollectedToolSurfaceEntry<TRuntime extends RuntimeToolExecution = RuntimeToolDefinition> = CollectedContractTool<TRuntime> | CollectedRuntimeTool<TRuntime>;
+export interface CollectToolSurfaceConfig<TRuntime extends RuntimeToolExecution = RuntimeToolDefinition> extends CollectToolsConfig {
+    surface: ToolSurfaceDefinition<TRuntime>;
     transport: ToolTransport;
     /** Diagnostics disable this so they can report a broken surface. Default: true. */
     assertUniqueNames?: boolean;
@@ -38,6 +36,6 @@ export interface CollectToolSurfaceConfig extends CollectToolsConfig {
  * Resolve contracts and runtime definitions in their real mount order through
  * the same name, exposure and presentation-schema machinery as the mounts.
  */
-export declare function collectToolSurface({ surface, transport, assertUniqueNames, ...collectConfig }: CollectToolSurfaceConfig): CollectedToolSurfaceEntry[];
+export declare function collectToolSurface<TRuntime extends RuntimeToolExecution>({ surface, transport, assertUniqueNames, ...collectConfig }: CollectToolSurfaceConfig<TRuntime>): CollectedToolSurfaceEntry<TRuntime>[];
 export {};
 //# sourceMappingURL=surface.d.ts.map

package/dist/tools/surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../src/tools/surface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,8BAA8B,CAAC;AACtF,OAAO,EAAE,KAAK,kBAAkB,EAAyB,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,KAAK,qBAAqB,EAAwB,MAAM,gBAAgB,CAAC;AAElF,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD;AAED,UAAU,qBAAqB;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,qBAAqB,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;CACjF;AAED,UAAU,oBAAoB;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;IACzB,UAAU,EAAE,qBAAqB,CAAC;IAClC,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,qBAAqB,CAAC,EAAE;QAAE,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;CAChF;AAED,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,GAAG,oBAAoB,CAAC;AAErF,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IAClE,OAAO,EAAE,qBAAqB,CAAC;IAC/B,SAAS,EAAE,aAAa,CAAC;IACzB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,OAAO,EACP,SAAS,EACT,iBAAwB,EACxB,GAAG,aAAa,EACjB,EAAE,wBAAwB,GAAG,yBAAyB,EAAE,CAkCxD"}
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../src/tools/surface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,KAAK,aAAa,EAElB,KAAK,qBAAqB,EAC3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,KAAK,kBAAkB,EAAyB,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,KAAK,qBAAqB,EAAwB,MAAM,gBAAgB,CAAC;AAClF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB,CACpC,QAAQ,SAAS,oBAAoB,GAAG,qBAAqB,CAC7D,SAAQ,qBAAqB,CAAC,QAAQ,CAAC;CAAG;AAE5C,UAAU,qBAAqB,CAAC,QAAQ,SAAS,oBAAoB;IACnE,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;CACpE;AAED,UAAU,oBAAoB,CAAC,QAAQ,SAAS,oBAAoB;IAClE,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;IACzB,UAAU,EAAE,QAAQ,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;CACnE;AAED,MAAM,MAAM,yBAAyB,CACnC,QAAQ,SAAS,oBAAoB,GAAG,qBAAqB,IAC3D,qBAAqB,CAAC,QAAQ,CAAC,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;AAErE,MAAM,WAAW,wBAAwB,CACvC,QAAQ,SAAS,oBAAoB,GAAG,qBAAqB,CAC7D,SAAQ,kBAAkB;IAC1B,OAAO,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACzC,SAAS,EAAE,aAAa,CAAC;IACzB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,SAAS,oBAAoB,EAAE,EACxE,OAAO,EACP,SAAS,EACT,iBAAwB,EACxB,GAAG,aAAa,EACjB,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAAG,yBAAyB,CAAC,QAAQ,CAAC,EAAE,CAkC5E"}

package/llms/application.2.txt

@@ -122,49 +122,101 @@ deadline holds `stop()` — and so the resource's `force()` — for that one cal
 so give the transport a timeout. Superseding a key that is being sent right now
 does not recall it: the send completes, and only its receipt is not written.
 
-`createDirectoryInbox` is the receiving side for another program on the same
-host: it drops entries — a release transition, say — into a directory, and
-the application takes each one at least once. It is a managed resource of its
-own (`createDirectoryInbox({ id, directory, schema, handle })`, imported from
-`stitchkit/application/directory-inbox` because it touches files; its types
-and schemas are in `stitchkit/application`) and publishes a handle with
-`flush()` and `state()`. The producer writes each entry
-atomically as `<name>.json` — a temporary name, then a rename; names that start
-with a dot are never read. Entries are delivered in name order, and only after
-`activate`: none reaches the application before it is ready. `stopAdmission`
-stops taking new ones, `drain` waits for the one in flight, and `force` aborts
-the `signal` its handler was given.
-
-Taken and done are separate durable records. Before `handle` runs, the entry
-is claimed with a lease (`leaseMs`, default five minutes); after it returns,
-a receipt replaces the claim and only then is the file removed. A process that
-died mid-delivery leaves a claim, and the entry is taken again once the lease
-runs out — at least once, not exactly once, so a handler that sends somewhere
-should carry the entry's `key` as its idempotency key. A process that died
-after the receipt leaves only the file, which the next pass removes without
-delivering it again. A handler that throws is retried after a backoff from one
-second doubling to five minutes; an entry that fails `schema`, is over
-`maxEntryBytes` or was taken `maxAttempts` times (default 20 — the count
-survives restarts, so an entry whose handling kills the process is not taken
-forever) is moved to `rejected/` with its reason and reported to `onRejected`,
-and the entries after it keep flowing. The state lives in
-`<directory>/.inbox-state.json` under `createFileStateStore`'s inter-process
-lock unless a `store` is supplied.
-
-These primitives depend on the structural `StateStore`. On a server,
-`createFileStateStore` supplies the shared Zod-validated JSON adapter with an
-inter-process lock, unique temporary file, fsync and atomic rename. The lock
-is a file with a heartbeat: the holder refreshes its mtime every third of
-`staleLockMs` (default 3 s), a contender waits up to `lockTimeoutMs` (default
-10 s), and the stale bound must sit inside the timeout — otherwise a crashed
-holder blocks every update until the lock ages out, which the constructor
-refuses. A lock whose heartbeat is stale is reclaimed once its recorded pid is
-gone; a live or unverifiable pid (a reused number, another user's process)
-keeps it for ten stale bounds — and never fewer than thirty missed heartbeats,
-so a scheduler stall on a loaded host cannot pull a live lock from under its
-holder — after which the heartbeat wins and the lock is abandoned. Temporary files a crashed writer left beside the state are swept on
-the store's first update. Ledger corruption may be declared reconstructable;
-an outbox must fail closed rather than silently discard pending delivery.
+`createDirectoryInbox` receives entries from another program on the same host,
+or directly from a transport adapter. Import the resource from
+`stitchkit/application/directory-inbox`; its contracts live in
+`stitchkit/application`. Its published handle has `accept({ source, key, entry })`,
+`flush()` and `state()`:
+
+```ts
+const inbox = createDirectoryInbox({
+  id: 'updates',
+  directory: env.INBOX_DIRECTORY,
+  schema: UpdateSchema,
+  handle: ({ identity, entry, signal }) => processUpdate(identity, entry, signal),
+})
+const ingress = defineManagedResource({
+  id: 'ingress',
+  dependsOn: [inbox],
+  start(context) {
+    const intake = context.use(inbox)
+    return { value: (key: string, entry: Update) =>
+      intake.accept({ source: 'client-updates', key, entry }) }
+  },
+})
+```
+
+`accept` is available after the resource starts, including before activation.
+It validates the entry and full producer identity, writes a lossless JSON envelope,
+syncs its file and parent directory, then returns
+`{ status: 'accepted' | 'duplicate', filename }`. Automatic delivery starts at
+`activate`; an explicit `flush()` is available before activation. A producer
+should acknowledge its provider only after acceptance resolves. Failure after
+publication can mean the entry was accepted but its acknowledgement was lost:
+retry the same identity, and `duplicate` keeps the original payload.
+
+The identity is the pair `source` (1–128 characters) and `key` (1–1024 characters).
+A hash of the pair names the file; the full pair is retained inside its envelope
+and checked against existing files and records. Two sources may use the same key.
+The handler's legacy `key` remains the filename; programmatic entries additionally
+carry `identity`. No Telegram numeric update id or MTProto event shape is invented.
+
+The default `maxPendingEntries: 1000` refuses new programmatic entries when the
+pending directory is full, without publishing another file; duplicate acceptance
+still succeeds. `maxEntryBytes` defaults to 1 MiB and counts the complete UTF-8
+envelope. A completed identity is deduplicated while its receipt is retained
+(`retain`, default 1000); a rejected envelope also deduplicates while its file
+remains in `rejected/`. Choose the retention and rejected-file cleanup policy to
+match the provider's replay window. Provider cursors, identity extraction and
+external-effect idempotency remain application responsibilities.
+
+The original file-producer path also remains: atomically publish
+`<name>.json`, using a temporary name followed by a rename. Names starting with
+a dot are ignored; `intake-<64 hex characters>.json` is reserved for programmatic
+envelopes. Entries are delivered in filename order. The reader refuses unsafe
+leaf symlinks, multiple links and files changed during reading.
+`stopAdmission` stops new acceptance and delivery, `drain` waits for accepted
+storage operations and the handler in flight, and `force` aborts its handler
+signal. A handler ignoring that signal may still finish an external effect;
+the inbox leaves its entry unsettled rather than claiming it was cancelled.
+
+Taken and done are separate durable records. Before `handle`, the entry is
+claimed with a unique expiring lease (`leaseMs`, default five minutes). A
+long handler renews that lease; an expired or replaced lease cannot complete,
+reject, retry or remove the successor's file. Success first commits a receipt,
+then removes only that file generation under a new protected transaction.
+A crash after receipt commit is recovered by cleanup without redelivery. A crash
+before receipt commit may redeliver: the guarantee is at least once, so use the
+full producer identity as the external idempotency key.
+
+A throwing handler retries after a backoff from one second to five minutes.
+Schema failures, oversize files and `maxAttempts` exhaustion (default 20) are
+recorded before their files move to `rejected/`, with `onRejected` reporting the
+reason. The state defaults to `<directory>/.inbox-state.json`, or uses the supplied
+`store`. Manual file producers are responsible for atomic publication and capacity.
+
+These primitives share the structural `StateStore`. `update` owns one atomic
+read/modify/write transaction and passes a `StateStoreUpdateContext` as the
+transition's second argument. Its `await context.assertHeld()` checks that the
+transaction is still active and its exclusive generation is still owned. A custom
+store must implement both real serialization/atomic commit and this guard;
+a no-op guard does not satisfy the contract. Ordinary one-argument transition
+callbacks remain valid.
+
+On a server, `createFileStateStore` uses the same process-instance lock as
+`withExclusiveLock`, unique staging files and atomic directory-durable publication.
+`lockTimeoutMs` (default 10 s, zero means one attempt) bounds acquisition only.
+A live or unattributable owner is never replaced by age, including after an event
+loop stall or `SIGSTOP`; only a provably dead local process instance is reclaimed.
+Legacy readable pid/token records without a host are unknown owners and need
+operator recovery after the old writer is verified stopped.
+
+`staleLockMs` and `retryMs` are removed and are refused at runtime. The current
+write removes its own staging file; unknown historical temporary files are
+preserved, without an age sweep. Directory durability requires a filesystem
+supporting directory sync (Linux and macOS); Windows is refused explicitly.
+Ledger corruption may be declared reconstructable; an outbox must fail closed
+rather than discard pending delivery.
 
 ## Recovering change subscriptions
 
@@ -232,7 +284,7 @@ description: Executable patterns for moving database, poller, queue and operatio
 type: architecture
 status: active
 created: 2026-08-24
-updated: 2026-08-24
+updated: 2026-10-04 13:28 +07:00
 ---
 
 # Application migration recipes
@@ -266,6 +318,131 @@ The application still owns the client, ORM configuration, transactions,
 migrations and reconnect policy. The executable recipe deliberately fails after
 allocation and proves one rollback close.
 
+## Stateful clients, including MTProto
+
+An application-owned client is an ordinary managed resource. Keep SDK creation,
+credentials, authorization and reconnect policy in the application; no Telegram
+client SDK is required by Stitchkit. Create a fresh client inside each `start`,
+publish it after connection/readiness succeeds, and share one memoized destroy
+promise between partial-start cleanup, `close` and `force`:
+
+```ts
+let generation: { destroy(): Promise<void> } | undefined
+
+const client = defineManagedResource({
+  id: 'client',
+  async start({ signal }) {
+    const connection = createClient() // Your SDK and configuration.
+    let destruction: Promise<void> | undefined
+    const destroy = () => destruction ??= Promise.resolve()
+      .then(() => connection.destroy())
+    generation = { destroy }
+    let ready = false
+    let startFailure: unknown
+    let startFailed = false
+    let cleanupFailure: unknown
+    let cleanupFailed = false
+    try {
+      await connection.connect(signal)
+      await connection.assertReady()
+      signal.throwIfAborted()
+      ready = true
+    } catch (error) {
+      startFailure = error
+      startFailed = true
+    } finally {
+      if (!ready) {
+        try { await destroy() }
+        catch (cleanup) {
+          cleanupFailure = cleanup
+          cleanupFailed = true
+        }
+      }
+    }
+    if (startFailed) {
+      if (cleanupFailed) throw new AggregateError([startFailure, cleanupFailure],
+        'Client startup and cleanup failed', { cause: startFailure })
+      throw startFailure
+    }
+    return { value: connection }
+  },
+  close: () => generation?.destroy(),
+  force: () => generation?.destroy(),
+})
+
+const api = defineManagedResource({
+  id: 'api',
+  dependsOn: [client],
+  start(context) {
+    const connection = context.use(client)
+    return { value: async () => {
+      const lease = context.admission.acquire()
+      if (!lease) throw new ApplicationAdmissionError()
+      try { return await connection.invoke() }
+      finally { lease.release() }
+    } }
+  },
+})
+```
+
+`createClient` supplies a client whose `destroy` safely cleans partial connection
+setup; its adapter must honor cancellation or otherwise reconcile late SDK effects.
+The destroy cache belongs to one generation and is reset by the next `start`.
+Successful startup keeps the connection alive. Dependants start after readiness,
+requests acquire admission before invoking the client, and dependent HTTP resources
+close before the client. A subtree restart builds a new client and new dependants.
+
+The packed-consumer fixture
+[`managed-client-composition.mjs`](../../packages/core/scripts/consumer-lane/fixtures/minimal/src/managed-client-composition.mjs)
+proves readiness/admission, partial startup, close order, forced cleanup and restart
+with a fake client on Bun and Node. It does not claim a live provider acceptance test.
+
+## Custom StateStore transaction guards
+
+Transitions now receive `(current, context)`. Keep ordinary callbacks that only use
+`current`; update custom store implementations to pass a real protected context.
+For an in-memory test store, queue transactions and invalidate the context when
+the transaction finishes:
+
+```ts
+function memoryStore<T>(): StateStore<T> {
+  let state: T | null = null
+  let tail: Promise<unknown> = Promise.resolve()
+  return {
+    read: async () => state,
+    update(transition) {
+      const work = tail.then(async () => {
+        let active = true
+        const context: StateStoreUpdateContext = {
+          async assertHeld() {
+            if (!active) throw new Error('Transaction is no longer active')
+          },
+        }
+        try {
+          const next = await transition(state, context)
+          await context.assertHeld()
+          state = next.state
+          return next.result
+        } finally { active = false }
+      })
+      tail = work.catch(() => undefined)
+      return work
+    },
+  }
+}
+```
+
+This recipe is process-local and has no restart durability. A database store must
+guard its real transaction/generation and commit atomically; an escaped or lost
+guard must refuse. Filesystem mutations made inside inbox transactions call
+`assertHeld` immediately before publication or cleanup.
+
+For `createFileStateStore`, remove `staleLockMs` and `retryMs` from configuration.
+`lockTimeoutMs` remains the acquisition budget. Timestamp age no longer revokes
+a live or unknown writer. Stop and verify old writers before recovering a legacy
+pid-only lock; do not invent owner metadata. Historical temporary files are no
+longer deleted by age. See the [durable intake contract](application-kernel.md#durable-process-facts-and-owner-notifications).
+
 ## Long-running poller
 
 Return separate readiness and completion promises. Readiness says dependants may

package/llms/application.3.txt

@@ -36,7 +36,9 @@ cutovers are covered by the executable
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
 | `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
 | `notificationOutboxResource` / `NotificationOutboxResource` / `NotificationOutboxResourceConfig` | function / _type_ | thin managed-resource scheduler over an outbox handle |
-| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | managed resource delivering each `<name>.json` entry another program drops into a directory to the application at least once, after readiness; separate durable taken/done records, leases, bounded retry |
+| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | one managed directory inbox for files or durable `accept({ source, key, entry })`; first payload wins, bounded capacity/bytes/receipts and renewable fenced leases; delivery begins after readiness and effects remain at least once |
+| `DirectoryInboxIdentitySchema` / `DirectoryInboxIdentity` / `DirectoryInboxAccept` / `DirectoryInboxAcceptResultSchema` / `DirectoryInboxAcceptResult` | schema / _type_ | validated source/key, typed entry and durable accepted/duplicate result with filename; duplicates do not replace the first payload |
+| `StateStoreUpdateContext` | _type_ | real active protected transaction: `assertHeld()` refuses after ownership loss or completion; custom adapters supply this context to their transition |
 | `DirectoryInboxStateSchema` / `DirectoryInboxState` / `DirectoryInboxRejection` / `DirectoryInboxRejectionReasonSchema` / `DirectoryInboxRejectionReason` | schema / _type_ | the inbox's claims, receipts and rejections (`invalid`, `too-large`, `attempt-limit`) |
 | `ApplicationHandle.restart` | method | replace one resource and everything that depends on it, leaving the rest of the graph running and the process epoch unchanged |
 | `ApplicationRestartInputSchema` / `ApplicationRestartInput` | schema / _type_ | the resource to replace, by id, and optionally `gracePeriodMs` / `forceTimeoutMs` for this restart — the application's own shutdown budget otherwise |

package/llms/application.txt

@@ -19,7 +19,7 @@ description: Compose process-local resources, schedules, readiness, drain and op
 type: architecture
 status: active
 created: 2026-08-23
-updated: 2026-09-30 17:41 +07:00
+updated: 2026-10-04 13:28 +07:00
 ---
 
 # Managed application kernel