@configbutler/krm-stream 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# @configbutler/krm-stream
+
+`@configbutler/krm-stream` is the official dependency-free ESM client for consuming a KRM resource
+stream in a browser or JavaScript application. It provides:
+
+- `LiveResourceStore` for server state, local drafts, conflicts, redactions, and merge patches.
+- `connectWithEventSource` for same-origin browser streams.
+- `connectResourceStream` for fetch-based transports with explicit headers.
+- `resourceStreamURL` for the v1 scope query format.
+
+The package is headless and does not choose a UI framework. It works with the Go gateway in this
+repository or any conforming producer.
+
+```ts
+import { LiveResourceStore, connectWithEventSource, resourceStreamURL } from "@configbutler/krm-stream";
+
+const store = new LiveResourceStore();
+connectWithEventSource(
+  resourceStreamURL("/resource-stream/v1", { version: "v1", resource: "configmaps", namespace: "app" }),
+  store,
+);
+```
+
+The unscoped `krm-stream` package is a compatibility forwarder. This project is pre-1.0 and has not
+been published to npm yet. See the repository [README](../../README.md),
+[client state model](../../docs/client-state-model.md), and [release guide](../../docs/releasing.md).

package/dist/deep.d.ts

@@ -0,0 +1,14 @@
+/** A plain JSON object — an object that is not an array and not null. Everything a KRM object
+ * contains is one of: plain object, array, string, number, boolean, null. */
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+/** Recursive, KEY-ORDER-INDEPENDENT structural equality (I-ORDER-EQ).
+ *
+ * `JSON.stringify(a) === JSON.stringify(b)` is the tempting one-liner and it is wrong: an API
+ * server may serialize the same object with its keys in a different order, and stringify-equality
+ * then reports a change that did not happen — which flashes the UI, and worse, makes an untouched
+ * field look like it "moved" so a three-way merge stops leaving edits alone. */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** A deep copy of a JSON value. The store never hands out a reference into its own state, and never
+ * keeps a reference into a caller's object: a draft that aliases the server snapshot would make the
+ * base drift silently as the user types, and the three-way merge would compare an object to itself. */
+export declare function clone<T>(v: T): T;

package/dist/deep.js

