stitchkit 0.89.0 → 0.90.0

package/dist/live/watch-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watch-contract.d.ts","sourceRoot":"","sources":["../../src/live/watch-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,2FAA2F;AAC3F,eAAO,MAAM,cAAc;;;;mBAkBd,CAAC;AACd,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,eAAO,MAAM,eAAe;;;;;;;kBAAkE,CAAC;AAE/F,eAAO,MAAM,mBAAmB;;;mBAOnB,CAAC;AAEd,eAAO,MAAM,gBAAgB;;;;;;;;kBAUhB,CAAC;AAEd,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;kBAShB,CAAC;AAEd,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE/D,eAAO,MAAM,UAAU,yBAAyB,CAAC;AACjD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;qBAEL,IAAI;;;;;;;;;;;qBACJ,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAGL,IAAI;;;;;;;;qBAA8B,GAAG;;;;;;qBACpC,IAAI;;;;;;;;;CAKxB,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"watch-contract.d.ts","sourceRoot":"","sources":["../../src/live/watch-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,2FAA2F;AAC3F,eAAO,MAAM,cAAc;;;;mBAkBd,CAAC;AACd,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;mBAGf,CAAC;AACd,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,eAAe;;;;;;;;;;;kBAEf,CAAC;AAEd,eAAO,MAAM,mBAAmB;;;mBAOnB,CAAC;AA6Bd,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAmB3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;kBAShB,CAAC;AAEd,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE/D,eAAO,MAAM,UAAU,yBAAyB,CAAC;AACjD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;qBAEL,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBACJ,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAGL,IAAI;;;;;;;;;;;;qBAA8B,GAAG;;;;;;qBACpC,IAAI;;;;;;;;;CAKxB,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEpD"}

package/dist/live/watch-delta.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The difference between two answers to the same watched read.
+ *
+ * A watched read publishes the whole value on every change. For a small answer
+ * that is the right thing — a difference has its own overhead, and below a few
+ * hundred bytes the difference is the larger message. For a large one it is not:
+ * the case this exists for is a ~75 KB list answer in which two timestamps move,
+ * republished every fifteen seconds, which is a megabyte of socket per
+ * subscriber per minute to carry a hundred bytes of news.
+ *
+ * ## What it is, and what it deliberately is not
+ *
+ * It is a *structural* difference over parsed JSON: objects by changed and
+ * removed key, arrays by runs copied from the previous value plus the elements
+ * that are genuinely new. It is not a text diff and not a patch format from
+ * elsewhere (JSON Patch, RFC 7386 merge patch): both of those lose the one
+ * property this has to keep — an array that shifted by one element must cost one
+ * op, not N. RFC 7386 additionally cannot express removing an array element or
+ * distinguish `null` from "delete", and a watched read's value is arbitrary
+ * application JSON where both are ordinary.
+ *
+ * ## The rule that makes it safe to use
+ *
+ * **A difference that is not smaller than the value is not sent.** Every caller
+ * measures — {@link deltaWins} — because a difference can be larger: a list that
+ * was replaced wholesale produces one `put` per element plus the framing. There
+ * is no shape of value for which sending the delta is the only option, so the
+ * failure mode of a bad diff is a wasted comparison, never a bigger frame.
+ *
+ * ## Fidelity
+ *
+ * `apply(previous, diff(previous, next))` reconstructs `next` exactly, for every
+ * value that survives `JSON.parse(JSON.stringify(x))` — which is every value a
+ * contract read can return, because it crossed a socket to get here. The
+ * property test over random pairs is the standing proof; it is a property rather
+ * than examples because the interesting inputs are the ones nobody thinks to
+ * write down.
+ *
+ * → the hub applies this per subscriber (`application/watch-hub`), the client
+ * reassembles (`live/watch-client`).
+ */
+import { z } from 'zod';
+/** One step of rebuilding an array from the previous one. */
+export type WatchArrayOp = 
+/** Take `count` elements from the previous array starting at `from`. */
+{
+    readonly o: 'copy';
+    readonly from: number;
+    readonly count: number;
+}
+/** Take the element at `from` and apply a difference to it. */
+ | {
+    readonly o: 'patch';
+    readonly from: number;
+    readonly d: WatchDelta;
+}
+/** An element with no counterpart in the previous array. */
+ | {
+    readonly o: 'put';
+    readonly v: unknown;
+};
+/** The difference between two values. */
+export type WatchDelta = 
+/** Replace wholesale — the two values have nothing to share. */
+{
+    readonly t: 'set';
+    readonly v: unknown;
+} | {
+    readonly t: 'obj';
+    /** Per changed or added key, the difference to apply to it. */
+    readonly set?: Readonly<Record<string, WatchDelta>>;
+    /** Keys present before and gone now. */
+    readonly drop?: readonly string[];
+} | {
+    readonly t: 'arr';
+    readonly ops: readonly WatchArrayOp[];
+};
+export declare const WatchDeltaSchema: z.ZodType<WatchDelta>;
+export declare const WatchArrayOpSchema: z.ZodType<WatchArrayOp>;
+/**
+ * The difference from `previous` to `next`, or `undefined` when they are equal.
+ *
+ * `undefined` is a real answer and the caller must handle it: a re-read that
+ * produced the same bytes has no news in it, and the hub already declines to
+ * publish one. It is returned rather than an empty delta so that "nothing
+ * changed" cannot be confused with "everything at the top level was replaced by
+ * an empty object".
+ */
+export declare function diff(previous: unknown, next: unknown): WatchDelta | undefined;
+/**
+ * Rebuild the new value from the old one and a difference.
+ *
+ * **Throws when the difference does not fit the value it was given.** That is
+ * the contract, and the reason it is not a tolerant merge: a difference applied
+ * to the wrong base produces a plausible object that is not what the server
+ * holds, and a watched read whose face is quietly wrong is the exact failure the
+ * revision and the fingerprint exist to prevent. The caller catches and
+ * resynchronises that one key.
+ */
+export declare function apply(previous: unknown, delta: WatchDelta): unknown;
+/**
+ * Whether sending the difference actually saves anything.
+ *
+ * Measured on the encoded length of both, because that is what crosses the
+ * socket — a delta with fewer *nodes* can still be the longer message once its
+ * framing is written out. Ties go to the value: identical cost, one fewer thing
+ * that can go wrong at the other end.
+ */
+export declare function deltaWins(delta: WatchDelta, value: unknown): boolean;
+//# sourceMappingURL=watch-delta.d.ts.map

