weir-harness 1.2.0 → 1.2.2

package/src/blackboard/kernel.js

@@ -12,6 +12,20 @@
 // wire delivery. The kernel is concept-isomorphic to Edit Lock but shares
 // none of its code: no persistence, no recovery, no cross-process story.
 
+/**
+ * One live write token; `timer` is the injected timer handle (opaque here).
+ * @typedef {{ key: string, holder: string, expiresAt: number, timer: unknown }} Token
+ * One registered subscription row (rebuilt from the owning runtime's snapshot).
+ * @typedef {{ key: string, subscriberIds: string[] }} Subscription
+ * The release-event shape every listener receives (slice 2 delivery wiring).
+ * @typedef {{ boardId: string, key: string, holder: string, reason: 'write' | 'delete' | 'expire' | 'terminate', subscriberIds: string[], at: number }} ReleaseEvent
+ * A release listener; onRelease returns the matching unregister.
+ * @typedef {(event: ReleaseEvent) => void} ReleaseListener
+ * One board's volatile state: durable entries plus the arbitration maps.
+ * @typedef {{ entries: Map<string, object>, tokens: Map<string, Token>, subscribers: Map<string, Set<string>> }} BoardState
+ * The runtime snapshot `restore` rebuilds a board's volatile state from.
+ * @typedef {{ tokens: Token[], subscriptions: Subscription[] }} RuntimeState
+ */
 /** The closed entry-type taxonomy (D4); schema `enum` and runtime both pin it. */
 export const ENTRY_TYPES = Object.freeze(['map', 'contract', 'deadend', 'wiring', 'recipe', 'why'])
 
@@ -101,9 +115,9 @@ export function createBlackboardKernel({ now = Date.now, setTimer, clearTimer }
   })
   const disarm = clearTimer ?? ((/** @type {any} */ handle) => globalThis.clearTimeout(handle))
 
-  /** @type {Map<string, { entries: Map<string, object>, tokens: Map<string, object>, subscribers: Map<string, Set<string>> }>} */
+  /** @type {Map<string, BoardState>} */
   const boards = new Map()
-  /** @type {Set<(event: object) => void>} release listeners (slice 2 delivery wiring) */
+  /** @type {Set<ReleaseListener>} release listeners (slice 2 delivery wiring) */
   const listeners = new Set()
 
   /** @param {string} boardId @returns {any} the board, created lazily */
