@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/framework/session.d.ts

@@ -0,0 +1,196 @@
+import { RebaseConflict, StampedPatch } from "./overlay.js";
+import { Snapshot } from "./snapshot.js";
+import { Config, LiveConfig, Patch } from "./Config.js";
+import { ChangeHookMap, ChangeHookRun } from "./change-hooks.js";
+import { WalkOptions } from "./schema-version.js";
+
+//#region src/framework/session.d.ts
+/** Confirmed state arriving from storage. */
+interface SourceChange {
+  readonly snapshot: Snapshot;
+  /** Ids of local patches the new base has absorbed — a merge landing. They are dropped rather than
+   *  replayed, because the base already contains them. Empty for an ordinary change. */
+  readonly merged?: readonly string[];
+}
+/** Where confirmed state comes from — the base half of a branch: the artifact a push built. */
+interface ConfigSource {
+  snapshot(): Snapshot;
+  subscribe(onChange: (change: SourceChange) => void): () => void;
+}
+/**
+ * Where the shared draft lives — the branch's unmerged patches, as one ordered list.
+ *
+ * Separate from {@link ConfigSource} because a branch's two sources carry different things: the
+ * base is entity state, the draft is patches. Only the draft is collaborative, so only the draft
+ * has a live shared home (the `system:{branchId}` Y.Doc); the base is the same artifact for every
+ * client and moves only when a push publishes a new one.
+ *
+ * The unit is the whole list, not a delta. A client adopts it rather than reconciling entry by
+ * entry, which is what makes its own echo a no-op — see `Config.withDraft`.
+ */
+interface DraftSource {
+  draft(): readonly StampedPatch[];
+  subscribe(onChange: (draft: readonly StampedPatch[]) => void): () => void;
+}
+/** Where local patches go. Called once per batch, never once per patch. */
+interface ConfigSink {
+  commit(patches: readonly StampedPatch[], next: Config): void | Promise<void>;
+  /**
+   * Take named entries back out of the shared draft — the other half of the pair, and the reason it
+   * has to exist: `drop(ids)` filters a list only this client can see. A patch that had already
+   * reached the sink therefore came back on the next change notification, because a client adopts the
+   * shared list wholesale (see {@link DraftSource}). Wholesale adoption is what makes an echo a no-op
+   * and what resurrects a removal that was never written through.
+   *
+   * ID-addressed on purpose. It names its victims, so an incomplete local view can't delete anything
+   * it didn't mean to. It must never grow into a `replaceAll(desiredList)` convenience: a full set
+   * deletes by omission, and omission is indistinguishable from ignorance.
+   *
+   * Optional, so a sink that only appends — a test double, a local-only session — still satisfies
+   * this. `drop` then stays local, exactly as it behaved before this existed.
+   *
+   * Must be idempotent, like `commit`: retracting an absent id is a no-op, so a retry and two clients
+   * retracting the same id both converge.
+   */
+  retract?(patchIds: readonly string[]): void | Promise<void>;
+}
+/** Which replay dropped an edit — see {@link ConfigSessionOptions.onConflict}. */
+type RebaseOrigin = 'base' | 'draft' | 'drop';
+interface ConfigSessionOptions {
+  source?: ConfigSource;
+  /** The shared draft. Without one, the pending patches are this client's alone. */
+  draft?: DraftSource;
+  sink?: ConfigSink;
+  /**
+   * When to hand the pending patches to the sink — transport, not meaning: how many Yjs updates a
+   * burst of edits produces, never which edits belong together (that is the changeset on the stamp).
+   * `'microtask'` (the default) flushes at the end of the current synchronous run, which is exactly
+   * the boundary a loop of `apply` calls sits inside. A number debounces by that many ms; `'manual'`
+   * flushes only on `flush()`.
+   */
+  flush?: 'microtask' | 'manual' | number;
+  /**
+   * Called when a rebase drops local edits the new base invalidated — never silent, because the
+   * user made those edits and they are now gone.
+   *
+   * `origin` says which replay dropped them, because the honest wording differs: `'base'` is a real
+   * base move (the classic rebase), `'draft'` is the shared draft being re-adopted onto the same
+   * base (a stale or conflicting entry another writer left there), `'drop'` is a dependent casualty
+   * of an explicit drop. Each casualty is announced once per life in the draft — the draft replays
+   * wholesale on every change, and re-announcing the same doomed entry on every keystroke taught
+   * users to ignore the report. A base move resets that memory: the same edit dying on a new base
+   * is news.
+   */
+  onConflict?: (dropped: RebaseConflict[], origin: RebaseOrigin) => void;
+  /**
+   * Called ONCE when the shared draft carries a patch stamped at a NEWER schema version than this
+   * build understands — a collaborator on a newer deploy is writing to the same draft. The entry is
+   * held out of replay (applying it would fail as a bogus conflict) and never retracted (it is valid
+   * for newer readers); the only real remedy is reloading onto the newer deploy, so the surface
+   * should say exactly that.
+   */
+  onSchemaAhead?: () => void;
+  /** Test seam — the adopt-side patch upgrade walks this chain/target instead of the registered
+   *  ones. Real sessions omit it: registration refuses synthetic versions, so only a seam can
+   *  exercise the walk. */
+  schemaWalk?: WalkOptions;
+  /** Called when a hooked derivation throws. The surface waiting on that value is now showing
+   *  something stale, and only the caller can say so. */
+  onDeriveError?: (name: string, error: unknown) => void;
+  /**
+   * Run over every value this session advances to, before anyone reads it — for content that is a
+   * FUNCTION of the config rather than an edit to it.
+   *
+   * The rows a linked system brings are the case: a link declares a pin and the rows are derived from
+   * it, so a surface reading the session has to see them, and a replay has to make them again. Purely
+   * derived content only. It must add no patches and must not depend on the value it produced, since
+   * it runs on the result of every apply, rebase, adopt and drop.
+   *
+   * The BASE is untouched, which is what makes it safe to run here: a rebase and a drop both replay
+   * from the base, so derived content is rebuilt rather than replayed as though someone had written
+   * it.
+   */
+  derive?: <C extends Config>(config: C) => C;
+}
+declare class ConfigSession<C extends Config = Config> implements LiveConfig {
+  #private;
+  constructor(config: C, options?: ConfigSessionOptions);
+  get config(): C;
+  /** Apply a patch and advance to the result. Returns the new config for a caller that wants it
+   *  immediately; `session.config` is the same value. */
+  apply(patch: Patch, id?: string): C;
+  /**
+   * Move the session forward to a config someone else derived from this one.
+   *
+   * The seam for code that is handed the next config rather than producing it — an operation
+   * handler is `config.apply(...)`, so what it returns is the next value and the session takes it
+   * rather than re-deriving it. Patches the value gained on the way join the outgoing batch, so a
+   * mutation made this way persists like any other.
+   */
+  advance(next: C): C;
+  /**
+   * Attach one resolved source and advance to the result.
+   *
+   * A read arriving late, not an edit: the answer is applied to the value the session holds now, so a
+   * caller never hands over a config it read a round trip ago, and nothing joins the outgoing batch.
+   * The edition is unchanged, which is what lets a write in flight tell this apart from a peer's edit.
+   */
+  attach(resolution: Parameters<C['attachResolved']>[0]): C;
+  subscribe(listener: () => void): () => void;
+  /**
+   * Derive something from this config for as long as the caller is interested.
+   *
+   * A surface hooks what it is showing, which is the point: today a provider subscribes once and
+   * every tab pays for the derive whether a canvas is mounted or not. The returned disposer is the
+   * whole teardown, so the effect that registers it is one line — and the same point can be hooked
+   * twice under different names, so an inspector can watch timings without displacing the paint.
+   *
+   * ```ts
+   * useEffect(() => session.hook('onChange', { styles: stylesOnChange }).dispose, [session]);
+   * ```
+   *
+   * The lifecycle is named rather than implied so the other points (`onLoad`, `onBuild`, `onPush`)
+   * land beside it instead of each inventing a method.
+   */
+  hook<H extends ChangeHookMap<C>>(_lifecycle: 'onChange', hooks: H): ChangeHookRun<H>;
+  /**
+   * The current value of a hooked derivation, by name — the pull half of `hook`.
+   *
+   * Typed by the caller, because a session accumulates hook sets from surfaces it knows nothing
+   * about; the statically-typed read is the `derived` on what `hook` returned. Two hook sets may
+   * claim one name — an inspector watching the same point — and this answers with the first that has
+   * answered, so a reader that cares which is reading the wrong way round.
+   */
+  derived<T>(name: string): T | undefined;
+  /** Replay the local edits onto a new base. Dropped edits go to `onConflict`. */
+  rebase(base: Snapshot): void;
+  /** Drop local edits a merge folded into the base. */
+  merge(patchIds: readonly string[]): void;
+  /**
+   * Drop local edits the server refused — the opposite of `merge`, and the difference matters.
+   *
+   * A merged patch leaves its value readable, because the new base contains it. A refused one must
+   * take its effect with it: the edit was not saved, so a surface that kept showing it would be
+   * lying about what the branch holds. That is why this replays the remaining draft instead of
+   * filtering the pending list — a later patch built on the refused one has nothing to build on, and
+   * the replay is what surfaces that rather than leaving a half-applied overlay.
+   *
+   * Those dependent casualties go to `onConflict` like any other dropped edit. Unknown ids change
+   * nothing, so a retry that already settled is harmless.
+   *
+   * The removal is also written through to the sink, for every dropped patch that had reached it. It
+   * has to be: the pending list this filters is local, and a client adopts the shared draft wholesale,
+   * so a patch removed only here reappears on the next change notification — any peer edit, any
+   * reconnect. See {@link ConfigSink.retract}.
+   */
+  drop(patchIds: readonly string[]): void;
+  /** Hand the pending batch to the sink now. Resolves once the sink has taken it. */
+  flush(): Promise<void>;
+  /** Detach from the source. The config value remains readable — it just stops advancing. */
+  dispose(): void;
+}
+/** A source over a fixed snapshot that never changes — the in-memory case, and what
+ *  `MapItemStore` used to be. Useful as a seed and in tests. */
+declare function memoryConfigSource(snapshot: Snapshot): ConfigSource;
+//#endregion
+export { ConfigSession, ConfigSessionOptions, ConfigSink, ConfigSource, DraftSource, RebaseOrigin, SourceChange, memoryConfigSource };