@@ -0,0 +1,44 @@
+// Structural comparison and cloning of JSON values. No dependencies, and deliberately not
+// `structuredClone`/`JSON.stringify` — see below.
+/** A plain JSON object — an object that is not an array and not null. Everything a KRM object
+ * contains is one of: plain object, array, string, number, boolean, null. */
+export function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Recursive, KEY-ORDER-INDEPENDENT structural equality (I-ORDER-EQ).
+ *
+ * `JSON.stringify(a) === JSON.stringify(b)` is the tempting one-liner and it is wrong: an API
+ * server may serialize the same object with its keys in a different order, and stringify-equality
+ * then reports a change that did not happen — which flashes the UI, and worse, makes an untouched
+ * field look like it "moved" so a three-way merge stops leaving edits alone. */
+export function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((x, i) => deepEqual(x, b[i]));
+    }
+    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) && deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/** A deep copy of a JSON value. The store never hands out a reference into its own state, and never
+ * keeps a reference into a caller's object: a draft that aliases the server snapshot would make the
+ * base drift silently as the user types, and the three-way merge would compare an object to itself. */
+export function clone(v) {
+    if (Array.isArray(v))
+        return v.map(clone);
+    if (isPlainObject(v)) {
+        const out = {};
+        for (const [k, x] of Object.entries(v))
+            out[k] = clone(x);
+        return out;
+    }
+    return v;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { clone, deepEqual } from "./deep.ts";
+export { get, has, isPrefix, parsePointer, pathKey } from "./path.ts";
+export { DEFAULT_EDITABLE_REGIONS, defaultPolicy, readOnlyPolicy, regionPolicy } from "./policy.ts";
+export type { KubernetesStructuralSchema } from "./schema.ts";
+export { withOpenAPIKeyedLists } from "./schema.ts";
+export type { StreamHandle, StreamOptions } from "./sse.ts";
+export { applyStreamEvent, connectResourceStream, connectWithEventSource, SSEDecoder, StreamSequence } from "./sse.ts";
+export type { ApplyOptions, ApplyResult } from "./store.ts";
+export { LiveResourceStore } from "./store.ts";
+export type { Change, Conflict, EditabilityPolicy, ErrorCode, EventType, Identity, KRMObject, Path, Projection, Redaction, Scope, StreamEvent, } from "./types.ts";
+export type { ScopeQuery } from "./url.ts";
+export { resourceStreamURL } from "./url.ts";
+export { PROTOCOL_VERSION, VERSION } from "./version.ts";

package/dist/index.js

@@ -0,0 +1,24 @@
+// krm-stream — a live, honest window onto Kubernetes resources, in the browser.
+//
+// The public surface is small on purpose:
+//
+//   LiveResourceStore      holds server truth + your draft; three-way merges every watch event;
+//                          derives dirtiness; tracks conflicts; builds the merge patch.
+//   connectResourceStream  a conforming SSE consumer that feeds a store.
+//   resourceStreamURL      builds the stream URL from a scope — the encoding the gateway parses back.
+//
+// The store is built test-first against conformance/ — the same fixtures the Go gateway runs. See
+// ../../../docs/client-state-model.md for the algorithm, ../../../spec/v1.md for the wire, and
+// CONTRIBUTING.md for the order of work.
+//
+// No runtime dependencies, and none of this knows anything about GitOps, Flux, Dex, kcp or
+// ConfigButler. It knows KRM.
+// Useful to a host that renders paths, and to anyone writing a policy: identity is a segment ARRAY.
+export { clone, deepEqual } from "./deep.js";
+export { get, has, isPrefix, parsePointer, pathKey } from "./path.js";
+export { DEFAULT_EDITABLE_REGIONS, defaultPolicy, readOnlyPolicy, regionPolicy } from "./policy.js";
+export { withOpenAPIKeyedLists } from "./schema.js";
+export { applyStreamEvent, connectResourceStream, connectWithEventSource, SSEDecoder, StreamSequence } from "./sse.js";
+export { LiveResourceStore } from "./store.js";
+export { resourceStreamURL } from "./url.js";
+export { PROTOCOL_VERSION, VERSION } from "./version.js";

package/dist/merge.d.ts

@@ -0,0 +1,21 @@
+import type { Conflict, Path } from "./types.ts";
+/** The store's per-resource view of which paths are editable — the policy, minus the paths this
+ * particular object declared redacted. */
+export interface Regions {
+    /** This path is inside an editable region: three-way merge it. */
+    editable(path: Path): boolean;
+    /** Not editable itself, but an editable region lives underneath: recurse, don't replace. */
+    container(path: Path): boolean;
+    /** Identity fields for a schema-declared Kubernetes associative list, if this is one. */
+    listMapKeys(path: Path): readonly string[] | undefined;
+}
+export interface MergeState {
+    regions: Regions;
+    /** Conflicts persist between events — a conflict the next event does not touch is still a
+     * conflict. (Dirtiness is the opposite: derived, never stored. R-DERIVED.) */
+    conflicts: Map<string, Conflict>;
+    /** An output, not state: the paths the server moved. The host flashes them and forgets them. */
+    flashed: Path[];
+}
+/** Reconcile one resource. Returns the new draft. */
+export declare function reconcile(s: MergeState, base: unknown, ours: unknown, theirs: unknown): unknown;

package/dist/merge.js

@@ -0,0 +1,212 @@
+// The deep three-way reconcile (docs/client-state-model.md §4).
+//
+//   base   the PREVIOUS server object we last reconciled from
+//   ours   the user's working draft
+//   theirs the complete incoming server object
+//
+// The base is the whole point (R-THREEWAY). Compare `theirs` to `ours` instead and you cannot tell
+// "the server changed this" from "the user typed this", so every watch event looks like the server
+// changed everything the user touched — and a controller's status heartbeat false-conflicts an edit
+// three fields away. Only a path where base ≠ theirs was actually moved by the server.
+//
+// Note what is NOT here: replacing the authoritative server object. That happens in the store, and
+// it is a REPLACEMENT, never a merge (spec §4.1) — merging complete server objects resurrects the
+// fields the server just removed. These are two layers, and conflating them is the ghost bug.
+import { clone, deepEqual, isPlainObject } from "./deep.js";
+import { at, isPrefix, pathKey } from "./path.js";
+/** Reconcile one resource. Returns the new draft. */
+export function reconcile(s, base, ours, theirs) {
+    return node(s, [], base, ours, theirs);
+}
+function node(s, path, base, ours, theirs) {
+    if (s.regions.editable(path))
+        return mergeEditable(s, path, base, ours, theirs);
+    if (s.regions.container(path))
+        return mergeContainer(s, path, base, ours, theirs);
+    return follow(s, path, base, theirs);
+}
+/** A read-only region: take the server's value, flash what moved, and never look at the draft.
+ * There is no draft here to look at — that is what read-only MEANS — but it still updates live. */
+function follow(s, path, base, theirs) {
+    if (isPlainObject(base) && isPlainObject(theirs)) {
+        const out = {};
+        for (const k of unionKeys(base, theirs)) {
+            const v = follow(s, [...path, k], at(base, k), at(theirs, k));
+            if (v !== undefined)
+                out[k] = v;
+        }
+        return out; // structurally clone(theirs): a key `theirs` lacks is GONE, not retained
+    }
+    // Arrays flash atomically, at the array's own path — a UI highlights "the conditions changed",
+    // not "conditions[0].reason changed", and §4.1 treats arrays as one value anyway.
+    if (!deepEqual(base, theirs))
+        s.flashed.push(path);
+    return clone(theirs);
+}
+/** Not editable, but an editable region is somewhere below (`[]`, `["metadata"]`). Recurse and let
+ * each child dispatch for itself: `metadata.labels` is merged while `metadata.name` beside it
+ * follows the server. */
+function mergeContainer(s, path, base, ours, theirs) {
+    if (!isPlainObject(base) && !isPlainObject(ours) && !isPlainObject(theirs)) {
+        return follow(s, path, base, theirs);
+    }
+    return recurse(s, path, base, ours, theirs);
+}
+function mergeEditable(s, path, base, ours, theirs) {
+    const keys = s.regions.listMapKeys(path);
+    if (keys && isAssociativeList(base, keys) && isAssociativeList(ours, keys) && isAssociativeList(theirs, keys)) {
+        return mergeAssociativeList(s, path, keys, base, ours, theirs);
+    }
+    const defined = [base, ours, theirs].filter((v) => v !== undefined);
+    if (defined.length > 0 && defined.every(isPlainObject))
+        return recurse(s, path, base, ours, theirs);
+    // Everything else — scalars, arrays, and any node where the three disagree about their very shape
+    // — is ONE atomic value.
+    //
+    // For arrays this is docs §4.1, and it is coarse on purpose: a positional merge of an array whose
+    // length moved mis-aligns (a PREPENDED sidecar would merge the user's edit into the wrong
+    // container), so a dirty array is treated as a single value and the user's version wins until they
+    // resolve it. RFC 7386 replaces arrays wholesale too, so the patch format needs no special case.
+    if (deepEqual(base, ours)) {
+        // The user has no edit here. Follow the server — including following it into deletion.
+        if (!deepEqual(base, theirs))
+            s.flashed.push(path);
+        clearConflict(s, path);
+        return clone(theirs);
+    }
+    // Dirty: `ours` diverged from `base`. The user's value is never silently overwritten.
+    if (deepEqual(base, theirs))
+        return clone(ours); // the server did not move it — no conflict (I-NOFALSE)
+    if (deepEqual(ours, theirs)) {
+        clearConflict(s, path); // the server arrived at what the user typed (I-CONVERGE)
+        return clone(ours);
+    }
+    setConflict(s, path, theirs);
+    return clone(ours);
+}
+/** Merge Kubernetes `listType: map` entries by their declared key rather than their position.
+ *
+ * A merge patch still writes the resulting array as a whole, because RFC 7386 has no keyed-array
+ * operation. The important part is that its value starts with the latest server list and carries the
+ * user's independent element edits across a reorder, append, or unrelated element change. */
+function mergeAssociativeList(s, path, keys, base, ours, theirs) {
+    const baseByKey = indexAssociativeList(base, keys);
+    const oursByKey = indexAssociativeList(ours, keys);
+    const theirsByKey = indexAssociativeList(theirs, keys);
+    if (!baseByKey || !oursByKey || !theirsByKey)
+        return mergeAtomic(s, path, base, ours, theirs);
+    // Server order is authoritative for entries it has. Locally-added or locally-preserved entries
+    // without a server position follow in their draft order, which keeps a user's new row stable.
+    const order = unique([...theirsByKey.order, ...oursByKey.order, ...baseByKey.order]);
+    const outputKeys = order.filter((key) => associativeEntrySurvives(oursByKey.values.get(key), theirsByKey.values.get(key)));
+    remapListConflicts(s, path, oursByKey.order, outputKeys);
+    const out = [];
+    for (const key of outputKeys) {
+        const value = mergeAssociativeEntry(s, [...path, out.length], baseByKey.values.get(key), oursByKey.values.get(key), theirsByKey.values.get(key));
+        if (value !== undefined)
+            out.push(value);
+    }
+    return out;
+}
+function associativeEntrySurvives(ours, theirs) {
+    // When both sides agree an entry is absent, there is no value to put in the result. Every other
+    // combination is retained or represented as a conflict by mergeAssociativeEntry.
+    return ours !== undefined || theirs !== undefined;
+}
+function remapListConflicts(s, path, previousOrder, outputKeys) {
+    const outputIndex = new Map(outputKeys.map((key, index) => [key, index]));
+    const moved = [];
+    for (const [encoded, conflict] of s.conflicts) {
+        const segment = conflict.path[path.length];
+        if (!isPrefix(path, conflict.path) || typeof segment !== "number")
+            continue;
+        const key = previousOrder[segment];
+        const nextIndex = key === undefined ? undefined : outputIndex.get(key);
+        if (nextIndex === undefined || nextIndex === segment)
+            continue;
+        s.conflicts.delete(encoded);
+        moved.push({ ...conflict, path: [...path, nextIndex, ...conflict.path.slice(path.length + 1)] });
+    }
+    for (const conflict of moved)
+        s.conflicts.set(pathKey(conflict.path), conflict);
+}
+function mergeAssociativeEntry(s, path, base, ours, theirs) {
+    // An added or deleted entry is an atomic user intent. Recursing through an absent object would
+    // turn a deletion into `{}` and erase the fact that the entry was removed.
+    if (base === undefined || ours === undefined || theirs === undefined)
+        return mergeAtomic(s, path, base, ours, theirs);
+    return node(s, path, base, ours, theirs);
+}
+function mergeAtomic(s, path, base, ours, theirs) {
+    if (deepEqual(base, ours)) {
+        if (!deepEqual(base, theirs))
+            s.flashed.push(path);
+        clearConflict(s, path);
+        return clone(theirs);
+    }
+    if (deepEqual(base, theirs))
+        return clone(ours);
+    if (deepEqual(ours, theirs)) {
+        clearConflict(s, path);
+        return clone(ours);
+    }
+    setConflict(s, path, theirs);
+    return clone(ours);
+}
+function isAssociativeList(value, keys) {
+    return Array.isArray(value) && indexAssociativeList(value, keys) !== undefined;
+}
+function indexAssociativeList(values, keys) {
+    const indexed = { order: [], values: new Map() };
+    for (const value of values) {
+        if (!isPlainObject(value))
+            return undefined;
+        const identity = keys.map((key) => value[key]);
+        if (identity.some((part) => part === undefined || part === null || typeof part === "object"))
+            return undefined;
+        const encoded = JSON.stringify(identity);
+        if (indexed.values.has(encoded))
+            return undefined;
+        indexed.order.push(encoded);
+        indexed.values.set(encoded, value);
+    }
+    return indexed;
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function recurse(s, path, base, ours, theirs) {
+    const out = {};
+    for (const k of unionKeys(base, ours, theirs)) {
+        const v = node(s, [...path, k], at(base, k), at(ours, k), at(theirs, k));
+        if (v !== undefined)
+            out[k] = v; // prune: a key that reconciled to nothing is GONE
+    }
+    // The server removed this whole subtree and nothing of the user's survived in it. Returning `{}`
+    // here would leave an empty container the server does not have — which then reads as a dirty
+    // "the user added an empty map" forever. (`theirs === {}` is a real empty map and is kept.)
+    if (theirs === undefined && Object.keys(out).length === 0)
+        return undefined;
+    return out;
+}
+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))
+                continue;
+            seen.add(k);
+            keys.push(k);
+        }
+    }
+    return keys;
+}
+function setConflict(s, path, theirs) {
+    s.conflicts.set(pathKey(path), { path: [...path], theirs: clone(theirs) });
+}
+function clearConflict(s, path) {
+    s.conflicts.delete(pathKey(path));
+}

