@foir/sdk 0.18.0 → 0.20.0

package/dist/auth/index.d.ts

@@ -12,6 +12,8 @@
  */
 export { customerLogin, customerRegister, customerRequestOTP, customerLoginOTP, customerRefreshToken, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, getAuthProviders, getAuthConfig, getDefaultAuthProvider, customerSignupContext, customerJoinWaitlist, customerRequestPasswordReset, customerResetPassword, customerUpdatePassword, customerVerifyEmail, currentUser, myProviderToken, customerLogout, deleteMyAccount, myOrganizations, selectOrganization, registerOrganization, saveSession, clearSession, getSessionToken, getSessionCustomer, loginWithPassword, registerWithPassword, loginWithOTP, resetPasswordAndSignIn, refreshSession, refreshSessionOnce, signOut, authedRequest, authedOp, requireAuth, requireAdmin, } from './auth';
 export type { FoirAuthTokens, FoirCustomer, FoirUser, SessionAdapter, RequireAuthOptions, RequireAdminOptions, } from './auth';
+export { customerAccess, getSessionAccess, hasRole, hasScope, requireRole, requireScope, FoirAccessDeniedError, } from './access';
+export type { FoirAccess, FoirAccessDenial } from './access';
 export { FoirAuthDowngradedError, FoirSessionExpiredError } from '../graphql/foir-request';
 export { AUTH_OPS } from './ops';
 export type { AuthOpName, AuthOpOptions } from './ops';

package/dist/auth/operations.d.ts

