@powerhousedao/reactor-attachments 6.2.3-dev.5 → 6.2.3-dev.51

package/dist/replication.d.ts

@@ -0,0 +1,955 @@
+import { O as TransportFetchResult, _ as AttachmentResponse, a as IAttachmentTransport, g as AttachmentMetadata, h as AttachmentHeader, i as IAttachmentStore } from "./interfaces-jHW9JXv1.js";
+import { a as IAttachmentReferenceScanner, c as IAttachmentSchemaCompiler, i as IAttachmentReferenceReader, n as AttachmentReferencePageResult, r as AttachmentReferenceRow } from "./types-AagIcjTD.js";
+import { AttachmentHash, AttachmentRef, IDocumentModelRegistry, IEventBus, IReactorClient, ISyncManager, JwtHandler, LocalChannelPort } from "@powerhousedao/reactor";
+import { AuthSubject, OperationWithContext } from "@powerhousedao/shared/document-model";
+//#region src/access/attachment-read-gate.d.ts
+/** The reactor's read gate, as an attachment read consults it. */
+type AttachmentReadGate = Pick<IReactorClient, "isServed" | "get">;
+/** Scopes a subject may read, by document id; `SyncScopeGate` satisfies it. */
+interface IDocumentScopeGate {
+  scopePredicateById(documentId: string, subject: {
+    address?: string;
+    key?: string;
+  }, branch: string, signal?: AbortSignal): Promise<(scope: string) => boolean>;
+}
+/** The scope an attachment's bytes belong to: the document's own domain state. */
+export declare const ATTACHMENT_READ_SCOPE = "global";
+/** The branch an attachment reference is resolved against. */
+export declare const ATTACHMENT_READ_BRANCH = "main";
+/** Whether `value` is a canonical v1 hash: 64 lowercase SHA-256 hex chars. */
+export declare function isAttachmentHash(value: unknown): value is AttachmentHash;
+/** Rethrows a failure: a read side that is down must not read as a denial. */
+export declare function scopeGateAllowsAttachmentRead(scopeGate: IDocumentScopeGate, documentId: string, subject: AuthSubject): Promise<boolean>;
+/** Served to the subject, references `ref`, and a referencing scope is readable. */
+export declare function readGateAllowsAttachmentRead(readGate: AttachmentReadGate, references: Pick<IAttachmentReferenceReader, "referencingScopes">, documentId: string, ref: AttachmentRef, subject: AuthSubject): Promise<boolean>;
+//#endregion
+//#region src/local/local-attachment-server.d.ts
+/** The peer a server answers: which reactor, over which channel. */
+type AttachmentPeerLink = {
+  peerId: string;
+  channelName: string;
+};
+/**
+ * Decides whether the linked peer may read `hash` through `documentId`. False
+ * is answered as `not-found`, indistinguishable from absent bytes.
+ */
+type LocalAttachmentAuthorizer = (link: AttachmentPeerLink, hash: AttachmentHash, documentId: string) => Promise<boolean>;
+type LocalAttachmentServerOptions = {
+  /** The brokered port to the peer; the same one the transport half uses. */
+  port: LocalChannelPort;
+  /** Who is asking; handed to {@link authorize}. */
+  link: AttachmentPeerLink;
+  /** The store bytes are served FROM. Only locally held bytes are served. */
+  store: IAttachmentStore;
+  /** Defaults to refusing every read; see {@link readGateAttachmentAuthorizer}. */
+  authorize?: LocalAttachmentAuthorizer;
+  /** Bytes per `chunk` message; defaults to {@link DEFAULT_LOCAL_CHUNK_BYTES}. */
+  chunkSizeBytes?: number;
+  /** Requests served at once; one past it is answered `pending`. */
+  maxConcurrentServes?: number;
+  onDiagnostic?: (message: string, error?: unknown) => void;
+};
+/** Default {@link LocalAttachmentServerOptions.maxConcurrentServes}. */
+export declare const DEFAULT_LOCAL_MAX_CONCURRENT_SERVES = 4;
+type ReadGateAttachmentAuthorizerOptions = {
+  readGate: AttachmentReadGate;
+  /** `SyncScopeGate`; a reactor without a policy model passes one over `BareReadGate`. */
+  scopeGate: IDocumentScopeGate;
+  references: Pick<IAttachmentReferenceReader, "referencingScopes">;
+  /** The subject a link reads as; undefined refuses every read on it. */
+  subjectOf: (link: AttachmentPeerLink) => AuthSubject | undefined;
+};
+/**
+ * Authorizes a peer read the way the Switchboard's attachment route does: the
+ * link's subject may read the document's `global` scope, the reactor serves
+ * the document to it, and a scope it may read references the hash.
+ */
+export declare function readGateAttachmentAuthorizer(options: ReadGateAttachmentAuthorizerOptions): LocalAttachmentAuthorizer;
+/**
+ * Serves attachment bytes to a brokered local peer from this reactor's own
+ * store.
+ *
+ * The answering half of {@link LocalAttachmentTransport}; both run on the same
+ * `LocalChannelPort` and ignore each other's messages.
+ *
+ * It never chains. The store is read WITHOUT a document id, which means a
+ * `LocalAttachmentStore` serves only bytes it actually holds and cannot reach
+ * for its own transport on the requester's behalf. Without that, two peers
+ * linked to each other would answer a miss by asking each other, and a hash
+ * neither held would bounce between them.
+ */
+export declare class LocalAttachmentServer {
+  private readonly port;
+  private readonly link;
+  private readonly store;
+  private readonly authorize;
+  private readonly chunkSizeBytes;
+  private readonly maxConcurrentServes;
+  private readonly onDiagnostic;
+  private readonly cancelled;
+  private readonly inFlight;
+  private readonly detachPort;
+  private served;
+  private bytesServed;
+  private refused;
+  private closed;
+  constructor(options: LocalAttachmentServerOptions);
+  /** What this peer has handed out. */
+  stats(): {
+    served: number;
+    bytesServed: number;
+    refused: number;
+  };
+  /** Detaches from the port. In-flight serves stop at their next slice. */
+  close(): void;
+  private onMessage;
+  private stopped;
+  private serve;
+  private serveInner;
+  private stream;
+  /** Refused and absent are one answer, so a peer learns nothing from it. */
+  private refuse;
+  private failRequest;
+  private post;
+}
+//#endregion
+//#region src/local/local-attachment-transport.d.ts
+type LocalAttachmentTransportOptions = {
+  /**
+   * The brokered port to the peer -- the same `LocalChannelPort` abstraction
+   * `LocalChannel` sync runs over (W1.1), on its own channel so byte traffic
+   * never interleaves with the sync wire.
+   */
+  port: LocalChannelPort;
+  /**
+   * How long to wait for the NEXT message of a request before abandoning it.
+   * Reset by every message, so a slow but progressing transfer is not cut off
+   * while a silent peer is. Defaults to
+   * {@link DEFAULT_LOCAL_REQUEST_TIMEOUT_MS}.
+   */
+  requestTimeoutMs?: number;
+  /** Swapped in tests; defaults to the realm's timers. */
+  setTimer?: (callback: () => void, delayMs: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+  /** Identifies this instance's request ids; defaults to a random nonce. */
+  instanceId?: string;
+  /** Refuses a body the peer declares larger than this. */
+  maxBytes?: number;
+};
+/**
+ * `IAttachmentTransport` over a brokered `LocalChannelPort`: one linked reactor
+ * pulling attachment bytes straight from its peer, with no Switchboard and no
+ * HTTP.
+ *
+ * The counterpart of {@link LocalAttachmentServer}, and a pair of them runs on
+ * each end of one port: a reactor both asks for bytes and serves them. The two
+ * halves share the port and ignore each other's messages (see
+ * `isLocalAttachmentRequest` / `isLocalAttachmentResponse`), and request ids
+ * are namespaced per instance so two peers that both start counting at 1 never
+ * match each other's replies.
+ *
+ * Pull-only by design. The agreed byte-movement model is lazy
+ * fetch-on-reference, so {@link announce} is a no-op and {@link push} refuses
+ * by name rather than silently succeeding: a push that reported success while
+ * moving nothing would make an eager-replication caller believe bytes had
+ * landed on a peer.
+ */
+export declare class LocalAttachmentTransport implements IAttachmentTransport {
+  private readonly port;
+  private readonly requestTimeoutMs;
+  private readonly setTimer;
+  private readonly clearTimer;
+  private readonly instanceId;
+  private readonly maxBytes;
+  private readonly pending;
+  private readonly detachPort;
+  private nextRequest;
+  private closed;
+  constructor(options: LocalAttachmentTransportOptions);
+  fetch(hash: AttachmentHash, documentId: string, signal?: AbortSignal): Promise<TransportFetchResult>;
+  /**
+   * No-op: the agreed model is the peer PULLING on reference, so there is
+   * nothing useful to tell it -- it will ask when one of its own operations
+   * names the hash. An eager-announce protocol would need a peer that acts on
+   * the notice, which nothing does.
+   */
+  announce(): Promise<void>;
+  /** Refuses: this transport moves bytes only in answer to a peer's request. */
+  push(): Promise<void>;
+  /** Detaches from the port and fails every in-flight request. */
+  close(): void;
+  private onMessage;
+  private handle;
+  /** A reply that breaks the protocol: tell the peer to stop, fail the request. */
+  private violate;
+  /** Resets this request's silence timer. */
+  private arm;
+  /** Forgets a request that completed normally. */
+  private release;
+  /**
+   * Forgets a request that failed, pushing the failure to whichever side is
+   * still listening: the fetch promise before `begin`, the body stream after.
+   */
+  private abandon;
+  private post;
+}
+//#endregion
+//#region src/local/protocol.d.ts
+/**
+ * Wire tag on every message, so one `LocalChannelPort` can carry this
+ * request/response protocol without being confused with anything else on the
+ * port, and so a version skew is a readable refusal rather than a crash.
+ */
+export declare const LOCAL_ATTACHMENT_PROTOCOL = "ph-attachment/v1";
+/** Default bytes per `chunk` message. */
+export declare const DEFAULT_LOCAL_CHUNK_BYTES: number;
+/** Default wait for the next message of a request before it is abandoned. */
+export declare const DEFAULT_LOCAL_REQUEST_TIMEOUT_MS = 30000;
+/** Ask a peer for the bytes of `hash`, authorized by `documentId`. */
+type LocalAttachmentFetchRequest = {
+  protocol: typeof LOCAL_ATTACHMENT_PROTOCOL;
+  kind: "fetch";
+  /** Unique per requesting instance; the peer echoes it on every reply. */
+  id: string;
+  hash: AttachmentHash;
+  documentId: string;
+};
+/** Abandon an in-flight `fetch` so the peer stops reading and sending. */
+type LocalAttachmentCancelRequest = {
+  protocol: typeof LOCAL_ATTACHMENT_PROTOCOL;
+  kind: "cancel";
+  id: string;
+};
+type LocalAttachmentRequest = LocalAttachmentFetchRequest | LocalAttachmentCancelRequest;
+/**
+ * The peer holds the bytes and is about to stream them. `metadata` arrives up
+ * front so the requester can start a body stream before the first byte.
+ */
+type LocalAttachmentBeginResponse = {
+  protocol: typeof LOCAL_ATTACHMENT_PROTOCOL;
+  kind: "begin";
+  id: string;
+  hash: AttachmentHash;
+  metadata: AttachmentMetadata;
+};
+/**
+ * One slice of the body. `bytes` is a `Uint8Array`, which both a browser
+ * `MessagePort` and a `node:worker_threads` one structured-clone natively.
+ * `seq` lets a receiver assert ordering rather than assume it.
+ */
+type LocalAttachmentChunkResponse = {
+  protocol: typeof LOCAL_ATTACHMENT_PROTOCOL;
+  kind: "chunk";
+  id: string;
+  seq: number;
+  bytes: Uint8Array;
+};
+/** The body is complete. */
+type LocalAttachmentEndResponse = {
+  protocol: typeof LOCAL_ATTACHMENT_PROTOCOL;
+  kind: "end";
+  id: string;
+};
+/** Retry later: the peer holds a reservation without bytes, or is at its serve cap. */
+type LocalAttachmentPendingResponse = {
+  protocol: typeof LOCAL_ATTACHMENT_PROTOCOL;
+  kind: "pending";
+  id: string;
+  hash: AttachmentHash;
+  expiresAtUtc: string;
+  retryAfterMs: number;
+  /** At its serve cap: the peer did not authorize or look up the hash. */
+  busy?: true;
+};
+/**
+ * The peer will not serve the hash: it does not hold the bytes, or the
+ * document does not authorize the read.
+ *
+ * The two are deliberately one answer. Distinguishing them would tell a peer
+ * which hashes exist without authorization, and the requester's handling is
+ * the same either way -- a bounded retry, because an unauthorized answer is
+ * most often the serving reactor's attachment reference index lagging its own
+ * sync (see `AttachmentRetryPolicy.notFoundAttempts`).
+ */
+type LocalAttachmentNotFoundResponse = {
+  protocol: typeof LOCAL_ATTACHMENT_PROTOCOL;
+  kind: "not-found";
+  id: string;
+};
+/** The peer failed while serving; the requester treats this as a retryable error. */
+type LocalAttachmentErrorResponse = {
+  protocol: typeof LOCAL_ATTACHMENT_PROTOCOL;
+  kind: "error";
+  id: string;
+  message: string;
+};
+type LocalAttachmentResponse = LocalAttachmentBeginResponse | LocalAttachmentChunkResponse | LocalAttachmentEndResponse | LocalAttachmentPendingResponse | LocalAttachmentNotFoundResponse | LocalAttachmentErrorResponse;
+type LocalAttachmentMessage = LocalAttachmentRequest | LocalAttachmentResponse;
+/**
+ * Whether `value` is a request for this protocol.
+ *
+ * Both halves live on one port -- each peer runs a transport AND a server over
+ * the same `LocalChannelPort` -- so each half has to recognise only its own
+ * side of the conversation and ignore the rest rather than treat it as
+ * malformed.
+ */
+export declare function isLocalAttachmentRequest(value: unknown): value is LocalAttachmentRequest;
+/** Whether `value` is a response for this protocol. */
+export declare function isLocalAttachmentResponse(value: unknown): value is LocalAttachmentResponse;
+//#endregion
+//#region src/peers/peered-attachment-transport.d.ts
+type PeeredAttachmentTransportOptions = {
+  /** Read at fetch time for the Switchboard origins of its gql remotes. */
+  syncManager?: Pick<ISyncManager, "list">;
+  /** An attachment host that is not one of the sync remotes. */
+  switchboardUrl?: string;
+  jwtHandler?: JwtHandler;
+  fetchFn?: typeof fetch;
+};
+/**
+ * Peers in parallel, then Switchboards in turn; verified data > pending >
+ * busy > error > unanimous not-found.
+ */
+export declare class PeeredAttachmentTransport implements IAttachmentTransport {
+  private readonly syncManager;
+  private readonly switchboardUrl;
+  private readonly jwtHandler;
+  private readonly fetchFn;
+  private readonly peers;
+  private readonly switchboards;
+  constructor(options?: PeeredAttachmentTransportOptions);
+  /** Keyed by (peerId, channelName), so one peer may hold several links. */
+  addPeer(peerId: string, channelName: string, transport: IAttachmentTransport): void;
+  /** Forgets one peer link; the caller owns closing its transport. */
+  removePeer(peerId: string, channelName: string): IAttachmentTransport | undefined;
+  /** Distinct linked peer ids. */
+  peerNames(): readonly string[];
+  /** The explicit Switchboard, then every gql remote's origin. */
+  switchboardSources(): readonly string[];
+  fetch(hash: AttachmentHash, documentId: string, signal?: AbortSignal): Promise<TransportFetchResult>;
+  private ask;
+  /** The first verified data wins and cancels the other peers. */
+  private askPeers;
+  /** Best effort across every source. */
+  announce(hash: AttachmentHash): Promise<void>;
+  push(): Promise<void>;
+  private sources;
+  private switchboardFor;
+}
+/** Attachments are served from the origin, not under the GraphQL path. */
+export declare function attachmentOriginOf(graphqlUrl: string): string;
+//#endregion
+//#region src/peers/attachment-peer-links.d.ts
+type AttachmentServedStats = {
+  served: number;
+  bytesServed: number;
+  refused: number;
+};
+type AttachmentPeerLinksOptions = {
+  /** What linked peers are served from. */
+  store: IAttachmentStore;
+  /** Where each link's pulling half is registered. */
+  transport: PeeredAttachmentTransport;
+  /** Absent, and absent on the link, every read is refused. */
+  authorize?: LocalAttachmentAuthorizer;
+  chunkSizeBytes?: number;
+  requestTimeoutMs?: number;
+  /** Each link's transport refuses a body declared larger than this. */
+  maxBytes?: number;
+  /** Requests each link's server serves at once. */
+  maxConcurrentServes?: number;
+  /** Called after a link is added; a host re-chases terminal hashes here. */
+  onPeerAdded?: (peerId: string, channelName: string) => void;
+  onDiagnostic?: (message: string, error?: unknown) => void;
+};
+type AttachmentPeerLinkOptions = {
+  /** Replaces the links-wide authorizer for this link. */
+  authorize?: LocalAttachmentAuthorizer;
+};
+/** Per-peer server and transport pairs, each on its own port, not the sync port. */
+export declare class AttachmentPeerLinks {
+  private readonly options;
+  private readonly links;
+  private readonly onDiagnostic;
+  constructor(options: AttachmentPeerLinksOptions);
+  has(peerId: string, channelName: string): boolean;
+  /** Takes ownership of `port` on success; on failure the port is untouched. */
+  addPeer(peerId: string, channelName: string, port: LocalChannelPort, linkOptions?: AttachmentPeerLinkOptions): void;
+  /** Closes the link's server, transport and port. False when absent. */
+  removePeer(peerId: string, channelName: string): boolean;
+  servedStats(): AttachmentServedStats;
+  close(): void;
+}
+//#endregion
+//#region src/replication/types.d.ts
+/**
+ * Pulls the attachment refs an operation carries.
+ *
+ * The replicator depends on this rather than on the schema compiler directly
+ * so a host that has no compiled document models (a test, a reactor whose
+ * models declare no `AttachmentRef` field but carry refs by another
+ * convention) can still feed it. The production implementation is
+ * `SchemaCompiledOperationRefs`, which is the same compiler + registry pair
+ * `AttachmentReferenceReadModel` uses, so the refs the replicator chases and
+ * the refs the reference index records are extracted by one piece of code.
+ */
+interface IOperationAttachmentRefs {
+  refsOf(item: OperationWithContext): readonly AttachmentRef[];
+}
+/**
+ * What the replicator is doing about one hash.
+ *
+ * - `queued`: known missing locally, waiting for a concurrency slot.
+ * - `fetching`: a transport fetch is in flight.
+ * - `held`: the bytes are in the local store. Terminal and the goal; a held
+ *   hash leaves the report.
+ * - `waiting`: the last answer was an unexpired `pending`, a bounded
+ *   `not-found` (see {@link AttachmentRetryPolicy.notFoundAttempts}), or a
+ *   transport error; a retry is scheduled.
+ * - `not-found`: the `not-found` budget is spent (an expired `pending` counts
+ *   as a `not-found`), no document is left unasked and no `pending` is live.
+ * - `failed`: the transport kept erroring and no document is left unasked.
+ *
+ * Both terminal states wait for `retry()`, or for a document not yet seen to
+ * reference the hash, which earns one more attempt through that document.
+ */
+type AttachmentReplicationState = "queued" | "fetching" | "held" | "waiting" | "not-found" | "failed";
+/**
+ * Retry shape for the three answers a fetch can give, honouring the
+ * `pending | not-found | data` triad that
+ * {@link IAttachmentTransport.fetch} exists to express.
+ *
+ * `notFoundAttempts` is the reference-index race budget and the reason
+ * `not-found` is retried at all: a peer authorizes a byte fetch through its
+ * OWN attachment reference index, and that index lags that peer's sync. So the
+ * first `not-found` for a freshly synced ref is far more likely to mean "that
+ * peer has not indexed this operation yet" than "these bytes do not exist".
+ * Retrying it a bounded number of times covers the lag without turning a
+ * genuinely missing hash into an unbounded loop -- and the counts keep both
+ * outcomes visible rather than papering over either.
+ */
+type AttachmentRetryPolicy = {
+  /** Fallback wait when a `pending` answer carries no `retryAfterMs`. */
+  pendingRetryMs: number;
+  /** Shortest wait honoured after a `pending`, whatever it asks for. */
+  minPendingRetryMs: number;
+  /** Cap for a run of `pending` answers, whose wait doubles per answer. */
+  maxPendingRetryMs: number;
+  /** `not-found` answers absorbed as index lag; cumulative until `retry()`. */
+  notFoundAttempts: number;
+  /** Base wait between `not-found` retries; doubles per attempt. */
+  notFoundRetryMs: number;
+  /** Transport errors in a row before giving up; any answer ends the run. */
+  errorAttempts: number;
+  /** Base wait between error retries; doubles per attempt. */
+  errorRetryMs: number;
+  /** Cap for not-found and error waits. */
+  maxRetryMs: number;
+};
+export declare const DEFAULT_ATTACHMENT_RETRY_POLICY: AttachmentRetryPolicy;
+/** Default bounded concurrency for in-flight attachment fetches. */
+export declare const DEFAULT_ATTACHMENT_REPLICATION_CONCURRENCY = 3;
+/** Default number of held hashes a replicator remembers after dropping their entries. */
+export declare const DEFAULT_ATTACHMENT_HELD_HASH_LIMIT = 10000;
+/** Default page size for the boot re-scan over the reference backlog. */
+export declare const DEFAULT_ATTACHMENT_BACKLOG_PAGE_SIZE = 200;
+/**
+ * The replicator's observable state: what it has seen, what it holds, and what
+ * it is still arguing about.
+ *
+ * Reported rather than inferred, because the two honest failure modes --
+ * a peer that never had the bytes, and a peer whose reference index has not
+ * caught up -- are indistinguishable from the outside at the moment they
+ * happen and only separable over time. `notFound` and `waiting` are both
+ * surfaced so an operator sees which one a reactor is in.
+ */
+type AttachmentReplicatorStatus = {
+  /** Whether the replicator is subscribed and scheduling. */
+  running: boolean;
+  /** Distinct hashes tracked: every entry plus the remembered held hashes. */
+  refsSeen: number;
+  /** Remembered held hashes, at most `heldHashLimit`. */
+  held: number;
+  /** `storageUsed()` of the local store, in bytes. */
+  bytesHeld: number;
+  /** Hashes waiting for a concurrency slot. */
+  queued: number;
+  /** Hashes with a fetch in flight. */
+  fetching: number;
+  /** Hashes with a retry scheduled (pending, lagging index, or error). */
+  waiting: number;
+  /** Hashes the peer answered `not-found` for, past the lag budget. */
+  notFound: number;
+  /** Hashes whose transport kept erroring. */
+  failed: number;
+  /** Whether the boot re-scan over the reference backlog has completed. */
+  backlogScanned: boolean;
+  /** The most recent transport error message, for the inspector. */
+  lastError: string | undefined;
+};
+/** One hash's replication record, as reported for diagnostics. */
+type AttachmentReplicationEntry = {
+  hash: AttachmentHash;
+  state: AttachmentReplicationState;
+  /** Documents whose operations referenced the hash; any of them may authorize. */
+  documentIds: readonly string[];
+  attempts: number;
+  notFoundAnswers: number;
+  /** Epoch ms of the next scheduled attempt, when one is scheduled. */
+  nextAttemptAtMs: number | undefined;
+  lastError: string | undefined;
+};
+//#endregion
+//#region src/replication/attachment-replicator.d.ts
+/**
+ * Clock and timer seam. Injected rather than taken from globals so a test can
+ * drive every retry deadline deterministically, without fake timers racing the
+ * replicator's own promises.
+ */
+type ReplicationTimers = {
+  /** Epoch ms; a pending answer's `expiresAtUtc` is compared against it. */
+  now: () => number;
+  setTimer: (callback: () => void, delayMs: number) => unknown;
+  clearTimer: (handle: unknown) => void;
+};
+export declare const SYSTEM_REPLICATION_TIMERS: ReplicationTimers;
+type AttachmentReplicatorOptions = {
+  /** Where bytes land, and the authority on what is already held. */
+  store: IAttachmentStore;
+  /** Where bytes come from. */
+  transport: IAttachmentTransport;
+  /** Pulls refs out of a committed operation. */
+  refs: IOperationAttachmentRefs;
+  /** The reactor's bus; the replicator subscribes to `JOB_READ_READY`. */
+  eventBus: IEventBus;
+  /**
+   * The durable reference list re-scanned on {@link AttachmentReplicator.start}.
+   * Omitted, the replicator only ever learns about refs from live operations --
+   * correct for a reactor with no reference index, and NOT resumable across a
+   * restart, which {@link AttachmentReplicatorStatus.backlogScanned} reports.
+   */
+  backlog?: IAttachmentReferenceScanner;
+  concurrency?: number;
+  retry?: Partial<AttachmentRetryPolicy>;
+  backlogPageSize?: number;
+  /**
+   * Held hashes remembered after their entry is dropped, oldest evicted first.
+   * An evicted hash referenced again costs one `store.has()`, never a fetch.
+   */
+  heldHashLimit?: number;
+  /**
+   * Whether fetched bytes are hashed and checked against the hash they were
+   * requested under. Defaults to true: a local peer transport means the bytes
+   * come from another reactor rather than from a trusted server, and a
+   * content-addressed store that accepts bytes it never verified is no longer
+   * content-addressed.
+   */
+  verifyHash?: boolean;
+  timers?: ReplicationTimers;
+  onDiagnostic?: (message: string, error?: unknown) => void;
+};
+/**
+ * Lazy fetch-on-reference: pulls attachment bytes a reactor's own operations
+ * reference but whose hash its local store lacks.
+ *
+ * The seam is `ReactorEventTypes.JOB_READ_READY` on the reactor's event bus,
+ * and that choice matters in two ways. It is AFTER the pre-ready read models,
+ * so by the time the replicator asks a peer for a hash, this reactor's own
+ * attachment reference index has recorded the reference -- the same reactor is
+ * therefore able to serve the hash onward, and a reactor cannot be in the
+ * position of chasing bytes it would refuse to authorize itself. And it is off
+ * the write path: a slow or unreachable peer cannot delay a commit, because
+ * the subscriber only notes hashes and returns.
+ *
+ * Resume is a re-scan of the reference index ({@link IAttachmentReferenceScanner}),
+ * not a cursor: the index plus `store.has()` re-derives the exact outstanding
+ * work set on every boot, idempotently, and a persisted cursor could only add a
+ * second truth that is wrong in the one direction that loses data.
+ *
+ * Loop-safety is structural: one entry per hash, created once, and every
+ * retry decision is {@link nextAfter}'s. A terminal entry (`not-found`,
+ * `failed`) is never re-queued by a further reference from a document it
+ * already knows; a document it has not seen earns it one more attempt, through
+ * that document. Otherwise only {@link AttachmentReplicator.retry} moves a
+ * terminal entry back. A held hash drops its entry and is remembered in a
+ * bounded set, so the map holds only unfinished work.
+ */
+export declare class AttachmentReplicator {
+  private readonly store;
+  private readonly transport;
+  private readonly refs;
+  private readonly eventBus;
+  private readonly backlog;
+  private readonly concurrency;
+  private readonly policy;
+  private readonly backlogPageSize;
+  private readonly heldHashLimit;
+  private readonly verifyHash;
+  private readonly timers;
+  private readonly onDiagnostic;
+  private readonly entries;
+  private readonly heldHashes;
+  private readonly queue;
+  private readonly idleWaiters;
+  private readonly aborts;
+  private unsubscribe;
+  private running;
+  private inFlight;
+  private timerHandle;
+  private timerAtMs;
+  private backlogScan;
+  private backlogDone;
+  private lastError;
+  constructor(options: AttachmentReplicatorOptions);
+  /**
+   * Subscribes to committed operations and starts the boot re-scan.
+   *
+   * The subscription is taken BEFORE the scan so no operation committed during
+   * the scan can slip between the two. A hash both paths find is one entry.
+   *
+   * A restart resumes its own unfinished work: a `stop()` empties the queue but
+   * keeps the entries, so entries left `queued` or `waiting` are re-armed here.
+   * Without that, a hash that was outstanding at `stop()` would sit in the map
+   * forever unless an unrelated live operation happened to pump the queue --
+   * the backlog re-scan does not rescue it, because `observeReference` treats
+   * an already-known hash as nothing to do.
+   */
+  start(): void;
+  /**
+   * Stops scheduling, drops the subscription and aborts in-flight fetches.
+   *
+   * Entries are kept: the in-memory retry counters are not durable state and a
+   * restart legitimately starts the budgets over (a hash that was `not-found`
+   * because a peer's index lagged deserves another look after a reboot), but a
+   * `stop()` that is not a restart should not forget what is held either --
+   * `store.has()` is re-checked before every fetch regardless.
+   */
+  stop(): Promise<void>;
+  /** Notes every ref carried by `items`. Synchronous: it only enqueues. */
+  observeOperations(items: readonly OperationWithContext[]): void;
+  /** Notes one (document, ref) pair, queueing the hash if it is new. */
+  observeReference(documentId: string, ref: AttachmentRef): void;
+  status(): Promise<AttachmentReplicatorStatus>;
+  /** Every hash not yet held and what is happening to it. */
+  report(): AttachmentReplicationEntry[];
+  /**
+   * Re-queues terminal entries so a `not-found` or `failed` hash is chased
+   * again, resetting their budgets. `hash` narrows it to one; absent, every
+   * terminal entry is retried.
+   *
+   * The deliberate manual lever over the reference-index race: when an
+   * operator can see that a peer has caught up, nothing should make them wait
+   * for a reboot to find out.
+   */
+  retry(hash?: AttachmentHash): void;
+  /**
+   * Resolves when nothing is queued or in flight.
+   *
+   * Entries `waiting` on a retry deadline do NOT hold this open -- their next
+   * attempt is the timer's business, and a caller that wants to reach it
+   * advances the injected clock. A test seam, and what a load harness waits on.
+   */
+  idle(): Promise<void>;
+  /** Awaits the boot re-scan; resolves immediately when there is no backlog. */
+  backlogScanned(): Promise<void>;
+  /** Re-queues every non-terminal entry a previous `stop()` stranded. */
+  private resumeOutstanding;
+  private scanBacklog;
+  /** Starts as many queued fetches as the concurrency bound allows. */
+  private pump;
+  private fetchOne;
+  private attempt;
+  private apply;
+  private markHeld;
+  private recordError;
+  private schedule;
+  /** Keeps exactly one timer, set to the earliest outstanding deadline. */
+  private armTimer;
+  private onTimer;
+  private cancelTimer;
+  private settleIdle;
+}
+/** A scanner over a plain list, for a host without a reference index. */
+export declare function staticAttachmentReferenceScanner(references: readonly AttachmentReferenceRow[]): IAttachmentReferenceScanner;
+//#endregion
+//#region src/replication/hash.d.ts
+/**
+ * Lowercase SHA-256 hex of `bytes` -- the `attachment://v1:` hash format
+ * (`packages/reactor/src/attachments/types.ts`).
+ *
+ * WebCrypto, so the same code runs in Node and in a browser realm. There is no
+ * streaming digest in WebCrypto, which is why verification happens over
+ * collected bytes.
+ */
+export declare function sha256Hex(bytes: Uint8Array): Promise<AttachmentHash>;
+//#endregion
+//#region src/replication/operation-attachment-refs.d.ts
+/**
+ * The production {@link IOperationAttachmentRefs}: the compiled, schema-driven
+ * extractor, reused rather than reimplemented.
+ *
+ * This is the same `(registry, compiler)` pair `AttachmentReferenceReadModel`
+ * runs, so a ref the index records and a ref the replicator chases are found by
+ * one piece of code -- including the compiler's per-module/per-action cache,
+ * which is held by the compiler instance a host shares between the two. A host
+ * with no read model to share one with takes the default compiler.
+ *
+ * Extraction failures do NOT propagate. A malformed ref or an unregistered
+ * document type must not take down the event-bus subscriber the replicator
+ * runs on: that would turn an attachment problem into a reactor-wide write
+ * failure, since `IEventBus.emit` aggregates subscriber errors back to the
+ * emitter. The read model is the component whose job is to refuse a bad ref
+ * loudly; this one is a best-effort byte chaser, so it reports and moves on.
+ */
+export declare class SchemaCompiledOperationRefs implements IOperationAttachmentRefs {
+  private readonly registry;
+  private readonly compiler;
+  private readonly onDiagnostic;
+  constructor(registry: IDocumentModelRegistry, compiler?: IAttachmentSchemaCompiler, onDiagnostic?: (message: string, error: unknown) => void);
+  refsOf(item: OperationWithContext): readonly AttachmentRef[];
+}
+//#endregion
+//#region src/storage/local/bytes.d.ts
+/**
+ * Drains `stream` into one `Uint8Array`.
+ *
+ * The local stores hold whole blobs (see {@link ILocalAttachmentBackend}), so
+ * the stream an `IAttachmentStore.put` is handed has to be collected before it
+ * can be written. Realm-neutral: no `node:buffer`, no `Blob`.
+ */
+export declare function collectStream(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;
+/** A one-chunk `ReadableStream` over `bytes`. */
+export declare function streamFromBytes(bytes: Uint8Array): ReadableStream<Uint8Array>;
+//#endregion
+//#region src/storage/local/types.d.ts
+/**
+ * One attachment's metadata row in a local, realm-resident store.
+ *
+ * The committed subset of {@link AttachmentHeader}: no `pending` status and no
+ * `expiresAtUtc`, because a local store of this kind holds no reservation
+ * table. Pending is a property of an in-flight UPLOAD, which belongs to the
+ * server-side `KyselyAttachmentStore`/`IReservationStore` pair; a replicating
+ * store only ever learns "pending" from a transport answer and never persists
+ * it.
+ */
+type LocalAttachmentRecord = {
+  hash: AttachmentHash;
+  mimeType: string;
+  fileName: string;
+  /**
+   * The byte length actually held (or last held, for an evicted record), not
+   * the producer's claim. `AttachmentMetadata.sizeBytes` arrives over a wire
+   * and is only as honest as its sender; `storageUsed()` sums this field, so
+   * it is measured from the bytes received.
+   */
+  sizeBytes: number;
+  extension: string | null;
+  status: "available" | "evicted";
+  source: "local" | "sync";
+  createdAtUtc: string;
+  lastAccessedAtUtc: string;
+};
+/**
+ * The persistence seam under {@link LocalAttachmentStore}: a content-addressed
+ * record store plus a blob store, and nothing else.
+ *
+ * Every `IAttachmentStore` semantic -- dedup on put, evicted-then-restored,
+ * access-time bumping, transport re-fetch, what `has()` means -- lives in
+ * {@link LocalAttachmentStore} above this interface, so the two backends
+ * (IndexedDB for a browser, a memory twin for Node) cannot drift on behaviour.
+ * A backend only has to move bytes and rows.
+ *
+ * Bytes cross this interface as whole `Uint8Array`s rather than streams on
+ * purpose: IndexedDB has no streaming value API, so a chunked backend would
+ * have to reassemble anyway, and a browser-side attachment store is bounded by
+ * what the realm can hold regardless.
+ */
+interface ILocalAttachmentBackend {
+  /** The record for `hash`, or undefined when the hash is unknown. */
+  readRecord(hash: AttachmentHash): Promise<LocalAttachmentRecord | undefined>;
+  /**
+   * Writes `record` and `bytes` as ONE unit, replacing whatever was there.
+   *
+   * Atomicity matters: a record claiming `available` with no blob behind it
+   * reads as a store that holds bytes it cannot serve, which is exactly the
+   * state the replicator would never retry.
+   */
+  write(record: LocalAttachmentRecord, bytes: Uint8Array): Promise<void>;
+  /** The bytes for `hash`, or undefined when none are held. */
+  readBytes(hash: AttachmentHash): Promise<Uint8Array | undefined>;
+  /**
+   * Writes `record` (expected to carry `status: "evicted"`) and deletes its
+   * blob as one unit. The record is retained so the hash stays known.
+   */
+  evict(record: LocalAttachmentRecord): Promise<void>;
+  /** Sets `lastAccessedAtUtc` on an existing record; a no-op for an unknown hash. */
+  touch(hash: AttachmentHash, lastAccessedAtUtc: string): Promise<void>;
+  /** Summed `sizeBytes` of every record whose status is `available`. */
+  availableBytes(): Promise<number>;
+  /** Releases the underlying handle. Idempotent. */
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/storage/local/idb-attachment-backend.d.ts
+/** Metadata rows, keyed by content hash. */
+export declare const IDB_RECORD_STORE = "records";
+/** Blob rows (`{ hash, bytes }`), keyed by the same content hash. */
+export declare const IDB_BLOB_STORE = "blobs";
+/** Index over {@link LocalAttachmentRecord.status}; what `storageUsed()` scans. */
+export declare const IDB_STATUS_INDEX = "by_status";
+/** Default database name. One database holds one reactor's attachment store. */
+export declare const DEFAULT_IDB_DATABASE = "ph-attachments";
+type IdbAttachmentBackendOptions = {
+  /**
+   * Database name; defaults to {@link DEFAULT_IDB_DATABASE}. A host running
+   * several reactors in one origin must namespace this per reactor, exactly as
+   * the operation store is namespaced -- two reactors sharing one attachment
+   * database would share evictions and storage accounting.
+   */
+  databaseName?: string;
+  /**
+   * The factory to open against; defaults to the realm's `indexedDB`. The seam
+   * a shim (or a test double) is injected through, and the reason this backend
+   * takes no dependency on a global being present at import time.
+   */
+  indexedDB?: IDBFactory;
+};
+/**
+ * An IndexedDB-backed {@link ILocalAttachmentBackend}: the browser-resident
+ * attachment store a reactor in a tab or a SharedWorker replicates into.
+ *
+ * Two object stores, written in one transaction so a record and its blob land
+ * or fail together (the atomicity {@link ILocalAttachmentBackend.write}
+ * requires). Bytes are kept as `ArrayBuffer` rather than `Blob`: both are
+ * structured-clone-safe values IndexedDB stores natively, and an ArrayBuffer
+ * needs no async read to get back to the `Uint8Array` the store serves.
+ *
+ * OPFS is the obvious later alternative for large blobs -- it streams and does
+ * not hold a whole attachment in the realm's heap -- and nothing above this
+ * interface would change: it is one more backend.
+ *
+ * The database handle is opened lazily on first use and reused, so constructing
+ * this in a realm that has no `indexedDB` (a Node import of the barrel) costs
+ * nothing and fails only if something actually reads or writes.
+ */
+export declare class IdbAttachmentBackend implements ILocalAttachmentBackend {
+  private readonly databaseName;
+  private readonly factory;
+  private opening;
+  private database;
+  private closed;
+  constructor(options?: IdbAttachmentBackendOptions);
+  readRecord(hash: AttachmentHash): Promise<LocalAttachmentRecord | undefined>;
+  write(record: LocalAttachmentRecord, bytes: Uint8Array): Promise<void>;
+  readBytes(hash: AttachmentHash): Promise<Uint8Array | undefined>;
+  evict(record: LocalAttachmentRecord): Promise<void>;
+  touch(hash: AttachmentHash, lastAccessedAtUtc: string): Promise<void>;
+  availableBytes(): Promise<number>;
+  close(): Promise<void>;
+  private open;
+  private openDatabase;
+}
+//#endregion
+//#region src/storage/local/local-attachment-store.d.ts
+/**
+ * A realm-resident, content-addressed {@link IAttachmentStore} over a
+ * {@link ILocalAttachmentBackend} -- the browser-capable half of attachment
+ * byte movement.
+ *
+ * The same class serves both backends, so an IndexedDB store in a tab and the
+ * memory twin a Node test runs cannot diverge in behaviour: every semantic the
+ * `IAttachmentStore` contract states is implemented once, here.
+ *
+ * Differences from `KyselyAttachmentStore`, all of them deliberate:
+ *
+ * - No reservation table, so `stat()`/`get()` never synthesize `pending` from
+ *   local state. `pending` only ever arrives as a TRANSPORT answer, which
+ *   `get()` raises as {@link AttachmentPending} exactly as the Kysely store
+ *   does for a remote pending.
+ * - `get()` reads the whole blob before it hands back a stream, so there is no
+ *   such thing as an in-flight read for `evict()` to destroy. The contract's
+ *   "skip hashes with active readers" clause is satisfied by construction
+ *   rather than by a refcount; a caller already holding a stream holds a
+ *   snapshot.
+ * - `sizeBytes` is the measured length of the bytes received, not the
+ *   producer's `AttachmentMetadata.sizeBytes` claim, so `storageUsed()` cannot
+ *   be talked into a wrong number by a remote.
+ */
+export declare class LocalAttachmentStore implements IAttachmentStore {
+  private readonly backend;
+  private readonly transport;
+  private readonly now;
+  constructor(backend: ILocalAttachmentBackend, transport: IAttachmentTransport, now?: () => Date);
+  stat(hash: AttachmentHash): Promise<AttachmentHeader>;
+  has(hash: AttachmentHash): Promise<boolean>;
+  get(hash: AttachmentHash, signal?: AbortSignal, documentId?: string): Promise<AttachmentResponse>;
+  put(hash: AttachmentHash, metadata: AttachmentMetadata, data: ReadableStream<Uint8Array>): Promise<void>;
+  evict(hash: AttachmentHash): Promise<void>;
+  storageUsed(): Promise<number>;
+  /** Releases the backend handle. */
+  close(): Promise<void>;
+  /**
+   * Stores bytes this realm produced itself, as `source: "local"`.
+   *
+   * `put()` is the transport's entry point and marks everything `sync`, which
+   * is the right provenance for a replicated blob and the wrong one for a blob
+   * that originated here. The server-side store gets `source: "local"` rows
+   * from its upload handles; a local store has no upload handle, so this is
+   * how a producer (an editor that just hashed a file, a test that seeds a
+   * peer) says the bytes are its own.
+   */
+  putLocal(hash: AttachmentHash, metadata: AttachmentMetadata, data: ReadableStream<Uint8Array>): Promise<void>;
+  /**
+   * `overwrite` skips the available-hash dedup check.
+   *
+   * Only {@link fetchRemote} sets it, and only because it is reached when the
+   * local copy is unusable -- including the torn case where the record says
+   * `available` over a missing blob. Without it, that record would deduplicate
+   * away its own repair and the hash could never be restored.
+   */
+  private store;
+  /**
+   * Restores `hash` from the transport on behalf of `documentId`, persists it
+   * through the same write path `put` uses (so provenance follows one rule)
+   * and serves the result from the store rather than from the transport's
+   * stream, which has already been consumed.
+   *
+   * The fetched bytes are hashed and refused when they are not what was asked
+   * for, mirroring {@link AttachmentReplicator}: a transport peer is another
+   * reactor rather than a trusted server, and a content-addressed store that
+   * accepts bytes it never verified is no longer content-addressed. A mismatch
+   * is surfaced as an error and nothing is written, so a lying peer cannot
+   * poison the store.
+   */
+  private fetchRemote;
+}
+//#endregion
+//#region src/storage/local/memory-attachment-backend.d.ts
+/**
+ * The in-realm memory twin of {@link IdbAttachmentBackend}.
+ *
+ * It exists so the whole {@link LocalAttachmentStore} contract -- and the
+ * replicator above it -- is testable in Node without an IndexedDB shim, and so
+ * a reactor that wants a deliberately ephemeral attachment store (a test, a
+ * throwaway reactor) has one. The backend contract suite runs against
+ * this and against the IndexedDB backend, so the two answer identically.
+ *
+ * Records are copied in and out: a caller mutating a returned record must not
+ * be able to change what the store holds, which is the behaviour a real
+ * persistence layer has for free.
+ */
+export declare class MemoryAttachmentBackend implements ILocalAttachmentBackend {
+  private readonly records;
+  private readonly blobs;
+  readRecord(hash: AttachmentHash): Promise<LocalAttachmentRecord | undefined>;
+  write(record: LocalAttachmentRecord, bytes: Uint8Array): Promise<void>;
+  readBytes(hash: AttachmentHash): Promise<Uint8Array | undefined>;
+  evict(record: LocalAttachmentRecord): Promise<void>;
+  touch(hash: AttachmentHash, lastAccessedAtUtc: string): Promise<void>;
+  availableBytes(): Promise<number>;
+  close(): Promise<void>;
+}
+//#endregion
+export type { AttachmentPeerLink, AttachmentPeerLinkOptions, AttachmentPeerLinksOptions, AttachmentReadGate, AttachmentReferencePageResult, AttachmentReferenceRow, AttachmentReplicationEntry, AttachmentReplicationState, AttachmentReplicatorOptions, AttachmentReplicatorStatus, AttachmentRetryPolicy, AttachmentServedStats, IAttachmentReferenceScanner, IDocumentScopeGate, ILocalAttachmentBackend, IOperationAttachmentRefs, IdbAttachmentBackendOptions, LocalAttachmentAuthorizer, LocalAttachmentBeginResponse, LocalAttachmentCancelRequest, LocalAttachmentChunkResponse, LocalAttachmentEndResponse, LocalAttachmentErrorResponse, LocalAttachmentFetchRequest, LocalAttachmentMessage, LocalAttachmentNotFoundResponse, LocalAttachmentPendingResponse, LocalAttachmentRecord, LocalAttachmentRequest, LocalAttachmentResponse, LocalAttachmentServerOptions, LocalAttachmentTransportOptions, PeeredAttachmentTransportOptions, ReadGateAttachmentAuthorizerOptions, ReplicationTimers };
+export {};
+//# sourceMappingURL=replication.d.ts.map