package/dist/path.d.ts

@@ -0,0 +1,27 @@
+import type { Path } from "./types.ts";
+/** A scalar key for a path, where a Map needs one. Encoded STRUCTURALLY — never by joining segments
+ * with a magic separator, which is how the original bug (a null byte vs a space) got in. */
+export declare function pathKey(path: Path): string;
+/** True when `prefix` addresses `path` or an ancestor of it. Segment-wise: `["data"]` is a prefix of
+ * `["data","token"]`, and `["dat"]` is a prefix of nothing. */
+export declare function isPrefix(prefix: Path, path: Path): boolean;
+/** The child of a JSON value at one segment, or undefined if there isn't one. Indexing a scalar (or
+ * a string, which would happily answer to `.length`) yields undefined, not nonsense. */
+export declare function at(value: unknown, seg: string | number): unknown;
+export declare function get(value: unknown, path: Path): unknown;
+/** True when the path is really THERE — as opposed to present with an undefined value. The
+ * difference is the whole of `absentPaths`: a ghost is a key that still exists. */
+export declare function has(value: unknown, path: Path): boolean;
+/** Set a value at a path, creating the containers it passes through. A numeric segment creates an
+ * array, a string segment an object — so `["spec","ports",0]` does the right thing on a fresh spec. */
+export declare function setAt(root: Record<string, unknown>, path: Path, value: unknown): void;
+/** Remove the key (or array element) a path addresses. Removing what is not there is a no-op, not
+ * an error: the server may have removed it first, and a UI must not blow up on that race. */
+export declare function removeAt(root: Record<string, unknown>, path: Path): void;
+/** An RFC 6901 JSON Pointer -> a segment array. This is the form `redacted[].path` arrives in on the
+ * wire (spec §3); inside the engine everything is a segment array.
+ *
+ * Segments stay STRINGS. `/data/0` on a map whose key is literally "0" must not become the number
+ * 0 — a pointer does not carry enough type information to tell those apart, and guessing corrupts
+ * exactly the Secret keys this is used to protect. */
+export declare function parsePointer(pointer: string): Path;

