weir-harness 1.2.2 → 2.0.0

package/src/edit-lock/settle.js

@@ -1,144 +0,0 @@
-/** Turn-end settling of still-held locks (design D2/D3).
- *
- * A finished turn that leaves locks unreleased is not an error, it is unfinished
- * business: the model decides whether each file is really done with. So the
- * session is continued once with a notice that asks for exactly one of two
- * things — release the lock, or ask explicitly to keep it for a bounded period.
- *
- * Only the durable `completed` reason enters this path. A provider error keeps its
- * cleanup-only recovery and a user stop keeps its latch: neither is nudged, and
- * classification still reads nothing but the turn/end reason (AGENTS §3.5).
- *
- * The notice count is bounded and configurable, and the disposition after it runs
- * out is configurable too (`release` or `abnormal`). Both are policy supplied by
- * the caller, so this module holds no configuration and no clock.
- */
-
-/** @param {{reason?: {kind?: string}}[]} locks @param {number} attempt @param {number} maxAttempts @param {{defaultMinutes: number, singleMaxMinutes: number, cumulativeMaxMinutes: number, remainingMinutes: number, unavailable?: boolean}} budget */
-export function settlementPrompt(locks, attempt, maxAttempts, budget) {
-  const lines = locks.map(lock => `- ${lock.resourceId}`)
-  // With the batch budget gone there is only one honest instruction left, so the
-  // hold option is not mentioned at all rather than offered and then refused.
-  const option = budget.unavailable
-    ? 'Retention is unavailable because its settings conflict, so no reservation can be made: release each file (edit_lock_release).'
-    : budget.remainingMinutes <= 0
-    ? `This batch has used its whole retention budget (${budget.cumulativeMaxMinutes} minutes), so no new reservation is available: release each file (edit_lock_release).`
-    : `For each file, either release it because you are done with it (edit_lock_release), or ask to keep ownership for a bounded time (edit_lock_hold, at most ${budget.singleMaxMinutes} minutes per request and ${budget.remainingMinutes} minutes left in this batch).`
-  return [
-    `Edit Lock: the turn ended while this session still held ${locks.length} file(s):`,
-    ...lines,
-    option,
-    `Do not edit other files to work around this. A file you leave unresolved after ${maxAttempts} notice(s) is handled for you.`,
-    `This is notice ${attempt} of ${maxAttempts}.`,
-  ].join('\n')
-}
-
-/** @param {{
- *   domainFor: (agent: object) => Promise<any> | undefined,
- *   followup: (agent: object, text: string) => void,
- *   notify: (agent: object, text: string) => void,
- *   limits: () => {holdDefaultMinutes: number, holdSingleMaxMinutes: number, holdCumulativeMaxMinutes: number, nudgeAttempts: number, nudgeFallback: 'release'|'abnormal'},
- *   now?: () => number,
- *   onSettled?: (agent: object) => void,
- *   warn?: (message: string) => void,
- * }} options */
-export function createSettlementDriver(options) {
-  const now = options.now ?? Date.now
-  let closed = false
-  /** Notices already sent for the current batch of one agent. In-memory on
-   * purpose: a restart restores the session as interrupted and takes the
-   * cleanup route instead, so a lost counter cannot loop. @type {WeakMap<object, number>} */
-  const notices = new WeakMap()
-  /** @type {Set<Promise<unknown>>} */
-  const running = new Set()
-  /** Agents whose next turn is the settle follow-up itself. @type {WeakSet<object>} */
-  const nudged = new WeakSet()
-
-  /** The notice counter is keyed by the live agent object, so a non-object key can
-   * never be remembered. Making that explicit turns a caller mistake into a clear
-   * failure instead of a silent "nothing happened". @param {unknown} agent */
-  function remember(agent) {
-    if (!agent || (typeof agent !== 'object' && typeof agent !== 'function')) {
-      throw new Error('settlement requires a live agent object')
-    }
-  }
-  /** @param {object} agent */
-  function forget(agent) {
-    if (!agent || typeof agent !== 'object') return
-    notices.delete(agent)
-    nudged.delete(agent)
-  }
-
-  /** @param {object} agent @param {any} domain @param {any[]} locks */
-  async function dispose(agent, domain, locks) {
-    const limits = options.limits()
-    if (limits.nudgeFallback === 'abnormal') {
-      // The team asked for human handling: keep the locks, never silently free them.
-      const marked = await domain.classifyAbnormal(agent, 'unsettled-after-notices')
-      options.notify(agent, `Edit Lock: ${marked.length} file(s) stayed locked and are now flagged for the user to sort out in the Edit Lock panel.`)
-    } else {
-      const { released } = await domain.releaseHeld(agent)
-      options.notify(agent, released.length
-        ? `Edit Lock: ${released.length} file(s) stayed locked after ${limits.nudgeAttempts} notice(s), so they were released for other sessions.`
-        : 'Edit Lock: no file is held any more.')
-    }
-    forget(agent)
-  }
-
-  /** @param {object} agent @param {any} domain */
-  async function settle(agent, domain) {
-    remember(agent)
-    const status = await domain.status(agent)
-    // Only ordinary ownership counts. Abnormal and interrupted locks have their
-    // own paths, and a pending confirmation already requires a human.
-    const held = status.locks.filter(lock => lock.status === 'active')
-    if (held.length === 0) { forget(agent); return }
-    const limits = options.limits()
-    const retention = status.retention ?? { held: false, remainingMs: 0, holdCumulativeMs: 0 }
-    // Already reserved and still inside its period: nothing to ask, and the
-    // expiry timer owns what happens next.
-    if (retention.held && retention.remainingMs > 0) return
-    const attempts = notices.get(agent) ?? 0
-    if (attempts >= limits.nudgeAttempts) { await dispose(agent, domain, held); return }
-    notices.set(agent, attempts + 1)
-    // The follow-up starts a turn of its own; that turn must not count as the
-    // holder getting back to work, or the count would reset forever.
-    nudged.add(agent)
-    const remainingMinutes = Math.max(0, Math.floor((limits.holdCumulativeMaxMinutes * 60_000 - retention.holdCumulativeMs) / 60_000))
-    options.followup(agent, settlementPrompt(held, attempts + 1, limits.nudgeAttempts, {
-      defaultMinutes: limits.holdDefaultMinutes,
-      singleMaxMinutes: limits.holdSingleMaxMinutes,
-      cumulativeMaxMinutes: limits.holdCumulativeMaxMinutes,
-      remainingMinutes,
-      unavailable: limits.holdUnavailable === true,
-    }))
-  }
-
-  return Object.freeze({
-    /** Durable turn/end feed for one agent. @param {object} agent @param {any} reason */
-    onTurnEnd(agent, reason) {
-      if (closed || reason?.kind !== 'completed') return
-      const domain = options.domainFor(agent)
-      if (!domain) return
-      const job = Promise.resolve(domain)
-        .then(resolved => (resolved ? settle(agent, resolved) : undefined))
-        .catch(error => options.warn?.(`edit lock settlement failed: ${error?.message ?? error}`))
-        .finally(() => running.delete(job))
-      running.add(job)
-    },
-    /** The holder started a new turn, so the batch is in use again: the notice
-     * budget restarts. Without this a long session would run out of notices over
-     * unrelated turns. @param {object} agent */
-    turnStarted(agent) {
-      if (agent && typeof agent === 'object' && nudged.delete(agent)) return
-      forget(agent)
-    },
-    /** The expiry timer released the batch: nothing left to settle. @param {object} agent */
-    settled(agent) { forget(agent) },
-    /** @param {object} agent */
-    noticeCount(agent) { return notices.get(agent) ?? 0 },
-    /** Host shutdown waits for in-flight settlement instead of dropping it. */
-    async drain() { await Promise.allSettled([...running]) },
-    close() { closed = true },
-  })
-}

