@owlmeans/client-planning 0.1.18-rc.8 → 0.1.18

package/README.md

@@ -1,15 +1,15 @@
 # @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
+with [`@owlmeans/server-planning`](../server-planning), optional state mirrors of cards, links,
+commits, assignees, teams, comments and mentions, 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.8
+bun add @owlmeans/client-planning@^0.1.18
 ```
 
 ## Concepts
@@ -17,14 +17,46 @@ bun add @owlmeans/client-planning@^0.1.18-rc.8
 - **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()`.
+  through `syncHelper.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
+- **`head > seq`** — a card with a transition allocated and not yet folded; the mirror's `applyReceipt` marks it
   the moment the server answers.
 
+## Forms under a strict Content Security Policy
+
+Use the exact resolved card or assignee type's field schema:
+
+```typescript
+import { makePlanningFieldValidator } from '@owlmeans/client-planning'
+
+const form = makePlanningFieldValidator(resolvedType.fields)
+const checked = form.validateFields(fields)
+if (checked.valid) {
+  // Submit this same fields object through the stock planning facade.
+}
+```
+
+The runtime interpreter supports dynamic organization and project definitions without `eval` or
+`new Function`. It preserves the schema and payload, nested objects, required fields, enum/const,
+dates, references, compositions and AJV nullable semantics; string formats use native
+`ajv-formats` full-mode predicates. Errors contain field `path`, `keyword`, `schemaPath` and a
+bounded message without submitted values. The server's authoritative AJV validates every write.
+
+The schema contract is Draft 7 plus `$defs` and `nullable`, with native AJV reference-sibling
+semantics. References must resolve within the supplied schema. Malformed schemas, missing
+references, same-instance reference cycles, other drafts/custom validation keywords, unknown or
+numeric formats, format-limit extensions and `multipleOf` throw `SchemaInvalid` at preparation.
+The interpreter's floating tolerance and native AJV's multiple semantics differ, so that keyword
+is explicitly refused. JSON fields cannot contain dot/dollar keys or non-JSON values. Standard
+annotations and `x-` metadata remain annotations. At most 64 validation errors are returned.
+
+Surface preparation errors and keep save disabled. Do not remove constraints, choose another
+schema or relax CSP. Registry `validator` / `assigneeValidator` compile with native AJV and need
+code generation; browser forms under strict CSP use this API instead.
+
 ## Usage
 
 Wire the client into a context with the server's own tree:
@@ -36,9 +68,14 @@ import { appendPlanningClient, appendPlanningStores } from '@owlmeans/client-pla
 const planningProtocols = makePlanningProtocols({
   base: { alias: 'app:api:planning', path: '/planning', service: API },
   guards: DEFAULT_GUARD,
+  resources: true,
+  definitions: true,
 })
 
-appendPlanningClient(context, { protocols: planningProtocols, poll: 20 })
+appendPlanningClient(context, {
+  protocols: planningProtocols, poll: 20,
+  scopeKey: () => `${currentEntitySlug}:${currentSessionId}`,
+})
 appendPlanningStores(context)
 ```
 
@@ -77,18 +114,61 @@ 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),
+  socket: async (protocol, request) => await socketClientHelper.ws(context.entrypoint(protocol), request),
+})
+```
+
+## Auxiliary resources and session lifecycle
+
+The remote facade supports the same `assignees`, `teams`, `comments` and `mentions` methods as
+the server, including compare-and-set writes, canonical team membership/project attachment,
+effective project assignees and mention-cache rebuilding. `definitions` supports assignee types
+when the server mounts writable schemas. Relationships include endpoint resource kinds and named
+inverse views; models resolve schemas through their nearest primary project.
+
+`appendPlanningStores` registers four auxiliary mirrors beside cards, links and commits. Reads
+and writes through the facade update those mirrors without replacing newer versions. A resource
+feed refreshes the requested subsets through the stock API:
+
+```ts
+import { makePlanningResourceFeed } from '@owlmeans/client-planning'
+
+const resources = makePlanningResourceFeed(context, {
+  assignees: { retired: false, size: 0 }, teams: { size: 0 },
+  comments: { card: cardId, size: 0 }, mentions: { card: cardId, size: 0 },
+  refresh: 5_000,
 })