package/dist/path.js

@@ -0,0 +1,105 @@
+// Paths: arrays of segments, never dot-joined strings (R-ID).
+//
+// `["metadata","labels","app.kubernetes.io/name"]` is THREE segments, the last containing two dots
+// and a slash. Join it with dots and it splits back into six segments addressing nothing at all —
+// no crash, no error, the conflict lookup just silently never matches and the user's edit is lost
+// on save. That bug is the reason this module exists and the reason `Path` is not a string.
+import { isPlainObject } from "./deep.js";
+/** A scalar key for a path, where a Map needs one. Encoded STRUCTURALLY — never by joining segments
+ * with a magic separator, which is how the original bug (a null byte vs a space) got in. */
+export function pathKey(path) {
+    return JSON.stringify(path);
+}
+/** True when `prefix` addresses `path` or an ancestor of it. Segment-wise: `["data"]` is a prefix of
+ * `["data","token"]`, and `["dat"]` is a prefix of nothing. */
+export function isPrefix(prefix, path) {
+    if (prefix.length > path.length)
+        return false;
+    return prefix.every((seg, i) => String(seg) === String(path[i]));
+}
+/** The child of a JSON value at one segment, or undefined if there isn't one. Indexing a scalar (or
+ * a string, which would happily answer to `.length`) yields undefined, not nonsense. */
+export function at(value, seg) {
+    if (Array.isArray(value))
+        return value[Number(seg)];
+    if (isPlainObject(value))
+        return value[String(seg)];
+    return undefined;
+}
+export function get(value, path) {
+    let cur = value;
+    for (const seg of path)
+        cur = at(cur, seg);
+    return cur;
+}
+/** True when the path is really THERE — as opposed to present with an undefined value. The
+ * difference is the whole of `absentPaths`: a ghost is a key that still exists. */
+export function has(value, path) {
+    let cur = value;
+    for (const seg of path) {
+        if (Array.isArray(cur)) {
+            if (Number(seg) >= cur.length)
+                return false;
+        }
+        else if (isPlainObject(cur)) {
+            if (!Object.hasOwn(cur, String(seg)))
+                return false;
+        }
+        else {
+            return false;
+        }
+        cur = at(cur, seg);
+    }
+    return cur !== undefined;
+}
+/** Set a value at a path, creating the containers it passes through. A numeric segment creates an
+ * array, a string segment an object — so `["spec","ports",0]` does the right thing on a fresh spec. */
+export function setAt(root, path, value) {
+    if (path.length === 0)
+        throw new Error("krm-stream: cannot set the root of an object");
+    let cur = root;
+    for (let i = 0; i < path.length - 1; i++) {
+        const seg = path[i];
+        let next = at(cur, seg);
+        if (!isPlainObject(next) && !Array.isArray(next)) {
+            next = typeof path[i + 1] === "number" ? [] : {};
+            assign(cur, seg, next);
+        }
+        cur = next;
+    }
+    assign(cur, path[path.length - 1], value);
+}
+/** Remove the key (or array element) a path addresses. Removing what is not there is a no-op, not
+ * an error: the server may have removed it first, and a UI must not blow up on that race. */
+export function removeAt(root, path) {
+    if (path.length === 0)
+        throw new Error("krm-stream: cannot remove the root of an object");
+    const parent = get(root, path.slice(0, -1));
+    const last = path[path.length - 1];
+    if (Array.isArray(parent))
+        parent.splice(Number(last), 1);
+    else if (isPlainObject(parent))
+        delete parent[String(last)];
+}
+function assign(container, seg, value) {
+    if (Array.isArray(container))
+        container[Number(seg)] = value;
+    else
+        container[String(seg)] = value;
+}
+/** An RFC 6901 JSON Pointer -> a segment array. This is the form `redacted[].path` arrives in on the
+ * wire (spec §3); inside the engine everything is a segment array.
+ *
+ * Segments stay STRINGS. `/data/0` on a map whose key is literally "0" must not become the number
+ * 0 — a pointer does not carry enough type information to tell those apart, and guessing corrupts
+ * exactly the Secret keys this is used to protect. */
+export function parsePointer(pointer) {
+    if (pointer === "")
+        return [];
+    if (!pointer.startsWith("/"))
+        throw new Error(`krm-stream: not an RFC 6901 pointer: ${JSON.stringify(pointer)}`);
+    return pointer
+        .slice(1)
+        .split("/")
+        .map((seg) => seg.replaceAll("~1", "/").replaceAll("~0", "~"));
+}

