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

package/lib/types/task-auth.d.ts

@@ -0,0 +1,271 @@
+/** The admission basis (closed set, design §2.2). */
+export type Via = 'host-face' | 'joined-session' | 'canvas-member' | 'peer-org' | 'cli-deposit' | 'open';
+/** The exact rule that admitted a caller (closed set, design §2.2). */
+export type AdmissionRule = 'scope-off' | 'host-face' | 'local-exempt' | 'roster-shared' | 'canvas-shared' | 'remote-ref-samezone' | 'remote-ref-foreign' | 'peer-org' | 'node-fact' | 'cli-deposit';
+/** Every rule's basis — the mapping the authorization record stores beside the rule. */
+export declare const VIA_OF: Readonly<Record<AdmissionRule, Via>>;
+/**
+ * One admission decision. `basis` lists every shared team that held; `rule`
+ * is the first branch of the decision that hit (deterministic, so a record
+ * built from it is reproducible).
+ */
+export type Admission = {
+    readonly ok: true;
+    readonly via: Via;
+    readonly rule: AdmissionRule;
+    readonly basis: readonly string[];
+} | {
+    readonly ok: false;
+    readonly refusal: string;
+};
+/** The refusal text of a decision, or undefined when admitted — the shape the faces have always read. */
+export declare const refusalOf: (admission: Admission) => string | undefined;
+/** One cached peer card's published canvas org (gh#71). */
+export interface PeerOrgEntry {
+    readonly team?: unknown;
+    readonly members?: unknown;
+}
+/**
+ * This host's records, read at decision time. Every field the admission
+ * rules consult and nothing else — the caller's self-description never
+ * appears here (gh#7 N3, V5).
+ */
+export interface AdmissionRecords {
+    readonly zone: string;
+    readonly teamScopeRouting: boolean;
+    id8(id: string): string;
+    canvasTeamOf(name: string): string;
+    memberships(): readonly {
+        readonly session: string;
+        readonly teams: readonly string[];
+    }[];
+    joined(): readonly string[];
+    canvasNames(): readonly string[];
+    /** Canvas names the session sits in. */
+    canvasTeamsOf(sessionId: string): readonly string[];
+    canvasMembersOf(name: string): readonly string[];
+    canvasRemoteMembersOf(name: string): readonly string[];
+    /** The canvasOrg lists of the warm peer-card cache. */
+    peerOrgs(): Iterable<readonly PeerOrgEntry[]>;
+    liveNodeIds(): readonly string[];
+    cliDeposited(handle: string): boolean;
+}
+/**
+ * W1/W2 shared-team admission core: a same-zone zone/id8 caller passes when
+ * it holds a team this host's records also hold. The caller's basis is its
+ * roster declarations UNION its canvas memberships (W2②); a handle that
+ * resolves to no local session is a cross-host member whose basis is this
+ * host's remote member refs (#43) and the warm cache's two-way canvasOrg
+ * (gh#71 ②). F5: with a target, the intersection is at target level.
+ */
+export declare function sameZoneAdmission(r: AdmissionRecords, caller: string, targetTeam?: string): Admission;
+/**
+ * W1: the joined-face gate for the LOCAL dispatch candidate — only a
+ * zone/id8 label of THIS zone is judged (the shared-team core); every other
+ * label is outside this gate.
+ */
+export declare function joinedFaceAdmission(r: AdmissionRecords, callerSession: string | undefined, targetTeam?: string): Admission | undefined;
+/**
+ * #139: the admission an in-process dispatch is recorded under (design §2.4):
+ * the joined face's shared-team verdict, or `local-exempt` for the callers
+ * dispatchLocalCandidate does not gate (the initiator face, a foreign-zone
+ * label, an agent-less call). A refused joined face never dispatches.
+ */
+export declare function localCandidateAdmission(r: AdmissionRecords, callerSession: string | undefined, targetTeam?: string): Admission;
+/** Inbound admission for the peer faces (/a2a/direct, /a2a/log): caller_session is the contract. */
+export declare function callerAdmission(r: AdmissionRecords, caller: string, targetTeam?: string): Admission;
+/**
+ * The inputs of the allowlist version (design §2.3): only operator-controlled
+ * records the admission rules really read. The peer-card canvasOrg is left
+ * out on purpose — it is the remote's self-description and churns with the
+ * cache; a peer-org record carries its org entry in `basis` instead.
+ */
+export interface AllowlistInputs {
+    readonly zone: string;
+    readonly scope: readonly [teamScopeRouting: boolean, originClaimWindow: boolean];
+    readonly joined: readonly string[];
+    readonly roster: readonly (readonly [handle: string, team: string])[];
+    readonly canvas: readonly (readonly [team: string, members: readonly string[]])[];
+    readonly cli: readonly string[];
+    readonly links: readonly string[];
+}
+/**
+ * The canonical JSON the version hashes: fixed key order, arrays sorted and
+ * deduplicated, no whitespace. Strings sort by UTF-16 code unit (JavaScript's
+ * default `sort`) and are NOT Unicode-normalized: another implementation must
+ * do the same to reproduce a version.
+ */
+export declare function canonicalAllowlist(inputs: AllowlistInputs): string;
+/** `al1:` + the first 16 hex of sha256 over the canonical inputs. */
+export declare function allowlistVersion(inputs: AllowlistInputs): string;
+/**
+ * How strongly the caller's identity was proven at birth:
+ * - `origin-claim`: a bound, audience-correct envelope verified on a root-origin card for this caller.
+ * - `claim-mismatch`: bound proof names another caller, or root-origin derivation failed.
+ * - `legacy-window`: no envelope, admitted inside the OriginClaim window.
+ * - `unbound`: a v1 signature proves only key possession, not origin.
+ * - `cli-identity`: a deposited CLI key proves the local CLI handle, not market issuer origin.
+ * - `in-process`: a local delivery inside this host (S4).
+ * - `none`: no identity evidence at all.
+ */
+export type AuthProof = 'origin-claim' | 'claim-mismatch' | 'legacy-window' | 'unbound' | 'cli-identity' | 'in-process' | 'none';
+/**
+ * Frozen on an inbound ledger row when it is born, archived with it, never
+ * mutated: the answer to "on what authority did this host take this task".
+ */
+export interface TaskAuthorization {
+    readonly v: 1;
+    /** The caller_session the admission rules judged. */
+    readonly caller: string;
+    readonly proof: AuthProof;
+    /** Signed claim identity/origin retained for audit even when proof is low-trust unbound or CLI; its presence alone is not trust. */
+    readonly claim?: {
+        readonly caller: string;
+        readonly origin: string;
+    };
+    readonly ingress: 'wire' | 'local';
+    readonly via: Via;
+    readonly admission_rule: AdmissionRule;
+    /** Every shared team that held (cache-owed ones as `peer-org:<team>`). */
+    readonly basis: readonly string[];
+    readonly allowlist_version: string;
+    /** The team the task was delivered to. */
+    readonly target: string;
+    /** Where the receipt is owed. */
+    readonly receipt_target: string;
+    readonly received_at: number;
+    /** Audit only: the target was running another turn when the task arrived (never used to attribute turns). */
+    readonly target_busy?: true;
+}
+/** Bounds a persisted record must respect; anything outside them is malformed, not truncated. */
+export declare const AUTH_STRING_CAP = 256;
+export declare const AUTH_BASIS_CAP = 64;
+/** A record born more than this far in the future is a forgery or a broken clock, not a birth. */
+export declare const AUTH_CLOCK_SKEW_MS: number;
+/** Does a verified claim's signed zone cover the judged caller (the same name, or `<zone>/…`)? */
+export declare const claimCovers: (caller: string, claimCaller: string) => boolean;
+/** The facts of one delivery that the admission decision does not carry. */
+export interface AuthorizationFacts {
+    readonly caller: string;
+    readonly proof: AuthProof;
+    readonly claim?: {
+        readonly caller: string;
+        readonly origin: string;
+    };
+    readonly ingress: 'wire' | 'local';
+    readonly allowlistVersion: string;
+    readonly target: string;
+    readonly receiptTarget: string;
+    readonly receivedAt: number;
+    readonly targetBusy?: boolean;
+}
+/** The one constructor of a record: from an admitted decision and the delivery's facts. Frozen. */
+export declare function buildAuthorization(admission: Extract<Admission, {
+    ok: true;
+}>, facts: AuthorizationFacts): TaskAuthorization;
+/**
+ * #114 S5: the canonical JSON of one authorization record — the single
+ * implementation `authRef` hashes. Fixed key order (the {@link
+ * TaskAuthorization} declaration order), absent optional fields omitted,
+ * `basis` sorted and deduplicated (it is a set: the order admission found its
+ * teams in is not part of the authority), no whitespace. Persisted key order
+ * never matters, so a restored record yields the same ref as its original.
+ */
+export declare function canonicalAuthorization(auth: TaskAuthorization): string;
+/**
+ * #114 S5: the auto-receipt envelope's `authRef` — the first 16 hex of
+ * sha256 over {@link canonicalAuthorization}. Pins which inbound record a
+ * host-synthesized receipt answers; recorded for audit, judged by S4.
+ */
+export declare function authorizationRef(auth: TaskAuthorization): string;
+/**
+ * Restore-side allowlist for one persisted record (design §2.5): all of it or
+ * none of it — a record with any field outside its closed set or bounds, or
+ * any combination admission could never have produced, is dropped whole (the
+ * row is kept, as a pre-S2 row), never partially adopted. Later slices (S4
+ * settlement) trust what survives, so a corrupt or hand-edited tasks.json
+ * must not be able to plant a plausible record.
+ * @param now - the restore clock, for the future-birth bound.
+ */
+export declare function parseAuthorization(raw: unknown, now?: number): TaskAuthorization | undefined;
+/** `off`: no judgement. `observe` (default): judge and record, settle as before. `enforce`: an off-chain settlement is refused. */
+export type SettlementMode = 'off' | 'observe' | 'enforce';
+/** How a settler stands on the task's authorization chain. */
+export type ChainRole = 'target' | 'target-member' | 'host-face' | 'compat' | 'legacy';
+/** Why a settlement is (or would be) refused — closed set (design §4.4). */
+export type SettlementReason = 'settler-off-chain' | 'settler-unverified' | 'on-behalf-mismatch' | 'echo-off-chain';
+/** Who carried the receipt to this host (design §4.1). */
+export interface Settler {
+    /** The caller_session of the message that carries the receipt. */
+    readonly caller: string;
+    readonly proof: AuthProof;
+    /** The origin of a VERIFIED OriginClaim's card URL (claim-mismatch included), absent without one. */
+    readonly claimOrigin?: string;
+    /** The public key of that claim's verified card (#139): the host identity, whatever address spelling signed it. */
+    readonly claimKey?: string;
+    readonly ingress: 'wire' | 'local';
+}
+/** The ledger row a receipt correlates, as far as the judgement reads it. */
+export interface SettlementRow {
+    readonly team: string;
+    readonly peer: string;
+    readonly direction?: 'inbound' | 'outbound';
+    readonly auth?: TaskAuthorization;
+    /** #139: the public key of the peer card the row was dispatched to (remote outbound rows). */
+    readonly peerKey?: string;
+    /** #139: that card's session label, the peer host's process label. */
+    readonly peerHost?: string;
+    /** #139: the member that actually received the task (canvas and bare-zone deliveries). */
+    readonly deliveredTo?: string;
+}
+/** Facts from outside the row. */
+export interface SettlementFacts {
+    /** This host's process label: the caller its own auto-receipts carry. */
+    readonly hostLabel: string;
+    /** A canvas team's members (session ids and handles), undefined for any other team. */
+    membersOf(team: string): readonly string[] | undefined;
+    /** The receipt envelope's onBehalfOf (S5), when present. */
+    readonly onBehalfOf?: string;
+    /** The row was matched by a content echo, not a receipt header (weak evidence). */
+    readonly echo?: boolean;
+}
+/** #139 (design §4.4): what the wire response tells a sender whose receipt enforce refused. */
+export interface SettlementRefusal {
+    readonly status: 'refused';
+    readonly reason: SettlementReason;
+    readonly task_id: string;
+}
+export type SettlementVerdict = {
+    readonly ok: true;
+    readonly role: ChainRole;
+} | {
+    readonly ok: false;
+    readonly reason: SettlementReason;
+};
+/**
+ * Is this settler on the task's authorization chain? Pure. The chain:
+ * - `target`: the settler IS the team the task went to (an inbound row: its
+ *   record's target). Where that target lives decides how it may speak: a
+ *   LOCAL row's target (an inbound row, or an outbound row delivered on this
+ *   host) lives here, so it settles in-process only; a REMOTE row's target
+ *   settles over the wire with an OriginClaim that covers it AND comes from
+ *   the row's peer origin (a zone name alone is self-signable — review of
+ *   PR #140 P1-1/P1-3);
+ * - `target-member`: the team is a canvas and the settler the member that
+ *   received the task (`deliveredTo`, #139) — one of its current members for
+ *   a row born before the field — under the same where-it-lives rule;
+ * - `host-face`: the target's host settling on its behalf — an envelope
+ *   `onBehalfOf` naming the target (a member, or for a bare zone team one of
+ *   that zone's faces — the one that received it once `deliveredTo` is
+ *   known), carried locally by THIS host's process label, or across hosts by
+ *   the peer's process label (its card's session once recorded) with a
+ *   verified claim from the row's peer: its origin, or its card key (#139);
+ * - `compat`: an older host's auto-receipt (no onBehalfOf, its process label —
+ *   never a session face) with a verified claim from the row's peer origin
+ *   (design §6);
+ * - `legacy`: an inbound row born before S2 (no record) — allowed, counted.
+ * A remote target or member without a covering claim is `settler-unverified`;
+ * an onBehalfOf for someone else is `on-behalf-mismatch`; anything else is
+ * off-chain (`echo-off-chain` for an echo match).
+ */
+export declare function judgeSettlement(row: SettlementRow, settler: Settler, facts: SettlementFacts): SettlementVerdict;

