@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/adapters/telemetry/trace.d.ts

@@ -0,0 +1,127 @@
+type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
+export type AttributeValue = string | number | boolean | readonly string[] | readonly number[];
+type Attributes = Readonly<Record<string, AttributeValue>>;
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface SpanLink {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly attributes?: Attributes;
+}
+/** One finished (or, for `onStart`, begun) span, as every sink sees it. Times are epoch milliseconds, fractional. */
+export interface SpanRecord {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    /** The parent came from another process (a `traceparent` header): this span is the local root. */
+    readonly remoteParent: boolean;
+    readonly traceState?: string;
+    /** Settable until the span ends: a request is named once its route is known. */
+    name: string;
+    readonly kind: SpanKind;
+    readonly startTime: number;
+    endTime?: number;
+    readonly attributes: Record<string, AttributeValue>;
+    readonly events: Array<{
+        name: string;
+        time: number;
+        attributes: Attributes;
+    }>;
+    readonly links: readonly SpanLink[];
+    status: {
+        code: 'unset' | 'ok' | 'error';
+        message?: string;
+    };
+    /** Whether the exporter keeps it: the sampler's word at the trace's root. The observer keeps every span. */
+    readonly sampled: boolean;
+    /** Dev-only detail. Empty unless a sink asked for it. Never exported. */
+    readonly detail: Record<string, unknown>;
+}
+/** A structured log line: `message` and `attributes` travel, `detail` stays local like a span's. */
+export interface LogRecord {
+    readonly time: number;
+    readonly level: LogLevel;
+    /** What wrote it: `http`, `commands`, `jobs`, `app` (an App's own console), `startup`… */
+    readonly source: string;
+    readonly message: string;
+    readonly attributes: Attributes;
+    readonly traceId?: string;
+    readonly spanId?: string;
+    readonly sampled?: boolean;
+    readonly detail?: Record<string, unknown>;
+    /** A line only the local observer may keep (the App's console, which says anything). */
+    readonly local?: boolean;
+}
+interface TelemetrySink {
+    /** Hand this sink the spans' `detail` and local log lines. Only the dev observer may. */
+    readonly local?: boolean;
+    onStart?(span: SpanRecord): void;
+    onEnd(span: SpanRecord): void;
+    onLog?(record: LogRecord): void;
+}
+export interface Span {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly recording: boolean;
+    setAttribute(key: string, value: AttributeValue | undefined): void;
+    /** Rename the span before it ends: a request's route is known only once its address is read. */
+    rename(name: string): void;
+    /** Drop the span: it ends and no sink hears of it (a heartbeat, the observer's own requests). */
+    discard(): void;
+    setAttributes(values: Readonly<Record<string, AttributeValue | undefined>>): void;
+    /** Local detail, built only when a local sink listens. */
+    detail(build: () => Record<string, unknown>): void;
+    event(name: string, attributes?: Readonly<Record<string, AttributeValue | undefined>>): void;
+    /** The span failed. `code` is what travels (a refusal code, an error class); the error itself stays local. */
+    fail(code: string, error?: unknown): void;
+    end(): void;
+}
+/** Whether anything listens. The one check every instrumented path makes first. */
+export declare const tracing: () => boolean;
+/** Whether a local sink (the dev observer) listens, so local detail is worth building. */
+export declare const observing: () => boolean;
+export declare function addSink(sink: TelemetrySink): () => void;
+export declare function setSampler(decide: (traceId: string) => boolean): void;
+interface TraceParent {
+    traceId: string;
+    spanId: string;
+    sampled: boolean;
+    traceState?: string;
+}
+interface SpanOptions {
+    kind?: SpanKind;
+    attributes?: Readonly<Record<string, AttributeValue | undefined>>;
+    /** A parent from elsewhere: an incoming `traceparent`, a job's enqueuer. Ignored when a span is already current. */
+    remote?: TraceParent;
+    links?: readonly SpanLink[];
+    /** Start only inside an existing span: a statement outside any request, job or command is not worth a trace. */
+    childOnly?: boolean;
+}
+/** Begin a span; the caller ends it. Prefer `inSpan`, which also makes it current. */
+export declare function startSpan(name: string, options?: SpanOptions): Span;
+/** Run `work` inside `span`, so every span begun beneath it is its child. */
+export declare function withSpan<T>(span: Span, work: () => T): T;
+/**
+ * Run `work` as a span: current for everything it starts, ended when it
+ * settles, failed when it throws. The error's class names the failure unless
+ * `failure` says otherwise (a refusal's code).
+ */
+export declare function inSpan<T>(name: string, options: SpanOptions, work: (span: Span) => T, failure?: (error: unknown) => string): T;
+/** An error's travelling name: its `code` when it is one of ours (a refusal's), else its class. Never its message. */
+export declare function errorCode(error: unknown): string;
+export declare function currentSpan(): Span | undefined;
+/** Carry the current trace on an outgoing request's headers (W3C Trace Context). */
+export declare function injectTrace(headers: Record<string, string>): Record<string, string>;
+/** Read a W3C `traceparent` (and its `tracestate`), refusing anything malformed rather than guessing. */
+export declare function parseTraceparent(header: unknown, state?: unknown): TraceParent | undefined;
+/**
+ * One structured log line, correlated with the current span. The terminal's
+ * own lines are left as they are; this is the structured version, for the
+ * exporter and the observer. `message` and `attributes` travel: write them
+ * from the code's own words.
+ */
+export declare function log(level: LogLevel, source: string, message: string, options?: {
+    attributes?: Readonly<Record<string, AttributeValue | undefined>>;
+    detail?: () => Record<string, unknown>;
+    local?: boolean;
+}): void;
+export {};