package/dist/policy.d.ts

@@ -0,0 +1,16 @@
+import type { EditabilityPolicy, Path } from "./types.ts";
+/** The default editable regions. Note that two of them are at the object ROOT: `ConfigMap.data` and
+ * `Secret.data`/`stringData` carry editable payload outside `spec`, and an engine that assumes
+ * everything editable lives under `spec` cannot edit a ConfigMap at all — which is the one kind the
+ * first consumer edits most. `binaryData` is deliberately absent: it is base64 of arbitrary bytes,
+ * and a text input silently corrupts it. */
+export declare const DEFAULT_EDITABLE_REGIONS: Path[];
+/** A policy from a list of editable region roots. Everything under a root is editable; everything
+ * else follows the server. */
+export declare function regionPolicy(roots: Path[]): EditabilityPolicy;
+/** `spec`, `metadata.labels`/`annotations`, `data`, `stringData` editable; `status`, the rest of
+ * `metadata`, `apiVersion`, `kind`, `binaryData` read-only. */
+export declare const defaultPolicy: EditabilityPolicy;
+/** Everything read-only: the status-watch use case. Same engine, same stream, no draft — a viewer
+ * that cannot accidentally offer to save. */
+export declare const readOnlyPolicy: EditabilityPolicy;

package/dist/policy.js

