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

package/lib/joined-store.js

@@ -26,6 +26,7 @@ export class JoinedSessions {
     path;
     /** Session ids, most recently joined first. */
     ids = [];
+    listeners = new Set();
     /**
      * @param path - persistence file (`<dsh-home>/a2a/joined.json`); empty = no persistence.
      */
@@ -54,8 +55,11 @@ export class JoinedSessions {
      * @param id - the joined session id.
      */
     add(id) {
+        const before = this.ids.join('\n');
         this.ids = [id, ...this.ids.filter(entry => entry !== id)].slice(0, JOIN_CAP);
         this.persist();
+        if (this.ids.join('\n') !== before)
+            this.notify();
     }
     /**
      * Forget one join intent (the leave operation; a no-op when absent).
@@ -66,6 +70,25 @@ export class JoinedSessions {
             return;
         this.ids = this.ids.filter(entry => entry !== id);
         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 */ }
+        }
     }
     /**
      * F7 (wake-intent self-heal): re-read the persisted snapshot into memory.

package/lib/ledger-conservation.js

@@ -0,0 +1,97 @@
+const ARCHIVE_ENDS = ['receipt', 'echo', 'abandoned', 'cancelled', 'evicted'];
+const intAtLeast0 = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= Number.MAX_SAFE_INTEGER;
+/**
+ * Restore-classify one snapshot's conservation block:
+ * - absent block → legacy bootstrap from what the rows prove;
+ * - present, fully valid (every field a non-negative integer, archiveTrimmed
+ *   bounded by the lifetime archived total, optional damaged marker a
+ *   non-empty string) → valid, counters load as persisted;
+ * - anything else (partial, negative, fractional, null body, unbounded trim)
+ *   → damaged: counters stay zero and the verdict refuses conserved.
+ */
+export function classifyConservationBlock(raw) {
+    if (raw === undefined)
+        return { kind: 'legacy' };
+    if (raw === null || typeof raw !== 'object')
+        return { kind: 'damaged', reason: 'conservation-block-invalid' };
+    const saved = raw;
+    const trackedOk = intAtLeast0(saved.trackedTotal);
+    const trimmedOk = intAtLeast0(saved.archiveTrimmed);
+    const restoreOk = intAtLeast0(saved.restoreTrimmed);
+    const byEndRaw = saved.archivedByEnd;
+    const byEnd = byEndRaw !== null && typeof byEndRaw === 'object' ? byEndRaw : undefined;
+    const byEndOk = byEnd !== undefined && ARCHIVE_ENDS.every(key => intAtLeast0(byEnd[key]));
+    if (!(trackedOk && trimmedOk && restoreOk && byEndOk))
+        return { kind: 'damaged', reason: 'conservation-block-invalid' };
+    const archivedByEnd = {};
+    let archivedTotal = 0;
+    for (const key of ARCHIVE_ENDS) {
+        archivedByEnd[key] = byEnd[key];
+        archivedTotal += byEnd[key];
+    }
+    if (saved.archiveTrimmed > archivedTotal)
+        return { kind: 'damaged', reason: 'conservation-block-invalid' };
+    const damaged = saved.damaged;
+    if (damaged !== undefined && (typeof damaged !== 'string' || damaged === ''))
+        return { kind: 'damaged', reason: 'conservation-block-invalid' };
+    return { kind: 'valid', snapshot: { trackedTotal: saved.trackedTotal, archivedByEnd, archiveTrimmed: saved.archiveTrimmed, restoreTrimmed: saved.restoreTrimmed, ...(typeof damaged === 'string' ? { damaged } : {}) } };
+}
+/** The counters themselves — one mutable holder the ledger owns. */
+export class ConservationCounters {
+    trackedTotal = 0;
+    archivedByEnd = { receipt: 0, echo: 0, abandoned: 0, cancelled: 0, evicted: 0 };
+    archiveTrimmed = 0;
+    restoreTrimmed = 0;
+    damaged;
+    /** Legacy bootstrap: the kept rows plus this load's cuts are all the snapshot proves. */
+    legacyBootstrap(owedCount, archive, restoreTrimmed, classify) {
+        this.trackedTotal = owedCount + archive.length + restoreTrimmed;
+        this.archiveTrimmed = 0;
+        this.restoreTrimmed = restoreTrimmed;
+        for (const row of archive)
+            this.archivedByEnd[classify(row)] += 1;
+    }
+    /** Valid-block load: counters EXACTLY as persisted (review P2: an undercount stays red — never repaired upward); restoreTrimmed ADDS this load's cuts to the persisted lifetime (review P2: neither overwrite nor max). */
+    loadFrom(snapshot, owedCount, archiveCount) {
+        this.trackedTotal = snapshot.trackedTotal;
+        this.archiveTrimmed = snapshot.archiveTrimmed;
+        this.restoreTrimmed += snapshot.restoreTrimmed;
+        for (const key of ARCHIVE_ENDS)
+            this.archivedByEnd[key] = snapshot.archivedByEnd[key];
+        if (snapshot.damaged !== undefined)
+            this.damaged = snapshot.damaged;
+        void owedCount;
+        void archiveCount;
+    }
+    /** The persisted shape (damaged rides along once stamped). */
+    toSnapshot() {
+        return {
+            trackedTotal: this.trackedTotal,
+            archivedByEnd: { ...this.archivedByEnd },
+            archiveTrimmed: this.archiveTrimmed,
+            restoreTrimmed: this.restoreTrimmed,
+            ...(this.damaged !== undefined ? { damaged: this.damaged } : {}),
+        };
+    }
+    /** The verdict's count half (the ledger supplies rows, owed count, duplicates). */
+    verdict(owedCount, archiveCount, duplicateTaskIds) {
+        const archivedTotal = ARCHIVE_ENDS.reduce((n, key) => n + this.archivedByEnd[key], 0);
+        const delta = this.trackedTotal - (owedCount + archivedTotal + this.restoreTrimmed);
+        // review P2: the archive lost rows only to its live cap or to the load cut.
+        const archiveLoss = archivedTotal - archiveCount - this.archiveTrimmed;
+        const trimConsistent = archiveLoss >= 0 && archiveLoss <= this.restoreTrimmed;
+        const damaged = this.damaged !== undefined ? this.damaged : trimConsistent ? undefined : 'archive-trim-inconsistent';
+        return {
+            conserved: duplicateTaskIds.length === 0 && delta === 0 && damaged === undefined,
+            delta,
+            trackedTotal: this.trackedTotal,
+            owed: owedCount,
+            archivedByEnd: { ...this.archivedByEnd },
+            archivedTotal,
+            archiveTrimmed: this.archiveTrimmed,
+            restoreTrimmed: this.restoreTrimmed,
+            duplicateTaskIds,
+            ...(damaged !== undefined ? { damaged } : {}),
+        };
+    }
+}