@@ -212,7 +212,12 @@ export interface MyOrganizationRole {
     id: string;
     key: string;
     name: string;
-    permissions: string[];
+    /**
+     * What the role gives, as grants in the permission catalogue's names
+     * (`records:read:order`, `members:write`). Each stands for itself: changing
+     * a record and creating one are two grants.
+     */
+    grants: string[];
 }
 /**
  * Where the caller now stands, as `selectMyOrganization` returns it.

package/dist/auth/ops.d.ts

@@ -44,6 +44,7 @@ export declare const AUTH_OPS: {
     readonly customerSignupContext: "customerSignupContext";
     readonly currentUser: "currentUser";
     readonly myProviderToken: "myProviderToken";
+    readonly whoami: "whoami";
     readonly customerLogin: "customerLogin";
     readonly customerRegister: "customerRegister";
     readonly customerRequestOTP: "customerRequestOTP";

package/dist/auth.js

@@ -679,7 +679,7 @@ function toVariableValue(value, label) {
     return value.toISOString();
   }
   if (Array.isArray(value)) {
-    return value.filter((item) => item !== void 0).map((item, index) => toVariableValue(item, `${label}[${index}]`));
+    return value.filter((item) => item !== void 0).map((item, index2) => toVariableValue(item, `${label}[${index2}]`));
   }
   if (kind === "object") {
     const out = {};
@@ -1034,6 +1034,9 @@ var AUTH_OPS = {
   // Post-credential self reads.
   currentUser: "currentUser",
   myProviderToken: "myProviderToken",
+  // What the calling credential may do, and for a signed-in customer the roles
+  // they hold. `./access` reads it.
+  whoami: "whoami",
   // Methods.
   customerLogin: "customerLogin",
   customerRegister: "customerRegister",
@@ -1357,6 +1360,264 @@ async function requireAdmin(adapter, options) {
   return user;
 }
 
+// src/auth/grant-table.generated.ts
+var GRANT_TABLE = [
+  ["records:read", true, ["own", "named", "all"], []],
+  ["records:create", true, [], []],
+  ["records:write", true, ["own", "named", "all"], []],
+  ["records:delete", true, ["own", "named", "all"], []],
+  ["records:publish", true, ["own", "all"], []],
+  ["records:attribute", true, [], []],
+  ["search:read", true, [], []],
+  ["embeddings:read", false, [], []],
+  ["embeddings:write", false, [], []],
+  ["schemas:read", false, [], []],
+  ["drafts:read", false, [], []],
+  ["files:read", false, ["own", "all"], []],
+  ["files:write", false, ["own", "all"], []],
+  ["files:delete", false, ["own", "all"], []],
+  ["notifications:read", false, ["own", "all"], []],
+  ["notifications:write", false, ["own", "named", "all"], []],
+  ["notifications:consent", false, [], []],
+  ["pushcredentials:read", false, [], []],
+  ["pushcredentials:write", false, [], []],
+  ["notes:read", false, [], []],
+  ["notes:write", false, [], []],
+  ["notes:create", false, [], []],
+  ["approvals:read", false, [], []],
+  ["approvals:write", false, [], []],
+  ["rooms:read", true, [], []],
+  ["rooms:write", true, [], []],
+  ["presence:read", true, [], []],
+  ["operations:read", false, [], []],
+  ["operations:execute", true, [], []],
+  ["operations:write", false, [], []],
+  ["operations:complete", false, [], []],
+  ["status:write", false, [], []],
+  ["appconfig:read", false, [], []],
+  ["schedules:read", false, [], []],
+  ["schedules:write", false, [], []],
+  ["hooks:read", false, [], []],
+  ["hooks:write", false, [], []],
+  ["relyingparties:read", false, [], []],
+  ["relyingparties:write", false, [], []],
+  ["domains:read", false, [], []],
+  ["domains:write", false, [], []],
+  ["secrets:read", false, [], []],
+  ["secrets:list", false, [], []],
+  ["secrets:put", false, [], []],
+  ["secrets:delete", false, [], []],
+  ["appsecrets:read", false, [], []],
+  ["appsecrets:list", false, [], []],
+  ["appsecrets:put", false, [], []],
+  ["appsecrets:delete", false, [], []],
+  ["opsecrets:read", false, [], []],
+  ["opsecrets:write", false, [], []],
+  ["settings:read", false, [], []],
+  ["settings:write", false, [], []],
+  ["designtokens:read", false, [], []],
+  ["designtokens:write", false, [], []],
+  ["models:read", false, [], []],
+  ["models:write", false, [], []],
+  ["configs:read", false, [], []],
+  ["configs:write", false, [], []],
+  ["apps:read", false, [], []],
+  ["apps:write", false, [], []],
+  ["events:read", false, [], []],
+  ["targeting:debug", false, [], []],
+  ["visitors:forward", false, [], []],
+  ["apikeys:read", false, [], []],
+  ["apikeys:write", false, [], []],
+  ["organizations:read", false, [], []],
+  ["organizations:write", false, [], []],
+  ["organizations:create", false, [], []],
+  ["organizations:delete", false, [], []],
+  ["organizations:reach", false, [], []],
+  ["members:read", false, [], []],
+  ["members:write", false, [], []],
+  ["roles:read", false, [], []],
+  ["roles:write", false, [], []],
+  ["projects:read", false, [], []],
+  ["projects:write", false, [], []],
+  ["project:manage", false, [], ["records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read", "notes:write", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "auth:login_with_foir", "relyingparties:read", "relyingparties:write", "domains:read", "domains:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write"]],
+  ["projects:create", false, [], []],
+  ["projects:delete", false, [], []],
+  ["tenants:read", false, [], []],
+  ["tenants:write", false, [], []],
+  ["tenants:delete", false, [], []],
+  ["audit:read", false, [], []],
+  ["export:run", false, [], []],
+  ["billing:read", false, [], []],
+  ["billing:manage", false, [], []],
+  ["usage:read", false, [], []],
+  ["controlkeys:read", false, [], []],
+  ["controlkeys:write", false, [], []],
+  ["tenanthooks:read", false, [], []],
+  ["tenanthooks:write", false, [], []],
+  ["apps:install", false, [], []],
+  ["tenant:manage", false, [], ["project:manage", "projects:create", "projects:delete", "tenants:read", "tenants:write", "tenants:delete", "audit:read", "export:run", "billing:read", "billing:manage", "usage:read", "controlkeys:read", "controlkeys:write", "tenanthooks:read", "tenanthooks:write", "apps:install"]],
+  ["platform:read", false, [], []],
+  ["platform:manage", false, [], ["tenant:manage", "platform:read", "platform:create_workspace", "users:setup"]],
+  ["platform:create_workspace", false, [], []],
+  ["users:read", false, ["own", "named", "all"], []],
+  ["users:write", false, ["own", "all"], []],
+  ["users:setup", false, [], []],
+  ["users:delete", false, ["own", "all"], []],
+  ["users:create", false, [], []],
+  ["identities:read", false, [], []],
+  ["identities:delete", false, [], []],
+  ["usersecrets:read", false, [], []],
+  ["usersecrets:list", false, [], []],
+  ["usersecrets:put", false, [], []],
+  ["usersecrets:delete", false, [], []],
+  ["auth:login_with_foir", false, [], []],
+  ["signinproviders:read", false, [], []],
+  ["signinproviders:write", false, [], []]
+];
+
+// src/auth/grants.ts
+var WILDCARD = "*";
+var RESOURCE_WILDCARD = ":*";
+var index;
+function catalogue() {
+  if (!index) {
+    const byName = new Map(GRANT_TABLE.map((row) => [row[0], row]));
+    const longestFirst = [...byName.keys()].sort(
+      (a, b) => a.length !== b.length ? b.length - a.length : a < b ? -1 : 1
+    );
+    index = { byName, longestFirst };
+  }
+  return index;
+}
+var reachRank = { own: 1, named: 2, all: 3 };
+function hasReach(permission, reach) {
+  const reaches = permission[2];
+  return reaches.length === 0 ? reach === "own" : reaches.includes(reach);
+}
+function resourceOf(name) {
+  const i = name.indexOf(":");
+  return i < 0 ? name : name.slice(0, i);
+}
+function parseGrant(s) {
+  const { byName, longestFirst } = catalogue();
+  for (const name of longestFirst) {
+    if (!s.startsWith(name)) continue;
+    let rest = s.slice(name.length);
+    if (rest !== "" && rest[0] !== "." && rest[0] !== ":") continue;
+    const permission = byName.get(name);
+    let reach = "own";
+    if (rest.startsWith(".")) {
+      const after = rest.slice(1);
+      const colon = after.indexOf(":");
+      const word = colon < 0 ? after : after.slice(0, colon);
+      if (word !== "named" && word !== "all") return null;
+      if (!hasReach(permission, word)) return null;
+      reach = word;
+      rest = after.slice(word.length);
+    }
+    let target = "";
+    if (rest.startsWith(":")) {
+      target = rest.slice(1);
+      if (!permission[1]) return null;
+      if (target === "" || /[: \t\n*]/.test(target)) return null;
+    }
+    return { permission, reach, target };
+  }
+  return null;
+}
+function covers(held, required) {
+  return held.permission === required.permission && reachRank[held.reach] >= reachRank[required.reach] && (held.target === "" || held.target === required.target);
+}
+function resourceWildcard(held) {
+  if (!held.endsWith(RESOURCE_WILDCARD)) return null;
+  const resource = held.slice(0, -RESOURCE_WILDCARD.length);
+  return resource.includes(":") ? null : resource;
+}
+function holdsAt(held, required, depth) {
+  for (const h of held) {
+    if (h === WILDCARD) return true;
+    const resource = resourceWildcard(h);
+    if (resource !== null) {
+      if (resource === resourceOf(required.permission[0])) return true;
+      continue;
+    }
+    const grant = parseGrant(h);
+    if (grant === null) continue;
+    if (covers(grant, required)) return true;
+    const implies = grant.permission[3];
+    if (depth < 4 && implies.length > 0 && holdsAt(implies, required, depth + 1)) return true;
+  }
+  return false;
+}
+function holds(held, required) {
+  const grant = parseGrant(required);
+  return grant !== null && holdsAt(held, grant, 0);
+}
+
+// src/auth/access.ts
+function accessFrom(who) {
+  const customer = who?.credential?.customer;
+  if (!customer?.id) return null;
+  return {
+    customerId: customer.id,
+    roles: Array.isArray(customer.roles) ? [...customer.roles] : null,
+    scopes: [...who?.authority?.effective ?? []]
+  };
+}
+async function customerAccess(env, options) {
+  return accessFrom(await authOp(env, AUTH_OPS.whoami, void 0, options));
+}
+async function getSessionAccess(adapter, env) {
+  if (!await getSessionToken(adapter)) return null;
+  return accessFrom(await authedOp(adapter, env, AUTH_OPS.whoami));
+}
+function hasRole(access, key) {
+  return access?.roles?.includes(key) ?? false;
+}
+function hasScope(access, scope) {
+  return access ? holds(access.scopes, scope) : false;
+}
+var FoirAccessDeniedError = class extends Error {
+  code = "FOIR_ACCESS_DENIED";
+  reason;
+  /** The role that was required, when one was. */
+  role;
+  /** The scope that was required, when one was. */
+  scope;
+  constructor(reason, required) {
+    super(denialMessage(reason, required));
+    this.name = "FoirAccessDeniedError";
+    this.reason = reason;
+    this.role = required.role;
+    this.scope = required.scope;
+  }
+};
+function denialMessage(reason, required) {
+  switch (reason) {
+    case "signed_out":
+      return "[foir] nobody is signed in";
+    case "role_not_held":
+      return `[foir] the signed-in customer does not hold the role "${required.role}"`;
+    case "roles_unknown":
+      return `[foir] the platform did not say which roles the signed-in customer holds, so "${required.role}" could not be checked`;
+    case "scope_not_held":
+      return `[foir] the signed-in customer's scopes do not cover "${required.scope}"`;
+  }
+}
+async function requireRole(adapter, env, key) {
+  const access = await getSessionAccess(adapter, env);
+  if (!access) throw new FoirAccessDeniedError("signed_out", { role: key });
+  if (access.roles === null) throw new FoirAccessDeniedError("roles_unknown", { role: key });
+  if (!access.roles.includes(key)) throw new FoirAccessDeniedError("role_not_held", { role: key });
+  return access;
+}
+async function requireScope(adapter, env, scope) {
+  const access = await getSessionAccess(adapter, env);
+  if (!access) throw new FoirAccessDeniedError("signed_out", { scope });
+  if (!holds(access.scopes, scope)) throw new FoirAccessDeniedError("scope_not_held", { scope });
+  return access;
+}
+
 // src/auth/hosted.ts
 var DEFAULT_COOKIE_NAME = "foir_customer_session";
 var DEFAULT_SESSION_PATH = "/session/token";
