stitchkit 0.78.0 → 0.80.0

package/dist/index-evcnmsc3.js

@@ -0,0 +1,866 @@
+import {
+  managedResourceDependencyId
+} from "./index-2k4yrqkc.js";
+import {
+  ApplicationIdSchema,
+  ApplicationShutdownResultSchema,
+  ApplicationSnapshotSchema
+} from "./index-3gye9wzb.js";
+import {
+  ShutdownOptionsSchema
+} from "./index-3z73fh2c.js";
+import {
+  AppError
+} from "./index-0w9abg87.js";
+
+// src/application/kernel.ts
+import { z } from "zod";
+
+// 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.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";
+  }
+}
+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";
+  }
+}
+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 createApplication(config) {
+  const id = ApplicationIdSchema.parse(config.id);
+  const ordered = resolveResourceGraph(config.resources ?? []);
+  const shutdownBudget = ApplicationShutdownBudgetSchema.parse(config.shutdown ?? {});
+  const reverse = [...ordered].reverse();
+  const reportFailure = (resourceId, phase, error) => {
+    if (!config.onResourceFailure)
+      return;
+    try {
+      Promise.resolve(config.onResourceFailure({ resourceId, phase, error })).catch(() => {
+        return;
+      });
+    } catch {}
+  };
+  const published = new Map;
+  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: []
+    });
+  }
+  const epoch = crypto.randomUUID();
+  const listeners = new Set;
+  const lifetimeAbort = new AbortController;
+  const startupAbort = new AbortController;
+  let lifecycle = "created";
+  let revision = 0;
+  let changedAt = new Date().toISOString();
+  let accepting = false;
+  let accepted = 0;
+  let completed = 0;
+  let pending = 0;
+  let startPromise;
+  let shutdownPromise;
+  let shutdownRequested = false;
+  let activationComplete = false;
+  const pendingWaiters = new Set;
+  const aggregateHealth = () => {
+    if (lifecycle === "created" || lifecycle === "starting")
+      return "unknown";
+    let optionalUnhealthy = false;
+    for (const record of 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";
+  };
+  const isReady = () => lifecycle === "ready" && [...records.values()].every((record) => !record.entry.required || record.state === "ready" && record.health === "healthy");
+  let restartingIds = [];
+  const snapshot = () => ApplicationSnapshotSchema.parse({
+    id,
+    epoch,
+    revision,
+    lifecycle,
+    health: aggregateHealth(),
+    ready: isReady(),
+    capturedAt: new Date().toISOString(),
+    changedAt,
+    admission: { accepting, accepted, completed, pending },
+    restarting: [...restartingIds],
+    resources: ordered.map((entry) => {
+      const record = records.get(entry.id);
+      if (!record)
+        throw new Error("Managed resource record disappeared");
+      return {
+        id: entry.id,
+        required: entry.required,
+        dependsOn: entry.dependsOn,
+        state: record.state,
+        health: record.health,
+        ready: record.state === "ready" && record.health === "healthy"
+      };
+    })
+  });
+  const publish = () => {
+    revision += 1;
+    changedAt = new Date().toISOString();
+    const value = snapshot();
+    for (const listener of listeners) {
+      try {
+        listener(value);
+      } catch {}
+    }
+    if (config.onSnapshot) {
+      Promise.resolve().then(() => config.onSnapshot?.(value)).catch(() => {});
+    }
+  };
+  const contextFor = (record, options = {}) => ({
+    applicationId: id,
+    signal: options.signal ?? 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 (!published.has(dependencyId)) {
+        throw new Error(`[stitchkit] resource "${record.entry.id}" used "${dependencyId}", which published no value from start()`);
+      }
+      return published.get(dependencyId);
+    },
+    reportHealth(health) {
+      if (record.state === "stopped")
+        return;
+      record.health = health;
+      record.healthReported = true;
+      if (health === "healthy")
+        record.everHealthy = true;
+      accepting = activationComplete && !shutdownRequested && isReady();
+      publish();
+    }
+  });
+  const markLateCompletion = (record, failure) => {
+    if (shutdownRequested || record.state === "stopping" || record.state === "stopped")
+      return;
+    if (failure) {
+      record.failures.push("completion");
+      reportFailure(record.entry.id, "completion", failure.error);
+    }
+    record.state = "failed";
+    record.health = "unhealthy";
+    accepting = activationComplete && isReady();
+    publish();
+  };
+  const closeAttempted = async () => {
+    const errors = [];
+    const rollbackStartedAt = performance.now();
+    const rollbackDeadlineAt = rollbackStartedAt + shutdownBudget.gracePeriodMs;
+    const rollbackForceDeadlineAt = rollbackDeadlineAt + shutdownBudget.forceTimeoutMs;
+    const rollbackAbort = new AbortController;
+    const rollbackTimer = setTimeout(() => rollbackAbort.abort(), Math.max(0, rollbackForceDeadlineAt - performance.now()));
+    try {
+      await closeEachAttempted(rollbackAbort.signal, errors, {
+        deadlineAt: rollbackDeadlineAt,
+        forceDeadlineAt: rollbackForceDeadlineAt
+      });
+    } finally {
+      clearTimeout(rollbackTimer);
+    }
+    return errors;
+  };
+  const closeEachAttempted = async (bound, errors, deadlines) => {
+    for (const entry of reverse) {
+      const record = 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(record, { signal: 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(entry.id, "close", timedOut);
+          errors.push(timedOut);
+          publish();
+          break;
+        }
+        if (settled.error !== undefined)
+          throw settled.error;
+        record.closed = true;
+        record.state = "stopped";
+      } catch (error) {
+        record.failures.push("close");
+        record.state = "failed";
+        reportFailure(entry.id, "close", error);
+        errors.push(error);
+      }
+      publish();
+    }
+  };
+  const startEach = async (entries, signal) => {
+    for (const entry of entries) {
+      if (shutdownRequested || signal.aborted) {
+        throw new ApplicationStartupInterruptedError;
+      }
+      const record = records.get(entry.id);
+      if (!record)
+        throw new Error("Managed resource record disappeared");
+      const dependencyFailed = entry.dependsOn.some((dependencyId) => records.get(dependencyId)?.state !== "ready");
+      if (dependencyFailed) {
+        record.state = "failed";
+        record.health = "unhealthy";
+        record.failures.push("start");
+        publish();
+        if (entry.required) {
+          throw new Error(`[stitchkit] required resource "${entry.id}" has an unavailable dependency`);
+        }
+        continue;
+      }
+      record.attempted = true;
+      record.state = "starting";
+      publish();
+      try {
+        const started = await entry.resource.start(contextFor(record, { signal }));
+        if (shutdownRequested || signal.aborted) {
+          throw new ApplicationStartupInterruptedError;
+        }
+        if (isStartResult(started)) {
+          record.runtime = started;
+          if (started.value !== undefined)
+            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(record);
+          }, (error) => {
+            completionSettled = true;
+            completionFailure = error;
+            if (resourceReady)
+              markLateCompletion(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 (shutdownRequested || signal.aborted) {
+          throw new ApplicationStartupInterruptedError;
+        }
+        record.state = "ready";
+        if (!record.healthReported) {
+          record.health = "healthy";
+          record.everHealthy = true;
+        }
+        publish();
+      } catch (error) {
+        const interrupted = 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(entry.id, record.failures[record.failures.length - 1] ?? "start", error);
+          publish();
+        }
+        if (interrupted || entry.required)
+          throw error;
+      }
+    }
+  };
+  const activateEach = async (entries, signal) => {
+    for (const entry of entries) {
+      if (shutdownRequested || signal.aborted) {
+        throw new ApplicationStartupInterruptedError;
+      }
+      const record = records.get(entry.id);
+      if (record?.state !== "ready")
+        continue;
+      const dependencyUnavailable = entry.dependsOn.some((dependencyId) => {
+        const dependency = records.get(dependencyId);
+        return dependency?.state !== "ready" || !dependency.activated;
+      });
+      if (dependencyUnavailable) {
+        record.failures.push("start");
+        record.state = "failed";
+        record.health = "unhealthy";
+        publish();
+        if (entry.required) {
+          throw new Error(`[stitchkit] required resource "${entry.id}" has an unavailable activation dependency`);
+        }
+        continue;
+      }
+      try {
+        await entry.resource.activate?.(contextFor(record));
+        if (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 = shutdownRequested || signal.aborted;
+        if (!(error instanceof ApplicationStartupInterruptedError)) {
+          record.failures.push("start");
+          record.state = "failed";
+          record.health = "unhealthy";
+          reportFailure(entry.id, "start", error);
+          publish();
+        }
+        if (interrupted || entry.required)
+          throw error;
+      }
+    }
+  };
+  const subtreeOf = (resourceId) => {
+    const affected = new Set([resourceId]);
+    for (const entry of ordered) {
+      if (entry.dependsOn.some((dependencyId) => affected.has(dependencyId))) {
+        affected.add(entry.id);
+      }
+    }
+    return ordered.filter((entry) => affected.has(entry.id));
+  };
+  const closeOne = async (entry, record, signal, deadlines) => {
+    const context = () => contextFor(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;
+    published.delete(entry.id);
+  };
+  let restarting = Promise.resolve();
+  const runRestart = async (input) => {
+    const startedAt = Date.now();
+    const parsed = ApplicationRestartInputSchema.parse(input);
+    const affected = subtreeOf(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 (!records.has(parsed.resourceId)) {
+      return refuse(`no resource is registered as "${parsed.resourceId}"`);
+    }
+    if (shutdownRequested) {
+      return refuse("the application is shutting down");
+    }
+    if (lifecycle !== "ready") {
+      return refuse(`the application is ${lifecycle}, not ready`);
+    }
+    const budget = {
+      gracePeriodMs: parsed.gracePeriodMs ?? shutdownBudget.gracePeriodMs,
+      forceTimeoutMs: parsed.forceTimeoutMs ?? shutdownBudget.forceTimeoutMs
+    };
+    const closeDeadlineAt = performance.now() + budget.gracePeriodMs;
+    const deadlines = {
+      deadlineAt: closeDeadlineAt,
+      forceDeadlineAt: closeDeadlineAt + budget.forceTimeoutMs
+    };
+    restartingIds = affectedIds;
+    const restartAbort = new AbortController;
+    const closeTimer = setTimeout(() => restartAbort.abort(), Math.max(0, deadlines.forceDeadlineAt - performance.now()));
+    const stillFailed = () => affectedIds.filter((id2) => records.get(id2)?.state === "failed");
+    try {
+      for (const entry of [...affected].reverse()) {
+        const record = records.get(entry.id);
+        if (record)
+          await closeOne(entry, record, restartAbort.signal, deadlines);
+      }
+      publish();
+      await startEach(affected, restartAbort.signal);
+      await activateEach(affected, restartAbort.signal);
+      publish();
+      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();
+      return {
+        resourceId: parsed.resourceId,
+        affected: affectedIds,
+        outcome: "failed",
+        reason: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startedAt
+      };
+    } finally {
+      restartingIds = [];
+      clearTimeout(closeTimer);
+      publish();
+    }
+  };
+  const runStart = async () => {
+    lifecycle = "starting";
+    publish();
+    let startFailure;
+    try {
+      await startEach(ordered, startupAbort.signal);
+      lifecycle = "ready";
+      publish();
+      await activateEach(ordered, startupAbort.signal);
+      if (shutdownRequested) {
+        throw new ApplicationStartupInterruptedError;
+      }
+      if (!isReady()) {
+        const blocking = [...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 = [...records.values()].some((record) => record.entry.required && record.health !== "healthy" && !record.everHealthy);
+        throw 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."}`);
+      }
+      activationComplete = true;
+      accepting = isReady();
+      publish();
+      return snapshot();
+    } catch (error) {
+      startFailure = error;
+    }
+    if (!shutdownRequested) {
+      const rollbackErrors = await closeAttempted();
+      lifecycle = "failed";
+      accepting = false;
+      publish();
+      if (rollbackErrors.length > 0) {
+        throw new AggregateError([startFailure, ...rollbackErrors], "[stitchkit] application startup and rollback failed", { cause: startFailure });
+      }
+    }
+    throw startFailure;
+  };
+  const start = () => {
+    if (startPromise)
+      return startPromise;
+    if (lifecycle !== "created") {
+      return Promise.reject(new Error(`[stitchkit] application cannot start from lifecycle "${lifecycle}"`));
+    }
+    startPromise = runStart();
+    startPromise.catch(() => {
+      return;
+    });
+    return startPromise;
+  };
+  const acquire = () => {
+    if (!accepting || !isReady())
+      return null;
+    accepted += 1;
+    pending += 1;
+    publish();
+    let released = false;
+    return {
+      get released() {
+        return released;
+      },
+      release() {
+        if (released)
+          return;
+        released = true;
+        pending -= 1;
+        completed += 1;
+        if (pending === 0) {
+          for (const waiter of pendingWaiters)
+            waiter();
+          pendingWaiters.clear();
+        }
+        publish();
+      }
+    };
+  };
+  const run = async (work) => {
+    const lease = acquire();
+    if (!lease)
+      throw new ApplicationAdmissionError;
+    try {
+      return await work();
+    } finally {
+      lease.release();
+    }
+  };
+  const waitForPending = () => {
+    if (pending === 0)
+      return Promise.resolve();
+    return new Promise((resolve) => pendingWaiters.add(resolve));
+  };
+  const shutdown = (options) => {
+    if (shutdownPromise)
+      return shutdownPromise;
+    const requested = options ?? {};
+    const parsed = ApplicationShutdownOptionsSchema.parse({
+      gracePeriodMs: requested.gracePeriodMs ?? shutdownBudget.gracePeriodMs,
+      forceTimeoutMs: requested.forceTimeoutMs ?? shutdownBudget.forceTimeoutMs,
+      ...requested.signal !== undefined && { signal: requested.signal }
+    });
+    const startedAt = performance.now();
+    const graceDeadlineAt = startedAt + parsed.gracePeriodMs;
+    const forceDeadlineAt = graceDeadlineAt + parsed.forceTimeoutMs;
+    shutdownRequested = true;
+    accepting = false;
+    startupAbort.abort();
+    lifecycle = lifecycle === "created" ? "stopping" : "draining";
+    publish();
+    shutdownPromise = (async () => {
+      const gracefulAbort = new AbortController;
+      let forcedReason;
+      let gracefulFailed = [...records.values()].some((record) => record.attempted && record.closeInvoked && !record.closed);
+      const force = (reason) => {
+        if (forcedReason)
+          return;
+        forcedReason = reason;
+        gracefulAbort.abort();
+        lifetimeAbort.abort();
+      };
+      const graceTimer = setTimeout(() => force("deadline"), Math.max(0, graceDeadlineAt - performance.now()));
+      const onExternalAbort = () => force("signal");
+      parsed.signal?.addEventListener("abort", onExternalAbort, { once: true });
+      if (parsed.signal?.aborted)
+        force("signal");
+      if (startPromise) {
+        await untilDeadline(startPromise.catch(() => {
+          return;
+        }), gracefulAbort.signal);
+      }
+      const gracefulContext = (record) => contextFor(record, {
+        signal: gracefulAbort.signal,
+        deadlineAt: graceDeadlineAt,
+        forceDeadlineAt
+      });
+      for (const entry of reverse) {
+        if (gracefulAbort.signal.aborted)
+          break;
+        const record = records.get(entry.id);
+        if (!record?.attempted || record.closed)
+          continue;
+        try {
+          const result = await untilDeadline(Promise.resolve(entry.resource.stopAdmission?.(gracefulContext(record))), gracefulAbort.signal);
+          if (!result.settled)
+            break;
+          if (result.error !== undefined)
+            throw result.error;
+        } catch (error) {
+          record.failures.push("admission");
+          reportFailure(entry.id, "admission", error);
+          gracefulFailed = true;
+          lifetimeAbort.abort();
+        }
+      }
+      if (!gracefulAbort.signal.aborted && !gracefulFailed) {
+        const result = await untilDeadline(waitForPending(), gracefulAbort.signal);
+        if (!result.settled)
+          force("deadline");
+      }
+      for (const entry of reverse) {
+        if (gracefulAbort.signal.aborted || gracefulFailed)
+          break;
+        const record = records.get(entry.id);
+        if (!record?.attempted || record.closed)
+          continue;
+        record.state = "stopping";
+        publish();
+        try {
+          const drained = await untilDeadline(Promise.resolve(entry.resource.drain?.(gracefulContext(record))), gracefulAbort.signal);
+          if (!drained.settled) {
+            force("deadline");
+            break;
+          }
+          if (drained.error !== undefined)
+            throw drained.error;
+        } catch (error) {
+          record.failures.push("drain");
+          reportFailure(entry.id, "drain", error);
+          gracefulFailed = true;
+          lifetimeAbort.abort();
+          break;
+        }
+      }
+      lifecycle = "stopping";
+      publish();
+      for (const entry of reverse) {
+        if (gracefulAbort.signal.aborted || gracefulFailed)
+          break;
+        const record = 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(record))), gracefulAbort.signal);
+          if (!closed.settled) {
+            force("deadline");
+            break;
+          }
+          if (closed.error !== undefined)
+            throw closed.error;
+          record.closed = true;
+          record.state = "stopped";
+          publish();
+        } catch (error) {
+          record.failures.push("close");
+          reportFailure(entry.id, "close", error);
+          record.state = "failed";
+          gracefulFailed = true;
+          lifetimeAbort.abort();
+          publish();
+          break;
+        }
+      }
+      clearTimeout(graceTimer);
+      parsed.signal?.removeEventListener("abort", onExternalAbort);
+      const mustForce = forcedReason !== undefined || gracefulFailed;
+      const pendingOperationsAtForce = mustForce ? pending : 0;
+      if (mustForce) {
+        lifetimeAbort.abort();
+        const forceAbort = new AbortController;
+        const forceTimer = setTimeout(() => forceAbort.abort(), Math.max(0, forceDeadlineAt - performance.now()));
+        await Promise.all(reverse.map(async (entry) => {
+          const record = records.get(entry.id);
+          if (!record?.attempted || record.closed)
+            return;
+          try {
+            let cleanup;
+            if (entry.resource.force) {
+              cleanup = Promise.resolve(entry.resource.force(contextFor(record, {
+                signal: forceAbort.signal,
+                deadlineAt: graceDeadlineAt,
+                forceDeadlineAt
+              })));
+            } else if (entry.resource.close && !record.closeInvoked) {
+              record.closeInvoked = true;
+              cleanup = Promise.resolve(entry.resource.close(contextFor(record, {
+                signal: forceAbort.signal,
+                deadlineAt: graceDeadlineAt,
+                forceDeadlineAt
+              })));
+            } else if (entry.resource.close) {
+              record.failures.push("force");
+              reportFailure(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(), forceAbort.signal);
+            if (!forced.settled || forced.error !== undefined) {
+              record.failures.push("force");
+              reportFailure(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(entry.id, "force", error);
+          }
+        }));
+        clearTimeout(forceTimer);
+      }
+      const cleanupComplete = [...records.values()].every((record) => !record.attempted || record.closed);
+      lifecycle = cleanupComplete ? "stopped" : "failed";
+      publish();
+      return ApplicationShutdownResultSchema.parse({
+        outcome: mustForce ? "forced" : "clean",
+        ...forcedReason && { reason: forcedReason },
+        cleanupComplete,
+        acceptedOperations: accepted,
+        completedOperations: completed,
+        pendingOperations: pending,
+        pendingOperationsAtForce,
+        resources: ordered.map((entry) => {
+          const record = records.get(entry.id);
+          if (!record)
+            throw new Error("Managed resource record disappeared");
+          return {
+            id: entry.id,
+            state: !record.attempted ? "not-started" : record.closed ? "closed" : "force-failed",
+            failures: record.failures
+          };
+        }),
+        durationMs: performance.now() - startedAt
+      });
+    })();
+    shutdownPromise.catch(() => {
+      return;
+    });
+    return shutdownPromise;
+  };
+  return {
+    id,
+    admission: { acquire, run },
+    start,
+    getSnapshot: snapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      listener(snapshot());
+      return () => listeners.delete(listener);
+    },
+    shutdown,
+    restart(input) {
+      const queued = restarting.then(() => runRestart(input));
+      restarting = queued.then(() => {
+        return;
+      }, () => {
+        return;
+      });
+      return queued;
+    }
+  };
+}
+
+export { ApplicationShutdownOptionsSchema, ApplicationShutdownBudgetSchema, ApplicationRestartInputSchema, ApplicationRestartOutcomeSchema, ApplicationRestartResultSchema, ApplicationAdmissionError, createApplication };