@serfab/cadre-core 0.7.1 → 0.9.0

package/src/strand-solicitation.ts

@@ -13,6 +13,10 @@ import {
   StrandFormationManager,
   type StrandFormationManagerConfig
 } from './strand-formation-manager.js';
+import {
+  isValidResponderCreatesResult,
+  type FormationResultMessage
+} from './strand-formation-protocol.js';
 
 const log = debug('sereus:cadre:solicitation');
 
@@ -29,6 +33,26 @@ export interface DisclosureValidator {
   validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean>;
 }
 
+/**
+ * Discriminated result of resolving the host strand an invite binds to (responder side):
+ *
+ * - `unbound`: the invite carries no `StrandId` → the responder-provisions path (provision
+ *   a NEW strand; legacy/open).
+ * - `bound`: the invite names a host strand AND that strand row is present on this responder
+ *   → provision-then-record (record consent against it, return it + its membership key).
+ * - `missing`: the invite names a host strand but the row is ABSENT on this responder (e.g.
+ *   not yet converged) → the manager rejects cleanly rather than recording usage against a
+ *   non-existent strand, which would fail the deferred `FormationUsage.StrandExists` CHECK at
+ *   commit and drop the result frame.
+ *
+ * Replaces the older `{ strandId, memberPrivateKey } | null` shape, which conflated `bound`
+ * and `missing` (both produced a non-null result whenever the invite had a `StrandId`).
+ */
+export type ResolvedHostStrand =
+  | { kind: 'unbound' }
+  | { kind: 'bound'; strandId: string; memberPrivateKey: string | null }
+  | { kind: 'missing'; strandId: string };
+
 /**
  * Interface for recording formation usage
  */
