stitchkit 0.94.1 → 0.95.1

package/dist/entrypoints/server.js

@@ -21,6 +21,9 @@ import {
   webSocketLane
 } from "../index-p3vsv1fb.js";
 import"../index-y91ry9h2.js";
+import {
+  createFileStateStore
+} from "../index-tm88avnj.js";
 import {
   withDeadline
 } from "../index-b9aefrqd.js";
@@ -113,222 +116,6 @@ import {
 import {
   isRecord
 } from "../index-hffjpmq9.js";
-
-// src/application/file-state-store.ts
-import { mkdir, open, readdir, readFile, rename, stat, unlink } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
-var ABANDONED_LOCK_MULTIPLIER = 10;
-var ABANDONED_HEARTBEATS = 30;
-var MIN_HEARTBEAT_MS = 10;
-var delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
-async function missing(error) {
-  return error instanceof Error && "code" in error && error.code === "ENOENT";
-}
-function existing(error) {
-  return error instanceof Error && "code" in error && error.code === "EEXIST";
-}
-async function ownerState(lockPath) {
-  let owner;
-  try {
-    owner = JSON.parse(await readFile(lockPath, "utf8"));
-  } catch {
-    return "unknown";
-  }
-  if (typeof owner !== "object" || owner === null || !("pid" in owner) || typeof owner.pid !== "number" || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) {
-    return "unknown";
-  }
-  try {
-    process.kill(owner.pid, 0);
-    return "alive";
-  } catch (error) {
-    return error instanceof Error && "code" in error && error.code === "ESRCH" ? "gone" : "unknown";
-  }
-}
-async function sweepTemporaries(path, staleLockMs) {
-  const prefix = `${basename(path)}.tmp.`;
-  const directory = dirname(path);
-  let entries;
-  try {
-    entries = await readdir(directory);
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (!entry.startsWith(prefix))
-      continue;
-    const candidate = join(directory, entry);
-    const info = await stat(candidate).catch(() => null);
-    if (info && Date.now() - info.mtimeMs > staleLockMs) {
-      await unlink(candidate).catch(() => {
-        return;
-      });
-    }
-  }
-}
-async function reclaim(lockPath, observed, staleLockMs, abandonedAfterMs) {
-  const guardPath = `${lockPath}.reclaim`;
-  let guard;
-  try {
-    guard = await open(guardPath, "wx");
-  } catch (error) {
-    if (!existing(error))
-      throw error;
-    const orphan = await stat(guardPath).catch(() => null);
-    if (orphan && Date.now() - orphan.mtimeMs > staleLockMs) {
-      await unlink(guardPath).catch(() => {
-        return;
-      });
-    }
-    return false;
-  }
-  try {
-    const current = await stat(lockPath).catch(() => null);
-    if (!current || current.dev !== observed.dev || current.ino !== observed.ino || current.mtimeMs !== observed.mtimeMs) {
-      return false;
-    }
-    const owner = await ownerState(lockPath);
-    const age = Date.now() - current.mtimeMs;
-    if (owner !== "gone" && age < abandonedAfterMs)
-      return false;
-    await unlink(lockPath);
-    return true;
-  } finally {
-    await guard.close().catch(() => {
-      return;
-    });
-    await unlink(guardPath).catch(() => {
-      return;
-    });
-  }
-}
-function createFileStateStore(path, options) {
-  const lockPath = `${path}.lock`;
-  const lockTimeoutMs = options.lockTimeoutMs ?? 1e4;
-  const staleLockMs = options.staleLockMs ?? 3000;
-  const retryMs = options.retryMs ?? 10;
-  const heartbeatMs = Math.max(MIN_HEARTBEAT_MS, Math.floor(staleLockMs / 3));
-  const abandonedAfterMs = Math.max(staleLockMs * ABANDONED_LOCK_MULTIPLIER, heartbeatMs * ABANDONED_HEARTBEATS);
-  if (staleLockMs >= lockTimeoutMs) {
-    throw new Error(`[stitchkit] createFileStateStore: staleLockMs (${staleLockMs}) must be below lockTimeoutMs (${lockTimeoutMs}), or a crashed holder blocks every update until the timeout`);
-  }
-  let sweptTemporaries = false;
-  const parseFile = async () => {
-    let source;
-    try {
-      source = await readFile(path, "utf8");
-    } catch (error) {
-      if (await missing(error))
-        return null;
-      throw error;
-    }
-    try {
-      return options.schema.parse(JSON.parse(source));
-    } catch (error) {
-      await options.onCorrupt?.({ path, error });
-      if ((options.corrupt ?? "throw") === "empty")
-        return null;
-      throw error;
-    }
-  };
-  const acquire = async () => {
-    await mkdir(dirname(path), { recursive: true });
-    if (!sweptTemporaries) {
-      sweptTemporaries = true;
-      await sweepTemporaries(path, staleLockMs);
-    }
-    const deadline = Date.now() + lockTimeoutMs;
-    while (true) {
-      try {
-        const handle = await open(lockPath, "wx");
-        const token = crypto.randomUUID();
-        try {
-          await handle.writeFile(JSON.stringify({ token, pid: process.pid, acquiredAt: Date.now() }));
-          await handle.sync();
-        } catch (error) {
-          await handle.close().catch(() => {
-            return;
-          });
-          await unlink(lockPath).catch(() => {
-            return;
-          });
-          throw error;
-        }
-        return {
-          refresh: async () => {
-            const now = new Date;
-            await handle.utimes(now, now);
-          },
-          release: async () => {
-            await handle.close();
-            try {
-              const owner = JSON.parse(await readFile(lockPath, "utf8"));
-              if (isRecord(owner) && owner.token === token)
-                await unlink(lockPath);
-            } catch (error) {
-              if (!await missing(error))
-                throw error;
-            }
-          }
-        };
-      } catch (error) {
-        if (!existing(error))
-          throw error;
-        try {
-          const lock = await stat(lockPath);
-          if (Date.now() - lock.mtimeMs > staleLockMs) {
-            if (await reclaim(lockPath, lock, staleLockMs, abandonedAfterMs))
-              continue;
-          }
-        } catch (statError) {
-          if (await missing(statError))
-            continue;
-          throw statError;
-        }
-        if (Date.now() >= deadline) {
-          throw new Error(`[stitchkit] timed out acquiring state lock for ${path}`);
-        }
-        await delay(retryMs);
-      }
-    }
-  };
-  const write = async (state) => {
-    const validated = options.schema.parse(state);
-    const temporary = `${path}.tmp.${process.pid}.${crypto.randomUUID()}`;
-    const handle = await open(temporary, "wx");
-    try {
-      try {
-        await handle.writeFile(`${JSON.stringify(validated)}
-`);
-        await handle.sync();
-      } finally {
-        await handle.close();
-      }
-      await rename(temporary, path);
-    } catch (error) {
-      await unlink(temporary).catch(() => {
-        return;
-      });
-      throw error;
-    }
-  };
-  return {
-    read: parseFile,
-    async update(transition) {
-      const lock = await acquire();
-      const heartbeat = setInterval(() => void lock.refresh().catch(() => {
-        return;
-      }), heartbeatMs);
-      try {
-        const next = await transition(await parseFile());
-        await write(next.state);
-        return next.result;
-      } finally {
-        clearInterval(heartbeat);
-        await lock.release();
-      }
-    }
-  };
-}
 // src/realtime/registry.ts
 var authorizedRoom = Symbol("stitchkit.authorized-room");
 function freezeRoom(name) {
@@ -1001,7 +788,7 @@ function createEventBus(options = {}) {
   };
 }
 // src/server/file.ts
-import { readFile as readFile2, stat as stat2 } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 
 // src/server/mime.ts
@@ -1061,10 +848,10 @@ function staticRoute(prefix, dir) {
       const realTarget = await realPathWithinDir(root, target);
       if (realTarget === null)
         return new Response("Not found", { status: 404 });
-      const info = await stat2(realTarget).catch(() => null);
+      const info = await stat(realTarget).catch(() => null);
       if (!info?.isFile())
         return new Response("Not found", { status: 404 });
-      return new Response(await readFile2(realTarget), {
+      return new Response(await readFile(realTarget), {
         headers: {
           "Content-Type": mimeForPath(realTarget),
           "X-Content-Type-Options": "nosniff"

package/dist/index-5jrd0yng.js

@@ -0,0 +1,114 @@
+// src/application/directory-inbox-contract.ts
+import { z } from "zod";
+var timestamp = z.string().datetime({ offset: true });
+var key = z.string().min(1).max(255);
+var DirectoryInboxRejectionReasonSchema = z.enum([
+  "invalid",
+  "too-large",
+  "attempt-limit"
+]);
+var DirectoryInboxStateSchema = z.object({
+  schemaVersion: z.literal(1),
+  claims: z.array(z.object({
+    key,
+    attempts: z.number().int().positive(),
+    nextAttemptAt: timestamp,
+    leaseId: z.string().min(1).max(128).nullable(),
+    leaseUntil: timestamp.nullable()
+  }).strict()),
+  receipts: z.array(z.object({ key, completedAt: timestamp }).strict()),
+  rejected: z.array(z.object({
+    key,
+    reason: DirectoryInboxRejectionReasonSchema,
+    detail: z.string().max(1000),
+    rejectedAt: timestamp
+  }).strict())
+}).strict();
+var emptyDirectoryInboxState = () => ({
+  schemaVersion: 1,
+  claims: [],
+  receipts: [],
+  rejected: []
+});
+var iso = (milliseconds) => new Date(milliseconds).toISOString();
+function withRejection(state, rejection, retain) {
+  return {
+    ...state,
+    claims: state.claims.filter((claim) => claim.key !== rejection.key),
+    rejected: [
+      rejection,
+      ...state.rejected.filter((item) => item.key !== rejection.key)
+    ].slice(0, retain)
+  };
+}
+function claimEntry(state, input) {
+  if (state.receipts.some((receipt) => receipt.key === input.key)) {
+    return { state, step: { kind: "remove" } };
+  }
+  if (state.rejected.some((rejection) => rejection.key === input.key)) {
+    return { state, step: { kind: "set-aside" } };
+  }
+  const now = input.now.getTime();
+  const claim = state.claims.find((candidate) => candidate.key === input.key);
+  if (claim) {
+    const leased = claim.leaseUntil !== null && Date.parse(claim.leaseUntil) > now;
+    if (leased || Date.parse(claim.nextAttemptAt) > now)
+      return { state, step: { kind: "skip" } };
+    if (claim.attempts >= input.maxAttempts) {
+      const rejection = {
+        key: input.key,
+        reason: "attempt-limit",
+        detail: `taken ${claim.attempts} times without completing`,
+        rejectedAt: iso(now)
+      };
+      return {
+        state: withRejection(state, rejection, input.retain),
+        step: { kind: "reject", rejection }
+      };
+    }
+  }
+  const taken = {
+    key: input.key,
+    attempts: (claim?.attempts ?? 0) + 1,
+    nextAttemptAt: iso(now),
+    leaseId: crypto.randomUUID(),
+    leaseUntil: iso(now + input.leaseMs)
+  };
+  return {
+    state: {
+      ...state,
+      claims: [...state.claims.filter((candidate) => candidate.key !== input.key), taken]
+    },
+    step: { kind: "deliver", claim: taken }
+  };
+}
+function completeEntry(state, entryKey, now, retain) {
+  return {
+    ...state,
+    claims: state.claims.filter((claim) => claim.key !== entryKey),
+    receipts: [
+      { key: entryKey, completedAt: now.toISOString() },
+      ...state.receipts.filter((receipt) => receipt.key !== entryKey)
+    ].slice(0, retain)
+  };
+}
+function releaseEntry(state, claim, retryAt) {
+  return {
+    ...state,
+    claims: state.claims.map((candidate) => candidate.key === claim.key && candidate.leaseId === claim.leaseId ? {
+      ...candidate,
+      nextAttemptAt: retryAt.toISOString(),
+      leaseId: null,
+      leaseUntil: null
+    } : candidate)
+  };
+}
+function forgetMissing(state, present, now) {
+  const live = (claim) => claim.leaseUntil !== null && Date.parse(claim.leaseUntil) > now.getTime();
+  return {
+    ...state,
+    claims: state.claims.filter((claim) => present.has(claim.key) || live(claim))
+  };
+}
+
+export { DirectoryInboxRejectionReasonSchema, DirectoryInboxStateSchema, emptyDirectoryInboxState, withRejection, claimEntry, completeEntry, releaseEntry, forgetMissing };

package/dist/{index-7f68ghdn.js → index-8zja4pkf.js}

@@ -1775,6 +1775,27 @@ function markProviderOrigin(error) {
 function hasProviderOrigin(error) {
   return typeof error === "object" && error !== null && providerOrigin.has(error);
 }
+function markProviderStream(stream) {
+  const reader = stream.getReader();
+  return new ReadableStream({
+    async pull(controller) {
+      let read;
+      try {
+        read = await reader.read();
+      } catch (error) {
+        controller.error(isOwnInputRefusal(error) ? error : markProviderOrigin(error));
+        return;
+      }
+      if (read.done)
+        controller.close();
+      else
+        controller.enqueue(read.value);
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    }
+  });
+}
 
 // src/agent-runtime/run-operation-lifecycle.ts
 function createAgentRunOperationLifecycle(config) {
@@ -1840,7 +1861,8 @@ function createAgentRunOperationLifecycle(config) {
             }
             await startModelRequest(callId, step);
             try {
-              return await doStream();
+              const result = await doStream();
+              return { ...result, stream: markProviderStream(result.stream) };
             } catch (error) {
               throw isOwnInputRefusal(error) ? error : markProviderOrigin(error);
             }

package/dist/index-tm88avnj.js

@@ -0,0 +1,221 @@
+import {
+  isRecord
+} from "./index-hffjpmq9.js";
+
+// src/application/file-state-store.ts
+import { mkdir, open, readdir, readFile, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+var ABANDONED_LOCK_MULTIPLIER = 10;
+var ABANDONED_HEARTBEATS = 30;
+var MIN_HEARTBEAT_MS = 10;
+var delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+async function missing(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function existing(error) {
+  return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+async function ownerState(lockPath) {
+  let owner;
+  try {
+    owner = JSON.parse(await readFile(lockPath, "utf8"));
+  } catch {
+    return "unknown";
+  }
+  if (typeof owner !== "object" || owner === null || !("pid" in owner) || typeof owner.pid !== "number" || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) {
+    return "unknown";
+  }
+  try {
+    process.kill(owner.pid, 0);
+    return "alive";
+  } catch (error) {
+    return error instanceof Error && "code" in error && error.code === "ESRCH" ? "gone" : "unknown";
+  }
+}
+async function sweepTemporaries(path, staleLockMs) {
+  const prefix = `${basename(path)}.tmp.`;
+  const directory = dirname(path);
+  let entries;
+  try {
+    entries = await readdir(directory);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.startsWith(prefix))
+      continue;
+    const candidate = join(directory, entry);
+    const info = await stat(candidate).catch(() => null);
+    if (info && Date.now() - info.mtimeMs > staleLockMs) {
+      await unlink(candidate).catch(() => {
+        return;
+      });
+    }
+  }
+}
+async function reclaim(lockPath, observed, staleLockMs, abandonedAfterMs) {
+  const guardPath = `${lockPath}.reclaim`;
+  let guard;
+  try {
+    guard = await open(guardPath, "wx");
+  } catch (error) {
+    if (!existing(error))
+      throw error;
+    const orphan = await stat(guardPath).catch(() => null);
+    if (orphan && Date.now() - orphan.mtimeMs > staleLockMs) {
+      await unlink(guardPath).catch(() => {
+        return;
+      });
+    }
+    return false;
+  }
+  try {
+    const current = await stat(lockPath).catch(() => null);
+    if (!current || current.dev !== observed.dev || current.ino !== observed.ino || current.mtimeMs !== observed.mtimeMs) {
+      return false;
+    }
+    const owner = await ownerState(lockPath);
+    const age = Date.now() - current.mtimeMs;
+    if (owner !== "gone" && age < abandonedAfterMs)
+      return false;
+    await unlink(lockPath);
+    return true;
+  } finally {
+    await guard.close().catch(() => {
+      return;
+    });
+    await unlink(guardPath).catch(() => {
+      return;
+    });
+  }
+}
+function createFileStateStore(path, options) {
+  const lockPath = `${path}.lock`;
+  const lockTimeoutMs = options.lockTimeoutMs ?? 1e4;
+  const staleLockMs = options.staleLockMs ?? 3000;
+  const retryMs = options.retryMs ?? 10;
+  const heartbeatMs = Math.max(MIN_HEARTBEAT_MS, Math.floor(staleLockMs / 3));
+  const abandonedAfterMs = Math.max(staleLockMs * ABANDONED_LOCK_MULTIPLIER, heartbeatMs * ABANDONED_HEARTBEATS);
+  if (staleLockMs >= lockTimeoutMs) {
+    throw new Error(`[stitchkit] createFileStateStore: staleLockMs (${staleLockMs}) must be below lockTimeoutMs (${lockTimeoutMs}), or a crashed holder blocks every update until the timeout`);
+  }
+  let sweptTemporaries = false;
+  const parseFile = async () => {
+    let source;
+    try {
+      source = await readFile(path, "utf8");
+    } catch (error) {
+      if (await missing(error))
+        return null;
+      throw error;
+    }
+    try {
+      return options.schema.parse(JSON.parse(source));
+    } catch (error) {
+      await options.onCorrupt?.({ path, error });
+      if ((options.corrupt ?? "throw") === "empty")
+        return null;
+      throw error;
+    }
+  };
+  const acquire = async () => {
+    await mkdir(dirname(path), { recursive: true });
+    if (!sweptTemporaries) {
+      sweptTemporaries = true;
+      await sweepTemporaries(path, staleLockMs);
+    }
+    const deadline = Date.now() + lockTimeoutMs;
+    while (true) {
+      try {
+        const handle = await open(lockPath, "wx");
+        const token = crypto.randomUUID();
+        try {
+          await handle.writeFile(JSON.stringify({ token, pid: process.pid, acquiredAt: Date.now() }));
+          await handle.sync();
+        } catch (error) {
+          await handle.close().catch(() => {
+            return;
+          });
+          await unlink(lockPath).catch(() => {
+            return;
+          });
+          throw error;
+        }
+        return {
+          refresh: async () => {
+            const now = new Date;
+            await handle.utimes(now, now);
+          },
+          release: async () => {
+            await handle.close();
+            try {
+              const owner = JSON.parse(await readFile(lockPath, "utf8"));
+              if (isRecord(owner) && owner.token === token)
+                await unlink(lockPath);
+            } catch (error) {
+              if (!await missing(error))
+                throw error;
+            }
+          }
+        };
+      } catch (error) {
+        if (!existing(error))
+          throw error;
+        try {
+          const lock = await stat(lockPath);
+          if (Date.now() - lock.mtimeMs > staleLockMs) {
+            if (await reclaim(lockPath, lock, staleLockMs, abandonedAfterMs))
+              continue;
+          }
+        } catch (statError) {
+          if (await missing(statError))
+            continue;
+          throw statError;
+        }
+        if (Date.now() >= deadline) {
+          throw new Error(`[stitchkit] timed out acquiring state lock for ${path}`);
+        }
+        await delay(retryMs);
+      }
+    }
+  };
+  const write = async (state) => {
+    const validated = options.schema.parse(state);
+    const temporary = `${path}.tmp.${process.pid}.${crypto.randomUUID()}`;
+    const handle = await open(temporary, "wx");
+    try {
+      try {
+        await handle.writeFile(`${JSON.stringify(validated)}
+`);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temporary, path);
+    } catch (error) {
+      await unlink(temporary).catch(() => {
+        return;
+      });
+      throw error;
+    }
+  };
+  return {
+    read: parseFile,
+    async update(transition) {
+      const lock = await acquire();
+      const heartbeat = setInterval(() => void lock.refresh().catch(() => {
+        return;
+      }), heartbeatMs);
+      try {
+        const next = await transition(await parseFile());
+        await write(next.state);
+        return next.result;
+      } finally {
+        clearInterval(heartbeat);
+        await lock.release();
+      }
+    }
+  };
+}
+
+export { createFileStateStore };

package/llms/application-directory-inbox.txt

@@ -0,0 +1,9 @@
+# stitchkit/application/directory-inbox — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: pointers only
+
+Also read:
+- see `llms/application.txt` for the Managed application kernel guide

package/llms/application.2.txt

@@ -290,15 +290,17 @@ cutovers are covered by the executable
 | `createApplication` | function | compose a validated resource DAG into one startup, readiness, admission and shutdown state machine |
 | `StateStore` / `StateStoreUpdate` | _type_ | async atomic read/update boundary shared by durable application state machines |
 | `createProcessLifecycleLedger` / `ProcessLifecycleLedger` / `ProcessLifecycleLedgerConfig` | function / _type_ | durable bounded run history and typed fact subscription |
-| `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state and termination vocabulary |
-| `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, handoff and abnormal lifecycle facts |
-| `transitionProcessStart` / `transitionProcessReady` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
-| `LifecycleTransition` / `TransitionStartInput` / `TransitionReadyInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs, the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
-| `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness and shutdown |
+| `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state — open (`active`, `draining` with `unavailableAt`) and ended (`clean`, `forced`, `startup-failed`, `hot-reload`, `abnormal`) |
+| `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `DrainingFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, startup-failed, handoff and abnormal lifecycle facts; `processGapMs` on start, `downtimeMs` (unavailable → ready) on ready |
+| `transitionProcessStart` / `transitionProcessReady` / `transitionProcessDraining` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
+| `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
+| `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness, admission stop (draining) and shutdown |
 | `createNotificationOutbox` / `NotificationOutbox` / `NotificationOutboxConfig` | function / _type_ | bounded at-least-once queue with durable claims, leases, retries and supersede |
 | `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 |
+| `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 |
 | `ApplicationRestartResultSchema` / `ApplicationRestartResult` | schema / _type_ | the subtree that was actually taken down and brought back, in start order, with the outcome, the reason on anything but success, and how long it took |