@nelsonlongxiang/dsh-open-a2a-net 0.5.14 → 0.6.24

package/lib/task-ledger.js

@@ -0,0 +1,540 @@
+/**
+ * Persisted async-task ledger (`<dsh-home>/a2a/tasks.json`). The receipt
+ * contract makes the target answer a fire-and-forget route with a message
+ * starting `[A2A receipt] task <task_id> <outcome summary>`, but the caller
+ * had no book to reconcile against — pending tasks were unqueryable and a
+ * restart forgot them all. The ledger keeps one record per routed task that
+ * is still owed a reply, correlates the receipt by its task id, and persists
+ * so a node restart does not orphan the reconciliation.
+ *
+ * Three-tier book (v0.5.29): the owed book holds only unsettled rows —
+ * `pending`, or `dead` once a row sits past {@link TASK_STALE_TTL_MS} (swept
+ * lazily on every entry point, never timer-driven — this host restarts too
+ * often for in-memory timers). Dead rows exit the owed view and disarm the
+ * async nudge via {@link TaskLedger.isPending}, yet still settle on a late
+ * receipt. Every settled row leaves the owed book for the bounded archive,
+ * so resolution history stops being silently evicted by the {@link TASK_CAP}
+ * slice (the evidence-loss defect behind the "the ledger keeps growing"
+ * illusion: settlements vanished while debts piled up).
+ * @module @nelsonlongxiang/dsh-open-a2a-net/task-ledger
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { parseReceipt, RECEIPT_OUTCOMES } from "./receipt.js";
+/**
+ * Caller-ended summaries (abandon / cancel) share one isolation law: late
+ * receipts never rewrite the verdict — they only stamp lateReceiptAt, and
+ * the projected outcome collapses to 'abandoned'.
+ */
+const CALLER_ENDED_PREFIX = /^caller-(abandoned|cancelled)/;
+/** Hard cap on the owed book (pending + dead-lettered rows, most recent first). */
+export const TASK_CAP = 64;
+/** Hard cap on the settled archive (most recent kept). */
+export const ARCHIVE_CAP = 64;
+/** Longest receipt summary kept on a record (multi-line outcomes collapse). */
+export const SUMMARY_CAP = 200;
+/**
+ * Longest dispatch brief kept per row. A ledger row without its payload is
+ * unreadable to supervision — "direct-8f3a1c2b → dsh/ec4ce7f8, 3h old" says
+ * nothing about whether to nudge, abandon, or read the receipt. The brief is
+ * the first non-empty line of the message, capped; the full body never enters
+ * the ledger (it can be arbitrarily large and may quote another session's log).
+ */
+export const BRIEF_CAP = 120;
+/** Reduce a dispatch body to one readable line: first non-empty line, collapsed, capped. */
+export function briefOf(message) {
+    if (message === undefined)
+        return undefined;
+    for (const raw of message.split('\n')) {
+        const line = raw.trim().replace(/\s+/g, ' ');
+        if (line !== '')
+            return line.length <= BRIEF_CAP ? line : `${line.slice(0, BRIEF_CAP - 1)}…`;
+    }
+    return undefined;
+}
+/**
+ * Age at which an unsettled task auto-dead-letters. A dead row exits the
+ * owed view, disarms its async-nudge retry (a cold session cannot consume a
+ * re-steer anyway), and still accepts a late receipt from a revived target.
+ * Injectable per instance so tests can use short windows; sweeping stays
+ * lazy — every read/write entry point sweeps first.
+ */
+export const TASK_STALE_TTL_MS = 24 * 60 * 60_000;
+/**
+ * Bounded outbound-task ledger with whole-file persistence. Pure of any
+ * routing knowledge: callers {@link track} a task when a route leaves it
+ * owed a receipt and feed every inbound/relayed message through
+ * {@link resolveFromMessage} for correlation.
+ */
+export class TaskLedger {
+    path;
+    /** Owed-book rows, most recently tracked first; settled rows leave here. */
+    tasks = [];
+    /** Settled rows, most recently resolved first; bounded by the archive cap. */
+    archived = [];
+    staleTtlMs;
+    archiveCap;
+    /** Injectable clock (option `now`). */
+    now;
+    /**
+     * @param path - persistence file (`<dsh-home>/a2a/tasks.json`); empty = no persistence.
+     * @param options - TTL/capacity overrides; defaults come from the exported constants.
+     */
+    constructor(path, options) {
+        this.path = path;
+        this.staleTtlMs = options?.staleTtlMs ?? TASK_STALE_TTL_MS;
+        this.archiveCap = options?.archiveCap ?? ARCHIVE_CAP;
+        this.now = options?.now ?? (() => Date.now());
+        this.restore();
+    }
+    /**
+     * Every unsettled task (pending + dead-lettered), most recently tracked first.
+     * Sweeping runs first, so an overdue pending row reports as dead here.
+     * @returns the owed-book records.
+     */
+    list() {
+        this.sweep(this.now());
+        return [...this.tasks];
+    }
+    /**
+     * The settled archive, most recently resolved first. Rows land here the
+     * moment their receipt correlates and stay until the archive cap evicts
+     * the oldest — receipts keep correlating against them, so a repeat or a
+     * delayed duplicate refreshes instead of resolving nothing.
+     * @returns the archived records.
+     */
+    archive() {
+        return [...this.archived];
+    }
+    /**
+     * Remember one outbound task owed a receipt, most-recent first, bounded by
+     * {@link TASK_CAP} over the owed book only (settled rows live in the
+     * archive, never silently evicted). A task id is caller-born and
+     * single-use: a known id in either tier keeps its first record verbatim.
+     * @param taskId - the correlation key the receipt echoes.
+     * @param team - the team the route addressed.
+     * @param peer - the candidate that accepted the delivery ('local' or URL).
+     * @param contextId - the delivery's conversation id, kept for follow-up routes (empty omits it).
+     */
+    /**
+     * Fix ② (ghost-debt stop): register one delivered async dispatch whose
+     * callback address could not be resolved — the row stays VISIBLE (the
+     * ledger is honest) but carries receiptExpected:false, so neither the
+     * owed book nor the settleable bucket ever counts it. Reconciliation is
+     * via context_id follow-ups (the dispatch reply already says so).
+     * Idempotent by task id like {@link track}.
+     */
+    trackReceiptless(taskId, team, peer, contextId, brief) {
+        if (taskId === '')
+            return;
+        this.sweep(this.now());
+        if (this.tasks.some(entry => entry.taskId === taskId))
+            return;
+        if (this.archived.some(entry => entry.taskId === taskId))
+            return;
+        this.tasks = [{
+                taskId,
+                team,
+                peer,
+                startedAt: this.now(),
+                direction: 'outbound',
+                receiptExpected: false,
+                ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
+                ...(brief !== undefined && brief !== '' ? { brief } : {}),
+                status: 'pending',
+            }, ...this.tasks].slice(0, TASK_CAP);
+        this.persist();
+    }
+    track(taskId, team, peer, contextId, brief) {
+        if (taskId === '')
+            return;
+        this.sweep(this.now());
+        if (this.tasks.some(entry => entry.taskId === taskId))
+            return;
+        if (this.archived.some(entry => entry.taskId === taskId))
+            return;
+        this.tasks = [{
+                taskId,
+                team,
+                peer,
+                startedAt: this.now(),
+                direction: 'outbound',
+                ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
+                ...(brief !== undefined && brief !== '' ? { brief } : {}),
+                status: 'pending',
+            }, ...this.tasks].slice(0, TASK_CAP);
+        this.persist();
+    }
+    /**
+     * F2' (receipt-settlement): remember one INBOUND delivery owed a receipt —
+     * this node is the settlement debtor here: the caller waits for a receipt
+     * only this target can produce. Before this row type existed, inbound
+     * deliveries were born ledger-less, so the async nudge's isPending gate
+     * no-op'd for exactly the deliveries that stall (08-30 evidence: zero
+     * ledger records for latched activations). Idempotent by task id like
+     * {@link track}.
+     * @param taskId - the correlation key the caller's task was born with.
+     * @param team - the team the delivery addressed (this node's).
+     * @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) {
+        if (taskId === '')
+            return;
+        this.sweep(this.now());
+        if (this.tasks.some(entry => entry.taskId === taskId))
+            return;
+        if (this.archived.some(entry => entry.taskId === taskId))
+            return;
+        this.tasks = [{
+                taskId,
+                team,
+                peer: `local:${from}`,
+                startedAt: this.now(),
+                direction: 'inbound',
+                ...(receiptExpected === false ? { receiptExpected: false } : {}),
+                ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
+                ...(brief !== undefined && brief !== '' ? { brief } : {}),
+                status: 'pending',
+            }, ...this.tasks].slice(0, TASK_CAP);
+        this.persist();
+    }
+    /**
+     * v0.5.23 (async-stall): whether a tracked task still owes its receipt.
+     * The async nudge consults this — a resolved or dead-lettered task
+     * disarms its retry (re-steering a session that could not start a turn
+     * past its own stale window is noise, not recovery).
+     * @param taskId - the correlation key the receipt echoes.
+     * @returns true when the task is tracked pending inside its TTL.
+     */
+    isPending(taskId) {
+        const record = this.tasks.find(entry => entry.taskId === taskId);
+        if (record === undefined || record.status !== 'pending')
+            return false;
+        return this.now() - record.startedAt <= this.staleTtlMs;
+    }
+    /**
+     * Caller-side give-up (work-order P1a): clears one owed row into the
+     * archive under a `caller-abandoned` outcome so waiters stop occupying the
+     * remote budget and the three-tier book stays honest about who ended it.
+     * NOT cooperative cancellation — the remote may still be working. A late
+     * receipt against an abandoned row lands as orphan metadata
+     * ({@link ArchivedRecord.lateReceiptAt}) without rewriting the decision.
+     * Idempotent and total per the consumer contract: repeat calls and unknown
+     * ids return stable structured outcomes, never throw.
+     * @param taskId - the correlation key to abandon.
+     * @param reason - optional short cause, folded into the archived summary.
+     * @returns `{outcome:'cleared'}` when a pending/dead row was settled now,
+     * `'already-terminal'` when the archive already held the task's end,
+     * `'unknown'` when neither tier ever saw the id.
+     */
+    abandon(taskId, reason) {
+        if (taskId === '')
+            return { outcome: 'unknown', taskId };
+        this.sweep(this.now());
+        const record = this.tasks.find(entry => entry.taskId === taskId);
+        if (record !== undefined) {
+            this.tasks = this.tasks.filter(entry => entry.taskId !== taskId);
+            const resolvedAt = this.now();
+            const cause = reason === undefined || reason === '' ? '' : `: ${reason.slice(0, SUMMARY_CAP - 'caller-abandoned:'.length)}`;
+            this.archiveSettled({
+                taskId: record.taskId,
+                team: record.team,
+                peer: record.peer,
+                startedAt: record.startedAt,
+                ...(record.contextId !== undefined ? { contextId: record.contextId } : {}),
+                ...(record.brief !== undefined ? { brief: record.brief } : {}),
+                resolvedAt,
+                summary: `caller-abandoned${cause}`,
+                outcome: 'abandoned',
+            });
+            this.persist();
+            return { outcome: 'cleared', taskId, archivedAt: resolvedAt };
+        }
+        const settled = this.archived.find(entry => entry.taskId === taskId);
+        if (settled === undefined)
+            return { outcome: 'unknown', taskId };
+        return { outcome: 'already-terminal', taskId, archivedAt: settled.resolvedAt };
+    }
+    /**
+     * Cooperative cancellation (work-order P1b): ends one owed row like
+     * {@link abandon} but marks it `caller-cancelled` so downstream tooling
+     * tells "stopped waiting" from "ordered a stop". Implemented standalone
+     * (not via a shared endTask core) deliberately: abandon() is already
+     * reviewed semantics on this stack — touching it would ripple re-review;
+     * the ~20 duplicated lines buy a frozen reviewed surface.
+     * Cross-node targets degrade honestly: no reachable lane ⇒ no notify —
+     * the route layer reads team/contextId from here for its best-effort
+     * steer, which is the documented boundary until origin-auth lands.
+     */
+    cancel(taskId, reason) {
+        if (taskId === '')
+            return { outcome: 'unknown', taskId };
+        this.sweep(this.now());
+        const record = this.tasks.find(entry => entry.taskId === taskId);
+        if (record !== undefined) {
+            this.tasks = this.tasks.filter(entry => entry.taskId !== taskId);
+            const resolvedAt = this.now();
+            const cause = reason === undefined || reason === '' ? '' : `: ${reason.slice(0, SUMMARY_CAP - 'caller-cancelled:'.length)}`;
+            this.archiveSettled({
+                taskId: record.taskId,
+                team: record.team,
+                peer: record.peer,
+                startedAt: record.startedAt,
+                ...(record.contextId !== undefined ? { contextId: record.contextId } : {}),
+                ...(record.brief !== undefined ? { brief: record.brief } : {}),
+                resolvedAt,
+                summary: `caller-cancelled${cause}`,
+                outcome: 'abandoned',
+            });
+            this.persist();
+            return {
+                outcome: 'cleared',
+                taskId,
+                archivedAt: resolvedAt,
+                team: record.team,
+                ...(record.contextId !== undefined ? { contextId: record.contextId } : {}),
+            };
+        }
+        const settled = this.archived.find(entry => entry.taskId === taskId);
+        if (settled === undefined)
+            return { outcome: 'unknown', taskId };
+        return { outcome: 'already-terminal', taskId, archivedAt: settled.resolvedAt };
+    }
+    /**
+     * Correlate one message against the ledger: a receipt (message starting
+     * `[A2A receipt] task <id> …`) settles its task into the archive, keeping
+     * the outcome summary; a repeat or late receipt refreshes that archived
+     * 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.
+     * @returns what the receipt settled, or `undefined` when the message
+     *   correlated nothing.
+     */
+    resolveFromMessage(message) {
+        const parsed = parseReceipt(message);
+        if (parsed === null)
+            return undefined;
+        const taskId = parsed.taskId;
+        const summary = parsed.summary.trim().slice(0, SUMMARY_CAP); // Controlled vocabulary only: a foreign outcome string never lands here.
+        const envelopeOutcome = parsed.envelope?.outcome !== undefined ? parsed.envelope.outcome : undefined;
+        const elapsedMs = parsed.envelope?.elapsedMs;
+        this.sweep(this.now());
+        const record = this.tasks.find(entry => entry.taskId === taskId);
+        if (record !== undefined) {
+            this.tasks = this.tasks.filter(entry => entry.taskId !== taskId);
+            this.archiveSettled({
+                taskId: record.taskId,
+                team: record.team,
+                peer: record.peer,
+                startedAt: record.startedAt,
+                ...(record.contextId !== undefined ? { contextId: record.contextId } : {}),
+                ...(record.brief !== undefined ? { brief: record.brief } : {}),
+                resolvedAt: this.now(),
+                ...(summary !== '' ? { summary } : {}),
+                ...(envelopeOutcome !== undefined ? { outcome: envelopeOutcome } : {}),
+                ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+            });
+            this.persist();
+            return {
+                taskId,
+                team: record.team,
+                peer: record.peer,
+                // A dead row still lives in the tasks array (the sweep only flips
+                // status): its receipt is a revival — the late marker's first form.
+                ...(record.status === 'dead' ? { late: true } : {}),
+                ...(envelopeOutcome !== undefined ? { outcome: envelopeOutcome } : {}),
+                ...(summary !== '' ? { summary } : {}),
+            };
+        }
+        const settled = this.archived.find(entry => entry.taskId === taskId);
+        if (settled === undefined)
+            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
+        // pin the projected verdict to 'abandoned'.
+        const callerEnded = CALLER_ENDED_PREFIX.test(settled.summary ?? '');
+        this.archived = [
+            {
+                ...settled,
+                ...(callerEnded
+                    ? { lateReceiptAt: this.now(), outcome: 'abandoned' }
+                    : {
+                        resolvedAt: this.now(),
+                        ...(summary !== '' ? { summary } : {}),
+                        ...(envelopeOutcome !== undefined ? { outcome: envelopeOutcome } : {}),
+                    }),
+            },
+            ...this.archived.filter(entry => entry.taskId !== taskId),
+        ];
+        this.persist();
+        return {
+            taskId,
+            team: settled.team,
+            peer: settled.peer,
+            ...(envelopeOutcome !== undefined ? { outcome: envelopeOutcome } : {}),
+            ...(summary !== '' ? { summary } : {}),
+            // The late marker's second form: the caller had already moved on
+            // (abandonment recorded verbatim). A HEALTHY row's duplicate refresh
+            // is neither dead-lettered nor abandoned — it carries no marker.
+            ...(callerEnded ? { late: true } : {}),
+        };
+    }
+    /**
+     * F5 (settlement integrity): settle pending rows by CONTENT ECHO — an
+     * inbound message that references `task <id>` of a pending row counts as
+     * the peer demonstrably responding to that task, even when the formal
+     * `[A2A receipt]` envelope never rode the reply (the 08-30 shape: content
+     * answered, formality lost). The receipt envelope keeps precedence: this
+     * runs only when {@link resolveFromMessage} correlated nothing. Echo-
+     * settled rows archive with a marker summary so the audit trail shows
+     * they were echoes, not envelopes.
+     * @param message - the inbound message text.
+     * @returns the task ids this message settled (usually none or one).
+     */
+    resolveEcho(message) {
+        const settled = [];
+        this.sweep(this.now());
+        for (const record of [...this.tasks]) {
+            if (record.status !== 'pending')
+                continue;
+            if (!message.includes(`task ${record.taskId}`))
+                continue;
+            this.tasks = this.tasks.filter(entry => entry.taskId !== record.taskId);
+            this.archiveSettled({
+                taskId: record.taskId,
+                team: record.team,
+                peer: record.peer,
+                startedAt: record.startedAt,
+                ...(record.contextId !== undefined ? { contextId: record.contextId } : {}),
+                resolvedAt: this.now(),
+                summary: '(settled by content echo)',
+            });
+            settled.push(record.taskId);
+        }
+        if (settled.length > 0)
+            this.persist();
+        return settled;
+    }
+    /** Move one settled record to the archive head, trimming at the cap. */
+    archiveSettled(record) {
+        this.archived = [record, ...this.archived].slice(0, this.archiveCap);
+    }
+    /** Lazy dead-letter sweep: overdue pending rows flip status, at most once. */
+    sweep(now) {
+        let changed = false;
+        for (const entry of this.tasks) {
+            if (entry.status === 'pending' && now - entry.startedAt > this.staleTtlMs) {
+                entry.status = 'dead';
+                entry.deadAt = now;
+                // F5 layer-3: stamp WHY the row aged — a fire-and-forget row
+                // (receiptExpected:false) expiring is expected bookkeeping; a
+                // receipt-owed row expiring means the settlement chain failed for
+                // that delivery and deserves supervision attention.
+                entry.reason = entry.receiptExpected === false ? 'fire-forget' : 'unconsumed';
+                changed = true;
+            }
+        }
+        if (changed)
+            this.persist();
+    }
+    /** Load a persisted snapshot on construction, if present. */
+    restore() {
+        if (this.path === '' || !existsSync(this.path))
+            return;
+        try {
+            const snapshot = JSON.parse(readFileSync(this.path, 'utf8'));
+            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 === '')
+                        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') {
+                        this.archived.push({
+                            taskId: entry.taskId,
+                            team: typeof entry.team === 'string' ? entry.team : '',
+                            peer: typeof entry.peer === 'string' ? entry.peer : '',
+                            startedAt: typeof entry.startedAt === 'number' && Number.isFinite(entry.startedAt) ? entry.startedAt : this.now(),
+                            ...(typeof entry.contextId === 'string' && entry.contextId !== '' ? { contextId: entry.contextId } : {}),
+                            ...(typeof entry.brief === 'string' && entry.brief !== '' ? { brief: entry.brief } : {}),
+                            resolvedAt: typeof entry.resolvedAt === 'number' && Number.isFinite(entry.resolvedAt) ? entry.resolvedAt : this.now(),
+                            ...(typeof entry.summary === 'string' && entry.summary !== '' ? { summary: entry.summary } : {}),
+                            ...(typeof entry.outcome === 'string' && RECEIPT_OUTCOMES.includes(entry.outcome) ? { outcome: entry.outcome } : {}),
+                            ...(typeof entry.lateReceiptAt === 'number' && Number.isFinite(entry.lateReceiptAt) ? { lateReceiptAt: entry.lateReceiptAt } : {}),
+                        });
+                        continue;
+                    }
+                    restored.push({
+                        taskId: entry.taskId,
+                        team: typeof entry.team === 'string' ? entry.team : '',
+                        peer: typeof entry.peer === 'string' ? entry.peer : '',
+                        startedAt: typeof entry.startedAt === 'number' && Number.isFinite(entry.startedAt) ? entry.startedAt : this.now(),
+                        ...(typeof entry.contextId === 'string' && entry.contextId !== '' ? { contextId: entry.contextId } : {}),
+                        ...(typeof entry.brief === 'string' && entry.brief !== '' ? { brief: entry.brief } : {}),
+                        ...(entry.direction === 'inbound' ? { direction: 'inbound' } : {}),
+                        ...(entry.receiptExpected === false ? { receiptExpected: false } : {}),
+                        status: entry.status === 'dead' ? 'dead' : 'pending',
+                        ...(entry.status === 'dead'
+                            ? {
+                                deadAt: typeof entry.deadAt === 'number' && Number.isFinite(entry.deadAt) ? entry.deadAt : this.now(),
+                                ...(entry.reason === 'fire-forget' || entry.reason === 'unconsumed' ? { reason: entry.reason } : {}),
+                            }
+                            : {}),
+                    });
+                }
+            }
+            const legacyArchive = snapshot?.archived;
+            if (Array.isArray(legacyArchive)) {
+                for (const raw of legacyArchive) {
+                    const entry = raw;
+                    if (typeof entry?.taskId !== 'string' || entry.taskId === '')
+                        continue;
+                    if (this.archived.some(existing => existing.taskId === entry.taskId))
+                        continue;
+                    this.archived.push({
+                        taskId: entry.taskId,
+                        team: typeof entry.team === 'string' ? entry.team : '',
+                        peer: typeof entry.peer === 'string' ? entry.peer : '',
+                        startedAt: typeof entry.startedAt === 'number' && Number.isFinite(entry.startedAt) ? entry.startedAt : this.now(),
+                        ...(typeof entry.contextId === 'string' && entry.contextId !== '' ? { contextId: entry.contextId } : {}),
+                        ...(typeof entry.brief === 'string' && entry.brief !== '' ? { brief: entry.brief } : {}),
+                        resolvedAt: typeof entry.resolvedAt === 'number' && Number.isFinite(entry.resolvedAt) ? entry.resolvedAt : this.now(),
+                        ...(typeof entry.summary === 'string' && entry.summary !== '' ? { summary: entry.summary } : {}),
+                        ...(typeof entry.outcome === 'string' && RECEIPT_OUTCOMES.includes(entry.outcome) ? { outcome: entry.outcome } : {}),
+                        ...(typeof entry.lateReceiptAt === 'number' && Number.isFinite(entry.lateReceiptAt) ? { lateReceiptAt: entry.lateReceiptAt } : {}),
+                    });
+                }
+            }
+            this.tasks = restored.slice(0, TASK_CAP);
+            this.archived = this.archived.slice(0, this.archiveCap);
+        }
+        catch {
+            // A corrupt ledger is not fatal: routing never depends on it; the
+            // reconciliation simply starts fresh.
+        }
+    }
+    /** Persist the ledger (no-op when no path was configured). */
+    persist() {
+        if (this.path === '')
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            const snapshot = {
+                tasks: this.tasks.map(task => ({ ...task })),
+                ...(this.archived.length > 0 ? { archived: this.archived.map(entry => ({ ...entry })) } : {}),
+            };
+            writeFileSync(this.path, JSON.stringify(snapshot), { mode: 0o600 });
+        }
+        catch {
+            // An unwritable home must not break routing; the ledger degrades to
+            // memory-only.
+        }
+    }
+}

