stitchkit 0.59.1 → 0.59.2

package/dist/application.js

@@ -0,0 +1,1370 @@
+import {
+  defineManagedResource
+} from "./index-yr276yz0.js";
+import {
+  ShutdownOptionsSchema
+} from "./index-dk6e56g0.js";
+import {
+  createBoundedSinkManager
+} from "./index-0nc0cddp.js";
+import"./index-1bx83sw4.js";
+
+// src/application/activity.ts
+import { z as z2 } from "zod";
+
+// src/application/latest-sink.ts
+import { z } from "zod";
+var SnapshotRevisionSchema = z.number().int().nonnegative();
+var ApplicationSnapshotSinkStatusSchema = z.object({
+  accepting: z.boolean(),
+  received: z.number().int().nonnegative(),
+  accepted: z.number().int().nonnegative(),
+  rejected: z.number().int().nonnegative(),
+  delivered: z.number().int().nonnegative(),
+  coalesced: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  inFlight: z.boolean(),
+  pending: z.boolean(),
+  lastAcceptedRevision: SnapshotRevisionSchema.optional(),
+  lastDeliveredRevision: SnapshotRevisionSchema.optional()
+}).strict().readonly();
+function createApplicationSnapshotSink(config) {
+  let accepting = true;
+  let received = 0;
+  let accepted = 0;
+  let rejected = 0;
+  let delivered = 0;
+  let coalesced = 0;
+  let failed = 0;
+  let lastAcceptedRevision;
+  let lastDeliveredRevision;
+  let inFlight;
+  let pending;
+  let closePromise;
+  let resolveClose;
+  const getStatus = () => ApplicationSnapshotSinkStatusSchema.parse({
+    accepting,
+    received,
+    accepted,
+    rejected,
+    delivered,
+    coalesced,
+    failed,
+    inFlight: inFlight !== undefined,
+    pending: pending !== undefined,
+    ...lastAcceptedRevision !== undefined && { lastAcceptedRevision },
+    ...lastDeliveredRevision !== undefined && { lastDeliveredRevision }
+  });
+  const reportFailure = (error, snapshot) => {
+    if (!config.onSinkError)
+      return;
+    Promise.resolve().then(() => config.onSinkError?.({ error, snapshot })).catch(() => {
+      return;
+    });
+  };
+  const settleCloseIfIdle = () => {
+    if (accepting || inFlight || pending || !resolveClose)
+      return;
+    const resolve = resolveClose;
+    resolveClose = undefined;
+    resolve(getStatus());
+  };
+  const startWrite = (snapshot) => {
+    const write = Promise.resolve().then(() => config.write(snapshot)).then(() => {
+      delivered += 1;
+      lastDeliveredRevision = snapshot.revision;
+    }).catch((error) => {
+      failed += 1;
+      reportFailure(error, snapshot);
+    }).finally(() => {
+      inFlight = undefined;
+      const next = pending;
+      pending = undefined;
+      if (next)
+        startWrite(next);
+      else
+        settleCloseIfIdle();
+    });
+    inFlight = write;
+  };
+  return {
+    publish(snapshot) {
+      received += 1;
+      const revision = SnapshotRevisionSchema.parse(snapshot.revision);
+      if (!accepting || lastAcceptedRevision !== undefined && revision <= lastAcceptedRevision) {
+        rejected += 1;
+        return false;
+      }
+      accepted += 1;
+      lastAcceptedRevision = revision;
+      if (!inFlight) {
+        startWrite(snapshot);
+      } else {
+        if (pending)
+          coalesced += 1;
+        pending = snapshot;
+      }
+      return true;
+    },
+    getStatus,
+    close() {
+      if (closePromise)
+        return closePromise;
+      accepting = false;
+      closePromise = new Promise((resolve) => {
+        resolveClose = resolve;
+        settleCloseIfIdle();
+      });
+      return closePromise;
+    }
+  };
+}
+
+// src/application/activity.ts
+var BoundedOperationalIdSchema = z2.string().min(1).max(64).regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/);
+var NonNegativeIntegerSchema = z2.number().int().nonnegative();
+var ActivityIdSchema = BoundedOperationalIdSchema;
+var ActivityStageIdSchema = BoundedOperationalIdSchema;
+var ActivityStageSnapshotSchema = z2.object({
+  id: ActivityStageIdSchema,
+  active: NonNegativeIntegerSchema,
+  queued: NonNegativeIntegerSchema,
+  completed: NonNegativeIntegerSchema,
+  failed: NonNegativeIntegerSchema
+}).strict().readonly();
+var ActivityTotalsSchema = z2.object({
+  active: NonNegativeIntegerSchema,
+  queued: NonNegativeIntegerSchema,
+  completed: NonNegativeIntegerSchema,
+  failed: NonNegativeIntegerSchema
+}).strict().readonly();
+var ActivitySnapshotSchema = z2.object({
+  id: ActivityIdSchema,
+  epoch: z2.string().uuid(),
+  revision: NonNegativeIntegerSchema,
+  capturedAt: z2.string().datetime({ offset: true }),
+  changedAt: z2.string().datetime({ offset: true }),
+  stages: z2.array(ActivityStageSnapshotSchema).min(1).max(64).readonly(),
+  totals: ActivityTotalsSchema
+}).strict().readonly();
+var ActivityLiveStateSchema = z2.enum(["active", "queued"]);
+var ActivityTokenBrand = Symbol("stitchkit.application.activity");
+function emptyCounters() {
+  return { active: 0, queued: 0, completed: 0, failed: 0 };
+}
+function totalsOf(stages) {
+  return stages.reduce((totals, stage) => ({
+    active: totals.active + stage.active,
+    queued: totals.queued + stage.queued,
+    completed: totals.completed + stage.completed,
+    failed: totals.failed + stage.failed
+  }), emptyCounters());
+}
+function createActivityProjection(config) {
+  const id = ActivityIdSchema.parse(config.id);
+  const declaredStages = z2.array(ActivityStageIdSchema).min(1).max(64).parse(config.stages);
+  const uniqueStages = new Set(declaredStages);
+  if (uniqueStages.size !== declaredStages.length) {
+    throw new Error("[stitchkit] createActivityProjection: stage ids must be unique");
+  }
+  const epoch = z2.string().uuid().parse(config.epoch ?? crypto.randomUUID());
+  const now = config.now ?? (() => new Date);
+  const counters = new Map(declaredStages.map((stage) => [stage, emptyCounters()]));
+  const activities = new WeakMap;
+  const subscribers = new Set;
+  let revision = 0;
+  let changedAt = now().toISOString();
+  const countersFor = (stage) => {
+    const value = counters.get(stage);
+    if (!value) {
+      throw new Error(`[stitchkit] createActivityProjection: undeclared stage "${stage}"`);
+    }
+    return value;
+  };
+  const getSnapshot = () => {
+    const stages = declaredStages.map((stage) => ({ id: stage, ...countersFor(stage) }));
+    return ActivitySnapshotSchema.parse({
+      id,
+      epoch,
+      revision,
+      capturedAt: now().toISOString(),
+      changedAt,
+      stages,
+      totals: totalsOf(stages)
+    });
+  };
+  const publishChange = () => {
+    revision += 1;
+    changedAt = now().toISOString();
+    const snapshot = getSnapshot();
+    for (const subscriber of subscribers)
+      subscriber.publish(snapshot);
+  };
+  const requireActivity = (token) => {
+    const activity = activities.get(token);
+    if (!activity) {
+      throw new Error("[stitchkit] activity token belongs to another projection");
+    }
+    return activity;
+  };
+  const leaveLiveState = (activity) => {
+    if (activity.state === "active" || activity.state === "queued") {
+      countersFor(activity.stage)[activity.state] -= 1;
+    }
+  };
+  const settle = (token, terminal) => {
+    const activity = requireActivity(token);
+    if (activity.state === "completed" || activity.state === "failed")
+      return false;
+    leaveLiveState(activity);
+    countersFor(activity.stage)[terminal] += 1;
+    activity.state = terminal;
+    publishChange();
+    return true;
+  };
+  return {
+    open(stage, rawState = "active") {
+      const parsedStage = ActivityStageIdSchema.parse(stage);
+      const state = ActivityLiveStateSchema.parse(rawState);
+      countersFor(parsedStage)[state] += 1;
+      const token = Object.freeze({
+        get [ActivityTokenBrand]() {
+          return true;
+        }
+      });
+      activities.set(token, { stage: parsedStage, state });
+      publishChange();
+      return token;
+    },
+    transition(token, input) {
+      const activity = requireActivity(token);
+      if (activity.state === "completed" || activity.state === "failed") {
+        throw new Error("[stitchkit] cannot transition a terminal activity");
+      }
+      const stage = ActivityStageIdSchema.parse(input.stage);
+      const state = ActivityLiveStateSchema.parse(input.state);
+      countersFor(stage);
+      if (activity.stage === stage && activity.state === state)
+        return false;
+      leaveLiveState(activity);
+      countersFor(stage)[state] += 1;
+      activity.stage = stage;
+      activity.state = state;
+      publishChange();
+      return true;
+    },
+    complete: (token) => settle(token, "completed"),
+    fail: (token) => settle(token, "failed"),
+    getSnapshot,
+    subscribe(listener) {
+      const sink = createApplicationSnapshotSink({
+        write: listener,
+        ...config.onSubscriberError && { onSinkError: config.onSubscriberError }
+      });
+      subscribers.add(sink);
+      sink.publish(getSnapshot());
+      return () => {
+        subscribers.delete(sink);
+        sink.close();
+      };
+    }
+  };
+}
+// src/application/events.ts
+import { z as z4 } from "zod";
+
+// src/application/schemas.ts
+import { z as z3 } from "zod";
+var ApplicationIdSchema = z3.string().min(1).max(128).regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/);
+var ApplicationLifecycleSchema = z3.enum([
+  "created",
+  "starting",
+  "ready",
+  "draining",
+  "stopping",
+  "stopped",
+  "failed"
+]);
+var ApplicationHealthSchema = z3.enum(["unknown", "healthy", "degraded", "unhealthy"]);
+var ManagedResourceStateSchema = z3.enum([
+  "registered",
+  "starting",
+  "ready",
+  "failed",
+  "stopping",
+  "stopped"
+]);
+var NonNegativeIntegerSchema2 = z3.number().int().nonnegative();
+var ApplicationAdmissionSnapshotSchema = z3.object({
+  accepting: z3.boolean(),
+  accepted: NonNegativeIntegerSchema2,
+  completed: NonNegativeIntegerSchema2,
+  pending: NonNegativeIntegerSchema2
+}).readonly();
+var ManagedResourceSnapshotSchema = z3.object({
+  id: ApplicationIdSchema,
+  required: z3.boolean(),
+  dependsOn: z3.array(ApplicationIdSchema).readonly(),
+  state: ManagedResourceStateSchema,
+  health: ApplicationHealthSchema,
+  ready: z3.boolean()
+}).readonly();
+var ApplicationSnapshotSchema = z3.object({
+  id: ApplicationIdSchema,
+  epoch: z3.string().uuid(),
+  revision: NonNegativeIntegerSchema2,
+  lifecycle: ApplicationLifecycleSchema,
+  health: ApplicationHealthSchema,
+  ready: z3.boolean(),
+  capturedAt: z3.string().datetime({ offset: true }),
+  changedAt: z3.string().datetime({ offset: true }),
+  admission: ApplicationAdmissionSnapshotSchema,
+  resources: z3.array(ManagedResourceSnapshotSchema).readonly()
+}).readonly();
+var ApplicationResourceShutdownSchema = z3.object({
+  id: ApplicationIdSchema,
+  state: z3.enum(["not-started", "closed", "force-failed"]),
+  failures: z3.array(z3.enum(["start", "ready", "completion", "admission", "drain", "close", "force"])).readonly()
+}).readonly();
+var ApplicationShutdownResultSchema = z3.object({
+  outcome: z3.enum(["clean", "forced"]),
+  reason: z3.enum(["deadline", "signal"]).optional(),
+  cleanupComplete: z3.boolean(),
+  acceptedOperations: NonNegativeIntegerSchema2,
+  completedOperations: NonNegativeIntegerSchema2,
+  pendingOperations: NonNegativeIntegerSchema2,
+  pendingOperationsAtForce: NonNegativeIntegerSchema2,
+  resources: z3.array(ApplicationResourceShutdownSchema).readonly(),
+  durationMs: z3.number().nonnegative()
+}).readonly();
+
+// src/application/events.ts
+var ApplicationLifecycleEventSchema = z4.object({
+  type: z4.literal("application-state"),
+  applicationId: ApplicationIdSchema,
+  epoch: z4.string().uuid(),
+  revision: z4.number().int().nonnegative(),
+  lifecycle: ApplicationLifecycleSchema,
+  health: ApplicationHealthSchema,
+  ready: z4.boolean(),
+  capturedAt: z4.string().datetime({ offset: true }),
+  resources: z4.array(ManagedResourceSnapshotSchema).readonly()
+}).strict().readonly();
+function applicationLifecycleEvent(snapshot) {
+  return ApplicationLifecycleEventSchema.parse({
+    type: "application-state",
+    applicationId: snapshot.id,
+    epoch: snapshot.epoch,
+    revision: snapshot.revision,
+    lifecycle: snapshot.lifecycle,
+    health: snapshot.health,
+    ready: snapshot.ready,
+    capturedAt: snapshot.capturedAt,
+    resources: snapshot.resources
+  });
+}
+function createApplicationEventSink(config) {
+  const manager = createBoundedSinkManager({
+    write: config.write,
+    ...config.maxPending !== undefined && { maxPending: config.maxPending },
+    ...config.onSinkError && { onSinkError: config.onSinkError }
+  });
+  return {
+    publish(snapshot) {
+      manager.submit(() => applicationLifecycleEvent(snapshot));
+    },
+    flush: () => manager.flush(),
+    getStatus: () => manager.getStatus(),
+    close: () => manager.close()
+  };
+}
+// src/application/health.ts
+import { z as z5 } from "zod";
+var ApplicationHealthHandlerOptionsSchema = z5.object({
+  kind: z5.enum(["liveness", "readiness"]),
+  retryAfterSeconds: z5.number().int().nonnegative().default(5)
+});
+function createApplicationHealthHandler(application, options) {
+  const parsed = ApplicationHealthHandlerOptionsSchema.parse(options);
+  return () => {
+    const snapshot = application.getSnapshot();
+    const healthy = parsed.kind === "readiness" ? snapshot.ready : snapshot.lifecycle !== "failed" && snapshot.lifecycle !== "stopped";
+    return Response.json(snapshot, {
+      status: healthy ? 200 : 503,
+      ...healthy ? {} : { headers: { "Retry-After": String(parsed.retryAfterSeconds) } }
+    });
+  };
+}
+// src/application/graph.ts
+function resolveResourceGraph(resources) {
+  const entries = resources.map((resource, declarationIndex) => ({
+    resource,
+    id: ApplicationIdSchema.parse(resource.id),
+    dependsOn: [...resource.dependsOn ?? []].map((id) => ApplicationIdSchema.parse(id)),
+    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 ApplicationAdmissionError extends Error {
+  code = "APPLICATION_NOT_ACCEPTING";
+  constructor() {
+    super("Application is not accepting new operations");
+    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 reverse = [...ordered].reverse();
+  const records = new Map;
+  for (const entry of ordered) {
+    records.set(entry.id, {
+      entry,
+      state: "registered",
+      health: "unknown",
+      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");
+  const snapshot = () => ApplicationSnapshotSchema.parse({
+    id,
+    epoch,
+    revision,
+    lifecycle,
+    health: aggregateHealth(),
+    ready: isReady(),
+    capturedAt: new Date().toISOString(),
+    changedAt,
+    admission: { accepting, accepted, completed, pending },
+    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(),
+    reportHealth(health) {
+      if (record.state === "stopped")
+        return;
+      record.health = health;
+      accepting = activationComplete && !shutdownRequested && isReady();
+      publish();
+    }
+  });
+  const markLateCompletion = (record, failure) => {
+    if (shutdownRequested || record.state === "stopping" || record.state === "stopped")
+      return;
+    if (failure)
+      record.failures.push("completion");
+    record.state = "failed";
+    record.health = "unhealthy";
+    accepting = activationComplete && isReady();
+    publish();
+  };
+  const closeAttempted = async () => {
+    const errors = [];
+    for (const entry of reverse) {
+      const record = records.get(entry.id);
+      if (!record?.attempted || record.closed)
+        continue;
+      record.state = "stopping";
+      try {
+        record.closeInvoked = true;
+        await entry.resource.close?.(contextFor(record, { signal: startupAbort.signal }));
+        record.closed = true;
+        record.state = "stopped";
+      } catch (error) {
+        record.failures.push("close");
+        record.state = "failed";
+        errors.push(error);
+      }
+      publish();
+    }
+    return errors;
+  };
+  const runStart = async () => {
+    lifecycle = "starting";
+    publish();
+    let startFailure;
+    try {
+      for (const entry of ordered) {
+        if (shutdownRequested || startupAbort.signal.aborted) {
+          throw new Error("[stitchkit] application startup interrupted by shutdown");
+        }
+        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: startupAbort.signal }));
+          if (shutdownRequested || startupAbort.signal.aborted) {
+            throw new Error("[stitchkit] application startup interrupted by shutdown");
+          }
+          if (isStartResult(started)) {
+            record.runtime = started;
+            let resourceReady = started.ready === undefined;
+            let completionSettled = false;
+            let completionFailure;
+            const completion = started.completion?.then(() => {
+              completionSettled = true;
+              if (resourceReady)
+                markLateCompletion(record, false);
+            }, (error) => {
+              completionSettled = true;
+              completionFailure = error;
+              if (resourceReady)
+                markLateCompletion(record, true);
+            });
+            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 || startupAbort.signal.aborted) {
+            throw new Error("[stitchkit] application startup interrupted by shutdown");
+          }
+          record.state = "ready";
+          record.health = "healthy";
+          publish();
+        } catch (error) {
+          if (shutdownRequested || startupAbort.signal.aborted)
+            throw error;
+          record.failures.push(error instanceof ResourceCompletionBeforeReadyError ? "completion" : record.runtime?.ready ? "ready" : "start");
+          record.state = "failed";
+          record.health = "unhealthy";
+          publish();
+          if (entry.required)
+            throw error;
+        }
+      }
+      lifecycle = "ready";
+      publish();
+      for (const entry of ordered) {
+        if (shutdownRequested || startupAbort.signal.aborted) {
+          throw new Error("[stitchkit] application startup interrupted by shutdown");
+        }
+        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 || startupAbort.signal.aborted) {
+            throw new Error("[stitchkit] application startup interrupted by shutdown");
+          }
+          record.activated = true;
+          if (entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+            throw new Error(`[stitchkit] required resource "${entry.id}" lost readiness during activation`);
+          }
+        } catch (error) {
+          if (shutdownRequested || startupAbort.signal.aborted)
+            throw error;
+          record.failures.push("start");
+          record.state = "failed";
+          record.health = "unhealthy";
+          publish();
+          if (entry.required)
+            throw error;
+        }
+      }
+      if (shutdownRequested) {
+        throw new Error("[stitchkit] application startup interrupted by shutdown");
+      }
+      if (!isReady()) {
+        throw new Error("[stitchkit] a required resource lost readiness during startup");
+      }
+      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 parsed = ShutdownOptionsSchema.parse(options ?? {});
+    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 {
+          record.failures.push("admission");
+          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 {
+          record.failures.push("drain");
+          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 {
+          record.failures.push("close");
+          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");
+              return;
+            }
+            const forced = await untilDeadline(cleanup ?? Promise.resolve(), forceAbort.signal);
+            if (!forced.settled || forced.error !== undefined) {
+              record.failures.push("force");
+              return;
+            }
+            record.closed = true;
+            record.state = "stopped";
+          } catch {
+            record.failures.push("force");
+          }
+        }));
+        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
+  };
+}
+// src/application/schedule.ts
+import { z as z6 } from "zod";
+var NonNegativeSafeIntegerSchema = z6.number().int().nonnegative().refine(Number.isSafeInteger, "Expected a safe integer");
+var PositiveSafeIntegerSchema = NonNegativeSafeIntegerSchema.refine((value) => value > 0, "Expected a positive integer");
+var ManagedScheduleOverlapSchema = z6.discriminatedUnion("mode", [
+  z6.object({ mode: z6.literal("skip") }).readonly(),
+  z6.object({ mode: z6.literal("queue-one") }).readonly(),
+  z6.object({
+    mode: z6.literal("parallel"),
+    maxConcurrent: PositiveSafeIntegerSchema
+  }).readonly()
+]);
+var ManagedScheduleErrorPolicySchema = z6.enum(["continue", "stop-schedule"]);
+var ManagedScheduleDescriptorSchema = z6.object({
+  id: ApplicationIdSchema,
+  everyMs: PositiveSafeIntegerSchema,
+  startAfterMs: NonNegativeSafeIntegerSchema,
+  overlap: ManagedScheduleOverlapSchema,
+  errorPolicy: ManagedScheduleErrorPolicySchema
+}).readonly();
+var ManagedScheduleStatusSchema = z6.object({
+  descriptor: ManagedScheduleDescriptorSchema,
+  state: z6.enum(["inactive", "scheduled", "running", "draining", "stopped"]),
+  revision: NonNegativeSafeIntegerSchema,
+  capturedAt: z6.string().datetime({ offset: true }),
+  changedAt: z6.string().datetime({ offset: true }),
+  accepting: z6.boolean(),
+  active: NonNegativeSafeIntegerSchema,
+  queued: z6.boolean(),
+  runsStarted: NonNegativeSafeIntegerSchema,
+  runsCompleted: NonNegativeSafeIntegerSchema,
+  runsFailed: NonNegativeSafeIntegerSchema,
+  ticksSkipped: NonNegativeSafeIntegerSchema,
+  nextRunAt: z6.string().datetime({ offset: true }).nullable(),
+  lastScheduledAt: z6.string().datetime({ offset: true }).nullable(),
+  lastStartedAt: z6.string().datetime({ offset: true }).nullable(),
+  lastFinishedAt: z6.string().datetime({ offset: true }).nullable()
+}).readonly();
+var systemClock = {
+  now: () => performance.now(),
+  wallNow: () => new Date,
+  schedule(callback, delayMs) {
+    const timer = setTimeout(callback, delayMs);
+    return { cancel: () => clearTimeout(timer) };
+  }
+};
+var DEFAULT_OVERLAP = { mode: "skip" };
+function createManagedSchedule(config) {
+  const descriptor = ManagedScheduleDescriptorSchema.parse({
+    id: config.id,
+    everyMs: config.everyMs,
+    startAfterMs: config.startAfterMs ?? config.everyMs,
+    overlap: config.overlap ?? DEFAULT_OVERLAP,
+    errorPolicy: config.errorPolicy ?? "continue"
+  });
+  const dependsOn = config.dependsOn?.map((id) => ApplicationIdSchema.parse(id));
+  const clock = config.clock ?? systemClock;
+  let revision = 0;
+  let accepting = false;
+  let activated = false;
+  let stopped = false;
+  let timer = null;
+  let activationContext = null;
+  let nextRunAt = null;
+  let queuedAt = null;
+  let runsStarted = 0;
+  let runsCompleted = 0;
+  let runsFailed = 0;
+  let ticksSkipped = 0;
+  let lastScheduledAt = null;
+  let lastStartedAt = null;
+  let lastFinishedAt = null;
+  let changedAt = clock.wallNow().toISOString();
+  const active = new Set;
+  const changed = () => {
+    revision += 1;
+    changedAt = clock.wallNow().toISOString();
+  };
+  const cancelFuture = () => {
+    timer?.cancel();
+    timer = null;
+    nextRunAt = null;
+    queuedAt = null;
+  };
+  const stopAdmission = () => {
+    if (!accepting && stopped)
+      return;
+    accepting = false;
+    stopped = true;
+    cancelFuture();
+    changed();
+  };
+  const reportError = (error, context) => {
+    if (!config.onError)
+      return;
+    Promise.resolve().then(() => config.onError?.(error, context)).catch(() => {});
+  };
+  const state = () => {
+    if (!activated)
+      return stopped ? "stopped" : "inactive";
+    if (!accepting)
+      return active.size > 0 ? "draining" : "stopped";
+    return active.size > 0 ? "running" : "scheduled";
+  };
+  const wallAt = (monotonicAt, anchor) => {
+    if (monotonicAt === null)
+      return null;
+    return new Date(anchor.wallNow + monotonicAt - anchor.monotonicNow).toISOString();
+  };
+  const status = () => {
+    const captured = clock.wallNow();
+    const anchor = { monotonicNow: clock.now(), wallNow: captured.getTime() };
+    return ManagedScheduleStatusSchema.parse({
+      descriptor,
+      state: state(),
+      revision,
+      capturedAt: captured.toISOString(),
+      changedAt,
+      accepting,
+      active: active.size,
+      queued: queuedAt !== null,
+      runsStarted,
+      runsCompleted,
+      runsFailed,
+      ticksSkipped,
+      nextRunAt: wallAt(nextRunAt, anchor),
+      lastScheduledAt,
+      lastStartedAt,
+      lastFinishedAt
+    });
+  };
+  let startExecution = () => {
+    return;
+  };
+  const settleExecution = () => {
+    if (!accepting || queuedAt === null || active.size !== 0)
+      return;
+    const successorAt = queuedAt;
+    queuedAt = null;
+    changed();
+    startExecution(successorAt);
+  };
+  startExecution = (scheduledAt) => {
+    const resourceContext = activationContext;
+    if (!accepting || !resourceContext)
+      return;
+    const startedAt = clock.now();
+    const wallStartedAt = clock.wallNow().getTime();
+    const runContext = {
+      applicationId: resourceContext.applicationId,
+      signal: resourceContext.signal,
+      scheduledAt,
+      startedAt,
+      now: () => clock.now()
+    };
+    runsStarted += 1;
+    lastScheduledAt = new Date(wallStartedAt + scheduledAt - startedAt).toISOString();
+    lastStartedAt = new Date(wallStartedAt).toISOString();
+    changed();
+    let tracked;
+    tracked = Promise.resolve().then(() => config.run(runContext)).then(() => {
+      runsCompleted += 1;
+      lastFinishedAt = clock.wallNow().toISOString();
+      if (descriptor.errorPolicy === "continue" && accepting) {
+        resourceContext.reportHealth("healthy");
+      }
+    }, (error) => {
+      runsFailed += 1;
+      lastFinishedAt = clock.wallNow().toISOString();
+      reportError(error, runContext);
+      if (descriptor.errorPolicy === "stop-schedule") {
+        resourceContext.reportHealth("unhealthy");
+        stopAdmission();
+      } else {
+        resourceContext.reportHealth("degraded");
+      }
+    }).finally(() => {
+      active.delete(tracked);
+      changed();
+      settleExecution();
+    });
+    active.add(tracked);
+  };
+  const dispatchTick = (scheduledAt) => {
+    if (!accepting)
+      return;
+    if (descriptor.overlap.mode === "skip") {
+      if (active.size > 0) {
+        ticksSkipped += 1;
+        changed();
+        return;
+      }
+      startExecution(scheduledAt);
+      return;
+    }
+    if (descriptor.overlap.mode === "queue-one") {
+      if (active.size > 0) {
+        queuedAt = scheduledAt;
+        changed();
+        return;
+      }
+      startExecution(scheduledAt);
+      return;
+    }
+    if (active.size >= descriptor.overlap.maxConcurrent) {
+      ticksSkipped += 1;
+      changed();
+      return;
+    }
+    startExecution(scheduledAt);
+  };
+  const arm = () => {
+    if (!accepting || nextRunAt === null)
+      return;
+    const delayMs = Math.max(0, nextRunAt - clock.now());
+    timer = clock.schedule(() => {
+      timer = null;
+      if (!accepting || nextRunAt === null)
+        return;
+      const scheduledAt = nextRunAt;
+      const observedAt = clock.now();
+      const elapsedIntervals = Math.max(1, Math.floor((observedAt - scheduledAt) / descriptor.everyMs) + 1);
+      if (elapsedIntervals > 1) {
+        ticksSkipped += elapsedIntervals - 1;
+        changed();
+      }
+      nextRunAt = scheduledAt + elapsedIntervals * descriptor.everyMs;
+      arm();
+      dispatchTick(scheduledAt);
+    }, delayMs);
+  };
+  const waitForActive = async (context, deadlineAt) => {
+    if (active.size === 0 || context.signal.aborted)
+      return;
+    await new Promise((resolve) => {
+      let settled = false;
+      let deadlineTimer = null;
+      const finish = () => {
+        if (settled)
+          return;
+        settled = true;
+        deadlineTimer?.cancel();
+        context.signal.removeEventListener("abort", finish);
+        resolve();
+      };
+      context.signal.addEventListener("abort", finish, { once: true });
+      if (deadlineAt !== undefined) {
+        deadlineTimer = clock.schedule(finish, Math.max(0, deadlineAt - context.now()));
+      }
+      Promise.allSettled([...active]).then(finish);
+    });
+  };
+  const drain = async (context) => {
+    stopAdmission();
+    await waitForActive(context, context.deadlineAt);
+  };
+  return {
+    id: descriptor.id,
+    ...dependsOn && { dependsOn },
+    ...config.required !== undefined && { required: config.required },
+    get status() {
+      return status();
+    },
+    start() {
+      if (stopped)
+        throw new Error(`[stitchkit] schedule "${descriptor.id}" is stopped`);
+    },
+    activate(context) {
+      if (activated || stopped)
+        return;
+      activated = true;
+      accepting = true;
+      activationContext = context;
+      nextRunAt = clock.now() + descriptor.startAfterMs;
+      context.reportHealth("healthy");
+      changed();
+      arm();
+    },
+    stopAdmission() {
+      stopAdmission();
+    },
+    drain,
+    close() {
+      stopAdmission();
+    },
+    async force(context) {
+      stopAdmission();
+      await waitForActive(context, context.forceDeadlineAt);
+      if (active.size > 0) {
+        throw new Error(`[stitchkit] schedule "${descriptor.id}" still has active executions`);
+      }
+    }
+  };
+}
+// src/application/server-resource.ts
+function managedServerResource(config) {
+  let shutdownPromise;
+  const getServer = () => typeof config.server === "function" ? config.server() : config.server;
+  const ensureShutdown = (context, phase = "graceful") => {
+    if (shutdownPromise)
+      return shutdownPromise;
+    const now = context.now();
+    const gracePeriodMs = phase === "force" ? 0 : Math.max(0, (context.deadlineAt ?? now) - now);
+    const forceTimeoutMs = phase === "force" ? Math.max(0, (context.forceDeadlineAt ?? now) - now) : Math.max(0, (context.forceDeadlineAt ?? context.deadlineAt ?? now) - (context.deadlineAt ?? now));
+    shutdownPromise = getServer().shutdown({
+      gracePeriodMs,
+      forceTimeoutMs,
+      retryAfterSeconds: config.retryAfterSeconds ?? 5,
+      signal: context.signal
+    });
+    shutdownPromise.catch(() => {
+      return;
+    });
+    return shutdownPromise;
+  };
+  return defineManagedResource({
+    id: config.id,
+    ...config.dependsOn && { dependsOn: config.dependsOn },
+    ...config.required !== undefined && { required: config.required },
+    start() {},
+    stopAdmission(context) {
+      ensureShutdown(context);
+    },
+    async drain() {
+      await shutdownPromise;
+    },
+    async close(context) {
+      await ensureShutdown(context);
+    },
+    async force(context) {
+      await ensureShutdown(context, "force");
+    }
+  });
+}
+export {
+  ActivityIdSchema,
+  ActivityLiveStateSchema,
+  ActivitySnapshotSchema,
+  ActivityStageIdSchema,
+  ActivityStageSnapshotSchema,
+  ApplicationAdmissionError,
+  ApplicationAdmissionSnapshotSchema,
+  ApplicationHealthHandlerOptionsSchema,
+  ApplicationHealthSchema,
+  ApplicationIdSchema,
+  ApplicationLifecycleEventSchema,
+  ApplicationLifecycleSchema,
+  ApplicationResourceShutdownSchema,
+  ApplicationShutdownResultSchema,
+  ApplicationSnapshotSchema,
+  ApplicationSnapshotSinkStatusSchema,
+  ManagedResourceSnapshotSchema,
+  ManagedResourceStateSchema,
+  ManagedScheduleDescriptorSchema,
+  ManagedScheduleErrorPolicySchema,
+  ManagedScheduleOverlapSchema,
+  ManagedScheduleStatusSchema,
+  applicationLifecycleEvent,
+  createActivityProjection,
+  createApplication,
+  createApplicationEventSink,
+  createApplicationHealthHandler,
+  createApplicationSnapshotSink,
+  createManagedSchedule,
+  defineManagedResource,
+  managedServerResource
+};