@onlyne/lib 3.0.0 → 3.1.0

package/src/threads.ts

@@ -1,6 +1,6 @@
-import { admissionView, fail, key, page, requireValue, utc } from './core.js';
-import type { Context } from './core.js';
-import type { Auth, Entry, Event, Grant, Json, Member, MessageRef, Mutation, Page, PageOptions, ReadScope, ReplyPermit, Thread, ThreadRef, Transaction } from './types.js';
+import { admissionView, decimal, fail, key, page, requireValue, utc } from './core.ts';
+import type { Context } from './core.ts';
+import type { Attention, Auth, Entry, Event, Grant, JoinedThread, Json, LocalAttention, Member, MessageRef, Mutation, Outbound, Page, PageOptions, ReadScope, ReplyPermit, Thread, ThreadDescription, ThreadRef, Transaction } from './types.ts';
 
 /** One reserved default-thread id per owner: omitted targets land here, and the id is never reused. */
 export const DEFAULT_THREAD = 'thr-default';
@@ -113,18 +113,22 @@ interface Known {
 }
 
 export class ThreadService {
-  constructor(private readonly ctx: Context) {}
+  readonly #ctx: Context;
+
+  constructor(ctx: Context) {
+    this.#ctx = ctx;
+  }
 
   async create(auth: Auth, mutation: Mutation & { title: string; id?: string; default?: boolean }): Promise<Thread> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
     const owner = auth.actor;
-    this.ctx.owner(owner);
+    this.#ctx.owner(owner);
     if (typeof mutation.title !== 'string' || mutation.title.length === 0) fail('invalid_request', 'A thread needs a title.');
     if (mutation.id !== undefined && (typeof mutation.id !== 'string' || mutation.id.length === 0)) fail('invalid_request', 'Thread id must be a non-empty string.');
     const wantsDefault = mutation.default === true || mutation.id === DEFAULT_THREAD;
     const body = { title: mutation.title, id: mutation.id ?? null, default: wantsDefault };
-    return this.ctx.mutate(auth, 'thread.create', mutation, body, async tx => {
-      const at = new Date(this.ctx.now()).toISOString();
+    return this.#ctx.mutate(auth, 'thread.create', mutation, body, async tx => {
+      const at = new Date(this.#ctx.now()).toISOString();
       const existingDefault = await tx.get<Thread>(key('thread', owner, DEFAULT_THREAD));
       if (wantsDefault) {
         if (existingDefault) {
@@ -158,29 +162,67 @@ export class ThreadService {
   async close(auth: Auth, ref: ThreadRef, mutation: Mutation): Promise<Thread> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
     requireThreadRef(ref);
-    this.ctx.owner(ref.owner);
+    this.#ctx.owner(ref.owner);
     if (auth.actor !== ref.owner) fail('forbidden', 'Only the owner may close a thread.');
     const body = { ref };
-    return this.ctx.mutate(auth, `thread.close/${ref.owner}/${ref.id}`, mutation, body, async tx => {
-      const thread = await loadThread(tx, this.ctx, ref);
+    return this.#ctx.mutate(auth, `thread.close/${ref.owner}/${ref.id}`, mutation, body, async tx => {
+      const thread = await loadThread(tx, this.#ctx, ref);
       if (thread.state === 'closed') fail('thread_closed', 'The thread is already closed.');
-      return recordEvent(tx, { ...thread, state: 'closed', closed_at: new Date(this.ctx.now()).toISOString() }, 'thread_closed', {});
+      return recordEvent(tx, { ...thread, state: 'closed', closed_at: new Date(this.#ctx.now()).toISOString() }, 'thread_closed', {});
     });
   }
 
   async list(auth: Auth, options: PageOptions = {}): Promise<Page<Thread>> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
-    this.ctx.owner(auth.actor);
-    return this.ctx.storage.transaction(async tx => {
+    this.#ctx.owner(auth.actor);
+    return this.#ctx.storage.transaction(async tx => {
       const threads = sortedBy((await tx.scan<Thread>(key('thread', auth.actor) + '/')).map(row => row.value), thread => thread.thread_ref.id);
       return page(threads, options, { kind: 'threads', owner: auth.actor }, thread => thread.thread_ref.id);
     });
   }
 
-  async describe(auth: Auth, ref: ThreadRef): Promise<{ thread: Thread; members: Member[] }> {
+  /**
+   * Participant view: the threads this node was invited into and does not own, derived only
+   * from the records it already holds — the known-owner rows and grant notices `acceptGrant`
+   * wrote, the attention and inbox rows that name a thread, and the receipts of messages it
+   * sent there. The title, the state and the member table belong to the owner, so they are
+   * absent here; a caller that can reach the owner fills them in. This listing never invents
+   * a member it could not read.
+   */
+  async joined(auth: Auth, options: PageOptions = {}): Promise<Page<JoinedThread>> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
-    return this.ctx.storage.transaction(async tx => {
-      const thread = await loadThread(tx, this.ctx, ref);
+    if (auth.actor !== this.#ctx.node) fail('forbidden', 'The joined-thread view belongs to this node.');
+    return this.#ctx.storage.transaction(async tx => {
+      const rows = new Map<string, { ref: ThreadRef; seq: string; messages: Set<string> }>();
+      const hold = (ref: ThreadRef, seq?: string, message?: MessageRef): void => {
+        // A thread this node owns is already in `list()`; this view is the other side of it.
+        if (ref.owner === this.#ctx.node) return;
+        const slot = key(ref.owner, ref.id);
+        const held = rows.get(slot) ?? { ref: { owner: ref.owner, id: ref.id }, seq: '0', messages: new Set<string>() };
+        rows.set(slot, held);
+        if (seq !== undefined && decimal(seq) > decimal(held.seq)) held.seq = seq;
+        if (message !== undefined) held.messages.add(key(message.sender, message.id));
+      };
+      for (const row of await tx.scan<Known>(key('known') + '/')) hold(row.value.thread_ref);
+      for (const row of await tx.scan<Grant>(key('grant') + '/')) hold(row.value.thread_ref);
+      for (const row of await tx.scan<Attention>(key('attention') + '/')) hold(row.value.thread_ref, row.value.seq, row.value.message_ref);
+      for (const row of await tx.scan<LocalAttention>(key('inbox') + '/')) hold(row.value.attention.thread_ref, row.value.attention.seq, row.value.attention.message_ref);
+      for (const row of await tx.scan<Outbound>(key('outbound') + '/')) {
+        const receipt = row.value.receipt;
+        if (receipt !== undefined) hold(receipt.thread_ref, receipt.seq, receipt.message_ref);
+      }
+      const items = sortedBy([...rows.values()], row => key(row.ref.owner, row.ref.id))
+        .map((row): JoinedThread => ({
+          thread_ref: row.ref, last_seq: row.seq, message_count: row.messages.size, read_only: true,
+        }));
+      return page(items, options, { kind: 'joined', owner: auth.actor }, item => key(item.thread_ref.owner, item.thread_ref.id));
+    });
+  }
+
+  async describe(auth: Auth, ref: ThreadRef): Promise<ThreadDescription> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    return this.#ctx.storage.transaction(async tx => {
+      const thread = await loadThread(tx, this.#ctx, ref);
       if (!await canRead(tx, auth.actor, ref)) fail('forbidden', 'The caller does not hold read access to this thread.');
       const members = (await tx.scan<Member>(key('member', ref.owner, ref.id) + '/')).map(row => row.value);
       return { thread, members };
@@ -198,19 +240,19 @@ export class ThreadService {
       fail('forbidden', 'A peer may only join or withdraw itself.');
     }
     const body = { ref, peer, patch };
-    return this.ctx.mutate(auth, `thread.member/${ref.owner}/${ref.id}/${peer}`, mutation, body, async tx => {
-      const thread = await loadThread(tx, this.ctx, ref);
+    return this.#ctx.mutate(auth, `thread.member/${ref.owner}/${ref.id}/${peer}`, mutation, body, async tx => {
+      const thread = await loadThread(tx, this.#ctx, ref);
       const current = await tx.get<Member>(key('member', ref.owner, ref.id, peer));
       let next: Member;
       if (!isOwner) {
         if (current === undefined) {
           if (patch.state === 'revoked') fail('not_found', 'No membership record to withdraw.');
           if (thread.state === 'closed') fail('thread_closed', 'A closed thread does not accept joins.');
-          const admitted = (await this.ctx.options.plugins.mayAdmit?.(auth.actor, ref, admissionView(tx))) === true;
-          next = { peer, state: admitted ? 'active' : 'requested', access: [...DEFAULT_ACCESS], read_scope: {}, revision: this.ctx.id() };
+          const admitted = (await this.#ctx.options.plugins.mayAdmit?.(auth.actor, ref, admissionView(tx))) === true;
+          next = { peer, state: admitted ? 'active' : 'requested', access: [...DEFAULT_ACCESS], read_scope: {}, revision: this.#ctx.id() };
         } else if (patch.state === 'revoked') {
           if (current.state !== 'active' && current.state !== 'requested') fail('conflict', 'This membership is already stopped.');
-          next = { ...current, state: 'revoked', access: [], revision: this.ctx.id() };
+          next = { ...current, state: 'revoked', access: [], revision: this.#ctx.id() };
         } else {
           fail('conflict', 'This peer already holds a membership record; only the owner changes it.');
         }
@@ -219,7 +261,7 @@ export class ThreadService {
         if (state !== 'requested' && state !== 'active' && state !== 'revoked' && state !== 'denied') fail('invalid_request', 'Unknown member state.');
         const stopping = state === 'revoked' || state === 'denied';
         const access = stopping ? [] : patch.access === undefined ? (current?.state === 'active' ? current.access : [...DEFAULT_ACCESS]) : requireAccess(patch.access);
-        next = { peer, state, access: [...access], read_scope: patch.read_scope === undefined ? (current?.read_scope ?? {}) : requireScope(patch.read_scope), revision: this.ctx.id() };
+        next = { peer, state, access: [...access], read_scope: patch.read_scope === undefined ? (current?.read_scope ?? {}) : requireScope(patch.read_scope), revision: this.#ctx.id() };
       }
       await tx.put(key('member', ref.owner, ref.id, peer), next);
       if (next.state === 'active' && current?.state !== 'active' && peer !== ref.owner) await issueGrant(tx, ref, peer, next.revision);
@@ -230,8 +272,8 @@ export class ThreadService {
 
   async members(auth: Auth, ref: ThreadRef, options: PageOptions = {}): Promise<Page<Member>> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
-    return this.ctx.storage.transaction(async tx => {
-      await loadThread(tx, this.ctx, ref);
+    return this.#ctx.storage.transaction(async tx => {
+      await loadThread(tx, this.#ctx, ref);
       if (!await canRead(tx, auth.actor, ref)) fail('forbidden', 'The caller does not hold read access to this thread.');
       const members = sortedBy((await tx.scan<Member>(key('member', ref.owner, ref.id) + '/')).map(row => row.value), member => member.peer);
       return page(members, options, { kind: 'members', ref }, member => member.peer);
@@ -240,8 +282,8 @@ export class ThreadService {
 
   async defaultThread(auth: Auth): Promise<ThreadRef> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
-    this.ctx.owner(auth.actor);
-    return this.ctx.storage.transaction(async tx => requireValue(await tx.get<ThreadRef>(key('default', auth.actor))));
+    this.#ctx.owner(auth.actor);
+    return this.#ctx.storage.transaction(async tx => requireValue(await tx.get<ThreadRef>(key('default', auth.actor))));
   }
 
   /**
@@ -251,8 +293,8 @@ export class ThreadService {
    */
   async notices(auth: Auth, options: PageOptions = {}): Promise<Page<Grant>> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
-    this.ctx.owner(auth.actor);
-    return this.ctx.storage.transaction(async tx => {
+    this.#ctx.owner(auth.actor);
+    return this.#ctx.storage.transaction(async tx => {
       const held = sortedBy((await tx.scan<Grant>(key('notice') + '/')).map(row => row.value).filter(grant => !grant.acked), grant => grant.id);
       return page(held, options, { kind: 'notices', owner: auth.actor }, grant => grant.id);
     });
@@ -265,7 +307,7 @@ export class ThreadService {
    */
   async grants(auth: Auth, options: PageOptions = {}): Promise<Page<Grant>> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
-    return this.ctx.storage.transaction(async tx => {
+    return this.#ctx.storage.transaction(async tx => {
       const held = sortedBy((await tx.scan<Grant>(key('grant') + '/')).map(row => row.value).filter(grant => !grant.acked), grant => grant.id);
       return page(held, options, { kind: 'grants', recipient: auth.actor }, grant => grant.id);
     });
@@ -274,7 +316,7 @@ export class ThreadService {
   /** Recipient side: records that the owner confirmed this grant, so it is not confirmed twice. */
   async ackGrantLocally(auth: Auth, ref: ThreadRef, id: string): Promise<void> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
-    await this.ctx.storage.transaction(async tx => {
+    await this.#ctx.storage.transaction(async tx => {
       const slot = key('grant', ref.owner, id);
       const stored = await tx.get<Grant>(slot);
       if (stored !== undefined && !stored.acked) await tx.put(slot, { ...stored, acked: true });
@@ -285,6 +327,10 @@ export class ThreadService {
    * Recipient side of grant acceptance: an owner pushes us a notice we received during
    * a prior join. We store both the notice and the known-owner record keyed owner+threadid.
    * Caller is the owner the notice names, notice is addressed to our node, thread stays on owner.
+   *
+   * A notice that names `previous_thread_ref` is a re-issue after its owner changed identity:
+   * the ref it names is the one this node learned before, so that known row is dropped. Two
+   * rows for one thread would make every reconciliation pass pull the dead owner.
    */
   async acceptGrant(auth: Auth, grant: Grant): Promise<Grant> {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
@@ -293,18 +339,31 @@ export class ThreadService {
     }
     requireThreadRef(grant.thread_ref);
     if (grant.thread_ref.owner !== auth.actor) fail('forbidden', 'A grant notice must come from the thread owner it names.');
-    if (grant.recipient !== this.ctx.node) fail('forbidden', 'The grant notice is addressed to another node.');
+    if (grant.recipient !== this.#ctx.node) fail('forbidden', 'The grant notice is addressed to another node.');
+    const previous = grant.previous_thread_ref;
+    if (previous !== undefined) requireThreadRef(previous);
     const ref: ThreadRef = { owner: grant.thread_ref.owner, id: grant.thread_ref.id };
-    return this.ctx.storage.transaction(async tx => {
+    return this.#ctx.storage.transaction(async tx => {
       const slot = key('grant', ref.owner, grant.id);
       const stored = await tx.get<Grant>(slot);
-      if (stored !== undefined && (stored.recipient !== this.ctx.node || stored.revision !== grant.revision || stored.thread_ref.id !== ref.id)) {
+      if (stored !== undefined && (stored.recipient !== this.#ctx.node || stored.revision !== grant.revision || stored.thread_ref.id !== ref.id)) {
         fail('id_conflict', 'The grant id is bound to another notice.');
       }
       const known: Known = { owner: ref.owner, thread_ref: ref, revision: grant.revision };
       await tx.put(key('known', ref.owner, ref.id), known);
+      if (previous !== undefined && (previous.owner !== ref.owner || previous.id !== ref.id)) {
+        await tx.delete(key('known', previous.owner, previous.id));
+        // The copied grant rows under the old owner are what the confirmation pass walks: left
+        // in place they keep confirming a notice the dead owner issued and keep the dead thread
+        // in this node's joined list. A re-issue replaces them, so drop every row that names it.
+        for (const row of await tx.scan<Grant>(key('grant') + '/')) {
+          if (row.value.thread_ref.owner === previous.owner && row.value.thread_ref.id === previous.id) {
+            await tx.delete(row.key);
+          }
+        }
+      }
       if (stored !== undefined) return stored;
-      const next: Grant = { id: grant.id, recipient: this.ctx.node, thread_ref: ref, revision: grant.revision, acked: false };
+      const next: Grant = { id: grant.id, recipient: this.#ctx.node, thread_ref: ref, revision: grant.revision, acked: false };
       await tx.put(slot, next);
       return next;
     });
@@ -318,7 +377,7 @@ export class ThreadService {
     if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
     if (typeof id !== 'string' || id.length === 0) fail('invalid_request', 'A grant id is required.');
     const body = { id };
-    return this.ctx.mutate(auth, `thread.grant.ack/${id}`, mutation, body, async tx => {
+    return this.#ctx.mutate(auth, `thread.grant.ack/${id}`, mutation, body, async tx => {
       const grant = requireValue(await tx.get<Grant>(key('notice', id)));
       if (grant.recipient !== auth.actor) fail('forbidden', 'The grant notice is addressed to another recipient.');
       if (grant.acked) return grant;
@@ -335,12 +394,12 @@ export class ThreadService {
     if (original.sender !== auth.actor) fail('forbidden', 'Only the original message sender may issue a reply permit.');
     if (typeof permit.grantee !== 'string' || !permit.grantee || permit.grantee === auth.actor) fail('invalid_request', 'A permit names one grantee other than its issuer.');
     requireThreadRef(permit.landing);
-    this.ctx.owner(permit.landing.owner);
+    this.#ctx.owner(permit.landing.owner);
     if (!Number.isInteger(permit.remaining) || permit.remaining < 1) fail('invalid_request', 'A permit needs a bounded positive reply count.');
-    if (utc(permit.expires_at) <= this.ctx.now()) fail('invalid_request', 'A permit needs a future expiry.');
+    if (utc(permit.expires_at) <= this.#ctx.now()) fail('invalid_request', 'A permit needs a future expiry.');
     const body = { message_ref: { sender: original.sender, id: original.id }, grantee: permit.grantee, landing: permit.landing, expires_at: permit.expires_at, remaining: permit.remaining, followup: permit.followup === true };
-    return this.ctx.mutate(auth, `thread.permit/${original.sender}/${original.id}/${permit.grantee}`, mutation, body, async tx => {
-      const thread = await loadThread(tx, this.ctx, permit.landing);
+    return this.#ctx.mutate(auth, `thread.permit/${original.sender}/${original.id}/${permit.grantee}`, mutation, body, async tx => {
+      const thread = await loadThread(tx, this.#ctx, permit.landing);
       if (thread.state === 'closed') fail('thread_closed', 'A permit cannot land on a closed thread.');
       const stored: ReplyPermit = { ...body, revoked: permit.revoked === true };
       await tx.put(key('permit', original.sender, original.id, permit.grantee), stored);

package/src/transport.ts

@@ -1,6 +1,6 @@
-import { OnlyneError } from './core.js';
-import type { ErrorCode, Failure, NodeId, Target, Transport, TrustEntry } from './types.js';
-import type { TrustService } from './keys.js';
+import { OnlyneError } from './core.ts';
+import type { ErrorCode, Failure, NodeId, Target, Transport, TrustEntry } from './types.ts';
+import type { TrustService } from './keys.ts';
 
 /** The trust reads and signing steps a transport performs; a host that builds its own node wraps the real service. */
 export type SigningTrust = Pick<TrustService, 'entry' | 'signRequest' | 'verifyResponse'>;
@@ -64,11 +64,15 @@ function failureRecord(parsed: unknown): unknown {
 /**
  * RFC 0017 §3: what a signed request hits when this node holds no trusted key for the peer.
  * Both node ids travel in the text and in `details`, because a missing key here says nothing
- * about whether the peer runs. The agent cannot pair the nodes — only the node's holder can,
- * through the host surface — and the runtime re-sends the record that stays open, so the code
- * is `unavailable` and the message keeps that retry apart from an agent repeating the send.
- * The failure names the responsible holder and the act; the host's `guidance` adds the menu
- * entry, so every trust case ends at one concrete surface instead of a search.
+ * about whether the peer runs. The runtime re-sends the record that stays open, so the code is
+ * `unavailable` and the message keeps that retry apart from an agent repeating the send.
+ *
+ * A pending exchange is not a task for the reader: the invitation is already recorded on the
+ * side that owes the approval, and the acquisition policy there submits the approval on the
+ * next attempt, or that node's holder confirms it (RFC 0018 §4). The text says that instead of
+ * prescribing a menu step, because with policy `all` or `segment` no one has to act. The
+ * `no_record` and `revoked` cases keep the host's `guidance` menu, since nothing records them
+ * yet and only a holder can start or restore the exchange.
  */
 function missingTrust(
   self: NodeId | null, target: NodeId, peer: TrustEntry | undefined,
@@ -85,8 +89,11 @@ function missingTrust(
   const surface = guide === undefined ? '' : `: ${guide.entry.join(' → ')}`;
   const failure = guide === undefined ? details : { ...details, entry: guide.entry };
   if (reason === 'no_record') {
+    // The exchange has a sanctioned start that is not a human step: `trust_begin` on this
+    // node, judged by this node's acquisition policy, and the peer's policy judges the
+    // statement that arrives. Naming only the panel hid that path (tern host report).
     return new OnlyneError('unavailable',
-      `${here} holds no trust record for ${target}, so this request cannot be signed. This agent cannot grant trust; the holder of ${here} completes the pairing through this node's Onlyne surface${surface}. ${retry}`,
+      `${here} holds no trust record for ${target}, so this request cannot be signed. Start the exchange with trust_begin, which the acquisition policy on ${here} judges; ${target} can also start one, and this node's policy judges the arriving statement. A holder can complete the pairing through this node's Onlyne surface${surface}. ${retry}`,
       failure);
   }
   if (reason === 'revoked') {
@@ -95,8 +102,8 @@ function missingTrust(
       failure);
   }
   const message = peer!.local_approved
-    ? `${target} has not answered the exchange ${here} requested, so this request cannot be signed yet. This agent cannot complete the pairing; the holder of ${target} confirms it through that node's Onlyne surface${surface}. ${retry}`
-    : `${target} requested an exchange with ${here} and this node has not approved it, so this request cannot be signed yet. This agent cannot approve it; the holder of ${here} confirms the fingerprint through this node's Onlyne surface${surface}. ${retry}`;
+    ? `${target} has not answered the exchange ${here} requested, so this request cannot be signed yet. The invitation is recorded at ${target} as pending; the acquisition policy on that node submits the approval on the next attempt, or its holder confirms it${surface}. ${retry}`
+    : `${target} requested an exchange with ${here} and this node has not approved it, so this request cannot be signed yet. The invitation is recorded here as pending; this node's acquisition policy submits the approval on the next attempt, or its holder confirms it${surface}. ${retry}`;
   return new OnlyneError('unavailable', message, failure);
 }
 

package/src/types.ts

@@ -77,6 +77,28 @@ export interface Thread {
   event_seq: string; created_at: string; closed_at: string | null;
   messages_until?: string;
 }
+/**
+ * A thread this node was invited into and does not own. Every field here comes from a record
+ * this node already holds; the owner's title, state and member table are filled in only by a
+ * caller that could ask the owner, and a row that could not ask keeps the failure instead of
+ * inventing them.
+ */
+export interface JoinedThread {
+  thread_ref: ThreadRef;
+  /** The highest sequence this node holds a local record for; `0` when it holds none. */
+  last_seq: string;
+  /** Distinct messages this node holds for the thread. */
+  message_count: number;
+  /** A participant never owns the member table, so this view is read-only by construction. */
+  read_only: true;
+  title?: string;
+  state?: Thread['state'];
+  members?: Member[];
+  /** The owner could not be asked; the row stays listed with what the local records prove. */
+  unavailable?: Failure;
+}
+/** One thread record with its member table: what the describe read answers, here or at the owner. */
+export interface ThreadDescription { thread: Thread; members: Member[] }
 export interface Attention {
   obligation_id: string; recipient: NodeId; thread_ref: ThreadRef; seq: string;
   message_ref: MessageRef; authenticated_author: NodeId; acked: boolean;
@@ -86,6 +108,12 @@ export interface Attention {
 }
 export interface Grant {
   id: string; recipient: NodeId; thread_ref: ThreadRef; revision: string; acked: boolean;
+  /**
+   * Set on a re-issued notice: the ref the recipient learned under the previous owner. The
+   * recipient stores the new known row and drops the one this names, so a renamed owner does
+   * not leave a second row pointing at an endpoint that no longer exists.
+   */
+  previous_thread_ref?: ThreadRef;
 }
 export interface Event {
   id: string; type: 'message' | 'membership' | 'thread_closed' | 'resource_event' | 'operation';
@@ -139,11 +167,16 @@ export interface OperationRecord {
 export interface Outbound {
   request: SendRequest; expected_author: NodeId; state: 'pending' | 'accepted' | 'refused' | 'unknown';
   receipt?: Receipt; error?: Failure; created_at?: string;
+  /** The peer this send addresses when it differs from the endpoint that stores the entry. */
+  addressee?: NodeId;
+  /** The caller's own spelling of the addressee, when it differs from the resolved node id. */
+  requested?: string;
 }
 export interface HistoryMessage {
   message_ref: MessageRef; message: Message; direction: 'in' | 'out';
   thread_ref?: ThreadRef; seq?: string; at: string | null;
   delivery: Outbound['state'] | 'received'; consumption?: 'pending' | 'consumed';
+  settlement?: AttentionSettlement;
   guarantee?: Storage['guarantee']; error?: Failure;
 }
 export interface Conversation {
@@ -151,15 +184,17 @@ export interface Conversation {
   last_at: string | null;
 }
 export interface HistoryQuery extends PageOptions { thread?: ThreadRef; message?: MessageRef }
+export type AttentionSettlement =
+  | { via: 'handover'; resource_ref: ResourceRef; handler: NodeId; revision: string; at: string }
+  | { via: 'undeliverable'; resource_ref: ResourceRef; reason: 'resource-unavailable'; at: string };
 /**
- * One queued obligation and what became of it. `context` is where the delivery was sent;
- * `injected` is **observed**, not submitted: it flips only in `confirmConsumption`, once the
- * host has seen the entry in a provider request. A message submitted into a session that never
- * reads it therefore stays `injected: false` and keeps its place in unread and alerts
- * (caerulea report 3, problem 1). The name predates that rule and is kept because renaming it
- * would read every stored row as unobserved and re-inject what was already read.
+ * `injected` closes the local delivery obligation after observed consumption or an explicit
+ * settlement. A settlement records why delivery ended without claiming model consumption.
  */
-export interface LocalAttention { attention: Attention; context?: string; injected: boolean }
+export interface LocalAttention {
+  attention: Attention; context?: string; injected: boolean; settlement?: AttentionSettlement;
+  resource_check_failures?: number;
+}
 export interface Target { node_id: NodeId; base_url: string; headers?: Record<string, string> }
 export interface Transport {
   request<T>(target: NodeId, method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<T>;
@@ -193,11 +228,19 @@ export type TraceEvent =
   | { event: 'inbound.duplicate'; sender: NodeId; message: string }
   | { event: 'inbound.acked'; obligation: string; thread: ThreadRef; seq: string }
   | { event: 'inbound.inject'; thread: ThreadRef; seq: string; context: string; outcome: InjectOutcome; reason?: string }
+  | { event: 'inbound.settled'; thread: ThreadRef; seq: string; settlement: AttentionSettlement }
+  | { event: 'inbound.resource-check.failed'; thread: ThreadRef; seq: string; resource_ref: ResourceRef; code: ErrorCode; attempts: number }
   | { event: 'consumption.confirmed'; thread: ThreadRef; seq: string; context: string; via: 'fragment' | 'tool_result' }
-  | { event: 'outbound.admitted'; sender: NodeId; message: string; target: string; state: string; guarantee?: string; code?: string }
+  | { event: 'outbound.admitted'; sender: NodeId; message: string; target: string; state: string; guarantee?: string; code?: string; resolved?: NodeId }
   | { event: 'outbound.redriven'; sender: NodeId; message: string; target: string }
   | { event: 'outbound.expired'; sender: NodeId; message: string; code: string }
-  | { event: 'await.settled'; thread: ThreadRef; seq: string; waiters: number };
+  | { event: 'await.settled'; thread: ThreadRef; seq: string; waiters: number }
+  /**
+   * A known owner this node could not reconcile, written at most once per (owner, thread, code)
+   * per window. `attempts` is how many failed passes that one line accounts for, the suppressed
+   * duplicates included; the local rows a failed pull never reached are still owed, not dropped.
+   */
+  | { event: 'reconcile.failed'; owner: NodeId; thread: string; code: ErrorCode; message: string; attempts: number };
 /** What the host did with one inbound entry, reported back with the injection result. */
 export type InjectOutcome = 'delivered' | 'queued' | 'waiting' | 'skipped' | 'consumed';
 export interface Runtime {
@@ -331,6 +374,8 @@ export interface Plugins {
   resolve(node: NodeId): Promise<Target>;
   decide(input: MsgInput): Promise<Action>;
   runtime?: Runtime;
+  /** When true, candidate exchange allows loopback addresses (useful in local dev & testing). */
+  allow_loopback?: boolean;
   /** Supplied when the host wants the library to own the maintenance loop (RFC 0017 §6). */
   maintenanceClock?: MaintenanceClock;
   resources?: ResourceDriver;