payload 4.0.0-internal.fa345ef → 4.0.0-internal.ff27d6e

package/dist/branching/resolveBranch.js

@@ -0,0 +1,398 @@
+import { getDataLoader } from '../collections/dataloader.js';
+import { extractRelationshipID } from '../utilities/extractRelationshipID.js';
+import { isolateObjectProperty } from '../utilities/isolateObjectProperty.js';
+import { branchesCollectionSlug, MAIN_BRANCH } from './types.js';
+const stateKey = '_branchState';
+const getBranchingConfig = (req)=>req?.payload?.config?.branching;
+/**
+ * Resolves the active branch for a request.
+ *
+ * The branch is an argument, exactly like `locale` and `depth`: it is whatever
+ * the caller passed, and `main` when they passed nothing. Nothing is read from
+ * storage here — no preference lookup, no cookie — so an unbranched request
+ * costs nothing beyond this function.
+ *
+ * Where the admin UI's persisted selection turns into that argument is the
+ * admin UI's business (`initAdminContext`), the same division `locale` already uses.
+ *
+ * Precedence, highest first:
+ *   1. explicit Local API argument (`req.branch`, set by the caller)
+ *   2. `branch` query param
+ *   3. `main`
+ */ export const resolveBranch = ({ req })=>{
+    const branching = getBranchingConfig(req);
+    if (!branching?.enabled) {
+        return MAIN_BRANCH;
+    }
+    const context = req.context;
+    const existing = context?.[stateKey];
+    if (existing) {
+        return existing.branch;
+    }
+    // The bypass sentinel `createPayloadRequest` sets for `branch: false`. Honoured here and not
+    // only at the database layer, because a request told to ignore branching must not
+    // report a branch to anything that asks — a `branch: false` request built from an HTTP
+    // request still carries `?branch=` in its query, and falling through to it made the
+    // merge engine resolve against the very branch it was merging.
+    if (context?._branchBypass) {
+        req.branch = MAIN_BRANCH;
+        return MAIN_BRANCH;
+    }
+    const branch = resolveBranchFromRequest(req) ?? MAIN_BRANCH;
+    if (context) {
+        context[stateKey] = {
+            branch,
+            deleted: new Map(),
+            manifest: new Map(),
+            manifestLoaded: false,
+            operations: new Map(),
+            rowIDs: new Map()
+        };
+    }
+    req.branch = branch;
+    return branch;
+};
+/**
+ * The branch the caller asked for, whether through the Local API option or the
+ * `branch` query param — the same two ways `locale` is supplied.
+ */ const resolveBranchFromRequest = (req)=>{
+    if (typeof req.branch === 'string' && req.branch) {
+        return req.branch;
+    }
+    if (typeof req.query?.branch === 'string' && req.query.branch) {
+        return req.query.branch;
+    }
+    return undefined;
+};
+/**
+ * Loads every change the active branch has made, in one query, and groups it
+ * by collection in memory.
+ *
+ * One query per request rather than per collection: a request touching a dozen
+ * collections still issues a single manifest read. Bounded by branch size, not
+ * table size.
+ */ export const loadBranchManifest = async (req)=>{
+    const branch = resolveBranch({
+        req
+    });
+    const context = req.context;
+    const state = context?.[stateKey];
+    if (!state || branch === MAIN_BRANCH) {
+        return new Map();
+    }
+    if (state.manifestLoaded) {
+        await state.manifestPromise;
+        return state.manifest;
+    }
+    // Marked loaded up front so the manifest read below — which itself goes
+    // through the adapter — cannot recurse back into loading the manifest.
+    state.manifestLoaded = true;
+    state.manifestPromise = (async ()=>{
+        const { docs } = await req.payload.db.find({
+            collection: 'payload-branch-changes',
+            limit: 0,
+            pagination: false,
+            req,
+            where: {
+                and: [
+                    {
+                        branch: {
+                            equals: branch
+                        }
+                    },
+                    {
+                        entityType: {
+                            equals: 'collection'
+                        }
+                    }
+                ]
+            }
+        });
+        for (const change of docs){
+            const slug = change.collectionSlug;
+            const docID = extractRelationshipID({
+                relationship: change.doc
+            });
+            if (!slug || docID === undefined || docID === null) {
+                continue;
+            }
+            const existing = state.manifest.get(slug);
+            if (existing) {
+                existing.push(docID);
+            } else {
+                state.manifest.set(slug, [
+                    docID
+                ]);
+            }
+            if (change.operation === 'delete') {
+                const deleted = state.deleted.get(slug);
+                if (deleted) {
+                    deleted.push(docID);
+                } else {
+                    state.deleted.set(slug, [
+                        docID
+                    ]);
+                }
+            }
+            if (change.operation === 'create' || change.operation === 'delete' || change.operation === 'update') {
+                state.operations.set(`${slug}:${String(docID)}`, change.operation);
+            }
+        }
+    })().catch((error)=>{
+        state.manifestLoaded = false;
+        state.manifestPromise = undefined;
+        state.manifest.clear();
+        state.deleted.clear();
+        state.operations.clear();
+        throw error;
+    });
+    await state.manifestPromise;
+    return state.manifest;
+};
+/**
+ * Canonical IDs the active branch has tombstoned, keyed by collection slug.
+ *
+ * Version and collection queries both exclude these documents by canonical
+ * identity from the authoritative change manifest.
+ *
+ * Loaded from the same manifest query, so asking for this costs nothing beyond
+ * the read the request already made.
+ */ export const loadBranchDeletions = async (req)=>{
+    await loadBranchManifest(req);
+    const state = req?.context?.[stateKey];
+    return state?.deleted ?? new Map();
+};
+export const loadBranchOperation = async ({ collectionSlug, docID, req })=>{
+    const branch = resolveBranch({
+        req
+    });
+    const state = req.context?.[stateKey];
+    const operationKey = `${collectionSlug}:${String(docID)}`;
+    const cachedOperation = state?.operations.get(operationKey);
+    if (cachedOperation || branch === MAIN_BRANCH) {
+        return cachedOperation;
+    }
+    const change = await req.payload.db.findOne({
+        branch: false,
+        collection: 'payload-branch-changes',
+        req,
+        where: {
+            and: [
+                {
+                    branch: {
+                        equals: branch
+                    }
+                },
+                {
+                    collectionSlug: {
+                        equals: collectionSlug
+                    }
+                },
+                {
+                    documentID: {
+                        equals: String(docID)
+                    }
+                }
+            ]
+        }
+    });
+    const operation = change?.operation;
+    if (operation === 'create' || operation === 'delete' || operation === 'update') {
+        state?.operations.set(operationKey, operation);
+        return operation;
+    }
+    return undefined;
+};
+/**
+ * A copy of the request that can resolve a branch of its own.
+ *
+ * The resolved branch and its manifest are memoized on `req.context`, so one
+ * request reads one branch — an explicit `branch` argument passed alongside a
+ * request that has already resolved a different one is otherwise accepted and
+ * ignored. Reading the same document on two branches, as a diff does, therefore
+ * needs a request per branch.
+ *
+ * The copy carries the transaction, the user and the locale, so it is the same
+ * request in every respect but the branch. Its dataloader is its own, because
+ * the dataloader's cache key does not include the branch and would otherwise
+ * serve one branch's document to the other.
+ */ export const isolateBranchState = ({ req })=>{
+    const isolated = isolateObjectProperty(req, [
+        'branch',
+        'context',
+        'payloadDataLoader',
+        'operation',
+        'query',
+        'locale',
+        'fallbackLocale',
+        'user',
+        'file',
+        'files'
+    ]);
+    isolated.context = {
+        ...req.context
+    };
+    resetBranchState({
+        req: isolated
+    });
+    isolated.payloadDataLoader = getDataLoader(isolated);
+    return isolated;
+};
+/**
+ * The branch's own row, read once per request.
+ *
+ * Three separate checks want it — whether the branch is closed, whether a merged branch
+ * should reopen, and whether the caller may see it at all — and each used to read it
+ * again. This is the trusted read (`overrideAccess: true`), so it deliberately does *not*
+ * serve the access-checked visibility gate: a row fetched without access control must
+ * never stand in for one fetched with it.
+ */ export const loadBranchRow = async ({ branch, req })=>{
+    const context = req.context;
+    const state = context?.[stateKey];
+    if (state && state.branch === branch && state.branchRow !== undefined) {
+        return state.branchRow;
+    }
+    const { docs } = await req.payload.find({
+        collection: branchesCollectionSlug,
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        pagination: false,
+        req,
+        select: {
+            slug: true,
+            status: true
+        },
+        where: {
+            slug: {
+                equals: branch
+            }
+        }
+    });
+    const row = docs[0] ?? null;
+    if (state && state.branch === branch) {
+        state.branchRow = row;
+    }
+    return row;
+};
+/** Replaces the memoized branch row after something changed it. */ export const setBranchRow = ({ branch, req, row })=>{
+    const context = req.context;
+    const state = context?.[stateKey];
+    if (state && state.branch === branch) {
+        state.branchRow = row;
+    }
+};
+/**
+ * Records a newly forked document in the memoized manifest.
+ *
+ * Cheaper than dropping the manifest and reloading it, which is what a fork used to do:
+ * the manifest needs to know the branch now shadows this document, and that is one ID —
+ * not a reason to re-read every change row on the branch. Reads later in the same request
+ * then exclude main's copy without a second query.
+ */ export const addToBranchManifest = ({ collectionSlug, docID, operation, req })=>{
+    const context = req.context;
+    const state = context?.[stateKey];
+    // Not loaded yet is the common case on a write-only request: the next read loads it
+    // fresh, and it will include this document.
+    if (!state?.manifestLoaded) {
+        return;
+    }
+    const existing = state.manifest.get(collectionSlug);
+    if (existing) {
+        if (!existing.some((id)=>String(id) === String(docID))) {
+            existing.push(docID);
+        }
+    } else {
+        state.manifest.set(collectionSlug, [
+            docID
+        ]);
+    }
+    state.operations.set(`${collectionSlug}:${String(docID)}`, operation);
+};
+/** The shadow row ID this request has already resolved for a canonical ID, if any. */ export const peekBranchRowID = ({ collectionSlug, docID, req })=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    return state?.rowIDs.get(`${collectionSlug}:${docID}`);
+};
+/** Remembers a canonical ID's shadow row, so the next write does not look it up again. */ export const rememberBranchRowID = ({ collectionSlug, docID, req, rowID })=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    state?.rowIDs.set(`${collectionSlug}:${docID}`, rowID);
+};
+/**
+ * The same request with branch resolution switched off.
+ *
+ * For the engines that write to `main` on a branch's behalf — merge and discard. They
+ * address shadow rows by their real primary keys and write production, so every write
+ * they make must bypass branch resolution. Passing `branch: false` per call is one
+ * omission away from a silent no-op: the merge-create promotion goes through
+ * `updateByIDOperation`, which takes no `branch` argument at all and reads the request,
+ * so a merge triggered over HTTP with `?branch=` resolved that write against the branch
+ * it was merging.
+ *
+ * Isolated rather than mutated, because the caller's request keeps its own branch — the
+ * HTTP handler still has a response to render on it.
+ */ export const withoutBranch = ({ req })=>{
+    const isolated = isolateBranchState({
+        req
+    });
+    // The same sentinel `createPayloadRequest({ branch: false })` sets, rather than a `branch`
+    // of our own: `req.branch` alone is not enough, because resolution falls back to the
+    // query string behind it.
+    isolated.branch = undefined;
+    isolated.context._branchBypass = true;
+    return isolated;
+};
+/**
+ * The branch this request has already resolved, or `undefined` if it has not.
+ *
+ * Deliberately does not resolve: callers use this to find out whether they are about to
+ * *change* the branch, and resolving here would create the state they are checking for.
+ */ export const peekResolvedBranch = ({ req } = {})=>{
+    const context = req?.context;
+    return context?.[stateKey]?.branch;
+};
+/** Clears memoized branch state, for tests and for cross-branch reads. */ export const resetBranchState = ({ req })=>{
+    const context = req.context;
+    if (context) {
+        delete context[stateKey];
+    }
+};
+/** Clears memoized branch and document state after a write changes what this request can read. */ export const refreshBranchState = ({ req })=>{
+    resetBranchState({
+        req
+    });
+    refreshRequestDataLoader({
+        req
+    });
+};
+/** Clears documents cached while populating relationships on this request. */ export const refreshRequestDataLoader = ({ req })=>{
+    req.payloadDataLoader = getDataLoader(req);
+};
+/**
+ * The manifest already loaded for this request, without loading it.
+ *
+ * For synchronous callers such as join query builders, which run after the
+ * top-level read has resolved the branch and populated the manifest.
+ */ export const peekBranchManifest = (req)=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    return state?.manifest ?? new Map();
+};
+/**
+ * The branch deletions already loaded for this request, without loading them.
+ *
+ * Version join builders are synchronous. They run after the top-level branch query has loaded the
+ * manifest, which also records deletions, so they can reuse that state without another query.
+ */ export const peekBranchDeletions = (req)=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    return state?.deleted ?? new Map();
+};
+/** The authoritative operation for one collection document in the loaded change manifest. */ export const peekBranchOperation = ({ collectionSlug, docID, req })=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    return state?.operations.get(`${collectionSlug}:${String(docID)}`);
+};
+
+//# sourceMappingURL=resolveBranch.js.map