package/dist/adapters/telemetry/trace.js

@@ -0,0 +1,295 @@
+/**
+ * Spans and logs, for whoever is listening — and nothing at all when nobody is.
+ *
+ * Two listeners exist. The OpenTelemetry exporter (otlp.ts) is switched on by
+ * the standard OTEL_* environment variables and sends what it is given to a
+ * collector, Datadog's Agent or Dynatrace. The dev observer
+ * (server/observe/) keeps the last few hundred requests in memory for the
+ * author at work. Both hear the same spans, so what the observer shows is
+ * what production exports, plus the detail production must never see.
+ *
+ * That split is the privacy rule, made structural rather than remembered:
+ *
+ * - `attributes` travel. They are set only from values the code itself names
+ *   — a route template, a statement's kind and table, a command's id, a
+ *   refusal's code, a count — never from a request, a row, a parameter, a
+ *   body, an email or a token. They follow the OpenTelemetry semantic
+ *   conventions where one exists.
+ * - `detail` does not. It is where the SQL with its parameters, a command's
+ *   input and output and a refusal's recorded cause go, and only a sink that
+ *   asks for it (the dev observer, loopback only, dev only) is handed it.
+ *   With no such sink, `detail` is never even built: callers pass a function.
+ *
+ * With no sink at all, `inSpan` calls its function and returns: no id is
+ * drawn, no clock read, no context entered. `npx tablewalk` pays one boolean.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+const NOOP = Object.freeze({
+    traceId: '',
+    spanId: '',
+    recording: false,
+    setAttribute() { },
+    rename() { },
+    discard() { },
+    setAttributes() { },
+    detail() { },
+    event() { },
+    fail() { },
+    end() { },
+});
+const sinks = [];
+let local = false;
+const storage = new AsyncLocalStorage();
+/** The sampler: whether a new trace is exported. Always on until the exporter says otherwise. */
+let sampler = () => true;
+/** Whether anything listens. The one check every instrumented path makes first. */
+export const tracing = () => sinks.length > 0;
+/** Whether a local sink (the dev observer) listens, so local detail is worth building. */
+export const observing = () => local;
+export function addSink(sink) {
+    sinks.push(sink);
+    local ||= sink.local === true;
+    return () => {
+        const at = sinks.indexOf(sink);
+        if (at >= 0)
+            sinks.splice(at, 1);
+        local = sinks.some((each) => each.local === true);
+    };
+}
+export function setSampler(decide) {
+    sampler = decide;
+}
+const now = () => performance.timeOrigin + performance.now();
+const hex = (bytes) => randomBytes(bytes).toString('hex');
+const clean = (values) => Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+class LiveSpan {
+    record;
+    recording = true;
+    ended = false;
+    constructor(record) {
+        this.record = record;
+    }
+    get traceId() {
+        return this.record.traceId;
+    }
+    get spanId() {
+        return this.record.spanId;
+    }
+    setAttribute(key, value) {
+        if (value !== undefined && !this.ended)
+            this.record.attributes[key] = value;
+    }
+    setAttributes(values) {
+        if (!this.ended)
+            Object.assign(this.record.attributes, clean(values));
+    }
+    rename(name) {
+        if (!this.ended)
+            this.record.name = name;
+    }
+    discarded = false;
+    discard() {
+        this.ended = true;
+        this.discarded = true;
+    }
+    detail(build) {
+        if (!local)
+            return;
+        // Detail is a courtesy to the author; building it must never fail the work it describes.
+        try {
+            Object.assign(this.record.detail, build());
+        }
+        catch {
+            /* left out */
+        }
+    }
+    event(name, attributes = {}) {
+        if (!this.ended)
+            this.record.events.push({ name, time: now(), attributes: clean(attributes) });
+    }
+    fail(code, error) {
+        this.record.status = { code: 'error', message: code };
+        this.record.attributes['error.type'] = code;
+        if (error !== undefined)
+            this.detail(() => ({ error: describeError(error) }));
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.record.endTime = now();
+        for (const sink of sinks) {
+            try {
+                sink.onEnd(this.record);
+            }
+            catch {
+                /* a sink never fails the traced work */
+            }
+        }
+    }
+}
+/** What an error was, for local eyes only: its class, its words and the reasons recorded beneath it. */
+function describeError(error) {
+    if (!(error instanceof Error))
+        return { message: String(error) };
+    const out = { name: error.name, message: error.message };
+    const code = error.code;
+    if (typeof code === 'string')
+        out.code = code;
+    if (error.stack)
+        out.stack = error.stack.split('\n').slice(0, 12).join('\n');
+    return out;
+}
+/** Begin a span; the caller ends it. Prefer `inSpan`, which also makes it current. */
+export function startSpan(name, options = {}) {
+    if (!sinks.length)
+        return NOOP;
+    const parent = storage.getStore();
+    if (options.childOnly && !parent)
+        return NOOP;
+    // Beneath a dropped span nothing is traced: the observer's own EXPLAIN is not a trace.
+    if (parent?.discarded)
+        return NOOP;
+    const remote = parent ? undefined : options.remote;
+    const traceId = parent?.traceId ?? remote?.traceId ?? hex(16);
+    const record = {
+        traceId,
+        spanId: hex(8),
+        parentSpanId: parent?.spanId ?? remote?.spanId,
+        remoteParent: !parent && !!remote,
+        ...((parent?.record.traceState ?? remote?.traceState) ? { traceState: parent?.record.traceState ?? remote?.traceState } : {}),
+        name,
+        kind: options.kind ?? 'internal',
+        startTime: now(),
+        attributes: clean(options.attributes ?? {}),
+        events: [],
+        links: options.links ?? [],
+        status: { code: 'unset' },
+        sampled: parent ? parent.record.sampled : remote ? remote.sampled : sampler(traceId),
+        detail: {},
+    };
+    const span = new LiveSpan(record);
+    for (const sink of sinks) {
+        try {
+            sink.onStart?.(record);
+        }
+        catch {
+            /* as above */
+        }
+    }
+    return span;
+}
+/** Run `work` inside `span`, so every span begun beneath it is its child. */
+export function withSpan(span, work) {
+    return span instanceof LiveSpan ? storage.run(span, work) : work();
+}
+/**
+ * Run `work` as a span: current for everything it starts, ended when it
+ * settles, failed when it throws. The error's class names the failure unless
+ * `failure` says otherwise (a refusal's code).
+ */
+export function inSpan(name, options, work, failure = errorCode) {
+    if (!sinks.length)
+        return work(NOOP);
+    const span = startSpan(name, options);
+    if (!(span instanceof LiveSpan))
+        return work(span);
+    return storage.run(span, () => {
+        let result;
+        try {
+            result = work(span);
+        }
+        catch (error) {
+            span.fail(failure(error), error);
+            span.end();
+            throw error;
+        }
+        if (result && typeof result.then === 'function') {
+            return result.then((value) => {
+                span.end();
+                return value;
+            }, (error) => {
+                span.fail(failure(error), error);
+                span.end();
+                throw error;
+            });
+        }
+        span.end();
+        return result;
+    });
+}
+/** An error's travelling name: its `code` when it is one of ours (a refusal's), else its class. Never its message. */
+export function errorCode(error) {
+    const code = error?.code;
+    if (typeof code === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(code))
+        return code;
+    return error instanceof Error ? error.name || 'Error' : 'Error';
+}
+export function currentSpan() {
+    return storage.getStore();
+}
+/** The current trace, as a W3C `traceparent` header. */
+function traceparent(span = storage.getStore()) {
+    if (!span || !(span instanceof LiveSpan))
+        return undefined;
+    return `00-${span.traceId}-${span.spanId}-${span.record.sampled ? '01' : '00'}`;
+}
+/** Carry the current trace on an outgoing request's headers (W3C Trace Context). */
+export function injectTrace(headers) {
+    const span = storage.getStore();
+    const parent = traceparent(span);
+    if (!parent)
+        return headers;
+    return { ...headers, traceparent: parent, ...(span.record.traceState ? { tracestate: span.record.traceState } : {}) };
+}
+/** Read a W3C `traceparent` (and its `tracestate`), refusing anything malformed rather than guessing. */
+export function parseTraceparent(header, state) {
+    if (typeof header !== 'string')
+        return undefined;
+    const match = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(header.trim());
+    if (!match || match[1] === 'ff' || /^0+$/.test(match[2]) || /^0+$/.test(match[3]))
+        return undefined;
+    const traceState = typeof state === 'string' && state.length <= 512 && /^[\x20-\x7e]*$/.test(state) ? state.trim() : undefined;
+    return { traceId: match[2], spanId: match[3], sampled: (parseInt(match[4], 16) & 1) === 1, ...(traceState ? { traceState } : {}) };
+}
+/**
+ * One structured log line, correlated with the current span. The terminal's
+ * own lines are left as they are; this is the structured version, for the
+ * exporter and the observer. `message` and `attributes` travel: write them
+ * from the code's own words.
+ */
+export function log(level, source, message, options = {}) {
+    if (!sinks.length)
+        return;
+    const span = storage.getStore();
+    let detail;
+    if (local && options.detail) {
+        try {
+            detail = options.detail();
+        }
+        catch {
+            detail = undefined;
+        }
+    }
+    const record = {
+        time: now(),
+        level,
+        source,
+        message,
+        attributes: clean(options.attributes ?? {}),
+        ...(span ? { traceId: span.traceId, spanId: span.spanId, sampled: span.record.sampled } : {}),
+        ...(detail ? { detail } : {}),
+        ...(options.local ? { local: true } : {}),
+    };
+    for (const sink of sinks) {
+        if (record.local && !sink.local)
+            continue;
+        try {
+            sink.onLog?.(record);
+        }
+        catch {
+            /* as above */
+        }
+    }
+}