package/lib/legacy/teams-bridge-inbound.js

@@ -0,0 +1,156 @@
+/**
+ * Build the inbound bridge. The bodies are byte-identical to their apply()
+ * originals (same two-space indent); only the four capture points arrive as
+ * deps.
+ */
+export function createTeamsBridgeInbound(deps) {
+    const { ctx, config, liveAgent, fromClause, sanitizeFromClause, proofHeader, } = deps;
+    function teamsRegistry() {
+        const candidate = ctx.get('teams');
+        if (candidate === undefined || candidate === null)
+            return undefined;
+        if (typeof candidate.describeTarget !== 'function' || typeof candidate.startRound !== 'function' || typeof candidate.listTeams !== 'function')
+            return undefined;
+        return candidate;
+    }
+    /** Reply-wait parity with the steer path's 180s deadline: native-teams
+     * rounds settle on their own cadence, but a wedged seam must not park a
+     * caller past a bounded window (config.nativeRoundWaitMs). */
+    /** The claim table changes at registry-edit cadence: a short memo dedupes
+     * the double probe (callers pre-check, the round re-verifies) without
+     * pretending the answer is permanent. */
+    const BRIDGE_CLAIM_TTL_MS = 5_000;
+    const bridgeClaimCache = new Map();
+    const bridgeTimers = new Set();
+    ctx.effect(() => () => {
+        for (const timer of bridgeTimers)
+            clearTimeout(timer);
+    });
+    /**
+     * Whether the native-teams registry claims `team` as an unambiguous local
+     * target, memoized for {@link BRIDGE_CLAIM_TTL_MS}. Ordinary misses never
+     * throw (the D2 query contract); anything that does throw is treated as a
+     * miss — the bridge is a guest here. The memo is skipped entirely while
+     * the bridge is off, so the flag gates the probe itself.
+     */
+    async function nativeTeamsClaims(team) {
+        if (config.nativeTeamsInbound !== true)
+            return false;
+        const cached = bridgeClaimCache.get(team);
+        if (cached !== undefined && Date.now() - cached.at < BRIDGE_CLAIM_TTL_MS)
+            return cached.claimed;
+        const teams = teamsRegistry();
+        let claimed = false;
+        if (teams !== undefined) {
+            try {
+                const descriptor = await teams.describeTarget(team);
+                claimed = descriptor.plane === 'local' && descriptor.ambiguous !== true && descriptor.localLabel !== undefined;
+            }
+            catch {
+                claimed = false;
+            }
+        }
+        bridgeClaimCache.set(team, { at: Date.now(), claimed });
+        // Bounded memo: probe-miss names accumulate one tiny row each; past a
+        // generous cap, drop the whole table (a cold re-probe costs one local
+        // describeTarget call).
+        if (bridgeClaimCache.size > 512)
+            bridgeClaimCache.clear();
+        return claimed;
+    }
+    /**
+     * Resolve everything the round needs BEFORE any caller is told the
+     * dispatch happened: the claim, the seam, and a parent initiator. The
+     * `error` variant is the only fast-failure shape — `not-claimed` simply
+     * hands the address back to the standard resolution chain.
+     */
+    async function nativeTeamsPrepare(team) {
+        if (!await nativeTeamsClaims(team))
+            return { ok: false, reason: 'not-claimed' };
+        const teams = teamsRegistry();
+        if (teams === undefined)
+            return { ok: false, reason: 'not-claimed' };
+        const parent = liveAgent();
+        if (parent === undefined)
+            return { ok: false, reason: 'error', error: 'No live DSH initiator is available to parent the native-teams round.' };
+        deps.taint?.(parent);
+        // The alpha.4 Session face dropped the events member (the widened
+        // BridgeTeamsRegistry accepts it optional) — the raw Agent carries the
+        // ambient Session whose shape no longer overlaps, so project through the
+        // widened structural face explicitly (type-level only; the runtime value
+        // is the same live agent).
+        const parentFace = parent;
+        return { ok: true, teams, parent: parentFace };
+    }
+    /** The A2A envelope rides the round message so the dispatcher sees the network origin. */
+    function bridgeEnvelope(team, caller, message, taskId, proofClause, headerBuilder) {
+        const from = caller === '' ? 'an unknown node' : caller;
+        const taskPrefix = taskId === undefined ? '' : `(task ${taskId}) `;
+        const builder = headerBuilder ?? proofHeader;
+        const header = builder !== undefined && taskId !== undefined ? builder(team, taskId, from, proofClause) : `[A2A direct] ${taskPrefix}${proofClause} ${sanitizeFromClause(from)} (routed to ${team}) sent:`;
+        return `${header}\n\n${message}`;
+    }
+    /** The projection for a round that outlived the reply window: unlike the
+     * steer deadline's text, this must NOT promise a receipt — native-teams
+     * rounds route none in this slice. */
+    function bridgeUnsettledReply(team) {
+        return `The native-teams round for "${team}" is still running past the reply window; it was delivered and keeps going. Native-teams rounds route no A2A receipt in this slice — reconcile with a follow-up route (continuity rides the team's own durable round chain).`;
+    }
+    /**
+     * Fire the round and wait, bounded. The caller's signal (when it has one)
+     * cancels the round itself; the deadline releases the caller with the
+     * unsettled projection while the round keeps running detached.
+     * @param prepared - a ready dispatch (claim, seam, parent) from {@link nativeTeamsPrepare}.
+     */
+    async function nativeTeamsRound(prepared, team, caller, message, taskId, proofClause, external, headerBuilder) {
+        const controller = new AbortController();
+        // One listener, always removed after the race: an external abort cancels
+        // the round through its own controller.
+        const onExternalAbort = () => { controller.abort(); };
+        if (external !== undefined) {
+            if (external.aborted)
+                controller.abort();
+            else
+                external.addEventListener('abort', onExternalAbort);
+        }
+        if (controller.signal.aborted)
+            return { ok: false, error: 'aborted before the native-teams round was dispatched', phase: 'pre-dispatch' };
+        let roundError;
+        let deadlineTimer;
+        const deadline = new Promise(resolve => {
+            deadlineTimer = setTimeout(() => {
+                if (deadlineTimer !== undefined)
+                    bridgeTimers.delete(deadlineTimer);
+                resolve({ kind: 'deadline' });
+            }, config.nativeRoundWaitMs ?? 180_000);
+            deadlineTimer.unref?.();
+            bridgeTimers.add(deadlineTimer);
+        });
+        const verdict = await Promise.race([
+            prepared.teams.startRound({ team, message: bridgeEnvelope(team, caller, message, taskId, proofClause, headerBuilder) }, prepared.parent, controller.signal).then((reply) => ({ kind: 'settled', reply }), (error) => { roundError = error; return { kind: 'failed' }; }),
+            deadline,
+            new Promise(resolve => {
+                if (controller.signal.aborted)
+                    resolve({ kind: 'aborted' });
+                else
+                    controller.signal.addEventListener('abort', () => resolve({ kind: 'aborted' }), { once: true });
+            }),
+        ]);
+        // Hygiene: the losing deadline timer stops here (not 180s later), and
+        // the external-signal listener does not outlive the round.
+        if (deadlineTimer !== undefined) {
+            clearTimeout(deadlineTimer);
+            bridgeTimers.delete(deadlineTimer);
+        }
+        if (external !== undefined)
+            external.removeEventListener('abort', onExternalAbort);
+        if (verdict.kind === 'settled')
+            return { ok: true, reply: verdict.reply, settled: true };
+        if (verdict.kind === 'deadline')
+            return { ok: true, reply: bridgeUnsettledReply(team), settled: false };
+        if (verdict.kind === 'aborted')
+            return { ok: false, error: `the wait for the native-teams round "${team}" was aborted (the round was cancelled with it)`, aborted: true };
+        return { ok: false, error: `the native-teams round for "${team}" failed: ${String(roundError)}` };
+    }
+    return { teamsRegistry, nativeTeamsClaims, nativeTeamsPrepare, nativeTeamsRound };
+}