weir-harness 1.2.0 → 1.2.1

package/src/capabilities/apply-engine.js

@@ -8,24 +8,26 @@
 //      no permission publication, no external installs, no notifications.
 //   4. Enter the session admission fence; close the gate and start draining
 //      removed managed MCP servers (drain is a stub seam until group 8.6).
-//   5. CAS-commit the new selection and receipt through the group-2 store,
-//      then in ONE non-async segment: swap the in-memory snapshot, call the
-//      provider's control.invalidate() and release the fence. invalidate()
+//   5. CAS-commit the new selection and receipt through the group-2 store, which
+//      reports the payload its CAS replaced — the authority for the net-change
+//      notice and for the gate/drain set — then in ONE non-async segment: swap
+//      the in-memory snapshot, call the provider's control.invalidate() and
+//      release the fence. invalidate()
 //      happens before the fence release and before the step-6 response.
 //   6. Send the response: accepted revision, effective sets, unresolved
 //      warnings and a drain snapshot taken at send time (never awaited).
 // Audit and notification are scheduled best-effort after the response; their
 // failure never rolls back accepted policy. Commands and audit logs are not
 // commit evidence: durable acceptance is only the store record.
-// Tasks 4.5 run content-refresh transactions through the SAME per-session
-// serialization point (coordinate); tasks 4.6 gate capability calls on the
-// fence and the authority snapshot exposed here.
+// Tasks 4.6 gate capability calls on the fence and the authority snapshot
+// exposed here.
 import { digestOf } from './store/record.js'
 import { isSegment } from './store/paths.js'
 import { skillIdentityKey } from './skill-identity.js'
 import { validateSkillSelection } from './skill-selection-provider.js'
 import { normalizeEnabledSets } from './selection-draft.js'
 import { AUDIT_TYPES } from '../shared/audit.js'