+await resources.ready
+// Read context.planningStores().assignees, teams, comments and mentions.
+await resources.stop()
 ```
 
+`scopeKey` identifies the current organization slug and authenticated session. A changed key
+cancels old requests and feeds, drains local mutations and clears mirrors; capture a new facade
+and feed for the new session. `await context.planning().close()` releases feeds, subscriptions,
+commit waits and sockets, including carriers that open late. Stopped requests cannot repopulate
+cleared mirrors, even when a transport ignores cancellation.
+
+The server derives authorization scope from credentials. Wire records omit native organization
+`entityId`; the client hydrates empty advisory metadata for the shared record shape. Never use
+that placeholder to authorize a request, and never send an organization record id on the wire.
+
 ## 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)`
+- `appendPlanningStores(context, aliases?)`
+- `syncHelper` — `.syncCards(store, items, where?, opts?)`, `.syncLinks(store, items, where?, opts?)`
+- `planningMirrorOf(stores)` (`makePlanningMirror`) — `.applyCommitEvent(event, facade?)`,
+  `.applyReceipt(view)`, `.applyCards(cards)`
 - `makePlanningFeed(context, opts?)`
-- `planningOf(context, scope?)`, `planningModelOf(context, card, scope?)`
+- `makePlanningResourceFeed(context, opts?)`, `PlanningResourceFeedOptions`
+- `makePlanningFieldValidator(schema)`, `PlanningFieldValidator`, `PlanningFieldValidation`, `PlanningFieldError`
+- `makePlanningClientLifecycle`, `PlanningClientLifecycle`; service `close()` and `scopeKey`
+- `planningContextOf(context)` (`makePlanningContextHelper`) — `.facade(scope?)`, `.model(card, scope?)`,
+  `.stores()`
+- The former plain functions (`syncCards`, `applyCards`, `planningOf`, …) remain as deprecated
+  delegates.
 - `CARDS`, `LINKS`, `COMMITS`, `DEFAULT_STORE_ALIASES`, `LONG_POLL_GRACE`, `EARLY_POLL_LADDER`, `EARLY_POLL_MS`
 - Types: `PlanningClientOptions`, `PlanningClientService`, `WithPlanningClient`,
   `PlanningSocketOpener`, `RemoteCommitSource`, `RemoteCommitSourceOptions`, `RemoteFacadeOptions`,