package/dist/adapters/writeAhead.d.ts

@@ -0,0 +1,27 @@
+/** A record the transaction reads by its key first, and, unless only read, writes. */
+interface WriteAheadTarget {
+    readonly table: string;
+    readonly key: Readonly<Record<string, string | number>>;
+}
+export interface WriteAhead {
+    /** The receipt the transaction's journal looks up before anything else (its journal's own shape; the journal checks it). */
+    readonly receipt?: unknown;
+    /** Records read by key before the work starts: locked, read in full through the row scope. */
+    readonly targets: readonly WriteAheadTarget[];
+    /** Whether those records are then written, so the write's own reads of them are sent too. */
+    readonly writes: boolean;
+    /** Records only read, never locked (a command's preparation): their rows are sent ahead, no FOR UPDATE with them. */
+    readonly readOnly?: true;
+    /** Whether the work locks each record itself first (a save's lockRecord). An unscoped transaction sends a record's
+     * lock ahead only then, or where its history capture will lock it; a scoped one always locks its targets. */
+    readonly locks?: true;
+}
+/** Run `work` with `hint` told to the next write transaction it opens. */
+export declare function withWriteAhead<T>(hint: WriteAhead | undefined, work: () => T): T;
+/** The hint for the transaction about to open here, if one was told. */
+export declare function writeAhead(): WriteAhead | undefined;
+/** Run `work` with no hint: a transaction's own work, so nothing it opens takes its hint. */
+export declare function withoutWriteAhead<T>(work: () => T): T;
+/** The hint with each target's table renamed (a tenant source's logical table to its physical one); undefined when one cannot be. */
+export declare function renamedWriteAhead(hint: WriteAhead | undefined, rename: (table: string) => string | undefined): WriteAhead | undefined;
+export {};