+import { selectionDelta } from './selection-notify.js'
 
 /** Audit event type (without the 'weir/' prefix) emitted after acceptance.
  * Registered in src/shared/audit.js (AUDIT_TYPES); emit sites never invent
@@ -36,6 +38,14 @@ export const APPLY_AUDIT_TYPE = AUDIT_TYPES.capabilityApply
  * @typedef {import('./skill-selection-provider.js')} SelectionProviderModule
  * @typedef {{ kind: 'skill'|'mcp', ref: string, reason: string }} UnresolvedRef
  * @typedef {{ server: string, state: 'draining'|'settled', inFlight: number }} DrainStatus
+ * The engine drain seam (step 4). begin(removed, sessionId) closes the gates
+ * of the removed servers FOR THAT SESSION and returns a handle: snapshot()
+ * reports the live in-flight counts (sent with the response, never awaited)
+ * and abort() reopens exactly the gates begin() closed when the Apply does
+ * not commit — abort() and begin() act on the SAME drain, so a failed Apply
+ * never leaves a session permanently gated. Production wires the manager's
+ * (agent, server)-keyed drain here (createSessionDrainAdapter, mcp-drain.js).
+ * @typedef {{ begin(removed: string[], sessionId: string): { snapshot(): DrainStatus[], abort(): void } }} ApplyDrain
  * A step-tagged rejection keeps the old authority and the user's draft.
  * @typedef {{ status: 'applied', revision: number, receipt: unknown, effective: unknown, unresolvedWarnings: UnresolvedRef[], draining?: DrainStatus[], warnings?: string[] }
  *   | { status: 'duplicate', revision: number, receipt: unknown, effective: unknown, warnings?: string[] }
@@ -94,10 +104,13 @@ export function createAdmissionFence() {
 }
 
 /**
- * Drain coordinator for managed MCP servers removed by an Apply (step 4 seam;
- * group 8.6 wires it to the real MCP facade with timeouts). Closing a gate is
- * reversible until the commit succeeds: a rejected or failed Apply aborts the
- * closure. In-flight calls are reported, never force-cancelled.
+ * Drain coordinator for managed MCP servers removed by an Apply: the
+ * server-keyed DEFAULT seam implementation (the test surface). Production
+ * wires the manager's (agent, server)-keyed drain through
+ * createSessionDrainAdapter in mcp-drain.js — the engine passes the session
+ * id to begin(), which a server-keyed coordinator simply ignores. Closing a
+ * gate is reversible until the commit succeeds: a rejected or failed Apply
+ * aborts the closure. In-flight calls are reported, never force-cancelled.
  */
 export function createDrainCoordinator() {
   /** @type {Map<string, { closed: boolean, inFlight: Set<Promise<unknown>> }>} */
@@ -176,12 +189,12 @@ export function digestApplyRequest(normalized) {
  *   inventory: (options: { cwd?: string, scope: { session: { id: string } } }) => Promise<{ complete: boolean, candidates: any[] }>,
  *   provider: { acceptSelection(identities: unknown[], options?: unknown): { accepted: boolean, conflicts?: unknown[] } },
  *   fence?: ReturnType<typeof createAdmissionFence>,
- *   drain?: ReturnType<typeof createDrainCoordinator>,
+ *   drain?: ApplyDrain,
  *   conditions?: () => string[] | Promise<string[]>,
  *   verifyContent?: (candidate: unknown) => Promise<void> | void,
  *   audit?: (session: { id?: string }, type: string, data?: unknown) => void,
  *   notify?: (response: unknown) => unknown,
- *   onAccepted?: (sessionId: string, delta: { added: string[], removed: string[] }) => void,
+ *   onAccepted?: (sessionId: string, delta: { added: string[], removed: string[] }, info: { revision: number }) => void,
  *   invalidate?: (sessionId: string, presetId: string) => void,
  *   publishSnapshot?: (sessionId: string, snapshot: { revision: number, skills: unknown[], mcpServers: string[] }) => void,
  *   warn?: (message: string) => void,
@@ -197,7 +210,7 @@ export function createApplyEngine(options) {
     verifyContent,
     audit, notify, invalidate, publishSnapshot, onAccepted, warn = () => {}, trace = () => {},
   } = options
-  /** In-memory authority snapshots per session (D6 seam; group 6 loads them at mount). */
+  /** In-memory authority snapshots per session (D6 seam): written only by the publication segment, never loaded from disk — after a restart the durable accepted record is the only delta/recovery basis (apply-delta-durable-basis D2). */
   const snapshots = new Map()
   /** Per-session in-process serialization; cross-process exclusion is the store lock. */
   const queues = new Map()
@@ -205,8 +218,15 @@ export function createApplyEngine(options) {
    * Sessions whose last write ended indeterminate: the fence lease stays held
    * and the prepared (never published) transaction is kept so a receipt query
    * can settle it from durable evidence — publish on proof, reopen on proven
-   * absence, keep blocking while the record cannot vouch either way.
-   * @type {Map<string, { lease: { release(): void }, requestId: string, prepared: { handles: unknown[], identities: unknown[], view: unknown }, payload: unknown, drainHandle: { abort(): void } | null, viewOptions: unknown }>}
+   * absence, keep blocking while the record cannot vouch either way. The entry
+   * captures the publication basis (`basisSets`) of the aborted transaction: at
+   * settle time the durable record already holds the LANDED write, so the
+   * recovery notice delta cannot re-read it. Which record that is depends on the
+   * site — the committed-over record when the commit result proved it (a landed
+   * write whose fence was lost before publication), otherwise the transaction-
+   * start store read (the commit threw or its outcome is unknown: this process
+   * never observed the locked record, so no committed-over proof exists).
+   * @type {Map<string, { lease: { release(): void }, requestId: string, prepared: { handles: unknown[], identities: unknown[], view: unknown }, payload: unknown, basisSets: { skills: unknown[], mcpServers: string[] }, drainHandle: { abort(): void } | null, viewOptions: unknown }>}
    */
   const blocked = new Map()
 
@@ -381,7 +401,7 @@ export function createApplyEngine(options) {
     }
     let drainHandle = null
     try {
-      drainHandle = removedServers.length ? drain.begin(removedServers) : null
+      drainHandle = removedServers.length ? drain.begin(removedServers, sessionId) : null
     } catch (error) {
       lease.release()
       return { status: 'rejected', reason: `drain-failed:${message(error)}`, step: 4 }
@@ -395,80 +415,90 @@ export function createApplyEngine(options) {
       // The write outcome is UNKNOWN: stay blocked (fence held, gates closed)
       // and let a receipt query confirm the authority; never roll back on a guess.
       trace('indeterminate', { sessionId })
-      blocked.set(sessionId, { lease, requestId: normalized.requestId, prepared, payload, drainHandle, viewOptions })
+      blocked.set(sessionId, { lease, requestId: normalized.requestId, prepared, payload, basisSets: previousSets, drainHandle, viewOptions })
       return { status: 'indeterminate', step: 5 }
     }
     trace('commit', { sessionId, status: result.status })
 
     if (result.status === 'committed') {
+      // Basis authority (D2/D5): the store hands back the payload its CAS replaced,
+      // read under the same per-unit lock. The transaction-start read above is NOT
+      // that authority — a foreign writer can land between it and this commit, and
+      // the CAS then passes on a revision this engine never saw. A committed result
+      // that cannot prove the record (a store double, a future store that does not
+      // honour the interface) keeps that read and reports
+      // `committed-over-unavailable`: never a fabricated full-set delta.
+      const proven = Object.hasOwn(result, 'committedOver')
+      const basisSets = proven
+        ? (result.committedOver === undefined ? { skills: [], mcpServers: [] } : safeSets(result.committedOver))
+        : previousSets
+      /** @type {string[]} */
+      const warnings = []
+      const degraded = (code, error) => {
+        warnings.push(code)
+        if (code === 'accepted-notification-degraded') warn(`apply onAccepted hook failed: ${message(error)}`)
+        else if (code === 'committed-over-unavailable') warn('apply commit result cannot prove the committed-over record: notice and drain basis fall back to the transaction-start read')
+      }
+      if (!proven) degraded('committed-over-unavailable')
+      // Two-phase drain (D3): the pre-commit closure above started draining from
+      // the transaction-start read — early, but possibly one revision stale.
+      // Servers the committed-over record drops that the earlier read could not
+      // name get their gates closed HERE, inside the still-held fence and before
+      // publication. The residual is a strict difference against the early set, so
+      // the two handles are disjoint by construction, and the reconciled handle is
+      // never abortable: a commit already landed.
+      const residualServers = basisSets.mcpServers.filter(server => !normalized.mcpServers.includes(server) && !removedServers.includes(server))
+      let reconciledHandle = null
+      if (residualServers.length) {
+        try {
+          reconciledHandle = drain.begin(residualServers, sessionId)
+        } catch (error) {
+          // The write is already durable: a reconciliation failure must never
+          // become a rejection. Report it and keep what the early handle closed.
+          degraded('drain-reconciliation-degraded', error)
+        }
+      }
       // Re-check the fence before publishing: the lease must still be ours.
       // The revision was already re-checked by the store CAS (expectedRevision).
       if (!fence.isHeld(sessionId)) {
         // The write LANDED but an atomic publication can no longer be
         // guaranteed: stay blocked and let a receipt query publish the
-        // authority from durable evidence.
+        // authority from durable evidence. The entry carries the basis this
+        // transaction would have published with (D4).
         trace('indeterminate', { sessionId, reason: 'fence-lost-before-publish' })
-        blocked.set(sessionId, { lease, requestId: normalized.requestId, prepared, payload, drainHandle, viewOptions })
+        blocked.set(sessionId, { lease, requestId: normalized.requestId, prepared, payload, basisSets, drainHandle, viewOptions })
         return { status: 'indeterminate', step: 5 }
       }
       // Synchronous publication segment: no await between the snapshot swap,
       // the provider invalidation and the fence release. invalidate() must
       // complete before the fence release and before the step-6 response, so
-      // a client that sees the new receipt never refetches a stale list.
-      /** @type {string[]} */
-      const warnings = []
+      // a client that sees the new receipt never refetches a stale list. The
+      // SAME segment runs on the recovery-'published' path (D4).
       trace('snapshot-swap', { sessionId, revision: result.revision })
-      // Task 12.4: the net accepted delta is known only HERE (previous
-      // authority snapshot vs the just-committed payload); notify consumers
-      // queue it for the next safe request. A failed hook warns, never
-      // changes the accepted policy.
-      try {
-        const previous = snapshots.get(sessionId)
-        const names = identities => new Set((Array.isArray(identities) ? identities : []).map(identity => String(identity?.name ?? '')).filter(Boolean))
-        const before = names(previous?.selection?.skills)
-        const after = names(payload?.skills)
-        const beforeMcp = new Set(Array.isArray(previous?.selection?.mcpServers) ? previous.selection.mcpServers : [])
-        const afterMcp = new Set(Array.isArray(payload?.mcpServers) ? payload.mcpServers : [])
-        const delta = {
-          added: [...after].filter(name => !before.has(name)).concat([...afterMcp].filter(name => !beforeMcp.has(name))).sort(),
-          removed: [...before].filter(name => !after.has(name)).concat([...beforeMcp].filter(name => !afterMcp.has(name))).sort(),
-        }
-        if (delta.added.length > 0 || delta.removed.length > 0) onAccepted?.(sessionId, delta)
-      } catch (error) {
-        warnings.push('accepted-notification-degraded')
-        warn(`apply onAccepted hook failed: ${message(error)}`)
-      }
-      snapshots.set(sessionId, { revision: result.revision, selection: structuredClone(payload), handles: prepared.handles, view: prepared.view })
-      // Task 6.1: load the accepted selection into the shared lifecycle
-      // memory snapshot inside the SAME non-async segment, so the
-      // agent/created listener's synchronous read never observes a durable
-      // acceptance this process has not published. A publication failure
-      // degrades to the listener's blocking synchronous disk read of the
-      // just-committed record — reported, never fatal.
-      try {
-        publishSnapshot?.(sessionId, { revision: result.revision, skills: structuredClone(payload.skills), mcpServers: [...payload.mcpServers] })
-      } catch {
-        warnings.push('snapshot-publication-degraded')
-      }
-      try {
-        trace('invalidate', { sessionId })
-        const accepted = provider.acceptSelection(prepared.identities, viewOptions)
-        if (!accepted?.accepted) warnings.push('provider-publication-degraded')
-      } catch {
-        // The record is durably accepted; a failed cache invalidation degrades
-        // convergence, never the policy. The warning is reported, not hidden.
-        warnings.push('invalidate-failed')
-      } finally {
-        trace('fence-release', { sessionId })
-        lease.release()
-      }
+      publishAccepted({
+        sessionId,
+        revision: result.revision,
+        payload,
+        prepared,
+        viewOptions,
+        basisSets,
+        lease,
+        degraded,
+      })
+      // The response's drain snapshot is the union of both closures: the early
+      // one from the transaction-start read and the reconciled one from the
+      // committed-over record. Disjoint by construction; absent when empty.
+      const draining = [
+        ...(drainHandle ? drainHandle.snapshot() : []),
+        ...(reconciledHandle ? reconciledHandle.snapshot() : []),
+      ]
       const response = {
         status: 'applied',
         revision: result.revision,
         receipt: result.receipt,
         effective: { skills: structuredClone(prepared.identities), mcpServers: [...normalized.mcpServers] },
         unresolvedWarnings: normalized.unresolved.map(entry => ({ ...entry })),
-        ...(drainHandle ? { draining: drainHandle.snapshot() } : {}),
+        ...(draining.length ? { draining } : {}),
         ...(warnings.length ? { warnings } : {}),
       }
       trace('response', { sessionId, revision: result.revision })
@@ -482,7 +512,7 @@ export function createApplyEngine(options) {
     const KNOWN_UNCOMMITTED = new Set(['duplicate', 'request-conflict', 'revision-conflict', 'locked', 'unreadable', 'unsupported', 'write-failed'])
     if (!KNOWN_UNCOMMITTED.has(result.status)) {
       trace('indeterminate', { sessionId, status: result.status })
-      blocked.set(sessionId, { lease, requestId: normalized.requestId, prepared, payload, drainHandle, viewOptions })
+      blocked.set(sessionId, { lease, requestId: normalized.requestId, prepared, payload, basisSets: previousSets, drainHandle, viewOptions })
       return { status: 'indeterminate', step: 5 }
     }
     drainHandle?.abort()
@@ -537,6 +567,71 @@ export function createApplyEngine(options) {
     }
   }
 
+  /**
+   * The ONE synchronous publication segment (apply-delta-durable-basis D4),
+   * run by BOTH the committed branch and the recovery-'published' branch:
+   * net delta → notice queue → snapshot swap → lifecycle publication →
+   * provider invalidation → fence release (→ blocked settle on recovery).
+   * No await anywhere in the segment: the atomicity invariant the committed
+   * branch documents (a client that sees the new receipt never refetches a
+   * stale list) holds for a recovered publication too.
+   *
+   * The delta basis is the durable evidence only (D2): `basisSets` is the
+   * accepted state this publication replaces — on the committed path the payload
+   * `store.commit` reports it committed over (read under the commit's own lock),
+   * carried into the recovery path by the blocked entry. It is never the
+   * in-memory snapshots map and never an unlocked re-read. A failed hook
+   * degrades, never changes the accepted policy; per-branch surfacing travels
+   * through `degraded` — the committed branch collects response warnings, the
+   * recovery branch warns only (it has no response payload).
+   *
+   * @param {{ sessionId: string, revision: number, payload: unknown,
+   *   prepared: { handles: unknown[], identities: unknown[], view: unknown },
+   *   viewOptions: unknown,
+   *   basisSets: { skills: unknown[], mcpServers: string[] },
+   *   lease: { release(): void }, settle?: (() => void) | null,
+   *   degraded: (code: string, error?: unknown) => void }} segment
+   */
+  function publishAccepted({ sessionId, revision, payload, prepared, viewOptions, basisSets, lease, settle = null, degraded }) {
+    // Task 12.4: the net accepted delta is known only HERE (durable pre-write
+    // record vs the just-committed payload); notify consumers queue it for
+    // the next safe request. durable-pending-notice D2: the acceptance revision
+    // rides along as a third argument for diagnosis and audit — additive, so
+    // every two-argument collector keeps working.
+    try {
+      const delta = selectionDelta(basisSets, safeSets(payload))
+      if (delta.added.length > 0 || delta.removed.length > 0) onAccepted?.(sessionId, delta, { revision })
+    } catch (error) {
+      degraded('accepted-notification-degraded', error)
+    }
+    snapshots.set(sessionId, { revision, selection: structuredClone(payload), handles: prepared.handles, view: prepared.view })
+    // Task 6.1: load the accepted selection into the shared lifecycle memory
+    // snapshot inside the SAME non-async segment (committed or recovered), so
+    // the agent/created listener's synchronous read never observes a durable
+    // acceptance this process has not published. A publication failure
+    // degrades to the listener's blocking synchronous disk read of the
+    // just-committed record — reported, never fatal.
+    try {
+      const sets = safeSets(payload)
+      publishSnapshot?.(sessionId, { revision, skills: structuredClone(sets.skills), mcpServers: [...sets.mcpServers] })
+    } catch (error) {
+      degraded('snapshot-publication-degraded', error)
+    }
+    try {
+      trace('invalidate', { sessionId })
+      const accepted = provider.acceptSelection(prepared.identities, viewOptions)
+      if (!accepted?.accepted) degraded('provider-publication-degraded')
+    } catch (error) {
+      // The record is durably accepted; a failed cache invalidation degrades
+      // convergence, never the policy. The warning is reported, not hidden.
+      degraded('invalidate-failed', error)
+    } finally {
+      trace('fence-release', { sessionId })
+      lease.release()
+      settle?.()
+    }
+  }
+
   /**
    * Receipt query (tasks 4.4): after a lost response or an indeterminate
    * write, the client enters "result pending confirmation" and queries the
@@ -548,8 +643,12 @@ export function createApplyEngine(options) {
    * the query is serialized behind any in-flight Apply, then settles the
    * pending transaction from durable evidence only —
    * - pending receipt FOUND in a clean record: the write had landed; run the
-   *   publication segment the lost response never ran (snapshot swap,
-   *   provider invalidation, fence release) and report recovery 'published';
+   *   publication segment the lost response never ran — the SAME segment the
+   *   committed path runs (delta → notice queue → snapshot swap → lifecycle
+   *   publication → provider invalidation → fence release, D4), with the
+   *   delta computed against the basis the blocked entry captured (the
+   *   committed-over record when the commit result proved it, D4) — and report
+   *   recovery 'published';
    * - a digest-verified record WITHOUT the pending receipt: durable proof the
    *   write never landed; reopen the drain gates, release the fence and
    *   report recovery 'not-committed' (proven absence, NOT a rollback);
@@ -585,27 +684,27 @@ export function createApplyEngine(options) {
     if (pending) {
       const confirmed = record.kind === 'ok' ? record.receipts.find(entry => entry.requestId === pending.requestId) ?? null : null
       if (confirmed) {
-        // The indeterminate write LANDED: publish the prepared authority and
-        // invalidate the provider BEFORE releasing the fence — the same
-        // ordering the synchronous publication segment guarantees.
+        // The indeterminate write LANDED: run the ONE publication segment the
+        // lost response never ran (D4), delta against the basis the blocked
+        // entry captured included, so the recovered acceptance notifies the
+        // model exactly once (the segment settles the blocked entry).
         trace('recovery-publish', { sessionId, revision: confirmed.revision })
-        snapshots.set(sessionId, { revision: confirmed.revision, selection: structuredClone(pending.payload), handles: pending.prepared.handles, view: pending.prepared.view })
-        // Task 6.1: the recovered publication loads the lifecycle memory
-        // snapshot too — the lost response never ran the segment.
-        try {
-          const sets = safeSets(pending.payload)
-          publishSnapshot?.(sessionId, { revision: confirmed.revision, skills: structuredClone(sets.skills), mcpServers: sets.mcpServers })
-        } catch (error) {
-          warn(`snapshot publication failed: ${message(error)}`)
-        }
-        try {
-          provider.acceptSelection(pending.prepared.identities, pending.viewOptions)
-        } catch (error) {
-          warn(`receipt-recovery invalidate failed: ${message(error)}`)
-        } finally {
-          pending.lease.release()
-          blocked.delete(sessionId)
-        }
+        publishAccepted({
+          sessionId,
+          revision: confirmed.revision,
+          payload: pending.payload,
+          prepared: pending.prepared,
+          viewOptions: pending.viewOptions,
+          basisSets: pending.basisSets,
+          lease: pending.lease,
+          settle: () => blocked.delete(sessionId),
+          // Recovery has no response payload: degradation is warn-only.
+          degraded: (code, error) => {
+            if (code === 'snapshot-publication-degraded') warn(`snapshot publication failed: ${message(error)}`)
+            else if (code === 'invalidate-failed') warn(`receipt-recovery invalidate failed: ${message(error)}`)
+            else warn(`receipt-recovery publication degraded: ${code}${error instanceof Error ? `: ${message(error)}` : ''}`)
+          },
+        })
         recovery = 'published'
         queueMicrotask(() => {
           try { audit?.({ id: sessionId }, APPLY_AUDIT_TYPE, { requestId: confirmed.requestId, revision: confirmed.revision, recovery }) } catch (error) { warn(`apply audit failed: ${message(error)}`) }
@@ -642,17 +741,6 @@ export function createApplyEngine(options) {
   return {
     apply,
     queryReceipt,
-    /**
-     * Shared in-process commit coordinator (tasks 4.5): a content refresh runs
-     * its whole transaction — selection re-check and durable commit — through
-     * the SAME per-session serialization point as selection Applies, so the
-     * two never interleave in-process. Cross-process exclusion stays the
-     * store lock.
-     * @template T
-     * @param {string} sessionId @param {() => Promise<T>} task
-     * @returns {Promise<T>}
-     */
-    coordinate: (sessionId, task) => serialize(sessionId, task),
     /** Synchronous in-memory authority snapshot for a session (null until loaded). */
     authority(sessionId) {
       const snapshot = snapshots.get(sessionId)

package/src/capabilities/defaults-transaction.js

@@ -7,7 +7,9 @@
 // (an explicit empty set is a real, savable choice). The binding is the
 // workspace's stable identity (canonical root path). Save and clear go
 // through the group-2 CAS — a conflict never overwrites.
-import { workspaceKeyOf } from './preset-library.js'
+import { workspaceKeyOf, draftSelectionSets, noWorkspaceError } from './preset-library.js'
+import { resolveSkillNamesForSave } from './initial-selection.js'
+import { isSegment } from './store/paths.js'
 
 /**
  * @param {{ store: { read(unit: unknown): Promise<any>, commit(unit: unknown, expectedRevision: number, mutate: (payload: unknown) => unknown, request?: unknown): Promise<any> },
@@ -58,3 +60,136 @@ export function createDefaultsTransaction({ store, now = Date.now }) {
 
   return { read, save, clear, unitOf, workspaceKeyOf }
 }
+
+// ---- /capabilities default verbs (capabilities-deepening D2) ----------------
+// The three workspace-default verb bodies of the /capabilities command, moved
+// verbatim out of the handler into the module that owns the defaults CAS
+// contract (read/save/clear above). Per-invocation state arrives through the
+// `call` argument ({ agent, options }); the handler's former closures are
+// injected in `wiring` — the payload builder included, so this module keeps
+// its import graph acyclic (read-payloads.js imports this module, never the
+// reverse).
+
+const message = error => (error instanceof Error ? error.message : String(error))
+
+/**
+ * The /capabilities default verb bodies. `wiring`:
+ * @param {{
+ *   openStore: () => any,
+ *   provider: any,
+ *   inventory: (options: any) => Promise<any>,
+ *   lifecycle: any,
+ *   builders: { buildDefaultGetPayload: Function },
+ * }} wiring
+ */
+export function createDefaultsVerbs(wiring) {
+  /**
+   * The sets a save records. from:'applied' is server-authoritative: the sets
+   * come from the same provider/lifecycle state the receipt verb reports —
+   * client-sent set fields are never trusted then.
+   */
+  const selectionSetsOf = async (spec, call) => {
+    if (spec.from === 'applied') {
+      const result = await wiring.provider.list(call.options)
+      const candidates = Array.isArray(result?.candidates) ? result.candidates : []
+      const skills = []
+      for (const candidate of candidates) {
+        if (candidate?.selected && candidate.identity) skills.push(candidate.identity)
+      }
+      const snapshot = wiring.lifecycle?.snapshotFor?.(call.agent.id)
+      return { skills, mcpServers: Array.isArray(snapshot?.mcpServers) ? [...snapshot.mcpServers] : [], unresolvedRefs: [] }
+    }
+    return draftSelectionSets(spec)
+  }
+
+  /**
+   * default-get: thin shell over the shared builder. The no-workspace status
+   * is the ONLY error mapping (the historical noWorkspace object); every
+   * other status — including a non-ok record — stays success.
+   */
+  async function defaultGet(_spec, call) {
+    try {
+      const payload = await wiring.builders.buildDefaultGetPayload({ store: wiring.openStore() }, call.options)
+      if (payload.status === 'no-workspace') return { kind: 'error', text: JSON.stringify(payload) }
+      return { kind: 'success', text: JSON.stringify(payload) }
+    } catch (cause) {
+      return { kind: 'error', text: `capabilities default-get failed: ${message(cause)}` }
+    }
+  }
+
+  /**
+   * default-save: save this workspace's new-session default as a COPY
+   * snapshot of the draft or the applied sets. Saving never changes the
+   * current session; an explicit empty set is a real choice.
+   */
+  async function defaultSave(spec, call) {
+    try {
+      if (spec?.from !== 'draft' && spec?.from !== 'applied') return { kind: 'error', text: 'capabilities default-save: from must be "draft" | "applied"' }
+      const workspaceKey = workspaceKeyOf(call.options)
+      if (!isSegment(workspaceKey)) return noWorkspaceError()
+      const transaction = createDefaultsTransaction({ store: wiring.openStore() })
+      let expectedRevision = spec.expectedRevision
+      if (expectedRevision === undefined) {
+        const current = await transaction.read(workspaceKey)
+        if (current.kind !== 'ok' && current.kind !== 'absent') return { kind: 'error', text: JSON.stringify({ status: current.kind }) }
+        expectedRevision = current.kind === 'ok' ? current.revision : 0
+      }
+      if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+        return { kind: 'error', text: 'capabilities default-save: expectedRevision must be a non-negative integer' }
+      }
+      const sets = await selectionSetsOf(spec, call)
+      let skills = sets.skills
+      if (spec.from === 'draft') {
+        // The draft's wire shape is name strings: resolve them to exact
+        // SkillIdentity objects BEFORE persisting, so the default record
+        // carries the resolved-sets contract and a duplicated name never
+        // lands as an unbindable string. The session's applied selection is
+        // the authoritative disambiguation; unresolvable or still-ambiguous
+        // names are an explicit error with ZERO writes.
+        const inventoryResult = await wiring.inventory(call.options)
+        const inventoryCandidates = Array.isArray(inventoryResult?.candidates) ? inventoryResult.candidates : []
+        const appliedResult = await wiring.provider.list(call.options)
+        const appliedCandidates = Array.isArray(appliedResult?.candidates) ? appliedResult.candidates : []
+        const appliedIdentities = []
+        for (const candidate of appliedCandidates) {
+          if (candidate?.selected && candidate.identity) appliedIdentities.push(candidate.identity)
+        }
+        const resolved = resolveSkillNamesForSave(spec.skills, inventoryCandidates, appliedIdentities)
+        if (resolved.missing.length > 0) return { kind: 'error', text: JSON.stringify({ status: 'missing', missing: resolved.missing }) }
+        if (resolved.ambiguous.length > 0) return { kind: 'error', text: JSON.stringify({ status: 'ambiguous', ambiguous: resolved.ambiguous }) }
+        skills = resolved.identities
+      }
+      const result = await transaction.save({ workspaceKey, expectedRevision, snapshot: { skills, mcpServers: sets.mcpServers, unresolvedRefs: sets.unresolvedRefs } })
+      return { kind: 'success', text: JSON.stringify({ ...result, workspaceKey }) }
+    } catch (cause) {
+      return { kind: 'error', text: `capabilities default-save failed: ${message(cause)}` }
+    }
+  }
+
+  /**
+   * default-clear: clear this workspace's default (absent afterwards — NOT
+   * an explicit empty set). The JSON payload is optional.
+   */
+  async function defaultClear(spec = {}, call) {
+    try {
+      const workspaceKey = workspaceKeyOf(call.options)
+      if (!isSegment(workspaceKey)) return noWorkspaceError()
+      const transaction = createDefaultsTransaction({ store: wiring.openStore() })
+      let expectedRevision = spec.expectedRevision
+      if (expectedRevision === undefined) {
+        const current = await transaction.read(workspaceKey)
+        if (current.kind !== 'ok' && current.kind !== 'absent') return { kind: 'error', text: JSON.stringify({ status: current.kind }) }
+        expectedRevision = current.kind === 'ok' ? current.revision : 0
+      }
+      if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+        return { kind: 'error', text: 'capabilities default-clear: expectedRevision must be a non-negative integer' }
+      }
+      const result = await transaction.clear({ workspaceKey, expectedRevision })
+      return { kind: 'success', text: JSON.stringify({ ...result, workspaceKey }) }
+    } catch (cause) {
+      return { kind: 'error', text: `capabilities default-clear failed: ${message(cause)}` }
+    }
+  }
+
+  return { 'default-get': defaultGet, 'default-save': defaultSave, 'default-clear': defaultClear }
+}