@kyneta/changefeed 1.5.2 → 1.6.1

package/README.md

@@ -8,7 +8,7 @@ A **changefeed** is a reactive value with a current state and a stream of future
 
 The protocol is expressed through a single well-known symbol: `CHANGEFEED` (`Symbol.for("kyneta:changefeed")`). Any object carrying this symbol participates in the reactive protocol — schema-interpreted refs, local state, peer lifecycle feeds, or anything else.
 
-This package contains the **contract only** — zero dependencies, no schema, no interpreters, no paths. Schema-specific extensions (`Op`, `ComposedChangefeedProtocol`, tree observation) live in `@kyneta/schema`, which depends on this package.
+This package contains the **contract only** — zero dependencies, no schema, no interpreters, no paths. Schema-specific extensions (`Op`, `TreeChangefeedProtocol`, tree observation) live in `@kyneta/schema`, which depends on this package.
 
 ## Install
 
@@ -119,9 +119,9 @@ Creates a protocol object that never emits changes — useful for static data so
 |---|---|
 | `ChangeBase` | `TextChange`, `MapChange`, `SequenceChange`, ... |
 | `Changeset<C>` | `Op<C>` (addressed delta with `Path`) |
-| `ChangefeedProtocol<S, C>` | `ComposedChangefeedProtocol<S, C>` (adds `subscribeTree`) |
-| `Changefeed<S, C>` | `HasComposedChangefeed<S, C>` |
-| `hasChangefeed()` | `hasComposedChangefeed()`, `getOrCreateChangefeed()` |
+| `ChangefeedProtocol<S, C>` | `TreeChangefeedProtocol<S, C>` (adds `subscribeTree`) |
+| `Changefeed<S, C>` | `HasTreeChangefeed<S, C>` |
+| `hasChangefeed()` | `hasTreeChangefeed()`, `getOrCreateChangefeed()` |
 | `createChangefeed()`, `createCallable()` | `expandMapOpsToLeaves()` |
 
 Consumers import the contract from `@kyneta/changefeed` directly — schema does **not** re-export contract symbols. The import path tells the truth about the dependency.

package/dist/index.d.ts

@@ -28,9 +28,14 @@ declare const CHANGEFEED: unique symbol;
  *
  * - Auto-commit produces a degenerate changeset of one change.
  * - Transactions and `applyChanges` produce multi-change batches.
