stitchkit 0.93.0 → 0.94.1

package/dist/entrypoints/application/diagnostic-journal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The local diagnostic journal — the one part of the application kernel that
+ * touches the machine.
+ *
+ * Its own entrypoint because of what it reaches: `node:child_process`,
+ * `node:fs`, `node:os` and `node:util`, with `promisify(execFile)` evaluated
+ * while the module initialises. Exported from `stitchkit/application`, that one
+ * line made the entire barrel — the kernel, admission, schedules, keyspaces and
+ * every application schema, 208 names — unusable in a browser bundle, and not
+ * by failing at the call: a bundler substitutes stubs for Node built-ins, so the
+ * page died during module initialisation, on every route.
+ *
+ * Its *contract* — every `DiagnosticJournal*Schema`, the states, the refusal
+ * reasons — stays in `stitchkit/application`, because none of it touches the
+ * machine and a client reading a journal's status has as much right to those
+ * schemas as the server writing them.
+ *
+ * → ADR 0156.
+ */
+export { createDiagnosticJournal } from '../../application/diagnostic-journal.js';
+//# sourceMappingURL=diagnostic-journal.d.ts.map

package/dist/entrypoints/application/diagnostic-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-journal.d.ts","sourceRoot":"","sources":["../../../src/entrypoints/application/diagnostic-journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC"}

package/dist/entrypoints/application/diagnostic-journal.js

