@powerhousedao/reactor 6.2.2-dev.42 → 6.2.2-dev.44

package/dist/entry.js

@@ -1,6 +1,6 @@
-import { o as instrumentPgPool } from "./drive-container-types-BJCKXJwH.js";
+import { o as instrumentPgPool } from "./drive-container-types-h3M1AK3K.js";
 import { n as errorToInfo, t as createForwardingLogger } from "./forwarding-logger-BBkMSxuJ.js";
-import { n as defaultLoadFactory, t as buildWorkerExecutor } from "./build-worker-executor-CAEZD_yJ.js";
+import { n as defaultLoadFactory, t as buildWorkerExecutor } from "./build-worker-executor-CHkkh55C.js";
 import { ConsoleLogger } from "document-model";
 import { isMainThread, parentPort } from "node:worker_threads";
 //#region src/executor/worker/run-worker.ts

package/dist/index.d.ts

@@ -57,7 +57,14 @@ declare function updateRelationshipAction(sourceId: string, targetId: string, re
 declare function removeRelationshipAction(sourceId: string, targetId: string, relationshipType?: string): Action;
 //#endregion
 //#region src/queue/types.d.ts
-type JobKind = "mutation" | "load";
+/**
+ * What a job carries: a mutation applies actions, a load imports synced
+ * operations, and a reevaluation re-judges a document's stored operations
+ * because a read-set stream elsewhere (a group document) changed. A
+ * reevaluation job carries no actions or operations; its work is derived
+ * from what is already stored.
+ */
+type JobKind = "mutation" | "load" | "reevaluation";
 /**
  * State of a job in the queue
  */
@@ -1189,6 +1196,15 @@ interface IOperationIndexTxn {
   createCollection(collectionId: string): void;
   addToCollection(collectionId: string, documentId: string): void;
   removeFromCollection(collectionId: string, documentId: string): void;
+  /**
+   * Records the group documents an auth operation's input names, tied to the
+   * last written operation like addToCollection. At commit each reference is
+   * remembered permanently and the group joins every collection the
+   * referencing document belongs to, keeping the earliest join and reopening
+   * a closed membership, so sync serves the group's history to every remote
+   * that can observe the referencing grant.
+   */
+  recordGroupReferences(documentId: string, groupIds: string[]): void;
   write(operations: OperationIndexEntry[]): void;
 }
 /**
@@ -1210,6 +1226,13 @@ interface IOperationIndex {
    * Returns a map of documentId to array of collection IDs.
    */
   getCollectionsForDocuments(documentIds: string[]): Promise<Record<string, string[]>>;
+  /**
+   * The documents whose auth history has ever referenced the group, from the
+   * group-reference relation. This is the set a group-stream change owes a
+   * re-evaluation pass to; it is complete because a group's auth scope cannot
+   * reference other groups.
+   */
+  getGroupReferencers(groupId: string, signal?: AbortSignal): Promise<string[]>;
 }
 /**
  * Identifies the collection a remote synchronizes. Collections are drive-level
@@ -1667,6 +1690,17 @@ type CreateDocumentOptions = {
   /** Optional "id" or "slug" of parent document */parentIdentifier?: string; /** Optional version of the document model to use (defaults to latest) */
   documentModelVersion?: number;
 };
+/**
+ * Options for upgrading a document.
+ */
+type UpgradeDocumentOptions = {
+  /**
+   * How many times to retry with a fresh read when the executor rejects the
+   * upgrade because the document changed after it was read. Defaults to
+   * {@link DEFAULT_UPGRADE_CONFLICT_RETRIES}.
+   */
+  maxConflictRetries?: number;
+};
 /**
  * Drive-aware operations grouped under `client.drives`.
  *
@@ -1843,6 +1877,38 @@ interface IReactorClient {
    * @param signal - Optional abort signal to cancel the request
    */
   createEmpty<TDocument extends PHDocument>(documentModelType: string, options?: CreateDocumentOptions, signal?: AbortSignal): Promise<TDocument>;