@@ -0,0 +1,36 @@
+// Which regions of a KRM object a user may edit.
+//
+// Read-only is NOT ignored (docs §3). A read-only region still follows the server live and still
+// flashes what changed — that is the entire live-status-watch use case, and it is the product. It
+// simply never grows a draft, a dirty flag, or a conflict, and never appears in a patch.
+import { isPrefix } from "./path.js";
+/** The default editable regions. Note that two of them are at the object ROOT: `ConfigMap.data` and
+ * `Secret.data`/`stringData` carry editable payload outside `spec`, and an engine that assumes
+ * everything editable lives under `spec` cannot edit a ConfigMap at all — which is the one kind the
+ * first consumer edits most. `binaryData` is deliberately absent: it is base64 of arbitrary bytes,
+ * and a text input silently corrupts it. */
+export const DEFAULT_EDITABLE_REGIONS = [
+    ["spec"],
+    ["metadata", "labels"],
+    ["metadata", "annotations"],
+    ["data"],
+    ["stringData"],
+];
+/** A policy from a list of editable region roots. Everything under a root is editable; everything
+ * else follows the server. */
+export function regionPolicy(roots) {
+    return {
+        isEditable: (_obj, path) => roots.some((root) => isPrefix(root, path)),
+        // A path that is not editable itself but that an editable region lives UNDER — `[]` and
+        // `["metadata"]` for the defaults. The merge must recurse through these rather than replacing
+        // them wholesale, or an edit to `metadata.labels` would be clobbered by the read-only handling
+        // of `metadata.name` sitting beside it.
+        containsEditable: (_obj, path) => roots.some((root) => root.length > path.length && isPrefix(path, root)),
+    };
+}
+/** `spec`, `metadata.labels`/`annotations`, `data`, `stringData` editable; `status`, the rest of
+ * `metadata`, `apiVersion`, `kind`, `binaryData` read-only. */
+export const defaultPolicy = regionPolicy(DEFAULT_EDITABLE_REGIONS);
+/** Everything read-only: the status-watch use case. Same engine, same stream, no draft — a viewer
+ * that cannot accidentally offer to save. */
+export const readOnlyPolicy = regionPolicy([]);