@@ -122,7 +136,7 @@ export function createBlackboardKernel({ now = Date.now, setTimer, clearTimer }
    * best-effort and NEVER breaks arbitration; events only fire when someone
    * actually waits (subscriberIds non-empty) so slice 2 gets a signal, not
    * noise.
-   * @param {object} event
+   * @param {ReleaseEvent} event
    */
   function fireRelease(event) {
     if (!Array.isArray(event.subscriberIds) || event.subscriberIds.length === 0) return
@@ -153,7 +167,7 @@ export function createBlackboardKernel({ now = Date.now, setTimer, clearTimer }
     const state = boards.get(boardId)
     const token = state?.tokens.get(key)
     if (!token || token.expiresAt > at) return
-    state.tokens.delete(key)
+    /** @type {BoardState} */ (state).tokens.delete(key)
     if (token.timer !== undefined) disarm(token.timer)
     release(state, boardId, key, token.holder, 'expire', at)
   }
@@ -438,11 +452,14 @@ export function createBlackboardKernel({ now = Date.now, setTimer, clearTimer }
 
     // Internal transaction seam. Only entries are durable; authority comes
     // exclusively from the owning runtime's snapshot, never from disk.
+    /**
+     * @param {string} boardId @param {any} entries @param {RuntimeState} [runtime]
+     */
     restore(boardId, entries, runtime = { tokens: [], subscriptions: [] }) {
       const state = board(boardId)
       state.entries = new Map(entries.map(entry => [entry.key, structuredClone(entry)]))
-      state.tokens = new Map(runtime.tokens.map(token => [token.key, { ...token }]))
-      state.subscribers = new Map(runtime.subscriptions.map(row => [row.key, new Set(row.subscriberIds)]))
+      state.tokens = new Map(runtime.tokens.map(token => /** @type {[string, Token]} */ ([token.key, { ...token }])))
+      state.subscribers = new Map(runtime.subscriptions.map(row => /** @type {[string, Set<string>]} */ ([row.key, new Set(row.subscriberIds)])))
     },
 
     expire(boardId, at = now()) {

package/src/blackboard/notify.js

@@ -32,6 +32,12 @@ export const RELEASE_NOTICE_PREFIX = 'Blackboard notice'
 /** Delivery attempts before the final failure is logged and dropped. */
 export const MAX_DELIVERY_ATTEMPTS = 3
 
+/**
+ * The subagent delivery face a between-turns subscriber is reached through: asserted
+ * present on the one path that needs it (no runtime guard is added, design D6).
+ * @typedef {{ sendMessage: (parent: any, childId: string, blocks: Array<{ type: string, text: string }>, options: object) => unknown }} SubagentSendFace
+ */
+
 /**
  * The human-readable release clause per reason. Instance content (the key) is
  * embedded verbatim; the template is English.
@@ -117,7 +123,7 @@ export function createReleaseNotifier({ agents, parentOf, subagents, logger, set
    * the live agent works, followup when it is idle, and — for a delegated
    * child whose agent handle is dropped between turns — the subagents channel
    * through its live parent.
-   * @param {string} subscriberId @param {object} message @param {number} attempt
+   * @param {string} subscriberId @param {{ content: Array<{ type: string, text: string }> }} message @param {number} attempt
    */
   function deliver(subscriberId, message, attempt) {
     const agent = safeGet(agents, subscriberId)
@@ -137,7 +143,7 @@ export function createReleaseNotifier({ agents, parentOf, subagents, logger, set
       }
       const parent = typeof parentId === 'string' && parentId.length > 0 ? safeGet(agents, parentId) : undefined
       if (!parent) throw new Error(`subscriber "${subscriberId}" is between turns and its parent agent is unavailable`)
-      return channel.sendMessage(parent, subscriberId, [{ type: 'text', text: message.content[0].text }], { signal: new AbortController().signal })
+      return /** @type {SubagentSendFace} */ (channel).sendMessage(parent, subscriberId, [{ type: 'text', text: message.content[0].text }], { signal: new AbortController().signal })
     }, (error) => {
       logger?.warn?.(`blackboard: release notice delivery to "${subscriberId}" failed after ${MAX_DELIVERY_ATTEMPTS} attempts: ${error?.message ?? error}`)
     })
@@ -145,7 +151,8 @@ export function createReleaseNotifier({ agents, parentOf, subagents, logger, set
 
   return (event) => {
     if (!Array.isArray(event.subscriberIds) || event.subscriberIds.length === 0) return
-    const message = userTextMessage(renderReleaseNotice(event), RELEASE_SOURCE_KIND)
+    // userTextMessage declares only `object`; assert the shape deliver reads (S13 UserMessage contract).
+    const message = /** @type {{ content: Array<{ type: string, text: string }> }} */ (userTextMessage(renderReleaseNotice(event), RELEASE_SOURCE_KIND))
     for (const subscriberId of event.subscriberIds) {
       if (typeof subscriberId !== 'string' || subscriberId.length === 0) continue
       deliver(subscriberId, message, 1)

package/src/blackboard/remote.js

@@ -84,7 +84,7 @@ const BLACKBOARD_REMOTE_PACKAGE = 'weir-blackboard'
  */
 export class BlackboardRemoteError extends Error {
   /**
-   * @param {'bridge-absent' | 'unknown-session' | 'payload-failed'} code
+   * @param {'bridge-absent' | 'unknown-session' | 'payload-failed' | 'channel-unavailable'} code
    * @param {string} message
    * @param {{ cause?: unknown }} [options]
    */
@@ -96,29 +96,47 @@ export class BlackboardRemoteError extends Error {
 }
 
 /**
- * The bridge: exactly one blackboard plugin mounts per composition (per
- * process), and every consumer is the same bundle module instance — the same
- * module-level slot pattern as the capability read bridge. Faces:
+ * The bridge: EVERY mounted blackboard plugin feeds this module-level slot,
+ * and every consumer is the same bundle module instance. The preset registry
+ * eagerly mounts BOTH declared presets (weir and weir-creative) at profile
+ * load, so two blackboard mounts feeding this bridge is the permanent steady
+ * state — ownership is a LIVE-FEED STACK: the latest live feed serves, a
+ * feed's unregister removes only itself and restores the previous live feed,
+ * and only an empty stack surfaces as bridge-absent. (The sibling capability
+ * read bridge keys its feeds by preset instead: its reads route by the
+ * session's exact projected preset, while blackboard calls carry no routing
+ * dimension and the two presets' faces are equivalent today.)
+ * Faces:
  *   kernel()  — the shared arbitration kernel (list/read/apply/write/deleteKey)
  *   boardOf(agent) — conversation-root board id for an agent handle
  *   rootOf(sessionId) — conversation-root session id for a BARE session id
  *   ttlMs()   — the settings-driven write-token TTL in milliseconds
  */
-let bridgeFaces = null
+/** The faces every live feed provides. `run` is the mount's lifecycle gate (apply/write/delete through one admission), `requestPromotion` the slice-3 promotion requester, and `boardOf` may await that same gate. @typedef {{ kernel: any, boardOf: (agent: any) => string | undefined | Promise<string | undefined>, rootOf?: (sessionId: string) => Promise<string>, ttlMs: () => number, run?: (agent: any, action: (root: string) => any) => Promise<any>, requestPromotion?: (agent: any) => Promise<unknown> }} BridgeFaces */
+/** @type {Array<{ faces: BridgeFaces }>} Live feeds in feed order; the stack top serves. */
+const bridgeStack = []
 
 /**
- * Feed the bridge (blackboard plugin apply). Returns the unregister the plugin
- * disposes with its own lifecycle.
- * @param {{ kernel: any, boardOf: (agent: any) => string | undefined, rootOf?: (sessionId: string) => Promise<string>, ttlMs: () => number }} faces
+ * Feed the bridge (blackboard plugin apply): push a unique token onto the
+ * live-feed stack and return the unregister the plugin disposes with its own
+ * lifecycle. The unregister removes exactly its own token — removing the
+ * serving token restores the previous live feed — and a repeated call is a
+ * no-op.
+ * @param {BridgeFaces} faces
  */
 export function feedBlackboardRemoteBridge(faces) {
-  bridgeFaces = faces
-  return () => { if (bridgeFaces === faces) bridgeFaces = null }
+  const token = { faces }
+  bridgeStack.push(token)
+  return () => {
+    const at = bridgeStack.indexOf(token)
+    if (at >= 0) bridgeStack.splice(at, 1)
+  }
 }
 
-/** Current bridge faces, or null when unmounted. */
+/** Current bridge faces: the latest live feed's, or null when no live feed remains (the one true bridge-absent). */
 export function blackboardRemoteBridge() {
-  return bridgeFaces
+  const top = bridgeStack[bridgeStack.length - 1]
+  return top ? top.faces : null
 }
 
 /** Strip one kernel row to the pinned wire entry shape (summary is a free-text string, content optional, the promoted marker rides along when present). */
@@ -165,7 +183,7 @@ export function createBlackboardRemoteService(dependencies = {}) {
   /**
    * Resolve the acting session and its board from the wire agent.
    * @param {any} agent
-   * @returns {{ sessionId: string, boardId: string, faces: { kernel: any, boardOf: Function, ttlMs: Function } }}
+   * @returns {Promise<{ sessionId: string, boardId: string | undefined, faces: BridgeFaces }>}
    */
   async function resolveActing(agent) {
     if (!ensure()) throw new BlackboardRemoteError('channel-unavailable', 'blackboard remote is not registered with the gateway')

package/src/blackboard/storage.js

@@ -12,7 +12,9 @@ export const LOG = /^session\.v([1-9][0-9]*)\.jsonl(?:\.zstd)?$/
 const SIDE = /^session\.v[1-9][0-9]*\.jsonl(?:\.zstd)?_bb$/
 const ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/
 const LOCK = 'weir-blackboard.lock'
-const uid = () => process.getuid?.()
+// The checked graph's global `process` contract (capabilities/store/checked-contract.d.ts)
+// is narrow by design; getuid is optional here and asserted locally (kernel.js:99 precedent).
+const uid = () => /** @type {any} */ (process).getuid?.()
 const code = error => error?.code
 const pause = ms => new Promise(resolve => setTimeout(resolve, ms))
 
@@ -55,11 +57,11 @@ export async function locateSession(home, id, expectedCwd) {
     const logs = (await fs.readdir(dir)).filter(name => LOG.test(name))
     // Highest generation is DSH's canonical selection. Same-version physical
     // encodings are ambiguous: never guess which installation owns the log.
-    if (logs.some(name => !Number.isSafeInteger(Number(LOG.exec(name)[1])))) throw new Error('blackboard: unsupported canonical generation number')
-    logs.sort((a, b) => Number(LOG.exec(b)[1]) - Number(LOG.exec(a)[1]))
+    if (logs.some(name => !Number.isSafeInteger(Number(/** @type {RegExpExecArray} */ (LOG.exec(name))[1])))) throw new Error('blackboard: unsupported canonical generation number')
+    logs.sort((a, b) => Number(/** @type {RegExpExecArray} */ (LOG.exec(b))[1]) - Number(/** @type {RegExpExecArray} */ (LOG.exec(a))[1]))
     if (!logs.length) continue
     const name = logs[0]
-    if (logs[1] && LOG.exec(logs[1])[1] === LOG.exec(name)[1]) throw new Error('blackboard: ambiguous canonical log')
+    if (logs[1] && /** @type {RegExpExecArray} */ (LOG.exec(logs[1]))[1] === /** @type {RegExpExecArray} */ (LOG.exec(name))[1]) throw new Error('blackboard: ambiguous canonical log')
     const path = join(dir, name)
     await trusted(path)
     const handle = await fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
@@ -70,7 +72,7 @@ export async function locateSession(home, id, expectedCwd) {
       const text = name.endsWith('.zstd') ? zstdDecompressSync(bytes).toString('utf8') : bytes.toString('utf8')
       header = JSON.parse(text.split('\n')[0])
     } catch { throw new Error('blackboard: unreadable Session header') }
-    if (header.type !== 'session' || header.id !== id || typeof header.cwd !== 'string' || !isAbsolute(header.cwd) || header.version !== Number(LOG.exec(name)[1]) || expectedCwd !== undefined && header.cwd !== expectedCwd) throw new Error('blackboard: Session header identity/cwd mismatch')
+    if (header.type !== 'session' || header.id !== id || typeof header.cwd !== 'string' || !isAbsolute(header.cwd) || header.version !== Number(/** @type {RegExpExecArray} */ (LOG.exec(name))[1]) || expectedCwd !== undefined && header.cwd !== expectedCwd) throw new Error('blackboard: Session header identity/cwd mismatch')
     matches.push({ id, dir, log: path, file: join(dir, name + '_bb'), header })
   }
   if (matches.length !== 1) throw new Error(`blackboard: ${matches.length ? 'ambiguous Session directories' : 'durable Session log unavailable; sidecars preserved'}`)
@@ -102,6 +104,12 @@ function dead(owner) {
 const ownerKey = Symbol.for('weir.blackboard.storage.owner.v1')
 const writerToken = globalThis[ownerKey] ??= randomUUID()
 
+/**
+ * @param {object} [dependencies] test seams
+ * @param {string} [dependencies.home] profile home; locateSession fail-closes on an unusable value
+ * @param {(op: string, path: string) => unknown} [dependencies.hook] maintenance fault-injection seam
+ * @param {number} [dependencies.timeoutMs] writer-lock acquisition budget
+ */
 export function createBlackboardStorage({ home, hook = async (_op, _path) => {}, timeoutMs = 5000 } = {}) {
   const queue = new Map()
   async function safeRead(path) {