- * - `origin` carries provenance for the entire batch (e.g. "sync",
- *   "undo", "local"). Individual changes do not carry provenance —
- *   the batch does.
+ * - `origin` is an *application-level label* — opaque to the framework.
+ *   Apps may use it freely (`"sync"`, `"undo"`, `"local"`, anything).
+ *   The schema package and the exchange never branch on its value.
+ * - `replay` is a *structural directive* set by kyneta-internal layers.
+ *   `true` iff the batch represents state authored elsewhere (substrate
+ *   event bridge, `merge` payload, version travel). Layered consumers
+ *   (e.g. the exchange's echo filter) use `replay` to discriminate
+ *   "echo from sync" from "local write" without piggy-backing on origin.
  *
  * The subscriber API always receives a `Changeset`, making it uniform
  * regardless of how the changes were produced.
@@ -38,8 +43,11 @@ declare const CHANGEFEED: unique symbol;
 interface Changeset<C = ChangeBase> {
   /** The individual changes in this batch. */
   readonly changes: readonly C[];
-  /** Provenance of the batch (e.g. "sync", "undo", "local"). */
+  /** App-level provenance label (e.g. "sync", "undo", "local"). */
   readonly origin?: string;
+  /** Structural: true iff this batch is replaying state authored
+   *  elsewhere (substrate event bridge, merge payload). */
+  readonly replay?: boolean;
 }
 /**
  * The protocol object that sits behind the `[CHANGEFEED]` symbol.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/change.ts","../src/changefeed.ts","../src/callable.ts","../src/reactive-map.ts"],"mappings":";;AAyBA;;;;;;;;UAAiB,UAAA;EAAA,SACN,IAAA;AAAA;;;AADX;;;;;;;;AAAA,cCMa,UAAA;;;;;AAmBb;;;;;;;;;UAAiB,SAAA,KAAc,UAAA;EAId;EAAA,SAFN,OAAA,WAAkB,CAAA;EA6BM;EAAA,SA3BxB,MAAA;AAAA;;;;;;;;;;;;;;;;;;;;AAoDX;UAzBiB,kBAAA,cAAgC,UAAA,GAAa,UAAA;EAyBnC;EAAA,SAvBhB,OAAA,EAAS,CAAA;EAuBkC;EArBpD,SAAA,CAAU,QAAA,GAAW,SAAA,EAAW,SAAA,CAAU,CAAA;AAAA;;;;;;;;;;;;;;;UAqB3B,UAAA,cAAwB,UAAA,GAAa,UAAA;EAI3C;EAAA,UAFC,UAAA,GAAa,kBAAA,CAAmB,CAAA,EAAG,CAAA;EAI7C;EAAA,SAFS,OAAA,EAAS,CAAA;EAEwB;EAA1C,SAAA,CAAU,QAAA,GAAW,SAAA,EAAW,SAAA,CAAU,CAAA;AAAA;;;AAU5C;;;;;UAAiB,aAAA,wBAAqC,UAAA,GAAa,UAAA;EAAA,UACvD,UAAA,GAAa,kBAAA,CAAmB,CAAA,EAAG,CAAA;AAAA;;;;;iBAW/B,aAAA,wBAAqC,UAAA,GAAa,UAAA,CAAA,CAChE,KAAA,YACC,KAAA,IAAS,aAAA,CAAc,CAAA,EAAG,CAAA;;;;;;iBAkBb,gBAAA,GAAA,CAAoB,IAAA,EAAM,CAAA,GAAI,kBAAA,CAAmB,CAAA;;;AApBjE;;;;;;;;;;iBA+CgB,UAAA,cAAwB,UAAA,CAAA,CACtC,MAAA,EAAQ,aAAA,CAAc,CAAA,EAAG,CAAA,IACxB,UAAA,CAAW,CAAA,EAAG,CAAA;;;;;;;;;;;AA7BjB;;;;;iBA6DgB,gBAAA,cAA8B,UAAA,GAAa,UAAA,CAAA,CACzD,UAAA,QAAkB,CAAA,IAChB,IAAA,EAAM,UAAA,CAAW,CAAA,EAAG,CAAA,GAAI,IAAA,GAAO,SAAA,EAAW,SAAA,CAAU,CAAA;;;;;;;;;KClM5C,kBAAA,cAEA,UAAA,GAAa,UAAA,IACrB,UAAA,CAAW,CAAA,EAAG,CAAA,WAAY,CAAA;ADK9B;;;;;AAmBA;;;;;;;;;;;AA+BA;;AAlDA,iBCmBgB,cAAA,cAA4B,UAAA,CAAA,CAC1C,IAAA,EAAM,UAAA,CAAW,CAAA,EAAG,CAAA,IACnB,kBAAA,CAAmB,CAAA,EAAG,CAAA;;;;;;;;;ADrBzB;;;;;AAmBA;;;;;UEdiB,WAAA,iBAA4B,UAAA,GAAa,UAAA,UAChD,kBAAA,CAAmB,WAAA,CAAY,CAAA,EAAG,CAAA,GAAI,CAAA;EFerC;EEbT,GAAA,CAAI,GAAA,EAAK,CAAA,GAAI,CAAA;EFeJ;EEbT,GAAA,CAAI,GAAA,EAAK,CAAA;EFaM;EEXf,IAAA,IAAQ,gBAAA,CAAiB,CAAA;EFsCQ;EAAA,SEpCxB,IAAA;EFoCsC;EAAA,CElC9C,MAAA,CAAO,QAAP,KAAoB,gBAAA,EAAkB,CAAA,EAAG,CAAA;AAAA;;;;;;;;;;;UAa3B,iBAAA,iBAAkC,UAAA;EFyBjB;EEvBhC,GAAA,CAAI,GAAA,EAAK,CAAA,EAAG,KAAA,EAAO,CAAA;EFuBE;EErBrB,MAAA,CAAO,GAAA,EAAK,CAAA;EFqByC;EEnBrD,KAAA;EFwCe;EEtCf,IAAA,CAAK,SAAA,EAAW,SAAA,CAAU,CAAA;AAAA;;;;;;;;;;;;;;;;;;;;;iBA2BZ,iBAAA,iBAAkC,UAAA,GAAa,UAAA,CAAA,CAAA,IAC7D,WAAA,CAAY,CAAA,EAAG,CAAA,EAAG,CAAA,GAClB,iBAAA,CAAkB,CAAA,EAAG,CAAA,EAAG,CAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/change.ts","../src/changefeed.ts","../src/callable.ts","../src/reactive-map.ts"],"mappings":"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"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/changefeed.ts","../src/callable.ts","../src/reactive-map.ts"],"sourcesContent":["// Changefeed — the universal reactive contract.\n//\n// A changefeed is a reactive value with a current state and a stream\n// of future changes. You read `current` to see what's there now;\n// you subscribe to learn what changes next.\n//\n// The changefeed protocol is expressed through a single symbol: CHANGEFEED.\n//\n// Changes are delivered as `Changeset<C>` — a batch of one or more\n// changes with optional provenance metadata. Auto-commit wraps a\n// single change in a degenerate changeset of one; transactions and\n// `applyChanges` deliver multi-change batches. The subscriber API\n// is uniform regardless of batch size.\n//\n// This module is the canonical home of the reactive contract. It has\n// zero dependencies — no schema, no paths, no interpreters.\n\nimport type { ChangeBase } from \"./change.js\"\n\n// ---------------------------------------------------------------------------\n// Symbol\n// ---------------------------------------------------------------------------\n\n/**\n * The single symbol that marks a value as a changefeed. Accessing\n * `obj[CHANGEFEED]` yields a `ChangefeedProtocol<S, C>` — the current\n * value and a stream of future changes.\n *\n * Uses `Symbol.for` so that multiple copies of this module (e.g. in\n * different bundle chunks) share the same symbol identity.\n */\nexport const CHANGEFEED: unique symbol = Symbol.for(\"kyneta:changefeed\") as any\n\n// ---------------------------------------------------------------------------\n// Changeset — the unit of batch delivery\n// ---------------------------------------------------------------------------\n\n/**\n * A changeset is the unit of delivery through the changefeed protocol.\n * It wraps one or more changes with optional batch-level metadata.\n *\n * - Auto-commit produces a degenerate changeset of one change.\n * - Transactions and `applyChanges` produce multi-change batches.\n * - `origin` carries provenance for the entire batch (e.g. \"sync\",\n *   \"undo\", \"local\"). Individual changes do not carry provenance —\n *   the batch does.\n *\n * The subscriber API always receives a `Changeset`, making it uniform\n * regardless of how the changes were produced.\n */\nexport interface Changeset<C = ChangeBase> {\n  /** The individual changes in this batch. */\n  readonly changes: readonly C[]\n  /** Provenance of the batch (e.g. \"sync\", \"undo\", \"local\"). */\n  readonly origin?: string\n}\n\n// ---------------------------------------------------------------------------\n// Core interfaces — protocol layer\n// ---------------------------------------------------------------------------\n\n/**\n * The protocol object that sits behind the `[CHANGEFEED]` symbol.\n *\n * A coalgebra: `current` gives the live state, `subscribe` gives the\n * stream of future changes. In automata-theory terms this is a Moore\n * machine with a push-based transition stream.\n *\n * Properties:\n * - `current` is a getter — always returns the live current value\n * - `subscribe` returns an unsubscribe function\n * - Subscribers receive a `Changeset<C>` — a batch of changes with\n *   optional provenance. For auto-commit (single mutation), the\n *   changeset contains exactly one change.\n * - Static (non-reactive) sources return a protocol whose tail never emits:\n *   `{ current: value, subscribe: () => () => {} }`\n *\n * This is internal plumbing — developers interact with `Changefeed<S, C>`\n * (the developer-facing type that includes `[CHANGEFEED]`, `.current`,\n * and `.subscribe()` in one interface).\n */\nexport interface ChangefeedProtocol<S, C extends ChangeBase = ChangeBase> {\n  /** The current value, always live (a getter). */\n  readonly current: S\n  /** Subscribe to future changes. Returns an unsubscribe function. */\n  subscribe(callback: (changeset: Changeset<C>) => void): () => void\n}\n\n// ---------------------------------------------------------------------------\n// Core interfaces — developer-facing type\n// ---------------------------------------------------------------------------\n\n/**\n * The developer-facing changefeed type: a reactive value with direct\n * access to `.current`, `.subscribe()`, and the `[CHANGEFEED]` marker.\n *\n * Developers write `readonly peers: Changefeed<PeerMap, PeerChange>` —\n * no `Has` prefix, no separate protocol object, no triple declaration.\n *\n * A `Changefeed<S, C>` is the intersection of:\n * - The `[CHANGEFEED]` marker (for compiler detection and runtime protocol)\n * - Direct `.current` and `.subscribe()` access (for developer ergonomics)\n *\n * Use `changefeed(source)` to project any `HasChangefeed` into a\n * `Changefeed`, or `createChangefeed()` to build one from scratch.\n */\nexport interface Changefeed<S, C extends ChangeBase = ChangeBase> {\n  /** The protocol object behind the symbol. */\n  readonly [CHANGEFEED]: ChangefeedProtocol<S, C>\n  /** The current value, always live (a getter). */\n  readonly current: S\n  /** Subscribe to future changes. Returns an unsubscribe function. */\n  subscribe(callback: (changeset: Changeset<C>) => void): () => void\n}\n\n/**\n * An object that carries a changefeed protocol under the `[CHANGEFEED]`\n * symbol.\n *\n * Any ref, interpreted node, or enriched value can implement this\n * interface to participate in the reactive protocol.\n */\nexport interface HasChangefeed<S = unknown, A extends ChangeBase = ChangeBase> {\n  readonly [CHANGEFEED]: ChangefeedProtocol<S, A>\n}\n\n// ---------------------------------------------------------------------------\n// Type guard\n// ---------------------------------------------------------------------------\n\n/**\n * Returns `true` if `value` has a `[CHANGEFEED]` property, i.e. it\n * implements the `HasChangefeed` interface.\n */\nexport function hasChangefeed<S = unknown, A extends ChangeBase = ChangeBase>(\n  value: unknown,\n): value is HasChangefeed<S, A> {\n  return (\n    value !== null &&\n    value !== undefined &&\n    (typeof value === \"object\" || typeof value === \"function\") &&\n    CHANGEFEED in (value as object)\n  )\n}\n\n// ---------------------------------------------------------------------------\n// Static feed helper\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a changefeed protocol that never emits changes — useful for\n * static/non-reactive data sources that still need to participate in\n * the changefeed protocol.\n */\nexport function staticChangefeed<S>(head: S): ChangefeedProtocol<S, never> {\n  return {\n    get current() {\n      return head\n    },\n    subscribe() {\n      return () => {}\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Projector — lift HasChangefeed to Changefeed\n// ---------------------------------------------------------------------------\n\n/**\n * Project any object with `[CHANGEFEED]` into a developer-facing\n * `Changefeed<S, C>` — lifting the hidden protocol surface to direct\n * `.current` and `.subscribe()` accessibility.\n *\n * ```ts\n * const feed = changefeed(doc.title)\n * feed.current          // live value\n * feed.subscribe(cb)    // subscribe to changes\n * feed[CHANGEFEED]      // the protocol object (same as doc.title[CHANGEFEED])\n * ```\n */\nexport function changefeed<S, C extends ChangeBase>(\n  source: HasChangefeed<S, C>,\n): Changefeed<S, C> {\n  const protocol = source[CHANGEFEED]\n  return {\n    [CHANGEFEED]: protocol,\n    get current(): S {\n      return protocol.current\n    },\n    subscribe(callback: (changeset: Changeset<C>) => void): () => void {\n      return protocol.subscribe(callback)\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory — create standalone Changefeed values\n// ---------------------------------------------------------------------------\n\n/**\n * Create a standalone `Changefeed<S, C>` with push semantics.\n *\n * Returns a tuple of the feed and an emit function. The feed's\n * `[CHANGEFEED]` returns the protocol view of itself. Manages its\n * own subscriber set internally.\n *\n * ```ts\n * const [feed, emit] = createChangefeed(() => count)\n * feed.current                       // read live value\n * feed.subscribe(cs => { ... })      // subscribe\n * hasChangefeed(feed)                 // true\n * emit({ changes: [{ type: \"replace\", value: 42 }] })  // push\n * ```\n */\nexport function createChangefeed<S, C extends ChangeBase = ChangeBase>(\n  getCurrent: () => S,\n): [feed: Changefeed<S, C>, emit: (changeset: Changeset<C>) => void] {\n  const subscribers = new Set<(changeset: Changeset<C>) => void>()\n\n  const protocol: ChangefeedProtocol<S, C> = {\n    get current(): S {\n      return getCurrent()\n    },\n    subscribe(callback: (changeset: Changeset<C>) => void): () => void {\n      subscribers.add(callback)\n      return () => {\n        subscribers.delete(callback)\n      }\n    },\n  }\n\n  const feed: Changefeed<S, C> = {\n    [CHANGEFEED]: protocol,\n    get current(): S {\n      return getCurrent()\n    },\n    subscribe(callback: (changeset: Changeset<C>) => void): () => void {\n      return protocol.subscribe(callback)\n    },\n  }\n\n  const emit = (changeset: Changeset<C>): void => {\n    for (const cb of subscribers) {\n      cb(changeset)\n    }\n  }\n\n  return [feed, emit]\n}\n","// callable — the createCallable combinator.\n//\n// Wraps a Changefeed<S, C> in a callable function-object so that\n// `feed()` returns `feed.current`. The callable preserves the full\n// changefeed contract: [CHANGEFEED], .current, .subscribe().\n//\n// This is the same function-object pattern used by LocalRef in\n// @kyneta/cast — a function with properties attached.\n\nimport type { ChangeBase } from \"./change.js\"\nimport type { Changefeed, ChangefeedProtocol, Changeset } from \"./changefeed.js\"\nimport { CHANGEFEED } from \"./changefeed.js\"\n\n// ---------------------------------------------------------------------------\n// Type\n// ---------------------------------------------------------------------------\n\n/**\n * A changefeed that is also callable — `feed()` returns `feed.current`.\n *\n * This is the intersection of `Changefeed<S, C>` and `() => S`.\n * The call signature provides ergonomic read access without `.current`.\n */\nexport type CallableChangefeed<\n  S,\n  C extends ChangeBase = ChangeBase,\n> = Changefeed<S, C> & (() => S)\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a `Changefeed<S, C>` in a callable function-object.\n *\n * The returned object:\n * - `feed()` → `feed.current` (callable)\n * - `feed.current` → delegated getter\n * - `feed.subscribe(cb)` → delegated\n * - `feed[CHANGEFEED]` → delegated protocol\n * - `hasChangefeed(feed)` → `true`\n *\n * ```ts\n * const [source, emit] = createChangefeed(() => count)\n * const feed = createCallable(source)\n * feed()              // read current value\n * feed.current        // same as feed()\n * feed.subscribe(cb)  // subscribe to changes\n * ```\n */\nexport function createCallable<S, C extends ChangeBase>(\n  feed: Changefeed<S, C>,\n): CallableChangefeed<S, C> {\n  const callable: any = () => feed.current\n\n  // [CHANGEFEED] — non-enumerable getter delegating to source\n  Object.defineProperty(callable, CHANGEFEED, {\n    get(): ChangefeedProtocol<S, C> {\n      return feed[CHANGEFEED]\n    },\n    enumerable: false,\n    configurable: false,\n  })\n\n  // .current — getter delegating to source\n  Object.defineProperty(callable, \"current\", {\n    get(): S {\n      return feed.current\n    },\n    enumerable: true,\n    configurable: false,\n  })\n\n  // .subscribe — delegating to source\n  callable.subscribe = (\n    callback: (changeset: Changeset<C>) => void,\n  ): (() => void) => {\n    return feed.subscribe(callback)\n  }\n\n  return callable as CallableChangefeed<S, C>\n}\n","// reactive-map — a callable changefeed over a mutable Map.\n//\n// ReactiveMap<K, V, C> is a CallableChangefeed<ReadonlyMap<K, V>, C>\n// with lifted collection accessors (.get, .has, .keys, .size, iteration).\n// The handle provides raw map mutations (set, delete, clear) without\n// automatic emission — the consumer decides when and what to emit.\n//\n// This extracts the recurring pattern of \"callable changefeed over a\n// ReadonlyMap with convenience accessors\" (used by exchange.peers,\n// Catalog, and future reactive collections) into a single combinator.\n\nimport type { CallableChangefeed } from \"./callable.js\"\nimport type { ChangeBase } from \"./change.js\"\nimport type { ChangefeedProtocol, Changeset } from \"./changefeed.js\"\nimport { CHANGEFEED, createChangefeed } from \"./changefeed.js\"\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A callable changefeed over a `ReadonlyMap<K, V>` with lifted\n * collection accessors.\n *\n * `reactiveMap()` returns a **snapshot** — a shallow copy of the\n * current `ReadonlyMap<K, V>`. Each call produces a new `Map` instance,\n * so external-store consumers (e.g. `useSyncExternalStore`) can detect\n * changes via reference identity.\n *\n * `.current` returns the **live** map — the same instance every time.\n * `.get()`, `.has()`, `.keys()`, `.size`, and `[Symbol.iterator]()`\n * delegate to the live internal map — no need to unwrap `.current` first.\n *\n * Extends `CallableChangefeed` — assignable anywhere a\n * `CallableChangefeed<ReadonlyMap<K, V>, C>` or `Changefeed` is expected.\n */\nexport interface ReactiveMap<K, V, C extends ChangeBase = ChangeBase>\n  extends CallableChangefeed<ReadonlyMap<K, V>, C> {\n  /** Get the value for a key, or `undefined` if absent. */\n  get(key: K): V | undefined\n  /** Whether the map contains a key. */\n  has(key: K): boolean\n  /** An iterator over all keys. */\n  keys(): IterableIterator<K>\n  /** The number of entries. */\n  readonly size: number\n  /** Iterate over `[key, value]` pairs. */\n  [Symbol.iterator](): IterableIterator<[K, V]>\n}\n\n/**\n * The producer-side handle for a `ReactiveMap`.\n *\n * Provides raw map mutations (`set`, `delete`, `clear`) that modify\n * the internal map **without** emitting changes. Call `emit()` with\n * the appropriate changeset after mutations are complete.\n *\n * This separation lets the consumer batch mutations and emit a single\n * changeset — e.g. `clear()` → N × `set()` → one `emit()`.\n */\nexport interface ReactiveMapHandle<K, V, C extends ChangeBase> {\n  /** Insert or overwrite an entry. Does NOT emit. */\n  set(key: K, value: V): void\n  /** Remove an entry. Returns `true` if the key was present. Does NOT emit. */\n  delete(key: K): boolean\n  /** Remove all entries. Does NOT emit. */\n  clear(): void\n  /** Push a changeset to all subscribers. */\n  emit(changeset: Changeset<C>): void\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a `ReactiveMap<K, V, C>` and its producer-side handle.\n *\n * The reactive map owns its internal `Map<K, V>`. Consumers read via\n * the `ReactiveMap` surface (call signature, `.get()`, `.has()`, etc.).\n * Producers mutate via the `ReactiveMapHandle` (`set`, `delete`,\n * `clear`) and push notifications via `emit`.\n *\n * ```ts\n * const [peers, handle] = createReactiveMap<PeerId, PeerInfo, PeerChange>()\n *\n * handle.set(\"alice\", aliceInfo)\n * handle.emit({ changes: [{ type: \"peer-joined\", peer: aliceInfo }] })\n *\n * peers()          // ReadonlyMap snapshot (shallow copy)\n * peers.current    // live map (same instance always)\n * peers.get(\"alice\")  // aliceInfo (reads live map)\n * peers.size       // 1\n * ```\n */\nexport function createReactiveMap<K, V, C extends ChangeBase = ChangeBase>(): [\n  ReactiveMap<K, V, C>,\n  ReactiveMapHandle<K, V, C>,\n] {\n  const map = new Map<K, V>()\n\n  // Create the base changefeed + emit pair.\n  // The thunk returns a shallow copy — each call produces a new Map.\n  // This gives the callable snapshot semantics: external-store consumers\n  // (e.g. useSyncExternalStore) detect identity changes when contents\n  // change.  The live map is still available via .current and the\n  // lifted accessors.\n  const [feed, emit] = createChangefeed<ReadonlyMap<K, V>, C>(\n    () => new Map(map),\n  )\n\n  // Build the callable function-object.\n  // We construct it manually (rather than using createCallable) so we\n  // can attach the collection accessors in one pass.\n  const callable: any = () => new Map(map) as ReadonlyMap<K, V>\n\n  // ── Changefeed protocol ──\n\n  Object.defineProperty(callable, CHANGEFEED, {\n    get(): ChangefeedProtocol<ReadonlyMap<K, V>, C> {\n      return feed[CHANGEFEED]\n    },\n    enumerable: false,\n    configurable: false,\n  })\n\n  Object.defineProperty(callable, \"current\", {\n    get(): ReadonlyMap<K, V> {\n      return map\n    },\n    enumerable: true,\n    configurable: false,\n  })\n\n  callable.subscribe = (\n    callback: (changeset: Changeset<C>) => void,\n  ): (() => void) => {\n    return feed.subscribe(callback)\n  }\n\n  // ── Lifted collection accessors ──\n\n  callable.get = (key: K): V | undefined => map.get(key)\n  callable.has = (key: K): boolean => map.has(key)\n  callable.keys = (): IterableIterator<K> => map.keys()\n\n  Object.defineProperty(callable, \"size\", {\n    get(): number {\n      return map.size\n    },\n    enumerable: true,\n    configurable: false,\n  })\n\n  callable[Symbol.iterator] = (): IterableIterator<[K, V]> =>\n    map[Symbol.iterator]()\n\n  // ── Handle (producer side) ──\n\n  const handle: ReactiveMapHandle<K, V, C> = {\n    set(key: K, value: V): void {\n      map.set(key, value)\n    },\n    delete(key: K): boolean {\n      return map.delete(key)\n    },\n    clear(): void {\n      map.clear()\n    },\n    emit,\n  }\n\n  return [callable as ReactiveMap<K, V, C>, handle]\n}\n"],"mappings":";;;;;;;;;AA+BA,MAAa,aAA4B,OAAO,IAAI,oBAAoB;;;;;AAuGxE,SAAgB,cACd,OAC8B;AAC9B,QACE,UAAU,QACV,UAAU,KAAA,MACT,OAAO,UAAU,YAAY,OAAO,UAAU,eAC/C,cAAe;;;;;;;AAanB,SAAgB,iBAAoB,MAAuC;AACzE,QAAO;EACL,IAAI,UAAU;AACZ,UAAO;;EAET,YAAY;AACV,gBAAa;;EAEhB;;;;;;;;;;;;;;AAmBH,SAAgB,WACd,QACkB;CAClB,MAAM,WAAW,OAAO;AACxB,QAAO;GACJ,aAAa;EACd,IAAI,UAAa;AACf,UAAO,SAAS;;EAElB,UAAU,UAAyD;AACjE,UAAO,SAAS,UAAU,SAAS;;EAEtC;;;;;;;;;;;;;;;;;AAsBH,SAAgB,iBACd,YACmE;CACnE,MAAM,8BAAc,IAAI,KAAwC;CAEhE,MAAM,WAAqC;EACzC,IAAI,UAAa;AACf,UAAO,YAAY;;EAErB,UAAU,UAAyD;AACjE,eAAY,IAAI,SAAS;AACzB,gBAAa;AACX,gBAAY,OAAO,SAAS;;;EAGjC;CAED,MAAM,OAAyB;GAC5B,aAAa;EACd,IAAI,UAAa;AACf,UAAO,YAAY;;EAErB,UAAU,UAAyD;AACjE,UAAO,SAAS,UAAU,SAAS;;EAEtC;CAED,MAAM,QAAQ,cAAkC;AAC9C,OAAK,MAAM,MAAM,YACf,IAAG,UAAU;;AAIjB,QAAO,CAAC,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;ACtMrB,SAAgB,eACd,MAC0B;CAC1B,MAAM,iBAAsB,KAAK;AAGjC,QAAO,eAAe,UAAU,YAAY;EAC1C,MAAgC;AAC9B,UAAO,KAAK;;EAEd,YAAY;EACZ,cAAc;EACf,CAAC;AAGF,QAAO,eAAe,UAAU,WAAW;EACzC,MAAS;AACP,UAAO,KAAK;;EAEd,YAAY;EACZ,cAAc;EACf,CAAC;AAGF,UAAS,aACP,aACiB;AACjB,SAAO,KAAK,UAAU,SAAS;;AAGjC,QAAO;;;;;;;;;;;;;;;;;;;;;;;;ACeT,SAAgB,oBAGd;CACA,MAAM,sBAAM,IAAI,KAAW;CAQ3B,MAAM,CAAC,MAAM,QAAQ,uBACb,IAAI,IAAI,IAAI,CACnB;CAKD,MAAM,iBAAsB,IAAI,IAAI,IAAI;AAIxC,QAAO,eAAe,UAAU,YAAY;EAC1C,MAAgD;AAC9C,UAAO,KAAK;;EAEd,YAAY;EACZ,cAAc;EACf,CAAC;AAEF,QAAO,eAAe,UAAU,WAAW;EACzC,MAAyB;AACvB,UAAO;;EAET,YAAY;EACZ,cAAc;EACf,CAAC;AAEF,UAAS,aACP,aACiB;AACjB,SAAO,KAAK,UAAU,SAAS;;AAKjC,UAAS,OAAO,QAA0B,IAAI,IAAI,IAAI;AACtD,UAAS,OAAO,QAAoB,IAAI,IAAI,IAAI;AAChD,UAAS,aAAkC,IAAI,MAAM;AAErD,QAAO,eAAe,UAAU,QAAQ;EACtC,MAAc;AACZ,UAAO,IAAI;;EAEb,YAAY;EACZ,cAAc;EACf,CAAC;AAEF,UAAS,OAAO,kBACd,IAAI,OAAO,WAAW;AAiBxB,QAAO,CAAC,UAbmC;EACzC,IAAI,KAAQ,OAAgB;AAC1B,OAAI,IAAI,KAAK,MAAM;;EAErB,OAAO,KAAiB;AACtB,UAAO,IAAI,OAAO,IAAI;;EAExB,QAAc;AACZ,OAAI,OAAO;;EAEb;EACD,CAEgD"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/changefeed.ts","../src/callable.ts","../src/reactive-map.ts"],"sourcesContent":["// Changefeed — the universal reactive contract.\n//\n// A changefeed is a reactive value with a current state and a stream\n// of future changes. You read `current` to see what's there now;\n// you subscribe to learn what changes next.\n//\n// The changefeed protocol is expressed through a single symbol: CHANGEFEED.\n//\n// Changes are delivered as `Changeset<C>` — a batch of one or more\n// changes with optional provenance metadata. Auto-commit wraps a\n// single change in a degenerate changeset of one; transactions and\n// `applyChanges` deliver multi-change batches. The subscriber API\n// is uniform regardless of batch size.\n//\n// This module is the canonical home of the reactive contract. It has\n// zero dependencies — no schema, no paths, no interpreters.\n\nimport type { ChangeBase } from \"./change.js\"\n\n// ---------------------------------------------------------------------------\n// Symbol\n// ---------------------------------------------------------------------------\n\n/**\n * The single symbol that marks a value as a changefeed. Accessing\n * `obj[CHANGEFEED]` yields a `ChangefeedProtocol<S, C>` — the current\n * value and a stream of future changes.\n *\n * Uses `Symbol.for` so that multiple copies of this module (e.g. in\n * different bundle chunks) share the same symbol identity.\n */\nexport const CHANGEFEED: unique symbol = Symbol.for(\"kyneta:changefeed\") as any\n\n// ---------------------------------------------------------------------------\n// Changeset — the unit of batch delivery\n// ---------------------------------------------------------------------------\n\n/**\n * A changeset is the unit of delivery through the changefeed protocol.\n * It wraps one or more changes with optional batch-level metadata.\n *\n * - Auto-commit produces a degenerate changeset of one change.\n * - Transactions and `applyChanges` produce multi-change batches.\n * - `origin` is an *application-level label* — opaque to the framework.\n *   Apps may use it freely (`\"sync\"`, `\"undo\"`, `\"local\"`, anything).\n *   The schema package and the exchange never branch on its value.\n * - `replay` is a *structural directive* set by kyneta-internal layers.\n *   `true` iff the batch represents state authored elsewhere (substrate\n *   event bridge, `merge` payload, version travel). Layered consumers\n *   (e.g. the exchange's echo filter) use `replay` to discriminate\n *   \"echo from sync\" from \"local write\" without piggy-backing on origin.\n *\n * The subscriber API always receives a `Changeset`, making it uniform\n * regardless of how the changes were produced.\n */\nexport interface Changeset<C = ChangeBase> {\n  /** The individual changes in this batch. */\n  readonly changes: readonly C[]\n  /** App-level provenance label (e.g. \"sync\", \"undo\", \"local\"). */\n  readonly origin?: string\n  /** Structural: true iff this batch is replaying state authored\n   *  elsewhere (substrate event bridge, merge payload). */\n  readonly replay?: boolean\n}\n\n// ---------------------------------------------------------------------------\n// Core interfaces — protocol layer\n// ---------------------------------------------------------------------------\n\n/**\n * The protocol object that sits behind the `[CHANGEFEED]` symbol.\n *\n * A coalgebra: `current` gives the live state, `subscribe` gives the\n * stream of future changes. In automata-theory terms this is a Moore\n * machine with a push-based transition stream.\n *\n * Properties:\n * - `current` is a getter — always returns the live current value\n * - `subscribe` returns an unsubscribe function\n * - Subscribers receive a `Changeset<C>` — a batch of changes with\n *   optional provenance. For auto-commit (single mutation), the\n *   changeset contains exactly one change.\n * - Static (non-reactive) sources return a protocol whose tail never emits:\n *   `{ current: value, subscribe: () => () => {} }`\n *\n * This is internal plumbing — developers interact with `Changefeed<S, C>`\n * (the developer-facing type that includes `[CHANGEFEED]`, `.current`,\n * and `.subscribe()` in one interface).\n */\nexport interface ChangefeedProtocol<S, C extends ChangeBase = ChangeBase> {\n  /** The current value, always live (a getter). */\n  readonly current: S\n  /** Subscribe to future changes. Returns an unsubscribe function. */\n  subscribe(callback: (changeset: Changeset<C>) => void): () => void\n}\n\n// ---------------------------------------------------------------------------\n// Core interfaces — developer-facing type\n// ---------------------------------------------------------------------------\n\n/**\n * The developer-facing changefeed type: a reactive value with direct\n * access to `.current`, `.subscribe()`, and the `[CHANGEFEED]` marker.\n *\n * Developers write `readonly peers: Changefeed<PeerMap, PeerChange>` —\n * no `Has` prefix, no separate protocol object, no triple declaration.\n *\n * A `Changefeed<S, C>` is the intersection of:\n * - The `[CHANGEFEED]` marker (for compiler detection and runtime protocol)\n * - Direct `.current` and `.subscribe()` access (for developer ergonomics)\n *\n * Use `changefeed(source)` to project any `HasChangefeed` into a\n * `Changefeed`, or `createChangefeed()` to build one from scratch.\n */\nexport interface Changefeed<S, C extends ChangeBase = ChangeBase> {\n  /** The protocol object behind the symbol. */\n  readonly [CHANGEFEED]: ChangefeedProtocol<S, C>\n  /** The current value, always live (a getter). */\n  readonly current: S\n  /** Subscribe to future changes. Returns an unsubscribe function. */\n  subscribe(callback: (changeset: Changeset<C>) => void): () => void\n}\n\n/**\n * An object that carries a changefeed protocol under the `[CHANGEFEED]`\n * symbol.\n *\n * Any ref, interpreted node, or enriched value can implement this\n * interface to participate in the reactive protocol.\n */\nexport interface HasChangefeed<S = unknown, A extends ChangeBase = ChangeBase> {\n  readonly [CHANGEFEED]: ChangefeedProtocol<S, A>\n}\n\n// ---------------------------------------------------------------------------\n// Type guard\n// ---------------------------------------------------------------------------\n\n/**\n * Returns `true` if `value` has a `[CHANGEFEED]` property, i.e. it\n * implements the `HasChangefeed` interface.\n */\nexport function hasChangefeed<S = unknown, A extends ChangeBase = ChangeBase>(\n  value: unknown,\n): value is HasChangefeed<S, A> {\n  return (\n    value !== null &&\n    value !== undefined &&\n    (typeof value === \"object\" || typeof value === \"function\") &&\n    CHANGEFEED in (value as object)\n  )\n}\n\n// ---------------------------------------------------------------------------\n// Static feed helper\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a changefeed protocol that never emits changes — useful for\n * static/non-reactive data sources that still need to participate in\n * the changefeed protocol.\n */\nexport function staticChangefeed<S>(head: S): ChangefeedProtocol<S, never> {\n  return {\n    get current() {\n      return head\n    },\n    subscribe() {\n      return () => {}\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Projector — lift HasChangefeed to Changefeed\n// ---------------------------------------------------------------------------\n\n/**\n * Project any object with `[CHANGEFEED]` into a developer-facing\n * `Changefeed<S, C>` — lifting the hidden protocol surface to direct\n * `.current` and `.subscribe()` accessibility.\n *\n * ```ts\n * const feed = changefeed(doc.title)\n * feed.current          // live value\n * feed.subscribe(cb)    // subscribe to changes\n * feed[CHANGEFEED]      // the protocol object (same as doc.title[CHANGEFEED])\n * ```\n */\nexport function changefeed<S, C extends ChangeBase>(\n  source: HasChangefeed<S, C>,\n): Changefeed<S, C> {\n  const protocol = source[CHANGEFEED]\n  return {\n    [CHANGEFEED]: protocol,\n    get current(): S {\n      return protocol.current\n    },\n    subscribe(callback: (changeset: Changeset<C>) => void): () => void {\n      return protocol.subscribe(callback)\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory — create standalone Changefeed values\n// ---------------------------------------------------------------------------\n\n/**\n * Create a standalone `Changefeed<S, C>` with push semantics.\n *\n * Returns a tuple of the feed and an emit function. The feed's\n * `[CHANGEFEED]` returns the protocol view of itself. Manages its\n * own subscriber set internally.\n *\n * ```ts\n * const [feed, emit] = createChangefeed(() => count)\n * feed.current                       // read live value\n * feed.subscribe(cs => { ... })      // subscribe\n * hasChangefeed(feed)                 // true\n * emit({ changes: [{ type: \"replace\", value: 42 }] })  // push\n * ```\n */\nexport function createChangefeed<S, C extends ChangeBase = ChangeBase>(\n  getCurrent: () => S,\n): [feed: Changefeed<S, C>, emit: (changeset: Changeset<C>) => void] {\n  const subscribers = new Set<(changeset: Changeset<C>) => void>()\n\n  const protocol: ChangefeedProtocol<S, C> = {\n    get current(): S {\n      return getCurrent()\n    },\n    subscribe(callback: (changeset: Changeset<C>) => void): () => void {\n      subscribers.add(callback)\n      return () => {\n        subscribers.delete(callback)\n      }\n    },\n  }\n\n  const feed: Changefeed<S, C> = {\n    [CHANGEFEED]: protocol,\n    get current(): S {\n      return getCurrent()\n    },\n    subscribe(callback: (changeset: Changeset<C>) => void): () => void {\n      return protocol.subscribe(callback)\n    },\n  }\n\n  const emit = (changeset: Changeset<C>): void => {\n    for (const cb of subscribers) {\n      cb(changeset)\n    }\n  }\n\n  return [feed, emit]\n}\n","// callable — the createCallable combinator.\n//\n// Wraps a Changefeed<S, C> in a callable function-object so that\n// `feed()` returns `feed.current`. The callable preserves the full\n// changefeed contract: [CHANGEFEED], .current, .subscribe().\n//\n// This is the same function-object pattern used by LocalRef in\n// @kyneta/cast — a function with properties attached.\n\nimport type { ChangeBase } from \"./change.js\"\nimport type { Changefeed, ChangefeedProtocol, Changeset } from \"./changefeed.js\"\nimport { CHANGEFEED } from \"./changefeed.js\"\n\n// ---------------------------------------------------------------------------\n// Type\n// ---------------------------------------------------------------------------\n\n/**\n * A changefeed that is also callable — `feed()` returns `feed.current`.\n *\n * This is the intersection of `Changefeed<S, C>` and `() => S`.\n * The call signature provides ergonomic read access without `.current`.\n */\nexport type CallableChangefeed<\n  S,\n  C extends ChangeBase = ChangeBase,\n> = Changefeed<S, C> & (() => S)\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a `Changefeed<S, C>` in a callable function-object.\n *\n * The returned object:\n * - `feed()` → `feed.current` (callable)\n * - `feed.current` → delegated getter\n * - `feed.subscribe(cb)` → delegated\n * - `feed[CHANGEFEED]` → delegated protocol\n * - `hasChangefeed(feed)` → `true`\n *\n * ```ts\n * const [source, emit] = createChangefeed(() => count)\n * const feed = createCallable(source)\n * feed()              // read current value\n * feed.current        // same as feed()\n * feed.subscribe(cb)  // subscribe to changes\n * ```\n */\nexport function createCallable<S, C extends ChangeBase>(\n  feed: Changefeed<S, C>,\n): CallableChangefeed<S, C> {\n  const callable: any = () => feed.current\n\n  // [CHANGEFEED] — non-enumerable getter delegating to source\n  Object.defineProperty(callable, CHANGEFEED, {\n    get(): ChangefeedProtocol<S, C> {\n      return feed[CHANGEFEED]\n    },\n    enumerable: false,\n    configurable: false,\n  })\n\n  // .current — getter delegating to source\n  Object.defineProperty(callable, \"current\", {\n    get(): S {\n      return feed.current\n    },\n    enumerable: true,\n    configurable: false,\n  })\n\n  // .subscribe — delegating to source\n  callable.subscribe = (\n    callback: (changeset: Changeset<C>) => void,\n  ): (() => void) => {\n    return feed.subscribe(callback)\n  }\n\n  return callable as CallableChangefeed<S, C>\n}\n","// reactive-map — a callable changefeed over a mutable Map.\n//\n// ReactiveMap<K, V, C> is a CallableChangefeed<ReadonlyMap<K, V>, C>\n// with lifted collection accessors (.get, .has, .keys, .size, iteration).\n// The handle provides raw map mutations (set, delete, clear) without\n// automatic emission — the consumer decides when and what to emit.\n//\n// This extracts the recurring pattern of \"callable changefeed over a\n// ReadonlyMap with convenience accessors\" (used by exchange.peers,\n// Catalog, and future reactive collections) into a single combinator.\n\nimport type { CallableChangefeed } from \"./callable.js\"\nimport type { ChangeBase } from \"./change.js\"\nimport type { ChangefeedProtocol, Changeset } from \"./changefeed.js\"\nimport { CHANGEFEED, createChangefeed } from \"./changefeed.js\"\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A callable changefeed over a `ReadonlyMap<K, V>` with lifted\n * collection accessors.\n *\n * `reactiveMap()` returns a **snapshot** — a shallow copy of the\n * current `ReadonlyMap<K, V>`. Each call produces a new `Map` instance,\n * so external-store consumers (e.g. `useSyncExternalStore`) can detect\n * changes via reference identity.\n *\n * `.current` returns the **live** map — the same instance every time.\n * `.get()`, `.has()`, `.keys()`, `.size`, and `[Symbol.iterator]()`\n * delegate to the live internal map — no need to unwrap `.current` first.\n *\n * Extends `CallableChangefeed` — assignable anywhere a\n * `CallableChangefeed<ReadonlyMap<K, V>, C>` or `Changefeed` is expected.\n */\nexport interface ReactiveMap<K, V, C extends ChangeBase = ChangeBase>\n  extends CallableChangefeed<ReadonlyMap<K, V>, C> {\n  /** Get the value for a key, or `undefined` if absent. */\n  get(key: K): V | undefined\n  /** Whether the map contains a key. */\n  has(key: K): boolean\n  /** An iterator over all keys. */\n  keys(): IterableIterator<K>\n  /** The number of entries. */\n  readonly size: number\n  /** Iterate over `[key, value]` pairs. */\n  [Symbol.iterator](): IterableIterator<[K, V]>\n}\n\n/**\n * The producer-side handle for a `ReactiveMap`.\n *\n * Provides raw map mutations (`set`, `delete`, `clear`) that modify\n * the internal map **without** emitting changes. Call `emit()` with\n * the appropriate changeset after mutations are complete.\n *\n * This separation lets the consumer batch mutations and emit a single\n * changeset — e.g. `clear()` → N × `set()` → one `emit()`.\n */\nexport interface ReactiveMapHandle<K, V, C extends ChangeBase> {\n  /** Insert or overwrite an entry. Does NOT emit. */\n  set(key: K, value: V): void\n  /** Remove an entry. Returns `true` if the key was present. Does NOT emit. */\n  delete(key: K): boolean\n  /** Remove all entries. Does NOT emit. */\n  clear(): void\n  /** Push a changeset to all subscribers. */\n  emit(changeset: Changeset<C>): void\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a `ReactiveMap<K, V, C>` and its producer-side handle.\n *\n * The reactive map owns its internal `Map<K, V>`. Consumers read via\n * the `ReactiveMap` surface (call signature, `.get()`, `.has()`, etc.).\n * Producers mutate via the `ReactiveMapHandle` (`set`, `delete`,\n * `clear`) and push notifications via `emit`.\n *\n * ```ts\n * const [peers, handle] = createReactiveMap<PeerId, PeerInfo, PeerChange>()\n *\n * handle.set(\"alice\", aliceInfo)\n * handle.emit({ changes: [{ type: \"peer-joined\", peer: aliceInfo }] })\n *\n * peers()          // ReadonlyMap snapshot (shallow copy)\n * peers.current    // live map (same instance always)\n * peers.get(\"alice\")  // aliceInfo (reads live map)\n * peers.size       // 1\n * ```\n */\nexport function createReactiveMap<K, V, C extends ChangeBase = ChangeBase>(): [\n  ReactiveMap<K, V, C>,\n  ReactiveMapHandle<K, V, C>,\n] {\n  const map = new Map<K, V>()\n\n  // Create the base changefeed + emit pair.\n  // The thunk returns a shallow copy — each call produces a new Map.\n  // This gives the callable snapshot semantics: external-store consumers\n  // (e.g. useSyncExternalStore) detect identity changes when contents\n  // change.  The live map is still available via .current and the\n  // lifted accessors.\n  const [feed, emit] = createChangefeed<ReadonlyMap<K, V>, C>(\n    () => new Map(map),\n  )\n\n  // Build the callable function-object.\n  // We construct it manually (rather than using createCallable) so we\n  // can attach the collection accessors in one pass.\n  const callable: any = () => new Map(map) as ReadonlyMap<K, V>\n\n  // ── Changefeed protocol ──\n\n  Object.defineProperty(callable, CHANGEFEED, {\n    get(): ChangefeedProtocol<ReadonlyMap<K, V>, C> {\n      return feed[CHANGEFEED]\n    },\n    enumerable: false,\n    configurable: false,\n  })\n\n  Object.defineProperty(callable, \"current\", {\n    get(): ReadonlyMap<K, V> {\n      return map\n    },\n    enumerable: true,\n    configurable: false,\n  })\n\n  callable.subscribe = (\n    callback: (changeset: Changeset<C>) => void,\n  ): (() => void) => {\n    return feed.subscribe(callback)\n  }\n\n  // ── Lifted collection accessors ──\n\n  callable.get = (key: K): V | undefined => map.get(key)\n  callable.has = (key: K): boolean => map.has(key)\n  callable.keys = (): IterableIterator<K> => map.keys()\n\n  Object.defineProperty(callable, \"size\", {\n    get(): number {\n      return map.size\n    },\n    enumerable: true,\n    configurable: false,\n  })\n\n  callable[Symbol.iterator] = (): IterableIterator<[K, V]> =>\n    map[Symbol.iterator]()\n\n  // ── Handle (producer side) ──\n\n  const handle: ReactiveMapHandle<K, V, C> = {\n    set(key: K, value: V): void {\n      map.set(key, value)\n    },\n    delete(key: K): boolean {\n      return map.delete(key)\n    },\n    clear(): void {\n      map.clear()\n    },\n    emit,\n  }\n\n  return [callable as ReactiveMap<K, V, C>, handle]\n}\n"],"mappings":";;;;;;;;;AA+BA,MAAa,aAA4B,OAAO,IAAI,mBAAmB;;;;;AA+GvE,SAAgB,cACd,OAC8B;CAC9B,OACE,UAAU,QACV,UAAU,KAAA,MACT,OAAO,UAAU,YAAY,OAAO,UAAU,eAC/C,cAAe;AAEnB;;;;;;AAWA,SAAgB,iBAAoB,MAAuC;CACzE,OAAO;EACL,IAAI,UAAU;GACZ,OAAO;EACT;EACA,YAAY;GACV,aAAa,CAAC;EAChB;CACF;AACF;;;;;;;;;;;;;AAkBA,SAAgB,WACd,QACkB;CAClB,MAAM,WAAW,OAAO;CACxB,OAAO;GACJ,aAAa;EACd,IAAI,UAAa;GACf,OAAO,SAAS;EAClB;EACA,UAAU,UAAyD;GACjE,OAAO,SAAS,UAAU,QAAQ;EACpC;CACF;AACF;;;;;;;;;;;;;;;;AAqBA,SAAgB,iBACd,YACmE;CACnE,MAAM,8BAAc,IAAI,IAAuC;CAE/D,MAAM,WAAqC;EACzC,IAAI,UAAa;GACf,OAAO,WAAW;EACpB;EACA,UAAU,UAAyD;GACjE,YAAY,IAAI,QAAQ;GACxB,aAAa;IACX,YAAY,OAAO,QAAQ;GAC7B;EACF;CACF;CAEA,MAAM,OAAyB;GAC5B,aAAa;EACd,IAAI,UAAa;GACf,OAAO,WAAW;EACpB;EACA,UAAU,UAAyD;GACjE,OAAO,SAAS,UAAU,QAAQ;EACpC;CACF;CAEA,MAAM,QAAQ,cAAkC;EAC9C,KAAK,MAAM,MAAM,aACf,GAAG,SAAS;CAEhB;CAEA,OAAO,CAAC,MAAM,IAAI;AACpB;;;;;;;;;;;;;;;;;;;;;AC/MA,SAAgB,eACd,MAC0B;CAC1B,MAAM,iBAAsB,KAAK;CAGjC,OAAO,eAAe,UAAU,YAAY;EAC1C,MAAgC;GAC9B,OAAO,KAAK;EACd;EACA,YAAY;EACZ,cAAc;CAChB,CAAC;CAGD,OAAO,eAAe,UAAU,WAAW;EACzC,MAAS;GACP,OAAO,KAAK;EACd;EACA,YAAY;EACZ,cAAc;CAChB,CAAC;CAGD,SAAS,aACP,aACiB;EACjB,OAAO,KAAK,UAAU,QAAQ;CAChC;CAEA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;ACcA,SAAgB,oBAGd;CACA,MAAM,sBAAM,IAAI,IAAU;CAQ1B,MAAM,CAAC,MAAM,QAAQ,uBACb,IAAI,IAAI,GAAG,CACnB;CAKA,MAAM,iBAAsB,IAAI,IAAI,GAAG;CAIvC,OAAO,eAAe,UAAU,YAAY;EAC1C,MAAgD;GAC9C,OAAO,KAAK;EACd;EACA,YAAY;EACZ,cAAc;CAChB,CAAC;CAED,OAAO,eAAe,UAAU,WAAW;EACzC,MAAyB;GACvB,OAAO;EACT;EACA,YAAY;EACZ,cAAc;CAChB,CAAC;CAED,SAAS,aACP,aACiB;EACjB,OAAO,KAAK,UAAU,QAAQ;CAChC;CAIA,SAAS,OAAO,QAA0B,IAAI,IAAI,GAAG;CACrD,SAAS,OAAO,QAAoB,IAAI,IAAI,GAAG;CAC/C,SAAS,aAAkC,IAAI,KAAK;CAEpD,OAAO,eAAe,UAAU,QAAQ;EACtC,MAAc;GACZ,OAAO,IAAI;EACb;EACA,YAAY;EACZ,cAAc;CAChB,CAAC;CAED,SAAS,OAAO,kBACd,IAAI,OAAO,UAAU;CAiBvB,OAAO,CAAC,UAAkC;EAZxC,IAAI,KAAQ,OAAgB;GAC1B,IAAI,IAAI,KAAK,KAAK;EACpB;EACA,OAAO,KAAiB;GACtB,OAAO,IAAI,OAAO,GAAG;EACvB;EACA,QAAc;GACZ,IAAI,MAAM;EACZ;EACA;CAG6C,CAAC;AAClD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kyneta/changefeed",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "description": "Universal reactive contract — a Moore machine identified by [CHANGEFEED]",
   "author": "Duane Johnson",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "./src/*": "./src/*"
   },
   "devDependencies": {
-    "tsdown": "^0.21.9",
+    "tsdown": "^0.22.0",
     "typescript": "^5.9.2",
     "vitest": "^4.0.17"
   },

