weir-harness 1.2.3 → 2.0.0

package/src/edit-lock/admin-recovery.js

@@ -1,151 +0,0 @@
-// Trusted offline admin API. Never opens a runtime or invokes a publisher.
-import { constants, lstatSync, realpathSync } from 'node:fs'
-import { open } from 'node:fs/promises'
-import { join, resolve, parse, relative, sep } from 'node:path'
-import { createHash } from 'node:crypto'
-import { reservePublisher } from './reservation.js'
-import { openEditLockStore } from './store.js'
-import { canonical, parseSnapshot, validateImage } from './snapshot.js'
-import { administrativeState, digest, LATE_WRITER_RISK } from './admin-ledger.js'
-import { dispositionFor } from './derived-facts.js'
-
-export const MAX_RECOVERY_BYTES = 16 * 1024 * 1024
-const sha256 = bytes => createHash('sha256').update(bytes).digest('hex')
-function fail(code, message) { throw Object.assign(new Error(message), { code: `weir-edit-lock/${code}` }) }
-function check(condition, message) { if (!condition) fail('invalid-recovery', message) }
-function scope(input) { return { root: input.root, owner: input.owner, expectedRevision: input.expectedRevision, operationIds: [...input.operationIds].sort(), risk: LATE_WRITER_RISK } }
-export function recoveryConfirmation(input) { return `ADMIN OVERRIDE ${digest(scope(input))}` }
-function validateInput(input) {
-  check(input && typeof input === 'object' && !Array.isArray(input), 'Recovery object required')
-  const keys = ['root', 'owner', 'expectedRevision', 'operationIds', 'recoveryId', 'reason', 'acceptLateWriterRisk', 'confirmation']
-  check(Object.keys(input).length === keys.length && keys.every(k => Object.hasOwn(input, k)), 'Exact recovery fields required')
-  for (const key of ['root', 'owner', 'recoveryId', 'reason']) check(typeof input[key] === 'string' && input[key].trim() && input[key].length <= (key === 'root' ? 4096 : key === 'reason' ? 2000 : key === 'recoveryId' ? 128 : 512) && !input[key].includes('\0'), `Invalid ${key}`)
-  check(Number.isSafeInteger(input.expectedRevision) && input.expectedRevision >= 0, 'Expected revision required')
-  check(Array.isArray(input.operationIds) && input.operationIds.length > 0 && input.operationIds.length <= 10000 && input.operationIds.every(id => typeof id === 'string' && id.trim() && id.length <= 1024), 'Operation IDs required')
-  check(new Set(input.operationIds).size === input.operationIds.length, 'Duplicate operation ID')
-  check(input.acceptLateWriterRisk === true && input.confirmation === recoveryConfirmation(input), 'Explicit scoped ADMIN OVERRIDE and late-writer risk acceptance required')
-}
-function pinsFor(directory) {
-  let current = parse(directory).root
-  const pins = []
-  for (const part of relative(current, directory).split(sep).filter(Boolean)) {
-    current = join(current, part)
-    const stat = lstatSync(current)
-    check(stat.isDirectory() && !stat.isSymbolicLink(), 'Authority ancestors must be nonsymlink directories')
-    pins.push({ path: current, stat })
-  }
-  return pins
-}
-const same = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mode === b.mode
-function verify(pins) { for (const pin of pins) check(same(pin.stat, lstatSync(pin.path)), 'Authority ancestor changed') }
-async function boundedRead(path, pins) {
-  verify(pins)
-  const before = lstatSync(path)
-  check(before.isFile() && !before.isSymbolicLink() && before.nlink === 1 && before.size <= MAX_RECOVERY_BYTES, 'Bounded single-link regular authority file required')
-  // win32: O_NOFOLLOW/O_NONBLOCK are undefined; the lstat above refused a symlink
-  // leaf and the post-open identity check below bounds the swap (read-authority.js).
-  const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
-  try {
-    const stat = await file.stat()
-    check(same(before, stat) && stat.isFile() && stat.nlink === 1 && stat.size <= MAX_RECOVERY_BYTES, 'Opened file identity or bound changed')
-    const bytes = Buffer.alloc(stat.size + 1)
-    let length = 0
-    while (length < bytes.length) {
-      const result = await file.read(bytes, length, bytes.length - length, length)
-      if (!result.bytesRead) break
-      length += result.bytesRead
-    }
-    const after = await file.stat()
-    verify(pins)
-    check(same(stat, lstatSync(path)) && after.size === stat.size && after.mtimeMs === stat.mtimeMs && after.ctimeMs === stat.ctimeMs && length === stat.size, 'Authority changed during read')
-    return bytes.subarray(0, length)
-  } finally { await file.close() }
-}
-async function syncDirectory(directory) {
-  // Directory fsync is POSIX-only (EPERM on win32, reservation.js SYNC_SUPPORTED).
-  if (process.platform !== 'darwin' && process.platform !== 'linux') return
-  const handle = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
-  try { await handle.sync() } finally { await handle.close() }
-}
-
-/** Caller must authenticate settings-plane access and exact-match a server-derived
- * root BEFORE calling. Test checkpoints surround real IO, never replace it.
- * @param {any} input
- * @param {{ checkpoint?: (point: string) => void|Promise<void> }} [testing] */
-export async function recoverAuthority(input, testing = {}) {
-  validateInput(input)
-  // Capture before the first await: the operator request cannot change in flight.
-  input = structuredClone(input)
-  check(resolve(input.root) === input.root && realpathSync.native(input.root) === input.root, 'Canonical root required')
-  const directory = join(input.root, '.weir/edit-lock')
-  const pins = pinsFor(directory)
-  const reservation = await reservePublisher(directory)
-  let store
-  try {
-    await testing.checkpoint?.('reserved')
-    const assertExclusive = async () => { verify(pins); await reservation.assertExclusive(); verify(pins) }
-    await assertExclusive()
-    const path = join(directory, 'snapshot.json')
-    const bytes = await boundedRead(path, pins)
-    const before = parseSnapshot(bytes, input.root)
-    const existing = before.state.adminRecoveries?.find(row => row.recoveryId === input.recoveryId)
-    if (existing) {
-      check(existing.confirmation === digest(scope(input)) && existing.reason === input.reason, 'Recovery ID reused with different request')
-      const backup = await boundedRead(join(directory, existing.backup.file), pins)
-      check(sha256(backup) === existing.backup.sha256 && backup.length === existing.backup.bytes, 'Recovery backup no longer validates')
-      const original = parseSnapshot(backup, input.root)
-      check(original.revision === existing.expectedRevision, 'Backup revision mismatch')
-      await syncDirectory(directory)
-      await assertExclusive()
-      return { revision: before.revision, idempotent: true, record: existing }
-    }
-    if (before.revision !== input.expectedRevision) fail('revision-conflict', 'Authority revision changed; inspect and confirm again')
-    const owner = before.state.sessions.find(s => s.sessionId === input.owner)
-    if (!owner || !owner.interrupted) throw new Error('Only an interrupted historical owner can be overridden')
-    // Operations an earlier disposition of the same owner already covers stay
-    // disposed: a re-revocation after repair names only genuinely new unknowns.
-    const unresolved = before.state.operations.filter(op => op.sessionId === input.owner && ['prepared', 'publishing', 'unknown'].includes(op.phase) && !dispositionFor(before.state, op))
-    check(unresolved.length > 0 && unresolved.every(op => op.phase === 'unknown'), 'Recover to stable unknown history before administrative override')
-    check(canonical(unresolved.map(op => op.operationId).sort()) === canonical([...input.operationIds].sort()), 'Confirm every unresolved operation for this owner')
-    const backup = { file: `admin-backup-${digest([input.root, input.recoveryId])}.json`, sha256: sha256(bytes), bytes: bytes.length }
-    const record = { recoveryId: input.recoveryId, root: input.root, owner: input.owner,
-      expectedRevision: before.revision, committedRevision: before.revision + 1, at: Date.now(), actor: 'authenticated-settings-administrator',
-      reason: input.reason, risk: LATE_WRITER_RISK, confirmation: digest(scope(input)), backup,
-      operations: unresolved.map(op => ({ operationId: op.operationId, sha256: digest(op) })),
-      releasedLocks: before.state.locks.filter(lock => lock.owner === input.owner), revokedEpoch: owner.executionEpoch + 1 }
-    const nextState = administrativeState(before.state, record)
-    validateImage(nextState)
-    check(Buffer.byteLength(canonical(nextState)) + 1024 <= MAX_RECOVERY_BYTES, 'Resulting authority exceeds recovery byte limit')
-    await testing.checkpoint?.('before-backup')
-    await assertExclusive()
-    let file
-    try { file = await open(join(directory, backup.file), 'wx', 0o600) }
-    catch (error) { if (/** @type {{code?: string}} */ (error).code !== 'EEXIST') throw error }
-    if (file) {
-      try { await file.writeFile(bytes); await testing.checkpoint?.('backup-written'); await file.sync() }
-      finally { await file.close() }
-    }
-    const savedBackup = await boundedRead(join(directory, backup.file), pins)
-    check(savedBackup.equals(bytes), 'Existing backup does not match exact authority bytes')
-    parseSnapshot(savedBackup, input.root)
-    // Also sync an existing backup when retrying a crash before its first fsync.
-    // fsync needs a writable handle on Windows (EPERM on O_RDONLY): open the
-    // existing backup read-write there so the re-sync stays a real fsync.
-    const backupHandle = await open(join(directory, backup.file), process.platform === 'win32' ? 'r+' : constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
-    try { await backupHandle.sync() } finally { await backupHandle.close() }
-    await syncDirectory(directory)
-    await testing.checkpoint?.('backup-durable')
-    await assertExclusive()
-    check((await boundedRead(path, pins)).equals(bytes), 'Authority changed after backup')
-    store = await openEditLockStore({ directory, domainId: input.root, mode: 'recover', maxSnapshotBytes: MAX_RECOVERY_BYTES }, { checkpoint: async point => { await testing.checkpoint?.(`store:${point}`); await assertExclusive() } })
-    check(canonical(store.snapshot()) === canonical(before), 'Authority changed before commit')
-    const saved = await store.recordAdministrativeRecovery({ expectedRevision: before.revision, nextState })
-    await assertExclusive()
-    return { revision: saved.revision, idempotent: false, record }
-  } finally {
-    await store?.close()
-    // This operation dispatched no file publisher; it may release ONLY its own
-    // reservation. A pre-existing runtime/stale reservation is never removed.
-    await reservation.releaseAfterQuiescence()
-  }
-}

package/src/edit-lock/admission.js

@@ -1,82 +0,0 @@
-import { posix, win32 } from 'node:path'
-
-/** Candidates describe effects, not merely explicit API arguments. Session-wide
- * operations must enumerate affected ownership at their FIFO position.
- * Modes: 'normal' covers every mutating ingress; 'release' is pure removal and
- * must retain the ownership unresolved updates require; 'revocation' is strictly
- * subtractive and crosses fences. 'resume' is reserved for session-level
- * recovery transactions (the trusted Continue): it publishes nothing, so an
- * unresolved resource-level fence never denies it, while domain fences and
- * every shape denial bind it exactly as they bind 'normal'. It must never be
- * used for a transaction that publishes, confirms, acquires or releases.
- * @typedef {{kind: 'resources', resourceIds: string[]} | {kind: 'scope', ancestor: string} | {kind: 'none'}} Candidate
- * @typedef {'normal'|'release'|'revocation'|'resume'} Mode
- */
-
-/** Shape check only, NOT filesystem proof. The trusted manager ingress already
- * requires canonical, single-link resource identity and exclusive topology control.
- * Opaque kernel test IDs remain valid without fences but cannot prove non-overlap.
- * @param {string} resourceId */
-function canonicalResource(resourceId) {
-  if (typeof resourceId !== 'string' || resourceId.includes('\0')) return false
-  // Shape check only, NOT filesystem proof. The POSIX arm is every POSIX row
-  // plus the platform-neutral synthetic ids historical records may carry; the
-  // win32 arm is the NTFS-native shape the resource-identity win32 row
-  // produces. Real producers emit exactly one shape per platform; relative,
-  // root, trailing-slash and non-normalized spellings stay refused.
-  const posixCanonical = resourceId.startsWith('/') && resourceId !== '/' &&
-    !resourceId.endsWith('/') && posix.normalize(resourceId) === resourceId
-  if (process.platform !== 'win32') return posixCanonical
-  return posixCanonical ||
-    (/^[A-Za-z]:\\/.test(resourceId) && resourceId.length > 3 &&
-      !resourceId.endsWith('\\') && !resourceId.includes('/') &&
-      win32.normalize(resourceId) === resourceId)
-}
-
-/** Pure denial check. Historical closeout assertions grant no authority.
- * v3 stores no ancestor continuity witness. Neither relative() nor resolving an
- * ancestor again proves its historical topology: scope relations stay undecidable.
- * @param {import('./operation-history.js').Operation[]} operations
- * @param {Candidate} candidate
- * @param {Mode} [mode]
- */
-export function admitMutation(operations, candidate, mode = 'normal') {
-  if (mode === 'revocation') return
-  for (const operation of operations) {
-    if (operation.phase !== 'publishing' && operation.phase !== 'unknown') continue
-    const fence = operation.fence
-    const deny = (/** @type {string} */ reason) => {
-      // Tagged so trusted maintenance (the stale-lock sweep) can tell this
-      // expected refusal from a persistence/poison/unexpected failure.
-      throw Object.assign(new Error(`unresolved publication fence: ${reason}`), { admissionRefusal: true })
-    }
-    if (!candidate || !fence) deny('scope-unproved')
-    // Pure removal cannot publish or grant authority, but MUST retain the exact
-    // ownership required by unresolved updates, even under historical fences.
-    if (mode === 'release') {
-      if (candidate.kind !== 'resources' || !candidate.resourceIds.every(canonicalResource)) deny('identity-unproved')
-      const target = operation.binding.target
-      if (target.kind === 'update' && candidate.kind === 'resources' && candidate.resourceIds.includes(target.resourceId)) deny('retained-ownership')
-      continue
-    }
-    if (fence?.kind === 'domain') deny('domain')
-    if (candidate.kind === 'none') continue
-    if (candidate.kind !== 'resources') deny('scope-continuity-unproved')
-    if (candidate.kind === 'resources') {
-      for (const resourceId of candidate.resourceIds) {
-        if (!canonicalResource(resourceId)) deny('identity-unproved')
-        if (fence?.kind !== 'resource') deny('scope-continuity-unproved')
-        // 'resume' publishes nothing: a resource-level fence never bars the
-        // session-level recovery transaction; it keeps barring the resource
-        // itself on every other mode until administrative settlement.
-        if (mode !== 'resume' && fence?.kind === 'resource' && (!canonicalResource(fence.resourceId) || fence.resourceId === resourceId)) deny('resource-conflict')
-      }
-    }
-  }
-}
-
-/** @param {import('./operation-history.js').Target} target @returns {Candidate} */
-export function publicationCandidate(target) {
-  return target.kind === 'update' ? { kind: 'resources', resourceIds: [target.resourceId] }
-    : { kind: 'scope', ancestor: target.ancestor }
-}

package/src/edit-lock/binding-attestation.js

@@ -1,29 +0,0 @@
-/** Same-bundle-instance bridge. Tokens identify channel runtime objects, never
- * confer authority. An absent registration is UNKNOWN, not evidence of death. */
-/** @type {Map<string, {agent: object, sessionId: string}>} */
-const registrations = new Map()
-
-/** @param {string} nonce @param {object} agent @param {string} sessionId */
-export function registerBindingRuntime(nonce, agent, sessionId) {
-  if (registrations.has(nonce)) throw new Error('duplicate binding nonce')
-  const entry = Object.freeze({ agent, sessionId })
-  registrations.set(nonce, entry)
-  return () => { if (registrations.get(nonce) === entry) registrations.delete(nonce) }
-}
-
-/** @param {string} nonce */
-export function bindingRuntime(nonce) { return registrations.get(nonce) }
-
-/** Undefined is a verified absence ONLY after a successful registry lookup.
- * Missing services and lookup failures must throw (and become unknown).
- * @param {(sessionId: string) => object | undefined} servingRuntime */
-export function createBindingAttester(servingRuntime) {
-  /** @param {string} sessionId @param {string} nonce
-   * @returns {'serving'|'stale'|'unknown'} */
-  return (sessionId, nonce) => {
-    const holder = bindingRuntime(nonce)
-    if (!holder || holder.sessionId !== sessionId) return 'unknown'
-    try { return servingRuntime(sessionId) === holder.agent ? 'serving' : 'stale' }
-    catch { return 'unknown' }
-  }
-}

package/src/edit-lock/binding-guidance.js

@@ -1,72 +0,0 @@
-/** Publisher-only classification; pid is compared with the publisher, never the client.
- * @param {number | undefined} pid @param {string} attestation */
-export function bindingRefusalReason(pid, attestation) {
-  const holder = attestation === 'serving' ? 'serving'
-    : attestation === 'serving-idle' ? 'serving-idle'
-    : pid === process.pid ? 'same-process-unattestable'
-      : pid !== undefined ? 'cross-process-pid' : 'unknown'
-  return `session already bound: holder=${holder}${pid !== undefined ? `; pid=${pid}` : ''}`
-}
-
-/** The wire/minted holder classes. */
-const HOLDER_KINDS = Object.freeze(['revocation-failed', 'serving', 'transferable', 'cross-process', 'unknown'])
-
-/** Validate a structured binding refusal — exactly the minted four-field
- * shape crosses the wire or reaches a classifier; anything else degrades to
- * the text channel (display only, never a decision input).
- * @param {unknown} value @returns {{code: 'binding-duplicate', retryable: true, holderKind: string, holderPid: number | null} | undefined} */
-export function asBindingFailure(value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
-  if (Object.keys(value).sort().join(',') !== 'code,holderKind,holderPid,retryable') return undefined
-  const { code, retryable, holderKind, holderPid } = /** @type {any} */ (value)
-  if (code !== 'binding-duplicate' || retryable !== true || !HOLDER_KINDS.includes(holderKind)) return undefined
-  if (holderPid !== null && !(Number.isSafeInteger(holderPid) && holderPid > 0)) return undefined
-  return { code, retryable, holderKind, holderPid }
-}
-
-/** Render only publisher-classified facts — the STRUCTURED bindingFailure,
- * never a re-parse of the display text (spec: presentation must not infer
- * state by matching human-readable text; change edit-lock-deepening D2).
- * Unrecognized or missing structure renders as unknown.
- * @param {string} sessionId @param {any} failure */
-export function bindingGuidance(sessionId, failure) {
-  const classification = failure?.code === 'binding-duplicate' ? failure?.holderKind : undefined
-  const pid = typeof failure?.holderPid === 'number' ? failure.holderPid : undefined
-  let holder
-  if (classification === 'transferable') {
-    // Transferable (change edit-lock-binding-transfer): an idle same-process
-    // holder is taken over by the next driving ingress — calm copy, no pid,
-    // no window hunt, and NEVER the publisher-reservation warning.
-    holder = `session ${sessionId} is held by an inactive attachment of this same session. Editing attaches here automatically when you next send a message; /edit-lock retry also takes it over now. Retry does not Continue editing.`
-  } else if (classification === 'serving') {
-    // The holder is provably live and not transferable (mid-turn or a live
-    // channel proxy): name what is happening and when to retry. No window
-    // hunt (single-instance hosts exist) and no process management.
-    holder = `session ${sessionId} is being edited in another attachment right now. Wait for that turn to finish, then use /edit-lock retry in this session; retry does not Continue editing.`
-  } else if (classification === 'unknown' && pid !== undefined) {
-    holder = `session ${sessionId} has a binding in this same process (pid ${pid}) that cannot be safely reclaimed. A stale runtime incarnation may still hold its channel. Wait for the original holder to disconnect or for confirmed process shutdown.`
-  } else if (classification === 'cross-process' && pid !== undefined) {
-    holder = `session ${sessionId} has a binding held by process pid ${pid}. Quit that holder process or disconnect the original holder, and wait for confirmation.`
-  } else {
-    holder = `session ${sessionId} has a binding whose holder cannot be attested. Wait for the original holder to disconnect or for confirmed process shutdown.`
-  }
-  if (classification === 'transferable' || classification === 'serving') return holder
-  return `${holder} Then use /edit-lock retry in the original session when available; retry does not Continue editing. Do NOT remove the publisher reservation (.weir/.edit-lock.publisher-reservation) while its process is alive — removing it would split the edit authority.`
-}
-
-/** Structured publisher fact; never classify a retry from prose.
- * @param {number | undefined} pid @param {string} attestation
- * @param {boolean} [revocationFailed] */
-export function bindingFailure(pid, attestation, revocationFailed = false) {
-  return { code: 'binding-duplicate', retryable: true,
-    holderKind: revocationFailed ? 'revocation-failed' : attestation === 'serving' ? 'serving'
-      : attestation === 'serving-idle' ? 'transferable'
-        : pid !== undefined && pid !== process.pid ? 'cross-process' : 'unknown',
-    holderPid: pid ?? null }
-}
-/** @param {number | undefined} pid @param {string} attestation @param {boolean} [revocationFailed] */
-export function bindingRefusal(pid, attestation, revocationFailed = false) {
-  const reason = bindingRefusalReason(pid, attestation)
-  return Object.assign(new Error(revocationFailed ? `${reason}; durable revocation was not acknowledged. Inspect authority; no replacement was admitted.` : reason),
-    { bindingFailure: bindingFailure(pid, attestation, revocationFailed) })
-}