package/dist/branching/resolveBranch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/branching/resolveBranch.ts"],"sourcesContent":["import type { PayloadRequest } from '../types/index.js'\nimport type { BranchOperation, SanitizedBranchingConfig } from './types.js'\n\nimport { getDataLoader } from '../collections/dataloader.js'\nimport { extractRelationshipID } from '../utilities/extractRelationshipID.js'\nimport { isolateObjectProperty } from '../utilities/isolateObjectProperty.js'\nimport { branchesCollectionSlug, MAIN_BRANCH } from './types.js'\n\n/**\n * Per-request branch state, memoized on `req` so a page rendering many\n * collections resolves the branch once and loads the change manifest once.\n */\ntype BranchState = {\n  branch: string\n  /** The branch's own row, read once per request rather than per check. */\n  branchRow?: null | Record<string, unknown>\n  /** Canonical IDs tombstoned on this branch, keyed by collection slug. */\n  deleted: Map<string, (number | string)[]>\n  /** Canonical shadowed document IDs, keyed by collection slug. */\n  manifest: Map<string, (number | string)[]>\n  manifestLoaded: boolean\n  manifestPromise?: Promise<void>\n  /** Change-record operation keyed by collection and canonical document ID. */\n  operations: Map<string, BranchOperation>\n  /** Canonical ID → shadow row primary key, for the writes that resolved it. */\n  rowIDs: Map<string, number | string>\n}\n\nconst stateKey = '_branchState'\n\nconst getBranchingConfig = (req: PayloadRequest): SanitizedBranchingConfig | undefined =>\n  req?.payload?.config?.branching\n\n/**\n * Resolves the active branch for a request.\n *\n * The branch is an argument, exactly like `locale` and `depth`: it is whatever\n * the caller passed, and `main` when they passed nothing. Nothing is read from\n * storage here — no preference lookup, no cookie — so an unbranched request\n * costs nothing beyond this function.\n *\n * Where the admin UI's persisted selection turns into that argument is the\n * admin UI's business (`initAdminContext`), the same division `locale` already uses.\n *\n * Precedence, highest first:\n *   1. explicit Local API argument (`req.branch`, set by the caller)\n *   2. `branch` query param\n *   3. `main`\n */\nexport const resolveBranch = ({ req }: { req: PayloadRequest }): string => {\n  const branching = getBranchingConfig(req)\n\n  if (!branching?.enabled) {\n    return MAIN_BRANCH\n  }\n\n  const context = req.context as Record<string, unknown> | undefined\n  const existing = context?.[stateKey] as BranchState | undefined\n\n  if (existing) {\n    return existing.branch\n  }\n\n  // The bypass sentinel `createPayloadRequest` sets for `branch: false`. Honoured here and not\n  // only at the database layer, because a request told to ignore branching must not\n  // report a branch to anything that asks — a `branch: false` request built from an HTTP\n  // request still carries `?branch=` in its query, and falling through to it made the\n  // merge engine resolve against the very branch it was merging.\n  if (context?._branchBypass) {\n    req.branch = MAIN_BRANCH\n\n    return MAIN_BRANCH\n  }\n\n  const branch = resolveBranchFromRequest(req) ?? MAIN_BRANCH\n\n  if (context) {\n    context[stateKey] = {\n      branch,\n      deleted: new Map(),\n      manifest: new Map(),\n      manifestLoaded: false,\n      operations: new Map(),\n      rowIDs: new Map(),\n    } satisfies BranchState\n  }\n\n  req.branch = branch\n\n  return branch\n}\n\n/**\n * The branch the caller asked for, whether through the Local API option or the\n * `branch` query param — the same two ways `locale` is supplied.\n */\nconst resolveBranchFromRequest = (req: PayloadRequest): string | undefined => {\n  if (typeof req.branch === 'string' && req.branch) {\n    return req.branch\n  }\n\n  if (typeof req.query?.branch === 'string' && req.query.branch) {\n    return req.query.branch\n  }\n\n  return undefined\n}\n\n/**\n * Loads every change the active branch has made, in one query, and groups it\n * by collection in memory.\n *\n * One query per request rather than per collection: a request touching a dozen\n * collections still issues a single manifest read. Bounded by branch size, not\n * table size.\n */\nexport const loadBranchManifest = async (\n  req: PayloadRequest,\n): Promise<Map<string, (number | string)[]>> => {\n  const branch = resolveBranch({ req })\n  const context = req.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  if (!state || branch === MAIN_BRANCH) {\n    return new Map()\n  }\n\n  if (state.manifestLoaded) {\n    await state.manifestPromise\n    return state.manifest\n  }\n\n  // Marked loaded up front so the manifest read below — which itself goes\n  // through the adapter — cannot recurse back into loading the manifest.\n  state.manifestLoaded = true\n\n  state.manifestPromise = (async () => {\n    const { docs } = await req.payload.db.find({\n      collection: 'payload-branch-changes',\n      limit: 0,\n      pagination: false,\n      req,\n      where: {\n        and: [{ branch: { equals: branch } }, { entityType: { equals: 'collection' } }],\n      },\n    })\n\n    for (const change of docs as Record<string, unknown>[]) {\n      const slug = change.collectionSlug as string\n      const docID = extractRelationshipID({ relationship: change.doc })\n\n      if (!slug || docID === undefined || docID === null) {\n        continue\n      }\n\n      const existing = state.manifest.get(slug)\n\n      if (existing) {\n        existing.push(docID)\n      } else {\n        state.manifest.set(slug, [docID])\n      }\n\n      if (change.operation === 'delete') {\n        const deleted = state.deleted.get(slug)\n\n        if (deleted) {\n          deleted.push(docID)\n        } else {\n          state.deleted.set(slug, [docID])\n        }\n      }\n\n      if (\n        change.operation === 'create' ||\n        change.operation === 'delete' ||\n        change.operation === 'update'\n      ) {\n        state.operations.set(`${slug}:${String(docID)}`, change.operation)\n      }\n    }\n  })().catch((error) => {\n    state.manifestLoaded = false\n    state.manifestPromise = undefined\n    state.manifest.clear()\n    state.deleted.clear()\n    state.operations.clear()\n    throw error\n  })\n\n  await state.manifestPromise\n\n  return state.manifest\n}\n\n/**\n * Canonical IDs the active branch has tombstoned, keyed by collection slug.\n *\n * Version and collection queries both exclude these documents by canonical\n * identity from the authoritative change manifest.\n *\n * Loaded from the same manifest query, so asking for this costs nothing beyond\n * the read the request already made.\n */\nexport const loadBranchDeletions = async (\n  req: PayloadRequest,\n): Promise<Map<string, (number | string)[]>> => {\n  await loadBranchManifest(req)\n\n  const state = (req?.context as Record<string, unknown> | undefined)?.[stateKey] as\n    | BranchState\n    | undefined\n\n  return state?.deleted ?? new Map()\n}\n\nexport const loadBranchOperation = async ({\n  collectionSlug,\n  docID,\n  req,\n}: {\n  collectionSlug: string\n  docID: number | string\n  req: PayloadRequest\n}): Promise<BranchOperation | undefined> => {\n  const branch = resolveBranch({ req })\n  const state = (req.context as Record<string, unknown> | undefined)?.[stateKey] as\n    | BranchState\n    | undefined\n  const operationKey = `${collectionSlug}:${String(docID)}`\n  const cachedOperation = state?.operations.get(operationKey)\n\n  if (cachedOperation || branch === MAIN_BRANCH) {\n    return cachedOperation\n  }\n\n  const change = await req.payload.db.findOne({\n    branch: false,\n    collection: 'payload-branch-changes',\n    req,\n    where: {\n      and: [\n        { branch: { equals: branch } },\n        { collectionSlug: { equals: collectionSlug } },\n        { documentID: { equals: String(docID) } },\n      ],\n    },\n  })\n  const operation = (change as { operation?: unknown } | null)?.operation\n\n  if (operation === 'create' || operation === 'delete' || operation === 'update') {\n    state?.operations.set(operationKey, operation)\n\n    return operation\n  }\n\n  return undefined\n}\n\n/**\n * A copy of the request that can resolve a branch of its own.\n *\n * The resolved branch and its manifest are memoized on `req.context`, so one\n * request reads one branch — an explicit `branch` argument passed alongside a\n * request that has already resolved a different one is otherwise accepted and\n * ignored. Reading the same document on two branches, as a diff does, therefore\n * needs a request per branch.\n *\n * The copy carries the transaction, the user and the locale, so it is the same\n * request in every respect but the branch. Its dataloader is its own, because\n * the dataloader's cache key does not include the branch and would otherwise\n * serve one branch's document to the other.\n */\nexport const isolateBranchState = ({ req }: { req: PayloadRequest }): PayloadRequest => {\n  const isolated = isolateObjectProperty(req, [\n    'branch',\n    'context',\n    'payloadDataLoader',\n    'operation',\n    'query',\n    'locale',\n    'fallbackLocale',\n    'user',\n    'file',\n    'files',\n  ])\n  isolated.context = { ...req.context }\n\n  resetBranchState({ req: isolated })\n  isolated.payloadDataLoader = getDataLoader(isolated)\n\n  return isolated\n}\n\n/**\n * The branch's own row, read once per request.\n *\n * Three separate checks want it — whether the branch is closed, whether a merged branch\n * should reopen, and whether the caller may see it at all — and each used to read it\n * again. This is the trusted read (`overrideAccess: true`), so it deliberately does *not*\n * serve the access-checked visibility gate: a row fetched without access control must\n * never stand in for one fetched with it.\n */\nexport const loadBranchRow = async ({\n  branch,\n  req,\n}: {\n  branch: string\n  req: PayloadRequest\n}): Promise<null | Record<string, unknown>> => {\n  const context = req.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  if (state && state.branch === branch && state.branchRow !== undefined) {\n    return state.branchRow\n  }\n\n  const { docs } = await req.payload.find({\n    collection: branchesCollectionSlug,\n    depth: 0,\n    limit: 1,\n    overrideAccess: true,\n    pagination: false,\n    req,\n    select: { slug: true, status: true },\n    where: { slug: { equals: branch } },\n  })\n\n  const row = (docs[0] as Record<string, unknown> | undefined) ?? null\n\n  if (state && state.branch === branch) {\n    state.branchRow = row\n  }\n\n  return row\n}\n\n/** Replaces the memoized branch row after something changed it. */\nexport const setBranchRow = ({\n  branch,\n  req,\n  row,\n}: {\n  branch: string\n  req: PayloadRequest\n  row: null | Record<string, unknown>\n}): void => {\n  const context = req.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  if (state && state.branch === branch) {\n    state.branchRow = row\n  }\n}\n\n/**\n * Records a newly forked document in the memoized manifest.\n *\n * Cheaper than dropping the manifest and reloading it, which is what a fork used to do:\n * the manifest needs to know the branch now shadows this document, and that is one ID —\n * not a reason to re-read every change row on the branch. Reads later in the same request\n * then exclude main's copy without a second query.\n */\nexport const addToBranchManifest = ({\n  collectionSlug,\n  docID,\n  operation,\n  req,\n}: {\n  collectionSlug: string\n  docID: number | string\n  operation: BranchOperation\n  req: PayloadRequest\n}): void => {\n  const context = req.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  // Not loaded yet is the common case on a write-only request: the next read loads it\n  // fresh, and it will include this document.\n  if (!state?.manifestLoaded) {\n    return\n  }\n\n  const existing = state.manifest.get(collectionSlug)\n\n  if (existing) {\n    if (!existing.some((id) => String(id) === String(docID))) {\n      existing.push(docID)\n    }\n  } else {\n    state.manifest.set(collectionSlug, [docID])\n  }\n\n  state.operations.set(`${collectionSlug}:${String(docID)}`, operation)\n}\n\n/** The shadow row ID this request has already resolved for a canonical ID, if any. */\nexport const peekBranchRowID = ({\n  collectionSlug,\n  docID,\n  req,\n}: {\n  collectionSlug: string\n  docID: number | string\n  req?: Partial<PayloadRequest>\n}): number | string | undefined => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  return state?.rowIDs.get(`${collectionSlug}:${docID}`)\n}\n\n/** Remembers a canonical ID's shadow row, so the next write does not look it up again. */\nexport const rememberBranchRowID = ({\n  collectionSlug,\n  docID,\n  req,\n  rowID,\n}: {\n  collectionSlug: string\n  docID: number | string\n  req?: Partial<PayloadRequest>\n  rowID: number | string\n}): void => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  state?.rowIDs.set(`${collectionSlug}:${docID}`, rowID)\n}\n\n/**\n * The same request with branch resolution switched off.\n *\n * For the engines that write to `main` on a branch's behalf — merge and discard. They\n * address shadow rows by their real primary keys and write production, so every write\n * they make must bypass branch resolution. Passing `branch: false` per call is one\n * omission away from a silent no-op: the merge-create promotion goes through\n * `updateByIDOperation`, which takes no `branch` argument at all and reads the request,\n * so a merge triggered over HTTP with `?branch=` resolved that write against the branch\n * it was merging.\n *\n * Isolated rather than mutated, because the caller's request keeps its own branch — the\n * HTTP handler still has a response to render on it.\n */\nexport const withoutBranch = ({ req }: { req: PayloadRequest }): PayloadRequest => {\n  const isolated = isolateBranchState({ req })\n\n  // The same sentinel `createPayloadRequest({ branch: false })` sets, rather than a `branch`\n  // of our own: `req.branch` alone is not enough, because resolution falls back to the\n  // query string behind it.\n  isolated.branch = undefined\n  ;(isolated.context as Record<string, unknown>)._branchBypass = true\n\n  return isolated\n}\n\n/**\n * The branch this request has already resolved, or `undefined` if it has not.\n *\n * Deliberately does not resolve: callers use this to find out whether they are about to\n * *change* the branch, and resolving here would create the state they are checking for.\n */\nexport const peekResolvedBranch = ({ req }: { req?: Partial<PayloadRequest> } = {}):\n  | string\n  | undefined => {\n  const context = req?.context as Record<string, unknown> | undefined\n\n  return (context?.[stateKey] as BranchState | undefined)?.branch\n}\n\n/** Clears memoized branch state, for tests and for cross-branch reads. */\nexport const resetBranchState = ({ req }: { req: PayloadRequest }): void => {\n  const context = req.context as Record<string, unknown> | undefined\n\n  if (context) {\n    delete context[stateKey]\n  }\n}\n\n/** Clears memoized branch and document state after a write changes what this request can read. */\nexport const refreshBranchState = ({ req }: { req: PayloadRequest }): void => {\n  resetBranchState({ req })\n  refreshRequestDataLoader({ req })\n}\n\n/** Clears documents cached while populating relationships on this request. */\nexport const refreshRequestDataLoader = ({ req }: { req: PayloadRequest }): void => {\n  req.payloadDataLoader = getDataLoader(req)\n}\n\n/**\n * The manifest already loaded for this request, without loading it.\n *\n * For synchronous callers such as join query builders, which run after the\n * top-level read has resolved the branch and populated the manifest.\n */\nexport const peekBranchManifest = (req: PayloadRequest): Map<string, (number | string)[]> => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  return state?.manifest ?? new Map()\n}\n\n/**\n * The branch deletions already loaded for this request, without loading them.\n *\n * Version join builders are synchronous. They run after the top-level branch query has loaded the\n * manifest, which also records deletions, so they can reuse that state without another query.\n */\nexport const peekBranchDeletions = (req: PayloadRequest): Map<string, (number | string)[]> => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  return state?.deleted ?? new Map()\n}\n\n/** The authoritative operation for one collection document in the loaded change manifest. */\nexport const peekBranchOperation = ({\n  collectionSlug,\n  docID,\n  req,\n}: {\n  collectionSlug: string\n  docID: number | string\n  req?: Partial<PayloadRequest>\n}): BranchOperation | undefined => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  return state?.operations.get(`${collectionSlug}:${String(docID)}`)\n}\n"],"names":["getDataLoader","extractRelationshipID","isolateObjectProperty","branchesCollectionSlug","MAIN_BRANCH","stateKey","getBranchingConfig","req","payload","config","branching","resolveBranch","enabled","context","existing","branch","_branchBypass","resolveBranchFromRequest","deleted","Map","manifest","manifestLoaded","operations","rowIDs","query","undefined","loadBranchManifest","state","manifestPromise","docs","db","find","collection","limit","pagination","where","and","equals","entityType","change","slug","collectionSlug","docID","relationship","doc","get","push","set","operation","String","catch","error","clear","loadBranchDeletions","loadBranchOperation","operationKey","cachedOperation","findOne","documentID","isolateBranchState","isolated","resetBranchState","payloadDataLoader","loadBranchRow","branchRow","depth","overrideAccess","select","status","row","setBranchRow","addToBranchManifest","some","id","peekBranchRowID","rememberBranchRowID","rowID","withoutBranch","peekResolvedBranch","refreshBranchState","refreshRequestDataLoader","peekBranchManifest","peekBranchDeletions","peekBranchOperation"],"mappings":"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"}

package/dist/branching/resolveBranchActionAccess.d.ts

@@ -0,0 +1,8 @@
+import type { Access } from '../config/types.js';
+import type { SanitizedBranchingConfig } from './types.js';
+export type BranchAction = 'discardBranch' | 'mergeBranch';
+export declare const resolveBranchActionAccess: ({ action, branching, }: {
+    action: BranchAction;
+    branching: SanitizedBranchingConfig;
+}) => Access;
+//# sourceMappingURL=resolveBranchActionAccess.d.ts.map

package/dist/branching/resolveBranchActionAccess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveBranchActionAccess.d.ts","sourceRoot":"","sources":["../../src/branching/resolveBranchActionAccess.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAI1D,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,aAAa,CAAA;AAE1D,eAAO,MAAM,yBAAyB,2BAGnC;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,SAAS,EAAE,wBAAwB,CAAA;CACpC,KAAG,MAMH,CAAA"}

package/dist/branching/resolveBranchActionAccess.js

@@ -0,0 +1,9 @@
+import { defaultAccess } from '../auth/defaultAccess.js';
+export const resolveBranchActionAccess = ({ action, branching })=>{
+    if (action === 'mergeBranch') {
+        return branching.access?.mergeBranch ?? branching.access?.readBranch ?? defaultAccess;
+    }
+    return branching.access?.discardBranch ?? branching.access?.deleteBranch ?? defaultAccess;
+};
+
+//# sourceMappingURL=resolveBranchActionAccess.js.map

package/dist/branching/resolveBranchActionAccess.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/branching/resolveBranchActionAccess.ts"],"sourcesContent":["import type { Access } from '../config/types.js'\nimport type { SanitizedBranchingConfig } from './types.js'\n\nimport { defaultAccess } from '../auth/defaultAccess.js'\n\nexport type BranchAction = 'discardBranch' | 'mergeBranch'\n\nexport const resolveBranchActionAccess = ({\n  action,\n  branching,\n}: {\n  action: BranchAction\n  branching: SanitizedBranchingConfig\n}): Access => {\n  if (action === 'mergeBranch') {\n    return branching.access?.mergeBranch ?? branching.access?.readBranch ?? defaultAccess\n  }\n\n  return branching.access?.discardBranch ?? branching.access?.deleteBranch ?? defaultAccess\n}\n"],"names":["defaultAccess","resolveBranchActionAccess","action","branching","access","mergeBranch","readBranch","discardBranch","deleteBranch"],"mappings":"AAGA,SAASA,aAAa,QAAQ,2BAA0B;AAIxD,OAAO,MAAMC,4BAA4B,CAAC,EACxCC,MAAM,EACNC,SAAS,EAIV;IACC,IAAID,WAAW,eAAe;QAC5B,OAAOC,UAAUC,MAAM,EAAEC,eAAeF,UAAUC,MAAM,EAAEE,cAAcN;IAC1E;IAEA,OAAOG,UAAUC,MAAM,EAAEG,iBAAiBJ,UAAUC,MAAM,EAAEI,gBAAgBR;AAC9E,EAAC"}

package/dist/branching/resolveBranchQuery.d.ts

@@ -0,0 +1,48 @@
+import type { PayloadRequest, Where } from '../types/index.js';
+type Args = {
+    /**
+     * Explicit override. `false` bypasses branching entirely — used by the merge
+     * engine, which must reach shadow rows by their real primary key, and by
+     * cross-branch reads such as diff views.
+     */
+    branch?: false | string;
+    collectionSlug?: string;
+    globalSlug?: string;
+    req?: Partial<PayloadRequest>;
+    where: undefined | Where;
+};
+export type BranchReadState = {
+    branch: string;
+    useBranching: boolean;
+};
+export declare const resolveBranchReadState: ({ branch: branchOverride, collectionSlug, globalSlug, req, }: Omit<Args, 'where'>) => BranchReadState;
+/**
+ * The single entry point adapters call to make a read branch-aware.
+ *
+ * Lives in `payload` rather than in each adapter so that Mongo and Drizzle
+ * cannot drift apart on branch semantics — adapters supply only the query
+ * translation they already do.
+ *
+ * Returns `where` untouched when branching is off, when the entity is not
+ * branch-enabled, or when the caller opted out, so a branching-disabled config
+ * takes the same code path it does today.
+ */
+export declare const resolveBranchQuery: ({ branch: branchOverride, collectionSlug, globalSlug, req, where, }: Args) => Promise<undefined | Where>;
+/**
+ * Synchronous branch predicate, for query builders that are not async.
+ *
+ * Reads the change manifest that `resolveBranchQuery` has already loaded and
+ * memoized on the request earlier in the same read. Returns `null` when
+ * branching is inactive for the entity, so callers can skip cleanly.
+ *
+ * Join subqueries need this: they are assembled inside synchronous query
+ * builders, but must carry the same branch predicate as the top-level read or
+ * a branch would see main's related documents.
+ */
+export declare const getBranchPredicateSync: ({ branch: branchOverride, collectionSlug, req, }: {
+    branch?: false | string;
+    collectionSlug: string;
+    req?: Partial<PayloadRequest>;
+}) => null | Where;
+export {};
+//# sourceMappingURL=resolveBranchQuery.d.ts.map

package/dist/branching/resolveBranchQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveBranchQuery.d.ts","sourceRoot":"","sources":["../../src/branching/resolveBranchQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAa9D,KAAK,IAAI,GAAG;IACV;;;;OAIG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;IAC7B,KAAK,EAAE,SAAS,GAAG,KAAK,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,eAAO,MAAM,sBAAsB,iEAKhC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,KAAG,eAkCxB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,wEAM5B,IAAI,KAAG,OAAO,CAAC,SAAS,GAAG,KAAK,CAyDlC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,qDAIhC;IACD,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IACvB,cAAc,EAAE,MAAM,CAAA;IACtB,GAAG,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;CAC9B,KAAG,IAAI,GAAG,KA2BV,CAAA"}

package/dist/branching/resolveBranchQuery.js

@@ -0,0 +1,120 @@
+import { appendBranchFilter } from './appendBranchFilter.js';
+import { rewriteBranchIDs } from './branchIDs.js';
+import { loadBranchDeletions, loadBranchManifest, peekBranchDeletions, peekBranchManifest, resolveBranch } from './resolveBranch.js';
+import { MAIN_BRANCH } from './types.js';
+export const resolveBranchReadState = ({ branch: branchOverride, collectionSlug, globalSlug, req })=>{
+    const branching = req?.payload?.config?.branching;
+    const isBranchable = collectionSlug ? Boolean(branching?.branchableCollections.has(collectionSlug)) : globalSlug ? Boolean(branching?.branchableGlobals.has(globalSlug)) : false;
+    const isRequestBypassed = Boolean(req?.context?._branchBypass);
+    const isBypassed = branchOverride === false || isRequestBypassed;
+    if (isRequestBypassed && req?.payload) {
+        resolveBranch({
+            req: req
+        });
+    }
+    if (!branching?.enabled || !isBranchable || isBypassed) {
+        return {
+            branch: typeof branchOverride === 'string' ? branchOverride : MAIN_BRANCH,
+            useBranching: false
+        };
+    }
+    const branch = typeof branchOverride === 'string' ? branchOverride : req?.payload ? resolveBranch({
+        req: req
+    }) : MAIN_BRANCH;
+    return {
+        branch,
+        useBranching: branch !== MAIN_BRANCH
+    };
+};
+/**
+ * The single entry point adapters call to make a read branch-aware.
+ *
+ * Lives in `payload` rather than in each adapter so that Mongo and Drizzle
+ * cannot drift apart on branch semantics — adapters supply only the query
+ * translation they already do.
+ *
+ * Returns `where` untouched when branching is off, when the entity is not
+ * branch-enabled, or when the caller opted out, so a branching-disabled config
+ * takes the same code path it does today.
+ */ export const resolveBranchQuery = async ({ branch: branchOverride, collectionSlug, globalSlug, req, where })=>{
+    if (branchOverride === false || !req?.payload) {
+        return where;
+    }
+    // Local API `branch: false` bypass, carried on context so it survives the
+    // hop from operation options into the adapter.
+    if (req.context?._branchBypass) {
+        return where;
+    }
+    const branching = req.payload.config?.branching;
+    if (!branching?.enabled) {
+        return where;
+    }
+    const isBranchable = collectionSlug ? branching.branchableCollections.has(collectionSlug) : globalSlug ? branching.branchableGlobals.has(globalSlug) : false;
+    if (!isBranchable) {
+        return where;
+    }
+    const branch = branchOverride ?? resolveBranch({
+        req: req
+    });
+    if (branch === MAIN_BRANCH) {
+        return appendBranchFilter({
+            branch,
+            deletedIDs: [],
+            enabled: true,
+            shadowedIDs: [],
+            where: where ?? {}
+        });
+    }
+    const [manifest, deletions] = await Promise.all([
+        loadBranchManifest(req),
+        loadBranchDeletions(req)
+    ]);
+    const shadowedIDs = collectionSlug ? manifest.get(collectionSlug) ?? [] : [];
+    const deletedIDs = collectionSlug ? deletions.get(collectionSlug) ?? [] : [];
+    // A shadow row's primary key is not the document's canonical ID, so any `id`
+    // constraint has to be redirected before the branch predicate is applied.
+    const rewritten = rewriteBranchIDs(where ?? {});
+    return appendBranchFilter({
+        branch,
+        deletedIDs,
+        enabled: true,
+        shadowedIDs,
+        where: rewritten ?? {}
+    });
+};
+/**
+ * Synchronous branch predicate, for query builders that are not async.
+ *
+ * Reads the change manifest that `resolveBranchQuery` has already loaded and
+ * memoized on the request earlier in the same read. Returns `null` when
+ * branching is inactive for the entity, so callers can skip cleanly.
+ *
+ * Join subqueries need this: they are assembled inside synchronous query
+ * builders, but must carry the same branch predicate as the top-level read or
+ * a branch would see main's related documents.
+ */ export const getBranchPredicateSync = ({ branch: branchOverride, collectionSlug, req })=>{
+    if (branchOverride === false || !req?.payload) {
+        return null;
+    }
+    if (req.context?._branchBypass) {
+        return null;
+    }
+    const branching = req.payload.config?.branching;
+    if (!branching?.enabled || !branching.branchableCollections.has(collectionSlug)) {
+        return null;
+    }
+    const branch = branchOverride ?? resolveBranch({
+        req: req
+    });
+    const shadowedIDs = branch === MAIN_BRANCH ? [] : peekBranchManifest(req).get(collectionSlug) ?? [];
+    const deletedIDs = branch === MAIN_BRANCH ? [] : peekBranchDeletions(req).get(collectionSlug) ?? [];
+    return appendBranchFilter({
+        branch,
+        deletedIDs,
+        enabled: true,
+        shadowedIDs,
+        where: {}
+    });
+};
+
+//# sourceMappingURL=resolveBranchQuery.js.map