sintbot 1.0.15 → 1.3.0

package/src/core/engineeffectcursor.js

@@ -0,0 +1,394 @@
+'use strict'
+
+// C2 effect commit cursor. The binary adapter validates a transition before
+// calling stage(); this journal stores only opaque IDs and confirmations. An
+// unconfirmed external effect is ambiguous after a crash and is never replayed.
+const { createHash } = require('node:crypto')
+
+const ID = /^[0-9a-f]{32}$/
+const MAX_EFFECTS = 1024
+const MAX_BATCH_MEMBERS = 1024
+const hash = (...parts) => createHash('sha256').update(parts.join('\0')).digest('hex').slice(0, 32)
+
+function batchId(receiptIds) {
+  if (!Array.isArray(receiptIds) || receiptIds.length < 2 || receiptIds.length > MAX_BATCH_MEMBERS ||
+      receiptIds.some(id => !ID.test(id)) || new Set(receiptIds).size !== receiptIds.length) {
+    throw new TypeError('invalid C2 batch members')
+  }
+  // Preserve dispatch order: two differently ordered prompts cannot share an
+  // external effect identity even when they contain the same accepted inputs.
+  return hash('sintbot-c2-batch-v2', String(receiptIds.length), ...receiptIds)
+}
+
+function batchStepId(receiptIds, ordinal) {
+  if (!Number.isSafeInteger(ordinal) || ordinal < 0) throw new TypeError('invalid C2 batch step identity')
+  return hash('sintbot-c2-batch-step-v2', batchId(receiptIds), String(ordinal))
+}
+
+function batchEffectId(step, index) {
+  if (!ID.test(step) || !Number.isSafeInteger(index) || index < 0 || index >= MAX_EFFECTS) {
+    throw new TypeError('invalid C2 batch effect identity')
+  }
+  return hash('sintbot-c2-batch-effect-v2', step, String(index))
+}
+
+function stepId(taskId, ordinal) {
+  if (!ID.test(taskId) || !Number.isSafeInteger(ordinal) || ordinal < 0) throw new TypeError('invalid C2 step identity')
+  return hash('sintbot-c2-step-v1', taskId, String(ordinal))
+}
+
+function effectId(step, index) {
+  if (!ID.test(step) || !Number.isSafeInteger(index) || index < 0 || index >= MAX_EFFECTS) {
+    throw new TypeError('invalid C2 effect identity')
+  }
+  return hash('sintbot-c2-effect-v1', step, String(index))
+}
+
+function readCursor(state) {
+  const cursor = Object.hasOwn(state, 'effectCursor') ? state.effectCursor : { version: 1, steps: [] }
+  if (!cursor || ![1, 2].includes(cursor.version) || !Array.isArray(cursor.steps) ||
+      Object.keys(cursor).some((key) => !['version', 'steps'].includes(key))) throw new TypeError('invalid C2 effect cursor')
+  const seen = new Set(), seenBatches = new Set()
+  for (const step of cursor.steps) {
+    const isBatch = !!step && Object.hasOwn(step, 'receiptIds')
+    const keys = isBatch ? ['id', 'batchId', 'receiptIds', 'ordinal', 'effects', 'confirmed']
+      : ['id', 'taskId', 'ordinal', 'effects', 'confirmed', 'notifiedAt']
+    if (!step || Object.keys(step).some((key) => !keys.includes(key)) ||
+        !ID.test(step.id) || !Number.isSafeInteger(step.ordinal) || step.ordinal < 0 ||
+        (isBatch ? cursor.version !== 2 || !Array.isArray(step.receiptIds) ||
+          step.batchId !== batchId(step.receiptIds) || batchStepId(step.receiptIds, step.ordinal) !== step.id
+          : !ID.test(step.taskId) || stepId(step.taskId, step.ordinal) !== step.id) ||
+        seen.has(step.id) || (isBatch && seenBatches.has(step.batchId)) ||
+        !Array.isArray(step.effects) || step.effects.length > MAX_EFFECTS ||
+        !Array.isArray(step.confirmed) ||
+        (step.notifiedAt !== undefined && (!Number.isSafeInteger(step.notifiedAt) || step.notifiedAt <= 0))) {
+      throw new TypeError('invalid C2 effect cursor step')
+    }
+    seen.add(step.id)
+    if (isBatch) seenBatches.add(step.batchId)
+    const expected = step.effects.map((_, index) => isBatch ? batchEffectId(step.id, index) : effectId(step.id, index))
+    if (new Set(step.effects).size !== step.effects.length ||
+        expected.some((id, index) => id !== step.effects[index]) ||
+        new Set(step.confirmed).size !== step.confirmed.length ||
+        step.confirmed.some((id, index) => id !== step.effects[index])) {
+      throw new TypeError('invalid C2 effect cursor IDs')
+    }
+  }
+  return cursor
+}
+
+class EngineEffectCursor {
+  constructor(journal, { now = Date.now } = {}) {
+    if (!journal || typeof journal.commitState !== 'function' || typeof journal.snapshot !== 'function') {
+      throw new TypeError('C2 effect cursor requires the shared receipt journal')
+    }
+    if (typeof now !== 'function') throw new TypeError('C2 effect cursor clock required')
+    this.journal = journal
+    this.now = now
+    this.live = new Set() // only steps staged by this process may perform effects
+    this.blocked = new Set() // an ambiguous external failure cannot be retried here
+    this._read()
+  }
+
+  _read() {
+    const disk = this.journal.snapshot()
+    if (disk.seq !== this.journal.current.seq) throw new Error('C2 effect cursor has a stale journal owner')
+    return readCursor(disk.state)
+  }
+
+  _save(cursor, sessionResetIntent = null) {
+    this.journal.commitState({ ...this.journal.current.state, effectCursor: cursor },
+      { sessionResetIntent })
+  }
+
+  _sessionResetIntent(step, receipts, identity) {
+    if (!identity || !Number.isSafeInteger(identity.turnToken) || identity.turnToken <= 0 ||
+        typeof identity.generation !== 'string' || !ID.test(identity.generation) ||
+        identity.resetSessionAfter !== true || !['ok', 'no-reply'].includes(identity.status) ||
+        Object.keys(identity).some(key => !['turnToken', 'generation', 'resetSessionAfter', 'status'].includes(key)) ||
+        step.ordinal !== 0) {
+      throw new TypeError('C2 session reset needs an eligible terminal and turn identity')
+    }
+    if (this.journal.current.sessionResets.some(item =>
+      item.chatId === receipts[0].chatId && item.effectId !== step.id)) {
+      throw new Error('C2 group already has an unresolved session reset')
+    }
+    return { effectId: step.id, receiptIds: step.receiptIds || [step.taskId],
+      chatId: receipts[0].chatId, turnToken: identity.turnToken,
+      generation: identity.generation, phase: 'acked', status: identity.status }
+  }
+
+  _forgetSettled(steps) {
+    for (const step of steps) {
+      this.live.delete(step.id)
+      this.blocked.delete(step.id)
+    }
+  }
+
+  _receipt(taskId) {
+    const receipt = this.journal.snapshot().pending.find((item) => item.id === taskId)
+    if (!receipt) throw new Error('C2 effect has no durable target receipt')
+    return receipt
+  }
+
+  _batchReceipts(receiptIds) {
+    batchId(receiptIds)
+    const byId = new Map(this.journal.snapshot().pending.map(receipt => [receipt.id, receipt]))
+    const receipts = receiptIds.map(id => byId.get(id))
+    if (receipts.some(receipt => !receipt)) throw new Error('C2 batch effect has no durable target receipt')
+    if (new Set(receipts.map(receipt => receipt.chatId)).size !== 1) {
+      throw new Error('C2 batch members must belong to one group')
+    }
+    return receipts
+  }
+
+  // Call only after the reducer output and all effect IDs have been validated.
+  // The effect count is projected from that output; no payload is stored.
+  stage(taskId, ordinal, effectCount, { sessionReset = null } = {}) {
+    if (!Number.isSafeInteger(effectCount) || effectCount < 0 || effectCount > MAX_EFFECTS) {
+      throw new TypeError('invalid C2 effect count')
+    }
+    const id = stepId(taskId, ordinal)
+    const effects = Array.from({ length: effectCount }, (_, index) => effectId(id, index))
+    const cursor = this._read()
+    const receipt = this._receipt(taskId)
+    if (sessionReset && effectCount !== 0) throw new Error('C2 reset intent requires final effect ACK')
+    if (cursor.steps.some(step => step.receiptIds?.includes(taskId))) {
+      throw new Error('C2 batch member is already bound to an effect')
+    }
+    const existing = cursor.steps.find((step) => step.id === id)
+    if (existing) {
+      if (existing.effects.length !== effectCount) throw new Error('C2 step identity changed its effects')
+      if (sessionReset) {
+        const expected = this._sessionResetIntent(existing, [receipt], sessionReset)
+        if (!this.journal.current.sessionResets.some(item => JSON.stringify(item) === JSON.stringify(expected))) {
+          throw new Error('C2 reset intent identity changed')
+        }
+      }
+      return { id, effects: [...existing.effects], reused: true }
+    }
+    const nextStep = { id, taskId, ordinal, effects, confirmed: [] }
+    this._save({ version: cursor.version, steps: [...cursor.steps, nextStep] },
+      sessionReset ? this._sessionResetIntent(nextStep, [receipt], sessionReset) : null)
+    this.live.add(id)
+    return { id, effects, reused: false }
+  }
+
+  // A zero-effect batch records a confirmed silent terminal decision. If the
+  // following atomic receipt settlement fails, startup can finish it quietly.
+  stageBatch(receiptIds, ordinal, effectCount, { sessionReset = null } = {}) {
+    if (!Number.isSafeInteger(effectCount) || effectCount < 0 || effectCount > MAX_EFFECTS) {
+      throw new TypeError('invalid C2 batch effect count')
+    }
+    const shared = batchId(receiptIds)
+    const members = [...receiptIds]
+    const id = batchStepId(members, ordinal)
+    const effects = Array.from({ length: effectCount }, (_, index) => batchEffectId(id, index))
+    const cursor = this._read()
+    const receipts = this._batchReceipts(members)
+    if (sessionReset && effectCount !== 0) throw new Error('C2 reset intent requires final effect ACK')
+    const existing = cursor.steps.find(step => step.id === id)
+    if (existing) {
+      if (existing.effects.length !== effectCount) throw new Error('C2 batch step identity changed its effects')
+      if (sessionReset) {
+        const expected = this._sessionResetIntent(existing, receipts, sessionReset)
+        if (!this.journal.current.sessionResets.some(item => JSON.stringify(item) === JSON.stringify(expected))) {
+          throw new Error('C2 reset intent identity changed')
+        }
+      }
+      return { id, batchId: shared, receiptIds: members, effects: [...existing.effects], reused: true }
+    }
+    const memberSet = new Set(members)
+    if (cursor.steps.some(step => step.receiptIds
+      ? step.receiptIds.some(member => memberSet.has(member)) : memberSet.has(step.taskId))) {
+      throw new Error('C2 batch member is already bound to an effect')
+    }
+    const nextStep = { id, batchId: shared, receiptIds: members, ordinal, effects, confirmed: [] }
+    this._save({ version: 2, steps: [...cursor.steps, nextStep] },
+      sessionReset ? this._sessionResetIntent(nextStep, receipts, sessionReset) : null)
+    this.live.add(id)
+    return { id, batchId: shared, receiptIds: members, effects, reused: false }
+  }
+
+  async apply(id, index, perform, { sessionReset = null } = {}) {
+    if (typeof perform !== 'function') throw new TypeError('C2 effect performer required')
+    const cursor = this._read()
+    const step = cursor.steps.find((item) => item.id === id)
+    if (!step || !Number.isSafeInteger(index) || index < 0 || index >= step.effects.length) {
+      throw new TypeError('unknown C2 effect')
+    }
+    const effect = step.effects[index]
+    if (sessionReset && index !== step.effects.length - 1) {
+      throw new Error('C2 reset intent requires final effect ACK')
+    }
+    const resetIntent = sessionReset ? this._sessionResetIntent(step,
+      step.receiptIds ? this._batchReceipts(step.receiptIds) : [this._receipt(step.taskId)], sessionReset) : null
+    if (step.confirmed.includes(effect)) {
+      if (resetIntent && !this.journal.current.sessionResets.some(item =>
+        JSON.stringify(item) === JSON.stringify(resetIntent))) {
+        throw new Error('C2 confirmed effect has no matching reset intent')
+      }
+      return { id: effect, status: 'already-confirmed' }
+    }
+    if (index !== step.confirmed.length) throw new Error('C2 effects must commit in order')
+    if (!this.live.has(id) || this.blocked.has(id) || step.notifiedAt !== undefined) {
+      throw new Error('C2 unconfirmed effect requires interruption notice')
+    }
+    try {
+      if (await perform(effect) !== true) throw new Error('C2 effect was not confirmed')
+      const fresh = this._read()
+      const next = fresh.steps.map((item) => item.id === id
+        ? { ...item, confirmed: [...item.confirmed, effect] } : item)
+      this._save({ version: fresh.version, steps: next }, resetIntent)
+      return { id: effect, status: 'confirmed' }
+    } catch (error) {
+      this.blocked.add(id)
+      throw error
+    }
+  }
+
+  unconfirmed() {
+    return this._read().steps.filter((step) => step.notifiedAt === undefined)
+      .map((step) => ({ id: step.id,
+        ...(step.receiptIds ? { batchId: step.batchId, receiptIds: [...step.receiptIds] } : { taskId: step.taskId }),
+        effects: step.effects.filter((id) => !step.confirmed.includes(id)) }))
+      .filter((step) => step.effects.length)
+  }
+
+  snapshot() { return JSON.parse(JSON.stringify(this._read())) }
+
+  // Call only AFTER the task receipt is settled. Reversing that order would
+  // leave a crash window where the task can restart without its effect IDs.
+  pruneConfirmedTask(taskId) {
+    if (!ID.test(taskId)) throw new TypeError('invalid C2 task identity')
+    const cursor = this._read()
+    if (cursor.steps.some(step => step.receiptIds?.includes(taskId))) {
+      throw new Error('C2 batch member requires atomic settlement')
+    }
+    const mine = cursor.steps.filter((step) => step.taskId === taskId)
+    if (mine.some((step) => step.confirmed.length !== step.effects.length)) {
+      throw new Error('C2 task still has unconfirmed effects')
+    }
+    if (mine.length && this.journal.snapshot().pending.some((item) => item.id === taskId)) {
+      throw new Error('C2 task receipt is still pending')
+    }
+    if (mine.length) {
+      this._save({ version: cursor.version, steps: cursor.steps.filter((step) => step.taskId !== taskId) })
+      this._forgetSettled(mine)
+    }
+    return mine.length
+  }
+
+  // Normal terminal path: remove the accepted task receipt and all of its
+  // confirmed effect IDs in ONE checkpoint write. A failed write leaves both
+  // in place; neither half can disappear independently.
+  settleConfirmedTask(taskId) {
+    if (!ID.test(taskId)) throw new TypeError('invalid C2 task identity')
+    const cursor = this._read()
+    if (cursor.steps.some(step => step.receiptIds?.includes(taskId))) {
+      throw new Error('C2 batch member requires atomic settlement')
+    }
+    const mine = cursor.steps.filter((step) => step.taskId === taskId)
+    if (mine.some((step) => step.confirmed.length !== step.effects.length)) {
+      throw new Error('C2 task still has unconfirmed effects')
+    }
+    this._receipt(taskId)
+    const nextState = { ...this.journal.current.state, effectCursor: {
+      version: cursor.version, steps: cursor.steps.filter((step) => step.taskId !== taskId),
+    } }
+    this.journal.settle(taskId, nextState)
+    this._forgetSettled(mine)
+    return mine.length
+  }
+
+  // Recovery-only terminal path. The caller must have a confirmed targeted
+  // interruption notice (or a previously durable notifiedAt receipt). This
+  // single checkpoint commit clears the receipt and every effect step.
+  settleInterruptedTask(taskId, { noticeConfirmed = false } = {}) {
+    if (noticeConfirmed !== true) throw new Error('C2 interruption notice is not confirmed')
+    if (!ID.test(taskId)) throw new TypeError('invalid C2 task identity')
+    const cursor = this._read()
+    if (cursor.steps.some(step => step.receiptIds?.includes(taskId))) {
+      throw new Error('C2 batch member requires atomic settlement')
+    }
+    this._receipt(taskId)
+    const mine = cursor.steps.filter((step) => step.taskId === taskId)
+    this.journal.settle(taskId, { ...this.journal.current.state, effectCursor: {
+      version: cursor.version, steps: cursor.steps.filter((step) => step.taskId !== taskId),
+    } })
+    this._forgetSettled(mine)
+    return mine.length
+  }
+
+  settleConfirmedBatch(receiptIds) {
+    const shared = batchId(receiptIds)
+    const members = [...receiptIds]
+    const cursor = this._read()
+    const mine = cursor.steps.filter(step => step.batchId === shared)
+    if (!mine.length) throw new Error('unknown C2 batch effect')
+    if (mine.some(step => step.confirmed.length !== step.effects.length)) {
+      throw new Error('C2 batch still has unconfirmed effects')
+    }
+    this._batchReceipts(members)
+    this.journal.settleBatch(members, { ...this.journal.current.state, effectCursor: {
+      version: 2, steps: cursor.steps.filter(step => step.batchId !== shared),
+    } })
+    this._forgetSettled(mine)
+    return mine.length
+  }
+
+  settleInterruptedBatch(receiptIds) {
+    const shared = batchId(receiptIds)
+    const members = [...receiptIds]
+    const cursor = this._read()
+    const mine = cursor.steps.filter(step => step.batchId === shared)
+    if (!mine.length) throw new Error('unknown C2 batch effect')
+    if (this._batchReceipts(members).some(receipt => receipt.notifiedAt === undefined)) {
+      throw new Error('C2 batch interruption notices are not all confirmed')
+    }
+    this.journal.settleBatch(members, { ...this.journal.current.state, effectCursor: {
+      version: 2, steps: cursor.steps.filter(step => step.batchId !== shared),
+    } })
+    this._forgetSettled(mine)
+    return mine.length
+  }
+
+  // send() must confirm a targeted interruption notice. A failed or ambiguous
+  // send leaves the step pending; a confirmed one is recorded before returning.
+  async notifyUnconfirmed(send) {
+    if (typeof send !== 'function') throw new TypeError('C2 interruption sender required')
+    const results = []
+    const unconfirmed = this.unconfirmed()
+    if (unconfirmed.some(step => step.receiptIds)) {
+      throw new Error('C2 batch effects require shared startup recovery')
+    }
+    const pending = unconfirmed.map((step) => ({ ...step, receipt: this._receipt(step.taskId) }))
+    for (const step of pending) {
+      try {
+        const at = this.now()
+        if (!Number.isSafeInteger(at) || at <= 0) throw new Error('C2 notification time required')
+        if (await send({ id: step.id, taskId: step.taskId, effects: [...step.effects],
+          target: { chatId: step.receipt.chatId, source: step.receipt.source,
+            sourceId: step.receipt.sourceId } }) !== true) {
+          throw new Error('C2 interruption notice was not confirmed')
+        }
+        const cursor = this._read()
+        this._save({ version: cursor.version, steps: cursor.steps.map((item) => item.id === step.id
+          ? { ...item, notifiedAt: at } : item) })
+        this.live.delete(step.id)
+        results.push({ id: step.id, status: 'notified' })
+      } catch {
+        this.blocked.add(step.id)
+        results.push({ id: step.id, status: 'retry' })
+      }
+    }
+    if (results.some((item) => item.status === 'retry')) {
+      const error = new Error('C2 effect interruption notices remain pending')
+      error.results = results
+      throw error
+    }
+    return results
+  }
+}
+
+module.exports = { EngineEffectCursor, stepId, effectId, batchId, batchStepId, batchEffectId, MAX_BATCH_MEMBERS }