package/lib/types/task-ledger.d.ts

@@ -18,7 +18,9 @@
  * illusion: settlements vanished while debts piled up).
  * @module @nelsonlongxiang/dsh-open-a2a-net/task-ledger
  */
+import { type AuthProof, type ChainRole, type SettlementReason, type SettlementVerdict, type TaskAuthorization } from './task-auth.ts';
 import { type ReceiptOutcomeV2 } from './receipt.ts';
+import { type ConservationSnapshot, type ConservationVerdict } from './ledger-conservation.ts';
 /** Hard cap on the owed book (pending + dead-lettered rows, most recent first). */
 export declare const TASK_CAP = 64;
 /** Hard cap on the settled archive (most recent kept). */
@@ -54,6 +56,45 @@ export type TaskStatus = 'pending' | 'dead';
 export type DeadReason = 'fire-forget' | 'unconsumed';
 /** gh#31: which archive path ended a row — a receipt, a content echo, or the caller. */
 export type ArchiveEnd = 'receipt' | 'echo' | 'abandoned' | 'cancelled' | 'evicted';
+/**
+ * #114 S3: who really sent one outbound task — the routing session, the
+ * agent-less host face, or a native-teams bridge submitter. Before this
+ * field every outbound row was attributable only to the host ("home"), so
+ * same-host seats could not be told apart.
+ */
+export interface Sender {
+    readonly kind: 'session' | 'host' | 'bridge';
+    /**
+     * A session's `<zone>/<id8>` node team, the host process label, or the
+     * bridge submitter. Group senders by `kind:id`, never by `id` alone: a host
+     * label set by hand may look like a session handle.
+     */
+    readonly id: string;
+    /**
+     * Host senders only: the label the call borrowed on the wire when it
+     * differs from {@link id} (quick dispatch rides a live joined session's
+     * team). Display context, never a bucket key.
+     */
+    readonly face?: string;
+}
+/** Longest sender id kept; anything longer is malformed, not truncated. */
+export declare 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 declare function parseSender(raw: unknown): Sender | undefined;
+/** #139: what an outbound row is born with besides its sender. */
+export interface OutboundBirth {
+    /** The local-candidate admission (ingress local); kept only on a row whose peer is 'local'. */
+    readonly auth?: TaskAuthorization;
+    readonly peerKey?: string;
+    readonly peerHost?: string;
+    readonly deliveredTo?: string;
+}
 /** One tracked outbound task still in the owed book (unsettled). */
 export interface TaskRecord {
     readonly taskId: string;
@@ -81,6 +122,20 @@ export interface TaskRecord {
      * replaying the conversation. Absent on rows persisted before this field.
      */
     readonly brief?: string;
+    /** #114 S3: the real sender of an outbound row (absent on inbound rows and rows persisted before the field). */
+    readonly sender?: Sender;
+    /**
+     * #114 S2: the immutable authorization the row was born with — an inbound
+     * row's wire admission, or (#139) an outbound row's local-candidate
+     * admission (`ingress: 'local'`). Absent on remote outbound and older rows.
+     */
+    readonly auth?: TaskAuthorization;
+    /** #139: the public key of the peer card a remote outbound row was dispatched to. */
+    readonly peerKey?: string;
+    /** #139: that card's session label (the peer host's process label). */
+    readonly peerHost?: string;
+    /** #139: the member that actually received the task (canvas / bare-zone deliveries). */
+    readonly deliveredTo?: string;
     status: TaskStatus;
     /** When the row was swept to dead-letter (absent while pending). */
     deadAt?: number;
@@ -126,6 +181,16 @@ export interface ArchivedRecord {
      * ever stored; absent means a receipt was owed (or the row predates the field).
      */
     readonly receiptExpected?: false;
+    /** #114 S3: copied from the owed row (absent on inbound rows and rows archived before the field). */
+    readonly sender?: Sender;
+    /** #114 S2: carried over from the live row unchanged. */
+    readonly auth?: TaskAuthorization;
+    /** #139: carried over from the live row unchanged (a late receipt is judged against them). */
+    readonly peerKey?: string;
+    readonly peerHost?: string;
+    readonly deliveredTo?: string;
+    /** #114 S4: who settled the row (receipt and echo ends), and their chain role. */
+    readonly settledBy?: SettledBy;
 }
 /**
  * How one archived row ended (gh#31). The recorded field wins; legacy rows
@@ -190,6 +255,47 @@ export interface ReceiptResolvedInfo {
 export interface TaskLedgerSnapshot {
     readonly tasks: readonly TaskRecord[];
     readonly archived?: readonly ArchivedRecord[];
+    /** #114 S4: the bounded ring of refused / would-be-refused settlements. */
+    readonly settlementRefusals?: readonly SettlementRefusalRecord[];
+    /** #114 S4: monotonic count of every refusal noted. */
+    readonly settlementRefusalsTotal?: number;
+    /** gh#154: lifetime conservation counters (persisted; absent = pre-#154 legacy) — the module contract, shared by classifier, counters, and this schema (review P3). */
+    readonly conservation?: ConservationSnapshot;
+}
+/** #114 S4: who settled an archived row, and how they stood on its authorization chain. */
+export interface SettledBy {
+    readonly caller: string;
+    readonly chain_role: ChainRole | 'off-chain';
+}
+/** #114 S4: one settlement the judgement refused (enforce) or would have refused (observe). */
+export interface SettlementRefusalRecord {
+    readonly taskId: string;
+    readonly at: number;
+    readonly settler: {
+        readonly caller: string;
+        readonly proof: AuthProof;
+        readonly ingress: 'wire' | 'local';
+    };
+    readonly reason: SettlementReason;
+    /** The receipt's first line, bounded. */
+    readonly head: string;
+    /** true: the settlement was refused (enforce); false: recorded only (observe). */
+    readonly enforced: boolean;
+    /** Repeats of the same (task, settler, reason) folded into this entry, so a flood cannot push older evidence out (review of PR #140 P2-4). */
+    readonly count: number;
+}
+/** Bound of the refusal ring (design §4.4). */
+export declare const SETTLEMENT_REFUSAL_CAP = 64;
+/**
+ * #114 S4: how the ledger asks whether a settler may settle a row. `check`
+ * is the pure judgement (task-auth.ts judgeSettlement) bound to this
+ * receipt's facts; `enforce` decides whether an off-chain verdict blocks
+ * the settlement or is only recorded.
+ */
+export interface SettlementJudge {
+    readonly enforce: boolean;
+    readonly settler: SettlementRefusalRecord['settler'];
+    check(row: Pick<TaskRecord, 'team' | 'peer' | 'direction' | 'auth' | 'peerKey' | 'peerHost' | 'deliveredTo'>, echo: boolean): SettlementVerdict;
 }
 /**
  * Bounded outbound-task ledger with whole-file persistence. Pure of any
@@ -203,6 +309,12 @@ export declare class TaskLedger {
     private tasks;
     /** Settled rows, most recently resolved first; bounded by the archive cap. */
     private archived;
+    /** #114 S4: refused / would-be-refused settlements, newest first. */
+    private refusals;
+    /** #114 S4: every refusal ever noted (monotonic; survives the ring's bound). */
+    private refusalsTotal;
+    /** 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. */
+    private readonly counters;
     private readonly staleTtlMs;
     private readonly archiveCap;
     /** Injectable clock (option `now`). */
@@ -244,8 +356,8 @@ export declare class TaskLedger {
      * via context_id follow-ups (the dispatch reply already says so).
      * Idempotent by task id like {@link track}.
      */
-    trackReceiptless(taskId: string, team: string, peer: string, contextId?: string, brief?: string): void;
-    track(taskId: string, team: string, peer: string, contextId?: string, brief?: string): void;
+    trackReceiptless(taskId: string, team: string, peer: string, contextId?: string, brief?: string, sender?: Sender, birth?: OutboundBirth): void;
+    track(taskId: string, team: string, peer: string, contextId?: string, brief?: string, sender?: Sender, birth?: OutboundBirth): void;
     /**
      * F2' (receipt-settlement): remember one INBOUND delivery owed a receipt —
      * this node is the settlement debtor here: the caller waits for a receipt
@@ -259,7 +371,7 @@ export declare 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: string, team: string, from: string, contextId?: string, receiptExpected?: boolean, brief?: string): void;
+    trackInbound(taskId: string, team: string, from: string, contextId?: string, receiptExpected?: boolean, brief?: string, auth?: TaskAuthorization, deliveredTo?: string): void;
     /**
      * v0.5.23 (async-stall): whether a tracked task still owes its receipt.
      * The async nudge consults this — a resolved or dead-lettered task
@@ -304,10 +416,12 @@ export declare 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: string): ReceiptResolvedInfo | undefined;
+    resolveFromMessage(message: string, judge?: SettlementJudge, only?: (record: TaskRecord) => boolean): ReceiptResolvedInfo | undefined;
     /**
      * F5 (settlement integrity): settle pending rows by CONTENT ECHO — an
      * inbound message that references `task <id>` of a pending row counts as
@@ -320,9 +434,32 @@ export declare class TaskLedger {
      * @param message - the inbound message text.
      * @returns the task ids this message settled (usually none or one).
      */
-    resolveEcho(message: string): string[];
-    /** Move one settled record to the archive head, trimming at the cap. */
+    resolveEcho(message: string, judge?: SettlementJudge): string[];
+    /** #114 S4: the owed row for a task id, if any (read-only; for the settlement gate). */
+    find(taskId: string): TaskRecord | undefined;
+    /** #114 S4: refused / would-be-refused settlements, newest first. */
+    settlementRefusals(): readonly SettlementRefusalRecord[];
+    /** #114 S4: every refusal ever noted, including those folded or pushed out of the ring. */
+    settlementRefusalsTotal(): number;
+    /**
+     * 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.
+     */
+    private noteRefusal;
+    /**
+     * 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.
+     */
     private archiveSettled;
+    /**
+     * 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(): ConservationVerdict;
     /**
      * gh#86 (chief order direct-4f596524): when the owed book exceeds
      * TASK_CAP, the overflow rows go to the ARCHIVE as evicted - visible

package/lib/types/team-store.d.ts

@@ -30,6 +30,7 @@ export declare class TeamMembershipStore {
     /** Entries in first-declaration order; teams in join order. */
     private entries;
     private readonly path;
+    private readonly listeners;
     /**
      * @param path - the snapshot file; an empty path keeps the store in memory.
      */
@@ -52,4 +53,12 @@ export declare class TeamMembershipStore {
     remove(session: string, team: string): void;
     /** Drop every declaration of one session (a left or archived node). */
     dropSession(session: string): void;
+    /**
+     * #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: () => void): () => void;
+    private notify;
 }

package/lib/types/tools/act.d.ts

@@ -0,0 +1,52 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Config } from '../index.ts';
+import type { ExposureStore } from '../exposure-store.ts';
+import type { JoinedSessions } from '../joined-store.ts';
+import type { TeamMembershipStore } from '../team-store.ts';
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Everything the action-plane tools capture from apply(). */
+export interface ActToolsDeps {
+    readonly ctx: Context;
+    readonly config: Config;
+    readonly logger: ReturnType<Context['logger']>;
+    readonly ownerAllowlist: readonly string[];
+    readonly sessionNodes: Map<string, Agent>;
+    readonly joinedSessions: JoinedSessions;
+    readonly teamMemberships: TeamMembershipStore;
+    readonly exposureStore: ExposureStore;
+    readonly reportRing: {
+        at: number;
+        level: 'info' | 'warning' | 'error';
+        message: string;
+        session: string;
+        task?: string;
+    }[];
+    readonly recordTeamAudit: (action: 'join' | 'leave' | 'archive-prune' | 'agent-less', team: string, id: string, ok: boolean, reason?: string) => void;
+    readonly a2aJoinGateRefusal: (exec: {
+        agent?: {
+            id: unknown;
+        };
+    } | undefined) => void;
+    readonly id8: (id: string) => string;
+    readonly routeTrunk: (args: {
+        team: string;
+        message: string;
+        context_id?: string;
+        async?: boolean;
+    }, agent: Agent | undefined, signal: AbortSignal, hostCaller?: string) => Promise<Record<string, JsonValue>>;
+}
+/**
+ * Build the five registrars. Invoke each at the tool's original registration
+ * position — the registry order the model sees must not change.
+ */
+export declare function createActTools(deps: ActToolsDeps): {
+    registerTeamJoin: () => void;
+    registerTeamLeave: () => void;
+    registerExposure: () => void;
+    registerReport: () => void;
+    registerRoute: () => void;
+};
+export {};

package/lib/types/tools/files.d.ts

@@ -0,0 +1,38 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Config } from '../index.ts';
+import { type BlobStore } from '../blob-store.ts';
+import { type OriginClaimTarget } from '../origin-claim.ts';
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Files one send may carry (one message; the FloodGuard per-transfer figure). */
+export declare const FILE_SEND_MAX = 16;
+/** The inbox directory under a session's workspace. */
+export declare const FILE_INBOX_DIR = "a2a-inbox";
+export interface FileToolsDeps {
+    readonly ctx: Context;
+    readonly config: Pick<Config, 'apiKey' | 'team'>;
+    readonly blobStore: BlobStore;
+    readonly canvasMembersOf: (name: string) => readonly string[];
+    /** This host's own card URL (live: it is known only once the web server settled). */
+    readonly ownCardUrl: () => string;
+    readonly sessionTeamOf: (agent: Agent) => string;
+    readonly a2aJoinGateRefusal: (exec: {
+        agent?: {
+            id: unknown;
+        };
+    } | undefined) => void;
+    readonly routeTrunk: (args: {
+        team: string;
+        message: string;
+        async?: boolean;
+    }, agent: Agent | undefined, signal: AbortSignal) => Promise<Record<string, JsonValue>>;
+    readonly peerFetch: typeof globalThis.fetch;
+    readonly originClaimHeaders: (target: OriginClaimTarget) => Record<string, string>;
+}
+export declare function createFileTools(d: FileToolsDeps): {
+    registerFileSend: () => void;
+    registerFileFetch: () => void;
+};
+export {};