package/src/edit-lock/snapshot.js

@@ -1,175 +0,0 @@
-// Pure durable-image validation shared by the authority store and the
-// read-only maintenance inspector. Everything here is a function of its
-// arguments: no filesystem access, no clock, no ctx. `parseSnapshot` performs
-// EXACTLY the checks the store's recover path always performed (same order,
-// same messages) so an inspection verdict can never diverge from what a real
-// recover would accept — corruption is reported, never repaired.
-import { createHash } from 'node:crypto'
-import { validateOperations } from './operation-history.js'
-import { validateAdminLedger } from './admin-ledger.js'
-import { validateIncarnations } from './incarnations.js'
-
-/**
- * @typedef {import('./store.js').AuthorityImage} AuthorityImage
- * @typedef {{ revision: number, state: AuthorityImage }} Snapshot
- */
-
-/** @param {unknown} condition @param {string} message @returns {asserts condition} */
-function valid(condition, message) {
-  if (!condition) throw new Error(`invalid ${message}`)
-}
-/** @param {unknown} value @returns {value is string} */
-function id(value) { return typeof value === 'string' && value.length > 0 }
-/** @param {unknown} value @param {number} [minimum] @returns {value is number} */
-function integer(value, minimum = 0) { return typeof value === 'number' && Number.isSafeInteger(value) && !Object.is(value, -0) && value >= minimum }
-/** @param {unknown} value @param {string[]} keys @returns {asserts value is Record<string, unknown>} */
-function shape(value, keys) {
-  valid(value !== null && typeof value === 'object' && !Array.isArray(value), 'object')
-  valid(Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null, 'object prototype')
-  valid(Reflect.ownKeys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key)), 'schema keys')
-  for (const key of keys) {
-    const descriptor = Object.getOwnPropertyDescriptor(value, key)
-    valid(descriptor && 'value' in descriptor && descriptor.enumerable, 'data property')
-  }
-}
-
-/** Deterministic JSON: UTF-16 key order, JSON scalar spelling, no whitespace.
- * Array order is retained (including the historical image's ordered collections).
- * @param {unknown} value @returns {string} */
-export function canonical(value) {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
-  if (value !== null && typeof value === 'object') {
-    const object = /** @type {Record<string, unknown>} */ (value)
-    return `{${Object.keys(object).sort().map(key => `${JSON.stringify(key)}:${canonical(object[key])}`).join(',')}}`
-  }
-  return JSON.stringify(value)
-}
-
-/** Lossless v2 -> v3 upgrade: add one empty retention row per known session.
- * @param {any} state @returns {any} */
-export function upgradeFromV2(state) {
-  valid(state && typeof state === 'object' && !Array.isArray(state) && !Object.hasOwn(state, 'holds') && state.version === 2, 'v2 image')
-  valid(Array.isArray(state.sessions), 'v2 sessions')
-  const holds = state.sessions.map((/** @type {any} */ session) => ({ sessionId: session?.sessionId, holding: false, holdUntil: null, holdCumulativeMs: 0 }))
-  const { version: _v, operations, ...rest } = state
-  return { ...rest, version: 3, holds, operations }
-}
-
-/** Lossless v3 -> v4: historical assertions remain inert, never upgraded to proof.
- * @param {any} state @returns {AuthorityImage} */
-export function upgradeFromV3(state) {
-  valid(state?.version === 3 && Array.isArray(state.operations), 'v3 image')
-  for (const operation of state.operations) {
-    valid(Array.isArray(operation.closeouts), 'v3 closeouts')
-    for (const closeout of operation.closeouts) shape(closeout, ['kind', 'assertionId'])
-  }
-  return { ...state, version: 4 }
-}
-
-/** @param {AuthorityImage} state */
-export function validateImage(state) {
-  shape(state, ['version', 'managerIncarnation', 'sessions', 'generations', 'locks', 'issuedRequests', 'recovery', 'holds', 'operations', ...(state.version === 5 ? ['adminRecoveries'] : []), ...(state.version === 6 ? ['adminRecoveries', 'incarnations'] : [])])
-  valid(state.version === 4 || state.version === 5 || state.version === 6, `image version ${state.version}; expected 4, 5 or 6`)
-  valid(state.managerIncarnation === null || id(state.managerIncarnation), 'incarnation')
-  for (const collection of [state.sessions, state.generations, state.locks, state.issuedRequests, state.recovery, state.holds]) {
-    valid(Array.isArray(collection) && Object.getPrototypeOf(collection) === Array.prototype, 'collection')
-    valid(Reflect.ownKeys(collection).length === collection.length + 1, 'dense collection keys')
-    for (let i = 0; i < collection.length; i++) {
-      const descriptor = Object.getOwnPropertyDescriptor(collection, i)
-      valid(descriptor && 'value' in descriptor && descriptor.enumerable, 'collection data property')
-    }
-  }
-  valid(state.managerIncarnation !== null || [state.sessions, state.generations, state.locks, state.issuedRequests, state.recovery, state.holds, state.operations].every(list => list.length === 0), 'null incarnation with history')
-  const sessions = new Map(state.sessions.map(session => {
-    shape(session, ['sessionId', 'executionEpoch', 'interrupted'])
-    valid(id(session.sessionId) && integer(session.executionEpoch, 1) && typeof session.interrupted === 'boolean', 'session')
-    return [session.sessionId, session]
-  }))
-  valid(sessions.size === state.sessions.length, 'duplicate session')
-  // Retention is a session-level budget (design D1): one row per session, only for
-  // sessions the image knows, and the cumulative allowance is a lifetime charge
-  // that is never refunded.
-  const holds = new Map()
-  for (const held of state.holds) {
-    shape(held, ['sessionId', 'holding', 'holdUntil', 'holdCumulativeMs'])
-    valid(sessions.has(held.sessionId) && !holds.has(held.sessionId), 'hold reference')
-    valid(typeof held.holding === 'boolean' && integer(held.holdCumulativeMs), 'hold flags')
-    valid(held.holdUntil === null || integer(held.holdUntil, 1), 'hold expiry')
-    valid(held.holding ? held.holdUntil !== null : held.holdUntil === null, 'hold expiry coherence')
-    holds.set(held.sessionId, held)
-  }
-  for (const session of state.sessions) valid(holds.has(session.sessionId), 'missing hold row')
-  const generations = new Map(state.generations.map(entry => {
-    shape(entry, ['resourceId', 'generation'])
-    valid(id(entry.resourceId) && integer(entry.generation, 1), 'generation')
-    return [entry.resourceId, entry.generation]
-  }))
-  valid(generations.size === state.generations.length, 'duplicate generation')
-  // A session whose last lock is gone has no batch left: the row stays (one row per
-  // session) but must be back at zero, so a stale allowance cannot survive a batch.
-  for (const held of state.holds) {
-    if (state.locks.some(lock => lock.owner === held.sessionId)) continue
-    valid(!held.holding && held.holdUntil === null && held.holdCumulativeMs === 0, 'hold without a lock')
-  }
-  const resources = new Set()
-  for (const lock of state.locks) {
-    shape(lock, lock.status === 'abnormal' ? ['resourceId', 'owner', 'generation', 'status', 'reason'] : ['resourceId', 'owner', 'generation', 'status'])
-    valid(id(lock.resourceId) && id(lock.owner) && integer(lock.generation, 1), 'lock')
-    const session = sessions.get(lock.owner)
-    valid(session && generations.get(lock.resourceId) === lock.generation && !resources.has(lock.resourceId), 'lock reference')
-    resources.add(lock.resourceId)
-    valid(['active', 'user-interrupted', 'pending-confirmation', 'abnormal'].includes(lock.status), 'lock status')
-    if (lock.status === 'abnormal') valid(id(lock.reason), 'abnormal reason')
-    else valid(session.interrupted === (lock.status === 'user-interrupted'), 'lock interruption')
-  }
-  const requests = new Set()
-  for (const request of state.issuedRequests) {
-    shape(request, ['sessionId', 'requestId'])
-    valid(sessions.has(request.sessionId) && id(request.requestId), 'issued request')
-    const key = canonical([request.sessionId, request.requestId])
-    valid(!requests.has(key), 'duplicate request')
-    requests.add(key)
-  }
-  const recoveries = new Set()
-  for (const recovery of state.recovery) {
-    shape(recovery, ['sessionId', 'attempts', 'elapsedMs', 'pauseMs'])
-    valid(sessions.has(recovery.sessionId) && !recoveries.has(recovery.sessionId), 'recovery reference')
-    valid(integer(recovery.attempts) && integer(recovery.elapsedMs) && integer(recovery.pauseMs), 'recovery counters')
-    recoveries.add(recovery.sessionId)
-  }
-  validateAdminLedger(state)
-  validateOperations(state)
-  if (state.version === 6) validateIncarnations(state)
-}
-
-/**
- * Parse and validate one committed snapshot's raw bytes for `domainId`.
- * Byte-for-byte the store recover path's validation, in the same order with
- * the same refusal messages; the caller supplies the bytes, so a read-only
- * inspection runs no store, no recovery and no reservation. Throws on any
- * deviation — the caller decides how corruption is surfaced; nothing here
- * repairs, rewrites or upgrades the file on disk.
- * @param {Buffer} bytes @param {string} domainId @returns {Snapshot}
- */
-export function parseSnapshot(bytes, domainId) {
-  const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
-  const envelope = JSON.parse(text)
-  // Exact byte equality rejects duplicate keys at every depth as well as
-  // alternate number/escape spellings, whitespace and reordered keys.
-  valid(Buffer.from(canonical(envelope)).equals(bytes), 'noncanonical snapshot')
-  shape(envelope, ['payload', 'checksum'])
-  const payload = envelope.payload
-  shape(payload, ['version', 'domainId', 'revision', 'state'])
-  valid(typeof payload.version === 'number' && [2, 3, 4, 5, 6].includes(payload.version), `snapshot version ${payload.version}; supported: 2, 3, 4, 5, 6; recover with a newer build or restore a pre-upgrade snapshot`)
-  valid(payload.domainId === domainId, 'snapshot domain')
-  valid(payload.state !== null && typeof payload.state === 'object' && 'version' in payload.state && payload.state.version === payload.version, 'snapshot/image version mismatch')
-  valid(integer(payload.revision), 'snapshot revision')
-  valid(typeof envelope.checksum === 'string' && envelope.checksum === createHash('sha256').update(canonical(payload)).digest('hex'), 'snapshot checksum')
-  // Verify legacy closeout shapes before upgrading: new semantics must never
-  // be smuggled into an old image. Integrity above is against the original bytes.
-  const legacy = payload.version === 2 ? upgradeFromV2(payload.state) : payload.state
-  const state = /** @type {AuthorityImage} */ (payload.version < 4 ? upgradeFromV3(legacy) : legacy)
-  validateImage(state)
-  for (const row of state.adminRecoveries ?? []) valid(row.root === domainId && row.committedRevision <= payload.revision, 'administrative domain/revision')
-  return { revision: payload.revision, state }
-}

