@powerhousedao/reactor 6.2.2-dev.3 → 6.2.2-dev.30

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Action, CreateDocumentActionInput, DocumentModelModule, ISigner, Operation, OperationContext, OperationWithContext, OperationWithContext as OperationWithContext$1, PHDocument, PHDocumentState, SignatureVerificationHandler, UpgradeDocumentActionInput, UpgradeManifest, UpgradeReducer, UpgradeTransition, actions as documentActions } from "@powerhousedao/shared/document-model";
+import { Action, AuthDecision, AuthRequest, AuthSubject, CreateDocumentActionInput, DocumentModelModule, ISigner, Operation, OperationContext, OperationWithContext, OperationWithContext as OperationWithContext$1, PHDocument, PHDocumentState, SignatureVerificationHandler, UpgradeDocumentActionInput, UpgradeManifest, UpgradeReducer, UpgradeTransition, actions as documentActions } from "@powerhousedao/shared/document-model";
 import { DocumentDriveDocument, DriveInput, FolderNode, Node } from "@powerhousedao/shared/document-drive";
 import { ILogger } from "document-model";
 import * as kysely from "kysely";
@@ -69,6 +69,17 @@ declare enum JobQueueState {
   RUNNING = 3,
   RESOLVED = 4
 }
+/**
+ * How a retry is accounted against the job's retry limit.
+ * - `CountAgainstLimit` (default): a fault; the job eventually exhausts its
+ *   retries and fails terminally.
+ * - `ExemptFromLimit`: not a fault, so the attempt is not charged to the job.
+ *   Used for concurrency conflicts, where the retry does new work.
+ */
+declare enum RetryAccounting {
+  CountAgainstLimit = "count-against-limit",
+  ExemptFromLimit = "exempt-from-limit"
+}
 /**
  * Interface for a job execution handle
  */
@@ -230,6 +241,11 @@ type ViewFilter = {
   branch?: string;
   scopes?: string[];
   revision?: number;
+  /**
+   * Read subject for the IReactorClient read gate; defaults to the client's
+   * signer. Set per request when serving many principals. Ignored by IReactor.
+   */
+  subject?: AuthSubject;
 };
 /**
  * Describes filter options for searching documents.
@@ -328,6 +344,16 @@ interface IReadModelCoordinator {
    */
   getChainDepth(): number;
 }
