@onlyne/lib 3.0.0 → 3.1.0

package/README.md

@@ -60,6 +60,8 @@ A resource has one binding — the handler and the highest event it has confirme
 
 `client.readResources(query)` reads local resources or requests their owner's authenticated endpoint. The `ResourceReadQuery` operations are `list`, `describe`, `log`, `event`, `operations`, and `status`. The `decide` plugin can return `{ kind: 'read', scope: 'resources', query }` to use the same reader through `msg`. Reads create no operation record and do not call a resource driver.
 
+A queued entry that projects a resource event (`meta.data.resource_ref`, authenticated by that resource's owner) is checked against the binding before it is injected. If the binding names another handler, the row is settled with `settlement.via === 'handover'`; if this node may no longer read the resource, the row is settled as `undeliverable` with `reason: 'resource-unavailable'`. A transient failure leaves the row owed and is traced as `inbound.resource-check.failed`. Settlement closes the local delivery obligation. It records why delivery ended, and it does not assert that the model read the entry, so no consumption record and no todo are written.
+
 `list` accepts concrete `owners`, `page_size`, and `cursor`. Omitted `owners` selects the local node. The result contains `owners: [{ owner, page } | { owner, error }]`, so an unavailable owner remains visible beside successful pages. A cursor selects exactly one owner. The host chooses which owners to include. Other queries name `resource: { owner, id }`. `log` accepts an exclusive `since` event id, `page_size`, and `cursor`. `event` names `event_id`; `status` names `operation_id` and returns the existing operation record. The original actor can read that record after losing resource-read access. `operations` returns only the current actor's records.
 
 An operation result is `committed`, `pending`, `aborted`, or `unknown`. `aborted` means the endpoint refused or locally stopped the call and confirmed that no external effect happened; a failure whose side effect cannot be ruled out is `unknown`, keeps the original error in `details`, and stays owed to `node.resources.recover()`, which asks the driver for the outcome by `operation_id`. A caller that stops waiting gets `unknown` while the external call keeps running, and a later driver outcome settles that record. A retried operation is asked for its outcome, never executed a second time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyne/lib",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Decentralized agent messaging: threads, durable admission, attention, reply correlation, resources with handover, and an HTTP binding",
   "type": "module",
   "main": "./src/index.ts",

package/src/client.ts

@@ -1,22 +1,30 @@
-import type { Context } from './core.js';
-import { canonical, decimal, fail, key, requireValue, utc } from './core.js';
+import type { Context } from './core.ts';
+import { canonical, decimal, fail, key, page, requireValue, utc } from './core.ts';
 import type {
-  Action, Attention, Auth, DeliveryPlan, DomainMembership, DomainMutation, Entry, ErrorCode, Failure, Json, LocalAttention,
-  InjectOutcome, Member, Message, MessageQuery, MessageRef, MsgInput, Mutation, Outbound, Page, PageOptions, SendRequest,
-  TraceEvent, Thread, ThreadRef, Transaction, Transport, MaintenanceClock, PreparedSend,
-  ResourceReadQuery, ResourceReadResult, ResourceInventory, Resource,
-} from './types.js';
-import type { MessageService } from './messages.js';
-import type { ResourceService } from './resources.js';
-import type { ThreadService } from './threads.js';
-import type { DomainService } from './domains.js';
-import type { TrustService } from './keys.js';
+  Action, Attention, Auth, DeliveryPlan, DomainMembership, DomainMutation, Entry, ErrorCode, Failure, Grant, Json, LocalAttention,
+  InjectOutcome, JoinedThread, Member, Message, MessageQuery, MessageRef, MsgInput, Mutation, NodeId, Outbound, Page, PageOptions, SendRequest,
+  TraceEvent, Thread, ThreadDescription, ThreadRef, Transaction, Transport, MaintenanceClock, PreparedSend,
+  ResourceReadQuery, ResourceReadResult, ResourceInventory, Resource, AttentionSettlement,
+} from './types.ts';
+import type { MessageService } from './messages.ts';
+import type { ResourceService } from './resources.ts';
+import type { ThreadService } from './threads.ts';
+import type { DomainService } from './domains.ts';
+import type { TrustService } from './keys.ts';
 
 /** Result of one delivery: `admission` is what the peer recorded, `wait` is what this caller observed. */
 export interface SendOutcome {
   receipt?: Outbound['receipt'];
   admission: Outbound['state'];
   reply?: Entry;
+  /** The target as the caller spelled it, present only with `resolved` when the two differ. */
+  requested?: string;
+  /**
+   * The node `requested` resolved to. Present whenever the addressee differs from the
+   * endpoint that stores the entry — which is this node whenever it started the
+   * conversation — so an initiator's receipt never reads as a message the node sent itself.
+   */
+  resolved?: NodeId;
   /**
    * Whether the reply body is safe to render. `withheld` means the same body is already
    * confirmed consumed in this context through another path (RFC 0008 §5), so the caller
@@ -32,6 +40,12 @@ export interface SendOptions {
   retry_until?: string;
   idempotency_key?: string;
   expected_author?: string;
+  /**
+   * The caller's own spelling of the addressee. Recorded on the outbound record beside the
+   * resolved node id when the two differ, so the record shows both what was asked and what
+   * was resolved (RFC 0005 §4: the receipt reports the landing, not the request).
+   */
+  requested?: string;
   /**
    * The sender's own consumption identity for the awaited reply (RFC 0008 §5). It stays
    * local and never stands in for the wire plan's receiver-side context.
@@ -74,6 +88,10 @@ const TERMINAL: Record<string, true> = {
   unsupported_delivery: true, ambiguous_target: true, ambiguous_resource: true,
 };
 const MAX_CURSOR_PAGES = 10_000;
+/** A binding check must not hold the maintenance pass behind an unreachable resource owner. */
+const RESOURCE_CHECK_MS = 5_000;
+/** One reconcile failure line per (owner, thread, code) per window; a dead owner stays observable. */
+const RECONCILE_FAILURE_WINDOW_MS = 300_000;
 
 /** Anything that is not a recorded refusal leaves the admission unknown, never "undelivered". */
 function admissionOf(failure: Failure): Outbound['state'] {
@@ -177,6 +195,8 @@ export class OnlyneClient {
   readonly #waiters = new Map<string, Waiter>();
   /** Replies already returned as tool results, per context, held until consumption confirms them. */
   readonly #held = new Map<string, Set<string>>();
+  /** Last `reconcile.failed` line per (owner, thread, code), and what the window suppressed. */
+  readonly #reconcileFailures = new Map<string, { at: number; suppressed: number }>();
 
   constructor(
     ctx: Context, transport: Transport, messages: MessageService, threads: ThreadService,
@@ -303,19 +323,31 @@ export class OnlyneClient {
       },
     };
     if (ref.owner === ctx.options.node_id && to !== ctx.options.node_id) {
-      await this.#ensureMember(ref, to);
+      // The addressee can only ever learn this entry through a signed grant or a signed
+      // reconcile, so a send that names a peer this node never paired with is refused before
+      // anything is stored: it would otherwise read `accepted` while the peer can never see it.
+      if (this.#trust !== undefined && ctx.options.plugins.keys !== undefined) {
+        const pairing = await this.#trust.entry(to);
+        if (pairing === undefined) {
+          fail('not_found', `No trust record names ${to}. Pair the nodes (trust_begin) before addressing them; nothing was stored.`);
+        }
+      }
+      const member = await this.#ensureMember(ref, to);
       // The participant is told about the thread now, not on a later maintenance pass: this
       // exchange is also where the participant's own policy answers, so a peer that revoked
       // this node refuses the conversation at the point the sender can still see it.
       try {
-        await this.#pushGrant(ref, to);
+        await this.#pushGrant(ref, member);
       } catch (error) {
         const failure = failureOf(error);
         return { admission: admissionOf(failure), error: failure };
       }
     }
 
-    return this.#deliver(ref.owner, normalized, plan, options);
+    const outcome = await this.#deliver(ref.owner, normalized, plan, options, to);
+    // The storing endpoint is this node whenever it started the conversation; the outcome
+    // still names the peer it addresses, or the receipt reads as a message sent to oneself.
+    return to !== ref.owner ? { ...outcome, resolved: to } : outcome;
   }
 
   /** The reply-authority route: the receiver owns the landing, so no thread is named here. */
@@ -324,7 +356,7 @@ export class OnlyneClient {
   }
 
   /** Records one outbound request, then transmits it or waits for its answer. */
-  async #deliver(target: string, message: Message, plan: DeliveryPlan, options: SendOptions): Promise<SendOutcome> {
+  async #deliver(target: string, message: Message, plan: DeliveryPlan, options: SendOptions, addressee?: NodeId): Promise<SendOutcome> {
     const ctx = this.#ctx;
     const slot = outboundKey(message.sender, message.id);
     const request: SendRequest = {
@@ -335,6 +367,15 @@ export class OnlyneClient {
       plan,
     };
     const digest = messageDigest(request);
+    // Who the send addresses, beside where the entry is stored: an initiator's own thread
+    // stores locally, so the record must still name the peer, or the receipt reads as a
+    // message the node sent itself.
+    const addressed = {
+      ...(addressee !== undefined && addressee !== target ? { addressee } : {}),
+      ...(typeof options.requested === 'string' && options.requested !== (addressee ?? target)
+        ? { requested: options.requested }
+        : {}),
+    };
     // The same message identity with different content is a conflict, never a rewrite:
     // the slot keeps the first request and the caller sends a new message id instead.
     const record = await ctx.storage.transaction(async tx => {
@@ -354,6 +395,7 @@ export class OnlyneClient {
       const fresh: StoredOutbound = {
         request, expected_author: options.expected_author ?? target, state: 'pending', digest,
         created_at: new Date(ctx.now()).toISOString(),
+        ...addressed,
         ...(options.context === undefined ? {} : { local_context: options.context }),
       };
       await tx.put(slot, fresh);
@@ -469,25 +511,24 @@ export class OnlyneClient {
   }
 
   /**
-   * Grants the addressee `post` and `read` in a thread this node owns, once. The notice the
-   * owner issues here is what teaches the participant the ThreadRef it reconciles against.
+   * Grants the addressee `post` and `read` in a thread this node owns, once, and returns the
+   * member row: the grant notice is keyed by the member revision, so the caller can push that
+   * exact notice instead of scanning the outbox for one it might not recognize.
    */
-  async #ensureMember(ref: ThreadRef, peer: string): Promise<void> {
+  async #ensureMember(ref: ThreadRef, peer: string): Promise<Member> {
     const existing = await this.#ctx.storage.transaction(tx => tx.get<Member>(key('member', ref.owner, ref.id, peer)));
-    if (existing !== undefined) return;
+    if (existing !== undefined) return existing;
     await this.#threads.member(this.#auth(), ref, peer, {}, {
       idempotency_key: this.#ctx.id(), retry_until: this.#window(undefined),
     });
+    return this.#ctx.storage.transaction(async tx => requireValue(await tx.get<Member>(key('member', ref.owner, ref.id, peer))));
   }
 
-  /** Delivers one outstanding notice to its recipient; a refusal here is the send's answer. */
-  async #pushGrant(ref: ThreadRef, peer: string): Promise<void> {
-    const notices = await this.#allPages(cursor =>
-      this.#threads.notices(this.#auth(), { page_size: 100, ...(cursor === undefined ? {} : { cursor }) }));
-    const notice = notices.find(grant =>
-      grant.recipient === peer && grant.thread_ref.owner === ref.owner && grant.thread_ref.id === ref.id);
-    if (notice === undefined) return;
-    await this.#remote(peer, 'POST', '/grants', { grant: notice }, undefined, this.#ctx.options.wait_ms ?? 60_000);
+  /** Delivers the outstanding notice for one member's revision; none outstanding, nothing to push. */
+  async #pushGrant(_ref: ThreadRef, member: Member): Promise<void> {
+    const notice = await this.#ctx.storage.transaction(tx => tx.get<Grant>(key('notice', member.revision)));
+    if (notice === undefined || notice.acked) return;
+    await this.#remote(member.peer, 'POST', '/grants', { grant: notice }, undefined, this.#ctx.options.wait_ms ?? 60_000);
   }
 
   // ---- inbound path -----------------------------------------------------------
@@ -543,6 +584,8 @@ export class OnlyneClient {
    * `owner + thread_ref` pairs recorded when a grant notice was accepted, plus the
    * threads this node hosts, which need no grant. The owner's authenticated attention
    * list is the evidence; the ack goes out only after the entry is durable locally.
+   * An owner this node cannot reach is reported as a trace record, never thrown: one dead
+   * owner must not starve the rest, and a silent skip is the failure nobody can diagnose.
    */
   async reconcile(signal?: AbortSignal): Promise<Page<LocalAttention>> {
     for (const ref of await this.#knownRefs()) {
@@ -551,14 +594,35 @@ export class OnlyneClient {
         await this.#reconcileThread(ref, signal);
       } catch (error) {
         if (ref.owner === this.#ctx.options.node_id) throw error;
-        // One owner this node cannot reach or resolve must not starve the rest; the next
-        // reconciliation pass retries it, and the local inbox still reflects what landed.
+        this.#reportReconcileFailure(ref, error);
         continue;
       }
     }
     return this.#messages.inbox(this.#auth(), {});
   }
 
+  /**
+   * Writes at most one `reconcile.failed` line per (owner, thread, code) per window. A failed
+   * pull drops nothing, so the next pass retries the same ref; deduplicating here keeps a
+   * permanently dead owner from writing the same line every pass while still accounting for
+   * every attempt it folded into the line it did write.
+   */
+  #reportReconcileFailure(ref: ThreadRef, error: unknown): void {
+    const failure = failureOf(error);
+    const slot = key(ref.owner, ref.id, failure.code);
+    const now = this.#ctx.now();
+    const held = this.#reconcileFailures.get(slot);
+    if (held !== undefined && now - held.at < RECONCILE_FAILURE_WINDOW_MS) {
+      held.suppressed += 1;
+      return;
+    }
+    this.#reconcileFailures.set(slot, { at: now, suppressed: 0 });
+    this.#trace({
+      event: 'reconcile.failed', owner: ref.owner, thread: ref.id,
+      code: failure.code, message: failure.message, attempts: (held?.suppressed ?? 0) + 1,
+    });
+  }
+
   /**
    * Delivers outstanding owner grant notices, replays owed todos and entries whose durable
    * record never reached the model, re-drives owed trust statements, then reconciles. Replay
@@ -679,7 +743,9 @@ export class OnlyneClient {
     const action = await this.#decide(input);
     if (action.kind !== 'send') return this.#dispatch(action, options);
     const prepared = this.#prepare(input, action);
-    return this.send(prepared.to, prepared.message, prepared.plan, options);
+    const outcome = await this.send(prepared.to, prepared.message, prepared.plan,
+      { ...options, ...(typeof input.meta?.to === 'string' ? { requested: input.meta.to } : {}) });
+    return this.#addressed(outcome, input.meta?.to, prepared.to);
   }
 
   async prepare(input: MsgInput): Promise<PreparedSend> {
@@ -756,6 +822,16 @@ export class OnlyneClient {
     return { to: action.to, message, plan };
   }
 
+  /**
+   * The caller's own spelling beside the node the decision resolved it to. Equal spellings say
+   * nothing new; a bare alias that resolved to a peer is the case the receipt cannot show. A
+   * `resolved` the send already derived (the addressee of an initiator's own thread) is kept.
+   */
+  #addressed(outcome: SendOutcome, requested: Json | undefined, resolved: NodeId): SendOutcome {
+    const merged: SendOutcome = outcome.resolved === undefined ? { ...outcome, resolved } : outcome;
+    return typeof requested !== 'string' || requested === resolved ? merged : { ...merged, requested };
+  }
+
   // ---- internals ---------------------------------------------------------------
 
   #auth(): Auth {