package/dist/adapters/writeAhead.js

@@ -0,0 +1,46 @@
+/**
+ * What a write transaction is about to ask, told to the adapter before it
+ * begins, so the reads and locks it will open with leave behind its BEGIN in
+ * one round trip instead of one round trip each (postgresTransactionHandle.ts
+ * sendAhead).
+ *
+ * A hint, never an instruction: the adapter turns it into the exact
+ * statements the transaction would send in its turn, each answered once to
+ * the identical statement when it comes, and anything the transaction never
+ * asks is dropped unread. A wrong hint costs the statements it sent and is
+ * counted (aheadReport); it never changes an answer.
+ *
+ * Carried the way `inWriteLanes` carries its keys (writeLanes.ts): by the
+ * caller that knows the command, through the owners between it and the
+ * adapter, each of which may translate it (a tenant source's logical tables
+ * to physical ones) or drop it. The adapter reads it once, for the
+ * transaction it is opening, and runs that transaction's own work without
+ * it, so a transaction opened inside never takes it for its own.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const hinted = new AsyncLocalStorage();
+/** Run `work` with `hint` told to the next write transaction it opens. */
+export function withWriteAhead(hint, work) {
+    return hinted.run(hint, work);
+}
+/** The hint for the transaction about to open here, if one was told. */
+export function writeAhead() {
+    return hinted.getStore();
+}
+/** Run `work` with no hint: a transaction's own work, so nothing it opens takes its hint. */
+export function withoutWriteAhead(work) {
+    return hinted.run(undefined, work);
+}
+/** The hint with each target's table renamed (a tenant source's logical table to its physical one); undefined when one cannot be. */
+export function renamedWriteAhead(hint, rename) {
+    if (!hint)
+        return undefined;
+    const targets = [];
+    for (const target of hint.targets) {
+        const table = rename(target.table);
+        if (table === undefined)
+            return undefined;
+        targets.push({ table, key: target.key });
+    }
+    return { ...hint, targets };
+}