package/src/changefeed.ts

@@ -41,9 +41,14 @@ export const CHANGEFEED: unique symbol = Symbol.for("kyneta:changefeed") as any
  *
  * - Auto-commit produces a degenerate changeset of one change.
  * - Transactions and `applyChanges` produce multi-change batches.
- * - `origin` carries provenance for the entire batch (e.g. "sync",
- *   "undo", "local"). Individual changes do not carry provenance —
- *   the batch does.
+ * - `origin` is an *application-level label* — opaque to the framework.
+ *   Apps may use it freely (`"sync"`, `"undo"`, `"local"`, anything).
+ *   The schema package and the exchange never branch on its value.
+ * - `replay` is a *structural directive* set by kyneta-internal layers.
+ *   `true` iff the batch represents state authored elsewhere (substrate
+ *   event bridge, `merge` payload, version travel). Layered consumers
+ *   (e.g. the exchange's echo filter) use `replay` to discriminate
+ *   "echo from sync" from "local write" without piggy-backing on origin.
  *
  * The subscriber API always receives a `Changeset`, making it uniform
  * regardless of how the changes were produced.
@@ -51,8 +56,11 @@ export const CHANGEFEED: unique symbol = Symbol.for("kyneta:changefeed") as any
 export interface Changeset<C = ChangeBase> {
   /** The individual changes in this batch. */
   readonly changes: readonly C[]
-  /** Provenance of the batch (e.g. "sync", "undo", "local"). */
+  /** App-level provenance label (e.g. "sync", "undo", "local"). */
   readonly origin?: string
+  /** Structural: true iff this batch is replaying state authored
+   *  elsewhere (substrate event bridge, merge payload). */
+  readonly replay?: boolean
 }
 
 // ---------------------------------------------------------------------------