@@ -853,7 +929,8 @@ export class OnlyneClient {
       const guarantee = (receipt as { guarantee?: unknown }).guarantee;
       this.#trace({
         event: 'outbound.admitted', sender: request.message.sender, message: request.message.id,
-        target: request.target_endpoint, state: 'accepted', ...(typeof guarantee === 'string' ? { guarantee } : {}),
+        target: request.target_endpoint, ...(record.addressee === undefined ? {} : { resolved: record.addressee }),
+        state: 'accepted', ...(typeof guarantee === 'string' ? { guarantee } : {}),
       });
       return { admission: 'accepted', receipt };
     } catch (error) {
@@ -862,7 +939,8 @@ export class OnlyneClient {
       await this.#commit(record, { state: admissionOf(failure), error: failure });
       this.#trace({
         event: 'outbound.admitted', sender: request.message.sender, message: request.message.id,
-        target: request.target_endpoint, state: admissionOf(failure), code: failure.code,
+        target: request.target_endpoint, ...(record.addressee === undefined ? {} : { resolved: record.addressee }),
+        state: admissionOf(failure), code: failure.code,
       });
       const stored = await this.#ctx.storage.transaction(tx => tx.get<StoredOutbound>(outboundKey(request.message.sender, request.message.id)));
       return {
@@ -919,16 +997,21 @@ export class OnlyneClient {
       // A row keeps the context the entry landed in; the confirmation context only fills in
       // for a row that names none.
       let original: string | undefined;
+      let settled = false;
+      let consumable = false;
       for (const row of await tx.scan<LocalAttention>(key('inbox') + '/')) {
         const held = row.value.attention.entry;
         if (held === undefined) continue;
         if (held.thread_ref.owner !== entry.thread_ref.owner || held.thread_ref.id !== entry.thread_ref.id) continue;
         if (held.seq !== entry.seq) continue;
+        if (row.value.settlement !== undefined) { settled = true; continue; }
+        consumable = true;
         original = original ?? row.value.context;
         if (row.value.injected) continue;
         const landed = row.value.context ?? context;
         await tx.put(row.key, { ...row.value, injected: true, ...(landed === undefined ? {} : { context: landed }) });
       }
+      if (settled && !consumable) return undefined;
       const where = context ?? original ?? this.#ctx.options.node_id;
       const slot = consumptionKey(where, entry.thread_ref, entry.seq);
       const stored = await tx.get<ConsumptionRecord>(slot);
@@ -940,6 +1023,10 @@ export class OnlyneClient {
       await this.#oweTodo(tx, entry, where);
       return where;
     });
+    if (consumedIn === undefined) {
+      this.#held.delete(entryKey(entry.thread_ref, entry.seq));
+      return;
+    }
     const identity = entryKey(entry.thread_ref, entry.seq);
     const held = this.#held.get(identity);
     if (held !== undefined) {
@@ -1159,9 +1246,10 @@ export class OnlyneClient {
    * answer with the context it really used, and that is the one the todo follows.
    */
   async #consume(entry: Entry, record: LocalAttention): Promise<void> {
+    if (record.injected) { this.#injectTrace(entry, record, 'skipped', 'injected'); return; }
+    if (await this.#settleResourceAttention(entry, record)) return;
     const runtime = this.#ctx.options.plugins.runtime;
     if (runtime === undefined) { this.#injectTrace(entry, record, 'skipped', 'no-runtime'); return; }
-    if (record.injected) { this.#injectTrace(entry, record, 'skipped', 'injected'); return; }
     const related = entry.message.meta?.in_reply_to;
     const outbound = related?.sender === this.#ctx.options.node_id
       ? await this.#ctx.storage.transaction(tx => tx.get<StoredOutbound>(outboundKey(related.sender, related.id)))
@@ -1187,6 +1275,55 @@ export class OnlyneClient {
     await this.confirmConsumption(entry, injected.context, 'fragment');
   }
 
+  async #settleResourceAttention(entry: Entry, record: LocalAttention): Promise<boolean> {
+    const ref = entry.message.meta?.data?.resource_ref;
+    if (typeof ref !== 'object' || ref === null || Array.isArray(ref)
+      || typeof ref.owner !== 'string' || typeof ref.id !== 'string'
+      || ref.owner !== entry.authenticated_author) return false;
+    const resource_ref = { owner: ref.owner, id: ref.id };
+    let settlement: AttentionSettlement;
+    const at = new Date(this.#ctx.now()).toISOString();
+    try {
+      const resource = await this.readResources(
+        { op: 'describe', resource: resource_ref },
+        { signal: AbortSignal.timeout(RESOURCE_CHECK_MS) },
+      ) as Resource;
+      if (resource.binding.handler === this.#ctx.node) return false;
+      settlement = { via: 'handover', resource_ref, handler: resource.binding.handler, revision: resource.revision, at };
+    } catch (error) {
+      const failure = failureOf(error);
+      if (failure.code !== 'not_found') {
+        const attempts = await this.#ctx.storage.transaction(async tx => {
+          const slot = inboxKey(record.attention.obligation_id);
+          const current = await tx.get<LocalAttention>(slot);
+          if (current === undefined || current.injected) return undefined;
+          const attempts = (current.resource_check_failures ?? 0) + 1;
+          await tx.put(slot, { ...current, resource_check_failures: attempts });
+          return attempts;
+        });
+        if (attempts !== undefined) this.#trace({
+          event: 'inbound.resource-check.failed', thread: entry.thread_ref, seq: entry.seq,
+          resource_ref, code: failure.code, attempts,
+        });
+        throw error;
+      }
+      settlement = { via: 'undeliverable', resource_ref, reason: 'resource-unavailable', at };
+    }
+    const changed = await this.#ctx.storage.transaction(async tx => {
+      const slot = inboxKey(record.attention.obligation_id);
+      const current = await tx.get<LocalAttention>(slot);
+      if (current === undefined || current.injected) return false;
+      await tx.put(slot, { ...current, injected: true, settlement });
+      return true;
+    });
+    if (changed) {
+      this.#held.delete(entryKey(entry.thread_ref, entry.seq));
+      this.#trace({ event: 'inbound.settled', thread: entry.thread_ref, seq: entry.seq, settlement });
+      this.#ctx.options.plugins.runtime?.notify({ event: 'inbound', thread: entry.thread_ref, seq: entry.seq, sender: entry.message.sender });
+    }
+    return true;
+  }
+
   /**
    * Records the todo this consumption owes, inside the commit that confirms the consumption.
    * A host without a todo hook owes none, so no record accrues for it.
@@ -1223,6 +1360,58 @@ export class OnlyneClient {
     return stored?.confirmed === true;
   }
 
+  /**
+   * The threads this node was invited into. The rows come from the records it already holds;
+   * each row is then asked of its owner through the same describe read the thread view uses,
+   * which is where the title, the state and the member table live. An owner that cannot be
+   * reached leaves the row in place with the failure attached: an unreachable peer is a
+   * reported outage, never a reason to hide a thread this node belongs to.
+   */
+  async joinedThreads(options: PageOptions = {}, signal?: AbortSignal): Promise<Page<JoinedThread>> {
+    const listed = await this.#threads.joined(this.#auth(), options);
+    const items: JoinedThread[] = [];
+    for (const row of listed.items) items.push(await this.#ownerFacts(row, signal));
+    return { ...listed, items };
+  }
+
+  async #ownerFacts(row: JoinedThread, signal?: AbortSignal): Promise<JoinedThread> {
+    try {
+      const described = await this.#remote<ThreadDescription>(
+        row.thread_ref.owner, 'GET',
+        `/threads/${encodeURIComponent(row.thread_ref.owner)}/${encodeURIComponent(row.thread_ref.id)}`,
+        undefined, signal, this.#ctx.options.wait_ms ?? 60_000);
+      return { ...row, title: described.thread.title, state: described.thread.state, members: described.members };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      return { ...row, unavailable: failureOf(error) };
+    }
+  }
+
+  /** One thread's record and members: local when this node hosts it, from the owner otherwise. */
+  async describeThread(ref: ThreadRef, signal?: AbortSignal): Promise<ThreadDescription> {
+    if (ref.owner === this.#ctx.options.node_id) return this.#threads.describe(this.#auth(), ref);
+    return this.#remote(
+      ref.owner, 'GET', `/threads/${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`,
+      undefined, signal, this.#ctx.options.wait_ms ?? 60_000);
+  }
+
+  /**
+   * One page of a thread's entries, read locally when this node hosts the thread and from the
+   * owner otherwise. A member of a joined thread has no local copy of the entries, so the
+   * owner's message route is the only source that can answer for them.
+   */
+  async threadEntries(ref: ThreadRef, query: MessageQuery = {}, signal?: AbortSignal): Promise<Page<Entry>> {
+    if (ref.owner === this.#ctx.options.node_id) return this.#messages.list(this.#auth(), ref, query);
+    const search = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+      if (value === undefined) continue;
+      search.set(name, typeof value === 'object' ? JSON.stringify(value) : String(value));
+    }
+    const path = `/threads/${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}/messages`
+      + (search.size === 0 ? '' : `?${search}`);
+    return this.#remote(ref.owner, 'GET', path, undefined, signal, this.#ctx.options.wait_ms ?? 60_000);
+  }
+
   /** Every owner + thread this node knows, from accepted grant notices plus its own threads. */
   async #knownRefs(): Promise<ThreadRef[]> {
     const granted = await this.#ctx.storage.transaction(async tx =>
@@ -1299,6 +1488,8 @@ export class OnlyneClient {
           ? (attention.plan?.context === undefined ? {} : { context: attention.plan.context })
           : { context: previous.context }),
         injected: previous?.injected === true,
+        ...(previous?.settlement === undefined ? {} : { settlement: previous.settlement }),
+        ...(previous?.resource_check_failures === undefined ? {} : { resource_check_failures: previous.resource_check_failures }),
       };
       if (previous !== undefined && canonical(previous.attention) === canonical(merged.attention)) {
         return previous;
@@ -1381,7 +1572,7 @@ export class OnlyneClient {
           if (peers === undefined) fail('unsupported_delivery', 'No neighbor directory is available on this host.');
           return peers();
         }
-        case 'threads': return this.#threads.list(auth);
+        case 'threads': return this.#threadsView(action, options);
         case 'inbox':
           // A thread-scoped inbox is the owner's attention list for that thread, so the
           // owner that admitted the messages is asked, exactly like reconciliation does.
@@ -1404,7 +1595,7 @@ export class OnlyneClient {
           return this.#threads.create(auth, { ...mutation(), title: requireValue(action.title, 'invalid_request') });
         case 'close': return this.#threads.close(auth, requireValue(action.thread, 'invalid_request'), mutation());
         case 'list': return this.#threads.list(auth);
-        case 'describe': return this.#readThreadRef(requireValue(action.thread, 'invalid_request'), options);
+        case 'describe': return this.describeThread(requireValue(action.thread, 'invalid_request'), options.signal);
         case 'member_add':
           return this.#threads.member(auth, requireValue(action.thread, 'invalid_request'), requireValue(action.to, 'invalid_request'), {}, mutation());
         case 'member_remove':
@@ -1440,37 +1631,42 @@ export class OnlyneClient {
    */
   async #readThread(action: Extract<Action, { kind: 'read'; scope: 'directory' | 'neighbors' | 'threads' | 'inbox' | 'messages' | 'message' | 'evidence' }>, options: MsgOptions): Promise<unknown> {
     const ref = requireValue(action.thread, 'invalid_request');
-    if (ref.owner === this.#ctx.options.node_id) {
-      return this.#messages.list(this.#auth(), ref, {
-        attention: action.attention ?? 'thread',
-        ...(action.cursor === undefined ? {} : { cursor: action.cursor }),
-        ...(action.page_size === undefined ? {} : { page_size: action.page_size }),
-        ...(action.seq === undefined ? {} : { since_seq: action.seq }),
-        ...(action.message === undefined ? {} : { related_to: action.message }),
-      });
-    }
     const query: MessageQuery = {
+      attention: action.attention ?? 'thread',
       ...(action.cursor === undefined ? {} : { cursor: action.cursor }),
       ...(action.page_size === undefined ? {} : { page_size: action.page_size }),
       ...(action.seq === undefined ? {} : { since_seq: action.seq }),
       ...(action.message === undefined ? {} : { related_to: action.message }),
-      attention: action.attention ?? 'thread',
     };
-    const search = new URLSearchParams();
-    for (const [name, value] of Object.entries(query)) {
-      if (value === undefined) continue;
-      search.set(name, typeof value === 'object' ? JSON.stringify(value) : String(value));
-    }
-    const path = `/threads/${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}/messages`
-      + (search.size === 0 ? '' : `?${search}`);
-    return this.#remote(ref.owner, 'GET', path, undefined, options.signal, this.#ctx.options.wait_ms ?? 60_000);
+    return this.threadEntries(ref, query, options.signal);
   }
 
-  async #readThreadRef(ref: ThreadRef, options: MsgOptions): Promise<unknown> {
-    if (ref.owner === this.#ctx.options.node_id) return this.#threads.describe(this.#auth(), ref);
-    return this.#remote(
-      ref.owner, 'GET', `/threads/${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`,
-      undefined, options.signal, this.#ctx.options.wait_ms ?? 60_000);
+  /**
+   * The threads this node can see in one page: the ones it owns, plus the ones it was invited
+   * into. A joined row carries `read_only: true`; its owner's title, state and member table
+   * come from the describe read, and an unreachable owner leaves the failure on the row
+   * instead of dropping the thread from the list.
+   */
+  async #threadsView(action: PageOptions, options: MsgOptions): Promise<Page<Thread | JoinedThread>> {
+    const [owned, joined] = await Promise.all([
+      this.#allPages(cursor => this.#threads.list(this.#auth(), { page_size: 100, ...(cursor === undefined ? {} : { cursor }) })),
+      this.#allPages(cursor => this.joinedThreads({ page_size: 100, ...(cursor === undefined ? {} : { cursor }) }, options.signal)),
+    ]);
+    const position = (row: Thread | JoinedThread): string => key(row.thread_ref.owner, row.thread_ref.id);
+    const rows = [...owned, ...joined].sort((left, right) => {
+      const a = position(left);
+      const b = position(right);
+      return a < b ? -1 : a > b ? 1 : 0;
+    });
+    return page(
+      rows,
+      {
+        ...(action.cursor === undefined ? {} : { cursor: action.cursor }),
+        ...(action.page_size === undefined ? {} : { page_size: action.page_size }),
+      },
+      { kind: 'threads', actor: this.#ctx.options.node_id },
+      position,
+    );
   }
 
   /**

package/src/core.ts

@@ -1,5 +1,5 @@
-import type { AdmissionContext, Auth, ErrorCode, Failure, Mutation, NodeId, NodeOptions, Page, PageOptions, Storage, Transaction, TrustEntry } from './types.js';
-import { trustPhase } from './types.js';
+import type { AdmissionContext, Auth, ErrorCode, Failure, Mutation, NodeId, NodeOptions, Page, PageOptions, Storage, Transaction, TrustEntry } from './types.ts';
+import { trustPhase } from './types.ts';
 
 const statuses: Record<ErrorCode, number> = {
   invalid_request: 400, unauthenticated: 401, forbidden: 403, not_a_member: 403,