package/dist/adapters/writeAttribution.d.ts

@@ -0,0 +1,18 @@
+export declare const WRITE_VIAS: readonly ['app', 'workbench', 'agent', 'api', 'form', 'system'];
+export type WriteVia = (typeof WRITE_VIAS)[number];
+/** Who and what a write is. Set only by trusted server code around the work. */
+interface WriteAttribution {
+    /** The verified account (its email), or none: who the write is attributed to, kept and never shown. */
+    readonly actor?: string;
+    /** Its display name at the time, as a history entry and a notice say who wrote it. Words only: never who a write is attributed to. */
+    readonly name?: string;
+    readonly via: WriteVia;
+    /** The action or command the write came from, in the App's words. */
+    readonly action?: string;
+}
+/** Run `work` with its writes attributed; a nested call refines the outer one. */
+export declare function attributeWrites<T>(attribution: WriteAttribution, work: () => T): T;
+/** Name the action or command a write came from, keeping who made it. */
+export declare function attributeAction<T>(action: string | undefined, work: () => T): T;
+export declare const currentWriteAttribution: () => WriteAttribution | undefined;
+export {};

package/dist/adapters/writeAttribution.js

@@ -0,0 +1,23 @@
+/*
+ * Who and what a write is, held around the work that makes it. It is part of
+ * the write path every server has, not of the App's record history that
+ * reads it (history/recordHistory.ts): the database MCP marks its tool calls
+ * as an agent's, the Workbench's routes name Undo, and an App's door names
+ * its person and action, all through the same frame.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const WRITE_VIAS = ['app', 'workbench', 'agent', 'api', 'form', 'system'];
+const attributions = new AsyncLocalStorage();
+/** Run `work` with its writes attributed; a nested call refines the outer one. */
+export function attributeWrites(attribution, work) {
+    const outer = attributions.getStore();
+    return attributions.run(Object.freeze({ ...outer, ...attribution }), work);
+}
+/** Name the action or command a write came from, keeping who made it. */
+export function attributeAction(action, work) {
+    const outer = attributions.getStore();
+    if (!action)
+        return work();
+    return attributions.run(Object.freeze({ ...(outer ?? { via: 'system' }), action }), work);
+}
+export const currentWriteAttribution = () => attributions.getStore();

