@configbutler/krm-stream 0.1.0

package/dist/sse.js

@@ -0,0 +1,215 @@
+// The transport, consumer side. Everything else in this package is pure logic; this is the only file
+// that knows a stream is made of bytes.
+//
+// Two ways in, because there are two authentication stories (spec §7) and neither is optional:
+//
+//   connectResourceStream    fetch-based. Needed for `Authorization: Bearer`, because native
+//                            EventSource cannot send a custom header. Works in Node, so it is what
+//                            the conformance suite drives.
+//   connectWithEventSource   native EventSource. Needed for the same-origin session-cookie case,
+//                            which is the BASELINE a v1 gateway must support.
+//
+// The rule both must obey, and the one that is easy to get wrong: on a TERMINAL error, close the
+// connection. EventSource reconnects automatically otherwise, and will hammer a scope it can never
+// be allowed to see — forever, from every open tab.
+/** Incremental SSE parser. Bytes arrive in whatever chunks the network feels like — a frame can be
+ * split down the middle, and it WILL be, under exactly the load where you least want to debug it —
+ * so this buffers and only yields complete frames. */
+export class SSEDecoder {
+    #buffer = "";
+    /** Feed a chunk of the stream; get back the events that completed with it. */
+    push(chunk) {
+        this.#buffer += chunk;
+        const out = [];
+        // Frames are separated by a blank line. Normalize completed line endings first: an SSE line may
+        // end \n, \r\n or bare \r, but a trailing \r may be the first byte of a split \r\n pair.
+        const trailingCR = this.#buffer.endsWith("\r");
+        const complete = trailingCR ? this.#buffer.slice(0, -1) : this.#buffer;
+        this.#buffer = complete.replace(/\r\n|\r/g, "\n") + (trailingCR ? "\r" : "");
+        for (;;) {
+            const sep = this.#buffer.indexOf("\n\n");
+            if (sep === -1)
+                break; // an incomplete frame stays in the buffer until the rest of it arrives
+            const frame = this.#buffer.slice(0, sep);
+            this.#buffer = this.#buffer.slice(sep + 2);
+            const ev = parseFrame(frame);
+            if (ev)
+                out.push(ev);
+        }
+        return out;
+    }
+}
+/** Tracks the mandatory per-connection event sequence. The first missing frame is enough to make
+ * state uncertain, so transports close and reconnect rather than applying a possibly stale tail. */
+export class StreamSequence {
+    #next = 1;
+    observe(event) {
+        if (!Number.isSafeInteger(event.seq) || event.seq !== this.#next) {
+            return { expected: this.#next, received: event.seq };
+        }
+        this.#next++;
+        return null;
+    }
+}
+/** One SSE frame -> one event, or null for a frame that carries none (a heartbeat, a comment).
+ *
+ * A comment is not an error and not an event: it is how a heartbeat is invisible to a consumer while
+ * still keeping an idle proxy from closing the connection out from under a live status watch. */
+function parseFrame(frame) {
+    const data = [];
+    for (const line of frame.split("\n")) {
+        if (line === "" || line.startsWith(":"))
+            continue; // comment / heartbeat
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        // "data: x" and "data:x" are the same field; exactly one leading space is stripped.
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        // `event:`, `id:` and `retry:` are SSE fields this protocol does not use (v1 emits no id: lines
+        // at all — §7). Ignoring them rather than failing is the same rule as ignoring an unknown event
+        // type: a minor addition must not break an older client.
+        if (field === "data")
+            data.push(value);
+    }
+    if (data.length === 0)
+        return null;
+    try {
+        return JSON.parse(data.join("\n"));
+    }
+    catch {
+        // A frame we cannot parse is not a reason to tear down a live stream. Skip it: the protocol is
+        // state-convergent, so the next snapshot cycle repairs whatever we missed.
+        return null;
+    }
+}
+/** What a stream event does to a store. This is the consumer's half of the event table (spec §4), and
+ * it is exported because it IS the protocol — a host feeding a store from its own transport should
+ * not have to reimplement the switch and get `synced` subtly wrong.
+ *
+ * Returns the paths that flashed, so a UI can highlight them. */
+export function applyStreamEvent(store, ev) {
+    switch (ev.type) {
+        case "reset":
+            store.beginSnapshot();
+            return [];
+        case "added":
+        case "modified":
+            if (!ev.object)
+                return [];
+            return store.applyServerEvent(ev.object, { redacted: ev.redacted }).flashed;
+        case "deleted":
+            if (ev.identity?.uid)
+                store.removeResource(ev.identity.uid);
+            return [];
+        case "synced":
+            store.endSnapshot();
+            return [];
+        default:
+            // An unknown event type MUST be ignored, not treated as an error (spec §0). That is what lets
+            // the gateway add an optional event type later without breaking a browser nobody can update.
+            return [];
+    }
+}
+/** Consume a resource stream over fetch, feeding a store. Use this when the gateway authenticates
+ * with a bearer token — native EventSource cannot send the header. */
+export function connectResourceStream(url, store, opts = {}) {
+    if (opts.signal?.aborted)
+        return { close: () => { }, closed: Promise.resolve() };
+    const controller = new AbortController();
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    opts.signal?.addEventListener("abort", () => controller.abort(), { once: true });
+    const closed = (async () => {
+        const res = await fetchImpl(url, {
+            signal: controller.signal,
+            headers: { Accept: "text/event-stream", ...opts.headers },
+            // The stream IS the response body; a cached one is a stream that never moves.
+            cache: "no-store",
+        });
+        if (!res.ok || !res.body) {
+            opts.onError?.("INTERNAL", `stream: HTTP ${res.status}`, true);
+            return;
+        }
+        const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
+        const decoder = new SSEDecoder();
+        const sequence = new StreamSequence();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                for (const ev of decoder.push(value)) {
+                    if (feed(store, sequence, ev, opts)) {
+                        controller.abort(); // terminal: stop, and do NOT come back
+                        return;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (!controller.signal.aborted)
+                throw err;
+        }
+        finally {
+            reader.cancel().catch(() => { });
+        }
+    })();
+    return {
+        close: () => controller.abort(),
+        closed: closed.catch(() => { }),
+    };
+}
+/** Consume a resource stream with the browser's native EventSource. This is the same-origin
+ * session-cookie path — the baseline a v1 gateway MUST support, because a cookie is the only
+ * credential EventSource can carry. */
+export function connectWithEventSource(url, store, opts = {}) {
+    if (opts.signal?.aborted)
+        return { close: () => { }, closed: Promise.resolve() };
+    const es = new EventSource(url, { withCredentials: true });
+    const sequence = new StreamSequence();
+    let resolve;
+    const closed = new Promise((r) => {
+        resolve = r;
+    });
+    const shut = () => {
+        es.close();
+        resolve();
+    };
+    es.onmessage = (e) => {
+        let ev;
+        try {
+            ev = JSON.parse(e.data);
+        }
+        catch {
+            return; // an unparseable frame is not a reason to tear down a live stream
+        }
+        if (feed(store, sequence, ev, opts))
+            shut();
+    };
+    // EventSource's `error` is also fired on a transport hiccup, where its OWN reconnect is the
+    // correct behaviour and we must not interfere. Only a terminal PROTOCOL error (which arrives as a
+    // message, above) closes the connection — and it must, or this reconnects forever.
+    es.onerror = () => {
+        if (es.readyState === EventSource.CLOSED)
+            resolve();
+    };
+    opts.signal?.addEventListener("abort", shut, { once: true });
+    return { close: shut, closed };
+}
+/** Apply one event; returns true if the stream must now be closed. */
+function feed(store, sequence, ev, opts) {
+    const gap = sequence.observe(ev);
+    if (gap) {
+        opts.onGap?.(gap.expected, gap.received);
+        return true;
+    }
+    if (ev.type === "error") {
+        opts.onError?.(ev.code ?? "INTERNAL", ev.message ?? "", ev.terminal ?? false);
+        return ev.terminal === true;
+    }
+    const flashed = applyStreamEvent(store, ev);
+    if (ev.type === "synced")
+        opts.onSynced?.();
+    opts.onChange?.(flashed);
+    return false;
+}

package/dist/store.d.ts

@@ -0,0 +1,98 @@
+import type { Change, Conflict, EditabilityPolicy, KRMObject, Path, Redaction } from "./types.ts";
+/** What one server event did, for a host that wants to animate it. `flashed` is an OUTPUT, not
+ * state: the host highlights those paths and forgets them. */
+export interface ApplyResult {
+    /** The uid was not known: this is an arrival, not a change. */
+    added: boolean;
+    /** Keys or array elements appeared or disappeared — a UI must rebuild rows, not just re-read values. */
+    structural: boolean;
+    /** Paths the server moved, in read-only regions and in editable regions the user had not touched. */
+    flashed: Path[];
+    /** The paths this object is now conflicted at (the complete set, not just the new ones). */
+    conflicts: Path[];
+}
+export interface ApplyOptions {
+    /** Values the projection withheld. Their paths are read-only, never dirtiable, and never in a patch. */
+    redacted?: (Redaction | {
+        path: Path;
+        rev: number;
+    })[];
+}
+export declare class LiveResourceStore {
+    #private;
+    constructor(policy?: EditabilityPolicy);
+    /** `added` and `modified` — the only two upsert spellings, and they are treated identically
+     * (spec §4). Both mean "here is this object's complete current state". */
+    applyServerEvent(object: KRMObject, opts?: ApplyOptions): ApplyResult;
+    /** `deleted`. The object is gone, and so is any draft of it — the user was editing something that
+     * no longer exists. (A recreate under the same name is a DIFFERENT uid and starts clean; that is
+     * the whole reason identity is the uid.) */
+    removeResource(id: string): void;
+    /** `reset`. Mark every known uid unseen — and prune NOTHING yet. */
+    beginSnapshot(): void;
+    /** `synced`. The snapshot is complete, so what it did not mention is genuinely gone. This is the
+     * only place anything is pruned, and it is what removes an object deleted while the consumer was
+     * disconnected — the one event the consumer never saw. */
+    endSnapshot(): void;
+    /** The save succeeded and this is the object it produced. The watch will echo it too — and that
+     * echo is a harmless no-op (I-IDEMPOTENT) — but a UI should not have to wait for it to stop
+     * showing the field as dirty. */
+    adoptSaved(object: KRMObject): void;
+    setValue(id: string, path: Path, value: unknown): void;
+    /** For a map entry or an object key the user deleted. It stays deleted across watch events (the
+     * merge sees ours=undefined, base=theirs and keeps the deletion) and becomes a `null` in the patch. */
+    removeKey(id: string, path: Path): void;
+    /** `path` addresses the MAP; `key` is the new entry. A new row in a UI starts empty. */
+    addKey(id: string, path: Path, key: string, value?: unknown): void;
+    /** `path` addresses the MAP. Order is preserved — renaming a label must not make its row jump to
+     * the bottom of the list while the user is typing in it. */
+    renameKey(id: string, path: Path, oldKey: string, newKey: string): void;
+    /** Throw the local edit away and take the server's value — which is also how a conflict is
+     * resolved in the server's favour. */
+    revert(id: string, path: Path): void;
+    /** Resolve a conflict by keeping the server's value. */
+    takeTheirs(id: string, path: Path): void;
+    ids(): string[];
+    /** The authoritative server object, including live `status`. */
+    server(id: string): KRMObject;
+    /** The server object with the editable regions merged over it. What a UI renders and edits. */
+    draft(id: string): KRMObject;
+    /** Read-only convenience for the watch UI. A kind with no status simply has none. */
+    status(id: string): unknown;
+    /** Every pending edit, derived fresh by comparing the draft to the server object. Arrays appear
+     * whole (§4.1), which is also what RFC 7386 wants. */
+    changes(id: string): Change[];
+    /** R-DERIVED: never a stored flag. A read-only path is never dirty by construction. */
+    isDirty(id: string, path: Path): boolean;
+    conflicts(id: string): Conflict[];
+    /** The policy, minus this object's redacted paths. A redacted value is read-only for exactly the
+     * same reason `status` is: it is not the user's to change — and here, they never even saw it. */
+    isEditable(id: string, path: Path): boolean;
+    /**
+     * The paths whose values the gateway withheld. **This is the only place a consumer learns that a
+     * redacted field exists**, and rendering it is the whole of keys-only disclosure.
+     *
+     * The value itself is not in the object — there is no mask, no placeholder, nothing (spec §3). So a
+     * UI showing `token ••••••` reads it from HERE, not from the object:
+     *
+     * ```ts
+     * for (const { path } of store.redactions(uid)) row(path, "••••••", { readOnly: true });
+     * ```
+     *
+     * That is deliberate. A placeholder sitting in the object is a value a browser can save back — and
+     * a merge patch carrying it writes the placeholder over the real Secret.
+     */
+    redactions(id: string): {
+        path: Path;
+        rev: number;
+    }[];
+    /** An RFC 7386 merge patch of the editable changes, or null when there is nothing to save.
+     *
+     * Built from the user's EDITS — never from a diff of the whole object against the server. The
+     * object on the wire is a projection: a path the projection removed is simply not there, and a
+     * whole-object diff would read that absence as a deletion and try to patch it away (spec §3). */
+    patch(id: string): Record<string, unknown> | null;
+    /** A coarse "something changed" signal — the host re-renders and re-queries. Returns an
+     * unsubscribe. */
+    subscribe(cb: () => void): () => void;
+}

package/dist/store.js

@@ -0,0 +1,340 @@
+// LiveResourceStore — the consumer half of the protocol (spec §10) and the engine of
+// docs/client-state-model.md.
+//
+// It holds, per uid:
+//
+//   server(id)   the authoritative projected object. REPLACED by every added/modified — never
+//                deep-merged, because a deep merge of complete objects cannot express a removal and
+//                so resurrects the field the server just deleted (spec §4.1). It is also the merge
+//                BASE, and it advances on every event (I-BASESHIFT).
+//   draft(id)    the same object with the editable regions three-way merged against the user's edits.
+//
+// Dirtiness is not in that list, on purpose: it is DERIVED, every time it is asked for (R-DERIVED).
+// A cached dirty set goes stale on the next watch event — the field the server converged onto stays
+// flagged forever, or unflags itself only on the next click.
+import { clone, deepEqual, isPlainObject } from "./deep.js";
+import { reconcile } from "./merge.js";
+import { get, has, isPrefix, parsePointer, pathKey, removeAt, setAt } from "./path.js";
+import { defaultPolicy } from "./policy.js";
+export class LiveResourceStore {
+    #policy;
+    #resources = new Map();
+    #subscribers = new Set();
+    /** Non-null exactly while a snapshot cycle is open: the uids seen since `beginSnapshot()`.
+     * Pruning reads it in `endSnapshot()` and NOWHERE else — a cycle that never completes must prune
+     * nothing, or a network hiccup makes the user watch half their resources evaporate (spec §5). */
+    #seen = null;
+    constructor(policy = defaultPolicy) {
+        this.#policy = policy;
+    }
+    // ------------------------------------------------------------------ the stream in --
+    /** `added` and `modified` — the only two upsert spellings, and they are treated identically
+     * (spec §4). Both mean "here is this object's complete current state". */
+    applyServerEvent(object, opts = {}) {
+        const id = object.metadata.uid;
+        const incoming = clone(object);
+        const redacted = (opts.redacted ?? []).map((entry) => ({
+            path: typeof entry.path === "string" ? parsePointer(entry.path) : [...entry.path],
+            rev: entry.rev,
+        }));
+        this.#seen?.add(id);
+        const existing = this.#resources.get(id);
+        if (!existing) {
+            // A resource we have never seen: base = draft = incoming. There is nothing to merge, and
+            // nothing flashes — an arrival is not a change.
+            this.#resources.set(id, { server: incoming, draft: clone(incoming), redacted, conflicts: new Map() });
+            this.#notify();
+            return { added: true, structural: true, flashed: [], conflicts: [] };
+        }
+        const state = {
+            regions: this.#regionsFor(incoming, redacted.map((r) => r.path)),
+            conflicts: existing.conflicts,
+            flashed: [],
+        };
+        const merged = reconcile(state, existing.server, existing.draft, incoming);
+        const structural = !sameShape(existing.draft, merged);
+        // The REPLACEMENT (spec §4.1) and the base shift (I-BASESHIFT), in one line. Everything above
+        // reconciled against the OLD server object; from here on, `incoming` is the base.
+        existing.server = incoming;
+        existing.draft = merged;
+        existing.redacted = redacted;
+        this.#notify();
+        return {
+            added: false,
+            structural,
+            flashed: state.flashed,
+            conflicts: [...existing.conflicts.values()].map((c) => c.path),
+        };
+    }
+    /** `deleted`. The object is gone, and so is any draft of it — the user was editing something that
+     * no longer exists. (A recreate under the same name is a DIFFERENT uid and starts clean; that is
+     * the whole reason identity is the uid.) */
+    removeResource(id) {
+        if (this.#resources.delete(id))
+            this.#notify();
+    }
+    /** `reset`. Mark every known uid unseen — and prune NOTHING yet. */
+    beginSnapshot() {
+        this.#seen = new Set();
+    }
+    /** `synced`. The snapshot is complete, so what it did not mention is genuinely gone. This is the
+     * only place anything is pruned, and it is what removes an object deleted while the consumer was
+     * disconnected — the one event the consumer never saw. */
+    endSnapshot() {
+        const seen = this.#seen;
+        if (!seen)
+            return; // a `synced` with no open cycle: ignore, do not prune the world
+        this.#seen = null;
+        let pruned = false;
+        for (const id of [...this.#resources.keys()]) {
+            if (!seen.has(id)) {
+                this.#resources.delete(id);
+                pruned = true;
+            }
+        }
+        if (pruned)
+            this.#notify();
+    }
+    /** The save succeeded and this is the object it produced. The watch will echo it too — and that
+     * echo is a harmless no-op (I-IDEMPOTENT) — but a UI should not have to wait for it to stop
+     * showing the field as dirty. */
+    adoptSaved(object) {
+        const existing = this.#resources.get(object.metadata.uid);
+        if (!existing) {
+            this.applyServerEvent(object);
+            return;
+        }
+        // A save response is another complete server object. Reconcile it rather than replacing the
+        // draft so an edit made after the request was sent survives the response arriving.
+        this.applyServerEvent(object, { redacted: existing.redacted });
+    }
+    // ------------------------------------------------------------------------- edits --
+    setValue(id, path, value) {
+        const res = this.#editable(id, path);
+        setAt(res.draft, path, clone(value));
+        this.#settle(res, path);
+    }
+    /** For a map entry or an object key the user deleted. It stays deleted across watch events (the
+     * merge sees ours=undefined, base=theirs and keeps the deletion) and becomes a `null` in the patch. */
+    removeKey(id, path) {
+        const res = this.#editable(id, path);
+        removeAt(res.draft, path);
+        this.#settle(res, path);
+    }
+    /** `path` addresses the MAP; `key` is the new entry. A new row in a UI starts empty. */
+    addKey(id, path, key, value = "") {
+        const res = this.#editable(id, [...path, key]);
+        setAt(res.draft, [...path, key], clone(value));
+        this.#settle(res, [...path, key]);
+    }
+    /** `path` addresses the MAP. Order is preserved — renaming a label must not make its row jump to
+     * the bottom of the list while the user is typing in it. */
+    renameKey(id, path, oldKey, newKey) {
+        const res = this.#editable(id, [...path, oldKey]);
+        this.#editable(id, [...path, newKey]);
+        const map = get(res.draft, path);
+        if (!isPlainObject(map))
+            throw new Error(`krm-stream: ${pathKey(path)} is not a map`);
+        if (!Object.hasOwn(map, oldKey))
+            throw new Error(`krm-stream: key ${JSON.stringify(oldKey)} does not exist`);
+        if (oldKey !== newKey && Object.hasOwn(map, newKey)) {
+            throw new Error(`krm-stream: key ${JSON.stringify(newKey)} already exists`);
+        }
+        const renamed = {};
+        for (const [k, v] of Object.entries(map))
+            renamed[k === oldKey ? newKey : k] = v;
+        setAt(res.draft, path, renamed);
+        this.#settle(res, [...path, oldKey]);
+        this.#settle(res, [...path, newKey]);
+    }
+    /** Throw the local edit away and take the server's value — which is also how a conflict is
+     * resolved in the server's favour. */
+    revert(id, path) {
+        const res = this.#editable(id, path);
+        if (has(res.server, path))
+            setAt(res.draft, path, clone(get(res.server, path)));
+        else
+            removeAt(res.draft, path);
+        this.#settle(res, path);
+    }
+    /** Resolve a conflict by keeping the server's value. */
+    takeTheirs(id, path) {
+        this.revert(id, path);
+    }
+    // ----------------------------------------------------------------------- queries --
+    ids() {
+        return [...this.#resources.keys()];
+    }
+    /** The authoritative server object, including live `status`. */
+    server(id) {
+        return clone(this.#must(id).server);
+    }
+    /** The server object with the editable regions merged over it. What a UI renders and edits. */
+    draft(id) {
+        return clone(this.#must(id).draft);
+    }
+    /** Read-only convenience for the watch UI. A kind with no status simply has none. */
+    status(id) {
+        return clone(this.#must(id).server.status);
+    }
+    /** Every pending edit, derived fresh by comparing the draft to the server object. Arrays appear
+     * whole (§4.1), which is also what RFC 7386 wants. */
+    changes(id) {
+        const res = this.#must(id);
+        const out = [];
+        this.#diff(this.#regionsFor(res.server, res.redacted.map((r) => r.path)), [], res.server, res.draft, out);
+        return out;
+    }
+    /** R-DERIVED: never a stored flag. A read-only path is never dirty by construction. */
+    isDirty(id, path) {
+        const res = this.#must(id);
+        if (this.isEditable(id, path))
+            return !deepEqual(get(res.server, path), get(res.draft, path));
+        // A container (`[]`, `["metadata"]`) is dirty iff something editable underneath it is.
+        if (!this.#policy.containsEditable(res.server, path))
+            return false;
+        return this.changes(id).some((c) => isPrefix(path, c.path));
+    }
+    conflicts(id) {
+        return [...this.#must(id).conflicts.values()].map((c) => ({ path: [...c.path], theirs: clone(c.theirs) }));
+    }
+    /** The policy, minus this object's redacted paths. A redacted value is read-only for exactly the
+     * same reason `status` is: it is not the user's to change — and here, they never even saw it. */
+    isEditable(id, path) {
+        const res = this.#must(id);
+        return this.#regionsFor(res.server, res.redacted.map((r) => r.path)).editable(path);
+    }
+    /**
+     * The paths whose values the gateway withheld. **This is the only place a consumer learns that a
+     * redacted field exists**, and rendering it is the whole of keys-only disclosure.
+     *
+     * The value itself is not in the object — there is no mask, no placeholder, nothing (spec §3). So a
+     * UI showing `token ••••••` reads it from HERE, not from the object:
+     *
+     * ```ts
+     * for (const { path } of store.redactions(uid)) row(path, "••••••", { readOnly: true });
+     * ```
+     *
+     * That is deliberate. A placeholder sitting in the object is a value a browser can save back — and
+     * a merge patch carrying it writes the placeholder over the real Secret.
+     */
+    redactions(id) {
+        return this.#must(id).redacted.map((r) => ({ path: [...r.path], rev: r.rev }));
+    }
+    /** An RFC 7386 merge patch of the editable changes, or null when there is nothing to save.
+     *
+     * Built from the user's EDITS — never from a diff of the whole object against the server. The
+     * object on the wire is a projection: a path the projection removed is simply not there, and a
+     * whole-object diff would read that absence as a deletion and try to patch it away (spec §3). */
+    patch(id) {
+        const changes = this.changes(id);
+        if (changes.length === 0)
+            return null;
+        const out = {};
+        for (const c of changes)
+            setAt(out, c.path, c.new === undefined ? null : clone(c.new));
+        return out;
+    }
+    /** A coarse "something changed" signal — the host re-renders and re-queries. Returns an
+     * unsubscribe. */
+    subscribe(cb) {
+        this.#subscribers.add(cb);
+        return () => this.#subscribers.delete(cb);
+    }
+    // ---------------------------------------------------------------------- internals --
+    #must(id) {
+        const res = this.#resources.get(id);
+        if (!res)
+            throw new Error(`krm-stream: no resource ${JSON.stringify(id)}`);
+        return res;
+    }
+    /** Every edit goes through here: a write to `status`, to `metadata.name`, or to a redacted path is
+     * refused. The engine is not the security boundary — the gateway rejects such a patch too — but a
+     * UI that cannot even form the edit is the difference between "safe" and "safe if the client is
+     * honest". */
+    #editable(id, path) {
+        const res = this.#must(id);
+        if (!this.isEditable(id, path)) {
+            throw new Error(`krm-stream: ${pathKey(path)} is read-only`);
+        }
+        return res;
+    }
+    #regionsFor(object, redacted) {
+        const insideRedacted = (path) => redacted.some((r) => isPrefix(r, path));
+        const containsRedacted = (path) => redacted.some((r) => isPrefix(path, r));
+        return {
+            editable: (path) => !insideRedacted(path) && !containsRedacted(path) && this.#policy.isEditable(object, path),
+            container: (path) => !insideRedacted(path) && this.#policy.containsEditable(object, path),
+            listMapKeys: (path) => this.#policy.listMapKeys?.(object, path),
+        };
+    }
+    /** After an edit: a conflict whose path the draft has now brought back to the server's value is no
+     * longer a conflict. (Typing the server's value by hand resolves it, and so does `revert`.) */
+    #settle(res, path) {
+        for (const [k, c] of res.conflicts) {
+            if (!isPrefix(c.path, path) && !isPrefix(path, c.path))
+                continue;
+            if (deepEqual(get(res.server, c.path), get(res.draft, c.path)))
+                res.conflicts.delete(k);
+        }
+        this.#notify();
+    }
+    #diff(regions, path, srv, drf, out) {
+        if (regions.editable(path)) {
+            const defined = [srv, drf].filter((v) => v !== undefined);
+            if (defined.length > 0 && defined.every(isPlainObject)) {
+                for (const k of unionKeys(srv, drf)) {
+                    this.#diff(regions, [...path, k], srv?.[k], drf?.[k], out);
+                }
+                return;
+            }
+            // Scalars, arrays, and shape changes are one atomic value — the same rule the merge uses, so
+            // "what is dirty" and "what was merged atomically" can never disagree.
+            if (!deepEqual(srv, drf)) {
+                const kind = srv === undefined ? "add" : drf === undefined ? "delete" : "update";
+                out.push({ path: [...path], kind, old: clone(srv), new: clone(drf) });
+            }
+            return;
+        }
+        if (regions.container(path)) {
+            for (const k of unionKeys(srv, drf)) {
+                this.#diff(regions, [...path, k], srv?.[k], drf?.[k], out);
+            }
+        }
+        // Read-only: the draft IS the server there. Nothing to diff, nothing to save.
+    }
+    #notify() {
+        for (const cb of this.#subscribers)
+            cb();
+    }
+}
+function unionKeys(...values) {
+    const keys = [];
+    const seen = new Set();
+    for (const v of values) {
+        if (!isPlainObject(v))
+            continue;
+        for (const k of Object.keys(v)) {
+            if (!seen.has(k)) {
+                seen.add(k);
+                keys.push(k);
+            }
+        }
+    }
+    return keys;
+}
+/** Did keys or array elements appear or disappear? A UI can re-read values cheaply; it must REBUILD
+ * when rows come and go — that is what `structural` tells it. Scalar value changes are not structural. */
+function sameShape(a, b) {
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        if (ka.length !== kb.length)
+            return false;
+        return ka.every((k) => Object.hasOwn(b, k) && sameShape(a[k], b[k]));
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((x, i) => sameShape(x, b[i]));
+    }
+    return isPlainObject(a) === isPlainObject(b) && Array.isArray(a) === Array.isArray(b);
+}