package/dist/schema.d.ts

@@ -0,0 +1,14 @@
+import type { EditabilityPolicy } from "./types.ts";
+/** The structural OpenAPI subset Kubernetes uses to describe object fields and associative lists. */
+export interface KubernetesStructuralSchema {
+    properties?: Record<string, KubernetesStructuralSchema>;
+    items?: KubernetesStructuralSchema;
+    "x-kubernetes-list-type"?: string;
+    "x-kubernetes-list-map-keys"?: string[];
+}
+/** Adds keyed-list merging to an existing editability policy.
+ *
+ * Pass the structural schema for the exact GroupVersionKind the store receives. Lists without both
+ * Kubernetes extensions, malformed lists, and lists whose elements have duplicate/missing keys all
+ * continue to use atomic-array behavior. */
+export declare function withOpenAPIKeyedLists(policy: EditabilityPolicy, schema: KubernetesStructuralSchema): EditabilityPolicy;

package/dist/schema.js

@@ -0,0 +1,26 @@
+// OpenAPI-backed associative-list support. Kubernetes uses these two extensions for lists whose
+// elements have a stable identity, such as containers by `name`. The store only needs this small
+// structural subset; fetching schemas and choosing the right resource schema remain host concerns.
+/** Adds keyed-list merging to an existing editability policy.
+ *
+ * Pass the structural schema for the exact GroupVersionKind the store receives. Lists without both
+ * Kubernetes extensions, malformed lists, and lists whose elements have duplicate/missing keys all
+ * continue to use atomic-array behavior. */
+export function withOpenAPIKeyedLists(policy, schema) {
+    return {
+        ...policy,
+        listMapKeys: (object, path) => policy.listMapKeys?.(object, path) ?? mapKeysAt(schema, path),
+    };
+}
+function mapKeysAt(root, path) {
+    let schema = root;
+    for (const segment of path) {
+        schema = typeof segment === "number" ? schema?.items : schema?.properties?.[segment];
+        if (!schema)
+            return undefined;
+    }
+    const keys = schema["x-kubernetes-list-map-keys"];
+    if (schema["x-kubernetes-list-type"] !== "map" || !keys || keys.length === 0)
+        return undefined;
+    return keys;
+}