@@ -0,0 +1,492 @@
+import {
+  attemptExclusiveLock
+} from "../../index-8p52kd5p.js";
+import {
+  DiagnosticJournalCloseResultSchema,
+  DiagnosticJournalFrameSchema,
+  DiagnosticJournalLimitsSchema,
+  DiagnosticJournalLockPolicySchema,
+  DiagnosticJournalStatusSchema,
+  DiagnosticJournalSubmitResultSchema,
+  DiagnosticJournalWaitResultSchema,
+  parseDiagnosticJournalMode
+} from "../../index-qwhynv6x.js";
+import {
+  createBoundedChannel
+} from "../../index-d9pk3td4.js";
+import {
+  isRecord
+} from "../../index-hffjpmq9.js";
+
+// src/application/diagnostic-journal.ts
+import { randomUUID } from "node:crypto";
+
+// src/application/diagnostic-journal-manager.ts
+import { z } from "zod";
+
+// src/application/diagnostic-journal-storage.ts
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath, rename, unlink } from "node:fs/promises";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+
+// src/application/diagnostic-journal-lock.ts
+async function acquireDiagnosticJournalLock(lockPath, mode, policy, declaredIdentity) {
+  const attempt = await attemptExclusiveLock(lockPath, {
+    mode,
+    reclaim: policy === "reclaim-stale",
+    ...declaredIdentity !== undefined && { machineIdentity: declaredIdentity }
+  });
+  if ("held" in attempt) {
+    return { lock: attempt.held, reclaimedStale: attempt.held.reclaimed };
+  }
+  const { error, diagnosis } = attempt;
+  if (diagnosis && error !== null && typeof error === "object") {
+    Object.assign(error, { journalLock: diagnosis });
+  }
+  throw error;
+}
+
+// src/application/diagnostic-journal-storage.ts
+class DiagnosticJournalStorageError extends Error {
+  phase;
+  constructor(phase, message, options) {
+    super(message, options);
+    this.phase = phase;
+    this.name = "DiagnosticJournalStorageError";
+  }
+}
+function isMissing(error) {
+  return isRecord(error) && error.code === "ENOENT";
+}
+async function removeIfPresent(path) {
+  try {
+    const info = await lstat(path);
+    if (info.isSymbolicLink() || !info.isFile()) {
+      throw new Error("Diagnostic journal generations must be regular files");
+    }
+    await unlink(path);
+  } catch (error) {
+    if (!isMissing(error))
+      throw error;
+  }
+}
+async function moveIfPresent(from, to) {
+  try {
+    const info = await lstat(from);
+    if (info.isSymbolicLink() || !info.isFile()) {
+      throw new Error("Diagnostic journal generations must be regular files");
+    }
+    await rename(from, to);
+    return true;
+  } catch (error) {
+    if (isMissing(error))
+      return false;
+    throw error;
+  }
+}
+function generation(path, index) {
+  return `${path}.${index}`;
+}
+function generationIndex(name, prefix) {
+  if (!name.startsWith(prefix))
+    return;
+  const suffix = name.slice(prefix.length);
+  if (!/^\d+$/.test(suffix))
+    return;
+  const value = Number(suffix);
+  return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+async function createRotatingDiagnosticJournalStorage(config) {
+  if (!isAbsolute(config.path) || resolve(config.path) !== config.path) {
+    throw new TypeError("Diagnostic journal path must be normalized and absolute");
+  }
+  const parent = await realpath(dirname(config.path));
+  const journalPath = resolve(parent, basename(config.path));
+  const lockPath = `${journalPath}.lock`;
+  const { lock, reclaimedStale } = await acquireDiagnosticJournalLock(lockPath, config.mode, config.lock, config.machineIdentity);
+  let handle;
+  let currentFileBytes = 0;
+  let retainedFiles = 1;
+  let rotations = 0;
+  let partialTails = 0;
+  let closed = false;
+  const openCurrent = async () => {
+    handle = await open(journalPath, constants.O_APPEND | constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, config.mode);
+    const info = await handle.stat();
+    if (!info.isFile()) {
+      await handle.close();
+      handle = undefined;
+      throw new Error("Diagnostic journal path must be a regular file");
+    }
+    currentFileBytes = Number(info.size);
+  };
+  const rotate = async () => {
+    try {
+      await handle?.close();
+      handle = undefined;
+      if (config.maxFiles === 1) {
+        await removeIfPresent(journalPath);
+      } else {
+        await removeIfPresent(generation(journalPath, config.maxFiles - 1));
+        for (let index = config.maxFiles - 2;index >= 1; index -= 1) {
+          await moveIfPresent(generation(journalPath, index), generation(journalPath, index + 1));
+        }
+        await moveIfPresent(journalPath, generation(journalPath, 1));
+      }
+      retainedFiles = Math.min(config.maxFiles, retainedFiles + 1);
+      rotations += 1;
+      await openCurrent();
+    } catch (error) {
+      throw new DiagnosticJournalStorageError("rotation", "Diagnostic journal rotation failed", { cause: error });
+    }
+  };
+  try {
+    const names = await readdir(parent);
+    const prefix = `${basename(journalPath)}.`;
+    let existingGenerations = 0;
+    for (const name of names) {
+      const index = generationIndex(name, prefix);
+      if (index === undefined)
+        continue;
+      if (index >= config.maxFiles) {
+        await removeIfPresent(resolve(parent, name));
+      } else {
+        const info = await lstat(resolve(parent, name));
+        if (info.isSymbolicLink() || !info.isFile()) {
+          throw new Error("Diagnostic journal generations must be regular files");
+        }
+        existingGenerations += 1;
+      }
+    }
+    retainedFiles = Math.min(config.maxFiles, existingGenerations + 1);
+    await openCurrent();
+    if (currentFileBytes > 0) {
+      const tail = new Uint8Array(1);
+      const read = await handle?.read(tail, 0, 1, currentFileBytes - 1);
+      if (read?.bytesRead === 1 && tail[0] !== 10) {
+        partialTails += 1;
+        await rotate();
+      }
+    }
+  } catch (error) {
+    await handle?.close().catch(() => {
+      return;
+    });
+    await lock.release().catch(() => {
+      return;
+    });
+    throw error;
+  }
+  const snapshot = () => ({
+    currentFileBytes,
+    retainedFiles,
+    rotations,
+    partialTails
+  });
+  return {
+    reclaimedStale,
+    async append(bytes) {
+      if (closed || !handle) {
+        throw new DiagnosticJournalStorageError("write", "Diagnostic journal storage is closed");
+      }
+      let rotated = false;
+      if (currentFileBytes > 0 && currentFileBytes + bytes.byteLength > config.maxFileBytes) {
+        await rotate();
+        rotated = true;
+      }
+      try {
+        await handle.writeFile(bytes);
+        currentFileBytes += bytes.byteLength;
+        return { ...snapshot(), rotated };
+      } catch (error) {
+        throw new DiagnosticJournalStorageError("write", "Diagnostic journal write failed", {
+          cause: error
+        });
+      }
+    },
+    snapshot,
+    async close() {
+      if (closed)
+        return;
+      closed = true;
+      let failure;
+      try {
+        await handle?.close();
+      } catch (error) {
+        failure = error;
+      }
+      try {
+        await lock.release();
+      } catch (error) {
+        failure ??= error;
+      }
+      if (failure !== undefined) {
+        throw new DiagnosticJournalStorageError("close", "Diagnostic journal close failed", {
+          cause: failure
+        });
+      }
+    }
+  };
+}
+
+// src/application/diagnostic-journal-manager.ts
+function waitBudget(options) {
+  if (options.timeoutMs === undefined)
+    return;
+  if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0) {
+    throw new TypeError("Diagnostic journal timeoutMs must be a positive safe integer");
+  }
+  return options.timeoutMs;
+}
+var NO_REFUSALS = {
+  closed: 0,
+  failed: 0,
+  invalid: 0,
+  oversized: 0,
+  "item-capacity": 0,
+  "byte-capacity": 0
+};
+function waitForProgress(progressWaiters, predicate, options) {
+  const timeoutMs = waitBudget(options);
+  if (predicate())
+    return Promise.resolve("settled");
+  if (options.signal?.aborted)
+    return Promise.resolve("cancelled");
+  return new Promise((resolve2) => {
+    let settled = false;
+    let timer;
+    const finish = (outcome) => {
+      if (settled)
+        return;
+      settled = true;
+      progressWaiters.delete(onProgress);
+      options.signal?.removeEventListener("abort", onAbort);
+      if (timer)
+        clearTimeout(timer);
+      resolve2(outcome);
+    };
+    const onProgress = () => {
+      if (predicate())
+        finish("settled");
+    };
+    const onAbort = () => finish("cancelled");
+    progressWaiters.add(onProgress);
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (timeoutMs !== undefined)
+      timer = setTimeout(() => finish("timed-out"), timeoutMs);
+    onProgress();
+  });
+}
+function createDiagnosticJournalManager(config, storage) {
+  const limits = DiagnosticJournalLimitsSchema.parse(config.limits);
+  const encoder = new TextEncoder;
+  const channel = createBoundedChannel({
+    policy: "ordered",
+    maxItems: limits.maxPendingItems,
+    maxBytes: limits.maxPendingBytes,
+    sizeOf: (frame) => frame.bytes.byteLength
+  });
+  const refusals = {
+    ...NO_REFUSALS
+  };
+  const progressWaiters = new Set;
+  let state = "open";
+  let received = 0;
+  let accepted = 0;
+  let refused = 0;
+  let written = 0;
+  let failedRecords = 0;
+  let pendingItems = 0;
+  let pendingBytes = 0;
+  let inFlight = false;
+  let rotationFailures = 0;
+  let lastAcceptedSequence = 0;
+  let lastWrittenSequence = 0;
+  let lastSettledSequence = 0;
+  let lastFailure;
+  let physicalClosed = false;
+  const isFailed = () => state === "failed";
+  const notifyProgress = () => {
+    for (const waiter of progressWaiters)
+      waiter();
+  };
+  const reportFailure = (failure) => {
+    if (!config.onFailure)
+      return;
+    Promise.resolve().then(() => config.onFailure?.(failure)).catch(() => {
+      return;
+    });
+  };
+  const markFailure = (error, fallbackPhase, sequence) => {
+    const phase = error instanceof DiagnosticJournalStorageError ? error.phase : fallbackPhase;
+    if (phase === "rotation")
+      rotationFailures += 1;
+    lastFailure = { phase, ...sequence !== undefined && { sequence } };
+    state = "failed";
+    channel.close({ mode: "drain" });
+    reportFailure({ phase, error, ...sequence !== undefined && { sequence } });
+  };
+  const worker = (async () => {
+    for await (const frame of channel) {
+      inFlight = true;
+      if (isFailed()) {
+        failedRecords += 1;
+      } else {
+        try {
+          await storage.append(frame.bytes);
+          written += 1;
+          lastWrittenSequence = frame.sequence;
+        } catch (error) {
+          failedRecords += 1;
+          markFailure(error, "write", frame.sequence);
+        }
+      }
+      pendingItems -= 1;
+      pendingBytes -= frame.bytes.byteLength;
+      lastSettledSequence = frame.sequence;
+      inFlight = false;
+      notifyProgress();
+    }
+    try {
+      await storage.close();
+    } catch (error) {
+      markFailure(error, "close");
+    }
+    physicalClosed = true;
+    if (!isFailed())
+      state = "closed";
+    notifyProgress();
+  })();
+  worker.catch((error) => {
+    markFailure(error, "close");
+    physicalClosed = true;
+    notifyProgress();
+  });
+  const refuse = (reason) => {
+    refused += 1;
+    refusals[reason] += 1;
+    return DiagnosticJournalSubmitResultSchema.parse({ outcome: "refused", reason });
+  };
+  const waitUntil = (predicate, options) => waitForProgress(progressWaiters, predicate, options);
+  const getStatus = () => {
+    const file = storage.snapshot();
+    return DiagnosticJournalStatusSchema.parse({
+      state,
+      epoch: config.epoch,
+      limits,
+      lock: config.lock,
+      received,
+      accepted,
+      refused,
+      refusals,
+      written,
+      failedRecords,
+      pendingItems,
+      pendingBytes,
+      inFlight,
+      rotations: file.rotations,
+      rotationFailures,
+      partialTails: file.partialTails,
+      currentFileBytes: file.currentFileBytes,
+      retainedFiles: file.retainedFiles,
+      ...lastAcceptedSequence > 0 && { lastAcceptedSequence },
+      ...lastWrittenSequence > 0 && { lastWrittenSequence },
+      ...lastSettledSequence > 0 && { lastSettledSequence },
+      ...lastFailure && { lastFailure }
+    });
+  };
+  return {
+    submit(event) {
+      received += 1;
+      if (state === "failed")
+        return refuse("failed");
+      if (state !== "open")
+        return refuse("closed");
+      const parsed = config.eventSchema.safeParse(event);
+      if (!parsed.success)
+        return refuse("invalid");
+      const json = z.json().safeParse(parsed.data);
+      if (!json.success)
+        return refuse("invalid");
+      const payload = encoder.encode(JSON.stringify(json.data));
+      if (payload.byteLength > limits.maxEventBytes)
+        return refuse("oversized");
+      if (pendingItems >= limits.maxPendingItems)
+        return refuse("item-capacity");
+      const sequence = lastAcceptedSequence + 1;
+      const frame = DiagnosticJournalFrameSchema.parse({
+        schemaVersion: 1,
+        epoch: config.epoch,
+        sequence,
+        event: json.data
+      });
+      const bytes = encoder.encode(`${JSON.stringify(frame)}
+`);
+      if (bytes.byteLength > limits.maxFileBytes)
+        return refuse("oversized");
+      if (pendingBytes + bytes.byteLength > limits.maxPendingBytes) {
+        return refuse("byte-capacity");
+      }
+      const offered = channel.offer({ sequence, bytes });
+      if (offered.outcome === "refused") {
+        return refuse(offered.reason === "not-open" ? "closed" : "item-capacity");
+      }
+      accepted += 1;
+      pendingItems += 1;
+      pendingBytes += bytes.byteLength;
+      lastAcceptedSequence = sequence;
+      return DiagnosticJournalSubmitResultSchema.parse({
+        outcome: "accepted",
+        epoch: config.epoch,
+        sequence
+      });
+    },
+    async flush(options = {}) {
+      const throughSequence = lastAcceptedSequence;
+      const outcome = await waitUntil(() => lastSettledSequence >= throughSequence, options);
+      return DiagnosticJournalWaitResultSchema.parse({
+        outcome,
+        state,
+        throughSequence,
+        settledSequence: lastSettledSequence
+      });
+    },
+    getStatus,
+    async close(options = {}) {
+      if (state === "open") {
+        state = "draining";
+        channel.close({ mode: "drain" });
+      }
+      const wait = await waitUntil(() => physicalClosed, options);
+      return DiagnosticJournalCloseResultSchema.parse({
+        outcome: wait === "settled" ? "closed" : wait,
+        state,
+        pendingItems
+      });
+    }
+  };
+}
+
+// src/application/diagnostic-journal.ts
+async function createDiagnosticJournal(config) {
+  const limits = DiagnosticJournalLimitsSchema.parse(config.limits);
+  const lock = DiagnosticJournalLockPolicySchema.parse(config.lock ?? "refuse");
+  const storage = await createRotatingDiagnosticJournalStorage({
+    path: config.path,
+    maxFileBytes: limits.maxFileBytes,
+    maxFiles: limits.maxFiles,
+    mode: parseDiagnosticJournalMode(config.mode),
+    lock,
+    ...config.machineIdentity !== undefined && { machineIdentity: config.machineIdentity }
+  });
+  return createDiagnosticJournalManager({
+    eventSchema: config.eventSchema,
+    epoch: randomUUID(),
+    limits,
+    lock: { policy: lock, reclaimedStale: storage.reclaimedStale },
+    ...config.onFailure && { onFailure: config.onFailure }
+  }, storage);
+}
+export {
+  createDiagnosticJournal
+};