package/dist/adapters/writeCapture.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What rides beneath every write a dialect adapter runs, in the write's own
+ * transaction: the App framework's record history and notices
+ * (history/recordHistory.ts, inbox/inbox.ts), and live sync's one change row
+ * per transaction (live/liveChange.ts). Beneath every facade, so a scoped
+ * writer, a command and an Undo record exactly as a Save does.
+ *
+ * The adapter is the engine's and knows no store, so the capture is lent to
+ * it: the framework installs one capturer (stores/writeCaptures.ts), which
+ * says which of an adapter's tables it watches and, for one transaction,
+ * hands back the capture that wraps its writes. The adapter hands over its
+ * writer and the two reads a capture needs on it; with nothing installed,
+ * as in the database browser, no write is captured.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { DeleteRequest, DeleteResult, InsertRequest, InsertResult, TellRequest, UpdateRequest, UpdateResult } from './adapter.js';
+import type { PgQuery } from './postgresPool.js';
+/** The transaction's writer, by dialect: a capture's own rows join it. */
+type CaptureWriter = {
+    readonly dialect: 'postgres';
+    readonly client: PgQuery;
+} | {
+    readonly dialect: 'sqlite';
+    readonly db: DatabaseSync;
+};
+/** What a capture reads on the writer. */
+export interface CaptureSource {
+    readonly writer: CaptureWriter;
+    /** `lock` takes the row for the rest of the transaction (FOR UPDATE), so the before image is the one the write replaces. */
+    read(table: string, key: Record<string, string | number>, columns?: string[], lock?: boolean): Promise<Record<string, unknown> | undefined>;
+    /** Up to `limit` rows whose columns equal these values. */
+    rows(table: string, where: Record<string, string | number>, columns: string[], limit: number): Promise<Record<string, unknown>[]>;
+    /**
+     * Where the writer sends together: `ride` runs the moment this table's
+     * UPDATE is sent, so a read it asks leaves in the update's own round trip,
+     * behind it, and reads what it wrote (postgresTransactionHandle.ts
+     * behindWrite). Answers a withdraw, true when `ride` never ran; absent, or
+     * undefined, where nothing rides.
+     */
+    behind?(table: string, ride: () => void): (() => boolean) | undefined;
+}
+/** One transaction's capture: each write runs through it. */
+interface WriteCapture {
+    insert(request: InsertRequest, write: (request: InsertRequest) => Promise<InsertResult>): Promise<InsertResult>;
+    update(request: UpdateRequest, write: (request: UpdateRequest) => Promise<UpdateResult>): Promise<UpdateResult>;
+    remove(request: DeleteRequest, write: (request: DeleteRequest) => Promise<DeleteResult>): Promise<DeleteResult>;
+    /** A flow's notify step (WriteTransaction.tell). */
+    tell(request: TellRequest): Promise<void>;
+    /**
+     * Once, after the transaction's last operation has settled and just before
+     * COMMIT, on the same writer: what a capture keeps per transaction rather
+     * than per write (live sync's change row) is written here, so it commits or
+     * rolls back with the writes it describes. A throw rolls the transaction back.
+     */
+    finish?(): Promise<void>;
+    /** Once, after COMMIT was acknowledged. A nudge only: it never fails the write it follows. */
+    committed?(): void;
+}
+interface WriteCapturer {
+    /** Whether a write to this table of this adapter is captured, so that even a lone write runs inside a transaction the capture's rows can join. */
+    captures(adapter: object, table: unknown): boolean;
+    /** This transaction's capture, or undefined where the adapter captures nothing. */
+    begin(adapter: object, source: CaptureSource): WriteCapture | undefined;
+}
+/** Trusted framework code, once per process. */
+export declare function installWriteCapture(capturer: WriteCapturer): void;
+export declare const capturesWrites: (adapter: object, table: unknown) => boolean;
+export declare const beginWriteCapture: (adapter: object, source: CaptureSource) => WriteCapture | undefined;
+/** The adapters' one way to end a capture: its per-transaction rows, just before COMMIT. */
+export declare const finishWriteCapture: (capture: WriteCapture | undefined) => Promise<void>;
+/** After COMMIT: a capture's nudge to whoever waits on committed changes. Never throws into the write. */
+export declare const committedWriteCapture: (capture: WriteCapture | undefined) => void;
+export {};

package/dist/adapters/writeCapture.js

@@ -0,0 +1,20 @@
+let installed;
+/** Trusted framework code, once per process. */
+export function installWriteCapture(capturer) {
+    installed = capturer;
+}
+export const capturesWrites = (adapter, table) => installed?.captures(adapter, table) ?? false;
+export const beginWriteCapture = (adapter, source) => installed?.begin(adapter, source);
+/** The adapters' one way to end a capture: its per-transaction rows, just before COMMIT. */
+export const finishWriteCapture = async (capture) => {
+    await capture?.finish?.();
+};
+/** After COMMIT: a capture's nudge to whoever waits on committed changes. Never throws into the write. */
+export const committedWriteCapture = (capture) => {
+    try {
+        capture?.committed?.();
+    }
+    catch {
+        /* The write has committed; a listener's failure is its own. */
+    }
+};