stitchkit 0.93.0 → 0.94.1

package/dist/index-w906953s.js

@@ -0,0 +1,946 @@
+import {
+  ApplicationIdSchema,
+  ApplicationShutdownResultSchema,
+  ApplicationSnapshotSchema
+} from "./index-3gye9wzb.js";
+import {
+  managedResourceDependencyId
+} from "./index-2k4yrqkc.js";
+import {
+  ShutdownOptionsSchema
+} from "./index-3z73fh2c.js";
+import {
+  AppError
+} from "./index-2vtcmrj9.js";
+
+// src/application/kernel-contract.ts
+import { z } from "zod";
+var ApplicationShutdownOptionsSchema = ShutdownOptionsSchema.pick({
+  gracePeriodMs: true,
+  forceTimeoutMs: true,
+  signal: true
+});
+var ApplicationShutdownBudgetSchema = ShutdownOptionsSchema.pick({
+  gracePeriodMs: true,
+  forceTimeoutMs: true
+});
+var ApplicationRestartInputSchema = z.object({
+  resourceId: z.string().min(1),
+  gracePeriodMs: z.number().int().nonnegative().optional(),
+  forceTimeoutMs: z.number().int().nonnegative().optional()
+}).strict().readonly();
+var ApplicationRestartOutcomeSchema = z.enum(["restarted", "failed", "refused"]);
+var ApplicationRestartResultSchema = z.object({
+  resourceId: z.string(),
+  affected: z.array(z.string()).readonly(),
+  outcome: ApplicationRestartOutcomeSchema,
+  reason: z.string().optional(),
+  durationMs: z.number().int().nonnegative()
+}).strict().readonly();
+
+class ApplicationAdmissionError extends AppError {
+  constructor() {
+    super("APPLICATION_NOT_ACCEPTING", "Application is not accepting new operations", 503);
+    this.name = "ApplicationAdmissionError";
+  }
+}
+
+// src/application/graph.ts
+function resolveResourceGraph(resources) {
+  const entries = resources.map((resource, declarationIndex) => ({
+    resource,
+    id: ApplicationIdSchema.parse(resource.id),
+    dependsOn: [...resource.dependsOn ?? []].map((dependency) => ApplicationIdSchema.parse(managedResourceDependencyId(dependency))),
+    required: resource.required ?? true,
+    declarationIndex
+  }));
+  const byId = new Map;
+  for (const entry of entries) {
+    if (byId.has(entry.id)) {
+      throw new Error(`[stitchkit] createApplication: duplicate resource id "${entry.id}"`);
+    }
+    byId.set(entry.id, entry);
+  }
+  for (const entry of entries) {
+    for (const dependencyId of entry.dependsOn) {
+      const dependency = byId.get(dependencyId);
+      if (!dependency) {
+        throw new Error(`[stitchkit] createApplication: resource "${entry.id}" depends on missing resource "${dependencyId}"`);
+      }
+      if (entry.required && !dependency.required) {
+        throw new Error(`[stitchkit] createApplication: required resource "${entry.id}" cannot depend on optional resource "${dependencyId}"`);
+      }
+    }
+  }
+  const pending = new Map(entries.map((entry) => [entry.id, entry]));
+  const resolved = new Set;
+  const ordered = [];
+  while (pending.size > 0) {
+    const ready = [...pending.values()].filter((entry) => entry.dependsOn.every((id) => resolved.has(id))).sort((left, right) => left.declarationIndex - right.declarationIndex);
+    if (ready.length === 0) {
+      throw new Error(`[stitchkit] createApplication: resource dependency cycle: ${[...pending.keys()].join(", ")}`);
+    }
+    for (const entry of ready) {
+      pending.delete(entry.id);
+      resolved.add(entry.id);
+      ordered.push(entry);
+    }
+  }
+  return ordered;
+}
+
+// src/application/kernel-state.ts
+class ResourceCompletionBeforeReadyError extends Error {
+  constructor(resourceId, cause) {
+    super(`[stitchkit] resource "${resourceId}" completed before reaching readiness`, {
+      ...cause !== undefined && { cause }
+    });
+    this.name = "ResourceCompletionBeforeReadyError";
+  }
+}
+
+class ApplicationStartupInterruptedError extends Error {
+  constructor() {
+    super("[stitchkit] application startup interrupted by shutdown");
+    this.name = "ApplicationStartupInterruptedError";
+  }
+}
+function isStartResult(value) {
+  return typeof value === "object" && value !== null;
+}
+function waitForAbort(signal) {
+  if (signal.aborted)
+    return Promise.resolve();
+  return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+}
+async function untilDeadline(work, signal) {
+  const result = await Promise.race([
+    work.then((value) => ({ settled: true, value }), (error) => ({ settled: true, error })),
+    waitForAbort(signal).then(() => ({ settled: false }))
+  ]);
+  return result;
+}
+function createKernelState(config) {
+  const id = ApplicationIdSchema.parse(config.id);
+  const ordered = resolveResourceGraph(config.resources ?? []);
+  const shutdownBudget = ApplicationShutdownBudgetSchema.parse(config.shutdown ?? {});
+  const reverse = [...ordered].reverse();
+  const records = new Map;
+  for (const entry of ordered) {
+    records.set(entry.id, {
+      entry,
+      state: "registered",
+      health: "unknown",
+      healthReported: false,
+      everHealthy: false,
+      attempted: false,
+      activated: false,
+      closeInvoked: false,
+      closed: false,
+      failures: []
+    });
+  }
+  return {
+    id,
+    config,
+    ordered,
+    reverse,
+    shutdownBudget,
+    published: new Map,
+    records,
+    epoch: crypto.randomUUID(),
+    listeners: new Set,
+    lifetimeAbort: new AbortController,
+    startupAbort: new AbortController,
+    lifecycle: "created",
+    revision: 0,
+    changedAt: new Date().toISOString(),
+    accepting: false,
+    accepted: 0,
+    completed: 0,
+    pending: 0,
+    startPromise: undefined,
+    shutdownPromise: undefined,
+    shutdownRequested: false,
+    activationComplete: false,
+    pendingWaiters: new Set,
+    restartingIds: [],
+    restarting: Promise.resolve()
+  };
+}
+function recordOf(state, resourceId) {
+  const record = state.records.get(resourceId);
+  if (!record)
+    throw new Error("Managed resource record disappeared");
+  return record;
+}
+function reportFailure(state, resourceId, phase, error) {
+  const config = state.config;
+  if (!config.onResourceFailure)
+    return;
+  try {
+    Promise.resolve(config.onResourceFailure({ resourceId, phase, error })).catch(() => {
+      return;
+    });
+  } catch {}
+}
+function aggregateHealth(state) {
+  if (state.lifecycle === "created" || state.lifecycle === "starting")
+    return "unknown";
+  let optionalUnhealthy = false;
+  for (const record of state.records.values()) {
+    if (record.entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+      return "unhealthy";
+    }
+    if (!record.entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+      optionalUnhealthy = true;
+    }
+  }
+  return optionalUnhealthy ? "degraded" : "healthy";
+}
+function isReady(state) {
+  return state.lifecycle === "ready" && [...state.records.values()].every((record) => !record.entry.required || record.state === "ready" && record.health === "healthy");
+}
+function snapshot(state) {
+  return ApplicationSnapshotSchema.parse({
+    id: state.id,
+    epoch: state.epoch,
+    revision: state.revision,
+    lifecycle: state.lifecycle,
+    health: aggregateHealth(state),
+    ready: isReady(state),
+    capturedAt: new Date().toISOString(),
+    changedAt: state.changedAt,
+    admission: {
+      accepting: state.accepting,
+      accepted: state.accepted,
+      completed: state.completed,
+      pending: state.pending
+    },
+    restarting: [...state.restartingIds],
+    resources: state.ordered.map((entry) => {
+      const record = recordOf(state, entry.id);
+      return {
+        id: entry.id,
+        required: entry.required,
+        dependsOn: entry.dependsOn,
+        state: record.state,
+        health: record.health,
+        ready: record.state === "ready" && record.health === "healthy"
+      };
+    })
+  });
+}
+function publish(state) {
+  state.revision += 1;
+  state.changedAt = new Date().toISOString();
+  const value = snapshot(state);
+  for (const listener of state.listeners) {
+    try {
+      listener(value);
+    } catch {}
+  }
+  const config = state.config;
+  if (config.onSnapshot) {
+    Promise.resolve().then(() => config.onSnapshot?.(value)).catch(() => {});
+  }
+}
+
+// src/application/kernel-admission.ts
+function acquire(state) {
+  if (!state.accepting || !isReady(state))
+    return null;
+  state.accepted += 1;
+  state.pending += 1;
+  publish(state);
+  let released = false;
+  return {
+    get released() {
+      return released;
+    },
+    release() {
+      if (released)
+        return;
+      released = true;
+      state.pending -= 1;
+      state.completed += 1;
+      if (state.pending === 0) {
+        for (const waiter of state.pendingWaiters)
+          waiter();
+        state.pendingWaiters.clear();
+      }
+      publish(state);
+    }
+  };
+}
+async function run(state, work) {
+  const lease = acquire(state);
+  if (!lease)
+    throw new ApplicationAdmissionError;
+  try {
+    return await work();
+  } finally {
+    lease.release();
+  }
+}
+function waitForPending(state) {
+  if (state.pending === 0)
+    return Promise.resolve();
+  return new Promise((resolve) => state.pendingWaiters.add(resolve));
+}
+
+// src/application/kernel-resource-context.ts
+function contextFor(state, record, options = {}) {
+  return {
+    applicationId: state.id,
+    signal: options.signal ?? state.lifetimeAbort.signal,
+    ...options.deadlineAt !== undefined && { deadlineAt: options.deadlineAt },
+    ...options.forceDeadlineAt !== undefined && {
+      forceDeadlineAt: options.forceDeadlineAt
+    },
+    now: () => performance.now(),
+    use(resource) {
+      const dependencyId = resource?.id;
+      if (typeof dependencyId !== "string" || dependencyId.length === 0) {
+        throw new Error(`[stitchkit] resource "${record.entry.id}": use() takes a managed resource, and this one has no id`);
+      }
+      if (!record.entry.dependsOn.includes(dependencyId)) {
+        throw new Error(`[stitchkit] resource "${record.entry.id}" used "${dependencyId}" without declaring it in dependsOn`);
+      }
+      if (!state.published.has(dependencyId)) {
+        throw new Error(`[stitchkit] resource "${record.entry.id}" used "${dependencyId}", which published no value from start()`);
+      }
+      return state.published.get(dependencyId);
+    },
+    reportHealth(health) {
+      if (record.state === "stopped")
+        return;
+      const repeated = record.healthReported && record.health === health;
+      record.health = health;
+      record.healthReported = true;
+      if (health === "healthy")
+        record.everHealthy = true;
+      const accepting = state.activationComplete && !state.shutdownRequested && isReady(state);
+      if (repeated && accepting === state.accepting)
+        return;
+      state.accepting = accepting;
+      publish(state);
+    }
+  };
+}
+function markLateCompletion(state, record, failure) {
+  if (state.shutdownRequested || record.state === "stopping" || record.state === "stopped") {
+    return;
+  }
+  if (failure) {
+    record.failures.push("completion");
+    reportFailure(state, record.entry.id, "completion", failure.error);
+  }
+  record.state = "failed";
+  record.health = "unhealthy";
+  state.accepting = state.activationComplete && isReady(state);
+  publish(state);
+}
+
+// src/application/kernel-rollback.ts
+async function closeAttempted(state) {
+  const errors = [];
+  const rollbackStartedAt = performance.now();
+  const rollbackDeadlineAt = rollbackStartedAt + state.shutdownBudget.gracePeriodMs;
+  const rollbackForceDeadlineAt = rollbackDeadlineAt + state.shutdownBudget.forceTimeoutMs;
+  const rollbackAbort = new AbortController;
+  const rollbackTimer = setTimeout(() => rollbackAbort.abort(), Math.max(0, rollbackForceDeadlineAt - performance.now()));
+  try {
+    await closeEachAttempted(state, rollbackAbort.signal, errors, {
+      deadlineAt: rollbackDeadlineAt,
+      forceDeadlineAt: rollbackForceDeadlineAt
+    });
+  } finally {
+    clearTimeout(rollbackTimer);
+  }
+  return errors;
+}
+async function closeEachAttempted(state, bound, errors, deadlines) {
+  for (const entry of state.reverse) {
+    const record = state.records.get(entry.id);
+    if (!record?.attempted || record.closed)
+      continue;
+    record.state = "stopping";
+    try {
+      record.closeInvoked = true;
+      const settled = await untilDeadline(Promise.resolve(entry.resource.close?.(contextFor(state, record, { signal: state.startupAbort.signal, ...deadlines }))), bound);
+      if (!settled.settled) {
+        record.failures.push("close");
+        record.state = "failed";
+        const timedOut = new Error(`[stitchkit] resource "${entry.id}" did not finish closing during rollback`);
+        reportFailure(state, entry.id, "close", timedOut);
+        errors.push(timedOut);
+        publish(state);
+        break;
+      }
+      if (settled.error !== undefined)
+        throw settled.error;
+      record.closed = true;
+      record.state = "stopped";
+    } catch (error) {
+      record.failures.push("close");
+      record.state = "failed";
+      reportFailure(state, entry.id, "close", error);
+      errors.push(error);
+    }
+    publish(state);
+  }
+}
+
+// src/application/kernel-start.ts
+async function startEach(state, entries, signal) {
+  for (const entry of entries) {
+    if (state.shutdownRequested || signal.aborted) {
+      throw new ApplicationStartupInterruptedError;
+    }
+    const record = recordOf(state, entry.id);
+    const dependencyFailed = entry.dependsOn.some((dependencyId) => state.records.get(dependencyId)?.state !== "ready");
+    if (dependencyFailed) {
+      record.state = "failed";
+      record.health = "unhealthy";
+      record.failures.push("start");
+      publish(state);
+      if (entry.required) {
+        throw new Error(`[stitchkit] required resource "${entry.id}" has an unavailable dependency`);
+      }
+      continue;
+    }
+    record.attempted = true;
+    record.state = "starting";
+    publish(state);
+    try {
+      const started = await entry.resource.start(contextFor(state, record, { signal }));
+      if (state.shutdownRequested || signal.aborted) {
+        throw new ApplicationStartupInterruptedError;
+      }
+      if (isStartResult(started)) {
+        record.runtime = started;
+        if (started.value !== undefined)
+          state.published.set(entry.id, started.value);
+        let resourceReady = started.ready === undefined;
+        let completionSettled = false;
+        let completionFailure;
+        const completion = started.completion?.then(() => {
+          completionSettled = true;
+          if (resourceReady)
+            markLateCompletion(state, record);
+        }, (error) => {
+          completionSettled = true;
+          completionFailure = error;
+          if (resourceReady)
+            markLateCompletion(state, record, { error });
+        });
+        if (started.ready && completion) {
+          const readiness = started.ready.then(() => "ready");
+          const completionBeforeReady = completion.then(() => "completion");
+          const first = await Promise.race([readiness, completionBeforeReady]);
+          if (first === "completion") {
+            throw new ResourceCompletionBeforeReadyError(entry.id, completionFailure);
+          }
+          resourceReady = true;
+          if (completionSettled) {
+            throw new ResourceCompletionBeforeReadyError(entry.id, completionFailure);
+          }
+        } else if (started.ready) {
+          await started.ready;
+          resourceReady = true;
+        } else if (completion) {}
+      }
+      if (state.shutdownRequested || signal.aborted) {
+        throw new ApplicationStartupInterruptedError;
+      }
+      record.state = "ready";
+      if (!record.healthReported) {
+        record.health = "healthy";
+        record.everHealthy = true;
+      }
+      publish(state);
+    } catch (error) {
+      const interrupted = state.shutdownRequested || signal.aborted;
+      if (!(error instanceof ApplicationStartupInterruptedError)) {
+        record.failures.push(error instanceof ResourceCompletionBeforeReadyError ? "completion" : record.runtime?.ready ? "ready" : "start");
+        record.state = "failed";
+        record.health = "unhealthy";
+        reportFailure(state, entry.id, record.failures[record.failures.length - 1] ?? "start", error);
+        publish(state);
+      }
+      if (interrupted || entry.required)
+        throw error;
+    }
+  }
+}
+async function activateEach(state, entries, signal) {
+  for (const entry of entries) {
+    if (state.shutdownRequested || signal.aborted) {
+      throw new ApplicationStartupInterruptedError;
+    }
+    const record = state.records.get(entry.id);
+    if (record?.state !== "ready")
+      continue;
+    const dependencyUnavailable = entry.dependsOn.some((dependencyId) => {
+      const dependency = state.records.get(dependencyId);
+      return dependency?.state !== "ready" || !dependency.activated;
+    });
+    if (dependencyUnavailable) {
+      record.failures.push("start");
+      record.state = "failed";
+      record.health = "unhealthy";
+      publish(state);
+      if (entry.required) {
+        throw new Error(`[stitchkit] required resource "${entry.id}" has an unavailable activation dependency`);
+      }
+      continue;
+    }
+    try {
+      await entry.resource.activate?.(contextFor(state, record));
+      if (state.shutdownRequested || signal.aborted) {
+        throw new ApplicationStartupInterruptedError;
+      }
+      record.activated = true;
+      if (entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+        const observed = `${record.state}/${record.health}`;
+        throw new Error(record.everHealthy ? `[stitchkit] required resource "${entry.id}" lost readiness during activation (${observed})` : `[stitchkit] required resource "${entry.id}" is not healthy (${observed}). A required resource must be healthy for the application to be ready; a resource that is expected to start degraded belongs behind \`required: false\`.`);
+      }
+    } catch (error) {
+      const interrupted = state.shutdownRequested || signal.aborted;
+      if (!(error instanceof ApplicationStartupInterruptedError)) {
+        record.failures.push("start");
+        record.state = "failed";
+        record.health = "unhealthy";
+        reportFailure(state, entry.id, "start", error);
+        publish(state);
+      }
+      if (interrupted || entry.required)
+        throw error;
+    }
+  }
+}
+function notReadyAfterStartup(state) {
+  const blocking = [...state.records.values()].filter((record) => record.entry.required && (record.state !== "ready" || record.health !== "healthy")).map((record) => `${record.entry.id} (${record.state}/${record.health})`);
+  if (blocking.length === 0)
+    blocking.push("(none identified)");
+  const chosen = [...state.records.values()].some((record) => record.entry.required && record.health !== "healthy" && !record.everHealthy);
+  return new Error(`[stitchkit] the application is not ready after startup — required ${blocking.length === 1 ? "resource" : "resources"} ${blocking.join(", ")}. A required resource must be healthy for the application to be ready; ${chosen ? "a resource that is expected to start degraded belongs behind `required: false`." : "this one was healthy and stopped being so — read `onResourceFailure` for the cause."}`);
+}
+async function runStart(state) {
+  state.lifecycle = "starting";
+  publish(state);
+  let startFailure;
+  try {
+    await startEach(state, state.ordered, state.startupAbort.signal);
+    state.lifecycle = "ready";
+    publish(state);
+    await activateEach(state, state.ordered, state.startupAbort.signal);
+    if (state.shutdownRequested) {
+      throw new ApplicationStartupInterruptedError;
+    }
+    if (!isReady(state)) {
+      throw notReadyAfterStartup(state);
+    }
+    state.activationComplete = true;
+    state.accepting = isReady(state);
+    publish(state);
+    return snapshot(state);
+  } catch (error) {
+    startFailure = error;
+  }
+  if (!state.shutdownRequested) {
+    const rollbackErrors = await closeAttempted(state);
+    state.lifecycle = "failed";
+    state.accepting = false;
+    publish(state);
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError([startFailure, ...rollbackErrors], "[stitchkit] application startup and rollback failed", { cause: startFailure });
+    }
+  }
+  throw startFailure;
+}
+function start(state) {
+  if (state.startPromise)
+    return state.startPromise;
+  if (state.lifecycle !== "created") {
+    return Promise.reject(new Error(`[stitchkit] application cannot start from lifecycle "${state.lifecycle}"`));
+  }
+  const started = runStart(state);
+  state.startPromise = started;
+  started.catch(() => {
+    return;
+  });
+  return started;
+}
+
+// src/application/kernel-restart.ts
+function subtreeOf(state, resourceId) {
+  const affected = new Set([resourceId]);
+  for (const entry of state.ordered) {
+    if (entry.dependsOn.some((dependencyId) => affected.has(dependencyId))) {
+      affected.add(entry.id);
+    }
+  }
+  return state.ordered.filter((entry) => affected.has(entry.id));
+}
+async function closeOne(state, entry, record, signal, deadlines) {
+  const context = () => contextFor(state, record, { ...deadlines, signal });
+  if (record.attempted && !record.closed) {
+    const phase = async (work, what) => {
+      const settled = await untilDeadline(Promise.resolve(work), signal);
+      if (!settled.settled) {
+        throw new Error(`[stitchkit] resource "${entry.id}" did not ${what} within the restart budget`);
+      }
+      if (settled.error !== undefined)
+        throw settled.error;
+    };
+    await phase(entry.resource.stopAdmission?.(context()), "stop admitting");
+    await phase(entry.resource.drain?.(context()), "drain");
+    record.closeInvoked = true;
+    await phase(entry.resource.close?.(context()), "close");
+  }
+  record.closed = false;
+  record.closeInvoked = false;
+  record.attempted = false;
+  record.activated = false;
+  record.state = "registered";
+  record.health = "unknown";
+  record.healthReported = false;
+  record.runtime = undefined;
+  state.published.delete(entry.id);
+}
+async function runRestart(state, input) {
+  const startedAt = Date.now();
+  const parsed = ApplicationRestartInputSchema.parse(input);
+  const affected = subtreeOf(state, parsed.resourceId);
+  const affectedIds = affected.map((entry) => entry.id);
+  const refuse = (reason) => ({
+    resourceId: parsed.resourceId,
+    affected: affectedIds,
+    outcome: "refused",
+    reason,
+    durationMs: Date.now() - startedAt
+  });
+  if (!state.records.has(parsed.resourceId)) {
+    return refuse(`no resource is registered as "${parsed.resourceId}"`);
+  }
+  if (state.shutdownRequested) {
+    return refuse("the application is shutting down");
+  }
+  if (state.lifecycle !== "ready") {
+    return refuse(`the application is ${state.lifecycle}, not ready`);
+  }
+  const budget = {
+    gracePeriodMs: parsed.gracePeriodMs ?? state.shutdownBudget.gracePeriodMs,
+    forceTimeoutMs: parsed.forceTimeoutMs ?? state.shutdownBudget.forceTimeoutMs
+  };
+  const closeDeadlineAt = performance.now() + budget.gracePeriodMs;
+  const deadlines = {
+    deadlineAt: closeDeadlineAt,
+    forceDeadlineAt: closeDeadlineAt + budget.forceTimeoutMs
+  };
+  state.restartingIds = affectedIds;
+  const restartAbort = new AbortController;
+  const closeTimer = setTimeout(() => restartAbort.abort(), Math.max(0, deadlines.forceDeadlineAt - performance.now()));
+  const stillFailed = () => affectedIds.filter((id) => state.records.get(id)?.state === "failed");
+  try {
+    for (const entry of [...affected].reverse()) {
+      const record = state.records.get(entry.id);
+      if (record)
+        await closeOne(state, entry, record, restartAbort.signal, deadlines);
+    }
+    publish(state);
+    await startEach(state, affected, restartAbort.signal);
+    await activateEach(state, affected, restartAbort.signal);
+    publish(state);
+    const failed = stillFailed();
+    if (failed.length > 0) {
+      return {
+        resourceId: parsed.resourceId,
+        affected: affectedIds,
+        outcome: "failed",
+        reason: `did not come back: ${failed.join(", ")}`,
+        durationMs: Date.now() - startedAt
+      };
+    }
+    return {
+      resourceId: parsed.resourceId,
+      affected: affectedIds,
+      outcome: "restarted",
+      durationMs: Date.now() - startedAt
+    };
+  } catch (error) {
+    restartAbort.abort();
+    publish(state);
+    return {
+      resourceId: parsed.resourceId,
+      affected: affectedIds,
+      outcome: "failed",
+      reason: error instanceof Error ? error.message : String(error),
+      durationMs: Date.now() - startedAt
+    };
+  } finally {
+    state.restartingIds = [];
+    clearTimeout(closeTimer);
+    publish(state);
+  }
+}
+function restart(state, input) {
+  const queued = state.restarting.then(() => runRestart(state, input));
+  state.restarting = queued.then(() => {
+    return;
+  }, () => {
+    return;
+  });
+  return queued;
+}
+
+// src/application/kernel-shutdown.ts
+function force(shutdown, reason) {
+  if (shutdown.forcedReason)
+    return;
+  shutdown.forcedReason = reason;
+  shutdown.gracefulAbort.abort();
+  shutdown.state.lifetimeAbort.abort();
+}
+function gracefulContext(shutdown, record) {
+  return contextFor(shutdown.state, record, {
+    signal: shutdown.gracefulAbort.signal,
+    deadlineAt: shutdown.graceDeadlineAt,
+    forceDeadlineAt: shutdown.forceDeadlineAt
+  });
+}
+async function stopAdmissionSweep(shutdown) {
+  const { state } = shutdown;
+  for (const entry of state.reverse) {
+    if (shutdown.gracefulAbort.signal.aborted)
+      break;
+    const record = state.records.get(entry.id);
+    if (!record?.attempted || record.closed)
+      continue;
+    try {
+      const result = await untilDeadline(Promise.resolve(entry.resource.stopAdmission?.(gracefulContext(shutdown, record))), shutdown.gracefulAbort.signal);
+      if (!result.settled)
+        break;
+      if (result.error !== undefined)
+        throw result.error;
+    } catch (error) {
+      record.failures.push("admission");
+      reportFailure(state, entry.id, "admission", error);
+      shutdown.gracefulFailed = true;
+      state.lifetimeAbort.abort();
+    }
+  }
+}
+async function drainSweep(shutdown) {
+  const { state } = shutdown;
+  for (const entry of state.reverse) {
+    if (shutdown.gracefulAbort.signal.aborted || shutdown.gracefulFailed)
+      break;
+    const record = state.records.get(entry.id);
+    if (!record?.attempted || record.closed)
+      continue;
+    record.state = "stopping";
+    publish(state);
+    try {
+      const drained = await untilDeadline(Promise.resolve(entry.resource.drain?.(gracefulContext(shutdown, record))), shutdown.gracefulAbort.signal);
+      if (!drained.settled) {
+        force(shutdown, "deadline");
+        break;
+      }
+      if (drained.error !== undefined)
+        throw drained.error;
+    } catch (error) {
+      record.failures.push("drain");
+      reportFailure(state, entry.id, "drain", error);
+      shutdown.gracefulFailed = true;
+      state.lifetimeAbort.abort();
+      break;
+    }
+  }
+}
+async function closeSweep(shutdown) {
+  const { state } = shutdown;
+  for (const entry of state.reverse) {
+    if (shutdown.gracefulAbort.signal.aborted || shutdown.gracefulFailed)
+      break;
+    const record = state.records.get(entry.id);
+    if (!record?.attempted || record.closed || record.closeInvoked)
+      continue;
+    try {
+      record.closeInvoked = true;
+      const closed = await untilDeadline(Promise.resolve(entry.resource.close?.(gracefulContext(shutdown, record))), shutdown.gracefulAbort.signal);
+      if (!closed.settled) {
+        force(shutdown, "deadline");
+        break;
+      }
+      if (closed.error !== undefined)
+        throw closed.error;
+      record.closed = true;
+      record.state = "stopped";
+      publish(state);
+    } catch (error) {
+      record.failures.push("close");
+      reportFailure(state, entry.id, "close", error);
+      record.state = "failed";
+      shutdown.gracefulFailed = true;
+      state.lifetimeAbort.abort();
+      publish(state);
+      break;
+    }
+  }
+}
+async function forceOne(shutdown, entry, forceSignal) {
+  const { state } = shutdown;
+  const record = state.records.get(entry.id);
+  if (!record?.attempted || record.closed)
+    return;
+  try {
+    let cleanup;
+    if (entry.resource.force) {
+      cleanup = Promise.resolve(entry.resource.force(contextFor(state, record, {
+        signal: forceSignal,
+        deadlineAt: shutdown.graceDeadlineAt,
+        forceDeadlineAt: shutdown.forceDeadlineAt
+      })));
+    } else if (entry.resource.close && !record.closeInvoked) {
+      record.closeInvoked = true;
+      cleanup = Promise.resolve(entry.resource.close(contextFor(state, record, {
+        signal: forceSignal,
+        deadlineAt: shutdown.graceDeadlineAt,
+        forceDeadlineAt: shutdown.forceDeadlineAt
+      })));
+    } else if (entry.resource.close) {
+      record.failures.push("force");
+      reportFailure(state, entry.id, "force", new Error(`[stitchkit] resource "${entry.id}" was already closing and did not settle before the force deadline`));
+      return;
+    }
+    const forced = await untilDeadline(cleanup ?? Promise.resolve(), forceSignal);
+    if (!forced.settled || forced.error !== undefined) {
+      record.failures.push("force");
+      reportFailure(state, entry.id, "force", forced.settled ? forced.error : new Error("[stitchkit] forced cleanup did not settle in time"));
+      return;
+    }
+    record.closed = true;
+    record.state = "stopped";
+  } catch (error) {
+    record.failures.push("force");
+    reportFailure(state, entry.id, "force", error);
+  }
+}
+async function forceSweep(shutdown) {
+  shutdown.state.lifetimeAbort.abort();
+  const forceAbort = new AbortController;
+  const forceTimer = setTimeout(() => forceAbort.abort(), Math.max(0, shutdown.forceDeadlineAt - performance.now()));
+  await Promise.all(shutdown.state.reverse.map((entry) => forceOne(shutdown, entry, forceAbort.signal)));
+  clearTimeout(forceTimer);
+}
+function shutdownResult(shutdown, mustForce, pendingOperationsAtForce) {
+  const { state } = shutdown;
+  const cleanupComplete = [...state.records.values()].every((record) => !record.attempted || record.closed);
+  state.lifecycle = cleanupComplete ? "stopped" : "failed";
+  publish(state);
+  return ApplicationShutdownResultSchema.parse({
+    outcome: mustForce ? "forced" : "clean",
+    ...shutdown.forcedReason && { reason: shutdown.forcedReason },
+    cleanupComplete,
+    acceptedOperations: state.accepted,
+    completedOperations: state.completed,
+    pendingOperations: state.pending,
+    pendingOperationsAtForce,
+    resources: state.ordered.map((entry) => {
+      const record = recordOf(state, entry.id);
+      return {
+        id: entry.id,
+        state: !record.attempted ? "not-started" : record.closed ? "closed" : "force-failed",
+        failures: record.failures
+      };
+    }),
+    durationMs: performance.now() - shutdown.startedAt
+  });
+}
+async function runShutdown(state, parsed, startedAt) {
+  const graceDeadlineAt = startedAt + parsed.gracePeriodMs;
+  const shutdown = {
+    state,
+    startedAt,
+    graceDeadlineAt,
+    forceDeadlineAt: graceDeadlineAt + parsed.forceTimeoutMs,
+    gracefulAbort: new AbortController,
+    forcedReason: undefined,
+    gracefulFailed: [...state.records.values()].some((record) => record.attempted && record.closeInvoked && !record.closed)
+  };
+  const graceTimer = setTimeout(() => force(shutdown, "deadline"), Math.max(0, graceDeadlineAt - performance.now()));
+  const onExternalAbort = () => force(shutdown, "signal");
+  parsed.signal?.addEventListener("abort", onExternalAbort, { once: true });
+  if (parsed.signal?.aborted)
+    force(shutdown, "signal");
+  if (state.startPromise) {
+    await untilDeadline(state.startPromise.catch(() => {
+      return;
+    }), shutdown.gracefulAbort.signal);
+  }
+  await stopAdmissionSweep(shutdown);
+  if (!shutdown.gracefulAbort.signal.aborted && !shutdown.gracefulFailed) {
+    const result = await untilDeadline(waitForPending(state), shutdown.gracefulAbort.signal);
+    if (!result.settled)
+      force(shutdown, "deadline");
+  }
+  await drainSweep(shutdown);
+  state.lifecycle = "stopping";
+  publish(state);
+  await closeSweep(shutdown);
+  clearTimeout(graceTimer);
+  parsed.signal?.removeEventListener("abort", onExternalAbort);
+  const mustForce = shutdown.forcedReason !== undefined || shutdown.gracefulFailed;
+  const pendingOperationsAtForce = mustForce ? state.pending : 0;
+  if (mustForce)
+    await forceSweep(shutdown);
+  return shutdownResult(shutdown, mustForce, pendingOperationsAtForce);
+}
+function shutdown(state, options) {
+  if (state.shutdownPromise)
+    return state.shutdownPromise;
+  const requested = options ?? {};
+  const parsed = ApplicationShutdownOptionsSchema.parse({
+    gracePeriodMs: requested.gracePeriodMs ?? state.shutdownBudget.gracePeriodMs,
+    forceTimeoutMs: requested.forceTimeoutMs ?? state.shutdownBudget.forceTimeoutMs,
+    ...requested.signal !== undefined && { signal: requested.signal }
+  });
+  const startedAt = performance.now();
+  state.shutdownRequested = true;
+  state.accepting = false;
+  state.startupAbort.abort();
+  state.lifecycle = state.lifecycle === "created" ? "stopping" : "draining";
+  publish(state);
+  const stopping = runShutdown(state, parsed, startedAt);
+  state.shutdownPromise = stopping;
+  stopping.catch(() => {
+    return;
+  });
+  return stopping;
+}
+
+// src/application/kernel.ts
+function createApplication(config) {
+  const state = createKernelState(config);
+  return {
+    id: state.id,
+    admission: {
+      acquire: () => acquire(state),
+      run: (work) => run(state, work)
+    },
+    start: () => start(state),
+    getSnapshot: () => snapshot(state),
+    subscribe(listener) {
+      state.listeners.add(listener);
+      listener(snapshot(state));
+      return () => state.listeners.delete(listener);
+    },
+    shutdown: (options) => shutdown(state, options),
+    restart: (input) => restart(state, input)
+  };
+}
+
+export { ApplicationShutdownOptionsSchema, ApplicationShutdownBudgetSchema, ApplicationRestartInputSchema, ApplicationRestartOutcomeSchema, ApplicationRestartResultSchema, ApplicationAdmissionError, createApplication };