stitchkit 0.74.1 → 0.75.1

package/dist/application.js

@@ -24,6 +24,10 @@ import {
 import {
   createBoundedSinkManager
 } from "./index-a59da114.js";
+import {
+  argumentsDigest,
+  stableValue
+} from "./index-vdvmcy7r.js";
 import {
   ApplicationAdmissionError,
   ApplicationShutdownBudgetSchema,
@@ -48,6 +52,7 @@ import {
   projectApplicationStatus
 } from "./index-8eywc9zv.js";
 import"./index-3z73fh2c.js";
+import"./index-rxfy4cq7.js";
 import"./index-0w9abg87.js";
 import {
   isRecord
@@ -1211,6 +1216,138 @@ function createApplicationOperationalHandlers(application, options = {}) {
     })
   };
 }
+// src/application/keyspace.ts
+function defineKeyspace(name, declaration) {
+  if (name.trim() === "") {
+    throw new Error("[stitchkit] defineKeyspace: a keyspace needs a name.");
+  }
+  return { name, schema: declaration.schema, key: declaration.key };
+}
+function keyspaceResource(declaration, config) {
+  const maxPending = config.maxPendingWrites ?? 1024;
+  const records = new Map;
+  let admitting = true;
+  let pending = 0;
+  let chain = Promise.resolve();
+  function run2(work) {
+    if (!admitting) {
+      return Promise.reject(new Error(`[stitchkit] keyspace "${declaration.name}" is shutting down and is not accepting writes.`));
+    }
+    if (pending >= maxPending) {
+      return Promise.reject(new Error(`[stitchkit] keyspace "${declaration.name}": ${pending} writes are already waiting for the backend (limit ${maxPending}). The backend is not keeping up; queueing this one would trade a visible refusal for an invisible leak.`));
+    }
+    pending += 1;
+    const queued = chain.then(work, work);
+    chain = queued.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return queued.finally(() => {
+      pending -= 1;
+    });
+  }
+  const keyspace = {
+    get: (key) => records.get(key),
+    list: () => [...records.values()],
+    get size() {
+      return records.size;
+    },
+    put(value) {
+      const parsed = declaration.schema.parse(value);
+      const key = declaration.key(parsed);
+      return run2(async () => {
+        await config.backend.put(key, parsed);
+        records.set(key, parsed);
+        config.onChanged?.({
+          keyspace: declaration.name,
+          key,
+          value: parsed,
+          change: "put"
+        });
+      });
+    },
+    delete(key) {
+      return run2(async () => {
+        await config.backend.delete(key);
+        records.delete(key);
+        config.onChanged?.({ keyspace: declaration.name, key, change: "delete" });
+      });
+    },
+    pendingWrites: () => pending
+  };
+  function reportUnwritten() {
+    if (pending > 0)
+      config.onUnwritten?.(pending);
+  }
+  return {
+    id: config.id ?? `keyspace:${declaration.name}`,
+    ...config.dependsOn && { dependsOn: config.dependsOn },
+    async start(_context) {
+      for (const stored of await config.backend.load()) {
+        const value = declaration.schema.parse(stored);
+        records.set(declaration.key(value), value);
+      }
+      return { value: keyspace };
+    },
+    stopAdmission() {
+      admitting = false;
+    },
+    async drain() {
+      await chain;
+    },
+    async close() {
+      reportUnwritten();
+      await config.backend.close?.();
+    },
+    force() {
+      reportUnwritten();
+    }
+  };
+}
+function memoryKeyspaceBackend() {
+  const stored = new Map;
+  return {
+    load: async () => [...stored.values()],
+    put: async (key, value) => {
+      stored.set(key, value);
+    },
+    delete: async (key) => {
+      stored.delete(key);
+    }
+  };
+}
+// src/application/keyspace-sqlite.ts
+var IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function sqliteKeyspaceBackend(declaration, config) {
+  const table = config.table ?? `stitchkit_keyspace_${declaration.name}`;
+  if (!IDENTIFIER.test(table)) {
+    throw new Error(`[stitchkit] sqliteKeyspaceBackend: "${table}" is not a bare SQL identifier. A table name cannot be a bound parameter, so it is checked here rather than interpolated on trust. Pass \`table\` explicitly when the keyspace name is not identifier-shaped.`);
+  }
+  const database = config.database;
+  if (config.initialize !== false) {
+    database.exec(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, payload TEXT NOT NULL)`);
+  }
+  return {
+    async load() {
+      const rows = database.prepare(`SELECT payload FROM ${table}`).all();
+      return rows.map((row) => {
+        const payload = Reflect.get(Object(row), "payload");
+        if (typeof payload !== "string") {
+          throw new Error(`[stitchkit] keyspace "${declaration.name}": a row in ${table} has no text payload.`);
+        }
+        return JSON.parse(payload);
+      });
+    },
+    async put(key, value) {
+      database.prepare(`INSERT INTO ${table} (key, payload) VALUES (?, ?)
+             ON CONFLICT(key) DO UPDATE SET payload = excluded.payload`).run(key, JSON.stringify(value));
+    },
+    async delete(key) {
+      database.prepare(`DELETE FROM ${table} WHERE key = ?`).run(key);
+    }
+  };
+}
 // src/application/server-resource.ts
 function managedServerResource(config) {
   let shutdownPromise;
@@ -1270,12 +1407,330 @@ function managedServerResource(config) {
     }
   });
 }
+// src/browser/resumable.ts
+import { z as z6 } from "zod";
+var PositiveSafeIntegerSchema3 = z6.number().int().positive().safe();
+var BackoffPolicySchema = z6.object({
+  minDelayMs: PositiveSafeIntegerSchema3,
+  maxDelayMs: PositiveSafeIntegerSchema3,
+  jitter: z6.number().min(0).max(1)
+}).strict().readonly().refine((policy) => policy.maxDelayMs >= policy.minDelayMs, {
+  message: "maxDelayMs must be at least minDelayMs"
+});
+function createBackoff(policy, random = Math.random) {
+  const { minDelayMs, maxDelayMs, jitter } = BackoffPolicySchema.parse(policy);
+  let attempt = 0;
+  return {
+    next() {
+      const exponential = Math.min(maxDelayMs, minDelayMs * 2 ** attempt);
+      attempt += 1;
+      const spread = exponential * jitter * random();
+      return Math.max(1, Math.round(exponential - spread));
+    },
+    reset() {
+      attempt = 0;
+    }
+  };
+}
+
+// src/live/watch-contract.ts
+import { z as z8 } from "zod";
+
+// src/browser/live-state.ts
+import { z as z7 } from "zod";
+var PositiveSafeIntegerSchema4 = z7.number().int().positive().safe();
+var LiveStatePhaseSchema = z7.enum([
+  "idle",
+  "opening",
+  "live",
+  "resync-required",
+  "unavailable",
+  "closed"
+]);
+var LiveStateStopReasonSchema = z7.enum([
+  "gap",
+  "buffer-overflow",
+  "source-unavailable",
+  "source-error",
+  "controller-error",
+  "controller-capacity"
+]);
+var LiveStateControllerStatusSchema = z7.object({
+  phase: LiveStatePhaseSchema,
+  generation: z7.number().int().nonnegative(),
+  hasValue: z7.boolean(),
+  bufferedEvents: z7.number().int().nonnegative(),
+  bufferedBytes: z7.number().int().nonnegative(),
+  receivedEvents: z7.number().int().nonnegative(),
+  appliedEvents: z7.number().int().nonnegative(),
+  duplicateEvents: z7.number().int().nonnegative(),
+  gapEvents: z7.number().int().nonnegative(),
+  refusedEvents: z7.number().int().nonnegative(),
+  reason: LiveStateStopReasonSchema.optional()
+}).strict().readonly();
+
+// src/live/watch-contract.ts
+var WatchKeySchema = z8.object({
+  service: z8.string().min(1),
+  action: z8.string().min(1),
+  digest: z8.string().min(1)
+}).strict().readonly();
+var WatchOpenSchema = z8.object({ key: WatchKeySchema, args: z8.unknown() }).readonly();
+var WatchAcceptedSchema = z8.object({
+  accepted: z8.boolean(),
+  reason: z8.string().optional()
+}).strict().readonly();
+var WatchValueSchema = z8.object({
+  key: WatchKeySchema,
+  revision: z8.number().int().nonnegative(),
+  value: z8.unknown()
+}).readonly();
+var WatchStateSchema = z8.object({
+  key: WatchKeySchema,
+  phase: LiveStatePhaseSchema,
+  reason: LiveStateStopReasonSchema.optional(),
+  code: z8.string().optional(),
+  message: z8.string().optional()
+}).readonly();
+var WATCH_OPEN = "stitchkit.watch.open";
+var WATCH_CLOSE = "stitchkit.watch.close";
+var WATCH_VALUE = "stitchkit.watch.value";
+var WATCH_STATE = "stitchkit.watch.state";
+var watchContract = {
+  serverToClient: {
+    [WATCH_VALUE]: { args: z8.tuple([WatchValueSchema]) },
+    [WATCH_STATE]: { args: z8.tuple([WatchStateSchema]) }
+  },
+  clientToServer: {
+    [WATCH_OPEN]: { args: z8.tuple([WatchOpenSchema]), ack: WatchAcceptedSchema },
+    [WATCH_CLOSE]: { args: z8.tuple([z8.object({ key: WatchKeySchema }).readonly()]) }
+  }
+};
+function watchKeyString(key) {
+  return `${key.service}/${key.action}/${key.digest}`;
+}
+
+// src/application/watch-hub.ts
+var DEFAULT_BACKOFF = { minDelayMs: 250, maxDelayMs: 30000, jitter: 0.2 };
+async function watchKey(operation, args) {
+  const record = typeof args === "object" && args !== null && !Array.isArray(args) ? args : { value: args };
+  return {
+    service: operation.service,
+    action: operation.action,
+    digest: await argumentsDigest(record)
+  };
+}
+function createWatchHub(config) {
+  const sources = new Map;
+  const held = new Map;
+  const maxWatches = config.maxWatchesPerSubscriber ?? 64;
+  const holdMs = config.holdMs ?? 0;
+  const same = config.same ?? ((previous, next) => JSON.stringify(stableValue(previous)) === JSON.stringify(stableValue(next)));
+  let reads = 0;
+  let closed = false;
+  function announceState(source, state) {
+    source.state = state;
+    for (const subscriber of source.subscribers)
+      subscriber.state(state);
+  }
+  function publish(source, value) {
+    source.revision += 1;
+    source.value = value;
+    const frame = { key: source.key, revision: source.revision, value };
+    for (const subscriber of source.subscribers)
+      subscriber.value(frame);
+  }
+  async function pump(source) {
+    if (source.reading || closed)
+      return;
+    source.reading = true;
+    try {
+      while (source.dirty && !closed) {
+        source.dirty = false;
+        reads += 1;
+        try {
+          const value = await config.read(source.operation, source.args);
+          source.backoff.reset();
+          const signature = JSON.stringify(stableValue(value));
+          const unchanged = source.signature !== undefined && same(source.value, value);
+          source.signature = signature;
+          if (!unchanged)
+            publish(source, value);
+          if (source.state.phase !== "live") {
+            announceState(source, { key: source.key, phase: "live" });
+          }
+        } catch (error) {
+          const code = readErrorCode(error);
+          announceState(source, {
+            key: source.key,
+            phase: "unavailable",
+            reason: "source-error",
+            ...code !== undefined && { code },
+            message: error instanceof Error ? error.message : String(error)
+          });
+          config.logger?.warn?.("[stitchkit] watched read failed", {
+            key: watchKeyString(source.key),
+            error
+          });
+          scheduleRetry(source);
+          return;
+        }
+      }
+    } finally {
+      source.reading = false;
+    }
+  }
+  function scheduleRetry(source) {
+    if (closed || source.subscribers.size === 0)
+      return;
+    clearTimeout(source.retry);
+    source.retry = setTimeout(() => {
+      source.dirty = true;
+      pump(source);
+    }, source.backoff.next());
+    source.retry.unref?.();
+  }
+  function acquire(operation, key, args) {
+    const id = watchKeyString(key);
+    const existing = sources.get(id);
+    if (existing) {
+      clearTimeout(existing.release);
+      existing.release = undefined;
+      return existing;
+    }
+    const source = {
+      key,
+      operation,
+      args,
+      subscribers: new Set,
+      unsubscribes: [],
+      revision: 0,
+      reading: false,
+      dirty: true,
+      state: { key, phase: "opening" },
+      backoff: createBackoff(config.backoff ?? DEFAULT_BACKOFF)
+    };
+    for (const topic of config.invalidatedBy(operation)) {
+      source.unsubscribes.push(config.subscribe(topic, () => {
+        source.dirty = true;
+        pump(source);
+      }));
+    }
+    sources.set(id, source);
+    return source;
+  }
+  function release(source) {
+    if (source.subscribers.size > 0)
+      return;
+    clearTimeout(source.retry);
+    source.retry = undefined;
+    const drop = () => {
+      if (source.reading) {
+        source.release = setTimeout(drop, 10);
+        source.release.unref?.();
+        return;
+      }
+      for (const unsubscribe of source.unsubscribes)
+        unsubscribe();
+      sources.delete(watchKeyString(source.key));
+    };
+    if (holdMs === 0) {
+      drop();
+      return;
+    }
+    source.release = setTimeout(drop, holdMs);
+    source.release.unref?.();
+  }
+  return {
+    attach(subscriber) {
+      const keys = new Set;
+      held.set(subscriber, keys);
+      return {
+        open(key, args) {
+          if (closed)
+            return { accepted: false, reason: "the watch hub is closed" };
+          const operation = { service: key.service, action: key.action };
+          if (!config.watchable(operation)) {
+            return {
+              accepted: false,
+              reason: `${key.service}.${key.action} is not watchable`
+            };
+          }
+          const id = watchKeyString(key);
+          if (keys.has(id))
+            return { accepted: true };
+          if (keys.size >= maxWatches) {
+            return {
+              accepted: false,
+              reason: `this connection is already watching ${keys.size} reads (limit ${maxWatches})`
+            };
+          }
+          const source = acquire(operation, key, args);
+          source.subscribers.add(subscriber);
+          keys.add(id);
+          if (source.signature !== undefined) {
+            subscriber.value({ key, revision: source.revision, value: source.value });
+          }
+          subscriber.state(source.state);
+          pump(source);
+          return { accepted: true };
+        },
+        close(key) {
+          const id = watchKeyString(key);
+          if (!keys.delete(id))
+            return;
+          const source = sources.get(id);
+          if (!source)
+            return;
+          source.subscribers.delete(subscriber);
+          release(source);
+        },
+        detach() {
+          for (const id of keys) {
+            const source = sources.get(id);
+            if (!source)
+              continue;
+            source.subscribers.delete(subscriber);
+            release(source);
+          }
+          keys.clear();
+          held.delete(subscriber);
+        }
+      };
+    },
+    readCount: () => reads,
+    size: () => sources.size,
+    close() {
+      closed = true;
+      for (const source of sources.values()) {
+        clearTimeout(source.retry);
+        clearTimeout(source.release);
+        for (const unsubscribe of source.unsubscribes)
+          unsubscribe();
+      }
+      sources.clear();
+      held.clear();
+    }
+  };
+}
+function readErrorCode(error) {
+  if (typeof error !== "object" || error === null)
+    return;
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : undefined;
+}
 export {
+  watchKey,
+  sqliteKeyspaceBackend,
   readDiagnosticJournalLockDiagnosis,
   projectApplicationStatus,
+  memoryKeyspaceBackend,
   managedServerResource,
   managedResourceDependencyId,
+  keyspaceResource,
   defineManagedResource,
+  defineKeyspace,
+  createWatchHub,
   createManagedSchedule,
   createDiagnosticJournal,
   createCreditWindow,

package/dist/cli.js

@@ -5,17 +5,18 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-s2rchahr.js";
-import"./index-k2zczx1g.js";
+} from "./index-9my2n66s.js";
+import"./index-9c5dbr5q.js";
 import"./index-wwst0td5.js";
-import"./index-7qy2ex0m.js";
-import"./index-s4c8wy8m.js";
-import"./index-nemjkxjp.js";
+import"./index-885chjxq.js";
+import"./index-k68e5jz0.js";
+import"./index-e0a57ymn.js";
 import"./index-sbdmyz75.js";
 import"./index-22by16v6.js";
 import"./index-cby4ar3v.js";
 import"./index-nt1mp8km.js";
-import"./index-vj3vvpaa.js";
+import"./index-hsz2mmk0.js";
+import"./index-rxfy4cq7.js";
 import"./index-0w9abg87.js";
 import"./index-qyrqwr4c.js";
 import"./index-6k1937bx.js";

package/dist/contract/index.js

@@ -20,7 +20,8 @@ import {
   paginatedSchema,
   rateLimited,
   unauthorized
-} from "../index-f6n5n7nz.js";
+} from "../index-4kp4fxvp.js";
+import"../index-rxfy4cq7.js";
 import"../index-ksp6e2ye.js";
 export {
   unauthorized,

package/dist/{index-aczggrty.js → index-28jsdwt1.js}

@@ -1,6 +1,6 @@
 import {
   isUnsafeKey
-} from "./index-vj3vvpaa.js";
+} from "./index-hsz2mmk0.js";
 import {
   isRecord
 } from "./index-qyrqwr4c.js";