package/dist/framework/session.js

@@ -0,0 +1,367 @@
+import { upgradeDraftEntries } from "./schema-version.js";
+import { runChangeHooks } from "./change-hooks.js";
+//#region src/framework/session.ts
+/**
+* Whether two patch lists are the same draft — same entries, same order.
+*
+* By ID, because an entry is immutable once stamped: the id is minted with the patch and travels with
+* it through the sink, the shared list and the storage row, so two entries sharing one are the same
+* edit however many times it was serialized on the way round.
+*/
+function sameDraft(a, b) {
+	return a.length === b.length && a.every((entry, i) => entry.id === b[i]?.id);
+}
+/**
+* One entry per id, first occurrence kept, order otherwise preserved.
+*
+* A shared draft can carry the same stamped patch twice: two realtime instances that each seeded a
+* cold room from the same rows mint their own Yjs items for one id, and the merge keeps both. The
+* second copy is the same edit, so it can't be replayed — a `create` fails as `ALREADY_EXISTS` — and
+* reporting it would tell the user an edit was lost when nothing was.
+*/
+function uniqueById(entries) {
+	const seen = /* @__PURE__ */ new Set();
+	const unique = [];
+	for (const entry of entries) {
+		if (seen.has(entry.id)) continue;
+		seen.add(entry.id);
+		unique.push(entry);
+	}
+	return unique;
+}
+var ConfigSession = class {
+	#config;
+	#listeners = /* @__PURE__ */ new Set();
+	#options;
+	/** Applied locally but not yet handed to the sink. Distinct from `config.pending`, which stays
+	*  populated until the source confirms — sent and confirmed are different questions. */
+	#uncommitted = [];
+	/** Casualties already reported to `onConflict`, by id — the once-per-life memory. Pruned to the
+	*  shared draft on every adopt, cleared whenever the base actually moves. */
+	#announcedDrops = /* @__PURE__ */ new Set();
+	/** Whether {@link ConfigSessionOptions.onSchemaAhead} already fired — the draft re-adopts
+	*  wholesale on every change, and one reload prompt is the message. */
+	#schemaAheadAnnounced = false;
+	/**
+	* Patches handed to the sink whose `commit` hasn't resolved yet, in apply order.
+	*
+	* They are in neither `#uncommitted` (flush empties it before awaiting) nor durably shared, and that
+	* gap matters twice:
+	*
+	*  - for `drop`, retracting one now would find nothing to remove, and the append would land
+	*    afterwards — resurrecting the patch permanently. So a drop naming one of these defers.
+	*  - for {@link #adoptDraft}, which rebuilds the pending list from the shared draft plus whatever
+	*    is only local. A patch in neither list is not dropped, it simply stops existing — no replay,
+	*    no conflict, no report. That erased "add a token, then delete it while the add is still
+	*    committing", leaving the delete to replay alone and fail as `NOT_FOUND`.
+	*
+	* So this holds the entries rather than their ids: the adopt needs the patch to replay and the
+	* position to replay it at, and a `Set<string>` had neither.
+	*/
+	#inFlight = [];
+	/** Ids dropped while their own commit was in flight — retracted once it settles. */
+	#retractOnSettle = /* @__PURE__ */ new Set();
+	/** Derivations hooked onto this session — held so `dispose` takes them down with it. */
+	#runs = /* @__PURE__ */ new Set();
+	#scheduled = false;
+	#timer;
+	#unsubscribe;
+	#unsubscribeDraft;
+	constructor(config, options = {}) {
+		this.#options = options;
+		this.#config = this.#derived(config.withOwner(this));
+		if (options.source) {
+			this.#config = this.#afterRebase(this.#config.rebase(options.source.snapshot()), "base");
+			this.#unsubscribe = options.source.subscribe((change) => this.#onSourceChange(change));
+		}
+		if (options.draft) {
+			this.#adoptDraft(options.draft.draft());
+			this.#unsubscribeDraft = options.draft.subscribe((draft) => {
+				if (this.#adoptDraft(draft)) this.#notify();
+			});
+		}
+	}
+	get config() {
+		return this.#config;
+	}
+	/** Apply a patch and advance to the result. Returns the new config for a caller that wants it
+	*  immediately; `session.config` is the same value. */
+	apply(patch, id) {
+		return this.advance(this.#config.apply(patch, id));
+	}
+	/**
+	* Move the session forward to a config someone else derived from this one.
+	*
+	* The seam for code that is handed the next config rather than producing it — an operation
+	* handler is `config.apply(...)`, so what it returns is the next value and the session takes it
+	* rather than re-deriving it. Patches the value gained on the way join the outgoing batch, so a
+	* mutation made this way persists like any other.
+	*/
+	advance(next) {
+		if (next === this.#config) return next;
+		const before = this.#config;
+		this.#config = this.#derived(next);
+		if (next.pending.length > before.pending.length) {
+			this.#uncommitted.push(...next.pending.slice(before.pending.length));
+			this.#schedule();
+		}
+		this.#notify();
+		return this.#config;
+	}
+	/**
+	* Attach one resolved source and advance to the result.
+	*
+	* A read arriving late, not an edit: the answer is applied to the value the session holds now, so a
+	* caller never hands over a config it read a round trip ago, and nothing joins the outgoing batch.
+	* The edition is unchanged, which is what lets a write in flight tell this apart from a peer's edit.
+	*/
+	attach(resolution) {
+		this.#config = this.#derived(this.#config.attachResolved(resolution));
+		this.#notify();
+		return this.#config;
+	}
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+	/**
+	* Derive something from this config for as long as the caller is interested.
+	*
+	* A surface hooks what it is showing, which is the point: today a provider subscribes once and
+	* every tab pays for the derive whether a canvas is mounted or not. The returned disposer is the
+	* whole teardown, so the effect that registers it is one line — and the same point can be hooked
+	* twice under different names, so an inspector can watch timings without displacing the paint.
+	*
+	* ```ts
+	* useEffect(() => session.hook('onChange', { styles: stylesOnChange }).dispose, [session]);
+	* ```
+	*
+	* The lifecycle is named rather than implied so the other points (`onLoad`, `onBuild`, `onPush`)
+	* land beside it instead of each inventing a method.
+	*/
+	hook(_lifecycle, hooks) {
+		const run = runChangeHooks({
+			feed: {
+				current: () => this.#config,
+				subscribe: (listener) => this.subscribe(listener)
+			},
+			hooks,
+			onError: this.#options.onDeriveError
+		});
+		const registered = {
+			...run,
+			dispose: () => {
+				this.#runs.delete(registered);
+				run.dispose();
+			}
+		};
+		this.#runs.add(registered);
+		return registered;
+	}
+	/**
+	* The current value of a hooked derivation, by name — the pull half of `hook`.
+	*
+	* Typed by the caller, because a session accumulates hook sets from surfaces it knows nothing
+	* about; the statically-typed read is the `derived` on what `hook` returned. Two hook sets may
+	* claim one name — an inspector watching the same point — and this answers with the first that has
+	* answered, so a reader that cares which is reading the wrong way round.
+	*/
+	derived(name) {
+		for (const run of this.#runs) {
+			const value = run.derived(name);
+			if (value !== void 0) return value;
+		}
+	}
+	/** Replay the local edits onto a new base. Dropped edits go to `onConflict`. */
+	rebase(base) {
+		this.#config = this.#afterRebase(this.#config.rebase(base), "base");
+		this.#notify();
+	}
+	/** Drop local edits a merge folded into the base. */
+	merge(patchIds) {
+		const next = this.#config.merge(patchIds);
+		if (next === this.#config) return;
+		this.#config = this.#derived(next);
+		this.#notify();
+	}
+	/**
+	* Drop local edits the server refused — the opposite of `merge`, and the difference matters.
+	*
+	* A merged patch leaves its value readable, because the new base contains it. A refused one must
+	* take its effect with it: the edit was not saved, so a surface that kept showing it would be
+	* lying about what the branch holds. That is why this replays the remaining draft instead of
+	* filtering the pending list — a later patch built on the refused one has nothing to build on, and
+	* the replay is what surfaces that rather than leaving a half-applied overlay.
+	*
+	* Those dependent casualties go to `onConflict` like any other dropped edit. Unknown ids change
+	* nothing, so a retry that already settled is harmless.
+	*
+	* The removal is also written through to the sink, for every dropped patch that had reached it. It
+	* has to be: the pending list this filters is local, and a client adopts the shared draft wholesale,
+	* so a patch removed only here reappears on the next change notification — any peer edit, any
+	* reconnect. See {@link ConfigSink.retract}.
+	*/
+	drop(patchIds) {
+		if (patchIds.length === 0) return;
+		const refused = new Set(patchIds);
+		const before = this.#config.pending;
+		const kept = before.filter((entry) => !refused.has(entry.id) && !(entry.changeset !== void 0 && refused.has(entry.changeset)));
+		if (kept.length === before.length) return;
+		const neverSent = new Set(this.#uncommitted.map((entry) => entry.id));
+		this.#uncommitted = this.#uncommitted.filter((entry) => !refused.has(entry.id));
+		this.#config = this.#afterRebase(this.#config.withDraft(kept), "drop");
+		this.#notify();
+		const survived = new Set(this.#config.pending.map((entry) => entry.id));
+		this.#retract(before.map((entry) => entry.id).filter((id) => !survived.has(id) && !neverSent.has(id)));
+	}
+	/** Write a removal through to the sink, deferring any id whose own commit is still in flight. */
+	#retract(ids) {
+		if (ids.length === 0) return;
+		const inFlight = new Set(this.#inFlight.map((entry) => entry.id));
+		const now = [];
+		for (const id of ids) if (inFlight.has(id)) this.#retractOnSettle.add(id);
+		else now.push(id);
+		this.#sendRetraction(now);
+	}
+	/**
+	* Hand ids to the sink's `retract`, if it has one.
+	*
+	* A sink without it keeps `drop` local-only — the behaviour before the pair existed — rather than
+	* throwing. A rejected retraction goes back on the deferred set so the next settle retries it:
+	* losing one strands the row in the shared draft, which is the resurrection this exists to stop.
+	* Deliberately not a background retry loop — that is a client-side sweeper, and a sweeper is where
+	* full-set pushes come from.
+	*/
+	#sendRetraction(ids) {
+		if (ids.length === 0) return;
+		const retract = this.#options.sink?.retract;
+		if (!retract) return;
+		try {
+			const settled = retract.call(this.#options.sink, ids);
+			if (settled) settled.catch(() => {
+				for (const id of ids) this.#retractOnSettle.add(id);
+			});
+		} catch {
+			for (const id of ids) this.#retractOnSettle.add(id);
+		}
+	}
+	/** Hand the pending batch to the sink now. Resolves once the sink has taken it. */
+	async flush() {
+		this.#scheduled = false;
+		if (this.#timer !== void 0) {
+			clearTimeout(this.#timer);
+			this.#timer = void 0;
+		}
+		const batch = this.#uncommitted;
+		if (batch.length === 0 || !this.#options.sink) return;
+		this.#uncommitted = [];
+		this.#inFlight = [...this.#inFlight, ...batch];
+		try {
+			await this.#options.sink.commit(batch, this.#config);
+		} catch (error) {
+			this.#uncommitted = [...batch.filter((entry) => !this.#retractOnSettle.has(entry.id)), ...this.#uncommitted];
+			throw error;
+		} finally {
+			const settled = new Set(batch.map((entry) => entry.id));
+			this.#inFlight = this.#inFlight.filter((entry) => !settled.has(entry.id));
+			const deferred = [...this.#retractOnSettle];
+			this.#retractOnSettle.clear();
+			this.#sendRetraction(deferred);
+		}
+	}
+	/** Detach from the source. The config value remains readable — it just stops advancing. */
+	dispose() {
+		this.#unsubscribe?.();
+		this.#unsubscribe = void 0;
+		this.#unsubscribeDraft?.();
+		this.#unsubscribeDraft = void 0;
+		for (const run of [...this.#runs]) run.dispose();
+		this.#listeners.clear();
+		if (this.#timer !== void 0) clearTimeout(this.#timer);
+	}
+	/**
+	* Take the shared draft as the pending list. Answers whether the config moved, so a change that
+	* says nothing new doesn't advance.
+	*
+	* Local patches that haven't reached the shared list yet are kept on the end. A batch applied a
+	* microtask ago is ours and still uncommitted, and adopting a list that predates it would undo
+	* the user's last edit the moment a collaborator typed.
+	*
+	* "Local" is in flight plus uncommitted, in that order, because those are the two ways a patch can
+	* be ours and not yet shared — and a patch in neither list doesn't get reported as dropped, it just
+	* stops existing. Reading only `#uncommitted` erased the whole in-flight batch: add a token, delete
+	* it before the add's commit settles, and the add vanished while the delete replayed alone onto a
+	* base that never had the token, dying as `NOT_FOUND`. In flight comes first because it was applied
+	* first — `flush` takes the head of the queue.
+	*
+	* An in-flight entry a `drop` already claimed is left out: `drop` filters `#uncommitted` itself but
+	* cannot touch a sent batch (it defers the retraction to `#retractOnSettle`), so without this the
+	* adopt would read the dropped patch straight back.
+	*/
+	#adoptDraft(draft) {
+		const { entries: readable, held } = upgradeDraftEntries(draft, this.#options.schemaWalk);
+		if (held.length > 0 && !this.#schemaAheadAnnounced) {
+			this.#schemaAheadAnnounced = true;
+			this.#options.onSchemaAhead?.();
+		}
+		const shared = new Set(readable.map((entry) => entry.id));
+		const localOnly = [...this.#inFlight, ...this.#uncommitted].filter((entry) => !shared.has(entry.id) && !this.#retractOnSettle.has(entry.id));
+		for (const id of this.#announcedDrops) if (!shared.has(id)) this.#announcedDrops.delete(id);
+		const adopted = uniqueById([...readable, ...localOnly]);
+		if (sameDraft(adopted, this.#config.pending)) return false;
+		this.#config = this.#afterRebase(this.#config.withDraft(adopted), "draft");
+		return true;
+	}
+	#onSourceChange(change) {
+		let next = this.#config;
+		if (change.merged?.length) next = next.merge(change.merged);
+		this.#config = this.#afterRebase(next.rebase(change.snapshot), "base");
+		this.#notify();
+	}
+	/**
+	* Unwrap a rebase result, reporting whatever it had to drop — a local edit the new base
+	* invalidated is the user's work disappearing, so it is never silent.
+	*
+	* Announced once per casualty: the shared draft replays wholesale on every change, so without a
+	* memory the same doomed entry re-reported on every subsequent edit, its own echo included — an
+	* alarm that fires forever is an alarm nobody reads. A base move clears the memory (the same edit
+	* dying on a new base is news); an id that leaves the draft is forgotten in {@link #adoptDraft}.
+	*/
+	#afterRebase({ config, dropped }, origin) {
+		if (origin === "base") this.#announcedDrops.clear();
+		const news = dropped.filter((entry) => !this.#announcedDrops.has(entry.id));
+		for (const entry of news) this.#announcedDrops.add(entry.id);
+		if (news.length) this.#options.onConflict?.(news, origin);
+		return this.#derived(config);
+	}
+	/** One value, ready to be read — {@link ConfigSessionOptions.derive} applied, or the value itself
+	*  when the session was given none. Every assignment to `#config` goes through here. */
+	#derived(config) {
+		return this.#options.derive ? this.#options.derive(config) : config;
+	}
+	#schedule() {
+		const { flush = "microtask", sink } = this.#options;
+		if (!sink || flush === "manual" || this.#scheduled) return;
+		this.#scheduled = true;
+		if (flush === "microtask") {
+			queueMicrotask(() => {
+				if (this.#scheduled) this.flush();
+			});
+			return;
+		}
+		this.#timer = setTimeout(() => void this.flush(), flush);
+	}
+	#notify() {
+		for (const listener of this.#listeners) listener();
+	}
+};
+/** A source over a fixed snapshot that never changes — the in-memory case, and what
+*  `MapItemStore` used to be. Useful as a seed and in tests. */
+function memoryConfigSource(snapshot) {
+	return {
+		snapshot: () => snapshot,
+		subscribe: () => () => {}
+	};
+}
+//#endregion
+export { ConfigSession, memoryConfigSource };

package/dist/framework/signature.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+//#region src/framework/signature.d.ts
+interface SignatureOptions {
+  /** Object nesting rendered in full before an object collapses to `{…}`. */
+  readonly depth?: number;
+  /** Enum members listed before the rest collapse to `…`. */
+  readonly enumLimit?: number;
+}
+/** Render one JSON Schema node as a type signature. `root` holds `$defs` for `$ref` lookups. */
+declare function renderSignature(schema: unknown, options?: SignatureOptions): string;
+/** The signature of a zod schema, read from its input side since it documents what an author writes. */
+declare function signatureOf(schema: z.ZodTypeAny | undefined, options?: SignatureOptions): string | undefined;
+//#endregion
+export { SignatureOptions, renderSignature, signatureOf };

package/dist/framework/signature.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+//#region src/framework/signature.ts
+/**
+* A JSON Schema rendered as a one-line type signature — `{ value: string | ref<token>, type?: string }`.
+*
+* The full JSON Schema for one create runs to tens of kilobytes; the signature says the same shape in
+* a line a prompt can afford to carry for every kind, so a model learns what an entity takes before
+* it writes one. Depth is capped: an object nested past it prints as `{…}`, and the full schema is one
+* `address` describe away. Two levels is enough to show a kind's fields and the shape of each field's
+* members; a token's color operation is recursive and would otherwise unfold without end.
+*/
+const DEFAULT_DEPTH = 2;
+const DEFAULT_ENUM_LIMIT = 8;
+function isNode(value) {
+	return typeof value === "object" && value !== null;
+}
+function literal(value) {
+	return typeof value === "string" ? `'${value}'` : String(value);
+}
+function unique(parts) {
+	return [...new Set(parts)];
+}
+/** Render one JSON Schema node as a type signature. `root` holds `$defs` for `$ref` lookups. */
+function renderSignature(schema, options = {}) {
+	if (!isNode(schema)) return "unknown";
+	const depth = options.depth ?? DEFAULT_DEPTH;
+	const enumLimit = options.enumLimit ?? DEFAULT_ENUM_LIMIT;
+	const render = (node, remaining) => {
+		if (node.$ref) {
+			const name = node.$ref.replace("#/$defs/", "");
+			const target = schema.$defs?.[name];
+			return target ? render(target, remaining) : "…";
+		}
+		if (node.ref && node.refKind) return `ref<${node.refKind}>`;
+		if (node.const !== void 0) return literal(node.const);
+		if (node.enum) {
+			const shown = node.enum.slice(0, enumLimit).map(literal);
+			if (node.enum.length > enumLimit) shown.push("…");
+			return shown.join(" | ");
+		}
+		const variants = node.anyOf ?? node.oneOf;
+		if (variants) return unique(variants.map((member) => render(member, remaining))).join(" | ");
+		if (node.allOf) return unique(node.allOf.map((member) => render(member, remaining))).join(" & ");
+		if (Array.isArray(node.type)) return unique(node.type.map((type) => render({
+			...node,
+			type
+		}, remaining))).join(" | ");
+		if (node.type === "array") {
+			const item = node.items ? render(node.items, remaining) : "unknown";
+			return item.includes(" | ") ? `(${item})[]` : `${item}[]`;
+		}
+		if (node.type === "object" || node.properties || node.additionalProperties) return renderObject(node, remaining);
+		return typeof node.type === "string" ? node.type : "unknown";
+	};
+	const renderObject = (node, remaining) => {
+		const entries = Object.entries(node.properties ?? {});
+		if (entries.length === 1 && entries[0]?.[0] === "__ref") return "ref";
+		if (entries.length === 0) {
+			if (isNode(node.additionalProperties)) {
+				if (remaining <= 0) return "Record<string, {…}>";
+				return `Record<string, ${render(node.additionalProperties, remaining - 1)}>`;
+			}
+			return node.additionalProperties === false ? "{}" : "Record<string, unknown>";
+		}
+		if (remaining <= 0) return "{…}";
+		const required = new Set(node.required ?? []);
+		return `{ ${entries.map(([key, value]) => {
+			return `${key}${required.has(key) ? "" : "?"}: ${render(value, remaining - 1)}`;
+		}).join(", ")} }`;
+	};
+	return render(schema, depth);
+}
+/** The signature of a zod schema, read from its input side since it documents what an author writes. */
+function signatureOf(schema, options) {
+	if (!schema) return void 0;
+	try {
+		return renderSignature(z.toJSONSchema(schema, { io: "input" }), options);
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { renderSignature, signatureOf };