package/src/edit-lock/stale-sweep.js

@@ -1,120 +0,0 @@
-// Message-triggered stale-lock sweep: the missing-target classifier and the
-// per-domain detached scheduler. Plain ESM, no ctx, no @deepseek-ai imports;
-// the scheduler's job, clock and timer are injected so the composition and
-// the unit tests share one core.
-import { lstatSync } from 'node:fs'
-import { dirname } from 'node:path'
-
-/** Missing-target classification for one stored canonical resource id. ONLY
- * ENOENT counts: a successful lstat — including of a dangling symlink — is
- * not missing, and any other error (EACCES, ENOTDIR, symlink loops) skips the
- * row. Never follows a moved file, never resolves aliases into a replacement
- * identity, never fabricates a resource key for a missing path.
- * @param {string} resourceId */
-export function isMissingTarget(resourceId) {
-  if (typeof resourceId !== 'string' || resourceId.length === 0) return false
-  try {
-    lstatSync(resourceId)
-    return false
-  } catch (error) {
-    const code = /** @type {any} */ (error)?.code
-    if (code !== 'ENOENT') return false
-    // Windows reports a path through a regular-file component as ENOENT as
-    // well (there is no ENOTDIR): preserve the conservative POSIX
-    // classification by walking up — a non-directory ancestor means the path
-    // is BLOCKED (skip the row), not missing.
-    if (process.platform === 'win32') {
-      for (let parent = dirname(resourceId); parent !== dirname(parent); parent = dirname(parent)) {
-        let stat
-        try { stat = lstatSync(parent) } catch (ancestorError) {
-          if (/** @type {any} */ (ancestorError)?.code === 'ENOENT') continue
-          return false
-        }
-        return stat.isDirectory()
-      }
-    }
-    return true
-  }
-}
-
-/** Cooldown between two sweeps of one management domain. */
-export const STALE_SWEEP_COOLDOWN_MS = 60_000
-
-/** Per-key detached sweep scheduler. At most one in-flight sweep and one
- * cooldown window per key (the management-domain ROOT, not a session), so
- * message volume across sessions never scales the aggregate scan cost. Idle
- * entries whose cooldown window expired are RECLAIMED — on each trigger pass
- * and when a job completes — and close() empties the registry, so the map
- * never grows unboundedly with the number of domains a process has touched.
- *
- * Dispatch happens on a zero-delay timer and is NEVER awaited by the caller:
- * the turn proceeds immediately (unlike auto-resume, which must precede the
- * first step). close() cancels undispatched work; an already-running job
- * always settles on its own — an already-submitted authority transaction is
- * never cancelled or reinterpreted. A failed job warns once through the
- * injected sink and still opens the cooldown window.
- * @param {{cooldownMs?: number, now?: () => number,
- *   setTimer?: (fn: () => void) => unknown, clearTimer?: (handle: unknown) => void,
- *   warn?: (message: string) => void}} [options] */
-export function createStaleSweepScheduler({ cooldownMs = STALE_SWEEP_COOLDOWN_MS, now = () => Date.now(), setTimer, clearTimer, warn = () => {} } = {}) {
-  const arm = setTimer ?? ((fn) => globalThis.setTimeout(fn, 0))
-  const disarm = clearTimer ?? ((handle) => globalThis.clearTimeout(handle))
-  /** @type {Map<string, {inFlight: Promise<unknown> | null, coolingUntil: number, handle: unknown}>} */
-  const entries = new Map()
-  let closed = false
-  /** Reclaim entries that are neither dispatched nor in flight and whose
-   * cooldown window expired. @param {unknown} [except] */
-  function prune(except = undefined) {
-    const at = now()
-    for (const [key, entry] of entries) {
-      if (entry === except) continue
-      if (entry.inFlight === null && entry.handle === null && at >= entry.coolingUntil) entries.delete(key)
-    }
-  }
-  return Object.freeze({
-    /** Arm one sweep for key. Returns false when the key is closed, one is
-     * already dispatched or in flight, or the cooldown window is still open.
-     * @param {string} key @param {() => unknown} job */
-    trigger(key, job) {
-      if (closed || typeof key !== 'string' || key.length === 0 || typeof job !== 'function') return false
-      prune()
-      let entry = entries.get(key)
-      if (!entry) {
-        entry = { inFlight: null, coolingUntil: 0, handle: null }
-        entries.set(key, entry)
-      }
-      if (entry.inFlight !== null || entry.handle !== null || now() < entry.coolingUntil) return false
-      entry.handle = arm(() => {
-        entry.handle = null
-        if (closed) return
-        const pending = Promise.resolve()
-          .then(job)
-          .then(
-            () => {},
-            (error) => warn(`edit lock stale sweep failed: ${/** @type {any} */ (error)?.message ?? error}`),
-          )
-          .then(() => {
-            entry.inFlight = null
-            entry.coolingUntil = now() + cooldownMs
-            // Completion is the other reclamation point: peers whose windows
-            // lapsed while this job ran are dropped here.
-            prune(entry)
-          })
-        entry.inFlight = pending
-      })
-      return true
-    },
-    /** Entry count, for diagnostics and tests. */
-    get size() { return entries.size },
-    /** Cancel every undispatched sweep and forget every key. In-flight jobs
-     * settle untouched. */
-    close() {
-      closed = true
-      for (const entry of entries.values()) {
-        if (entry.handle !== null) disarm(entry.handle)
-        entry.handle = null
-      }
-      entries.clear()
-    },
-  })
-}