+  /**
+   * Retrieves the document model module matching the version a document is
+   * stamped with. Use this instead of {@link getDocumentModelModule}
+   * whenever a specific document is in hand: the latest-wins lookup feeds
+   * not-yet-upgraded documents the wrong reducer, diverging from replay.
+   *
+   * @param document - The document whose stamped version selects the module
+   * @returns The document model module registered for that version
+   * @throws UnsupportedDocumentModelVersionError if no module is registered for the stamped version
+   */
+  getDocumentModelModuleForDocument(document: PHDocument): Promise<DocumentModelModule<any>>;
+  /**
+   * Upgrades a document to a newer document model version by dispatching an
+   * UPGRADE_DOCUMENT action. When toVersion is omitted, upgrades to the
+   * latest registered module version for the document's type. Returns the
+   * document unchanged when it is already at the target version.
+   *
+   * The action carries a snapshot of the document's version and per-scope
+   * revisions, which the executor validates before persisting. When an edit
+   * lands between the read and the upgrade executing, the upgrade is
+   * rejected and retried with a fresh read up to
+   * {@link UpgradeDocumentOptions.maxConflictRetries} times before the
+   * conflict is surfaced.
+   *
+   * @param documentIdentifier - Target document id or slug
+   * @param toVersion - Optional target document model version; defaults to latest
+   * @param options - Optional upgrade options (maxConflictRetries)
+   * @param signal - Optional abort signal to cancel the request
+   * @returns The upgraded document
+   * @throws DowngradeNotSupportedError if toVersion is less than the document's current version
+   */
+  upgradeDocument<TDocument extends PHDocument = PHDocument>(documentIdentifier: string, toVersion?: number, options?: UpgradeDocumentOptions, signal?: AbortSignal): Promise<TDocument>;
   /**
    * Creates an empty document in a drive as a single batched operation.
    * This is more efficient than createEmpty + addFile as it batches all
@@ -2032,6 +2098,12 @@ declare class ReactorClient implements IReactorClient {
    * @returns The document model module
    */
   getDocumentModelModule(documentType: string): Promise<DocumentModelModule<any>>;
+  /**
+   * Retrieves the document model module matching the version the document is
+   * stamped with, so not-yet-upgraded documents get the reducer their
+   * history was written with rather than the latest.
+   */
+  getDocumentModelModuleForDocument(document: PHDocument): Promise<DocumentModelModule<any>>;
   /**
    * Retrieves a specific PHDocument
    */
