@nelsonlongxiang/dsh-open-a2a-net 0.6.30 → 0.6.32

package/lib/task-ledger.js

@@ -18,9 +18,11 @@
  * illusion: settlements vanished while debts piled up).
  * @module @nelsonlongxiang/dsh-open-a2a-net/task-ledger
  */
+import { parseAuthorization } from "./task-auth.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { parseReceipt, RECEIPT_OUTCOMES } from "./receipt.js";
+import { classifyConservationBlock, ConservationCounters } from "./ledger-conservation.js";
 /**
  * Caller-ended summaries (abandon / cancel) share one isolation law: late
  * receipts never rewrite the verdict — they only stamp lateReceiptAt, and
@@ -63,6 +65,96 @@ export const TASK_STALE_TTL_MS = 24 * 60 * 60_000;
 const ARCHIVE_ENDS = ['receipt', 'echo', 'abandoned', 'cancelled', 'evicted'];
 /** Summary marker {@link TaskLedger.resolveEcho} writes on echo-settled rows. */
 const ECHO_SUMMARY = '(settled by content echo)';
+const SENDER_KINDS = ['session', 'host', 'bridge'];
+/** Longest sender id kept; anything longer is malformed, not truncated. */
+export const SENDER_ID_CAP = 256;
+/**
+ * Restore-side allowlist for one persisted sender: a well-formed value comes
+ * back as a fresh object holding only kind, id and (when present) face; anything else is dropped whole (the row
+ * itself survives — a bad sender never costs the debt record).
+ * @param raw - the persisted value.
+ * @returns the sender, or undefined when absent or malformed.
+ */
+export function parseSender(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const { kind, id, face } = raw;
+    if (typeof kind !== 'string' || !SENDER_KINDS.includes(kind))
+        return undefined;
+    if (typeof id !== 'string' || id === '' || id.length > SENDER_ID_CAP)
+        return undefined;
+    if (face !== undefined && (typeof face !== 'string' || face === '' || face.length > SENDER_ID_CAP))
+        return undefined;
+    // `face` belongs to host senders only; on any other kind it is dropped, the sender kept.
+    return { kind: kind, id, ...(face !== undefined && kind === 'host' ? { face } : {}) };
+}
+/**
+ * Spread helper for restore: `{ sender }` when the persisted value parses and
+ * the row is not inbound (an inbound row's originator is its caller, never a
+ * sender this host recorded), else nothing.
+ */
+function withSender(raw, direction) {
+    if (direction === 'inbound')
+        return {};
+    const sender = parseSender(raw);
+    return sender === undefined ? {} : { sender };
+}
+/**
+ * #114 S2: `{ auth }` when a persisted INBOUND row carries a record that
+ * parses whole (parseAuthorization) and belongs to THIS row — its target is
+ * the row's team and its receipt target the row's peer — else nothing: the
+ * row survives as a pre-S2 row, never with a partially adopted or borrowed
+ * record.
+ */
+function withAuth(raw, entry, now) {
+    if (entry.direction !== 'inbound' && entry.direction !== 'outbound')
+        return {};
+    const auth = parseAuthorization(raw, now);
+    if (auth === undefined || auth.target !== entry.team)
+        return {};
+    if (entry.direction === 'inbound')
+        return auth.ingress === 'wire' && `local:${auth.receipt_target}` === entry.peer ? { auth } : {};
+    // #139: an outbound row carries only its local-candidate admission.
+    return auth.ingress === 'local' && entry.peer === 'local' ? { auth } : {};
+}
+/** #139: the routing facts settlement reads, copied between a row and its archive entry. */
+function routingOf(row) {
+    return {
+        ...(row.peerKey !== undefined ? { peerKey: row.peerKey } : {}),
+        ...(row.peerHost !== undefined ? { peerHost: row.peerHost } : {}),
+        ...(row.deliveredTo !== undefined ? { deliveredTo: row.deliveredTo } : {}),
+    };
+}
+/** The facts of one outbound birth that fit the row (see {@link withRouting} for the same shape on restore). */
+function birthFacts(peer, birth) {
+    if (birth === undefined)
+        return {};
+    const fact = (v) => v !== undefined && v !== '' && v.length <= ROUTING_FACT_CAP;
+    const remote = peer !== 'local' && !peer.startsWith('local:');
+    return {
+        ...(!remote && birth.auth !== undefined && birth.auth.ingress === 'local' ? { auth: birth.auth } : {}),
+        ...(remote && fact(birth.peerKey) ? { peerKey: birth.peerKey } : {}),
+        ...(remote && fact(birth.peerHost) ? { peerHost: birth.peerHost } : {}),
+        ...(fact(birth.deliveredTo) ? { deliveredTo: birth.deliveredTo } : {}),
+    };
+}
+/** Bound on a persisted routing fact; anything longer (or empty, or not a string) is dropped on restore. */
+const ROUTING_FACT_CAP = 256;
+/**
+ * #139: restore-side allowlist for the routing facts. Each is kept only in
+ * its shape — a non-empty string within the cap — and the peer facts only on
+ * a remote outbound row; anything else is dropped (the row survives as one
+ * born before the fields, judged by current membership and origin).
+ */
+function withRouting(entry) {
+    const fact = (v) => typeof v === 'string' && v !== '' && v.length <= ROUTING_FACT_CAP;
+    const remoteOutbound = entry.direction === 'outbound' && typeof entry.peer === 'string' && entry.peer !== 'local' && !entry.peer.startsWith('local:');
+    return {
+        ...(remoteOutbound && fact(entry.peerKey) ? { peerKey: entry.peerKey } : {}),
+        ...(remoteOutbound && fact(entry.peerHost) ? { peerHost: entry.peerHost } : {}),
+        ...(fact(entry.deliveredTo) ? { deliveredTo: entry.deliveredTo } : {}),
+    };
+}
 /**
  * How one archived row ended (gh#31). The recorded field wins; legacy rows
  * fall back to the summary markers this ledger writes itself. The fallback
@@ -83,6 +175,39 @@ export function archivedEndedBy(row) {
         return 'echo';
     return 'receipt';
 }
+/** Bound on ids and callers kept in settlement records; longer values are cut on write and refused on restore. */
+const SETTLEMENT_ID_CAP = 256;
+/** Bound of the refusal ring (design §4.4). */
+export const SETTLEMENT_REFUSAL_CAP = 64;
+const SETTLEMENT_REASONS = ['settler-off-chain', 'settler-unverified', 'on-behalf-mismatch', 'echo-off-chain'];
+const CHAIN_ROLES = ['target', 'target-member', 'host-face', 'compat', 'legacy', 'off-chain'];
+const PROOF_VALUES = ['origin-claim', 'claim-mismatch', 'legacy-window', 'unbound', 'cli-identity', 'in-process', 'none'];
+/** Restore-side allowlist for settledBy: whole or nothing. */
+function withSettledBy(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return {};
+    const r = raw;
+    if (typeof r.caller !== 'string' || r.caller.length > SETTLEMENT_ID_CAP || typeof r.chain_role !== 'string' || !CHAIN_ROLES.includes(r.chain_role))
+        return {};
+    return { settledBy: { caller: r.caller, chain_role: r.chain_role } };
+}
+/** Restore-side allowlist for one refusal record: whole or nothing. */
+function parseRefusal(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const st = r.settler;
+    if (typeof r.taskId !== 'string' || r.taskId === '' || r.taskId.length > SETTLEMENT_ID_CAP || typeof r.at !== 'number' || !Number.isFinite(r.at))
+        return undefined;
+    if (typeof r.reason !== 'string' || !SETTLEMENT_REASONS.includes(r.reason) || typeof r.head !== 'string' || typeof r.enforced !== 'boolean')
+        return undefined;
+    if (st === null || typeof st !== 'object' || typeof st.caller !== 'string' || st.caller.length > SETTLEMENT_ID_CAP || typeof st.proof !== 'string' || !PROOF_VALUES.includes(st.proof) || (st.ingress !== 'wire' && st.ingress !== 'local'))
+        return undefined;
+    const count = r.count === undefined ? 1 : r.count;
+    if (typeof count !== 'number' || !Number.isInteger(count) || count < 1)
+        return undefined;
+    return { taskId: r.taskId, at: r.at, settler: { caller: st.caller, proof: st.proof, ingress: st.ingress }, reason: r.reason, head: r.head.slice(0, SUMMARY_CAP), enforced: r.enforced, count };
+}
 /**
  * Bounded outbound-task ledger with whole-file persistence. Pure of any
  * routing knowledge: callers {@link track} a task when a route leaves it
@@ -95,6 +220,12 @@ export class TaskLedger {
     tasks = [];
     /** Settled rows, most recently resolved first; bounded by the archive cap. */
     archived = [];
