@owlmeans/client-planning 0.1.18-rc.0

package/README.md

@@ -0,0 +1,128 @@
+# @owlmeans/client-planning
+
+The client half of OwlMeans planning: a `PlanningFacade` over the protocol tree a server mounted
+with [`@owlmeans/server-planning`](../server-planning), an optional state mirror of cards, links and
+commits, and a commit wait that subscribes first and then long-polls. It is React-free, so the same
+code runs in a browser app and in a Node client. Use `@owlmeans/server-planning` instead wherever the
+planning service runs in-process.
+
+## Installation
+
+```bash
+bun add @owlmeans/client-planning@^0.1.18-rc.0
+```
+
+## Concepts
+
+- **Remote facade** — the same `PlanningFacade` interface the server answers; every method is one
+  entrypoint call, and `modelOf(record, facade)` models behave identically on both sides.
+- **One id space** — projects, cards and specifications share ONE card store; a list reaches it
+  through `syncCards(store, items, where)`, never `replace()`.
+- **Commit** — `execute()` returns a receipt for a pending transition; `receipt.committed()` /
+  `commits.wait()` resolve with the folded card, or throw `CommitTimeout` / `CommitFailed`.
+- **Socket seam** — the commit socket is opened by an injected `PlanningSocketOpener`; without one
+  the client long-polls.
+- **`head > seq`** — a card with a transition allocated and not yet folded; `applyReceipt` marks it
+  the moment the server answers.
+
+## Usage
+
+Wire the client into a context with the server's own tree:
+
+```typescript
+import { makePlanningProtocols } from '@owlmeans/planning'
+import { appendPlanningClient, appendPlanningStores } from '@owlmeans/client-planning'
+
+const planningProtocols = makePlanningProtocols({
+  base: { alias: 'app:api:planning', path: '/planning', service: API },
+  guards: DEFAULT_GUARD,
+})
+
+appendPlanningClient(context, { protocols: planningProtocols, poll: 20 })
+appendPlanningStores(context)
+```
+
+Read through the facade — rich queries, encoded for the wire by the package:
+
+```typescript
+const planning = context.planning().for()
+const { items } = await planning.cards.list({ parent: projectId, type: 'app:story', sort: ['order'], size: 0 })
+const counts = await planning.cards.summary([projectId])
+```
+
+Transit a card and wait for the commit:
+
+```typescript
+const story = await planning.model(items[0])
+if (story.can('start')) {
+  const card = await (await story.transit('start')).committed({ timeout: 15_000 })
+}
+```
+
+Keep a mirror current with one feed per screen:
+
+```typescript
+import { makePlanningFeed } from '@owlmeans/client-planning'
+
+const feed = makePlanningFeed(context, {
+  query: { parent: projectId }, filter: { project: projectId }, refresh: 15_000,
+})
+await feed.ready
+// … read context.planningStores().cards with useStoreList from @owlmeans/client
+await feed.stop()
+```
+
+Give a browser its commit socket through the host's own opener:
+
+```typescript
+appendPlanningClient(context, {
+  protocols: planningProtocols,
+  socket: async (protocol, request) => await ws(context.entrypoint(protocol), request),
+})
+```
+
+## API
+
+- `appendPlanningClient(context, options)`, `makePlanningClientService(context, options)`
+- `makeRemoteFacade(context, protocols, scope, opts)`, `makeRemoteCommitSource(context, protocols, opts?)`
+- `appendPlanningStores(context, aliases?)`, `planningStoresOf(context)`, `syncCards`, `syncLinks`
+- `applyCommitEvent(stores, event, facade?)`, `applyReceipt(stores, view)`, `applyCards(stores, cards)`
+- `makePlanningFeed(context, opts?)`
+- `planningOf(context, scope?)`, `planningModelOf(context, card, scope?)`
+- `CARDS`, `LINKS`, `COMMITS`, `DEFAULT_STORE_ALIASES`, `LONG_POLL_GRACE`, `EARLY_POLL_LADDER`, `EARLY_POLL_MS`
+- Types: `PlanningClientOptions`, `PlanningClientService`, `WithPlanningClient`,
+  `PlanningSocketOpener`, `RemoteCommitSource`, `RemoteCommitSourceOptions`, `RemoteFacadeOptions`,
+  `PlanningStores`, `PlanningStoreAliases`, `WithPlanningStores`, `PlanningCommitRecord`,
+  `SyncOptions`, `PlanningFeed`, `PlanningFeedOptions`, `PlanningFeedState`, `Config`, `Context`
+
+## Common pitfalls
+
+- The tree must match the server's alias for alias; a `socketBase` is the host's to bind.
+- Never `replace()` the card store — it holds every kind.
+- The scope passed to `for()` is advisory; the server takes the entity and actor from the credential.
+- `CommitTimeout` leaves the transition pending — re-wait or re-read, do not re-execute without a `key`.
+- A client refuses `store()`, `committed()` and plugins carrying hooks with `PlanningUnsupported`.
+- Mount one feed per screen; every other reader uses the store.
+
+## Related packages
+
+- [`@owlmeans/planning`](../planning) — records, flows, the fold, models, the protocol tree
+- [`@owlmeans/server-planning`](../server-planning) — the handlers, the executor, the memory store
+- [`@owlmeans/state`](../state) — the store the mirror is built on
+- [`@owlmeans/client`](../client) — `useStoreModel` / `useStoreList` over the mirror
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.27
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/client-planning",
+  "version": "0.1.18-rc.0",
+  "generatedAt": "2026-09-16T15:11:05.003Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "client-planning",
+      "category": "package-specific",
+      "file": "skills/client-planning/SKILL.md",
+      "canonicalPath": ".agents/skills/client-planning/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/client-planning/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: client-planning
+description: How to use @owlmeans/client-planning — appendPlanningClient for the remote planning facade, appendPlanningStores and applyCommitEvent for the state mirror, makePlanningFeed, commits.wait (subscribe then long-poll), and the models that are the same objects the server uses. Auto-invoked when reading planning data in a browser or a Node client, mounting the commit feed, or wiring optimistic transitions.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/client-planning
+
+**Layer:** Client
+**Install:** `"@owlmeans/client-planning": "^0.1.18-rc.0"` in `dependencies`
+
+The client half of OwlMeans planning. It answers the `PlanningFacade` interface of
+`@owlmeans/planning` over the protocol tree a server mounted with `@owlmeans/server-planning`, keeps
+an optional `@owlmeans/state` mirror of cards, links and commits current, and waits for commits.
+It is **React-free**: the same package runs in a browser app and in a Node client (a connector, a
+CLI). React hooks over the mirror are `useStoreModel` / `useStoreList` from `@owlmeans/client`.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `appendPlanningClient(context, options)` | Bind the tree, register the service under `PLANNING_SERVICE`, add `context.planning()` |
+| `makePlanningClientService(context, options)` | The service itself, for a host that registers it on its own |
+| `makeRemoteFacade(context, protocols, scope, opts)` | One facade — every method is one entrypoint call |
+| `makeRemoteCommitSource(context, protocols, opts?)` | `status` / `subscribe` / `wait` over `commit.get` and `commit.events` |
+| `appendPlanningStores(context, aliases?)` / `planningStoresOf(context)` | The state mirror, and a lookup that answers `null` without one |
+| `syncCards(store, items, where?, opts?)` / `syncLinks(...)` | Make the mirror agree with a list WITHIN a scope |
+| `applyCommitEvent(stores, event, facade?)` / `applyReceipt(stores, view)` / `applyCards(stores, cards)` | The folds |
+| `makePlanningFeed(context, opts?)` | Subscribe, seed, fold, refresh — `{ connected, seeded, error, ready, refresh, stop }` |
+| `planningOf(context, scope?)` / `planningModelOf(context, card, scope?)` | The facade / a model with the schemas loaded |
+| `CARDS`, `LINKS`, `COMMITS` | Store aliases (`planning-card-state`, `planning-link-state`, `planning-commit-state`) |
+| Types | `PlanningClientOptions`, `PlanningClientService`, `WithPlanningClient`, `PlanningSocketOpener`, `RemoteCommitSource`, `PlanningStores`, `PlanningStoreAliases`, `WithPlanningStores`, `PlanningCommitRecord`, `PlanningFeed`, `PlanningFeedOptions`, `PlanningFeedState`, `SyncOptions` |
+
+## Wiring
+
+```typescript
+import { makePlanningProtocols } from '@owlmeans/planning'
+import { appendPlanningClient, appendPlanningStores } from '@owlmeans/client-planning'
+
+export const planningProtocols = makePlanningProtocols({
+  base: { alias: 'app:api:planning', path: '/planning', service: API },
+  guards: DEFAULT_GUARD,
+  socketBase: updateBase,
+})
+
+appendPlanningClient(context, {
+  protocols: planningProtocols,
+  socket: async (protocol, request) => await ws(context.entrypoint(protocol), request),
+  poll: 20,
+})
+appendPlanningStores(context)        // a browser mirror; a Node client usually skips it
+```
+
+- The tree is **the server's tree** — the same `makePlanningProtocols` options, alias for alias.
+  Declare it once in the application's shared contract package and import it on both sides.
+- When the commit feed hangs under a `socketBase`, the HOST binds that base too. A parent a
+  registry cannot resolve fails the whole context at init, not the one call that uses it.
+- `bind: false` when the host already bound the tree.
+- The service answers under `PLANNING_SERVICE`, the alias the server's service uses, so
+  `context.planning().for(scope)` is the same call in a handler and in a screen. The scope is
+  **advisory**: the server takes the entity and the actor from the credential. The execution's own
+  `actor` is never sent.
+- A client runs no middleware and folds nothing: `store()`, `committed()` and a plugin carrying
+  `before`/`after`/`store`/`mintCode` answer `PlanningUnsupported`. `use()` accepts a schemas-only
+  plugin, layered over the server's bundle.
+- `timeout` (ms) bounds every call that is not a long poll; a long poll's deadline is its own hold
+  plus `LONG_POLL_GRACE`.
+
+### The schema bundle
+
+`model()` needs the flows and types (`can()`, `available()`, `statusOf()` read the registry with no
+round trip). The bundle is fetched in the background once the context is **Ready** and a failure
+there is swallowed — a browser that is not signed in yet cannot read it, and a context must never
+fail or wait over it. `model()` and `service.loadSchemas()` load it on first use regardless, and a
+failed load is retried by the next caller. `schemas: false` skips the background load.
+
+## Reading
+
+```typescript
+const planning = context.planning().for()
+
+const stories = await planning.cards.list({ parent: projectId, type: STORY, sort: ['order'], size: 0 })
+const board = await planning.cards.summary([projectId])
+const brief = await planning.specifications.current(projectId, 'specification')
+const story = await planning.model(storyId)
+story.available().map(rule => rule.name)
+```
+
+- The facade takes the rich `WorkcardQuery`; it encodes the scalar wire shape itself
+  (`encodeWorkcardQuery` and its twins). Never pass a wire shape to the facade.
+- `cards.load(id)` answers `null` for a missing card — and for another entity's card, which the
+  server deliberately reports the same way.
+- `cards.count(query)` is a one-row list read for its `total`; the tree declares no count route.
+- `transitions.list(query)` needs `card` — the tree reads the log through one card, so a
+  project-wide read answers `PlanningUnsupported` on a client.
+- `size: 0` is "no limit"; a paged server answers 100 rows when no size is asked for.
+
+## The mirror — one id space
+
+`appendPlanningStores` registers ONE card store for every kind. Projects, cards and specifications
+share an id space on the server, so they share one store here: a store per kind lets a card list
+that reloads drop the projects beside it.
+
+That is also why a list reaches the store through **`syncCards(store, items, where)`, never
+`replace()`**: every card given is written, every card matching `where` that the list does not name
+is dropped, and everything outside `where` is left alone. An unchanged card is not rewritten, so a
+periodic re-seed wakes no subscriber. `opts.keep` protects ids a commit wrote while the list was in
+flight.
+
+The fold rules, shared by `syncCards`, `applyCards`, `applyCommitEvent` and `commits.wait`:
+
+- an OLDER `seq` never overwrites a newer record — frames and list answers race;
+- a committed `delete` removes the row and every link touching it; a project's delete also drops
+  the rows whose `parents` hold it (the server purged them in the same fold);
+- a frame for an id the store never saw still writes a row;
+- a `failed` commit leaves the card alone and records the reason in the commit store;
+- a frame without `record` (a cross-process bus carries ids only) is re-read through the facade —
+  without one, only the commit row is written;
+- a committed `link`/`unlink` re-lists the card's outgoing links; links written together with a
+  `create` arrive with the next link seed.
+
+## The feed
+
+```typescript
+const feed = makePlanningFeed(context, {
+  query: { parent: projectId, type: STORY },
+  filter: { project: projectId },
+  refresh: 15_000,
+  onChange: state => setState(state),
+})
+await feed.ready          // never rejects — read feed.error
+// …
+await feed.stop()         // stops folding; the shared socket stays open
+```
+
+1. Subscribes to commits FIRST (the socket, when an opener exists).
+2. Seeds: `cards.list` (unpaged unless the query pages) → `syncCards` over `where`
+   (`criteriaOf(query)` by default). A PAGED seed only writes — a page cannot say what does not
+   exist.
+3. Folds every frame with `applyCommitEvent`, and re-seeds every `refresh` ms — the authoritative
+   backstop to a socket that can drop frames.
+
+`connected` reports whether a socket was open when the feed subscribed; `seeded` tells "nothing
+there" from "not loaded yet". A React hook wraps the feed in an effect and stops it on unmount.
+
+## Waiting for a commit
+
+`execute()` is asynchronous: the receipt names a PENDING transition until the store folds it.
+
+```typescript
+const receipt = await planning.execute({ card: id, action: TransitionAction.Transit, transition: 'start' })
+const card = await receipt.committed({ timeout: 15_000 })     // or execute(exec, { wait: true, timeout })
+```
+
+`commits.wait(transition, { timeout })`:
+
+1. **subscribes first** — a commit landing between a status read and a subscription is otherwise
+   missed until the deadline;
+2. reads the status once with `wait: 0`;
+3. long-polls `commit.get` in holds of `min(poll, remaining)` seconds, racing any socket frame;
+4. at the deadline throws `CommitTimeout` — the transition STAYS pending, nothing is undone.
+
+A `failed` commit throws `CommitFailed` with the store's reason. A settled commit is folded into
+the mirror when stores are registered. A poll the server answers without holding is followed by a
+short pause ladder instead of a tight loop, and a dropped hold is replaced by one non-holding read.
+
+`execute({ wait: true })` never holds the POST on the wire: the receipt returns at once and the
+wait above runs from the client. A lost response therefore never leaves a caller unsure whether
+the transition was appended — the key (`exec.key`) still makes a retry of the POST itself safe.
+
+## The socket seam
+
+`socket` is a `PlanningSocketOpener` — `(protocol, request?) => Promise<Connection | null>`. The
+package never imports `@owlmeans/client-socket`, whose helpers pull React; a browser host wraps its
+own `ws()` there (which also puts the session token on the connection). `null` means "no socket
+right now" and the next subscription asks again. ONE connection serves every subscription of the
+service; releasing a subscription never closes it — `context.planning().close()` does.
+
+A Node client passes no opener and relies on the long poll.
+
+## Optimistic writes and `head > seq`
+
+`seq` is the last transition folded into a card, `head` the highest allocated. `applyReceipt`
+(run by `execute` whenever stores are registered) raises the stored card's `head` to the new
+transition's `seq`, so `model.pending()` is true before any frame arrives; the commit's fold brings
+`seq` up to it. The mirror only ever grows `head`, so a list fetched before the append does not
+clear the marker. A model's writes default `expectSeq` to `record.head ?? record.seq`; a stale model
+gets `WorkcardConflict` — reload and retry.
+
+## Gotchas
+
+- Mount a feed once per screen; read the store everywhere else.
+- Do not `replace()` the card store — it holds every kind. Use `syncCards` with a `where`.
+- A refusal crosses the hop as its class (`IllegalTransition`, `WorkcardConflict`,
+  `FieldsInvalid`, a plugin's own class) — branch on `instanceof`, never on message text.
+- `CommitTimeout` is not a failure of the transition; re-wait or re-read the card.
+- The scope passed to `for()` changes nothing the server decides; it exists so code written against
+  `PlanningFacade` reads the same on both sides.
+
+## Depends On
+
+- `@owlmeans/planning` — the facade interface, the protocol tree, the wire encoders, `modelOf`
+- `@owlmeans/client-entrypoint` — `bindAll`, the typed `call()`
+- `@owlmeans/state` — the mirror; `@owlmeans/socket` — `Connection`
+
+## Related
+
+- `planning` — records, flows, the fold, the models
+- `server-planning` — the handlers this addresses, the executor, the commit hub
+- `client-job` — the same seed-then-fold shape for queue jobs
+- `state` — `syncCards` is built on its criteria engine and `purge`

package/build/client.d.ts

@@ -0,0 +1,26 @@
+import type { Config, Context, PlanningClientOptions, PlanningClientService, WithPlanningClient } from './types.js';
+/**
+ * The client planning service: a remote facade factory under the SAME alias the server registers
+ * its service under, so `context.planning().for(scope)` is one call on both sides.
+ *
+ * What only a server can do is refused rather than faked: a client runs no middleware and folds
+ * nothing, so `store()`, `committed()` and a plugin carrying hooks or a store answer
+ * `PlanningUnsupported`. A plugin carrying only schemas is accepted — it layers over the server's
+ * bundle.
+ */
+export declare const makePlanningClientService: <C extends Config, T extends Context<C>>(context: T, options: PlanningClientOptions) => PlanningClientService;
+/**
+ * Wire the planning client into a client context: bind the protocol tree as client entrypoints
+ * (unless `bind: false`), register the service under `PLANNING_SERVICE`, and add
+ * `context.planning()`.
+ *
+ * The tree must be the one the server mounted — the same `makePlanningProtocols` options, alias for
+ * alias. When its commit feed hangs under a `socketBase`, that base belongs to the host and must be
+ * bound by the host too: a parent a registry cannot resolve fails the whole context at init.
+ *
+ * The schema bundle is fetched in the background once the context is READY, and a failure there is
+ * swallowed — a browser that is not signed in yet cannot read it, and a context must not fail over
+ * data it can fetch later. `model()` and `loadSchemas()` load it on first use regardless.
+ */
+export declare const appendPlanningClient: <C extends Config, T extends Context<C>>(context: T, options: PlanningClientOptions) => T & WithPlanningClient;
+//# sourceMappingURL=client.d.ts.map

package/build/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,MAAM,EAAE,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,kBAAkB,EAClF,MAAM,YAAY,CAAA;AAEnB;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,WACrE,CAAC,WAAW,qBAAqB,KACzC,qBAoFF,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,WAChE,CAAC,WAAW,qBAAqB,KACzC,CAAC,GAAG,kBA0BN,CAAA"}

package/build/client.js

@@ -0,0 +1,120 @@
+import { bindAll } from '@owlmeans/client-entrypoint';
+import { createLazyService, MiddlewareStage, MiddlewareType } from '@owlmeans/context';
+import { DEFAULT_PLUGIN_ORDER, makeSchemaRegistry, PLANNING_SERVICE, PlanningUnsupported, } from '@owlmeans/planning';
+import { makeRemoteCommitSource } from './commits.js';
+import { makeRemoteFacade } from './facade.js';
+import { planningStoresOf } from './stores.js';
+/**
+ * The client planning service: a remote facade factory under the SAME alias the server registers
+ * its service under, so `context.planning().for(scope)` is one call on both sides.
+ *
+ * What only a server can do is refused rather than faked: a client runs no middleware and folds
+ * nothing, so `store()`, `committed()` and a plugin carrying hooks or a store answer
+ * `PlanningUnsupported`. A plugin carrying only schemas is accepted — it layers over the server's
+ * bundle.
+ */
+export const makePlanningClientService = (context, options) => {
+    const registry = makeSchemaRegistry();
+    const plugins = [];
+    const stores = () => planningStoresOf(context);
+    const commits = makeRemoteCommitSource(context, options.protocols, {
+        socket: options.socket, poll: options.poll, timeout: options.timeout, stores,
+    });
+    const layerPlugins = () => plugins.forEach(plugin => {
+        plugin.schemas?.flows?.forEach(registry.registerFlow);
+        plugin.schemas?.types?.forEach(registry.registerType);
+    });
+    let loaded = false;
+    let loading = null;
+    const loadSchemas = async (opts) => {
+        if (loaded && opts?.force !== true) {
+            return registry;
+        }
+        if (loading == null || opts?.force === true) {
+            const attempt = (async () => {
+                const bundle = await context.entrypoint(options.protocols.schema.list).call({ timeout: options.timeout });
+                registry.load(bundle);
+                layerPlugins();
+                loaded = true;
+                return registry;
+            })();
+            loading = attempt;
+            // A failed load is forgotten, so the next caller asks again instead of inheriting the error.
+            attempt.catch(() => {
+                if (loading === attempt) {
+                    loading = null;
+                }
+            });
+        }
+        return await loading;
+    };
+    const facadeFor = (scope) => makeRemoteFacade(context, options.protocols, { ...options.scope, ...scope }, {
+        commits, schemas: registry, loadSchemas, timeout: options.timeout, stores,
+    });
+    let fallback = null;
+    // Lazy, like the server's host: `context.planning()` answers before the context initializes.
+    return createLazyService(PLANNING_SERVICE, {
+        schemas: registry,
+        commits,
+        loadSchemas,
+        use: plugin => {
+            if (plugin.before != null || plugin.after != null || plugin.store != null || plugin.mintCode != null) {
+                throw new PlanningUnsupported(`client:plugin:${plugin.name}`);
+            }
+            const existing = plugins.findIndex(candidate => candidate.name === plugin.name);
+            if (existing >= 0) {
+                plugins.splice(existing, 1);
+            }
+            plugins.push(plugin);
+            plugins.sort((left, right) => (left.order ?? DEFAULT_PLUGIN_ORDER) - (right.order ?? DEFAULT_PLUGIN_ORDER));
+            layerPlugins();
+        },
+        plugins: () => [...plugins],
+        store: () => {
+            throw new PlanningUnsupported('client:store');
+        },
+        for: scope => scope == null ? (fallback ??= facadeFor({})) : facadeFor(scope),
+        committed: async () => {
+            throw new PlanningUnsupported('client:committed');
+        },
+        close: async () => await commits.close(),
+    });
+};
+/**
+ * Wire the planning client into a client context: bind the protocol tree as client entrypoints
+ * (unless `bind: false`), register the service under `PLANNING_SERVICE`, and add
+ * `context.planning()`.
+ *
+ * The tree must be the one the server mounted — the same `makePlanningProtocols` options, alias for
+ * alias. When its commit feed hangs under a `socketBase`, that base belongs to the host and must be
+ * bound by the host too: a parent a registry cannot resolve fails the whole context at init.
+ *
+ * The schema bundle is fetched in the background once the context is READY, and a failure there is
+ * swallowed — a browser that is not signed in yet cannot read it, and a context must not fail over
+ * data it can fetch later. `model()` and `loadSchemas()` load it on first use regardless.
+ */
+export const appendPlanningClient = (context, options) => {
+    const ctx = context;
+    if (options.bind !== false) {
+        ctx.registerEntrypoints(bindAll(options.protocols));
+    }
+    const service = makePlanningClientService(context, options);
+    ctx.registerService(service);
+    ctx.planning = () => ctx.service(PLANNING_SERVICE);
+    if (options.schemas !== false) {
+        ctx.registerMiddleware({
+            type: MiddlewareType.Context,
+            stage: MiddlewareStage.Ready,
+            apply: async () => {
+                try {
+                    await service.loadSchemas();
+                }
+                catch {
+                    // Best effort by design — see above.
+                }
+            },
+        });
+    }
+    return ctx;
+};
+//# sourceMappingURL=client.js.map

package/build/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/build/commits.d.ts

@@ -0,0 +1,17 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context';
+import type { PlanningProtocols } from '@owlmeans/planning';
+import type { RemoteCommitSource, RemoteCommitSourceOptions } from './types.js';
+/**
+ * The commit source of a remote facade: the `commit.get` long poll and, when the host injects a
+ * socket opener, the `commit.events` feed.
+ *
+ * `wait` SUBSCRIBES FIRST and only then reads the status — a commit landing between a read and a
+ * subscription would otherwise be missed until the deadline. It then long-polls in holds of
+ * `min(poll, remaining)` seconds, so a client with no socket (a Node connector) still learns of a
+ * commit within one round trip of it landing, and a client with one learns from whichever arrives
+ * first. The deadline is a {@link CommitTimeout}; the transition stays pending — nothing is undone.
+ *
+ * ONE socket serves every subscription of the source; releasing a subscription never closes it.
+ */
+export declare const makeRemoteCommitSource: <C extends BasicConfig, T extends BasicContext<C>>(context: T, protocols: PlanningProtocols, opts?: RemoteCommitSourceOptions) => RemoteCommitSource;
+//# sourceMappingURL=commits.d.ts.map

package/build/commits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commits.d.ts","sourceRoot":"","sources":["../src/commits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKlE,OAAO,KAAK,EAC+B,iBAAiB,EAC3D,MAAM,oBAAoB,CAAA;AAG3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAuB/E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GAAI,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,WAC5E,CAAC,aAAa,iBAAiB,SAAS,yBAAyB,KACzE,kBAuMF,CAAA"}