@@ -47,6 +71,29 @@ export interface FormationUsageRecorder {
    * Check if a token is valid and not expired
    */
   isTokenValid(token: string): Promise<{ valid: boolean; invitation?: OpenInvitation }>;
+
+  /**
+   * Resolve the host strand an invite binds to, classifying it as unbound / bound /
+   * missing (see {@link ResolvedHostStrand}). Optional: a recorder that does not bind
+   * strands omits it, and {@link StrandFormationManager} treats every invite as `unbound`
+   * and falls back to its provisioner. Keeping resolution behind this interface keeps the
+   * manager DB-agnostic and unit-testable with an in-memory fake.
+   */
+  resolveStrand?(token: string): Promise<ResolvedHostStrand>;
+
+  /**
+   * Provision a NEW strand for an UNBOUND invite and record consent against it
+   * ATOMICALLY (single `FormationUsage` row → single-use enforced on the next redemption).
+   * Optional: a recorder that only supports provision-then-record omits it, and the
+   * manager falls back to its {@link StrandProvisioner}. Mirrors the create-strand-by-consent
+   * path the schema's `Strand.Authorized` `FormationUsage` branch authorizes. Returns the
+   * minted strand id plus its membership key (null for an open responder-provisioned strand).
+   */
+  provisionAndRecord?(
+    token: string,
+    initiatorKey: string,
+    sAppId: string
+  ): Promise<{ strandId: string; memberPrivateKey: string | null }>;
 }
 
 /**
@@ -76,11 +123,47 @@ export interface FormationSigner {
   }>;
 }
 
+/**
+ * Interface for validating the responder's formation result on the initiator side.
+ *
+ * Symmetric to {@link DisclosureValidator} (which runs responder→initiator): it lets
+ * the initiator verify the responder's disclosed identity, cadre, and provisioned
+ * strand against the invitation/disclosure it used to form the strand. The manager
+ * owns one dialer session per `formStrand` call, so the per-session invitation +
+ * disclosure context is local — no hook-signature gymnastics needed.
+ */
+export interface FormationResponseValidator {
+  /** Validate the responder's result against the invitation/disclosure used to form the strand. */
+  validateResponse(ctx: {
+    invitation: OpenInvitation;
+    disclosure: StrandFormationDisclosure;
+    response: FormationResultMessage;
+  }): Promise<boolean>;
+}
+
+/**
+ * Built-in structural {@link FormationResponseValidator}.
+ *
+ * `validateResponse` rejects when the responder did not approve, omitted a disclosed
+ * identity, returned no/placeholder cadre addresses, or returned a missing/empty or
+ * non-responder-created strand (see {@link isValidResponderCreatesResult}).
+ * Apps can supply a stricter validator via {@link StrandSolicitationServiceOptions}.
+ */
+export function createDefaultFormationResponseValidator(): FormationResponseValidator {
+  return {
+    async validateResponse({ response }) {
+      return isValidResponderCreatesResult(response);
+    }
+  };
+}
+
 export interface StrandSolicitationServiceOptions {
   disclosureValidator?: DisclosureValidator;
   formationUsageRecorder?: FormationUsageRecorder;
   strandProvisioner?: StrandProvisioner;
   formationSigner?: FormationSigner;
+  /** Validates the responder's result on the initiator side (defaults to a structural check) */
+  formationResponseValidator?: FormationResponseValidator;
   /** Party ID for this node (used in protocol messages) */
   partyId?: string;
   /** Cadre peer addresses for this node */
@@ -96,14 +179,15 @@ export interface StrandSolicitationServiceOptions {
  * - formStrand(invitation, disclosure, node) - called by initiator
  * - validateStrandFormation(token, disclosure) - called by responder
  *
- * When a libp2p node is provided, the underlying protocol is handled by
- * strand-proto's SessionManager via StrandFormationManager.
+ * When a libp2p node is provided, the underlying protocol is handled by the
+ * native cadre-core formation transport via StrandFormationManager.
  */
 export class StrandSolicitationService {
   private readonly disclosureValidator?: DisclosureValidator;
   private readonly formationUsageRecorder?: FormationUsageRecorder;
   private readonly strandProvisioner?: StrandProvisioner;
   private readonly formationSigner?: FormationSigner;
+  private readonly formationResponseValidator?: FormationResponseValidator;
   private readonly partyId: string;
   private readonly cadrePeerAddrs: string[];
   private formationManager?: StrandFormationManager;
@@ -114,6 +198,7 @@ export class StrandSolicitationService {
     this.formationUsageRecorder = options?.formationUsageRecorder;
     this.strandProvisioner = options?.strandProvisioner;
     this.formationSigner = options?.formationSigner;
+    this.formationResponseValidator = options?.formationResponseValidator;
     this.partyId = options?.partyId ?? `party-${Date.now()}`;
     this.cadrePeerAddrs = options?.cadrePeerAddrs ?? [];
     this.formationConfig = options?.formationConfig;
@@ -130,6 +215,7 @@ export class StrandSolicitationService {
         disclosureValidator: this.disclosureValidator,
         formationUsageRecorder: this.formationUsageRecorder,
         strandProvisioner: this.strandProvisioner,
+        formationResponseValidator: this.formationResponseValidator,
         partyId: this.partyId,
         cadrePeerAddrs: this.cadrePeerAddrs,
         config: this.formationConfig
@@ -188,7 +274,7 @@ export class StrandSolicitationService {
 
     // If we have a full invitation and a node, use the real protocol
     if (typeof invitation !== 'string' && node) {
-      log('Using strand-proto for real protocol handling');
+      log('Using native cadre-core formation transport');
       const result = await this.getFormationManager().formStrand(
         invitation,
         { ...disclosure, partyId: memberKey },
@@ -197,7 +283,10 @@ export class StrandSolicitationService {
       return {
         memberKey,
         invitePrivateKey,
-        strandId: result.strandId
+        strandId: result.strandId,
+        // Carry the host strand's membership key delivered over the protocol (closed-strand
+        // provision-then-record). invitePrivateKey stays the initiator's generated signing key.
+        memberPrivateKey: result.memberPrivateKey
       };
     }
 

package/src/strand-wake-payload.ts

@@ -0,0 +1,32 @@
+/**
+ * strand-wake-payload.ts — the canonical wire contract for a strand-wake data
+ * message, shared by the server-side sender (`PushNotifier`, this package) and
+ * the mobile receiver (`@serfab/reference-app-rn`'s `push-wake.ts`).
+ *
+ * A strand-wake is a data-only push delivered to an OS-suspended phone over its
+ * platform channel (FCM/APNs) when a control-network dial cannot reach the
+ * hibernating process. It names the strand that has pending activity so the phone
+ * can run one `serviceWake` cycle and re-hibernate.
+ *
+ * This module is intentionally dependency-free (no node/RN/browser-specific
+ * imports) so it sits cleanly on the cross-platform `cadre-core` entry and can be
+ * re-exported by the RN receive module without dragging any platform code across
+ * the send/receive boundary. The defensive `parseStrandWakePayload` parser stays
+ * on the receive side (it guards untrusted wire input); the sender constructs
+ * payloads from typed fields and never parses.
+ */
+
+/** Discriminator value carried by a strand-wake data message. */
+export const STRAND_WAKE_TYPE = 'strand-wake';
+
+/**
+ * A data-only push payload telling a suspended phone that `strandId` has pending
+ * activity. Delivered addressed to the phone's resolved `DeviceToken`.
+ */
+export interface StrandWakePayload {
+  type: typeof STRAND_WAKE_TYPE;
+  /** The strand the wake is for. */
+  strandId: string;
+  /** Why the wake was sent (e.g. `'activity'`). Free-form, for diagnostics. */
+  reason: string;
+}

package/src/strand-wake-protocol.ts

@@ -0,0 +1,331 @@
+/**
+ * Control-network push-wake transport.
+ *
+ * Lets a same-cadre peer — typically an always-on server that participates in a
+ * strand and sees new activity — signal a hibernating cadre peer to bring that
+ * strand online, pull pending activity, and re-hibernate. Push-wake travels the
+ * **control network** (the per-party network connecting this party's own cadre
+ * nodes), which is the only network a hibernating peer keeps connected.
+ *
+ * Modeled directly on `seed-bootstrap.ts`: a dedicated libp2p protocol id,
+ * 4-byte big-endian length-prefixed JSON frames, `node.handle` for the receiver,
+ * `node.dialProtocol` for the sender, and the shared `ControlStream` primitives
+ * from `control-stream.ts`. The exchange is a single request → single ack on one
+ * stream (like seed delivery), so each side reads to EOF (under a read timeout)
+ * and decodes one frame via the shared {@link decodeLengthPrefixedFrame} guard.
+ *
+ * **Authorization (v1):** the control network already restricts membership —
+ * only this party's cadre peers connect (schema-gated `CadrePeer`). A wake is
+ * low-risk: it only causes the receiver to spend resources coming online for a
+ * strand it already participates in. So the receiver verifies the remote peer is
+ * a `CadrePeer` member (via the injected `isMember` gate) and requires no
+ * signature beyond control-network membership. A richer per-request signature is
+ * deliberately out of scope for v1.
+ */
+
+import debug from 'debug';
+import type { Libp2p, Connection } from '@libp2p/interface';
+import type { Multiaddr } from '@multiformats/multiaddr';
+import type { StrandInstance, WakeRequest, WakeAck } from './types.js';
+import { decodeLengthPrefixedFrame } from './seed-bootstrap.js';
+import { type ControlStream, writeFrame, withTimeout, readStreamToEnd } from './control-stream.js';
+
+const log = debug('sereus:cadre:strand-wake');
+
+/** Protocol id for control-network push-wake (parallel to `/sereus/seed/1.0.0`). */
+export const WAKE_PROTOCOL = '/sereus/strand-wake/1.0.0';
+
+/**
+ * Maximum wake frame size. Wake messages are tiny (a strand id + short reason),
+ * so this is a defensive cap — far below the 1MB seed ceiling — that bounds the
+ * bytes a peer can make the receiver buffer per stream.
+ */
+const MAX_WAKE_SIZE = 64 * 1024;
+
+/** Default time to wait for the ack before abandoning a wake dial (ms). */
+const DEFAULT_WAKE_TIMEOUT_MS = 10_000;
+
+/** Default time the receiver waits for an inbound wake frame before aborting (ms). */
+const DEFAULT_WAKE_READ_TIMEOUT_MS = 10_000;
+
+/** Default cap on concurrent inbound wake streams a single peer can pin open. */
+const DEFAULT_MAX_CONCURRENT_WAKES = 100;
+
+/**
+ * Read a libp2p stream to EOF and decode the single length-prefixed JSON frame
+ * it carries. Bounded by `timeoutMs` (a never-half-closing peer is aborted, not
+ * awaited forever) and capped at {@link MAX_WAKE_SIZE}, reusing the shared
+ * {@link decodeLengthPrefixedFrame} guard for the prefix/length checks.
+ */
+async function readFrame<T>(stream: ControlStream, timeoutMs: number): Promise<T> {
+  const data = await readStreamToEnd(stream, { maxBytes: MAX_WAKE_SIZE, timeoutMs, label: 'Wake' });
+  const body = decodeLengthPrefixedFrame(data, MAX_WAKE_SIZE);
+  return JSON.parse(new TextDecoder().decode(body)) as T;
+}
+
+/**
+ * Dependencies the {@link StrandWakeService} receiver needs from its host
+ * (`CadreNode`), injected so the service is testable without a full node.
+ */
+export interface StrandWakeServiceOptions {
+  /** Membership gate: is the remote peer a `CadrePeer` member of this cadre? */
+  isMember(remotePeerId: string): Promise<boolean>;
+  /** Look up a local strand instance by id (undefined if not participated in). */
+  getStrand(strandId: string): StrandInstance | undefined;
+  /**
+   * Trigger the local wake path for a hibernating/idle strand. Wired to
+   * `CadreNode.wakeStrand` (→ `HibernationManager` → `resumeStrand`), whose
+   * resume coalescing prevents a push-wake racing a concurrent check-in.
+   */
+  wake(strandId: string): Promise<void>;
+  /**
+   * Time to wait for the inbound wake frame before aborting the read (ms).
+   * Defaults to {@link DEFAULT_WAKE_READ_TIMEOUT_MS}. Bounds a buggy/compromised
+   * own-cadre node that opens a stream and never half-closes its write end.
+   */
+  readTimeoutMs?: number;
+  /**
+   * Cap on concurrent inbound wake streams (defaults to
+   * {@link DEFAULT_MAX_CONCURRENT_WAKES}). Over the cap, a non-accepting ack is
+   * returned without invoking the wake path.
+   */
+  maxConcurrent?: number;
+}
+
+/**
+ * Receiver side of the push-wake protocol. Registers a `WAKE_PROTOCOL` handler
+ * on the control node and, for each inbound {@link WakeRequest}, gates on cadre
+ * membership, then resumes the named strand if it is hibernating/idle and we
+ * participate in it — replying with a {@link WakeAck}.
+ */
+export class StrandWakeService {
+  private readonly options: StrandWakeServiceOptions;
+  private readonly readTimeoutMs: number;
+  private readonly maxConcurrent: number;
+  private node: Libp2p | null = null;
+  /** In-flight inbound wake streams, used to enforce {@link maxConcurrent}. */
+  private activeStreams = 0;
+
+  constructor(options: StrandWakeServiceOptions) {
+    this.options = options;
+    this.readTimeoutMs = options.readTimeoutMs ?? DEFAULT_WAKE_READ_TIMEOUT_MS;
+    this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT_WAKES;
+  }
+
+  /** Number of in-flight inbound wake streams. */
+  get activeCount(): number {
+    return this.activeStreams;
+  }
+
+  /** Register the wake protocol handler on the control node. */
+  initialize(node: Libp2p): void {
+    this.node = node;
+    // `runOnLimitedConnection: true` is REQUIRED for the relay path: a NAT'd
+    // receiver is reached over a circuit-relay connection, which libp2p marks
+    // "limited" (the relay caps its data/duration). Without this the receiver
+    // would refuse the inbound wake stream on exactly the connection the
+    // protocol is designed to use (see the relay note on `dialWake`).
+    void node.handle(WAKE_PROTOCOL, async (rawStream: unknown, rawConnection: unknown) => {
+      const remotePeerId = (rawConnection as Connection).remotePeer.toString();
+      await this.handleStream(rawStream as ControlStream, remotePeerId);
+    }, { runOnLimitedConnection: true });
+    log('StrandWakeService registered handler: %s', WAKE_PROTOCOL);
+  }
+
+  /** Unregister the handler and release the node reference. */
+  async shutdown(): Promise<void> {
+    if (this.node) {
+      await this.node.unhandle(WAKE_PROTOCOL);
+      this.node = null;
+      log('StrandWakeService shutdown');
+    }
+  }
+
+  /**
+   * Read the inbound request, decide + execute the wake, and write the ack.
+   *
+   * Three hardening layers, all reported as a non-accepting ack rather than a
+   * dropped/hung stream: a concurrency cap (over {@link maxConcurrent}, reply
+   * without touching the wake path), a read timeout (a peer that never
+   * half-closes is aborted inside {@link readFrame}/`readStreamToEnd`), and the
+   * existing malformed/oversized-frame guard.
+   */
+  private async handleStream(stream: ControlStream, remotePeerId: string): Promise<void> {
+    log('Incoming wake request from: %s', remotePeerId);
+
+    if (this.activeStreams >= this.maxConcurrent) {
+      log('Rejecting wake from %s: %d concurrent streams at cap %d', remotePeerId, this.activeStreams, this.maxConcurrent);
+      const ack: WakeAck = { accepted: false, reason: 'Too many concurrent wake requests' };
+      try {
+        writeFrame(stream, ack);
+      } catch {
+        // Ignore send errors on the reject path.
+      }
+      try {
+        await stream.close();
+      } catch {
+        // Ignore close errors.
+      }
+      return;
+    }
+
+    this.activeStreams++;
+    try {
+      const request = await readFrame<WakeRequest>(stream, this.readTimeoutMs);
+      const ack = await this.processWakeRequest(request, remotePeerId);
+      writeFrame(stream, ack);
+    } catch (err) {
+      log('Error handling wake request from %s: %o', remotePeerId, err);
+      const ack: WakeAck = {
+        accepted: false,
+        reason: err instanceof Error ? err.message : 'Unknown error',
+      };
+      try {
+        writeFrame(stream, ack);
+      } catch {
+        // Ignore send errors on the error path.
+      }
+    } finally {
+      this.activeStreams--;
+      try {
+        await stream.close();
+      } catch {
+        // Ignore close errors.
+      }
+    }
+  }
+
+  /**
+   * Decide and execute the wake for a decoded request. Exposed (not private) so
+   * the decision matrix can be unit-tested directly.
+   *
+   * - Non-member sender → rejected (`accepted: false`).
+   * - Unknown / not-participated strand → rejected.
+   * - Hibernating or idle strand → resumed via the wake path, then `accepted`.
+   * - Already-live strand → no-op, `accepted` with current status.
+   */
+  async processWakeRequest(request: WakeRequest, remotePeerId: string): Promise<WakeAck> {
+    // Control-network membership is the v1 authorization: only this party's
+    // cadre peers may ask us to wake.
+    if (!(await this.options.isMember(remotePeerId))) {
+      log('Rejecting wake from non-member %s', remotePeerId);
+      return { accepted: false, reason: 'Sender is not a cadre member' };
+    }
+
+    const instance = this.options.getStrand(request.strandId);
+    if (!instance) {
+      log('Rejecting wake for unknown/unparticipated strand %s', request.strandId);
+      return { accepted: false, reason: 'Strand not found or not participated in' };
+    }
+
+    if (instance.status === 'hibernating' || instance.status === 'idle') {
+      log('Waking strand %s on push from %s (reason=%s)', request.strandId, remotePeerId, request.reason ?? 'unspecified');
+      await this.options.wake(request.strandId);
+    } else {
+      log('Strand %s already %s; push-wake is a no-op', request.strandId, instance.status);
+    }
+
+    // The wake path mutates the shared instance, so re-read its current status.
+    return { accepted: true, status: instance.status };
+  }
+}
+
+/** Options for {@link dialWake}. */
+export interface DialWakeOptions {
+  /** Per-dial timeout in ms (default {@link DEFAULT_WAKE_TIMEOUT_MS}). */
+  timeoutMs?: number;
+  /** Override the protocol id (defaults to {@link WAKE_PROTOCOL}). */
+  protocolId?: string;
+}
+
+/**
+ * Sender side: dial a target's control-network address(es), send a
+ * {@link WakeRequest} over `WAKE_PROTOCOL`, and return the peer's {@link WakeAck}.
+ *
+ * Tries each candidate address in order (signaling/relay first, as produced by
+ * `CadreNode.resolvePeerAddrs`) until one dials, so a NAT'd peer is reachable via
+ * its circuit-relay address. Throws if no address is dialable.
+ */
+export async function dialWake(
+  node: Libp2p,
+  addrs: Multiaddr[],
+  request: WakeRequest,
+  options: DialWakeOptions = {}
+): Promise<WakeAck> {
+  if (addrs.length === 0) {
+    throw new Error('No dialable address for wake target');
+  }
+  const protocolId = options.protocolId ?? WAKE_PROTOCOL;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_WAKE_TIMEOUT_MS;
+
+  let lastError: Error | null = null;
+  for (const addr of addrs) {
+    // One controller per attempt: on timeout, `withTimeout`'s `onTimeout` aborts
+    // it, which aborts the in-flight dialProtocol (via the dial `signal`) and the
+    // live stream — so neither the connect nor the unbounded ack-read leaks.
+    const controller = new AbortController();
+    try {
+      return await withTimeout(
+        timeoutMs,
+        `Wake dial ${addr.toString()}`,
+        () => sendWake(node, addr, protocolId, request, timeoutMs, controller.signal),
+        () => controller.abort(),
+      );
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      log('Wake dial to %s failed: %o', addr.toString(), err);
+    }
+  }
+  throw lastError ?? new Error('Wake dial failed');
+}
+
+/**
+ * Open one stream, send the request, half-close, and read the ack.
+ *
+ * `signal` is the per-attempt abort signal from {@link dialWake}: it is passed to
+ * `dialProtocol` so a timeout during connect aborts the dial, and once the stream
+ * is open an abort listener resets the live stream — releasing the otherwise
+ * unbounded ack-read. `readFrame` still applies `timeoutMs` as a backstop for the
+ * case where an abort does not propagate (e.g. a stream double whose `abort()` is
+ * a no-op).
+ */
+async function sendWake(
+  node: Libp2p,
+  addr: Multiaddr,
+  protocolId: string,
+  request: WakeRequest,
+  timeoutMs: number,
+  signal: AbortSignal,
+): Promise<WakeAck> {
+  // `runOnLimitedConnection: true`: the target may be reachable only over a
+  // circuit-relay connection (the signaling-first addr), which libp2p marks
+  // "limited". The wake exchange is a single tiny request→ack well within the
+  // relay's data/duration cap, so opening it on the limited connection is safe
+  // and is the whole point of dialing the relay address.
+  const rawStream = await node.dialProtocol(addr, protocolId, { runOnLimitedConnection: true, signal });
+  const stream = rawStream as unknown as ControlStream;
+
+  const abortErr = new Error('Wake dial aborted by timeout');
+  const onAbort = (): void => stream.abort(abortErr);
+  // If the timeout already fired during connect, release the freshly-opened stream now.
+  if (signal.aborted) {
+    onAbort();
+    throw abortErr;
+  }
+  signal.addEventListener('abort', onAbort, { once: true });
+
+  try {
+    writeFrame(stream, request);
+    // close() half-closes the write end (EOF) while the read end stays open for
+    // the ack — the same libp2p 3.x pattern as seed delivery.
+    await stream.close();
+    const ack = await readFrame<WakeAck>(stream, timeoutMs);
+    log('Wake ack from %s: accepted=%s status=%s', addr.toString(), ack.accepted, ack.status ?? '-');
+    return ack;
+  } catch (err) {
+    stream.abort(err instanceof Error ? err : new Error(String(err)));
+    throw err;
+  } finally {
+    signal.removeEventListener('abort', onAbort);
+  }
+}

package/src/strand-watcher.ts

@@ -3,6 +3,14 @@ import type { StrandFilter, StrandRow } from './types.js';
 
 const log = debug('sereus:cadre:strand-watcher');
 
+/**
+ * Outcome of evaluating a strand against the current filter.
+ * - `pass`: admit (final)
+ * - `reject`: exclude
+ * - `defer`: admit provisionally; sAppId not yet known, re-evaluate next poll
+ */
+type FilterDecision = 'pass' | 'reject' | 'defer';
+
 /**
  * Extended strand row that includes the sAppId for filtering purposes.
  * The sAppId is provided by the hosting application, not from the control network.
@@ -49,6 +57,8 @@ export class StrandWatcher {
   private readonly sAppIdLookup?: SAppIdLookup;
 
   private knownStrands: Map<string, StrandRow> = new Map();
+  /** Ids admitted under a `defer` decision; re-evaluated each poll until they resolve. */
+  private provisional: Set<string> = new Set();
   private pollTimer: ReturnType<typeof setInterval> | null = null;
   private initialPollTimer: ReturnType<typeof setTimeout> | null = null;
   private running = false;
@@ -69,32 +79,36 @@ export class StrandWatcher {
   }
 
   /**
-   * Check if a strand passes the current filter
+   * Evaluate a strand against the current filter, distinguishing a not-yet-known
+   * sAppId (`defer`) from a known non-match (`reject`). A `defer` admission is
+   * provisional and re-checked on subsequent polls.
    */
-  private passesFilter(strand: StrandRow): boolean {
+  private evaluateFilter(strand: StrandRow): FilterDecision {
     switch (this.filter.mode) {
       case 'all':
-        return true;
+        return 'pass';
       case 'none':
-        return false;
+        return 'reject';
       case 'strandId':
-        return strand.Id === this.filter.strandId;
+        return strand.Id === this.filter.strandId ? 'pass' : 'reject';
       case 'sAppId': {
-        // Look up the sAppId for this strand
-        const sAppId = this.sAppIdLookup?.getSAppId(strand.Id);
+        if (!this.sAppIdLookup) {
+          // No way to ever decide - admit permanently (no lookup configured).
+          return 'pass';
+        }
+        const sAppId = this.sAppIdLookup.getSAppId(strand.Id);
         if (sAppId === undefined) {
-          // If no sAppId lookup configured or unknown strand, pass through
-          // The strand will need to be re-evaluated when sApp info is available
+          // sAppId not yet known - admit provisionally and re-evaluate next poll.
           log('sAppId unknown for strand %s - deferring filter decision', strand.Id);
-          return true;
+          return 'defer';
         }
         const matches = sAppId === this.filter.sAppId;
         log('sAppId filter: strand %s has sAppId %s, filter wants %s, match=%s',
             strand.Id, sAppId, this.filter.sAppId, matches);
-        return matches;
+        return matches ? 'pass' : 'reject';
       }
       default:
-        return true;
+        return 'pass';
     }
   }
 
@@ -110,15 +124,43 @@ export class StrandWatcher {
 
       // Find added strands
       for (const strand of currentStrands) {
-        if (!this.knownStrands.has(strand.Id) && this.passesFilter(strand)) {
-          log('Strand added: %s', strand.Id);
-          this.knownStrands.set(strand.Id, strand);
+        if (this.knownStrands.has(strand.Id)) continue;
+        const decision = this.evaluateFilter(strand);
+        if (decision === 'reject') continue;
+        log('Strand added: %s', strand.Id);
+        this.knownStrands.set(strand.Id, strand);
+        if (decision === 'defer') {
+          // Provisional admission: sAppId unknown, re-check on later polls.
+          this.provisional.add(strand.Id);
+        }
+        try {
+          await this.callbacks.onStrandAdded(strand);
+        } catch (error) {
+          log('Error handling strand add for %s: %o', strand.Id, error);
+        }
+      }
+
+      // Re-evaluate provisional admissions whose sAppId may now be resolvable.
+      // Snapshot ids so we can mutate provisional/knownStrands inside the loop.
+      for (const strandId of [...this.provisional]) {
+        const strand = currentMap.get(strandId);
+        if (!strand) continue; // handled by the removed-strand loop below
+        const decision = this.evaluateFilter(strand);
+        if (decision === 'pass') {
+          // Resolved to a match - admission is now final.
+          this.provisional.delete(strandId);
+        } else if (decision === 'reject') {
+          // Resolved to a non-match - stop the provisionally-admitted strand.
+          log('Provisional strand rejected on re-evaluation: %s', strandId);
+          this.knownStrands.delete(strandId);
+          this.provisional.delete(strandId);
           try {
-            await this.callbacks.onStrandAdded(strand);
+            await this.callbacks.onStrandRemoved(strandId);
           } catch (error) {
-            log('Error handling strand add for %s: %o', strand.Id, error);
+            log('Error handling strand remove for %s: %o', strandId, error);
           }
         }
+        // decision === 'defer': still unknown, leave provisional for next poll.
       }
 
       // Find removed strands
@@ -126,6 +168,7 @@ export class StrandWatcher {
         if (!currentMap.has(strandId)) {
           log('Strand removed: %s', strandId);
           this.knownStrands.delete(strandId);
+          this.provisional.delete(strandId);
           try {
             await this.callbacks.onStrandRemoved(strandId);
           } catch (error) {
@@ -187,6 +230,7 @@ export class StrandWatcher {
     }
 
     this.knownStrands.clear();
+    this.provisional.clear();
     log('StrandWatcher stopped');
   }