package/dist/entrypoints/application/grammy.d.ts

@@ -0,0 +1,2 @@
+export { createGrammyWebhookResource, type GrammyPollingResourceConfig, type GrammyUpdate, type GrammyWebhookResource, type GrammyWebhookResourceConfig, GrammyWebhookUnavailableError, grammyPollingResource, } from '../../application/grammy.js';
+//# sourceMappingURL=grammy.d.ts.map

package/dist/entrypoints/application/grammy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammy.d.ts","sourceRoot":"","sources":["../../../src/entrypoints/application/grammy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,6BAA6B,EAC7B,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}

package/dist/entrypoints/application/grammy.js

@@ -0,0 +1,169 @@
+import {
+  defineManagedResource
+} from "../../index-2k4yrqkc.js";
+import {
+  AppError
+} from "../../index-2vtcmrj9.js";
+
+// src/application/grammy.ts
+import { Context } from "grammy";
+if (typeof Context !== "function") {
+  throw new TypeError("[stitchkit] stitchkit/application/grammy requires the grammY peer");
+}
+function reportIsolated(callback, error) {
+  if (!callback)
+    return;
+  Promise.resolve().then(() => callback(error)).catch(() => {});
+}
+function grammyPollingResource(config) {
+  let completion;
+  let stopPromise;
+  const stop = () => {
+    if (!stopPromise) {
+      stopPromise = Promise.resolve().then(() => config.bot.stop());
+      stopPromise.catch((error) => reportIsolated(config.onError, error));
+    }
+    return stopPromise;
+  };
+  return defineManagedResource({
+    id: config.id,
+    ...config.dependsOn && { dependsOn: config.dependsOn },
+    ...config.required !== undefined && { required: config.required },
+    start() {
+      let resolveReady = () => {
+        return;
+      };
+      let rejectReady = () => {
+        return;
+      };
+      let becameReady = false;
+      const ready = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+      });
+      const polling = config.bot.start({
+        ...config.polling,
+        onStart: async (botInfo) => {
+          await config.onStart?.(botInfo);
+          becameReady = true;
+          resolveReady();
+        }
+      });
+      completion = polling.then(() => {
+        if (!becameReady) {
+          rejectReady(new Error("[stitchkit] grammY polling stopped before reaching readiness"));
+        }
+      }, (error) => {
+        if (!becameReady)
+          rejectReady(error);
+        reportIsolated(config.onError, error);
+        throw error;
+      });
+      completion.catch(() => {
+        return;
+      });
+      return { ready, completion };
+    },
+    stopAdmission() {
+      return stop();
+    },
+    async drain() {
+      await completion;
+    },
+    async close() {
+      await stop();
+      if (completion)
+        await completion.catch(() => {
+          return;
+        });
+    },
+    async force() {
+      await stop();
+      if (completion)
+        await completion.catch(() => {
+          return;
+        });
+    }
+  });
+}
+function grammyNodeSignal(signal) {
+  return signal;
+}
+
+class GrammyWebhookUnavailableError extends AppError {
+  constructor() {
+    super("GRAMMY_WEBHOOK_NOT_ACCEPTING", "grammY webhook resource is not accepting updates", 503);
+    this.name = "GrammyWebhookUnavailableError";
+  }
+}
+function createGrammyWebhookResource(config) {
+  let accepting = false;
+  let pending = 0;
+  const waiters = new Set;
+  const waitForIdle = (signal) => {
+    if (pending === 0 || signal.aborted)
+      return Promise.resolve();
+    return new Promise((resolve) => {
+      const finish = () => {
+        signal.removeEventListener("abort", finish);
+        waiters.delete(finish);
+        resolve();
+      };
+      waiters.add(finish);
+      signal.addEventListener("abort", finish, { once: true });
+    });
+  };
+  const resource = defineManagedResource({
+    id: config.id,
+    ...config.dependsOn && { dependsOn: config.dependsOn },
+    ...config.required !== undefined && { required: config.required },
+    async start(context) {
+      await config.bot.init(grammyNodeSignal(context.signal));
+    },
+    activate() {
+      accepting = true;
+    },
+    stopAdmission() {
+      accepting = false;
+    },
+    drain(context) {
+      return waitForIdle(context.signal);
+    },
+    close() {
+      accepting = false;
+    },
+    async force(context) {
+      accepting = false;
+      await waitForIdle(context.signal);
+      if (pending > 0) {
+        throw new Error("[stitchkit] grammY webhook middleware remained active at force deadline");
+      }
+    }
+  });
+  return {
+    resource,
+    async handleUpdate(update, webhookReplyEnvelope) {
+      if (!accepting)
+        throw new GrammyWebhookUnavailableError;
+      pending += 1;
+      try {
+        await config.bot.handleUpdate(update, webhookReplyEnvelope);
+      } catch (error) {
+        reportIsolated(config.onError, error);
+        throw error;
+      } finally {
+        pending -= 1;
+        if (pending === 0) {
+          for (const waiter of waiters)
+            waiter();
+          waiters.clear();
+        }
+      }
+    }
+  };
+}
+export {
+  grammyPollingResource,
+  createGrammyWebhookResource,
+  GrammyWebhookUnavailableError
+};

package/dist/entrypoints/application/opentelemetry.d.ts

@@ -0,0 +1,2 @@
+export { type ApplicationOpenTelemetryBinding, type ApplicationOpenTelemetryCollectionError, type ApplicationOpenTelemetryConfig, type ApplicationTelemetryMeter, createApplicationOpenTelemetry, } from '../../application/opentelemetry.js';
+//# sourceMappingURL=opentelemetry.d.ts.map

package/dist/entrypoints/application/opentelemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opentelemetry.d.ts","sourceRoot":"","sources":["../../../src/entrypoints/application/opentelemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,+BAA+B,EACpC,KAAK,uCAAuC,EAC5C,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC9B,8BAA8B,GAC/B,MAAM,iCAAiC,CAAC"}