@@ -103,6 +183,9 @@ appendPlanningClient(context, {
 - `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.
+- Auxiliary updates/removals require `{ version: record.version }`. Their `fields` replace the
+  previous object; card `changes.fields` merge.
+- After a scope/session change, acquire new facades and feeds. Old ones are deliberately stale.
 
 ## Related packages
 
@@ -119,7 +202,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.35
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/client-planning",
-  "version": "0.1.18-rc.8",
-  "generatedAt": "2026-09-22T21:57:18.823Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.741Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -10,7 +10,65 @@
       "name": "client-planning",
       "category": "package-specific",
       "file": "skills/client-planning/SKILL.md",
-      "canonicalPath": ".agents/skills/client-planning/SKILL.md"
+      "canonicalPath": ".agents/skills/client-planning/SKILL.md",
+      "parts": [
+        {
+          "name": "aux-mirrors",
+          "file": "skills/client-planning/parts/aux-mirrors.md",
+          "description": "The assignee, team, comment and mention mirrors and resource feeds, and the authenticated scope lifecycle (scopeKey, close, lifecycle.run and lifecycle.mutate).",
+          "purposes": [
+            "state",
+            "auth"
+          ],
+          "mentions": [
+            "makePlanningResourceFeed",
+            "scopeKey",
+            "lifecycle.run",
+            "lifecycle.mutate",
+            "registerFeed",
+            "client:scope-changed",
+            "PlanningReply"
+          ]
+        },
+        {
+          "name": "mirror",
+          "file": "skills/client-planning/parts/mirror.md",
+          "description": "The state mirror's one id space and fold rules, makePlanningFeed, and optimistic writes with head over seq.",
+          "purposes": [
+            "state",
+            "list"
+          ],
+          "mentions": [
+            "appendPlanningStores",
+            "planningMirrorOf",
+            "applyCommitEvent",
+            "applyReceipt",
+            "applyCards",
+            "syncHelper",
+            "syncCards",
+            "syncLinks",
+            "makePlanningFeed",
+            "PlanningFeed",
+            "useStoreList"
+          ]
+        },
+        {
+          "name": "validation",
+          "file": "skills/client-planning/parts/validation.md",
+          "description": "CSP-safe browser validation of a served field schema with makePlanningFieldValidator — the supported keywords, refusals and limits, and the external references behind them.",
+          "purposes": [
+            "form"
+          ],
+          "mentions": [
+            "makePlanningFieldValidator",
+            "validateFields",
+            "@cfworker/json-schema",
+            "JSON_SCHEMA_DRAFT_07",
+            "unsafe-eval",
+            "SchemaInvalid"
+          ]
+        }
+      ]
     }
   ]
 }

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: How to use @owlmeans/client-planning — appendPlanningClient for the remote planning facade, appendPlanningStores and planningMirrorOf 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. -->
@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/client-planning
 
 **Layer:** Client
-**Install:** `"@owlmeans/client-planning": "^0.1.18-rc.8"` in `dependencies`
+**Install:** `"@owlmeans/client-planning": "^0.1.18"` 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
@@ -24,13 +24,15 @@ CLI). React hooks over the mirror are `useStoreModel` / `useStoreList` from `@ow
 | `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 |
+| `makeRemoteDefinitions(context, protocols, opts?)` | Data-defined types and flows over a tree declared with `definitions: true` |
+| `appendPlanningStores(context, aliases?)` / `planningContextOf(context).stores()` | The state mirror, and a lookup that answers `null` without one |
+| `syncHelper.syncCards(store, items, where?, opts?)` / `syncHelper.syncLinks(...)` | Make the mirror agree with a list WITHIN a scope |
+| `planningMirrorOf(stores).applyCommitEvent(event, facade?)` / `.applyReceipt(view)` / `.applyCards(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 |
+| `planningContextOf(context).facade(scope?)` / `.model(card, scope?)` | The facade / a model with the schemas loaded |
+| `makePlanningFieldValidator(schema)` | CSP-safe validation of an exact served field schema; `{ validateFields }` |
 | `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` |
+| Types | `PlanningClientOptions`, `PlanningClientService`, `WithPlanningClient`, `PlanningSocketOpener`, `RemoteCommitSource`, `RemoteDefinitions`, `RemoteDefinitionsOptions`, `PlanningStores`, `PlanningStoreAliases`, `WithPlanningStores`, `PlanningCommitRecord`, `PlanningFeed`, `PlanningFeedOptions`, `PlanningFeedState`, `SyncOptions`, `PlanningContextHelper`, `PlanningMirror`, `SyncHelper` |
 
 ## Wiring
 
@@ -59,36 +61,66 @@ appendPlanningStores(context)        // a browser mirror; a Node client usually
 - `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.
+  **advisory** — it changes nothing the server decides: 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.
+  plugin, layered over the server's bundle; its `schemas.app` merges over the served declarations
+  (`bundle.app`) in plugin order, and a malformed one is refused (`SchemaInvalid`) before anything
+  changes.
 - `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
+round trip). The bundle also carries the application's declarations (`registry.app()`), so
+`registry.fieldsSchema(type)` / `validator(type)` include its base card fields and a definition's
+`app` bag reads back as written. 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.
 
+### Data-defined types and flows
+
+A tree declared with `definitions: true` (the server's store holds data-defined schemas) gives the
+service and every facade `definitions`: `registry(project?)` / `bundle(project?)` read
+`schema.list?project=` and are cached per project; `putType`/`putFlow` (compare-and-set on the
+declaration's `version`), `define`, `seed` and `retire` go through `schema.define` and drop the
+whole cache — an organization-wide write reaches every project's layer — and make the next
+`model()` reload the service's own bundle. `records` is the server's alone (`PlanningUnsupported`).
+`model(card)` of a card resolves its type in its project's layer (a project's own id, a card's
+nearest primary project ancestor); a specification's type is always code's. A tree without `definitions` has none of this.
+
+## Mounting in a target
+
+The web half of the target mount (`planning` → Mounting in a target, in that skill's `mounting` part).
+
+- `appendPlanningClient(context, { protocols, bind: false, schemas: false })` — the target binds
+  its whole api tree itself, and a signed-out visitor may read nothing, so the bundle loads on
+  first use — plus `appendPlanningStores(context)`. No `socket`: the target serves no commit socket,
+  so `commits.wait` long-polls.
+- Screens read the mirror with `useStoreList` / `useStoreModel` (`@owlmeans/client`), never a
+  fetched array kept in component state; lists reach the store through `syncHelper.syncCards` or
+  `makePlanningFeed` (with `refresh`), NEVER `replace()` — the one card store holds every kind.
+- Every write is `facade.execute(...)` with a `key` (a retried click or a double submit answers
+  the first receipt) and `{ wait: true }` where the screen shows the result.
+- Never call a route with an empty id; a picker offers no archived parent (`intrinsic: closed`).
+
 ## 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)
+const tools = await planning.cards.list({ parent: shedId, type: 'shed:tool', sort: ['order'], size: 0 })
+const board = await planning.cards.summary([shedId])
+const rules = await planning.specifications.current(shedId, 'house-rules')
+const drill = await planning.model(drillId)
+drill.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.
+  (`wireHelper.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.
@@ -96,54 +128,6 @@ story.available().map(rule => rule.name)
   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.
@@ -179,24 +163,12 @@ service; releasing a subscription never closes it — `context.planning().close(
 
 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
 
@@ -209,4 +181,14 @@ gets `WorkcardConflict` — reload and retry.
 - `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 safe application-job views
-- `state` — `syncCards` is built on its criteria engine and `purge`
+- `state` — `syncHelper.syncCards` is built on its criteria engine and `purge`
+
+## Parts
+
+Load a part on top of this core when its job is in play.
+
+| Part | Load it when |
+|---|---|
+| [validation](parts/validation.md) | Validating planning `fields` in a browser form under a strict CSP (`makePlanningFieldValidator`) |
+| [mirror](parts/mirror.md) | Reading lists from the state mirror (`syncHelper`, `planningMirrorOf`), mounting `makePlanningFeed`, or relying on `head > seq` |
+| [aux-mirrors](parts/aux-mirrors.md) | Assignee, team, comment or mention mirrors and feeds, or switching organization / signing out (`scopeKey`, `close()`) |

package/agent-meta/skills/client-planning/parts/aux-mirrors.md

@@ -0,0 +1,61 @@
+---
+name: aux-mirrors
+description: The assignee, team, comment and mention mirrors and resource feeds, and the authenticated scope lifecycle (scopeKey, close, lifecycle.run and lifecycle.mutate).
+metadata:
+  purposes: state, auth
+  mentions: makePlanningResourceFeed, scopeKey, lifecycle.run, lifecycle.mutate, registerFeed, client:scope-changed, PlanningReply
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/client-planning — Auxiliary mirrors and the scope lifecycle
+
+## Auxiliary mirrors and authenticated scope lifecycle
+
+With `resources: true` in the shared protocol tree, every remote facade exposes the complete
+assignee/team/comment/mention API, including versioned writes, team membership and project
+attachment. `appendPlanningStores` registers separate stock typed mirrors for all four resources.
+`makePlanningResourceFeed` seeds and polls selected resource queries; use it with the stock stores
+and `useStoreList` / `useStoreModel`. Auxiliary writes update the mirror only after success.
+An active-assignee query (`retired: false`) includes an absent or null retirement flag. Local
+mirror queries and feed reconciliation use `{ retired: { $ne: true } }`, matching the native
+facade rather than strict equality to false. A filtered poll removes only its unchanged matching
+snapshot rows, preserving unrelated retired identities needed by existing references.
+Comments use trusted server authors; mentions are read-only derived cache commands.
+
+Supply `PlanningClientOptions.scopeKey` from authenticated organization entity slug, profile/user
+id, session id and authorization revision; return undefined when signed out. Before switching
+organization or signing out, **await** `service.close()` before adopting the credential. It cancels
+requests and commit waits, invalidates receipts (including already-settled receipts), stops every
+registered feed, removes socket subscriptions, closes the carrier and rejects late socket openers.
+A stale operation answers `client:scope-changed`; cancellation never rolls back an accepted server
+write. A new subscription opens a fresh carrier after close.
+
+Close drains admitted **local** mirror writes before clearing every stock store and schema cache.
+New calls during an explicit close are refused, including hosts without `scopeKey`. Concurrent
+closes share the boundary. If clearing fails, close rejects and fresh work stays blocked; retain
+the old credential and retry close explicitly. An observed identity change also cancels old work
+and queues clearing before the new identity's mirror writes. Reload schemas and create fresh feeds
+after credential adoption. Feed query scope alone is insufficient for this lifecycle.
+
+The service's `lifecycle` coordinates stock facades, receipts, feeds and schema writes. A custom
+mirror integration captures an operation with `lifecycle.run`, performs remote reads through
+`operation.wait` with `operation.signal`, then uses `lifecycle.mutate(operation, write)` for local
+writes; never hold or nest that queue over a request, socket opener or another queued mutation.
+`planningMirrorOf(stores)` accepts `{ lifecycle, operation }` as its optional last argument and
+fetches missing frame records/links before entering the queue. Direct mirror/sync helpers without
+that option are local primitives: their caller owns isolation and cleanup.
+
+Planning protocols return `PlanningReply<T>` without storage organization identifiers. Stock
+facades hydrate records, receipts, schema scopes and socket frames with `entityId: ''` only to
+preserve the shared facade shape. That value is an advisory placeholder, never an organization
+identity or a credential. Use `scopeKey` and the authenticated organization entity slug for
+identity changes and access isolation; native server records keep their verified stable scope.
+
+Resource feed reconciliation snapshots mirror versions before requesting a list. Only unchanged
+snapshot rows absent from that response are removed, so a new local write or a newer version
+survives an older in-flight poll. Stopped feeds cannot publish. Track custom feeds through
+`registerFeed` when their lifecycle must end with the planning service. Card feeds use the same
+identity fence and stop registration; component cleanup awaits `stop()` when it must observe a
+completed boundary. Stop cancels unresolved seeds and drains admitted local changes without waiting
+for the network; neither late callbacks nor authoritative deletion passes may publish afterward.
+A schema write from an old generation cannot invalidate a newer generation's cached registry.

package/agent-meta/skills/client-planning/parts/mirror.md

@@ -0,0 +1,67 @@
+---
+name: mirror
+description: The state mirror's one id space and fold rules, makePlanningFeed, and optimistic writes with head over seq.
+metadata:
+  purposes: state, list
+  mentions: appendPlanningStores, planningMirrorOf, applyCommitEvent, applyReceipt, applyCards, syncHelper, syncCards, syncLinks, makePlanningFeed, PlanningFeed, useStoreList
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/client-planning — The mirror and the feed
+
+## 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 **`syncHelper.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 `syncHelper.syncCards`, the mirror's `applyCards` and `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: shedId, type: 'shed:tool' },
+  filter: { project: shedId },
+  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) → `syncHelper.syncCards` over `where`
+   (`queryHelper.criteriaOf(query)` by default). A PAGED seed only writes — a page cannot say what
+   does not exist.
+3. Folds every frame with `planningMirrorOf(stores).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.
+
+## Optimistic writes and `head > seq`
+
+`seq` is the last transition folded into a card, `head` the highest allocated. The mirror's
+`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 `expectSeq` default and its `WorkcardConflict` are `planning` → Models.

package/agent-meta/skills/client-planning/parts/validation.md

@@ -0,0 +1,60 @@
+---
+name: validation
+description: CSP-safe browser validation of a served field schema with makePlanningFieldValidator — the supported keywords, refusals and limits, and the external references behind them.
+metadata:
+  purposes: form
+  mentions: makePlanningFieldValidator, validateFields, @cfworker/json-schema, JSON_SCHEMA_DRAFT_07, unsafe-eval, SchemaInvalid
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/client-planning — Browser field validation
+
+## Browser field validation under CSP
+
+Bind `makePlanningFieldValidator(registry.fieldsSchema(type))` to the registry of the resolved
+organization or project bundle — the type's own `fields` plus the application's base card fields
+(`planning` → types part); with no base fields it IS `type.fields`. Passing `type.fields` alone
+skips the base fields the server still enforces. Its `validateFields(fields)` returns `{ valid, errors }`; errors
+carry decoded `path`, `keyword`, `schemaPath` and a bounded value-free `message`. Construct one JSON
+fields object, validate it and send that same object. No coercion, defaults or property removal
+occurs, and the schema is left unchanged. Preserve nested money objects and calendar date strings.
+The native server validates every write again.
+
+The validator interprets schemas with `@cfworker/json-schema`, with no `eval`, `new Function` or
+network reference loading. Building, loading and merging a registry is safe under a strict
+`script-src` — `loadSchemas()`, `definitions.registry()`/`bundle()`, `model()`, `makeSchemaRegistry(bundle)`,
+`scopedRegistryOf` — because a page runs only the closed-form checks of the served `app` declarations
+(`planning` → types part). Do not call `.validator()`, `.assigneeValidator()`, `appSchemaHelper.assertBag`,
+`scopedSchemaHelper.assert*Schema` or `validateHelper.*` in a browser with strict `script-src`: those
+remain native AJV compilers, the server's.
+The Draft 7 meta-schema is DATA in `src/validation/consts.ts` (`JSON_SCHEMA_DRAFT_07`, pinned to ajv's
+`refs/json-schema-draft-07.json` by `tests/draft7.spec.ts`), never an import of that file: Node ESM needs
+`with { type: 'json' }` on it, and a bundler that also meets ajv's own attribute-less `require` of the
+same file refuses the pair (Rollup: "import attributes for the same module are always consistent"),
+which fails every target web build that mounts the planning client.
+Static AJV standalone compilation is suitable only when the schema cannot change after building;
+organization and project definitions require the runtime interpreter.
+
+The supported contract is Draft 7's object/array/scalar, required, enum/const, ranges, string
+length/pattern, dependencies, boolean, composition and conditional keywords; `$defs`, local/nested
+`$id` references and AJV's `nullable` are also supported. `$ref` sibling constraints are enforced as
+by native planning AJV. String formats use the same `ajv-formats` full-mode predicates, including
+real calendar dates and timezone-aware times. `nullable` adds null to the declared type while
+leaving enum and const constraints intact. All references must resolve inside the supplied field
+schema; productive recursive schemas are supported, same-instance reference cycles are refused.
+Plain JSON values and field names without dot or dollar characters are required.
+
+Preparation throws `SchemaInvalid` for malformed schemas, unresolved references, unsupported
+drafts/keywords/formats, numeric formats, `formatMinimum`/`formatMaximum` extensions and
+`multipleOf`. The latter is refused because the interpreter's epsilon and native AJV's quotient
+semantics disagree for fractional and very large numbers. Standard annotation keywords and `x-`
+annotations do not add validation. Never discard a refused constraint, invent a substitute schema,
+enable `unsafe-eval` or proceed with a ready form after preparation fails. Show the error and retain
+disabled save controls. Validation reports at most 64 errors, with paths bounded to 512 characters.
+
+## External docs
+
+- https://ajv.js.org/security.html#content-security-policy — runtime AJV requires unsafe-eval; standalone build compilation preserves strict CSP for static schemas.
+- https://www.npmjs.com/package/@cfworker/json-schema/v/4.1.1 — the interpreter supports dynamic schemas without code generation; select an explicit vocabulary and check its known limitations (4.1.1).
+- https://github.com/ajv-validator/ajv-formats#full-and-fast-validation-modes — full-mode predicates validate formats completely and are reusable through the plugin's `get` API (3.0.1).
+- https://ajv.js.org/json-schema.html#nullable-openapi — nullable expands the declared type without adding null to enum or const.