Client ergonomics (Layer 1a): typed Ref, lossless transition, single-actor governance sugar, origin config

[styk-tv]

Reduce the code a user writes — grounded in the v1.5.4 seal-half proof, where we hit reply-shape guessing, bare() URN surgery, the propose→vote→apply dance for a single-actor act, and had to drop to raw do() because transition() sugar strips from/allowed.

Pure-client, non-breaking:

• Typed Ref (.id/.urn/.local) returned by writes → kill reply-shape guessing and bare().
• Lossless transition() → surface {ok, from, to, allowed} instead of a reduced writeResult (no dropping to do()).
• Single-actor governance sugar — k.setTransitionMap(type, map) / generic k.govern(op, detail) = propose→vote→apply at quorum 1, returning the applied result (no manual proposal-id extraction).
• Origin-derived config defaults — drop wssEndpoint/hydrate/dispatchTimeout boilerplate where a same-origin browser can derive them.

doFresh is the template: a method that absorbs the complexity and stays honest. This is the foundation the notation compiler (#7) stands on.

Future (separate, gated): Layer 1b — server-derived genesis state (stop passing lifecycle_state) + transitionsFrom(id) legal-now targets — needs pgCK to expose the declared lifecycle/genome.

[styk-tv]

First increment landed on main (45068ea), TDD, non-breaking, full suite 80/80 green:

• Typed Ref fields — writes now return .urn (full IRI) + .local (bare) alongside .id → kills bare() surgery and .id/.iri guessing.
• Lossless transition() — surfaces {from, to, source} (and allowed when present) verbatim → no dropping to raw do() to read the from-state.
• Stable propose().iri — normalizes the proposal handle (was a 5-way OR-guess).
• govern() / setTransitionMap() — propose→vote→apply q1 in one call.

Reply shapes grounded in the live pgCK 0.4.21 seal-gate output, not assumption. Finding worth noting: the live 0.4.21 reject omitted allowed for a nonexistent-target move, which contradicts ck.js's own comment and smoke-ck's mock — so the client treats allowed as optional passthrough.

Still open on this issue: origin-config defaults (drop wssEndpoint/hydrate/dispatchTimeout boilerplate) and the Ref-as-callable form (ref.transition(...)), plus live-verification of the ergonomics against a real bundle — the gate before this rides a tagged release. Layer 1b (server-derived genesis + transitionsFrom) stays gated on pgCK exposing the declared lifecycle.

[styk-tv]

Layer 1a complete + live-verified against pgCK 0.4.21 (commits 45068ea, de740ef; full suite 83/83).

Landed:

• Typed Ref fields (.urn/.local) on writes.
• Lossless transition() — {from, to, source} (+ optional allowed) verbatim.
• Stable propose().iri + govern() / setTransitionMap() single-actor sugar.
• Callable Ref — const t = await k.create(…); await t.transition("sealed") (routes to the id automatically; also .update/.link/.verify/.get).

Live-verified over real WSS → pgCK 0.4.21: setTransitionMap → {applied, epoch}; create → Ref; t.transition("sealed") → {ok:true, from:"pending", to:"sealed"}. The whole seal-half flow that took ~8 hand-written lines + a 5-way id guess in the v1.5.4 proof gate is now 3 clean calls.

Grounding finding: pgCKs create reply is a **bare id (no full @id)** → .urn === .local === .idfor create; the derivation falls back honestly (never fabricates an IRI). Ref fields carry their full value on reads/edges that include@id`.

Scope note: dropping origin-config defaults from this issue — the wssEndpoint/hydrate/dispatchTimeout opts are node-gate/test boilerplate, not a real same-origin browser-app pain (defaults already work there). So Layer 1a is done. Layer 1b (server-derived genesis + transitionsFrom) stays gated on pgCK exposing the declared lifecycle — separate follow-up.

Ships in the next tagged release (with a fresh live gate at tag time).