@@ -1567,6 +1828,7 @@ function trimSlash(s) {
 }
 export {
   AUTH_OPS,
+  FoirAccessDeniedError,
   FoirAuthDowngradedError,
   FoirSessionExpiredError,
   authedOp,
@@ -1574,6 +1836,7 @@ export {
   clearSession,
   createFoirSessionClient,
   currentUser,
+  customerAccess,
   customerJoinWaitlist,
   customerLogin,
   customerLoginOTP,
@@ -1594,8 +1857,11 @@ export {
   getAuthConfig,
   getAuthProviders,
   getDefaultAuthProvider,
+  getSessionAccess,
   getSessionCustomer,
   getSessionToken,
+  hasRole,
+  hasScope,
   hostedLoginUrl,
   hostedLogoutUrl,
   loginWithOTP,
@@ -1608,6 +1874,8 @@ export {
   registerWithPassword,
   requireAdmin,
   requireAuth,
+  requireRole,
+  requireScope,
   resetPasswordAndSignIn,
   saveSession,
   selectOrganization,

package/dist/data/builtins.d.ts

@@ -520,7 +520,7 @@ export interface FoirCustomerNote {
  * What a note surface has to know about the project before it renders anything
  * — `foir.ns.notes.noteConfig`.
  *
- * Charged `notes:write` rather than `notes:read`, and refused to a caller with
+ * Charged `notes:create` rather than `notes:read`, and refused to a caller with
  * no customer session, because the only caller it is useful to is one that can
  * submit. So a composer can read it as its single readiness probe: an answer
  * means this visitor may write, and a refusal names which half is missing.
@@ -551,7 +551,54 @@ export interface FoirMyNotesArgs {
  * internal ones.
  */
 export type FoirMyNotesResult = FoirConnection<FoirCustomerNote>;
-/** `createMyNote` arguments. */
+/**
+ * `writeNote` arguments: the one note create, for a signed-in customer and for
+ * a visitor alike. It asks `notes:create` of both.
+ *
+ * A signed-in customer's note is theirs and comes back in `myNotes`. A
+ * visitor's, through a key that gives `notes:create` to whoever comes through
+ * it, on a project that takes visitors' notes, is nobody's: ask for its `id`
+ * and `createdAt` and nothing else, because nothing reads it back.
+ *
+ * Served by a data API that has the field. `<FoirFeedback>` still writes
+ * through `createMyNote`, the same create under its older name, which every
+ * data API serves.
+ */
+export interface FoirWriteNoteArgs {
+    /** A visitor may write about a record and nothing else. */
+    subjectType: FoirNoteSubjectType;
+    subjectId: string;
+    /** Required when `subjectType` is `'record'`, refused otherwise. */
+    subjectModelKey?: string;
+    body: string;
+    /** Reply within an existing thread. Refused where nobody is signed in. */
+    parentNoteId?: string;
+    /**
+     * Files to submit with this note, already uploaded through
+     * `createFileUpload` / `confirmFileUpload`. Refused where nobody is signed in.
+     *
+     * A file this caller cannot read is REFUSED and the note is not written. That
+     * is not a rough edge to code around: a create that accepted the note and
+     * dropped the attachment would leave the author believing they sent a
+     * screenshot nobody has.
+     */
+    attachmentFileIds?: string[];
+    /**
+     * Where the operators may reply to a visitor. Refused from a signed-in
+     * customer, whose note has an author.
+     *
+     * Captured as typed and NEVER verified: it is not treated as proof of who
+     * wrote the note, and nothing is sent to it to confirm it. Do not build a
+     * flow that assumes the address is reachable.
+     */
+    contactEmail?: string;
+}
+/**
+ * `createMyNote` arguments.
+ *
+ * @deprecated `createMyNote` is the older name of `writeNote` for a signed-in
+ * customer. Use `writeNote` and {@link FoirWriteNoteArgs}.
+ */
 export interface FoirCreateMyNoteArgs {
     subjectType: FoirNoteSubjectType;
     subjectId: string;
@@ -581,6 +628,10 @@ export interface FoirCreateMyNoteArgs {
  *
  * WRITE-ONLY. Nothing reads an anonymous note back on the public plane, which
  * is why the result is a receipt rather than the note.
+ *
+ * @deprecated `submitAnonymousNote` is the older name of `writeNote` for a
+ * visitor. Use `writeNote` and {@link FoirWriteNoteArgs}, asking for `id` and
+ * `createdAt`.
  */
 export interface FoirSubmitAnonymousNoteArgs {
     /**
@@ -606,7 +657,12 @@ export interface FoirSubmitAnonymousNoteArgs {
      */
     contactEmail?: string;
 }
-/** What `submitAnonymousNote` returns. */
+/**
+ * What `submitAnonymousNote` returns.
+ *
+ * @deprecated With the field it answers. `writeNote` answers a visitor with
+ * the note's `id` and `createdAt`.
+ */
 export interface FoirAnonymousNoteReceipt {
     /**
      * A reference for this submission, to quote when following it up.

package/dist/data/compatibility.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Whether the surface being served can still answer what a generated module
+ * prints.
+ *
+ * A generated module records the surface version it came from, and that version
+ * is a hash over everything `foir types` reads. So it moves when a model gains
+ * a field, when a namespace gains an op, and when the platform adds a mutation
+ * to every model at once. None of those changes a document this client prints:
+ * the document names the fields and arguments the module knew about, and the
+ * server still has every one of them. Treating a moved version as a reason to
+ * refuse calls made every deployed client stop working the moment the surface
+ * grew, with nothing in its own project having changed.
+ *
+ * So the two are kept apart. A moved version is DRIFT, and it is reported. A
+ * call is refused only for an INCOMPATIBILITY: something that call prints, or
+ * sends, that the server no longer serves the way the module describes. The
+ * client holds both sides of that question once the manifest has arrived, since
+ * the generated trees and the served manifest are the same shape, and this file
+ * compares them.
+ *
+ * ---------------------------------------------------------------------------
+ * What "the same" means
+ * ---------------------------------------------------------------------------
+ *
+ * What `document.ts` reads, because a property the printer never reads cannot
+ * change a document:
+ *
+ *   - an op: its root `field`, whether it is a `mutation`, its `args` and
+ *     `argTypes`, and its `payload` (`kind`, `model`, `union`, `fields`);
+ *   - a selection field: its `key`, and which of the printer's branches it
+ *     takes (a relation, a stopping point, a `model` reference, a `union`
+ *     reference, an object with `fields`, or a leaf);
+ *   - a relation an `include` resolves: `target`, `targets` and `connection`,
+ *     and one property the printer does not read, `list`, because it decides
+ *     whether the same document answers with one record or an array;
+ *   - a model's `typeName`, which names the fragment a polymorphic relation
+ *     prints for it;
+ *   - a union's members, by `typeName`, and each member's fields.
+ *
+ * `cost`, `nullable`, `deprecated` and the buckets the generator does not emit
+ * are not compared. `alias` is not compared either, and that one is a decision:
+ * an alias is a name this client gives a field in its OWN document, so the
+ * server never sees the manifest's opinion of it. A new union member whose
+ * field collides with an existing one makes the server publish aliases for
+ * both, and the module's document, which selects only the members it knew,
+ * is as valid as it was.
+ *
+ * The comparison runs one way. Everything the module names must still be
+ * served; whatever the server has added is never looked at, with one
+ * exception: an argument the served op REQUIRES and the module does not know,
+ * since a call that cannot supply it cannot succeed.
+ */
+import { type FoirSelectionSource } from './document';
+/** One thing the generated module describes that the server no longer serves that way. */
+export interface FoirIncompatibility {
+    /**
+     * Where it sits, in the manifest's own keys:
+     * `models.order.selection.status`, `models.order.ops.update`,
+     * `namespaces.search.ops.searchRecords.args.query`.
+     */
+    path: string;
+    /** What happened to it, as a clause a message can put in brackets. */
+    reason: string;
+}
+/** The comparison, held by a client for as long as it lives. */
+export interface FoirSurfaceComparison {
+    /** Every incompatible path, sorted. Empty when the surface has only grown. */
+    readonly incompatible: readonly string[];
+    /** What `foir.<model>.<op>()` depends on that is incompatible. */
+    modelCall(model: string, op: string, include: unknown): readonly FoirIncompatibility[];
+    /** What `foir.ns.<namespace>.<op>()` depends on that is incompatible. */
+    namespaceCall(namespace: string, op: string, include: unknown): readonly FoirIncompatibility[];
+}
+/**
+ * Compare a generated module's trees with the manifest being served.
+ *
+ * Called once, when the manifest arrives, and off the response path. What it
+ * returns answers each later call from maps built here, so a call pays for a
+ * lookup and, when it has an `include`, a walk of the relations it names.
+ *
+ * How far a break reaches is decided per call rather than per model. A call
+ * depends on its op, on every tree its result prints (the model's own, the
+ * unions inside it, and so on down), and on the relations THIS call includes
+ * with the trees of their targets. A model whose relation points at a broken
+ * model is not refused for it until a call includes that relation, because
+ * until then the broken tree is not in the document. Refusing on the whole
+ * relation graph would let one field removed from one model stop every call in
+ * a project whose models all reach each other, which is most projects.
+ *
+ * It is not narrowed by `pick` or `omit`. A call that omits the one field that
+ * is gone is still refused: resolving a caller's paths against two trees, with
+ * aliases and union members in play, is the printer's work done a second time,
+ * and regenerating is the remedy either way.
+ */
+export declare function compareFoirSurfaces(generated: FoirSelectionSource, served: FoirSelectionSource): FoirSurfaceComparison;

package/dist/data/document.d.ts

@@ -51,7 +51,7 @@
  * inferring a literal would reinstate the defect above under a condition no
  * caller can see.
  */
-import type { FoirManifestOp, FoirManifestRelation, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionUnion } from './manifest';
+import type { FoirManifestOp, FoirManifestOpPayload, FoirManifestRelation, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionUnion } from './manifest';
 /**
  * One model, as the printer needs it.
  *
@@ -145,6 +145,16 @@ export interface FoirRecordPath {
     /** Model key whose published `selection` is printed at that position. */
     modelKey: string;
 }
+/**
+ * Every record position in a payload, in the order the tree declares them.
+ *
+ * ONE walk, and everything that needs to know where the records are reads it:
+ * `planCall` takes the model SET from it to decide where `pick`/`omit`/`include`
+ * land, and the plan carries the positions so the transport's caller can find
+ * the records in the response. A second walk would be correct on the day it was
+ * written and wrong on the day the payload format grew a case.
+ */
+export declare function payloadRecordPaths(payload: FoirManifestOpPayload): readonly FoirRecordPath[];
 /** One printed operation, and what the transport needs to route it. */
 export interface FoirDocumentPlan {
     /** The document text. Also the thing that gets hashed for APQ. */

package/dist/data/index.d.ts

@@ -59,7 +59,7 @@ export { planFoirModelCall, planFoirNamespaceCall } from './document';
 export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
 export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
 export type { FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
-export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirSubmitAnonymousNoteArgs, FoirAnonymousNoteReceipt, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirWriteNoteArgs, FoirSubmitAnonymousNoteArgs, FoirAnonymousNoteReceipt, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
 /**
  * Pre-rename spellings. The `<Name>Block` wrappers and the `<Name>Value`
  * split are the same thing as the types above — an item IS its value — so each