@@ -2067,6 +2139,18 @@ declare class ReactorClient implements IReactorClient {
    * Creates an empty document and waits for completion
    */
   createEmpty<TDocument extends PHDocument>(documentModelType: string, options?: CreateDocumentOptions, signal?: AbortSignal): Promise<TDocument>;
+  /**
+   * Upgrades a document to a newer document model version by dispatching an
+   * UPGRADE_DOCUMENT action. When toVersion is omitted, upgrades to the
+   * latest registered module version for the document's type. Returns the
+   * document unchanged when it is already at the target version.
+   *
+   * The executor validates the action's version and revision snapshot against
+   * the state the migration actually runs on. When a concurrent edit
+   * invalidates the snapshot, the upgrade is rebuilt from a fresh read and
+   * retried up to maxConflictRetries times before the conflict is surfaced.
+   */
+  upgradeDocument<TDocument extends PHDocument = PHDocument>(documentIdentifier: string, toVersion?: number, options?: UpgradeDocumentOptions, signal?: AbortSignal): Promise<TDocument>;
   /**
    * Creates an empty document in a drive as a single batched operation.
    * Delegates to {@link IDriveClient.addFile}.
@@ -2339,11 +2423,20 @@ interface SyncDeadLetterTable {
   error_type: Generated<string>;
   created_at: Generated<Date>;
 }
+/**
+ * One (document, group) reference ever discovered from an auth operation's
+ * input. Rows are never updated or deleted (see migration 017).
+ */
+interface GroupReferenceTable {
+  documentId: string;
+  groupId: string;
+}
 interface Database$1 {
   Operation: OperationTable;
   Keyframe: KeyframeTable;
   document_collections: DocumentCollectionTable;
   operation_index_operations: OperationIndexOperationTable;
+  group_references: GroupReferenceTable;
   sync_remotes: SyncRemoteTable;
   sync_cursors: SyncCursorTable;
   sync_dead_letters: SyncDeadLetterTable;
@@ -3037,7 +3130,40 @@ declare class KyselyWriteCache implements IWriteCache {
    */
   getStream(documentId: string, scope: string, branch: string): DocumentStream | undefined;
   private findNearestKeyframe;
+  /**
+   * Rebuilds a scope from a keyframe or from the whole operation history.
+   *
+   * The document scope is always rebuilt first, because it carries the type,
+   * the upgrades and the deletion marker. Its version-changing upgrades are not
+   * applied there though: an upgrade reducer must see the state the requested
+   * scope has reached at that upgrade's boundary, so each one is held back and
+   * applied when the replay below crosses the boundary that
+   * resolveModuleVersionForOp derives from it. Upgrades whose boundary lies past
+   * the last replayed operation are applied at the end. Creation-time 0->N seed
+   * upgrades carry the initial state, so they still apply immediately.
+   */
   private coldMissRebuild;
+  /**
+   * Applies and removes every held-back upgrade whose target version is at or
+   * below `throughVersion`, in the order the document scope recorded them.
+   */
+  private applyPendingUpgrades;
+  /**
+   * Applies the remaining held-back upgrades after the requested scope's
+   * replay has finished. A head read applies them all. A positional read
+   * applies only those whose boundary for this scope lies at or before the
+   * target position: applying a later one would label migrated state with a
+   * pre-upgrade revision, and a keyframe stored from that poisons every
+   * rebuild that resumes from it. Boundaries come from the upgrade's revision
+   * snapshot; an upgrade without one records no position for this scope, and
+   * the replay loop not having crossed it already places it past the target.
+   */
+  private applyTailPendingUpgrades;
+  /**
+   * Applies one held-back upgrade, then re-applies the deletes the document
+   * scope recorded after it so the hold-back cannot invert their order.
+   */
+  private applyPendingUpgrade;
   /**
    * Copies the current document revisions onto the document. Overwrites the
    * requested scope revision with the target revision, if provided.
@@ -3166,6 +3292,16 @@ type ReactorFeatureFlags = {
    * Requires documentDecisions.
    */
   authEnforcement: boolean;
+  /**
+   * Match { group } principals by folding the referenced PHGroup documents as
+   * derived projections. Requires authEnforcement.
+   */
+  authGroups: boolean;
+  /**
+   * Evaluate `where` clauses and { match } principals against the executing
+   * scope's state, the subject, and the action input. Requires authGroups.
+   */
+  authConditions: boolean;
 };
 /**
  * Configuration options for the job executor
@@ -3509,6 +3645,30 @@ interface IQueue {
   unblock(): void;
 }
 //#endregion
+//#region src/core/group-reevaluation-trigger.d.ts
+/**
+ * Watches committed writes for group membership changes and enqueues a
+ * re-evaluation job for every document whose auth history references the
+ * changed group, found through the reverse direction of the group-reference
+ * relation. Each affected document is re-judged in its own job, so the work
+ * runs under that document's execution slot rather than the group's.
+ *
+ * The job carries the earliest changed membership timestamp; the executor
+ * skips the pass when everything the document holds sorts before it, which
+ * keeps the common case (a membership write later than all history) free.
+ */
+declare class GroupReevaluationTrigger {
+  private logger;
+  private eventBus;
+  private queue;
+  private operationIndex;
+  private unsubscribe?;
+  constructor(logger: ILogger, eventBus: IEventBus, queue: IQueue, operationIndex: IOperationIndex);
+  startup(): void;
+  shutdown(): void;
+  private onWriteReady;
+}
+//#endregion
 //#region src/read-models/types.d.ts
 interface ViewStateTable {
   readModelId: string;
@@ -4295,6 +4455,12 @@ interface InProcessReactorModule extends ReactorModule {
   processorManagerConsistencyTracker: IConsistencyTracker;
   reactor: IReactor;
   syncModule: InProcessSyncModule | undefined;
+  /**
+   * Present when authGroups is on: enqueues re-evaluation jobs for the
+   * documents a group membership change affects. Started by the builder;
+   * hosts shut it down alongside the sync manager.
+   */
+  groupReevaluationTrigger: GroupReevaluationTrigger | undefined;
   /**
    * Instrumented pg.Pool handles registered with the builder, either by
    * createPostgresDatabase or by withInstrumentedPool. Empty when no pg
@@ -5314,6 +5480,13 @@ declare class SimpleJobExecutor implements IJobExecutor {
    * re-appended, carrying a skip that spans the indices it supersedes.
    */
   private reevaluateDocument;
+  /**
+   * Re-judges a document's stored operations because a read-set stream in
+   * another document (a group) gained an operation. The trigger timestamp
+   * bounds the work: an operation later than everything this document holds
+   * cannot change any evaluation, so the pass is skipped.
+   */
+  private executeReevaluationJob;
   private executeLoadJob;
   private accumulateResultOrReturnError;
 }
@@ -5394,9 +5567,20 @@ type DecisionTarget = {
   documentId: string;
   branch: string;
 };
-/** The executing scope's own state, for conditions that read it. */
+/**
+ * What a decision's conditions may read beyond the projections: the executing
+ * scope's own state and the attempted action's input. Populated only while
+ * authConditions is on; otherwise both stay undefined and conditional grants
+ * never apply.
+ */
 type DecisionContext = {
   scopeState: unknown;
+  actionInput?: unknown;
+};
+/** A statically-queried stream's operations, named after its projection. */
+type StreamHistory = {
+  name: string;
+  operations: Operation[];
 };
 /**
  * A named stream whose value in the model is that scope's state from the
@@ -5405,6 +5589,16 @@ type DecisionContext = {
  */
 type Projection<M> = {
   query: StreamQuery | ((model: Partial<M>) => StreamQuery[]);
+  /**
+   * For a derived projection, the streams it may read anywhere in an
+   * evaluated range, derived from the statically-queried streams' operations
+   * (including the operations under evaluation). A positional walk cannot use
+   * `query`, because the folded state it depends on changes over the range;
+   * this over-approximates by design, since a stream referenced at any
+   * position stays readable when the earlier range is re-evaluated even if a
+   * later operation removes the reference. Ignored on static projections.
+   */
+  queryOverHistory?: (reads: StreamHistory[]) => StreamQuery[];
   /**
    * Action types in this stream that can change an evaluation. Reads of the stream
    * are filtered to these, so anything left out is invisible to a decision.
@@ -5425,6 +5619,14 @@ type Evaluation = {
 /** Projections plus a decision function over the built model. */
 type DecisionModel<M> = {
   projections: { [K in keyof M]: Projection<M> };
+  /**
+   * Present when decide reads the executing scope's state through the
+   * decision context. A positional walk then folds the evaluated stream with
+   * this, from its base state through every effective operation, so
+   * conditions read the state as it stood at each operation's position
+   * rather than at the head.
+   */
+  foldEvaluatedScope?: (document: PHDocument, operation: Operation) => PHDocument;
   /**
    * Whether or not this model decides about operations in a given scope. That
    * is, a scope it reads is not necessarily one it evaluates, and vise-versa.
@@ -5480,16 +5682,31 @@ type AdmissionDecision = {
   documentVersion: number;
   deletedAtUtcIso: string | null;
 };
+/**
+ * What decideAtHead resolves a condition context from: the action's input,
+ * with the executing scope's state read at the head. Supplied only while
+ * authConditions is on.
+ */
+type AdmissionConditions = {
+  actionInput?: unknown;
+};
 /**
  * Builds the model at the stream heads and decides one request against it. The
  * append condition it returns is the read-set the store enforces at write time.
+ *
+ * With `conditions` supplied, the executing scope's state is read at the head
+ * for `doc.<scope>.*` paths. That read carries no append-condition entry of
+ * its own: the written stream's expected-revision check already refuses a
+ * write whose scope grew between the read and the append.
  */
-declare function decideAtHead(model: RegisteredDecisionModel, cache: IWriteCache, target: DecisionTarget, subject: AuthSubject, request: AuthRequest, signal?: AbortSignal): Promise<AdmissionDecision>;
+declare function decideAtHead(model: RegisteredDecisionModel, cache: IWriteCache, target: DecisionTarget, subject: AuthSubject, request: AuthRequest, signal?: AbortSignal, conditions?: AdmissionConditions): Promise<AdmissionDecision>;
 /**
  * The model this reactor enforces. With `authEnforcement` off the auth scope is
- * absent from every append condition and no load walks it.
+ * absent from every append condition and no load walks it; with `authGroups`
+ * on, the group documents the grant list names join the read-set and the
+ * registry supplies the reducer that folds them.
  */
-declare function selectDecisionModel(flags: ReactorFeatureFlags): RegisteredDecisionModel;
+declare function selectDecisionModel(flags: ReactorFeatureFlags, registry: IDocumentModelRegistry): RegisteredDecisionModel;
 //#endregion
 //#region src/decision/stream-order.d.ts
 /** Where a stream's stored order contradicts its timestamps. */
@@ -5649,6 +5866,16 @@ declare class KyselyDocumentView extends BaseReadModel implements IDocumentView
    */
 
   servesDeletionBoundary: boolean);
+  /**
+   * Indexes committed operations into DocumentSnapshot rows. CREATE_DOCUMENT
+   * only seeds header/document/auth. UPGRADE_DOCUMENT reindexes every scope
+   * present in resultingState when the operation vouches for them — a seed
+   * carrying initialState or a migration stamped with the __migrated marker
+   * — since the upgrade reducer may have reshaped any of them; upgrades
+   * without either fall back to header/document/auth, because their sibling
+   * echoes may be stale. All other action types index only header and their
+   * own scope.
+   */
   protected commitOperations(items: OperationWithContext$1[]): Promise<void>;
   exists(documentIds: string[], consistencyToken?: ConsistencyToken, signal?: AbortSignal): Promise<boolean[]>;
   get<TDocument extends PHDocument>(documentId: string, view?: ViewFilter$1, consistencyToken?: ConsistencyToken, signal?: AbortSignal): Promise<TDocument>;