package/dist/live/watch-delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-delta.d.ts","sourceRoot":"","sources":["../../src/live/watch-delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,6DAA6D;AAC7D,MAAM,MAAM,YAAY;AACtB,wEAAwE;AACtE;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACvE,+DAA+D;GAC7D;IAAE,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAA;CAAE;AACxE,4DAA4D;GAC1D;IAAE,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/C,yCAAyC;AACzC,MAAM,MAAM,UAAU;AACpB,gEAAgE;AAC9D;IAAE,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1C;IACE,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IACpD,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC,GACD;IAAE,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,CAAC;AAEjE,eAAO,MAAM,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAUzB,CAAC;AAE3B,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAc3B,CAAC;AAiB7B;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAK7E;AAwGD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAqCnE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE"}

package/dist/live.d.ts

@@ -14,5 +14,6 @@
  */
 export { defineEvents, type EventDeliveryMode, type EventPayloads, type EventsConfig, type EventsDeclaration, type EventTopicDeclaration, type EventTopicRegistry, type EventTopicsOfMode, type PolicyDecision, toRealtimeContract, type UndecidedOutcome, type WireTopic, } from './live/events.js';
 export { createWatchClient, type RealtimeClientLike, type TypedWatchClient, type WatchClientConfig, type WatchHandle, type WatchInboundEvents, type WatchListeners, type WatchTransport, watchTransport, } from './live/watch-client.js';
-export { WATCH_CLOSE, WATCH_OPEN, WATCH_STATE, WATCH_VALUE, type WatchKey, WatchKeySchema, type WatchStateFrame, WatchStateSchema, type WatchValueFrame, WatchValueSchema, watchContract, watchKeyString, } from './live/watch-contract.js';
+export { WATCH_CLOSE, WATCH_OPEN, WATCH_STATE, WATCH_VALUE, type WatchHave, WatchHaveSchema, type WatchKey, WatchKeySchema, type WatchStateFrame, WatchStateSchema, type WatchValueFrame, WatchValueSchema, watchContract, watchKeyString, } from './live/watch-contract.js';
+export { apply as applyWatchDelta, deltaWins as watchDeltaWins, diff as watchDiff, type WatchArrayOp, WatchArrayOpSchema, type WatchDelta, WatchDeltaSchema, } from './live/watch-delta.js';
 //# sourceMappingURL=live.d.ts.map