package/src/core/enginestepcoordinator.js

@@ -0,0 +1,183 @@
+'use strict'
+
+const { randomUUID } = require('node:crypto')
+const { engineStep, resetBinaryCore } = require('../agent/privatecore')
+
+// Development bridge for the unified C2 entry. A prepared result reserves the
+// coordinator while other host reducers validate; only commit publishes it.
+// Persistence is opt-in: lifecycle state can contain turnText, so callers must
+// provide an approved durable representation before enabling a writer.
+class EngineStepCoordinator {
+  #committed
+  #blocked = false
+  #pending = null
+  #step
+  #reset
+  #persist
+  #journal
+
+  constructor({ state = { version: 1, seq: 0, lanes: {} }, step = engineStep,
+    reset = resetBinaryCore, persist = null, journal = null } = {}) {
+    const durable = journal?.snapshot?.()
+    if (journal) state = durable?.state
+    if (typeof step !== 'function' || typeof reset !== 'function' ||
+        (persist !== null && (typeof persist !== 'function' || persist.constructor?.name === 'AsyncFunction')) ||
+        (journal !== null && (persist !== null || typeof journal.snapshot !== 'function' ||
+          typeof journal.hasEvent !== 'function' || typeof journal.appendTransition !== 'function' ||
+          state?.version !== 2 || durable.cursor !== state.seq)) || !validState(state)) {
+      throw new TypeError('invalid C2 step coordinator')
+    }
+    this.#committed = structuredClone(state)
+    this.#step = step
+    this.#reset = reset
+    this.#persist = persist
+    this.#journal = journal
+  }
+
+  get blocked() { return this.#blocked }
+  snapshot() { return structuredClone(this.#committed) }
+
+  prepare({ domain, scope, payload, seed, id, validate = null, receipts = null } = {}) {
+    if (this.#blocked) throw new Error('C2 step coordinator needs recovery')
+    if (this.#pending) throw new Error('C2 step coordinator has an uncommitted transition')
+    if (this.#journal && id === undefined) throw new Error('durable C2 event ID required')
+    id ??= randomUUID()
+    const token = {}
+    this.#pending = token
+    const event = { id, domain, scope, expectedCursor: this.#committed.seq, payload }
+    if (seed !== undefined) event.seed = seed
+    try {
+      if (![id, domain, scope].every(value => typeof value === 'string' &&
+          Buffer.byteLength(value) > 0 && Buffer.byteLength(value) <= 256) ||
+          !payload || typeof payload !== 'object' || Array.isArray(payload) ||
+          (seed !== undefined && (!seed || typeof seed !== 'object' || Array.isArray(seed)))) {
+        throw new TypeError('invalid C2 step event')
+      }
+      if (validate !== null && typeof validate !== 'function') throw new TypeError('invalid C2 step validator')
+      if (validate && validate.constructor?.name === 'AsyncFunction') throw new TypeError('C2 step validator must be synchronous')
+      if (this.#journal && this.#journal.hasEvent(id)) throw new Error('C2 event already committed')
+      const durableReceipts = this.#journal
+        ? structuredClone(receipts ?? this.#journal.snapshot().receipts) : null
+      const admission = this.#journal
+        ? { version: 1, cursor: this.#committed.seq, eventId: id, unseen: true } : undefined
+      const result = this.#step(this.snapshot(), event, admission)
+      const copy = structuredClone(result)
+      if (!validResult(copy, this.#committed.seq, id, domain, scope)) {
+        throw new Error('invalid C2 step result')
+      }
+      if (validate) {
+        const verdict = validate(structuredClone(copy))
+        if (verdict && typeof verdict.then === 'function') throw new TypeError('C2 step validator must be synchronous')
+      }
+      return {
+        result: structuredClone(copy),
+        commit: () => {
+          if (this.#pending !== token || this.#blocked) throw new Error('C2 step preparation is no longer current')
+          try {
+            if (this.#journal) {
+              this.#journal.appendTransition({ eventId: id, before: this.#committed.seq,
+                after: copy.state.seq, state: copy.state, receipts: durableReceipts,
+                effectIds: copy.effects.map(effect => effect.effectId),
+                ...(copy.effectDescriptors === undefined ? {} :
+                  { effectDescriptors: copy.effectDescriptors }) })
+            } else if (this.#persist) {
+              const saved = this.#persist(structuredClone(copy.state))
+              if (saved && typeof saved.then === 'function') throw new TypeError('C2 step persistence must be synchronous')
+            }
+            this.#committed = structuredClone(copy.state)
+            this.#pending = null
+            return structuredClone(copy)
+          } catch (error) {
+            this.#pending = null
+            this.#blocked = true
+            throw error
+          }
+        },
+        cancel: () => {
+          if (this.#pending !== token) return false
+          this.#pending = null
+          return true
+        },
+      }
+    } catch (error) {
+      this.#pending = null
+      this.#blocked = true
+      throw error
+    }
+  }
+
+  transition(options) { return this.prepare(options).commit() }
+
+  recover(state) {
+    if (this.#journal) throw new Error('durable C2 recovery needs verified journal reopen')
+    // A failed durable writer may have committed before reporting an error.
+    // Its last trusted on-disk snapshot must be supplied by the caller.
+    if (this.#persist && state === undefined) throw new Error('C2 recovery needs durable state import')
+    if (state !== undefined && !validState(state)) throw new TypeError('invalid C2 recovery state')
+    this.#reset()
+    if (state !== undefined) this.#committed = structuredClone(state)
+    this.#pending = null
+    this.#blocked = false
+    return this.snapshot()
+  }
+
+  recoverFromJournal(journal) {
+    if (!this.#journal || !journal || typeof journal.snapshot !== 'function' ||
+        typeof journal.hasEvent !== 'function' || typeof journal.appendTransition !== 'function') {
+      throw new TypeError('durable C2 journal required')
+    }
+    const durable = journal.snapshot()
+    if (!validState(durable.state) || durable.state.version !== 2 ||
+        durable.cursor !== durable.state.seq) throw new TypeError('invalid durable C2 state')
+    this.#reset()
+    this.#journal = journal
+    this.#committed = structuredClone(durable.state)
+    this.#pending = null
+    this.#blocked = false
+    return this.snapshot()
+  }
+}
+
+function validState(state) {
+  if (!state || typeof state !== 'object' || Array.isArray(state) ||
+      ![1, 2].includes(state.version) || !Number.isSafeInteger(state.seq) || state.seq < 0 ||
+      !state.lanes || typeof state.lanes !== 'object' || Array.isArray(state.lanes)) return false
+  if (state.version === 2) return Object.keys(state).every(key =>
+    ['version', 'seq', 'lanes', 'lastEventId'].includes(key)) &&
+    (state.seq === 0 ? state.lastEventId === undefined :
+      typeof state.lastEventId === 'string' && !!state.lastEventId &&
+      Buffer.byteLength(state.lastEventId) <= 256)
+  if (state.seq === 0 && state.committedEventIds === undefined && state.lastEventId === undefined) return true
+  const ids = state.committedEventIds
+  if (!ids || typeof ids !== 'object' || Array.isArray(ids) ||
+      Object.keys(ids).length !== state.seq || Object.keys(ids).length > 100_000 ||
+      Object.entries(ids).some(([id, value]) => value !== true || !id || Buffer.byteLength(id) > 256)) return false
+  if (state.seq === 0) return state.lastEventId === undefined
+  if (typeof state.lastEventId !== 'string' || !state.lastEventId ||
+      Buffer.byteLength(state.lastEventId) > 256 || !Object.hasOwn(ids, state.lastEventId)) return false
+  return true
+}
+
+function validResult(result, priorSeq, id, domain, scope) {
+  if (!result || typeof result !== 'object' || Array.isArray(result) ||
+      !validState(result.state) || result.state.seq !== priorSeq + 1 ||
+      result.cursor !== result.state.seq || result.eventId !== id ||
+      (result.state.lastEventId !== undefined && result.state.lastEventId !== id) ||
+      (result.state.committedEventIds !== undefined && !Object.hasOwn(result.state.committedEventIds, id)) ||
+      !Array.isArray(result.effects) ||
+      (result.effectDescriptors !== undefined &&
+        (!Array.isArray(result.effectDescriptors) ||
+          result.effectDescriptors.length !== result.effects.length ||
+          result.effectDescriptors.some((descriptor, index) =>
+            !descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor) ||
+            descriptor.effectId !== result.effects[index]?.effectId ||
+            descriptor.type !== result.effects[index]?.type ||
+            descriptor.domain !== domain || descriptor.scope !== scope))) ||
+      !result.decision ||
+      typeof result.decision !== 'object' || Array.isArray(result.decision)) return false
+  return result.effects.every((effect, index) => effect && typeof effect === 'object' &&
+    !Array.isArray(effect) && typeof effect.type === 'string' && !!effect.type &&
+    effect.effectId === `sbot-c2-effect-v1:${Buffer.byteLength(id)}:${id}:${index}`)
+}
+
+module.exports = { EngineStepCoordinator }

package/src/core/store.js

@@ -20,15 +20,15 @@ function atomicWriteJSON(file, obj, opts = {}) {
   // the default umask — would silently widen it back to 0644 on every save.
   let mode = null
   try { mode = fs.statSync(file).mode & 0o777 } catch { mode = opts.mode == null ? null : opts.mode } // 新文件:有 opts.mode 就用它,否则随 umask
-  const fd = fs.openSync(tmp, 'w')
-  try {
-    fs.writeSync(fd, data)
-    fs.fsyncSync(fd)
-    if (mode != null) fs.fchmodSync(fd, mode)
-  } finally {
-    fs.closeSync(fd)
-  }
   try {
+    const fd = fs.openSync(tmp, 'w')
+    try {
+      fs.writeSync(fd, data)
+      fs.fsyncSync(fd)
+      if (mode != null) fs.fchmodSync(fd, mode)
+    } finally {
+      fs.closeSync(fd)
+    }
     fs.renameSync(tmp, file)
   } catch (e) {
     try { fs.unlinkSync(tmp) } catch { /* best-effort cleanup */ }
@@ -89,6 +89,35 @@ class StateStore {
 
   getSession(chatId) { return this._group(chatId).sessionId || null }
   setSession(chatId, sid) { this._group(chatId).sessionId = sid; this._save() }
+  // C2 writeback: persist a new snapshot before exposing the session in this
+  // process. Mark an aborted session in the same replacement when requested;
+  // omitted/false tainted leaves the existing flag as the legacy setter does.
+  // The legacy setter keeps its existing behavior for other callers.
+  setSessionAtomic(chatId, sid, { tainted, sessionStats } = {}) {
+    if (sessionStats !== undefined && (!sessionStats ||
+        typeof sessionStats !== 'object' || Array.isArray(sessionStats) ||
+        sessionStats.sessionId !== sid ||
+        ['turns', 'in', 'out'].some(key =>
+          !Number.isFinite(sessionStats[key]) || sessionStats[key] < 0) ||
+        (sessionStats.ctx !== undefined &&
+          (!Number.isFinite(sessionStats.ctx) || sessionStats.ctx < 0)) ||
+        (sessionStats.cum !== undefined && (!sessionStats.cum ||
+          typeof sessionStats.cum !== 'object' || Array.isArray(sessionStats.cum) ||
+          ['in', 'cr', 'out'].some(key =>
+            !Number.isFinite(sessionStats.cum[key]) || sessionStats.cum[key] < 0))))) {
+      throw new TypeError('session statistics must match the session being written')
+    }
+    const groups = this.data.groups || {}
+    const group = { ...(groups[chatId] || {}), sessionId: sid }
+    if (tainted === true) group.tainted = true
+    if (sessionStats !== undefined) group.sessionStats = {
+      ...sessionStats,
+      ...(sessionStats.cum === undefined ? {} : { cum: { ...sessionStats.cum } }),
+    }
+    const next = { ...this.data, groups: { ...groups, [chatId]: group } }
+    atomicWriteJSON(this.file, next, { mode: 0o600 })
+    this.data = next
+  }
   // 清会话连带清「被掐断」标记:标记属于那段会话,会话没了它就没有意义。
   clearSession(chatId) { const g = this._group(chatId); delete g.sessionId; delete g.tainted; this._save() }
 
@@ -108,6 +137,21 @@ class StateStore {
   putSessionStats(chatId, s) { this._group(chatId).sessionStats = s; this._save() }
   clearSessionStats(chatId) { delete this._group(chatId).sessionStats; this._save() }
 
+  // Session writeback may be followed by a requested fresh session. Publish
+  // all three session-owned fields in one file replacement, and only replace
+  // the live snapshot after that write succeeds. A failed fsync/rename cannot
+  // make this process observe a reset that the next process will not see.
+  resetSessionAndStats(chatId) {
+    const groups = this.data.groups || {}
+    const group = { ...(groups[chatId] || {}) }
+    delete group.sessionId
+    delete group.tainted
+    delete group.sessionStats
+    const next = { ...this.data, groups: { ...groups, [chatId]: group } }
+    atomicWriteJSON(this.file, next, { mode: 0o600 })
+    this.data = next
+  }
+
   getProvider(chatId) { return this._group(chatId).provider || null }
   // ⚠ 人主动切模型(/model · 控制台)连带作废「额度临时切换」记录:人说了算,引擎之后不再自作主张切回。
   setProvider(chatId, name) { const g = this._group(chatId); g.provider = name; delete g.failover; this._save() }