package/lib/team-store.js

@@ -0,0 +1,122 @@
+/**
+ * Persisted team-membership declarations: which routable teams each joined
+ * session node declares itself a member of (`a2a/teams.json`). Membership
+ * is the node's own state — the inverse of canvas teams, where a team
+ * declares its members — and is published serve-fresh on the host card so
+ * a team's roster rebuilds as the union of member declarations (desired
+ * state, no central directory; the S2 half of the team-roster iteration).
+ * Joins are allowlist-gated at the tool layer; the store is pure storage.
+ * Plain JSON, one writer (the a2a_team_join / a2a_team_leave tools), read
+ * fresh by the state route.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/team-store
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Upper bounds: a curation surface, not a database. */
+export const TEAM_NODE_CAP = 64;
+export const TEAMS_PER_NODE_CAP = 16;
+/** Longest accepted team name (full routable form, `zone/<id8>` etc.). */
+export const TEAM_NAME_MAX = 60;
+function validTeam(raw) {
+    const clean = raw.trim();
+    if (clean === '' || clean.length > TEAM_NAME_MAX)
+        return undefined;
+    return clean;
+}
+/**
+ * Bounded membership store with last-write-wins persistence. Pure of any
+ * policy: callers gate joins and resolve rosters.
+ */
+export class TeamMembershipStore {
+    /** Entries in first-declaration order; teams in join order. */
+    entries = [];
+    path;
+    /**
+     * @param path - the snapshot file; an empty path keeps the store in memory.
+     */
+    constructor(path) {
+        this.path = path;
+        this.restore();
+    }
+    /** Load a persisted snapshot, if present and well-formed. */
+    restore() {
+        if (this.path === '' || !existsSync(this.path))
+            return;
+        try {
+            const snapshot = JSON.parse(readFileSync(this.path, 'utf8'));
+            const raw = Array.isArray(snapshot?.memberships)
+                ? snapshot.memberships
+                : [];
+            for (const entry of raw) {
+                if (typeof entry.session !== 'string' || entry.session === '')
+                    continue;
+                if (!Array.isArray(entry.teams))
+                    continue;
+                const teams = entry.teams
+                    .filter((team) => typeof team === 'string')
+                    .map(team => validTeam(team))
+                    .filter((team) => team !== undefined);
+                if (teams.length > 0)
+                    this.entries.push({ session: entry.session, teams });
+            }
+        }
+        catch {
+            // A malformed snapshot stays unloaded; the next write replaces it.
+        }
+    }
+    persist() {
+        if (this.path === '')
+            return;
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify({ memberships: this.entries }));
+    }
+    /** Membership entries, copies — callers cannot mutate the store. */
+    list() {
+        return this.entries.map(entry => ({ session: entry.session, teams: [...entry.teams] }));
+    }
+    /** Teams one session node declares, in join order. */
+    teamsOf(session) {
+        return [...(this.entries.find(entry => entry.session === session)?.teams ?? [])];
+    }
+    /** Local sessions declaring one team, in declaration order. */
+    membersOf(team) {
+        return this.entries.filter(entry => entry.teams.includes(team)).map(entry => entry.session);
+    }
+    /** Declare one membership. Idempotent; silently caps at the bounds. */
+    add(session, team) {
+        const clean = validTeam(team);
+        if (clean === undefined || session === '')
+            return;
+        let entry = this.entries.find(candidate => candidate.session === session);
+        if (entry === undefined) {
+            if (this.entries.length >= TEAM_NODE_CAP)
+                return;
+            entry = { session, teams: [] };
+            this.entries.push(entry);
+        }
+        if (entry.teams.includes(clean) || entry.teams.length >= TEAMS_PER_NODE_CAP)
+            return;
+        entry.teams.push(clean);
+        this.persist();
+    }
+    /** Retract one membership; a no-op when absent. */
+    remove(session, team) {
+        const entry = this.entries.find(candidate => candidate.session === session);
+        if (entry === undefined)
+            return;
+        const index = entry.teams.indexOf(team);
+        if (index >= 0) {
+            entry.teams.splice(index, 1);
+            if (entry.teams.length === 0)
+                this.entries = this.entries.filter(candidate => candidate.session !== session);
+            this.persist();
+        }
+    }
+    /** 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)
+            this.persist();
+    }
+}

package/lib/teams-bridge.js

@@ -0,0 +1,18 @@
+/**
+ * Structural contract for the native-teams A2A transport bridge (the
+ * node-unification design's outbound half-bridge).
+ *
+ * Contract ownership belongs to `@nelsonlongxiang/dsh-native-teams`
+ * (`src/a2a-face.ts`, 0.14.0). These are this plugin's local structural
+ * mirrors — plugins never value-import each other, so the shapes are
+ * restated here and kept in lockstep by the three-party protocol docs
+ * (exposure-grants / t3-declaration-remote-members). Any drift is a
+ * protocol-doc bug first.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/teams-bridge
+ */
+/**
+ * Service key the face mounts under. Frozen by the tool face's
+ * `NATIVE_TEAMS_A2A_FACE_KEY` (mirrored verbatim per the single-source
+ * discipline; the protocol docs arbitrate any dispute).
+ */
+export const NATIVE_TEAMS_A2A_FACE_KEY = 'nativeTeamsA2a';