@thomasfosterau/legation-devtools 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,319 @@
+# @thomasfosterau/legation-devtools
+
+## 0.1.0
+
+### Minor Changes
+
+- fc880dc: Ship `@thomasfosterau/legation-devtools` (#120): a devtools panel over the introspection
+  substrate — journal & mutation timeline, subscriptions & collections (with
+  row counts and the pull cookie), a sync activity log, and actions (force
+  pull/push, a simulated-offline toggle, drop a subscription, and a destructive
+  clear-store behind a confirm).
+
+  Architecture: a framework-agnostic headless core built entirely over
+  already-public substrate (`Introspection`, `ClientEngine.mutationStates`,
+  `engineEvents`/`syncFailures`, `ClientStore`), with thin per-framework panels
+  — `@thomasfosterau/legation-devtools/react` and `@thomasfosterau/legation-devtools/svelte` — as separate,
+  lazily-loadable entry points so an app that never imports them pays nothing
+  for the panel in production. This is a functional first cut: plain, legible
+  markup; visual polish is deliberately out of scope.
+
+  Scoped to the owned-engine case (an app that constructs its own `ClientEngine`
+
+  - `ClientStore` in-process); attaching over the mirror seam needs a
+    mirror-protocol introspection extension, tracked separately (#136).
+
+  Demonstrated in `examples/northwind`.
+
+- 5496ddf: Bump the pinned Effect version from `4.0.0-beta.84` to `4.0.0-beta.107` across
+  all packages (catalog and exact `peerDependencies`), and move
+  `@thomasfosterau/legation-jsonapi` and the commerce example from
+  `@thomasfosterau/effect-jsonapi@^0.6.0` to `^0.12.0` (#152).
+
+  **Why beta.107.** effect-jsonapi 0.12 requires `effect >= 4.0.0-beta.104` and
+  develops against `4.0.0-beta.107` exactly, so that is the version its typings
+  are known to line up with. The later `4.0.0-rc.*` releases were not attempted
+  in this change: the exact-pin policy (ADR-0003) prefers the version the
+  adopted library is built against, and every `effect/unstable/*` module this
+  repo uses (`httpapi`, `http`, `rpc`, `reactivity`, `persistence`, `sql`)
+  compiles and tests clean on beta.107.
+
+  **Effect API drift absorbed (no behavioural change):**
+
+  - `Schedule.either` / `Schedule.both` are gone; the default retry policy is now
+    `Schedule.max([Schedule.min([exponential, spaced]), recurs(5)])`, which is
+    the same policy (`min` recurs while any schedule recurs at the shortest
+    delay, `max` recurs while all recur at the longest delay).
+  - `Schema.TaggedErrorClass` is now `Schema.TaggedError` (the wire
+    `SyncRpcError` is unchanged on the wire).
+  - `SchemaRepresentation.fromASTs` is now `SchemaRepresentation.toRepresentations`
+    (spec export output is unchanged).
+  - `HttpApiGroup.Any` is gone and `HttpApi`'s group parameter is now
+    invariant, so `JsonApiSync.layer`, `JsonApiSync.inspect` and
+    `Convention.reflectResources` are generic over the concrete `HttpApi`
+    instead of accepting a widened alias. The exported `JsonApiSync.JsonApi`
+    alias is now `HttpApi.Constraint` (identifier and groups erased); pass your
+    concrete api to the functions rather than annotating it with the alias.
+
+  **effect-jsonapi 0.6 → 0.12 at the ADR-0016 boundary.** `Document`, `Query`,
+  `Resource`, `Relationship` and `Endpoint` lost no exports; `Query` gained
+  `IncludeOption`/`IncludePathsOf`/`OffsetPageStruct`/`bracketPageKeys` and
+  `Resource` gained `IncludeDepth`/`IncludePathsTo`. `schema.ts`, `types.ts` and
+  `CollectionLoader.ts` compile unchanged. One typing regression was noticed in
+  0.12: endpoints with `:id` params (`Endpoint.get`/`delete`/`update`) declare
+  their params as `Schema.Struct<Schema.Struct.Fields & { id }>`, which leaks
+  `unknown` into the requirements of the corresponding `HttpApiClient` calls.
+  The commerce example narrows this with a small `run` helper in
+  `server/client.ts`; nothing in the published packages is affected.
+
+  The bump is `minor` rather than `patch` because the exact `effect` peer pin
+  means every consumer must move `effect` in the same change, and the
+  `@thomasfosterau/legation-jsonapi` type signatures above changed shape.
+
+- fed4634: Peer the Effect v4 release-candidate line through an open floor rather than
+  an exact pin (#222), so an app can install `@thomasfosterau/legation-*` beside
+  `@thomasfosterau/effect-auth` and `@thomasfosterau/effect-jsonapi` and resolve
+  a single copy of `effect`. The published floor is `>=4.0.0-rc.118` (see
+  `effect-rc118-floor.md`), on `effect` and on the `@effect/platform-browser` /
+  `@effect/platform-node` peers.
+
+  **`@thomasfosterau/legation-jsonapi`**: a repeated shorthand filter key
+  (`?filter[name]=a&filter[name]=b`) is read as the comma list it spells
+  (`filter[name]=a,b`, an `In` predicate) rather than rejected with a 400,
+  because `@thomasfosterau/effect-jsonapi` accepts the repeated-key spelling at
+  every list-valued position.
+
+  The packages run in browsers and workers and deliberately declare no `engines`
+  (ADR-0003).
+
+- fcc52eb: Target Effect `4.0.0-rc.118`: every package peers `effect >=4.0.0-rc.118`
+  (#261), and the `@effect/platform-browser` / `@effect/platform-node` peers use
+  the same floor. Install `effect` and every `@effect/*` companion at
+  `4.0.0-rc.118` or later together.
+
+  The packages import Effect's modules at their rc.118 paths (`effect/rpc`,
+  `effect/http`, `effect/http-api`, …); rc.118 removed the `effect/unstable/*`
+  export paths, so the packages don't resolve beside an earlier `effect`.
+
+  **`@thomasfosterau/legation-jsonapi`** depends on `@thomasfosterau/effect-jsonapi@^0.16.1`,
+  the first release that peers `effect >=4.0.0-rc.118`.
+
+  **`@thomasfosterau/legation-svelte`** depends on `@thomasfosterau/effect-svelte@^0.4.0`, for
+  the same reason.
+
+- 3538a81: Depend on the engine core under its new name, `@thomasfosterau/legation` (formerly `@thomasfosterau/legation-effect`), and its engine seams at `@thomasfosterau/legation/internal`. Install `@thomasfosterau/legation` alongside these packages and import the core from it.
+- 16889f0: Rename every package from the `@legation/*` scope to
+  `@thomasfosterau/legation-*` (#303): `@legation/effect` is now
+  `@thomasfosterau/legation`, and likewise for `browser`, `cloudflare`,
+  `devtools`, `jsonapi`, `node`, `sql` and `svelte`. Subpath entries keep their
+  paths (`@thomasfosterau/legation/internal`,
+  `@thomasfosterau/legation-svelte/kit`,
+  `@thomasfosterau/legation-devtools/svelte`). Update imports and dependency
+  names accordingly; no `@legation/*` name was ever published to npm.
+
+  `Context.Service` identifiers and `Symbol.for` keys follow the package name
+  (`@legation/effect/Client` → `@thomasfosterau/legation/Client`, and
+  per-package equivalents). The reserved identity sentinels
+  (`@legation/anonymous`, `@legation/unstamped`), the `legation/` client-store
+  prefixes, metric and span names are unchanged.
+
+### Patch Changes
+
+- 7b21d11: The `clearStore` action now clears through the running engine (`ClientEngine.clearRows`). It previously cleared the store directly, so the engine's view kept showing the cleared rows until something else invalidated it.
+- 99edbe2: Correct the package description: the devtools ship one framework panel, the Svelte one on `@thomasfosterau/legation-devtools/svelte`. There is no React panel.
+- 40d28f3: Fix the types of the `@thomasfosterau/legation-devtools/svelte` entry in the published
+  package. `svelte/store.ts` and `DevtoolsPanel.svelte` (shipped as source)
+  imported their `DevtoolsCore` types from `../src/Devtools.js`, which is not in
+  the tarball, so a consumer's type check couldn't resolve them. They now import
+  them from `@thomasfosterau/legation-devtools`, the package's own root entry.
+- ae18cb3: Add a one-sentence doc comment to every exported declaration that had none, so editor hovers on the published `.d.ts` say what each export is for. This covers the root `@thomasfosterau/legation` surface (`Backend`, `Server`, `ClientStore`, the `Predicate` and `Aggregate` constructors, …), its `/internal` seams, and the options and config interfaces of the other packages. The `@thomasfosterau/legation` module header now counts seven concepts (Hydration joined ADR-0022's six). Documentation only; no API or behaviour changes.
+- d1b01a4: Tested against `effect` 4.0.0 (and the matching `@effect/*` companions); the
+  peer floor is unchanged at `effect >=4.0.0-rc.118`.
+
+  `@thomasfosterau/legation` adapts to 4.0.0's stricter, type-only `Schema.brand`:
+
+  - `Node.Id` keeps its signature and runtime behaviour; its internal brand
+    identifier is cast to satisfy the new concrete-identifier check.
+  - `Node.AnyNode`'s `Id` property is now
+    `Schema.Codec<string & Brand.Brand<string>, string>` instead of `Id<string>`.
+    4.0.0's `brand<String, B>` is type-only and no longer assignable to a wider
+    ``brand<String, `${string}/id`>``, so no concrete `Node<"todos", …>` was
+    assignable to `AnyNode`. Every concrete node is assignable again, and `Id`
+    is still a string-encoded branded id schema; only code that reads `.Id` off
+    an `AnyNode`-typed value sees the wider brand.
+
+  Checked the 4.0.0 behavioural changes against the packages and found no impact:
+  no use of `partition`/`separate`/`Option.partitionMap`, `Queue.State`,
+  `MessageStorage` or `RpcMessage.ExitEncoded`. The RPC client's missed-pong
+  handling now fails in-flight WebSocket calls rather than reporting a transient
+  error; `RpcTransport.fromOrigin` already treats a failed WebSocket call as a
+  `TransportError` and falls back to HTTP. The RPC server's WebSocket route now
+  closes with 1000/1001/1011, which nothing in the packages inspects.
+
+- c5d3484: README: the `effect` floor (`4.0.0-rc.118`) is now tested on every pull
+  request, where CI runs the test suite against it, instead of in a weekly
+  canary. The peer range (`effect >=4.0.0-rc.118`) and the tested pin (`4.0.0`)
+  are unchanged.
+- e9363c0: Peer `effect ^4.0.0` (was `>=4.0.0-rc.118`), and `@effect/platform-node` /
+  `@effect/platform-browser` `^4.0.0` likewise, per the peer-range policy: the
+  range is raised only when a dependency requires it. The range form changes
+  (the caret no longer admits the 4.0 release candidates or Effect 5); every
+  package's tests pass at `effect` 4.0.0.
+
+  `@thomasfosterau/legation-svelte` peers `effect ^4.0.2`: its dependency
+  `@thomasfosterau/effect-svelte` 0.6.0 peers `effect >=4.0.2`.
+
+- 97cc5f9: Build with `vp pack` (tsdown) instead of `tsc --build`. Each entry point is now one ESM bundle with one declaration file (the two `@thomasfosterau/legation` entries share a chunk, so a value reached through `.` and `./internal` is still one instance). The `exports` map, entry file names and published dependency and peer ranges are unchanged, and nothing from npm is bundled. The source also moved to the Effect lint presets' idioms (namespace imports from `effect/*` submodules, `effect/Predicate` guards, tag-exact error recovery); behaviour is unchanged.
+- Updated dependencies [2a1f63c]
+- Updated dependencies [ef59fa7]
+- Updated dependencies [56a2e51]
+- Updated dependencies [d09dc65]
+- Updated dependencies [db2366a]
+- Updated dependencies [97db489]
+- Updated dependencies [cc67999]
+- Updated dependencies [a94df19]
+- Updated dependencies [d76b04d]
+- Updated dependencies [6f53fb1]
+- Updated dependencies [d675d2e]
+- Updated dependencies [1743c2b]
+- Updated dependencies [1c56914]
+- Updated dependencies [615e792]
+- Updated dependencies [c8d9afc]
+- Updated dependencies [4709f41]
+- Updated dependencies [f0348b4]
+- Updated dependencies [3e29e1b]
+- Updated dependencies [a053736]
+- Updated dependencies [8a8adfc]
+- Updated dependencies [8995115]
+- Updated dependencies [8995115]
+- Updated dependencies [87fa7a5]
+- Updated dependencies [822001c]
+- Updated dependencies [4c59860]
+- Updated dependencies [961e604]
+- Updated dependencies [5937efe]
+- Updated dependencies [08ac9cd]
+- Updated dependencies [1fc3725]
+- Updated dependencies [8995115]
+- Updated dependencies [8a8adfc]
+- Updated dependencies [025fabb]
+- Updated dependencies [0b8fccb]
+- Updated dependencies [e7369e1]
+- Updated dependencies [8995115]
+- Updated dependencies [c856d66]
+- Updated dependencies [01a8c64]
+- Updated dependencies [3362c37]
+- Updated dependencies [62dcb1c]
+- Updated dependencies [be4be06]
+- Updated dependencies [ae18cb3]
+- Updated dependencies [be0a44d]
+- Updated dependencies [cc2f5b7]
+- Updated dependencies [e818dc4]
+- Updated dependencies [d1b01a4]
+- Updated dependencies [5496ddf]
+- Updated dependencies [19eb4b0]
+- Updated dependencies [a874acb]
+- Updated dependencies [c5d3484]
+- Updated dependencies [38c3147]
+- Updated dependencies [e9363c0]
+- Updated dependencies [fed4634]
+- Updated dependencies [fcc52eb]
+- Updated dependencies [454e75c]
+- Updated dependencies [2003cd6]
+- Updated dependencies [52c614f]
+- Updated dependencies [94d6327]
+- Updated dependencies [91f07db]
+- Updated dependencies [6e9e119]
+- Updated dependencies [6c2c802]
+- Updated dependencies [ebcc6aa]
+- Updated dependencies [a1b95d4]
+- Updated dependencies [c105fbf]
+- Updated dependencies [e1a028a]
+- Updated dependencies [dfb8759]
+- Updated dependencies [9260efb]
+- Updated dependencies [0644af5]
+- Updated dependencies [4b05d55]
+- Updated dependencies
+- Updated dependencies [82911cc]
+- Updated dependencies [9c9f2b0]
+- Updated dependencies [7b21d11]
+- Updated dependencies [6f54de8]
+- Updated dependencies [ab1fb4e]
+- Updated dependencies [792d8f5]
+- Updated dependencies [a3b2ee4]
+- Updated dependencies [eb9555a]
+- Updated dependencies [c0ab703]
+- Updated dependencies [8c65627]
+- Updated dependencies [26ad3f3]
+- Updated dependencies [d7cafd2]
+- Updated dependencies [cb0a33d]
+- Updated dependencies [912d95d]
+- Updated dependencies [7290d2b]
+- Updated dependencies [41c33e3]
+- Updated dependencies [a77261c]
+- Updated dependencies [c47786c]
+- Updated dependencies [501b12c]
+- Updated dependencies [7f1efac]
+- Updated dependencies [a04918b]
+- Updated dependencies [cf0b26c]
+- Updated dependencies [ddb1fda]
+- Updated dependencies [f54f568]
+- Updated dependencies [fc880dc]
+- Updated dependencies [9cbd160]
+- Updated dependencies [0bebedf]
+- Updated dependencies [bc4c599]
+- Updated dependencies [20a6e18]
+- Updated dependencies [b4d2b80]
+- Updated dependencies [2201b4c]
+- Updated dependencies [0cdefe7]
+- Updated dependencies [66f3b5b]
+- Updated dependencies [7e11e61]
+- Updated dependencies [6175e38]
+- Updated dependencies [caf4761]
+- Updated dependencies [821b10d]
+- Updated dependencies [9e74a83]
+- Updated dependencies [49fd066]
+- Updated dependencies [06405ed]
+- Updated dependencies [e7f4871]
+- Updated dependencies [916d91b]
+- Updated dependencies [47f4e15]
+- Updated dependencies [f829146]
+- Updated dependencies [13658a7]
+- Updated dependencies [31cfb2c]
+- Updated dependencies [a1cea1c]
+- Updated dependencies [7e94abc]
+- Updated dependencies [4fbd0b7]
+- Updated dependencies [9d2f21b]
+- Updated dependencies [3016170]
+- Updated dependencies [f4a1a60]
+- Updated dependencies [507ccb1]
+- Updated dependencies [c671ccf]
+- Updated dependencies [16889f0]
+- Updated dependencies [fb2a992]
+- Updated dependencies [22f320d]
+- Updated dependencies [652ae7b]
+- Updated dependencies [83bcf76]
+- Updated dependencies [20e57d3]
+- Updated dependencies [f010749]
+- Updated dependencies [8d02113]
+- Updated dependencies [bf9054d]
+- Updated dependencies [e40c73a]
+- Updated dependencies [ca38874]
+- Updated dependencies [27e1040]
+- Updated dependencies [e68eb3e]
+- Updated dependencies [985c4d5]
+- Updated dependencies [3be5abc]
+- Updated dependencies [97db489]
+- Updated dependencies [4a23603]
+- Updated dependencies [f441941]
+- Updated dependencies [a01f43b]
+- Updated dependencies [9a6426b]
+- Updated dependencies [97cc5f9]
+- Updated dependencies [fc880dc]
+- Updated dependencies [e34bc24]
+- Updated dependencies [0470e1c]
+- Updated dependencies [439f449]
+- Updated dependencies [3a88118]
+- Updated dependencies [1b8b120]
+- Updated dependencies [cf48723]
+- Updated dependencies [b4489c5]
+  - @thomasfosterau/legation@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Foster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @thomasfosterau/legation-devtools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A devtools panel over the introspection substrate (#120): the journal &
+mutation timeline, subscriptions & collections, sync activity log, and
+actions (force pull/push, a simulated-offline toggle, drop a subscription,
+and a destructive clear-store behind a confirm).
+
+Architecture: a framework-agnostic headless core (`@thomasfosterau/legation-devtools`) that
+owns all data acquisition — built entirely over already-public substrate
+(`@thomasfosterau/legation/internal`'s `Introspection`, `ClientEngine.mutationStates`,
+`ClientEngine.engineEvents`/`syncFailures`, `ClientStore`) — plus thin,
+idiomatic panels per framework — today `@thomasfosterau/legation-devtools/svelte`. A panel
+just runs the core's Effects/Streams through its own framework's reactivity;
+it has no data-acquisition path of its own.
+
+This is a **functional first cut**: plain, legible, correct. Visual polish is
+out of scope — a human design pass comes later.
+
+## Install
+
+```sh
+npm install @thomasfosterau/legation-devtools @thomasfosterau/legation effect
+```
+
+Add `svelte` (an optional peer, `>=5.40`) for the `@thomasfosterau/legation-devtools/svelte` panel.
+
+## Effect version
+
+Peers `effect ^4.0.0`. Tested against `4.1.2` (the version CI pins) and `4.0.0` (the floor; CI runs the tests against it on every PR); install one copy of `effect` in your app (ADR-0003).
+
+## Scope
+
+The owned-engine case only: an app that constructs its own `ClientEngine` +
+`ClientStore` in-process (see `examples/northwind`).
+Attaching over the mirror seam (a service-worker-hosted engine) needs a
+mirror-protocol introspection extension that doesn't exist yet — tracked as a
+follow-up substrate issue (#136).
+
+## Usage
+
+```ts
+import * as Devtools from "@thomasfosterau/legation-devtools";
+
+// `engine`/`store` are the same values you provided to `ClientEngine.make`.
+const devtools = Devtools.make(engine, store, {
+  // Optional: wires the "simulated offline" action. Build `offline` with
+  // `Transport.simulateOffline` and wrap your real transport with it.
+  offline: { setOffline, isOffline },
+});
+```
+
+Svelte:
+
+```svelte
+<script lang="ts">
+  import { DevtoolsPanel } from "@thomasfosterau/legation-devtools/svelte";
+</script>
+
+<DevtoolsPanel core={devtools} />
+```
+
+The `/svelte` entry point is a separate export so an app that never imports
+it pays nothing for the panel in its production bundle. The headless core is
+framework-agnostic — a binding for another framework is a component over the
+same `DevtoolsCore`.
+
+Note: `@thomasfosterau/legation-devtools/svelte` ships raw `.svelte`/`.ts` source (not a
+pre-compiled bundle) — any Svelte 5 app already has a bundler that compiles
+`.svelte` files, so this composes directly with your app's own build.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import * as Effect from "effect/Effect";
+import { ClientEngine, MutationState, Subset } from "@thomasfosterau/legation/internal";
+import * as Stream from "effect/Stream";
+import { ClientStore, StoreError } from "@thomasfosterau/legation";
+/** One collection's name plus its confirmed row count, for the subscriptions
+ * & collections panel's "rows in window" summary. */
+export interface CollectionSummary {
+  readonly name: string;
+  readonly rowCount: number;
+}
+/**
+ * The optional simulated-offline control (built by `Transport.simulateOffline`
+ * and wired into the app's transport at boot) — the devtools actions panel's
+ * offline toggle. Omitted when the app never wired a toggleable transport, in
+ * which case the panel simply doesn't render that action.
+ */
+export interface OfflineControl {
+  readonly setOffline: (offline: boolean) => Effect.Effect<void>;
+  readonly isOffline: Effect.Effect<boolean>;
+}
+/** Options for {@link make}. */
+export interface DevtoolsOptions {
+  readonly offline?: OfflineControl;
+}
+/** The devtools headless core: one instance per engine, shared by every panel mounted over it. */
+export interface DevtoolsCore {
+  /** The keyed, reactive mutation-state map (#116): re-emits on every fold. */
+  readonly mutationStates: Stream.Stream<MutationState.MutationStateMap>;
+  /** Active subsets: collection, predicate, order, and window (limit/cursor). */
+  readonly subscriptions: Effect.Effect<ReadonlyArray<Subset.Subset>>;
+  /** The current pull cookie, or `undefined` before the first pull. */
+  readonly cookie: Effect.Effect<string | undefined, StoreError>;
+  /** Every collection currently holding confirmed rows, with its row count. */
+  readonly collections: Effect.Effect<ReadonlyArray<CollectionSummary>, StoreError>;
+  /** The unified sync-lifecycle event stream (push/pull/poke/mutation/rebuild). */
+  readonly events: Stream.Stream<ClientEngine.EngineEvent>;
+  /** Terminal sync failures (retry exhausted) — the "last error" surface. */
+  readonly syncFailures: Stream.Stream<ClientEngine.SyncFailure>;
+  /** Push the journal now. */
+  readonly forcePush: ClientEngine.ClientEngine["push"];
+  /** Pull a patch now and rebase. */
+  readonly forcePull: ClientEngine.ClientEngine["pull"];
+  /** Drop an active subscription. */
+  readonly dropSubscription: (subset: Subset.Subset) => Effect.Effect<void>;
+  /** Destructive: clear every confirmed row from the store. Gate behind a confirm in the UI. */
+  readonly clearStore: Effect.Effect<void, StoreError>;
+  /** The simulated-offline toggle, if the app wired one — see {@link OfflineControl}. */
+  readonly offline?: OfflineControl;
+}
+/** Build the devtools core over a running engine + its store. */
+export declare const make: (engine: ClientEngine.ClientEngine, store: ClientStore.ClientStore, options?: DevtoolsOptions) => DevtoolsCore;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Devtools.ts"],"mappings":";;;;;;iBAuCiB;WACN;WACA;;;;;;;;iBASM;WACN,aAAa,qBAAqB,OAAO;WACzC,WAAW,OAAO;;;iBAIZ;WACN,UAAU;;;iBAIJ;;WAGN,gBAAgB,OAAO,OAAO,cAAc;;WAI5C,eAAe,OAAO,OAAO,cAAc,OAAO;;WAElD,QAAQ,OAAO,2BAA2B;;WAE1C,aAAa,OAAO,OAAO,cAAc,oBAAoB;;WAI7D,QAAQ,OAAO,OAAO,aAAa;;WAEnC,cAAc,OAAO,OAAO,aAAa;;WAIzC,WAAW,aAAa;;WAExB,WAAW,aAAa;;WAExB,mBAAmB,QAAQ,OAAO,WAAW,OAAO;;WAEpD,YAAY,OAAO,aAAa;;WAEhC,UAAU;;;qBAIR,OACX,QAAQ,aAAa,cACrB,OAAO,YAAY,aACnB,UAAU,oBACT"}

package/dist/index.js

@@ -0,0 +1,54 @@
+import * as Effect from "effect/Effect";
+import { Introspection } from "@thomasfosterau/legation/internal";
+// src/Devtools.ts
+/**
+* Devtools
+*
+* The headless core over the introspection substrate (#120): all data
+* acquisition and every action live here as plain `Effect`/`Stream` values —
+* the same surfaces `@thomasfosterau/legation-svelte` already exposes bindings over — so a
+* framework panel (`@thomasfosterau/legation-devtools/svelte`) is a thin idiomatic UI over
+* one shared, tested read model, never its own data-acquisition path.
+*
+* Fed exclusively by already-public substrate (the `@thomasfosterau/legation/internal`
+* entrypoint, the same one `@thomasfosterau/legation-svelte` itself depends on):
+* `Introspection` (subscriptions, cookie, collections),
+* `ClientEngine.mutationStates` (#116, the journal/mutation timeline —
+* including the `"dropped"` phase paced compaction settles a compacted entry
+* to, so a devtools timeline never shows a phantom in-flight mutation),
+* `ClientEngine.engineEvents` (the sync activity log), and
+* `ClientEngine.syncFailures`. Nothing here reaches into engine-private
+* state; a capability this core would need that isn't already exposed there
+* is substrate work, not a private hook.
+*
+* Scope: the owned-engine case only — an app that constructed its own
+* `ClientEngine` + `ClientStore` in this process. Attaching over the mirror
+* seam (a service-worker-hosted engine, ADR-0010/0021) needs a
+* mirror-protocol introspection extension that does not exist yet; that is
+* substrate work for a follow-up issue, not something this package works
+* around with a private hook of its own.
+*/
+/** Build the devtools core over a running engine + its store. */
+const make = (engine, store, options) => {
+	const introspection = Introspection.make(engine, store);
+	const collections = introspection.collections.pipe(Effect.flatMap((names) => Effect.forEach(names, (name) => store.listRows(name).pipe(Effect.map((rows) => ({
+		name,
+		rowCount: rows.length
+	}))))));
+	return {
+		mutationStates: engine.mutationStates,
+		subscriptions: introspection.subscriptions,
+		cookie: introspection.cookie,
+		collections,
+		events: introspection.events,
+		syncFailures: engine.syncFailures,
+		forcePush: engine.push,
+		forcePull: engine.pull,
+		dropSubscription: engine.unsubscribe,
+		clearStore: engine.clearRows,
+		...options?.offline === void 0 ? {} : { offline: options.offline }
+	};
+};
+export { make };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/Devtools.ts"],"sourcesContent":["/**\n * Devtools\n *\n * The headless core over the introspection substrate (#120): all data\n * acquisition and every action live here as plain `Effect`/`Stream` values —\n * the same surfaces `@thomasfosterau/legation-svelte` already exposes bindings over — so a\n * framework panel (`@thomasfosterau/legation-devtools/svelte`) is a thin idiomatic UI over\n * one shared, tested read model, never its own data-acquisition path.\n *\n * Fed exclusively by already-public substrate (the `@thomasfosterau/legation/internal`\n * entrypoint, the same one `@thomasfosterau/legation-svelte` itself depends on):\n * `Introspection` (subscriptions, cookie, collections),\n * `ClientEngine.mutationStates` (#116, the journal/mutation timeline —\n * including the `\"dropped\"` phase paced compaction settles a compacted entry\n * to, so a devtools timeline never shows a phantom in-flight mutation),\n * `ClientEngine.engineEvents` (the sync activity log), and\n * `ClientEngine.syncFailures`. Nothing here reaches into engine-private\n * state; a capability this core would need that isn't already exposed there\n * is substrate work, not a private hook.\n *\n * Scope: the owned-engine case only — an app that constructed its own\n * `ClientEngine` + `ClientStore` in this process. Attaching over the mirror\n * seam (a service-worker-hosted engine, ADR-0010/0021) needs a\n * mirror-protocol introspection extension that does not exist yet; that is\n * substrate work for a follow-up issue, not something this package works\n * around with a private hook of its own.\n */\nimport * as Effect from \"effect/Effect\";\nimport * as Stream from \"effect/Stream\";\nimport type { ClientStore, StoreError } from \"@thomasfosterau/legation\";\nimport {\n  Introspection,\n  type ClientEngine,\n  type MutationState,\n  type Subset,\n} from \"@thomasfosterau/legation/internal\";\n\n/** One collection's name plus its confirmed row count, for the subscriptions\n * & collections panel's \"rows in window\" summary. */\nexport interface CollectionSummary {\n  readonly name: string;\n  readonly rowCount: number;\n}\n\n/**\n * The optional simulated-offline control (built by `Transport.simulateOffline`\n * and wired into the app's transport at boot) — the devtools actions panel's\n * offline toggle. Omitted when the app never wired a toggleable transport, in\n * which case the panel simply doesn't render that action.\n */\nexport interface OfflineControl {\n  readonly setOffline: (offline: boolean) => Effect.Effect<void>;\n  readonly isOffline: Effect.Effect<boolean>;\n}\n\n/** Options for {@link make}. */\nexport interface DevtoolsOptions {\n  readonly offline?: OfflineControl;\n}\n\n/** The devtools headless core: one instance per engine, shared by every panel mounted over it. */\nexport interface DevtoolsCore {\n  // ─── Journal & mutation timeline (panel #1) ──────────────────────────────\n  /** The keyed, reactive mutation-state map (#116): re-emits on every fold. */\n  readonly mutationStates: Stream.Stream<MutationState.MutationStateMap>;\n\n  // ─── Subscriptions & collections (panel #2) ──────────────────────────────\n  /** Active subsets: collection, predicate, order, and window (limit/cursor). */\n  readonly subscriptions: Effect.Effect<ReadonlyArray<Subset.Subset>>;\n  /** The current pull cookie, or `undefined` before the first pull. */\n  readonly cookie: Effect.Effect<string | undefined, StoreError>;\n  /** Every collection currently holding confirmed rows, with its row count. */\n  readonly collections: Effect.Effect<ReadonlyArray<CollectionSummary>, StoreError>;\n\n  // ─── Sync activity (panel #3) ────────────────────────────────────────────\n  /** The unified sync-lifecycle event stream (push/pull/poke/mutation/rebuild). */\n  readonly events: Stream.Stream<ClientEngine.EngineEvent>;\n  /** Terminal sync failures (retry exhausted) — the \"last error\" surface. */\n  readonly syncFailures: Stream.Stream<ClientEngine.SyncFailure>;\n\n  // ─── Actions (panel #4) ──────────────────────────────────────────────────\n  /** Push the journal now. */\n  readonly forcePush: ClientEngine.ClientEngine[\"push\"];\n  /** Pull a patch now and rebase. */\n  readonly forcePull: ClientEngine.ClientEngine[\"pull\"];\n  /** Drop an active subscription. */\n  readonly dropSubscription: (subset: Subset.Subset) => Effect.Effect<void>;\n  /** Destructive: clear every confirmed row from the store. Gate behind a confirm in the UI. */\n  readonly clearStore: Effect.Effect<void, StoreError>;\n  /** The simulated-offline toggle, if the app wired one — see {@link OfflineControl}. */\n  readonly offline?: OfflineControl;\n}\n\n/** Build the devtools core over a running engine + its store. */\nexport const make = (\n  engine: ClientEngine.ClientEngine,\n  store: ClientStore.ClientStore,\n  options?: DevtoolsOptions\n): DevtoolsCore => {\n  const introspection = Introspection.make(engine, store);\n\n  const collections: Effect.Effect<\n    ReadonlyArray<CollectionSummary>,\n    StoreError\n  > = introspection.collections.pipe(\n    Effect.flatMap((names) =>\n      Effect.forEach(names, (name) =>\n        store\n          .listRows(name)\n          .pipe(Effect.map((rows): CollectionSummary => ({ name, rowCount: rows.length })))\n      )\n    )\n  );\n\n  return {\n    mutationStates: engine.mutationStates,\n    subscriptions: introspection.subscriptions,\n    cookie: introspection.cookie,\n    collections,\n    events: introspection.events,\n    syncFailures: engine.syncFailures,\n    forcePush: engine.push,\n    forcePull: engine.pull,\n    dropSubscription: engine.unsubscribe,\n    clearStore: engine.clearRows,\n    ...(options?.offline === undefined ? {} : { offline: options.offline }),\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,MAAa,QACX,QACA,OACA,YACiB;CACjB,MAAM,gBAAgB,cAAc,KAAK,QAAQ,KAAK;CAEtD,MAAM,cAGF,cAAc,YAAY,KAC5B,OAAO,SAAS,UACd,OAAO,QAAQ,QAAQ,SACrB,MACG,SAAS,IAAI,CAAC,CACd,KAAK,OAAO,KAAK,UAA6B;EAAE;EAAM,UAAU,KAAK;CAAO,EAAE,CAAC,CACpF,CACF,CACF;CAEA,OAAO;EACL,gBAAgB,OAAO;EACvB,eAAe,cAAc;EAC7B,QAAQ,cAAc;EACtB;EACA,QAAQ,cAAc;EACtB,cAAc,OAAO;EACrB,WAAW,OAAO;EAClB,WAAW,OAAO;EAClB,kBAAkB,OAAO;EACzB,YAAY,OAAO;EACnB,GAAI,SAAS,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS,QAAQ,QAAQ;CACvE;AACF"}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@thomasfosterau/legation-devtools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A devtools headless core over the introspection substrate (#120): journal/mutation timeline, subscriptions & collections, sync activity, and actions — with a Svelte panel on /svelte",
+  "keywords": [
+    "devtools",
+    "effect",
+    "introspection",
+    "react",
+    "svelte",
+    "sync-engine",
+    "typescript"
+  ],
+  "homepage": "https://github.com/thomasfosterau/legation/tree/trunk/packages/devtools#readme",
+  "bugs": {
+    "url": "https://github.com/thomasfosterau/legation/issues"
+  },
+  "license": "MIT",
+  "author": "Thomas Foster",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thomasfosterau/legation.git",
+    "directory": "packages/devtools"
+  },
+  "files": [
+    "dist",
+    "svelte",
+    "!svelte/tsconfig.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./svelte": {
+      "svelte": "./svelte/index.ts",
+      "types": "./svelte/index.ts",
+      "default": "./svelte/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@thomasfosterau/legation": "^0.1.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.1.2",
+    "effect": "4.1.2",
+    "svelte": "^5.57.3",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0",
+    "svelte": ">=5.40"
+  },
+  "peerDependenciesMeta": {
+    "svelte": {
+      "optional": true
+    }
+  }
 }

package/svelte/DevtoolsPanel.svelte

@@ -0,0 +1,169 @@
+<script lang="ts">
+  /**
+   * @thomasfosterau/legation-devtools/svelte — DevtoolsPanel
+   *
+   * A thin Svelte panel over the headless `DevtoolsCore` (#120): every
+   * section below just reads a store built by `store.ts` (which in turn
+   * just runs the core's Effects/Streams) — no data acquisition of its own.
+   * Visual polish is out of scope for this first cut: plain, legible markup.
+   */
+  import { untrack } from "svelte";
+  import * as Effect from "effect/Effect";
+  import * as Fiber from "effect/Fiber";
+  import * as HashMap from "effect/HashMap";
+  import * as Result from "effect/Result";
+  import type { DevtoolsCore } from "@thomasfosterau/legation-devtools";
+  import * as Stores from "./store.js";
+
+  const props: { core: DevtoolsCore } = $props();
+  // `core` is a stable singleton built once by the app's `createWorld`, the
+  // same as `App.svelte`'s own `world` prop; read it untracked so the
+  // one-time store wiring below isn't flagged as reading reactive state.
+  const core = untrack(() => props.core);
+
+  const { mutationStates, subscriptions, cookie, collections, events, syncFailures } =
+    Stores.makeStores(core);
+
+  const journalEntries = $derived(
+    [...HashMap.values($mutationStates)].toSorted((a, b) => b.mutationId - a.mutationId)
+  );
+  const pendingCount = $derived(journalEntries.filter((e) => e.phase === "pending").length);
+
+  // `JSON.stringify` throws on a cycle or a BigInt; the mutator name alone stands in then.
+  const summarise = (mutator: string, args: unknown): string =>
+    Result.getOrElse(
+      Result.try(() => `${mutator} ${JSON.stringify(args)}`),
+      () => mutator
+    );
+
+  let offline = $state<boolean | undefined>(undefined);
+
+  $effect(() => {
+    if (core.offline === undefined) return;
+    const fiber = Effect.runFork(
+      Effect.map(core.offline.isOffline, (value) => {
+        offline = value;
+      })
+    );
+    return () => {
+      Effect.runFork(Fiber.interrupt(fiber));
+    };
+  });
+
+  const toggleOffline = (): void => {
+    if (core.offline === undefined) return;
+    const next = !(offline ?? false);
+    void Effect.runPromise(core.offline.setOffline(next)).then(() => {
+      offline = next;
+    });
+  };
+
+  const forcePull = (): void => void Effect.runPromise(core.forcePull);
+  const forcePush = (): void => void Effect.runPromise(core.forcePush);
+  const dropSubscription = (subset: (typeof $subscriptions)[number]): void =>
+    void Effect.runPromise(core.dropSubscription(subset));
+  const clearStore = (): void => {
+    if (!confirm("Clear every confirmed row from the store? This cannot be undone.")) return;
+    void Effect.runPromise(core.clearStore);
+  };
+</script>
+
+<div>
+  <h2>Devtools</h2>
+
+  <section>
+    <h3>Journal &amp; mutations</h3>
+    <p>{pendingCount} pending, {journalEntries.length} total (newest first)</p>
+    {#if journalEntries.length === 0}
+      <p>Journal empty.</p>
+    {:else}
+      <ul>
+        {#each journalEntries as entry (entry.mutationId)}
+          <li>
+            <strong>{entry.phase}</strong> #{entry.mutationId}
+            {summarise(entry.mutator, entry.args)}
+            {#if entry.phase === "rejected" && entry.reason !== undefined}
+              — {entry.reason}
+            {/if}
+          </li>
+        {/each}
+      </ul>
+    {/if}
+  </section>
+
+  <section>
+    <h3>Subscriptions &amp; collections</h3>
+    <p>Cookie: {$cookie ?? "(none — no pull yet)"}</p>
+    <h4>Active subscriptions</h4>
+    {#if $subscriptions.length === 0}
+      <p>None.</p>
+    {:else}
+      <ul>
+        {#each $subscriptions as s, i (i)}
+          <li>
+            {s.collection} — where {JSON.stringify(s.where)}
+            {#if s.orderBy.length > 0}, order {JSON.stringify(s.orderBy)}{/if}
+            {#if s.limit !== undefined}, limit {s.limit}{/if}
+          </li>
+        {/each}
+      </ul>
+    {/if}
+    <h4>Collections</h4>
+    {#if $collections.length === 0}
+      <p>None synced yet.</p>
+    {:else}
+      <ul>
+        {#each $collections as c (c.name)}
+          <li>{c.name}: {c.rowCount} row{c.rowCount === 1 ? "" : "s"}</li>
+        {/each}
+      </ul>
+    {/if}
+  </section>
+
+  <section>
+    <h3>Sync activity</h3>
+    {#if $syncFailures.length === 0}
+      <p>No sync failures.</p>
+    {:else}
+      <p>
+        Last failure: {$syncFailures[$syncFailures.length - 1].operation} —
+        {String($syncFailures[$syncFailures.length - 1].error)}
+      </p>
+    {/if}
+    {#if $events.length === 0}
+      <p>No activity yet.</p>
+    {:else}
+      <ul>
+        {#each $events.toReversed() as event, i (i)}
+          <li>{JSON.stringify(event)}</li>
+        {/each}
+      </ul>
+    {/if}
+  </section>
+
+  <section>
+    <h3>Actions</h3>
+    <button type="button" onclick={forcePull}>Force pull</button>
+    <button type="button" onclick={forcePush}>Force push</button>
+    {#if core.offline !== undefined}
+      <button type="button" onclick={toggleOffline}>
+        {offline === true ? "Go online" : "Simulate offline"}
+      </button>
+    {/if}
+    <h4>Drop a subscription</h4>
+    {#if $subscriptions.length === 0}
+      <p>No active subscriptions.</p>
+    {:else}
+      <ul>
+        {#each $subscriptions as s, i (i)}
+          <li>
+            {s.collection}
+            <button type="button" onclick={() => dropSubscription(s)}>drop</button>
+          </li>
+        {/each}
+      </ul>
+    {/if}
+    <h4>Destructive</h4>
+    <button type="button" onclick={clearStore}>Clear store…</button>
+  </section>
+</div>

package/svelte/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @thomasfosterau/legation-devtools/svelte
+ *
+ * The Svelte panel entry point (#120): `DevtoolsPanel.svelte` is the thin
+ * UI, `store.ts` bridges the headless core's Effects/Streams to Svelte
+ * `Readable`s. Shipped as raw source — see `store.ts`'s module doc.
+ */
+export { default as DevtoolsPanel } from "./DevtoolsPanel.svelte";
+export * from "./store.js";

package/svelte/store.ts

@@ -0,0 +1,93 @@
+/**
+ * @thomasfosterau/legation-devtools/svelte — store adapters
+ *
+ * Bridges the headless {@link Devtools.DevtoolsCore} (#120) to Svelte
+ * `Readable` stores, the same shape `@thomasfosterau/legation-svelte`'s own `Query.ts`
+ * bridges live queries with: a store's `start` callback forks the source in
+ * a fiber and pushes each value through `set`; `stop` interrupts that fiber
+ * when the last subscriber unsubscribes. No data acquisition of its own —
+ * every store here just runs one of the core's Effects/Streams.
+ *
+ * Shipped as raw source (not pre-compiled): this subpath is consumed
+ * directly by a Svelte-aware bundler (any Svelte 5 app already has one), the
+ * same as the `.svelte` panel component alongside it.
+ */
+import { readable, type Readable } from "svelte/store";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as HashMap from "effect/HashMap";
+import * as Stream from "effect/Stream";
+import type { ClientEngine, MutationState, Subset } from "@thomasfosterau/legation/internal";
+import type * as Devtools from "@thomasfosterau/legation-devtools";
+
+/** Subscribe to a `Stream` as a store; `initial` until the first emission. */
+export const toStreamStore = <A>(stream: Stream.Stream<A>, initial: A): Readable<A> =>
+  readable<A>(initial, (set) => {
+    const fiber = Effect.runFork(Stream.runForEach(stream, (a) => Effect.sync(() => set(a))));
+    return () => {
+      Effect.runFork(Fiber.interrupt(fiber));
+    };
+  });
+
+/**
+ * Re-run a one-shot Effect snapshot whenever `signal` (a live Stream) emits,
+ * plus once on subscribe — see `react.tsx`'s `useSnapshot` for the same
+ * pattern and its rationale (the Introspection substrate's plain-Effect
+ * reads aren't Streams; `events` is the "something changed" trigger).
+ */
+export const toSnapshotStore = <A, E, S>(
+  effect: Effect.Effect<A, E>,
+  signal: Stream.Stream<S>,
+  initial: A
+): Readable<A> =>
+  readable<A>(initial, (set) => {
+    const safe = Effect.catch(effect, () => Effect.succeed(initial));
+    const refresh = Effect.runFork(Effect.map(safe, (a) => set(a)));
+    const fiber = Effect.runFork(Stream.runForEach(signal, () => Effect.map(safe, (a) => set(a))));
+    return () => {
+      Effect.runFork(Fiber.interrupt(refresh));
+      Effect.runFork(Fiber.interrupt(fiber));
+    };
+  });
+
+/** A capped rolling log of a Stream's emissions, newest last. */
+export const toLogStore = <A>(
+  stream: Stream.Stream<A>,
+  limit: number
+): Readable<ReadonlyArray<A>> =>
+  readable<ReadonlyArray<A>>([], (set) => {
+    let log: ReadonlyArray<A> = [];
+    const fiber = Effect.runFork(
+      Stream.runForEach(stream, (a) =>
+        Effect.sync(() => {
+          log = [...log, a].slice(-limit);
+          set(log);
+        })
+      )
+    );
+    return () => {
+      Effect.runFork(Fiber.interrupt(fiber));
+    };
+  });
+
+const EMPTY_STATES: MutationState.MutationStateMap = HashMap.empty();
+
+/** Devtools stores for one core instance — the panel's whole data surface. */
+export interface DevtoolsStores {
+  readonly mutationStates: Readable<MutationState.MutationStateMap>;
+  readonly subscriptions: Readable<ReadonlyArray<Subset.Subset>>;
+  readonly cookie: Readable<string | undefined>;
+  readonly collections: Readable<ReadonlyArray<Devtools.CollectionSummary>>;
+  readonly events: Readable<ReadonlyArray<ClientEngine.EngineEvent>>;
+  readonly syncFailures: Readable<ReadonlyArray<ClientEngine.SyncFailure>>;
+}
+
+/** Build every store the panel needs from one {@link Devtools.DevtoolsCore}. */
+export const makeStores = (core: Devtools.DevtoolsCore): DevtoolsStores => ({
+  mutationStates: toStreamStore(core.mutationStates, EMPTY_STATES),
+  subscriptions: toSnapshotStore(core.subscriptions, core.events, []),
+  cookie: toSnapshotStore(core.cookie, core.events, undefined as string | undefined),
+  collections: toSnapshotStore(core.collections, core.events, []),
+  events: toLogStore(core.events, 50),
+  syncFailures: toLogStore(core.syncFailures, 10),
+});