package/dist/live.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,SAAS,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,WAAW,EACX,KAAK,QAAQ,EACb,cAAc,EACd,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,gBAAgB,EAChB,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,SAAS,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,WAAW,EACX,KAAK,SAAS,EACd,eAAe,EACf,KAAK,QAAQ,EACb,cAAc,EACd,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,gBAAgB,EAChB,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,IAAI,eAAe,EACxB,SAAS,IAAI,cAAc,EAC3B,IAAI,IAAI,SAAS,EACjB,KAAK,YAAY,EACjB,kBAAkB,EAClB,KAAK,UAAU,EACf,gBAAgB,GACjB,MAAM,oBAAoB,CAAC"}

package/dist/live.js

@@ -3,12 +3,18 @@ import {
   WATCH_OPEN,
   WATCH_STATE,
   WATCH_VALUE,
+  WatchArrayOpSchema,
+  WatchDeltaSchema,
+  WatchHaveSchema,
   WatchKeySchema,
   WatchStateSchema,
   WatchValueSchema,
+  apply,
+  deltaWins,
+  diff,
   watchContract,
   watchKeyString
-} from "./index-dre2ywck.js";
+} from "./index-2na0qrfn.js";
 import"./index-ywd0y6m1.js";
 import"./index-7gnkny4z.js";
 import {
@@ -79,17 +85,56 @@ function createWatchClient(contract, config) {
     for (const listener of [...entry.listeners])
       listener.state?.(state);
   }
+  function resynchronise(entry, message) {
+    entry.hasValue = false;
+    entry.value = undefined;
+    entry.revision = 0;
+    entry.fingerprint = undefined;
+    entry.opened = false;
+    publishState(entry, { key: entry.key, phase: "resync-required", message });
+    config.transport.emit(WATCH_CLOSE, { key: entry.key });
+    open(entry);
+  }
   config.transport.on(WATCH_VALUE, (frame) => {
     const entry = entries.get(watchKeyString(frame.key));
     if (!entry)
       return;
+    if (frame.kind === "unchanged") {
+      if (!entry.hasValue) {
+        resynchronise(entry, "the server confirmed a value this client does not hold");
+        return;
+      }
+      entry.revision = frame.revision;
+      entry.fingerprint = frame.fingerprint;
+      return;
+    }
     if (entry.hasValue && frame.revision <= entry.revision)
       return;
+    let value;
+    if (frame.kind === "full") {
+      value = frame.value;
+    } else {
+      if (!entry.hasValue || entry.revision !== frame.base) {
+        resynchronise(entry, `a difference against revision ${frame.base} arrived while holding ${entry.hasValue ? String(entry.revision) : "nothing"}`);
+        return;
+      }
+      try {
+        value = apply(entry.value, frame.delta);
+      } catch (error) {
+        resynchronise(entry, error instanceof Error ? error.message : String(error));
+        return;
+      }
+      if (argumentsDigest({ value }) !== frame.fingerprint) {
+        resynchronise(entry, "the rebuilt value did not match the fingerprint the server sent");
+        return;
+      }
+    }
     entry.revision = frame.revision;
-    entry.value = frame.value;
+    entry.value = value;
+    entry.fingerprint = frame.fingerprint;
     entry.hasValue = true;
     for (const listener of [...entry.listeners])
-      listener.value(frame.value);
+      listener.value(value);
   });
   config.transport.on(WATCH_STATE, (frame) => {
     const entry = entries.get(watchKeyString(frame.key));
@@ -142,7 +187,8 @@ function createWatchClient(contract, config) {
       return;
     entry.opened = true;
     try {
-      const acknowledgement = await config.transport.request(WATCH_OPEN, { key: entry.key, args: entry.args }, { timeoutMs: openTimeoutMs });
+      const have = entry.hasValue && entry.fingerprint !== undefined ? { revision: entry.revision, fingerprint: entry.fingerprint } : undefined;
+      const acknowledgement = await config.transport.request(WATCH_OPEN, { key: entry.key, args: entry.args, ...have !== undefined && { have } }, { timeoutMs: openTimeoutMs });
       if (!acknowledgement.accepted) {
         const reason = acknowledgement.reason ?? "the server refused this watch";
         config.onRefused?.(entry.key, reason);
@@ -216,13 +262,19 @@ function createWatchClient(contract, config) {
 export {
   watchTransport,
   watchKeyString,
+  diff as watchDiff,
+  deltaWins as watchDeltaWins,
   watchContract,
   toRealtimeContract,
   defineEvents,
   createWatchClient,
+  apply as applyWatchDelta,
   WatchValueSchema,
   WatchStateSchema,
   WatchKeySchema,
+  WatchHaveSchema,
+  WatchDeltaSchema,
+  WatchArrayOpSchema,
   WATCH_VALUE,
   WATCH_STATE,
   WATCH_OPEN,

package/dist/observability/changes.d.ts

@@ -0,0 +1,55 @@
+/**
+ * "Write the calls that changed something" — one filter, not six.
+ *
+ * Every project that audits eventually writes this predicate, and measured
+ * across six sibling consumers they had written six different ones: one audited
+ * only tool calls, one excluded `/mcp`, and two disagreed with each other on
+ * `OPTIONS`. Nobody decided any of that. They each started from the one form the
+ * `RequestEvent.httpMethod` doc gives — `(event.httpMethod ?? event.method) !==
+ * 'GET'` — which is right about `GET` and silent about the other two verbs that
+ * change nothing, and filled the gap from memory.
+ *
+ * That is the duplicated observability layer ADR 0012 exists to end, one level
+ * further in: the module owns the machinery, the project owns the policy. A
+ * predicate over a normalised event is machinery.
+ *
+ * ## The two rules, and why they are in this order
+ *
+ * **A security outcome is written whatever the verb was.** A rejected read is
+ * the single most interesting row in an audit table — it is how an attempt to
+ * reach something shows up at all — and a filter that drops every `GET` drops
+ * exactly that. This rule is first because it is the one a hand-written filter
+ * loses: the author is thinking about writes, and a refused read is not a write.
+ *
+ * **Then reads are dropped and everything else is kept.** Not "writes are kept":
+ * an unknown verb is kept, because the failure modes are not symmetric. An extra
+ * row costs bytes; a missing row costs the answer to "who changed this", and it
+ * costs it silently and only later, when the question is finally asked.
+ */
+import type { RequestEvent } from './event.js';
+/**
+ * Whether this call is worth an audit row: it changed something, or it was
+ * refused for a reason the audit exists to record.
+ *
+ * Hand it to a sink as its `filter`:
+ *
+ * ```ts
+ * createObservability({
+ *   request: { write: (event) => db.audit.create({ data: event }), filter: auditChanges },
+ *   tools: { write: (event) => db.audit.create({ data: event }), filter: auditChanges },
+ * });
+ * ```
+ *
+ * One filter for both surfaces on purpose. A tool call carries its contract verb
+ * in `httpMethod` while its `method` is the literal `TOOL` (→ ADR 0030), so the
+ * same predicate reads a write the same way whether it arrived over HTTP, MCP or
+ * an agent — which is what keeps one audit table queryable across all three.
+ *
+ * Narrower or wider policy stays the project's: compose it.
+ *
+ * ```ts
+ * filter: (event) => auditChanges(event) && event.serviceName !== 'health',
+ * ```
+ */
+export declare function auditChanges(event: RequestEvent): boolean;
+//# sourceMappingURL=changes.d.ts.map

package/dist/observability/changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.d.ts","sourceRoot":"","sources":["../../src/observability/changes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAuB5C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAIzD"}

package/dist/observability/index.d.ts

@@ -8,9 +8,11 @@
  */
 export { createDimensionsProjector, createObservability, type DimensionsProjector, type DimensionsProjectorConfig, type HttpRequestCompletion, type HttpRequestObserver, type Observability, type ObservabilityConfig, type ObservabilityDrainBound, type ProjectedDimensions, type RequestEventSinkConfig, type RequestObservabilityConfig, type SinkDrop, type SinkDropReason, type SinkError, } from './audit.js';
 export { type BoundedLoggerBounds, type BoundedLoggerOptions, createBoundedLogger, DEFAULT_REDACT_PATHS, } from './bounded-logger.js';
+export { auditChanges } from './changes.js';
 export { type DimensionCollision, getRequestContext, getTraceId, getUserId, type RequestContext, runWithRequestContext, type SetRequestDimensionsOptions, setRequestDimensions, setRequestEndpoint, setRequestError, setRequestUser, type WrapRequestContextOptions, wrapInRequestContext, } from './context.js';
 export type { RequestEvent } from './event.js';
 export { type JsonValue, measureSize, redact, type SanitizeOptions, type SizeMeasure, sanitizePayload, truncatePreview, } from './sanitize.js';
+export { createSpooledSink, type SpooledSink, type SpooledSinkConfig, type SpoolRecovery, } from './spool.js';
 export { type ObservabilityDrainReport, ObservabilityDrainReportSchema, type ObservabilitySinkStatus, ObservabilitySinkStatusSchema, type ObservabilityStatus, ObservabilityStatusSchema, } from './status.js';
 export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, resolvePropagationContext, resolveTraceContext, type TraceContext, } from './trace.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,KAAK,yBAAyB,EAC9B,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,KAAK,SAAS,EACd,WAAW,EACX,MAAM,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,yBAAyB,GAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EACL,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,KAAK,yBAAyB,EAC9B,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,KAAK,SAAS,EACd,WAAW,EACX,MAAM,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,yBAAyB,GAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}

package/dist/observability/index.js

@@ -364,6 +364,131 @@ function createBoundedLogger(options) {
     debug: (message, data) => write("debug", message, data)
   };
 }
+// src/observability/changes.ts
+var READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+var SECURITY_STATUSES = new Set([401, 403]);
+function auditChanges(event) {
+  if (SECURITY_STATUSES.has(event.statusCode))
+    return true;
+  const verb = event.httpMethod ?? event.method;
+  return !READ_METHODS.has(verb.toUpperCase());
+}
+// src/observability/spool.ts
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+function reviveEvent(event) {
+  return { ...event, startedAt: new Date(event.startedAt) };
+}
+function createSpooledSink(config) {
+  const keyOf = config.key ?? ((event) => event.spanId);
+  const compactAfter = config.compactAfter ?? 512;
+  const undelivered = new Map;
+  let delivered = 0;
+  let tail = Promise.resolve();
+  function serialise(work) {
+    const next = tail.then(work, work);
+    tail = next.catch(() => {
+      return;
+    });
+    return next;
+  }
+  async function append(line, event) {
+    try {
+      await appendFile(config.path, `${JSON.stringify(line)}
+`, "utf8");
+    } catch (error) {
+      if (isMissing(error)) {
+        await mkdir(dirname(config.path), { recursive: true });
+        await appendFile(config.path, `${JSON.stringify(line)}
+`, "utf8");
+        return;
+      }
+      config.onSpoolError?.({ error, ...event !== undefined && { event } });
+    }
+  }
+  async function compact() {
+    const temporary = `${config.path}.compacting`;
+    const body = [...undelivered.entries()].map(([key, event]) => `${JSON.stringify({ k: key, e: event })}
+`).join("");
+    try {
+      await writeFile(temporary, body, "utf8");
+      await rename(temporary, config.path);
+      delivered = 0;
+    } catch (error) {
+      config.onSpoolError?.({ error });
+    }
+  }
+  return {
+    async write(event) {
+      const key = keyOf(event);
+      await serialise(() => append({ k: key, e: event }, event));
+      undelivered.set(key, event);
+      await config.write(event);
+      undelivered.delete(key);
+      delivered += 1;
+      await serialise(async () => {
+        await append({ a: key });
+        if (delivered >= compactAfter)
+          await compact();
+      });
+    },
+    async recover() {
+      let body;
+      try {
+        body = await readFile(config.path, "utf8");
+      } catch (error) {
+        if (!isMissing(error))
+          config.onSpoolError?.({ error });
+        return { replayed: 0, failed: 0 };
+      }
+      const pending = new Map;
+      for (const line of body.split(`
+`)) {
+        if (line.length === 0)
+          continue;
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch (error) {
+          config.onSpoolError?.({ error });
+          continue;
+        }
+        if (parsed.a !== undefined) {
+          pending.delete(parsed.a);
+          continue;
+        }
+        if (parsed.k !== undefined && parsed.e !== undefined) {
+          pending.set(parsed.k, reviveEvent(parsed.e));
+        }
+      }
+      const replayed = pending.size;
+      let failed = 0;
+      for (const [key, event] of pending) {
+        try {
+          await config.write(event);
+          pending.delete(key);
+        } catch (error) {
+          failed += 1;
+          config.onSpoolError?.({ error, event });
+        }
+      }
+      undelivered.clear();
+      for (const [key, event] of pending)
+        undelivered.set(key, event);
+      delivered = 0;
+      await serialise(compact);
+      return { replayed, failed };
+    },
+    pending: () => undelivered.size
+  };
+}
+function code(error) {
+  if (typeof error !== "object" || error === null)
+    return;
+  const value = Reflect.get(error, "code");
+  return typeof value === "string" ? value : undefined;
+}
+var isMissing = (error) => code(error) === "ENOENT";
 export {
   wrapInRequestContext,
   truncatePreview,
@@ -383,10 +508,12 @@ export {
   getRequestContext,
   formatTraceparent,
   createTraceContext,
+  createSpooledSink,
   createObservability,
   createDimensionsProjector,
   createBoundedLogger,
   childSpan,
+  auditChanges,
   ObservabilityStatusSchema,
   ObservabilitySinkStatusSchema,
   ObservabilityDrainReportSchema,

package/dist/observability/spool.d.ts

@@ -0,0 +1,53 @@
+import type { RequestEvent } from './event.js';
+export interface SpooledSinkConfig {
+    /** The real sink — normally the project's audit-table write. */
+    write: (event: RequestEvent) => void | Promise<void>;
+    /**
+     * The spool file. Created with its directory if missing.
+     *
+     * One process, one path: see the module header.
+     */
+    path: string;
+    /**
+     * The identity a replayed record is recognised by. Default: `event.spanId`,
+     * which is unique per call by construction.
+     *
+     * Whatever it returns is what the store must be idempotent on.
+     */
+    key?: (event: RequestEvent) => string;
+    /**
+     * Delivered records tolerated in the file before it is rewritten without
+     * them. Default 512. The rewrite is atomic — a temporary file and a rename —
+     * so a crash during it leaves either the old file or the new one.
+     */
+    compactAfter?: number;
+    /** Observe a spool-file failure. The event is still offered to the store. */
+    onSpoolError?: (failure: {
+        error: unknown;
+        event?: RequestEvent;
+    }) => void;
+}
+export interface SpoolRecovery {
+    /** Records found undelivered and offered to the store again. */
+    replayed: number;
+    /** Of those, the ones the store refused again. They stay in the file. */
+    failed: number;
+}
+export interface SpooledSink {
+    /** Spool, then deliver. Hand this to `RequestEventSinkConfig.write`. */
+    write(event: RequestEvent): Promise<void>;
+    /**
+     * Replay what a previous process left undelivered, then rewrite the file with
+     * whatever is still undelivered.
+     *
+     * Call it once at startup, **before** the sink is wired, and await it: a
+     * replay racing live writes can only make the file larger and the order
+     * stranger. Safe to call on a path that does not exist — that is the ordinary
+     * first run, and it reports zero rather than failing.
+     */
+    recover(): Promise<SpoolRecovery>;
+    /** Records spooled and not yet marked delivered, in this process. */
+    pending(): number;
+}
+export declare function createSpooledSink(config: SpooledSinkConfig): SpooledSink;
+//# sourceMappingURL=spool.d.ts.map

package/dist/observability/spool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spool.d.ts","sourceRoot":"","sources":["../../src/observability/spool.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC;IACtC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,YAAY,CAAA;KAAE,KAAK,IAAI,CAAC;CAC5E;AAED,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;;;;;OAQG;IACH,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAClC,qEAAqE;IACrE,OAAO,IAAI,MAAM,CAAC;CACnB;AAqBD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAuHxE"}