+    /** #114 S4: refused / would-be-refused settlements, newest first. */
+    refusals = [];
+    /** #114 S4: every refusal ever noted (monotonic; survives the ring's bound). */
+    refusalsTotal = 0;
+    /** gh#154: lifetime conservation counters (persisted; never reset by cap trims or restarts) and the durable damage marker — the machinery lives in src/ledger-conservation.ts (R-mod); the ledger's seams delegate. */
+    counters = new ConservationCounters();
     staleTtlMs;
     archiveCap;
     /** Injectable clock (option `now`). */
@@ -147,7 +278,7 @@ export class TaskLedger {
      * via context_id follow-ups (the dispatch reply already says so).
      * Idempotent by task id like {@link track}.
      */
-    trackReceiptless(taskId, team, peer, contextId, brief) {
+    trackReceiptless(taskId, team, peer, contextId, brief, sender, birth) {
         if (taskId === '')
             return;
         this.sweep(this.now());
@@ -155,6 +286,7 @@ export class TaskLedger {
             return;
         if (this.archived.some(entry => entry.taskId === taskId))
             return;
+        this.counters.trackedTotal += 1;
         this.tasks = [{
                 taskId,
                 team,
@@ -164,12 +296,14 @@ export class TaskLedger {
                 receiptExpected: false,
                 ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
                 ...(brief !== undefined && brief !== '' ? { brief } : {}),
+                ...(sender !== undefined ? { sender } : {}),
+                ...birthFacts(peer, birth),
                 status: 'pending',
             }, ...this.tasks];
         this.trimOwed();
         this.persist();
     }
-    track(taskId, team, peer, contextId, brief) {
+    track(taskId, team, peer, contextId, brief, sender, birth) {
         if (taskId === '')
             return;
         this.sweep(this.now());
@@ -177,6 +311,7 @@ export class TaskLedger {
             return;
         if (this.archived.some(entry => entry.taskId === taskId))
             return;
+        this.counters.trackedTotal += 1;
         this.tasks = [{
                 taskId,
                 team,
@@ -185,6 +320,8 @@ export class TaskLedger {
                 direction: 'outbound',
                 ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
                 ...(brief !== undefined && brief !== '' ? { brief } : {}),
+                ...(sender !== undefined ? { sender } : {}),
+                ...birthFacts(peer, birth),
                 status: 'pending',
             }, ...this.tasks];
         this.trimOwed();
@@ -203,7 +340,7 @@ export class TaskLedger {
      * @param from - the caller's receipt target (label or callback address).
      * @param contextId - the delivery's conversation id, kept for follow-up routes (empty omits it).
      */
-    trackInbound(taskId, team, from, contextId, receiptExpected, brief) {
+    trackInbound(taskId, team, from, contextId, receiptExpected, brief, auth, deliveredTo) {
         if (taskId === '')
             return;
         this.sweep(this.now());
@@ -211,6 +348,7 @@ export class TaskLedger {
             return;
         if (this.archived.some(entry => entry.taskId === taskId))
             return;
+        this.counters.trackedTotal += 1;
         this.tasks = [{
                 taskId,
                 team,
@@ -220,6 +358,9 @@ export class TaskLedger {
                 ...(receiptExpected === false ? { receiptExpected: false } : {}),
                 ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
                 ...(brief !== undefined && brief !== '' ? { brief } : {}),
+                // #114 S2: frozen at birth; a replayed id never reaches here (first record wins above).
+                ...(auth !== undefined ? { auth } : {}),
+                ...(deliveredTo !== undefined && deliveredTo !== '' ? { deliveredTo: deliveredTo.slice(0, ROUTING_FACT_CAP) } : {}),
                 status: 'pending',
             }, ...this.tasks];
         this.trimOwed();
@@ -276,6 +417,9 @@ export class TaskLedger {
                 endedBy: 'abandoned',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
                 ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
+                ...(record.sender !== undefined ? { sender: record.sender } : {}),
+                ...(record.auth !== undefined ? { auth: record.auth } : {}),
+                ...routingOf(record),
             });
             this.persist();
             return { outcome: 'cleared', taskId, archivedAt: resolvedAt };
@@ -318,6 +462,9 @@ export class TaskLedger {
                 endedBy: 'cancelled',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
                 ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
+                ...(record.sender !== undefined ? { sender: record.sender } : {}),
+                ...(record.auth !== undefined ? { auth: record.auth } : {}),
+                ...routingOf(record),
             });
             this.persist();
             return {
@@ -340,10 +487,12 @@ export class TaskLedger {
      * record with the latest outcome. A dead-lettered row revives through this
      * same path when a revived target finally answers.
      * @param message - the inbound or relayed message text.
+     * @param only - gh#141: settle the named row only when it passes this test;
+     *   with a test, a row that fails it or is already archived correlates nothing.
      * @returns what the receipt settled, or `undefined` when the message
      *   correlated nothing.
      */
-    resolveFromMessage(message) {
+    resolveFromMessage(message, judge, only) {
         const parsed = parseReceipt(message);
         if (parsed === null)
             return undefined;
@@ -353,7 +502,18 @@ export class TaskLedger {
         const elapsedMs = parsed.envelope?.elapsedMs;
         this.sweep(this.now());
         const record = this.tasks.find(entry => entry.taskId === taskId);
+        if (only !== undefined && (record === undefined || !only(record)))
+            return undefined;
         if (record !== undefined) {
+            // #114 S4: judge the settler before the row moves; enforce keeps a refused row owed.
+            const verdict = judge?.check(record, false);
+            if (verdict !== undefined && !verdict.ok) {
+                this.noteRefusal(taskId, judge, verdict.reason, message);
+                if (judge.enforce) {
+                    this.persist();
+                    return undefined;
+                }
+            }
             this.tasks = this.tasks.filter(entry => entry.taskId !== taskId);
             this.archiveSettled({
                 taskId: record.taskId,
@@ -369,6 +529,10 @@ export class TaskLedger {
                 endedBy: 'receipt',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
                 ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
+                ...(record.sender !== undefined ? { sender: record.sender } : {}),
+                ...(record.auth !== undefined ? { auth: record.auth } : {}),
+                ...routingOf(record),
+                ...(verdict !== undefined ? { settledBy: { caller: judge.settler.caller.slice(0, SETTLEMENT_ID_CAP), chain_role: verdict.ok ? verdict.role : 'off-chain' } } : {}),
             });
             this.persist();
             return {
@@ -385,6 +549,18 @@ export class TaskLedger {
         const settled = this.archived.find(entry => entry.taskId === taskId);
         if (settled === undefined)
             return undefined;
+        // #114 S4 (review of PR #140 P2-3): a late receipt is judged too. Under
+        // enforce, an off-chain one only marks that an answer came late — it
+        // never rewrites the settled summary or outcome.
+        const lateVerdict = judge?.check(settled, false);
+        if (lateVerdict !== undefined && !lateVerdict.ok) {
+            this.noteRefusal(taskId, judge, lateVerdict.reason, message);
+            if (judge.enforce) {
+                this.archived = [{ ...settled, lateReceiptAt: this.now() }, ...this.archived.filter(entry => entry.taskId !== taskId)];
+                this.persist();
+                return undefined;
+            }
+        }
         // Orphan isolation: a receipt for an explicitly abandoned row must not
         // rewrite the abandonment outcome — the caller stopped waiting by choice.
         // Record that the target did answer later; keep the decision verbatim and
@@ -432,14 +608,23 @@ export class TaskLedger {
      * @param message - the inbound message text.
      * @returns the task ids this message settled (usually none or one).
      */
-    resolveEcho(message) {
+    resolveEcho(message, judge) {
         const settled = [];
+        let refused = false;
         this.sweep(this.now());
         for (const record of [...this.tasks]) {
             if (record.status !== 'pending')
                 continue;
             if (!message.includes(`task ${record.taskId}`))
                 continue;
+            // #114 S4: an echo is weak evidence — only an on-chain settler's echo counts under enforce.
+            const verdict = judge?.check(record, true);
+            if (verdict !== undefined && !verdict.ok) {
+                this.noteRefusal(record.taskId, judge, verdict.reason, message);
+                refused = true;
+                if (judge.enforce)
+                    continue;
+            }
             this.tasks = this.tasks.filter(entry => entry.taskId !== record.taskId);
             this.archiveSettled({
                 taskId: record.taskId,
@@ -452,16 +637,72 @@ export class TaskLedger {
                 endedBy: 'echo',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
                 ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
+                ...(record.sender !== undefined ? { sender: record.sender } : {}),
+                ...(record.auth !== undefined ? { auth: record.auth } : {}),
+                ...routingOf(record),
+                ...(verdict !== undefined ? { settledBy: { caller: judge.settler.caller.slice(0, SETTLEMENT_ID_CAP), chain_role: verdict.ok ? verdict.role : 'off-chain' } } : {}),
             });
             settled.push(record.taskId);
         }
-        if (settled.length > 0)
+        if (settled.length > 0 || refused)
             this.persist();
         return settled;
     }
-    /** Move one settled record to the archive head, trimming at the cap. */
+    /** #114 S4: the owed row for a task id, if any (read-only; for the settlement gate). */
+    find(taskId) {
+        return this.tasks.find(entry => entry.taskId === taskId);
+    }
+    /** #114 S4: refused / would-be-refused settlements, newest first. */
+    settlementRefusals() {
+        return [...this.refusals];
+    }
+    /** #114 S4: every refusal ever noted, including those folded or pushed out of the ring. */
+    settlementRefusalsTotal() {
+        return this.refusalsTotal;
+    }
+    /**
+     * Record one refused / would-be-refused settlement in the bounded ring
+     * (persisted by the caller). A repeat of the same (task, settler, reason)
+     * folds into its entry and moves it to the head, so one row's flood cannot
+     * push other evidence out.
+     */
+    noteRefusal(taskId, judge, reason, message) {
+        const head = (message.split('\n')[0] ?? '').slice(0, SUMMARY_CAP);
+        const id = taskId.slice(0, SETTLEMENT_ID_CAP);
+        const settler = { ...judge.settler, caller: judge.settler.caller.slice(0, SETTLEMENT_ID_CAP) };
+        const same = (r) => r.taskId === id && r.settler.caller === settler.caller && r.reason === reason && r.enforced === judge.enforce;
+        const prior = this.refusals.find(same);
+        this.refusalsTotal += 1;
+        this.refusals = [{ taskId: id, at: this.now(), settler, reason, head, enforced: judge.enforce, count: (prior?.count ?? 0) + 1 }, ...this.refusals.filter(r => !same(r))].slice(0, SETTLEMENT_REFUSAL_CAP);
+    }
+    /**
+     * Move one settled record to the archive head, trimming at the cap.
+     * gh#154: every arrival and every cap-trimmed row is counted — the trim
+     * itself stays exactly as it was, only visible now.
+     */
     archiveSettled(record) {
-        this.archived = [record, ...this.archived].slice(0, this.archiveCap);
+        const next = [record, ...this.archived];
+        const kept = next.slice(0, this.archiveCap);
+        this.counters.archiveTrimmed += next.length - kept.length;
+        if (record.endedBy !== undefined)
+            this.counters.archivedByEnd[record.endedBy] += 1;
+        this.archived = kept;
+    }
+    /**
+     * gh#154 conservation verdict — duplicates first, then the count identity
+     * (a duplicated row can still make the counts balance; the Harness²
+     * assert_identity lesson). The counters module answers the count half.
+     */
+    conservation() {
+        const seen = new Set();
+        const duplicateTaskIds = [];
+        for (const row of [...this.tasks, ...this.archived]) {
+            if (seen.has(row.taskId))
+                duplicateTaskIds.push(row.taskId);
+            else
+                seen.add(row.taskId);
+        }
+        return this.counters.verdict(this.tasks.length, this.archived.length, duplicateTaskIds);
     }
     /**
      * gh#86 (chief order direct-4f596524): when the owed book exceeds
@@ -487,6 +728,9 @@ export class TaskLedger {
                 ...(row.brief !== undefined ? { brief: row.brief } : {}),
                 endedBy: 'evicted',
                 ...(row.direction !== undefined ? { direction: row.direction } : {}),
+                ...(row.sender !== undefined ? { sender: row.sender } : {}),
+                ...(row.auth !== undefined ? { auth: row.auth } : {}),
+                ...routingOf(row),
             });
         }
     }
@@ -514,15 +758,33 @@ export class TaskLedger {
             return;
         try {
             const snapshot = JSON.parse(readFileSync(this.path, 'utf8'));
-            const entries = snapshot?.tasks;
+            // gh#154 review r3: a non-object OR ARRAY top level, and a missing or
+            // non-array required `tasks` member, are malformed snapshots — never a
+            // healthy empty ledger (an array is typeof 'object'; absence of the
+            // one required member is damage, not an empty legacy snapshot).
+            if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot) || !Array.isArray(snapshot.tasks)) {
+                this.counters.damaged = 'snapshot-shape-invalid';
+                return;
+            }
+            // The optional archive array: present-but-not-an-array stamps damage —
+            // but the REQUIRED tasks rows still load (review r4 P1: an early return
+            // here would drop parseable owed rows wholesale on the next persist).
+            if (snapshot.archived !== undefined && !Array.isArray(snapshot.archived)) {
+                this.counters.damaged = 'snapshot-shape-invalid';
+            }
+            const entries = snapshot.tasks;
             const restored = [];
             if (Array.isArray(entries)) {
                 for (const raw of entries) {
                     // Unparsed on purpose: the legacy shape carries a 'resolved' status
                     // and inline outcome fields that TaskRecord no longer declares.
                     const entry = raw;
-                    if (typeof entry?.taskId !== 'string' || entry.taskId === '')
+                    if (typeof entry?.taskId !== 'string' || entry.taskId === '') {
+                        // gh#154 review r3: a malformed row never vanishes into a balanced
+                        // baseline — the parseable rows still load, the verdict refuses.
+                        this.counters.damaged = this.counters.damaged ?? 'row-shape-invalid';
                         continue;
+                    }
                     // Legacy two-state files carried resolved rows inline; they migrate
                     // into the archive so pre-upgrade outcomes survive the upgrade.
                     if (entry.status === 'resolved') {
@@ -540,6 +802,10 @@ export class TaskLedger {
                             ...(typeof entry.endedBy === 'string' && ARCHIVE_ENDS.includes(entry.endedBy) ? { endedBy: entry.endedBy } : {}),
                             ...(entry.direction === 'inbound' || entry.direction === 'outbound' ? { direction: entry.direction } : {}),
                             ...(entry.receiptExpected === false ? { receiptExpected: false } : {}),
+                            ...withSender(entry.sender, entry.direction),
+                            ...withAuth(entry.auth, entry, this.now()),
+                            ...withRouting(entry),
+                            ...withSettledBy(entry.settledBy),
                         });
                         continue;
                     }
@@ -554,6 +820,10 @@ export class TaskLedger {
                         // it is unknown, so a restored outbound row must not lose it.
                         ...(entry.direction === 'inbound' || entry.direction === 'outbound' ? { direction: entry.direction } : {}),
                         ...(entry.receiptExpected === false ? { receiptExpected: false } : {}),
+                        // #114 S3: a malformed sender is dropped whole; the row survives.
+                        ...withSender(entry.sender, entry.direction),
+                        ...withAuth(entry.auth, entry, this.now()),
+                        ...withRouting(entry),
                         status: entry.status === 'dead' ? 'dead' : 'pending',
                         ...(entry.status === 'dead'
                             ? {
@@ -568,8 +838,11 @@ export class TaskLedger {
             if (Array.isArray(legacyArchive)) {
                 for (const raw of legacyArchive) {
                     const entry = raw;
-                    if (typeof entry?.taskId !== 'string' || entry.taskId === '')
+                    if (typeof entry?.taskId !== 'string' || entry.taskId === '') {
+                        // gh#154 review r3: same refusal for a malformed archived row.
+                        this.counters.damaged = this.counters.damaged ?? 'row-shape-invalid';
                         continue;
+                    }
                     if (this.archived.some(existing => existing.taskId === entry.taskId))
                         continue;
                     this.archived.push({
@@ -586,15 +859,48 @@ export class TaskLedger {
                         ...(typeof entry.endedBy === 'string' && ARCHIVE_ENDS.includes(entry.endedBy) ? { endedBy: entry.endedBy } : {}),
                         ...(entry.direction === 'inbound' || entry.direction === 'outbound' ? { direction: entry.direction } : {}),
                         ...(entry.receiptExpected === false ? { receiptExpected: false } : {}),
+                        ...withSender(entry.sender, entry.direction),
+                        ...withAuth(entry.auth, entry, this.now()),
+                        ...withRouting(entry),
+                        ...withSettledBy(entry.settledBy),
                     });
                 }
             }
+            // gh#154: the load path's cap cuts are COUNTED, never silent. Rows this
+            // snapshot carried beyond the caps leave the live view but remain in the
+            // identity through restoreTrimmed.
             this.tasks = restored.slice(0, TASK_CAP);
+            this.counters.restoreTrimmed += Math.max(0, restored.length - this.tasks.length);
+            this.counters.restoreTrimmed += Math.max(0, this.archived.length - this.archiveCap);
             this.archived = this.archived.slice(0, this.archiveCap);
+            // gh#154: restore the lifetime counters through the conservation
+            // module's classifier - absent block = pre-#154 legacy bootstrap
+            // (kept rows + this load's cuts, endedBy via the legacy classifier);
+            // present-but-invalid (partial/negative/fractional/null body/
+            // unbounded trim) = damage: counters zero, verdict refuses conserved;
+            // valid = counters as persisted, a persisted damage marker riding
+            // along (review r2: it outlives the restart).
+            const classified = classifyConservationBlock(snapshot.conservation);
+            if (classified.kind === 'legacy') {
+                this.counters.legacyBootstrap(this.tasks.length, this.archived, this.counters.restoreTrimmed, archivedEndedBy);
+            }
+            else if (classified.kind === 'valid') {
+                this.counters.loadFrom(classified.snapshot, this.tasks.length, this.archived.length);
+            }
+            else {
+                this.counters.damaged = classified.reason;
+            }
+            const refusals = snapshot?.settlementRefusals;
+            if (Array.isArray(refusals))
+                this.refusals = refusals.map(parseRefusal).filter((r) => r !== undefined).slice(0, SETTLEMENT_REFUSAL_CAP);
+            const total = snapshot?.settlementRefusalsTotal;
+            this.refusalsTotal = Math.max(typeof total === 'number' && Number.isInteger(total) && total >= 0 ? total : 0, this.refusals.reduce((n, r) => n + r.count, 0));
         }
         catch {
             // A corrupt ledger is not fatal: routing never depends on it; the
-            // reconciliation simply starts fresh.
+            // reconciliation simply starts fresh. gh#154 review P1: a fresh start
+            // is NOT a conserved state — the unreadable history may have held work.
+            this.counters.damaged = 'snapshot-unreadable';
         }
     }
     /** Persist the ledger (no-op when no path was configured). */
@@ -606,6 +912,12 @@ export class TaskLedger {
             const snapshot = {
                 tasks: this.tasks.map(task => ({ ...task })),
                 ...(this.archived.length > 0 ? { archived: this.archived.map(entry => ({ ...entry })) } : {}),
+                ...(this.refusals.length > 0 ? { settlementRefusals: this.refusals.map(entry => ({ ...entry, settler: { ...entry.settler } })) } : {}),
+                ...(this.refusalsTotal > 0 ? { settlementRefusalsTotal: this.refusalsTotal } : {}),
+                // gh#154: the conservation counters ride every snapshot once any work
+                // has been tracked (zero-work ledgers stay byte-identical to before).
+                // A damage marker rides too — review r2: it must survive restarts.
+                ...(this.counters.trackedTotal > 0 || this.counters.damaged !== undefined ? { conservation: this.counters.toSnapshot() } : {}),
             };
             writeFileSync(this.path, JSON.stringify(snapshot), { mode: 0o600 });
         }

package/lib/team-store.js

@@ -31,6 +31,7 @@ export class TeamMembershipStore {
     /** Entries in first-declaration order; teams in join order. */
     entries = [];
     path;
+    listeners = new Set();
     /**
      * @param path - the snapshot file; an empty path keeps the store in memory.
      */
@@ -98,6 +99,7 @@ export class TeamMembershipStore {
             return;
         entry.teams.push(clean);
         this.persist();
+        this.notify();
     }
     /** Retract one membership; a no-op when absent. */
     remove(session, team) {
@@ -110,13 +112,34 @@ export class TeamMembershipStore {
             if (entry.teams.length === 0)
                 this.entries = this.entries.filter(candidate => candidate.session !== session);
             this.persist();
+            this.notify();
         }
     }
     /** Drop every declaration of one session (a left or archived node). */
     dropSession(session) {
         const before = this.entries.length;
         this.entries = this.entries.filter(entry => entry.session !== session);
-        if (this.entries.length !== before)
+        if (this.entries.length !== before) {
             this.persist();
+            this.notify();
+        }
+    }
+    /**
+     * #114 S6: observe changes — the listener runs after every write that
+     * changed the store (never on restore or reload). A throwing listener
+     * cannot break the write.
+     * @returns the unsubscribe function.
+     */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    notify() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch { /* a listener's failure is its own */ }
+        }
     }
 }