+type ReadModelRegistrationStage = "pre_ready" | "post_ready";
+/**
+ * Optional capability exposed by coordinators that support adding read models
+ * after construction. Custom and remote coordinators are not required to
+ * implement it.
+ */
+interface ILiveReadModelCoordinator extends IReadModelCoordinator {
+  addReadModel(readModel: IReadModel, stage: ReadModelRegistrationStage): void;
+}
+declare function supportsLiveReadModelRegistration(coordinator: IReadModelCoordinator): coordinator is ILiveReadModelCoordinator;
 //#endregion
 //#region src/sync/types.d.ts
 declare enum ChannelScheme {
@@ -537,6 +563,36 @@ declare class OptimisticLockError extends Error {
 declare class RevisionMismatchError extends Error {
   constructor(expected: number, actual: number);
 }
+/**
+ * One read-set stream and the highest operation index observed on it, or -1
+ * if it was observed empty.
+ */
+type AppendConditionStream = {
+  documentId: string;
+  scope: string;
+  branch: string;
+  revision: number;
+};
+/**
+ * A read-set enforced by {@link IOperationStore.apply}: the append fails if
+ * any stream has operations past its recorded revision.
+ */
+type AppendCondition = {
+  streams: AppendConditionStream[];
+};
+/** Error history keeps messages, not classes, so failures match by prefix. */
+declare const APPEND_CONDITION_FAILED_PREFIX = "Append condition failed: ";
+/**
+ * A read-set stream grew before the append committed. A concurrency
+ * conflict, not a fault: the caller retries against the new stream heads.
+ */
+declare class AppendConditionFailedError extends Error {
+  readonly condition: AppendCondition;
+  constructor(condition: AppendCondition);
+  static isError(error: unknown): error is AppendConditionFailedError;
+  /** True when a recorded error message is an append-condition failure. */
+  static isFailureMessage(message: string): boolean;
+}
 /**
  * A write transaction passed to {@link IOperationStore.apply}. Accumulates
  * operations that are committed atomically when the callback returns.
@@ -571,6 +627,12 @@ interface IOperationStore {
    * returned instead of throwing. If no matching stored row is found, the
    * original error is propagated unchanged.
    *
+   * With an {@link AppendCondition}, the append additionally fails with
+   * {@link AppendConditionFailedError} — writing nothing — if any read-set
+   * stream has operations past its recorded revision. The written and
+   * read-set streams are advisory-locked in sorted key order, so concurrent
+   * conditional appends on overlapping streams serialize.
+   *
    * @param documentId - The document id
    * @param documentType - The document type identifier
    * @param scope - The operation scope (e.g. "global", "local")
@@ -578,9 +640,10 @@ interface IOperationStore {
    * @param revision - Expected current revision (optimistic lock)
    * @param fn - Callback that stages operations via {@link AtomicTxn}
    * @param signal - Optional abort signal to cancel the request
+   * @param condition - Optional read-set to enforce at write time
    * @returns The stored operations; empty array when no operations were staged
    */
-  apply(documentId: string, documentType: string, scope: string, branch: string, revision: number, fn: (txn: AtomicTxn) => void | Promise<void>, signal?: AbortSignal): Promise<Operation[]>;
+  apply(documentId: string, documentType: string, scope: string, branch: string, revision: number, fn: (txn: AtomicTxn) => void | Promise<void>, signal?: AbortSignal, condition?: AppendCondition): Promise<Operation[]>;
   /**
    * Returns operations for a document/scope/branch whose index is greater
    * than the given revision.
@@ -1152,6 +1215,51 @@ declare class DriveCollectionId {
   equals(other: DriveCollectionId): boolean;
 }
 //#endregion
+//#region src/cache/write-cache-types.d.ts
+/**
+ * Configuration options for the write cache
+ */
+type WriteCacheConfig = {
+  /** Maximum number of document streams to cache (LRU eviction). Default: 1000 */maxDocuments: number; /** Number of snapshots to keep in each document's ring buffer. Default: 10 */
+  ringBufferSize: number; /** Persist a keyframe snapshot every N revisions. Default: 10 */
+  keyframeInterval: number;
+};
+/**
+ * Unique identifier for a document stream
+ */
+type DocumentStreamKey = {
+  /** Document identifier */documentId: string; /** Operation scope */
+  scope: string; /** Branch name */
+  branch: string;
+};
+/**
+ * Where a snapshot sits in its stream.
+ *
+ * - `Head`: the newest revision of the stream when it was stored. Only these
+ *   can answer a read that asks for the head.
+ * - `Historical`: state at an earlier revision. Usable as a starting point to
+ *   replay forward from, and as an answer to a read for that same revision.
+ */
+declare enum SnapshotPosition {
+  Head = "head",
+  Historical = "historical"
+}
+/**
+ * A cached document snapshot at a specific revision
+ */
+type CachedSnapshot = {
+  /** The revision number of this snapshot */revision: number; /** The document state at this revision */
+  document: PHDocument; /** Where this snapshot sat in the stream when it was stored */
+  position: SnapshotPosition;
+};
+/**
+ * Serialized keyframe snapshot for K/V store persistence
+ */
+type KeyframeSnapshot = {
+  /** The revision number of this keyframe */revision: number; /** Serialized document state */
+  document: string;
+};
+//#endregion
 //#region src/cache/write/interfaces.d.ts
 /**
  * IWriteCache is a write-side projection that optimizes document state retrieval
@@ -1166,7 +1274,8 @@ interface IWriteCache {
    * @param documentId - The document identifier
    * @param scope - Operation scope
    * @param branch - Branch name
-   * @param targetRevision - The exact revision to retrieve (optional, defaults to latest)
+   * @param targetRevision - Index of the last operation to apply, defaulting
+   *   to latest. An operation index, never `header.revision[scope]`.
    * @param signal - Optional abort signal to cancel the operation
    * @returns The complete document at the specified revision
    *
@@ -1192,15 +1301,19 @@ interface IWriteCache {
    * @param documentId - The document identifier
    * @param scope - Operation scope
    * @param branch - Branch name
-   * @param revision - The revision this document represents
+   * @param revision - Index of the last operation this document reflects, so
+   *   `header.revision[scope]` is one greater. -1 for an empty scope.
    * @param document - The document to cache
+   * @param position - Whether `revision` is the stream's head. Nothing checks
+   *   it: claiming `Head` for an earlier revision makes a getState() with no
+   *   target return stale state.
    *
    * @example
    * ```typescript
-   * cache.putState(docId, 'global', 'main', 42, document);
+   * cache.putState(docId, 'global', 'main', 42, document, SnapshotPosition.Head);
    * ```
    */
-  putState(documentId: string, scope: string, branch: string, revision: number, document: PHDocument): void;
+  putState(documentId: string, scope: string, branch: string, revision: number, document: PHDocument, position: SnapshotPosition): void;
   /**
    * Invalidates (removes) cached entries for a document stream.
    *
@@ -1884,6 +1997,7 @@ declare class ReactorClient implements IReactorClient {
   private documentView;
   readonly drives: IDriveClient;
   constructor(logger: ILogger, reactor: IReactor, signer: ISigner, subscriptionManager: IReactorSubscriptionManager, jobAwaiter: IJobAwaiter, documentIndexer: IDocumentIndexer, documentView: IDocumentView);
+  private readSubject;
   /**
    * Retrieves a list of document model modules.
    */
@@ -2013,11 +2127,28 @@ type JobResult = {
   duration?: number; /** Any additional metadata from the execution */
   metadata?: Record<string, any>;
 };
+/**
+ * Enforcement the reactor performs, each off by default.
+ *
+ * A verdict reached while replaying is part of the document's history, so two
+ * reactors that share documents and disagree on these diverge. A flag is turned
+ * on for a set of reactors that sync with each other, not for one node.
+ */
+type ReactorFeatureFlags = {
+  /**
+   * Decide whether an operation may be admitted by building a decision model
+   * over the document stream, rather than reading the deleted flag from the
+   * document meta cache. Deletion then takes effect from the deleting
+   * operation's position rather than for the whole document.
+   */
+  documentDecisions: boolean;
+};
 /**
  * Configuration options for the job executor
  */
 type JobExecutorConfig = {
-  /** Maximum number of conflicting operations to skip when reshuffling. */maxSkipThreshold?: number; /** Maximum number of concurrent jobs to execute */
+  /** Feature flags; anything unset is off. */featureFlags?: Partial<ReactorFeatureFlags>; /** Maximum number of conflicting operations to skip when reshuffling. */
+  maxSkipThreshold?: number; /** Maximum number of concurrent jobs to execute */
   maxConcurrency?: number; /** Maximum time in milliseconds a job can run before being considered timed out */
   jobTimeoutMs?: number; /** Base delay in milliseconds for exponential backoff retries */
   retryBaseDelayMs?: number; /** Maximum delay in milliseconds for exponential backoff retries */
@@ -2242,9 +2373,10 @@ type InitMessage = {
   correlationId: string;
   workerId: string;
   poolConfig: WorkerPoolConfig;
-  db: DbConfig;
-  signatureVerifier: SignatureVerifierSpec;
-  models: ModelManifestEntry[];
+  db: DbConfig; /** Omitted = the worker performs no executor-side signature verification. */
+  signatureVerifier?: SignatureVerifierSpec;
+  models: ModelManifestEntry[]; /** Omitted = the worker builds its executor with the built-in defaults. */
+  executorConfig?: JobExecutorConfig;
 };
 /**
  * Dispatches a job to the worker for execution.
@@ -2679,9 +2811,11 @@ interface IQueue {
    * Retry a failed job.
    * @param jobId - The ID of the job to retry
    * @param error - Optional error information from the failure
+   * @param accounting - Whether the attempt counts against the job's retry
+   * limit; defaults to {@link RetryAccounting.CountAgainstLimit}
    * @returns Promise that resolves when the job is requeued for retry
    */
-  retryJob(jobId: string, error?: ErrorInfo$1): Promise<void>;
+  retryJob(jobId: string, error?: ErrorInfo$1, accounting?: RetryAccounting): Promise<void>;
   /**
    * Returns true if and only if all jobs have been resolved.
    */
@@ -2749,6 +2883,25 @@ interface DocumentViewDatabase {
 }
 type InsertableDocumentSnapshot = Insertable<DocumentSnapshotTable>;
 //#endregion
+//#region src/core/model-sources.d.ts
+/** An importable file holding one or more document-model exports. */
+type FileModelSource = {
+  filePath: string;
+  exportName?: string;
+};
+/** An importable package specifier holding one or more document-model exports. */
+type PackageModelSource = {
+  packageName: string;
+  subpath?: string;
+  exportName?: string;
+};
+/**
+ * A source of document models: a live module, an importable file, or an
+ * importable package. File and package sources can cross a worker-thread
+ * boundary (workers re-import them); a live module cannot.
+ */
+type DocumentModelSource = DocumentModelModule<any> | FileModelSource | PackageModelSource;
+//#endregion
 //#region src/registry/interfaces.d.ts
 type RegistrationResult<T> = {
   status: "success";
@@ -2759,18 +2912,18 @@ type RegistrationResult<T> = {
   error: Error;
 };
 /**
- * Loader that can asynchronously resolve and return a document model module
- * for a given document type. Used by the queue to gate CREATE_DOCUMENT jobs
- * until the required model is available in the registry.
+ * Loader that asynchronously resolves a document type to a
+ * {@link DocumentModelSource}. Used by the queue to gate CREATE_DOCUMENT
+ * jobs until the required model is available in the registry.
  *
- * `resolveSpec` is an optional companion that returns the IPC-clonable spec
- * for the same document type. Implementations that integrate with the worker
- * pool must provide it so the parent can broadcast `load-model` to workers
- * after registering the model on the parent.
+ * Return an importable source ({ filePath } or { packageName }) whenever
+ * possible: the resolver registers the resolved models on the host registry
+ * and broadcasts importable sources to executor workers. A live
+ * DocumentModelModule is also valid but host-only — it cannot cross a
+ * worker-thread boundary, so worker pools will not receive it.
  */
 interface IDocumentModelLoader {
-  load(documentType: string): Promise<DocumentModelModule<any>>;
-  resolveSpec?(documentType: string): Promise<ModelManifestEntry | null>;
+  load(documentType: string): Promise<DocumentModelSource>;
 }
 /**
  * Registry for managing document model modules.
@@ -2943,6 +3096,7 @@ interface OperationTable {
   action: unknown;
   skip: number;
   error?: string | null;
+  deniedReason?: string | null;
   hash: string;
 }
 interface KeyframeTable {
@@ -2974,6 +3128,7 @@ interface OperationIndexOperationTable {
   skip: number;
   hash: string;
   action: unknown;
+  deniedReason?: string | null;
   sourceRemote: Generated<string>;
 }
 interface SyncRemoteTable {
@@ -3841,7 +3996,6 @@ declare class DocumentModelResolver implements IDocumentModelResolver {
   ensureModelLoaded(documentType: string): Promise<void>;
   private loadRegisterAndBroadcast;
   private notifyPeersModelLoaded;
-  private broadcastIfPossible;
 }
 /**
  * No-op resolver used when no document model loader is configured.
@@ -3862,38 +4016,6 @@ declare class NullDocumentModelResolver implements IDocumentModelResolver {
  */
 type WorkerFactory = (index: number) => IExecutorWorker;
 //#endregion
-//#region src/cache/write-cache-types.d.ts
-/**
- * Configuration options for the write cache
- */
-type WriteCacheConfig = {
-  /** Maximum number of document streams to cache (LRU eviction). Default: 1000 */maxDocuments: number; /** Number of snapshots to keep in each document's ring buffer. Default: 10 */
-  ringBufferSize: number; /** Persist a keyframe snapshot every N revisions. Default: 10 */
-  keyframeInterval: number;
-};
-/**
- * Unique identifier for a document stream
- */
-type DocumentStreamKey = {
-  /** Document identifier */documentId: string; /** Operation scope */
-  scope: string; /** Branch name */
-  branch: string;
-};
-/**
- * A cached document snapshot at a specific revision
- */
-type CachedSnapshot = {
-  /** The revision number of this snapshot */revision: number; /** The document state at this revision */
-  document: PHDocument;
-};
-/**
- * Serialized keyframe snapshot for K/V store persistence
- */
-type KeyframeSnapshot = {
-  /** The revision number of this keyframe */revision: number; /** Serialized document state */
-  document: string;
-};
-//#endregion
 //#region src/projection/protocol.d.ts
 /**
  * Identifier for a built-in read model the projection worker materializes
@@ -4144,6 +4266,7 @@ declare class SyncBuilder {
  * them (`BaseReadModel` subclasses, in particular).
  */
 interface ReadModelFactoryDeps {
+  documentModelRegistry: IDocumentModelRegistry;
   operationIndex: IOperationIndex;
   writeCache: IWriteCache;
   processorManagerConsistencyTracker: IConsistencyTracker;
@@ -4153,16 +4276,28 @@ interface ReadModelFactoryDeps {
  * dependencies once they are available. Awaited during `buildModule()`.
  */
 type ReadModelFactory = (deps: ReadModelFactoryDeps) => IReadModel | Promise<IReadModel>;
+type WorkerPoolBase = {
+  /** Number of worker threads to spawn; also the sticky-routing modulus. */numWorkers: number;
+  /**
+   * Factory spec the default transport's workers import to instantiate
+   * their signature verifier. Omitted = no executor-side verification,
+   * parity with the in-process executor's default.
+   */
+  verifier?: SignatureVerifierSpec;
+};
 /**
- * Describes a document-model package the worker should import at runtime.
- * Either a bare-specifier package or an absolute file path.
+ * Executor worker-pool configuration. Either `db` (default thread
+ * transport; each worker opens its own Postgres pool) or a custom
+ * `factory` transport is required by construction — an enabled pool
+ * without connection info is unrepresentable.
  */
-type DocumentModelSpecInput = {
-  packageName: string;
-  version: string;
-} | {
-  filePath: string;
-};
+type WorkerPoolOptions = (WorkerPoolBase & {
+  db: DbConfig;
+  factory?: WorkerFactory;
+}) | (WorkerPoolBase & {
+  db?: DbConfig;
+  factory: WorkerFactory;
+});
 /**
  * Caller-facing config for {@link ReactorBuilder.withProjectionShards}.
  * When set, the builder replaces the in-process
@@ -4177,6 +4312,12 @@ type ProjectionShardBuilderConfig = {
   shardCount: number;
   preReadyKinds: BuiltInReadModelKind[];
   postReadyKinds: BuiltInReadModelKind[];
+  /**
+   * Connection info for the projection workers' own pools. Falls back to
+   * the executor worker pool's `db` when {@link ReactorBuilder.withWorkerPool}
+   * is configured with one.
+   */
+  db?: DbConfig;
   poolSize?: number;
   initTimeoutMs?: number;
   shutdownGraceMs?: number;
@@ -4185,7 +4326,7 @@ type ProjectionShardBuilderConfig = {
 };
 declare class ReactorBuilder {
   private logger?;
-  private documentModels;
+  private documentModelSources;
   private upgradeManifests;
   private features;
   private readModels;
@@ -4206,17 +4347,20 @@ declare class ReactorBuilder {
   private documentModelLoader?;
   private shutdownHooks;
   private driveContainerTypes;
-  private documentModelSpecs;
-  private workerPoolConfig?;
+  private workerPool?;
   private resolvedModelManifest?;
-  private workerDbConfig?;
-  private workerSignatureVerifierSpec?;
-  private workerFactory?;
   private projectionShardConfig?;
   private projectionWorkerFactory?;
   private instrumentedPools;
   withLogger(logger: ILogger): this;
-  withDocumentModels(models: DocumentModelModule<any>[]): this;
+  /**
+   * Register document-model sources: live modules, importable files, or
+   * importable packages. Appends across calls. At `buildModule()` every
+   * source is resolved host-side and registered on the registry; file and
+   * package sources additionally form the worker manifest when the worker
+   * pool is enabled (live modules cannot cross a thread boundary).
+   */
+  withDocumentModelSources(sources: DocumentModelSource[]): this;
   withUpgradeManifests(manifests: UpgradeManifest<readonly number[]>[]): this;
   withFeatures(features: ReactorFeatures): this;
   withReadModel(readModel: IReadModel): this;
@@ -4260,43 +4404,27 @@ declare class ReactorBuilder {
    * shutdown chain.
    */
   withShutdownHook(hook: () => Promise<void>): this;
-  withDocumentModelSpecs(specs: DocumentModelSpecInput[]): this;
   /**
-   * Stores the worker-pool configuration. When `config.enabled === true` the
-   * builder constructs a {@link WorkerPoolJobExecutorManager} in place of the
-   * in-process {@link SimpleJobExecutorManager}.
+   * Enable the executor worker pool: N `node:worker_threads` workers with
+   * sticky per-document routing, replacing the in-process executor. Calling
+   * this enables the pool — there is no `enabled` flag. Provide `db`
+   * (each worker opens its own Postgres pool; the parent database is built
+   * from it too unless {@link withKysely} is set) or a custom `factory`
+   * transport. `verifier` is imported by the default transport's workers;
+   * omitted = no executor-side signature verification.
    */
-  withWorkerPool(config: WorkerPoolConfig): this;
-  /**
-   * Postgres connection info forwarded to each worker so it can open its own
-   * pool. Required when `workerPool.enabled === true` unless a custom
-   * `withWorkerFactory` or `withExecutor` is provided.
-   */
-  withWorkerDbConfig(db: DbConfig): this;
-  /**
-   * Factory spec the worker imports to instantiate its signature verifier.
-   * Required when `workerPool.enabled === true` unless a custom
-   * `withWorkerFactory` or `withExecutor` is provided.
-   */
-  withWorkerSignatureVerifierSpec(spec: SignatureVerifierSpec): this;
-  /**
-   * Inject a custom {@link WorkerFactory}. When set, the builder skips
-   * default thread-transport wiring and hands the factory directly to the
-   * pool manager. Use this in tests or to plug in a different transport
-   * (e.g. a child-process adapter).
-   */
-  withWorkerFactory(factory: WorkerFactory): this;
+  withWorkerPool(options: WorkerPoolOptions): this;
   /**
    * Configure N sharded projection workers. When set, the builder replaces
    * the default in-process {@link ReadModelCoordinator} with a
-   * {@link ProjectionShardManager}. The same `DbConfig` registered via
-   * {@link withWorkerDbConfig} is reused for the projection workers'
-   * connection info; only the `poolSize` is overridden by
-   * {@link ProjectionShardBuilderConfig.poolSize}.
+   * {@link ProjectionShardManager}.
    *
-   * Requires {@link withWorkerDbConfig} (the projection workers need
-   * connection info to open their own pools). The same model manifest
-   * resolved from {@link withDocumentModelSpecs} is forwarded.
+   * Projection workers open their own Postgres pools from `config.db`,
+   * falling back to the executor worker pool's `db` when
+   * {@link withWorkerPool} is configured with one; only the `poolSize` is
+   * overridden by {@link ProjectionShardBuilderConfig.poolSize}. The same
+   * model manifest resolved from {@link withDocumentModelSources} is
+   * forwarded.
    */
   withProjectionShards(config: ProjectionShardBuilderConfig): this;
   /**
@@ -4308,6 +4436,14 @@ declare class ReactorBuilder {
   getResolvedModelManifest(): ModelManifestEntry[] | undefined;
   build(): Promise<IReactor>;
   buildModule(): Promise<InProcessReactorModule>;
+  /**
+   * The single Postgres config for the parent, executor workers, and
+   * projection shards. They must share one physical database (the parent
+   * writes operations; workers and shards read them), so divergent
+   * worker/shard targets throw. `withKysely` overrides the parent and is not
+   * validated against a worker/shard `db`.
+   */
+  private resolveReactorDbConfig;
   /**
    * Constructs a {@link ProjectionShardManager} bound to the host event
    * bus. Builds the default thread-transport factory unless one was
@@ -4318,9 +4454,9 @@ declare class ReactorBuilder {
   private createProjectionShardManager;
   private createDefaultProjectionWorkerFactory;
   /**
-   * Default {@link WorkerFactory} used when `workerPool.enabled` is set and
-   * the caller did not inject `withWorkerFactory`. Each worker spawns a real
-   * `node:worker_threads` Worker pointing at the compiled `worker/entry.js`.
+   * Default {@link WorkerFactory} used when the pool options carry no
+   * custom `factory`. Each worker spawns a real `node:worker_threads`
+   * Worker pointing at the compiled `worker/entry.js`.
    */
   private createDefaultWorkerFactory;
   /**
@@ -4596,7 +4732,7 @@ declare class InMemoryQueue implements IQueue {
   completeJob(jobId: string): Promise<void>;
   failJob(jobId: string, error?: ErrorInfo$1): Promise<void>;
   deferJob(jobId: string): void;
-  retryJob(jobId: string, error?: ErrorInfo$1): Promise<void>;
+  retryJob(jobId: string, error?: ErrorInfo$1, accounting?: RetryAccounting): Promise<void>;
   /**
    * Check if the queue is drained and call the callback if it is
    */
@@ -4899,6 +5035,8 @@ declare class KyselyWriteCache implements IWriteCache {
   /**
    * Retrieves document state at a specific revision from cache or rebuilds it.
    *
+   * Note: this returns a _shallow_ copy of the document.
+   *
    * Cache hit path: Returns cached snapshot if available (O(1))
    * Warm miss path: Rebuilds from cached base revision + incremental ops
    * Cold miss path: Rebuilds from keyframe or from scratch using all operations
@@ -4936,7 +5074,8 @@ declare class KyselyWriteCache implements IWriteCache {
    * @param document - The document to cache
    * @throws {Error} If document serialization fails
    */
-  putState(documentId: string, scope: string, branch: string, revision: number, document: PHDocument): void;
+  putState(documentId: string, scope: string, branch: string, revision: number, document: PHDocument, position: SnapshotPosition): void;
+  private store;
   /**
    * Invalidates cached document streams.
    *
@@ -4965,6 +5104,13 @@ declare class KyselyWriteCache implements IWriteCache {
   getStream(documentId: string, scope: string, branch: string): DocumentStream | undefined;
   private findNearestKeyframe;
   private coldMissRebuild;
+  /**
+   * Copies the current document revisions onto the document. Overwrites the
+   * requested scope revision with the target revision, if provided.
+   */
+  private stampRevisions;
+  /** The stored operation at `index`, or undefined if it is no longer there. */
+  private operationAt;
   /**
    * Resolves which module version to use for a given operation in phase 2.
    *
@@ -4988,9 +5134,23 @@ declare class KyselyOperationStore implements IOperationStore {
   constructor(db: Kysely<Database$1>);
   private get queryExecutor();
   withTransaction(trx: Transaction<Database$1>): KyselyOperationStore;
-  apply(documentId: string, documentType: string, scope: string, branch: string, revision: number, fn: (txn: AtomicTxn) => void | Promise<void>, signal?: AbortSignal): Promise<Operation[]>;
+  apply(documentId: string, documentType: string, scope: string, branch: string, revision: number, fn: (txn: AtomicTxn) => void | Promise<void>, signal?: AbortSignal, condition?: AppendCondition): Promise<Operation[]>;
   private resolveUniqueConstraint;
   private executeApply;
+  /**
+   * Locks the written stream and every read-set stream, in sorted key order
+   * so that overlapping concurrent appends serialize rather than deadlock.
+   * The locks are still taken one row at a time, so the query preserves that
+   * order. It must stay separate from the guarded insert, which would
+   * otherwise read a snapshot taken before the locks were held.
+   */
+  private acquireStreamLocks;
+  /**
+   * Inserts the staged operations with the condition compiled in as a WHERE
+   * NOT EXISTS guard, making the check and the append one statement. Returns
+   * the rows inserted; zero means the guard failed and nothing was written.
+   */
+  private insertGuarded;
   private findIdempotentReplay;
   getSince(documentId: string, scope: string, branch: string, revision: number, filter?: OperationFilter, paging?: PagingOptions, signal?: AbortSignal): Promise<PagedResults<Operation>>;
   getSinceId(id: number, paging?: PagingOptions, signal?: AbortSignal): Promise<PagedResults<OperationWithContext$1>>;
@@ -5048,6 +5208,7 @@ declare class SimpleJobExecutor implements IJobExecutor {
   private collectionMembershipCache;
   private driveContainerTypes;
   private config;
+  private featureFlags;
   private signatureVerifierModule;
   private documentActionHandler;
   private executionScope;
@@ -5060,6 +5221,13 @@ declare class SimpleJobExecutor implements IJobExecutor {
   private getCollectionMembershipsForOperations;
   private processActions;
   private executeRegularAction;
+  /**
+   * If an operation happened that could change a decision model verdict, we
+   * need to re-evaluate across the streams that could be affected. Previously
+   * approved operations may need to be denied, which will apply new denied
+   * operations with appropriate skip.
+   */
+  private reevaluateReadingScopes;
   private executeLoadJob;
   private accumulateResultOrReturnError;
 }
@@ -5128,6 +5296,61 @@ declare class DocumentModelRegistry implements IDocumentModelRegistry {
   getUpgradeReducer(documentType: string, fromVersion: number, toVersion: number): UpgradeReducer<any, any>;
 }
 //#endregion
+//#region src/decision/types.d.ts
+/** One operation stream. */
+type StreamQuery = {
+  documentId: string;
+  branch: string;
+  scope: string;
+};
+/** The document and branch a decision model is built for. */
+type DecisionTarget = {
+  documentId: string;
+  branch: string;
+};
+/** The executing scope's own state, for conditions that read it. */
+type DecisionContext = {
+  scopeState: unknown;
+};
+/**
+ * A named stream whose value in the model is that scope's state from the
+ * document rebuild the reactor already performs. A derived query may read
+ * only statically-queried projections, so composition is one layer deep.
+ */
+type Projection<M> = {
+  query: StreamQuery | ((model: Partial<M>) => StreamQuery[]);
+  /**
+   * Action types in this stream that can change a verdict. Reads of the stream
+   * are filtered to these, so anything left out is invisible to a decision.
+   */
+  decidingActions: string[]; /** Applies one of this stream's operations while deciding. */
+  apply: (document: PHDocument, operation: Operation) => PHDocument;
+};
+/** Projections plus a decision function over the built model. */
+type DecisionModel<M> = {
+  projections: { [K in keyof M]: Projection<M> };
+  /**
+   * Whether or not this model decides about operations in a given scope. That
+   * is, a scope it reads is not necessarily one it judges, and vise-versa.
+   */
+  judgesScope(scope: string): boolean;
+  decide(model: M, subject: AuthSubject, request: AuthRequest, ctx: DecisionContext): AuthDecision;
+};
+/** A built model plus the read-set condition recording what the build read. */
+type BuiltDecisionModel<M> = {
+  model: M;
+  appendCondition: AppendCondition;
+};
+//#endregion
+//#region src/decision/build-decision-model.d.ts
+/**
+ * Reads each projection's stream through the write cache, recording the
+ * revision observed. Static projections resolve first; derived projections
+ * see only those and contribute a map from document id to state. Each
+ * distinct stream is read once and yields one append condition entry.
+ */
+declare function buildDecisionModel<M>(cache: IWriteCache, definition: (target: DecisionTarget) => DecisionModel<M>, target: DecisionTarget, signal?: AbortSignal): Promise<BuiltDecisionModel<M>>;
+//#endregion
 //#region src/read-models/base-read-model.d.ts
 type BaseReadModelConfig = {
   readModelId: string;
@@ -5212,7 +5435,7 @@ declare class KyselyDocumentIndexer extends BaseReadModel implements IDocumentIn
  * serialized so the executor can return to dispatch without holding ordering
  * implicitly.
  */
-declare class ReadModelCoordinator implements IReadModelCoordinator {
+declare class ReadModelCoordinator implements ILiveReadModelCoordinator {
   private eventBus;
   readonly preReady: IReadModel[];
   readonly postReady: IReadModel[];
@@ -5231,6 +5454,7 @@ declare class ReadModelCoordinator implements IReadModelCoordinator {
    */
   drain(): Promise<void>;
   getChainDepth(): number;
+  addReadModel(readModel: IReadModel, stage: ReadModelRegistrationStage): void;
   private handleWriteReady;
   private emitEmptyReadReady;
   private runChain;
@@ -5676,5 +5900,5 @@ declare class ProcessorManager extends BaseReadModel implements IProcessorManage
   private deleteProcessorCursors;
 }
 //#endregion
-export { type AbortMessage, type AtomicTxn, type AttachmentHash, type AttachmentRef, BaseReadModel, type BatchExecutionRequest, type BatchExecutionResult, type BatchLoadRequest, type BatchLoadResult, type BuiltInReadModelKind, type CachedSnapshot, type ChannelConfig, ChannelError, ChannelErrorSource, type ChannelHealth, type ChannelMeta, ChannelScheme, type ConnectionState, type ConnectionStateChangeCallback, type ConnectionStateChangedEvent, type ConnectionStateSnapshot, type ConsistencyCoordinate, type ConsistencyKey, type ConsistencyToken, ConsistencyTracker, DEFAULT_DRIVE_CONTAINER_TYPES, DRIVE_AUTH_ERROR_MESSAGES, type Database, type DbConfig, type DeadLetterAddedEvent, DefaultSubscriptionErrorHandler, type DocumentChangeEvent, DocumentChangeType, type DocumentGraphEdge, type DocumentIndexerDatabase, DocumentIntegrityService, DocumentModelRegistry, DocumentModelResolver, type DocumentModelSpec, type DocumentModelSpecInput, type DocumentRelationship, type DocumentRevisions, type DocumentStreamKey, type DocumentViewDatabase, DriveClient, DriveCollectionId, DuplicateManifestError, DuplicateModuleError, DuplicateOperationError, EventBus, EventBusAggregateError, type ExecuteMessage, type ExecutionJobPlan, type ExecutorStartedEvent, type ExecutorStoppedEvent, type FactorySpec, type GqlChannelConfig, GqlRequestChannel, GqlRequestChannelFactory, GqlResponseChannel, GqlResponseChannelFactory, type HeartbeatMessage, type IChannel, type IChannelFactory, type IConsistencyTracker, type IDocumentGraph, type IDocumentIndexer, type IDocumentIntegrityService, type IDocumentModelLoader, type IDocumentModelRegistry, type IDocumentModelResolver, type IDocumentView, type IDriveClient, type IEventBus, type IJobAwaiter, type IJobExecutor, type IJobExecutorManager, type IJobTracker, type IKeyframeStore, type IMailbox, type IOperationIndex, type IOperationStore, type IPollTimer, type IProcessor, type IProcessorHostModule, type IProcessorManager, type IProjectionTransport, type IQueue, type IReactor, type IReactorClient, type IReactorSubscriptionManager, type IReadModel, type IReadModelCoordinator, type IRelationalDb, type ISubscriptionErrorHandler, type ISyncCursorStorage, type ISyncManager, type ISyncRemoteStorage, type ISyncStatusTracker, type IWriteCache, SimpleJobExecutor as InMemoryJobExecutor, SimpleJobExecutor, InMemoryJobTracker, InMemoryQueue, type InProcessReactorClientModule, type InProcessReactorModule, type InProcessSyncModule, type InitMessage, type InsertableDocumentSnapshot, IntervalPollTimer, InvalidModuleError, type Job, type JobAvailableEvent, JobAwaiter, type JobCompletedEvent, type JobExecutorConfig, JobExecutorEventTypes, type JobExecutorFactory, type JobFailedEvent, type JobInfo, type JobPendingEvent, type JobReadReadyEvent, type JobResult, type JobRunningEvent, type JobStartedEvent, JobStatus, type JobWriteReadyEvent, type JobWriteReadyPayload, type JwtHandler, type KeyframeSnapshot, type KeyframeValidationIssue, KyselyDocumentIndexer, KyselyDocumentView, KyselyKeyframeStore, KyselyOperationStore, KyselySyncCursorStorage, KyselySyncRemoteStorage, KyselyWriteCache, type LoadJobPlan, type LoadModelMessage, type LogMessage, Mailbox, type MetricsMessage, type ModelLoadFailedMessage, type ModelLoadedEvent, type ModelLoadedMessage, type ModelManifestEntry, ModuleNotFoundError, type ModuleRef, NullDocumentModelResolver, type OperationBatch, type OperationContext, type OperationFilter, type OperationIndexEntry, type OperationTable, type OperationWithContext, OptimisticLockError, type PagedResults, type PagingOptions, type ParentMessage, type ParsedDriveUrl, type ParsedPaging, PollBehavior, PollingChannelError, type PoolInstrumentation, type PoolStats, type ProcessorApp, type ProcessorFactory, type ProcessorFactoryBuilder, type ProcessorFilter, ProcessorManager, type ProcessorRecord, type ProcessorStatus, type ProjectionShardBuilderConfig, type ProjectionShardManagerConfig, type ProjectionWorkerFactory, PropagationMode, QueueEventTypes, REACTOR_SCHEMA, Reactor, ReactorBuilder, ReactorClient, ReactorClientBuilder, type ReactorClientModule, ReactorEventTypes, type ReactorFeatures, type JobFailedEvent$1 as ReactorJobFailedEvent, type ReactorModule, ReactorSubscriptionManager, type ReadModelBatchCompletedEvent, ReadModelCoordinator, type ReadModelFactory, type ReadModelFactoryDeps, type ReadModelIndexedEvent, type ReadModelIndexingStage, type ReadModelStage, type ReadyMessage, type RebuildResult, RelationalDbProcessor, RelationshipChangeType, type Remote, type RemoteCursor, type RemoteFilter, type RemoteMeta, type RemoteOptions, type RemoteRecord, type RemoteStatus, type ResultMessage, RevisionMismatchError, type SanitizedArg, type SearchFilter, type ShutdownMessage, type ShutdownStatus, type SignatureVerificationHandler, type SignatureVerifierSpec, type SignerConfig, SimpleJobExecutorManager, type SnapshotValidationIssue, type Database$1 as StorageDatabase, type SubscriptionErrorContext, SyncBuilder, type SyncEnvelope, type SyncEnvelopeType, SyncEventTypes, type SyncFailedEvent, type SyncModule, SyncOperation, SyncOperationAggregateError, type SyncOperationErrorType, SyncOperationStatus, type SyncPendingEvent, SyncStatus, type SyncStatusChangeCallback, SyncStatusTracker, type SyncSucceededEvent, type TrackedProcessor, type Unsubscribe, type ValidationResult, type ViewFilter, type ErrorInfo as WorkerErrorInfo, type WorkerMessage, type WorkerPoolConfig, type WriteCacheConfig, addRelationshipAction, batchOperationsByDocument, consolidateSyncOperations, createDocumentAction, createForwardingLogger, createMutableShutdownStatus, createRelationalDb, deleteDocumentAction, documentActions, driveIdFromUrl, envelopesToSyncOperations, errorToInfo, getMigrationStatus, instrumentPgPool, isDriveAuthError, makeConsistencyKey, parseDriveUrl, parsePagingOptions, removeRelationshipAction, runMigrations, sanitizeArg, trimMailboxFromAckOrdinal, updateRelationshipAction, upgradeDocumentAction, workerEntryPath };
+export { APPEND_CONDITION_FAILED_PREFIX, type AbortMessage, type AppendCondition, AppendConditionFailedError, type AppendConditionStream, type AtomicTxn, type AttachmentHash, type AttachmentRef, BaseReadModel, type BatchExecutionRequest, type BatchExecutionResult, type BatchLoadRequest, type BatchLoadResult, type BuiltDecisionModel, type BuiltInReadModelKind, type CachedSnapshot, type ChannelConfig, ChannelError, ChannelErrorSource, type ChannelHealth, type ChannelMeta, ChannelScheme, type ConnectionState, type ConnectionStateChangeCallback, type ConnectionStateChangedEvent, type ConnectionStateSnapshot, type ConsistencyCoordinate, type ConsistencyKey, type ConsistencyToken, ConsistencyTracker, DEFAULT_DRIVE_CONTAINER_TYPES, DRIVE_AUTH_ERROR_MESSAGES, type Database, type DbConfig, type DeadLetterAddedEvent, type DecisionContext, type DecisionModel, type DecisionTarget, DefaultSubscriptionErrorHandler, type DocumentChangeEvent, DocumentChangeType, type DocumentGraphEdge, type DocumentIndexerDatabase, DocumentIntegrityService, DocumentModelRegistry, DocumentModelResolver, type DocumentModelSource, type DocumentModelSpec, type DocumentRelationship, type DocumentRevisions, type DocumentStreamKey, type DocumentViewDatabase, DriveClient, DriveCollectionId, DuplicateManifestError, DuplicateModuleError, DuplicateOperationError, EventBus, EventBusAggregateError, type ExecuteMessage, type ExecutionJobPlan, type ExecutorStartedEvent, type ExecutorStoppedEvent, type FactorySpec, type FileModelSource, type GqlChannelConfig, GqlRequestChannel, GqlRequestChannelFactory, GqlResponseChannel, GqlResponseChannelFactory, type HeartbeatMessage, type IChannel, type IChannelFactory, type IConsistencyTracker, type IDocumentGraph, type IDocumentIndexer, type IDocumentIntegrityService, type IDocumentModelLoader, type IDocumentModelRegistry, type IDocumentModelResolver, type IDocumentView, type IDriveClient, type IEventBus, type IJobAwaiter, type IJobExecutor, type IJobExecutorManager, type IJobTracker, type IKeyframeStore, type ILiveReadModelCoordinator, type IMailbox, type IOperationIndex, type IOperationStore, type IPollTimer, type IProcessor, type IProcessorHostModule, type IProcessorManager, type IProjectionTransport, type IQueue, type IReactor, type IReactorClient, type IReactorSubscriptionManager, type IReadModel, type IReadModelCoordinator, type IRelationalDb, type ISubscriptionErrorHandler, type ISyncCursorStorage, type ISyncManager, type ISyncRemoteStorage, type ISyncStatusTracker, type IWriteCache, SimpleJobExecutor as InMemoryJobExecutor, SimpleJobExecutor, InMemoryJobTracker, InMemoryQueue, type InProcessReactorClientModule, type InProcessReactorModule, type InProcessSyncModule, type InitMessage, type InsertableDocumentSnapshot, IntervalPollTimer, InvalidModuleError, type Job, type JobAvailableEvent, JobAwaiter, type JobCompletedEvent, type JobExecutorConfig, JobExecutorEventTypes, type JobExecutorFactory, type JobFailedEvent, type JobInfo, type JobPendingEvent, type JobReadReadyEvent, type JobResult, type JobRunningEvent, type JobStartedEvent, JobStatus, type JobWriteReadyEvent, type JobWriteReadyPayload, type JwtHandler, type KeyframeSnapshot, type KeyframeValidationIssue, KyselyDocumentIndexer, KyselyDocumentView, KyselyKeyframeStore, KyselyOperationStore, KyselySyncCursorStorage, KyselySyncRemoteStorage, KyselyWriteCache, type LoadJobPlan, type LoadModelMessage, type LogMessage, Mailbox, type MetricsMessage, type ModelLoadFailedMessage, type ModelLoadedEvent, type ModelLoadedMessage, type ModelManifestEntry, ModuleNotFoundError, type ModuleRef, NullDocumentModelResolver, type OperationBatch, type OperationContext, type OperationFilter, type OperationIndexEntry, type OperationTable, type OperationWithContext, OptimisticLockError, type PackageModelSource, type PagedResults, type PagingOptions, type ParentMessage, type ParsedDriveUrl, type ParsedPaging, PollBehavior, PollingChannelError, type PoolInstrumentation, type PoolStats, type ProcessorApp, type ProcessorFactory, type ProcessorFactoryBuilder, type ProcessorFilter, ProcessorManager, type ProcessorRecord, type ProcessorStatus, type Projection, type ProjectionShardBuilderConfig, type ProjectionShardManagerConfig, type ProjectionWorkerFactory, PropagationMode, QueueEventTypes, REACTOR_SCHEMA, Reactor, ReactorBuilder, ReactorClient, ReactorClientBuilder, type ReactorClientModule, ReactorEventTypes, type ReactorFeatures, type JobFailedEvent$1 as ReactorJobFailedEvent, type ReactorModule, ReactorSubscriptionManager, type ReadModelBatchCompletedEvent, ReadModelCoordinator, type ReadModelFactory, type ReadModelFactoryDeps, type ReadModelIndexedEvent, type ReadModelIndexingStage, type ReadModelRegistrationStage, type ReadModelStage, type ReadyMessage, type RebuildResult, RelationalDbProcessor, RelationshipChangeType, type Remote, type RemoteCursor, type RemoteFilter, type RemoteMeta, type RemoteOptions, type RemoteRecord, type RemoteStatus, type ResultMessage, RetryAccounting, RevisionMismatchError, type SanitizedArg, type SearchFilter, type ShutdownMessage, type ShutdownStatus, type SignatureVerificationHandler, type SignatureVerifierSpec, type SignerConfig, SimpleJobExecutorManager, type SnapshotValidationIssue, type Database$1 as StorageDatabase, type StreamQuery, type SubscriptionErrorContext, SyncBuilder, type SyncEnvelope, type SyncEnvelopeType, SyncEventTypes, type SyncFailedEvent, type SyncModule, SyncOperation, SyncOperationAggregateError, type SyncOperationErrorType, SyncOperationStatus, type SyncPendingEvent, SyncStatus, type SyncStatusChangeCallback, SyncStatusTracker, type SyncSucceededEvent, type TrackedProcessor, type Unsubscribe, type ValidationResult, type ViewFilter, type ErrorInfo as WorkerErrorInfo, type WorkerMessage, type WorkerPoolConfig, type WorkerPoolOptions, type WriteCacheConfig, addRelationshipAction, batchOperationsByDocument, buildDecisionModel, consolidateSyncOperations, createDocumentAction, createForwardingLogger, createMutableShutdownStatus, createRelationalDb, deleteDocumentAction, documentActions, driveIdFromUrl, envelopesToSyncOperations, errorToInfo, getMigrationStatus, instrumentPgPool, isDriveAuthError, makeConsistencyKey, parseDriveUrl, parsePagingOptions, removeRelationshipAction, runMigrations, sanitizeArg, supportsLiveReadModelRegistration, trimMailboxFromAckOrdinal, updateRelationshipAction, upgradeDocumentAction, workerEntryPath };
 //# sourceMappingURL=index.d.ts.map