package/dist/sse.d.ts

@@ -0,0 +1,53 @@
+import type { LiveResourceStore } from "./store.ts";
+import type { ErrorCode, Path, StreamEvent } from "./types.ts";
+/** 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 declare class SSEDecoder {
+    #private;
+    /** Feed a chunk of the stream; get back the events that completed with it. */
+    push(chunk: string): StreamEvent[];
+}
+/** 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 declare class StreamSequence {
+    #private;
+    observe(event: StreamEvent): {
+        expected: number;
+        received: number;
+    } | 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 declare function applyStreamEvent(store: LiveResourceStore, ev: StreamEvent): Path[];
+export interface StreamOptions {
+    /** Called for every `error` event. A terminal one has already closed the connection by the time
+     * this returns — there is nothing to retry, and retrying is the bug. */
+    onError?: (code: ErrorCode, message: string, terminal: boolean) => void;
+    /** Called at the end of every snapshot cycle. The store is now consistent: a good moment to paint. */
+    onSynced?: () => void;
+    /** Called after any change, with the paths that flashed. */
+    onChange?: (flashed: Path[]) => void;
+    /** A missing or duplicated event was observed. The connection is closed; reconnect for a snapshot. */
+    onGap?: (expected: number, received: number) => void;
+    /** Abort the stream from outside. */
+    signal?: AbortSignal;
+    /** Injectable for tests. Defaults to the global fetch. */
+    fetch?: typeof globalThis.fetch;
+    headers?: Record<string, string>;
+}
+export interface StreamHandle {
+    close(): void;
+    /** Resolves when the stream ends: closed, aborted, or terminated by a terminal error. */
+    closed: Promise<void>;
+}
+/** 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 declare function connectResourceStream(url: string, store: LiveResourceStore, opts?: StreamOptions): StreamHandle;
+/** 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 declare function connectWithEventSource(url: string, store: LiveResourceStore, opts?: Omit<StreamOptions, "fetch" | "headers">): StreamHandle;