@aglyn/aglyn 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/app-utils/{dataset-query.js → repeat-query.js}

@@ -14,15 +14,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ /**
- * Dataset query layer (AGL-181): filter/sort/limit over typed documents,
- * shared by the console editor and the tenant renderer's repeatable
- * expansion. Deliberately evaluated IN MEMORY over the already-bounded
- * reads (editor page / `REPEAT_MAX_RECORDS`) — the Firestore reality
- * check from the issue: this sidesteps inequality-filter and composite-
- * index constraints entirely, at the documented cost that documents
- * beyond the fetch bound are never considered. The bound is explicit,
- * never silently unbounded.
- */ export const DATASET_QUERY_OPS = [
+ * A repeat's query (AGL-181): the filter, sort and limit an element's
+ * `repeatFilter` / `repeatSort` / `repeatLimit` apply to the rows it repeats
+ * over, whatever source supplied them — the canvas preview and the published
+ * page's expansion run the same one. Deliberately evaluated IN MEMORY over
+ * the already-bounded reads (`REPEAT_MAX_RECORDS`): this sidesteps
+ * inequality-filter and composite-index constraints entirely, at the
+ * documented cost that rows beyond the fetch bound are never considered. The
+ * bound is explicit, never silently unbounded.
+ */ export const REPEAT_QUERY_OPS = [
     '==',
     '!=',
     '>',
@@ -35,7 +35,7 @@
  * Parses the authoring shorthand `field op value` (e.g. `price <= 20`,
  * `tier == plus`, `tags contains red`). Null for unparseable input so
  * callers fail open (no filter) rather than filtering wrongly.
- */ export function parseDatasetFilter(input) {
+ */ export function parseRepeatFilter(input) {
     const match = String(input != null ? input : '').trim().match(/^([A-Za-z][A-Za-z0-9_]*)\s*(==|!=|>=|<=|>|<|contains)\s+(.+)$/);
     if (!match) return null;
     return {
@@ -44,7 +44,7 @@
         value: match[3].trim()
     };
 }
-/** Parses `field` or `field desc` into an orderBy config. */ export function parseDatasetSort(input) {
+/** Parses `field` or `field desc` into an orderBy config. */ export function parseRepeatSort(input) {
     var _match_;
     const match = String(input != null ? input : '').trim().match(/^([A-Za-z][A-Za-z0-9_]*)(?:\s+(asc|desc))?$/i);
     if (!match) return null;
@@ -92,10 +92,10 @@ function matches(stored, where) {
     return false;
 }
 /**
- * Applies where/orderBy/limit to in-memory rows. Where-clauses on fields
- * absent from the model still run (stored-value comparison) so v1
- * datasets work; timestamps compare numerically (epoch millis storage).
- */ export function applyDatasetQuery(model, rows, query) {
+ * Applies where/orderBy/limit to in-memory rows. A clause compares the
+ * stored value whatever field it names, so rows with no declared field
+ * model filter too; timestamps compare numerically (epoch millis storage).
+ */ export function applyRepeatQuery(rows, query) {
     var _query_where;
     let result = rows;
     for (const where of (_query_where = query.where) != null ? _query_where : []){
@@ -123,4 +123,4 @@ function matches(stored, where) {
     return result;
 }
 
-//# sourceMappingURL=dataset-query.js.map
+//# sourceMappingURL=repeat-query.js.map

package/src/lib/app-utils/repeat-query.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/repeat-query.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A repeat's query (AGL-181): the filter, sort and limit an element's\n * `repeatFilter` / `repeatSort` / `repeatLimit` apply to the rows it repeats\n * over, whatever source supplied them — the canvas preview and the published\n * page's expansion run the same one. Deliberately evaluated IN MEMORY over\n * the already-bounded reads (`REPEAT_MAX_RECORDS`): this sidesteps\n * inequality-filter and composite-index constraints entirely, at the\n * documented cost that rows beyond the fetch bound are never considered. The\n * bound is explicit, never silently unbounded.\n */\n\nexport type RepeatQueryOp =\n  | '=='\n  | '!='\n  | '>'\n  | '>='\n  | '<'\n  | '<='\n  | 'contains'\n\nexport const REPEAT_QUERY_OPS: RepeatQueryOp[] = [\n  '==',\n  '!=',\n  '>',\n  '>=',\n  '<',\n  '<=',\n  'contains',\n]\n\nexport interface RepeatQueryWhere {\n  fieldId: string\n  op: RepeatQueryOp\n  /** Literal, compared with type-aware coercion against stored values. */\n  value: string\n}\n\nexport interface RepeatQuery {\n  where?: RepeatQueryWhere[]\n  orderBy?: { fieldId: string; direction?: 'asc' | 'desc' }\n  limit?: number\n}\n\n/**\n * Parses the authoring shorthand `field op value` (e.g. `price <= 20`,\n * `tier == plus`, `tags contains red`). Null for unparseable input so\n * callers fail open (no filter) rather than filtering wrongly.\n */\nexport function parseRepeatFilter(input: string): RepeatQueryWhere | null {\n  const match = String(input ?? '')\n    .trim()\n    .match(/^([A-Za-z][A-Za-z0-9_]*)\\s*(==|!=|>=|<=|>|<|contains)\\s+(.+)$/)\n  if (!match) return null\n  return {\n    fieldId: match[1],\n    op: match[2] as RepeatQueryOp,\n    value: match[3].trim(),\n  }\n}\n\n/** Parses `field` or `field desc` into an orderBy config. */\nexport function parseRepeatSort(\n  input: string,\n): RepeatQuery['orderBy'] | null {\n  const match = String(input ?? '')\n    .trim()\n    .match(/^([A-Za-z][A-Za-z0-9_]*)(?:\\s+(asc|desc))?$/i)\n  if (!match) return null\n  return {\n    fieldId: match[1],\n    direction: match[2]?.toLowerCase() === 'desc' ? 'desc' : 'asc',\n  }\n}\n\nconst comparable = (value: unknown): number | string | null => {\n  if (typeof value === 'number') return value\n  if (typeof value === 'boolean') return value ? 1 : 0\n  if (typeof value === 'string') {\n    const numeric = Number(value)\n    return Number.isFinite(numeric) && value.trim() !== '' ? numeric : value\n  }\n  return null\n}\n\nfunction matches(stored: unknown, where: RepeatQueryWhere): boolean {\n  const { op, value } = where\n  if (op === 'contains') {\n    if (Array.isArray(stored)) {\n      return stored.some(\n        (entry) => String(entry).toLowerCase() === value.toLowerCase(),\n      )\n    }\n    return String(stored ?? '')\n      .toLowerCase()\n      .includes(value.toLowerCase())\n  }\n  if (op === '==' || op === '!=') {\n    const equal =\n      typeof stored === 'boolean'\n        ? String(stored) === value.toLowerCase()\n        : String(stored ?? '') === value\n    return op === '==' ? equal : !equal\n  }\n  const left = comparable(stored)\n  const right = comparable(value)\n  if (left == null || right == null || typeof left !== typeof right) {\n    return false\n  }\n  switch (op) {\n    case '>':\n      return left > right\n    case '>=':\n      return left >= right\n    case '<':\n      return left < right\n    case '<=':\n      return left <= right\n  }\n  return false\n}\n\n/**\n * Applies where/orderBy/limit to in-memory rows. A clause compares the\n * stored value whatever field it names, so rows with no declared field\n * model filter too; timestamps compare numerically (epoch millis storage).\n */\nexport function applyRepeatQuery<Row extends Record<string, unknown>>(\n  rows: Row[],\n  query: RepeatQuery,\n): Row[] {\n  let result = rows\n  for (const where of query.where ?? []) {\n    result = result.filter((row) => matches(row[where.fieldId], where))\n  }\n  if (query.orderBy) {\n    const { fieldId, direction } = query.orderBy\n    const sign = direction === 'desc' ? -1 : 1\n    result = [...result].sort((a, b) => {\n      const left = comparable(a[fieldId])\n      const right = comparable(b[fieldId])\n      if (left == null) return 1\n      if (right == null) return -1\n      if (typeof left === 'number' && typeof right === 'number') {\n        return (left - right) * sign\n      }\n      return String(left).localeCompare(String(right)) * sign\n    })\n  }\n  if (query.limit != null && query.limit > 0) {\n    result = result.slice(0, query.limit)\n  }\n  return result\n}\n"],"names":["REPEAT_QUERY_OPS","parseRepeatFilter","input","match","String","trim","fieldId","op","value","parseRepeatSort","direction","toLowerCase","comparable","numeric","Number","isFinite","matches","stored","where","Array","isArray","some","entry","includes","equal","left","right","applyRepeatQuery","rows","query","result","filter","row","orderBy","sign","sort","a","b","localeCompare","limit","slice"],"mappings":"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"}

package/src/lib/app-utils/repeat-sources.d.ts

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 import type { AglynAttributeSchema } from '../foundation/definitions/components.types';
+import type { EntityPickerKind } from './entity-picker-context';
 import type { RepeatableDataset } from './expand-repeatables';
 /**
  * Where a repeat's rows come from, for the editor (AGL-3111).
@@ -78,6 +79,14 @@ export interface RepeatSource {
      * component attribute is. The panel names the field after `keyProp`.
      */
     keyAttribute: Omit<AglynAttributeSchema, 'name'>;
+    /**
+     * The entity picker kind a key names, when a key is an entity the picker
+     * lists. With it, the insert-token menu inside the repeat names the entity
+     * through the picker and offers `{{item.<field>}}` for each field the
+     * entity declares (`EntityPickerContextValue.entityFields`). Without it the
+     * menu offers no item tokens and authors type them.
+     */
+    entityKind?: EntityPickerKind;
     /**
      * Reads one key's rows for the besigner's canvas preview and badge. A React
      * hook: the editor mounts one reader per key and calls it unconditionally,

package/src/lib/app-utils/repeat-sources.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/repeat-sources.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { AglynAttributeSchema } from '../foundation/definitions/components.types'\nimport type { RepeatableDataset } from './expand-repeatables'\n\n/**\n * Where a repeat's rows come from, for the editor (AGL-3111).\n *\n * Any element can repeat, and the platform decides what a repeat MEANS — the\n * scope, the copies, the bounds (`expand-repeatables.ts`). What it does not\n * decide is what an element repeats OVER. That belongs to the plugin that owns\n * the rows, which registers a source here from the registration function its\n * loader calls by name. Core names no source.\n *\n * Reached by path, never through a barrel: nothing on a published page asks\n * where rows come from, so nothing here is in a published page's download.\n */\n\n/**\n * What a source answers for one key.\n *\n * - `loading` — no answer yet.\n * - `missing` — the key names nothing this site may use. The published page\n *   renders the element once, as written.\n * - `error` — the read failed. Nothing is known about the rows.\n * - `ready` — the rows, read and bounded exactly as the published page's\n *   composition reads them.\n */\nexport type RepeatRowsAnswer =\n  | { status: 'loading' }\n  | { status: 'missing' }\n  | { status: 'error' }\n  | {\n      status: 'ready'\n      /** The name authors know the entry by, for the canvas badge. */\n      label: string\n      /**\n       * The rows under every key the expansion looks them up by: the key as\n       * the node stores it, the entry's id, and each entry a one-hop reference\n       * in the rows reads (`{{item.ref.field}}`).\n       */\n      rowsByKey: Readonly<Record<string, RepeatableDataset>>\n    }\n\n/** One read a source is asked for. */\nexport interface RepeatRowsRequest {\n  /** The site the canvas edits. A source answers only what it may show. */\n  hostId: string\n  /** The key exactly as the node stores it. */\n  key: string\n}\n\n/** One kind of thing an element can repeat over. */\nexport interface RepeatSource {\n  /** Stable id, e.g. the plugin's name for the kind. */\n  id: string\n  /** What the Attributes panel calls the kind. */\n  label: string\n  /**\n   * The node prop the chosen key persists under. Persisted in documents, so a\n   * source never renames it.\n   */\n  keyProp: string\n  /**\n   * The attribute that picks a key, drawn by the Attributes panel as any\n   * component attribute is. The panel names the field after `keyProp`.\n   */\n  keyAttribute: Omit<AglynAttributeSchema, 'name'>\n  /**\n   * Reads one key's rows for the besigner's canvas preview and badge. A React\n   * hook: the editor mounts one reader per key and calls it unconditionally,\n   * so its identity must not change after registration.\n   */\n  useRows(request: RepeatRowsRequest): RepeatRowsAnswer\n}\n\nconst sources = new Map<string, RepeatSource>()\nconst listeners = new Set<() => void>()\nlet version = 0\n/**\n * Replaced only when the registered set changes, never rebuilt per call: it is\n * the snapshot `useSyncExternalStore` compares, and a fresh array every time\n * is a render loop rather than a wasted allocation.\n */\nlet snapshot: readonly RepeatSource[] = []\n\nconst notify = () => {\n  version += 1\n  snapshot = [...sources.values()]\n  for (const listener of [...listeners]) listener()\n}\n\n/**\n * Registers a source, replacing any registered under its id. Returns the\n * unregister, which removes the source only if it is still the one registered.\n *\n * Call it from a registration function the plugin loader calls BY NAME, never\n * from a module's top level: a bundler deletes a module imported only for its\n * side effect when its package says it has none (AGL-3025).\n */\nexport function registerRepeatSource(source: RepeatSource): () => void {\n  if (sources.get(source.id) !== source) {\n    sources.set(source.id, source)\n    notify()\n  }\n  return () => {\n    if (sources.get(source.id) !== source) return\n    sources.delete(source.id)\n    notify()\n  }\n}\n\n/**\n * Every registered source, in registration order. The SAME array until the\n * registered set changes, so it can be read as a store snapshot.\n */\nexport function listRepeatSources(): readonly RepeatSource[] {\n  return snapshot\n}\n\n/** The source registered under `id`. */\nexport function getRepeatSource(id: string): RepeatSource | undefined {\n  return sources.get(id)\n}\n\n/** Called after the registered set changes. Returns the unsubscribe. */\nexport function subscribeRepeatSources(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/** Moves on every change — the snapshot `useSyncExternalStore` reads. */\nexport function getRepeatSourcesVersion(): number {\n  return version\n}\n\n/**\n * The registered source a node repeats over, and the key it names, trimmed.\n * `undefined` for a node that repeats over nothing a registered source owns.\n */\nexport function repeatSourceOf(\n  node: unknown,\n): { source: RepeatSource; key: string } | undefined {\n  const props = (node as { props?: Record<string, unknown> } | undefined)?.props\n  if (!props) return undefined\n  for (const source of sources.values()) {\n    const value = props[source.keyProp]\n    const key = typeof value === 'string' ? value.trim() : ''\n    if (key) return { source, key }\n  }\n  return undefined\n}\n"],"names":["sources","Map","listeners","Set","version","snapshot","notify","values","listener","registerRepeatSource","source","get","id","set","delete","listRepeatSources","getRepeatSource","subscribeRepeatSources","add","getRepeatSourcesVersion","repeatSourceOf","node","props","undefined","value","keyProp","key","trim"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GA4ED,MAAMA,UAAU,IAAIC;AACpB,MAAMC,YAAY,IAAIC;AACtB,IAAIC,UAAU;AACd;;;;CAIC,GACD,IAAIC,WAAoC,EAAE;AAE1C,MAAMC,SAAS;IACbF,WAAW;IACXC,WAAW;WAAIL,QAAQO,MAAM;KAAG;IAChC,KAAK,MAAMC,YAAY;WAAIN;KAAU,CAAEM;AACzC;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,qBAAqBC,MAAoB;IACvD,IAAIV,QAAQW,GAAG,CAACD,OAAOE,EAAE,MAAMF,QAAQ;QACrCV,QAAQa,GAAG,CAACH,OAAOE,EAAE,EAAEF;QACvBJ;IACF;IACA,OAAO;QACL,IAAIN,QAAQW,GAAG,CAACD,OAAOE,EAAE,MAAMF,QAAQ;QACvCV,QAAQc,MAAM,CAACJ,OAAOE,EAAE;QACxBN;IACF;AACF;AAEA;;;CAGC,GACD,OAAO,SAASS;IACd,OAAOV;AACT;AAEA,sCAAsC,GACtC,OAAO,SAASW,gBAAgBJ,EAAU;IACxC,OAAOZ,QAAQW,GAAG,CAACC;AACrB;AAEA,sEAAsE,GACtE,OAAO,SAASK,uBAAuBT,QAAoB;IACzDN,UAAUgB,GAAG,CAACV;IACd,OAAO;QACLN,UAAUY,MAAM,CAACN;IACnB;AACF;AAEA,uEAAuE,GACvE,OAAO,SAASW;IACd,OAAOf;AACT;AAEA;;;CAGC,GACD,OAAO,SAASgB,eACdC,IAAa;IAEb,MAAMC,QAASD,wBAAD,AAACA,KAA0DC,KAAK;IAC9E,IAAI,CAACA,OAAO,OAAOC;IACnB,KAAK,MAAMb,UAAUV,QAAQO,MAAM,GAAI;QACrC,MAAMiB,QAAQF,KAAK,CAACZ,OAAOe,OAAO,CAAC;QACnC,MAAMC,MAAM,OAAOF,UAAU,WAAWA,MAAMG,IAAI,KAAK;QACvD,IAAID,KAAK,OAAO;YAAEhB;YAAQgB;QAAI;IAChC;IACA,OAAOH;AACT"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/repeat-sources.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { AglynAttributeSchema } from '../foundation/definitions/components.types'\nimport type { EntityPickerKind } from './entity-picker-context'\nimport type { RepeatableDataset } from './expand-repeatables'\n\n/**\n * Where a repeat's rows come from, for the editor (AGL-3111).\n *\n * Any element can repeat, and the platform decides what a repeat MEANS — the\n * scope, the copies, the bounds (`expand-repeatables.ts`). What it does not\n * decide is what an element repeats OVER. That belongs to the plugin that owns\n * the rows, which registers a source here from the registration function its\n * loader calls by name. Core names no source.\n *\n * Reached by path, never through a barrel: nothing on a published page asks\n * where rows come from, so nothing here is in a published page's download.\n */\n\n/**\n * What a source answers for one key.\n *\n * - `loading` — no answer yet.\n * - `missing` — the key names nothing this site may use. The published page\n *   renders the element once, as written.\n * - `error` — the read failed. Nothing is known about the rows.\n * - `ready` — the rows, read and bounded exactly as the published page's\n *   composition reads them.\n */\nexport type RepeatRowsAnswer =\n  | { status: 'loading' }\n  | { status: 'missing' }\n  | { status: 'error' }\n  | {\n      status: 'ready'\n      /** The name authors know the entry by, for the canvas badge. */\n      label: string\n      /**\n       * The rows under every key the expansion looks them up by: the key as\n       * the node stores it, the entry's id, and each entry a one-hop reference\n       * in the rows reads (`{{item.ref.field}}`).\n       */\n      rowsByKey: Readonly<Record<string, RepeatableDataset>>\n    }\n\n/** One read a source is asked for. */\nexport interface RepeatRowsRequest {\n  /** The site the canvas edits. A source answers only what it may show. */\n  hostId: string\n  /** The key exactly as the node stores it. */\n  key: string\n}\n\n/** One kind of thing an element can repeat over. */\nexport interface RepeatSource {\n  /** Stable id, e.g. the plugin's name for the kind. */\n  id: string\n  /** What the Attributes panel calls the kind. */\n  label: string\n  /**\n   * The node prop the chosen key persists under. Persisted in documents, so a\n   * source never renames it.\n   */\n  keyProp: string\n  /**\n   * The attribute that picks a key, drawn by the Attributes panel as any\n   * component attribute is. The panel names the field after `keyProp`.\n   */\n  keyAttribute: Omit<AglynAttributeSchema, 'name'>\n  /**\n   * The entity picker kind a key names, when a key is an entity the picker\n   * lists. With it, the insert-token menu inside the repeat names the entity\n   * through the picker and offers `{{item.<field>}}` for each field the\n   * entity declares (`EntityPickerContextValue.entityFields`). Without it the\n   * menu offers no item tokens and authors type them.\n   */\n  entityKind?: EntityPickerKind\n  /**\n   * Reads one key's rows for the besigner's canvas preview and badge. A React\n   * hook: the editor mounts one reader per key and calls it unconditionally,\n   * so its identity must not change after registration.\n   */\n  useRows(request: RepeatRowsRequest): RepeatRowsAnswer\n}\n\nconst sources = new Map<string, RepeatSource>()\nconst listeners = new Set<() => void>()\nlet version = 0\n/**\n * Replaced only when the registered set changes, never rebuilt per call: it is\n * the snapshot `useSyncExternalStore` compares, and a fresh array every time\n * is a render loop rather than a wasted allocation.\n */\nlet snapshot: readonly RepeatSource[] = []\n\nconst notify = () => {\n  version += 1\n  snapshot = [...sources.values()]\n  for (const listener of [...listeners]) listener()\n}\n\n/**\n * Registers a source, replacing any registered under its id. Returns the\n * unregister, which removes the source only if it is still the one registered.\n *\n * Call it from a registration function the plugin loader calls BY NAME, never\n * from a module's top level: a bundler deletes a module imported only for its\n * side effect when its package says it has none (AGL-3025).\n */\nexport function registerRepeatSource(source: RepeatSource): () => void {\n  if (sources.get(source.id) !== source) {\n    sources.set(source.id, source)\n    notify()\n  }\n  return () => {\n    if (sources.get(source.id) !== source) return\n    sources.delete(source.id)\n    notify()\n  }\n}\n\n/**\n * Every registered source, in registration order. The SAME array until the\n * registered set changes, so it can be read as a store snapshot.\n */\nexport function listRepeatSources(): readonly RepeatSource[] {\n  return snapshot\n}\n\n/** The source registered under `id`. */\nexport function getRepeatSource(id: string): RepeatSource | undefined {\n  return sources.get(id)\n}\n\n/** Called after the registered set changes. Returns the unsubscribe. */\nexport function subscribeRepeatSources(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/** Moves on every change — the snapshot `useSyncExternalStore` reads. */\nexport function getRepeatSourcesVersion(): number {\n  return version\n}\n\n/**\n * The registered source a node repeats over, and the key it names, trimmed.\n * `undefined` for a node that repeats over nothing a registered source owns.\n */\nexport function repeatSourceOf(\n  node: unknown,\n): { source: RepeatSource; key: string } | undefined {\n  const props = (node as { props?: Record<string, unknown> } | undefined)?.props\n  if (!props) return undefined\n  for (const source of sources.values()) {\n    const value = props[source.keyProp]\n    const key = typeof value === 'string' ? value.trim() : ''\n    if (key) return { source, key }\n  }\n  return undefined\n}\n"],"names":["sources","Map","listeners","Set","version","snapshot","notify","values","listener","registerRepeatSource","source","get","id","set","delete","listRepeatSources","getRepeatSource","subscribeRepeatSources","add","getRepeatSourcesVersion","repeatSourceOf","node","props","undefined","value","keyProp","key","trim"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAqFD,MAAMA,UAAU,IAAIC;AACpB,MAAMC,YAAY,IAAIC;AACtB,IAAIC,UAAU;AACd;;;;CAIC,GACD,IAAIC,WAAoC,EAAE;AAE1C,MAAMC,SAAS;IACbF,WAAW;IACXC,WAAW;WAAIL,QAAQO,MAAM;KAAG;IAChC,KAAK,MAAMC,YAAY;WAAIN;KAAU,CAAEM;AACzC;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,qBAAqBC,MAAoB;IACvD,IAAIV,QAAQW,GAAG,CAACD,OAAOE,EAAE,MAAMF,QAAQ;QACrCV,QAAQa,GAAG,CAACH,OAAOE,EAAE,EAAEF;QACvBJ;IACF;IACA,OAAO;QACL,IAAIN,QAAQW,GAAG,CAACD,OAAOE,EAAE,MAAMF,QAAQ;QACvCV,QAAQc,MAAM,CAACJ,OAAOE,EAAE;QACxBN;IACF;AACF;AAEA;;;CAGC,GACD,OAAO,SAASS;IACd,OAAOV;AACT;AAEA,sCAAsC,GACtC,OAAO,SAASW,gBAAgBJ,EAAU;IACxC,OAAOZ,QAAQW,GAAG,CAACC;AACrB;AAEA,sEAAsE,GACtE,OAAO,SAASK,uBAAuBT,QAAoB;IACzDN,UAAUgB,GAAG,CAACV;IACd,OAAO;QACLN,UAAUY,MAAM,CAACN;IACnB;AACF;AAEA,uEAAuE,GACvE,OAAO,SAASW;IACd,OAAOf;AACT;AAEA;;;CAGC,GACD,OAAO,SAASgB,eACdC,IAAa;IAEb,MAAMC,QAASD,wBAAD,AAACA,KAA0DC,KAAK;IAC9E,IAAI,CAACA,OAAO,OAAOC;IACnB,KAAK,MAAMb,UAAUV,QAAQO,MAAM,GAAI;QACrC,MAAMiB,QAAQF,KAAK,CAACZ,OAAOe,OAAO,CAAC;QACnC,MAAMC,MAAM,OAAOF,UAAU,WAAWA,MAAMG,IAAI,KAAK;QACvD,IAAID,KAAK,OAAO;YAAEhB;YAAQgB;QAAI;IAChC;IACA,OAAOH;AACT"}

package/src/lib/app-utils/retained-refusals.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** `orgs/{orgId}/retainedRefusals/{personKey}` — server-only, closed to every client. */
+export declare const RETAINED_REFUSALS_COLLECTION = "retainedRefusals";
+/** When a refusal was retained, epoch ms: on each entry and on the document. */
+export declare const RETAINED_AT_FIELD = "retainedAtMs";
+/** The record an entry was retained from, on each entry. */
+export declare const RETAINED_FROM_RECORD_FIELD = "retainedFromContactId";
+/** Every refusal one person's record holds. */
+export interface RetainedRefusals {
+    /** Each site's refusal entry, keyed by the site, as the record stored it. */
+    byHost: Record<string, Record<string, unknown>>;
+    /** The top-level refusal, which names no site and is honored against every one. */
+    unscoped: boolean;
+}
+type Doc = Record<string, unknown>;
+/**
+ * Every refusal `record` holds, or `null` when it holds none.
+ *
+ * Every SITE, not the sites of one group: a record can carry a refusal for a
+ * site that let it go earlier, or one a consent group change carried onto
+ * it, and each is still somebody's "no". Reads a retained document as well
+ * as a person record, since the two share their field names.
+ */
+export declare function refusalsOf(record: Doc | null | undefined): RetainedRefusals | null;
+/**
+ * `record` with what was retained for the same person laid over it — the
+ * record a reader of the stored basis should read.
+ *
+ * Per retained site, the record's entry stands only when it is a GRANT whose
+ * date is strictly after the refusal's (the person's own date, or when it was
+ * retained where they gave none). Anything else — no entry, a refusal of its
+ * own, an older or undated grant — reads as the retained refusal. The
+ * unscoped refusal is laid on only where the record gives no top-level
+ * answer of its own.
+ *
+ * With nothing retained the record comes back as it was, `null` included, so
+ * a person with no retained refusal reads exactly as they did before this
+ * store existed.
+ */
+export declare function withRetainedRefusals(record: Doc | null | undefined, retained: RetainedRefusals | null | undefined): Doc | null;
+/**
+ * The entries one retention writes: each refusal stamped with when it was
+ * retained and from which record, keyed by site.
+ */
+export declare function retainedEntries(retained: RetainedRefusals, recordId: string, nowMs: number): Record<string, Doc>;
+/**
+ * One retained document's share of a consent group change's carry `to ← from`
+ * — the dotted-path patch that gives `to` the refusal `from` holds, or `null`
+ * when `from` holds none or `to` already has an entry.
+ *
+ * Never overwrites: every entry in this store is a refusal, so an entry on
+ * `to` is already the answer, and a re-run after a crash writes nothing.
+ */
+export declare function retainedRefusalCarry(retained: Doc | null | undefined, carry: {
+    toHostId: string;
+    fromHostId: string;
+}, changeId: string): Doc | null;
+export {};

package/src/lib/app-utils/retained-refusals.js

@@ -0,0 +1,186 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * RETAINED REFUSALS — a person's "no" outlives the record it was written on
+ * (AGL-3338).
+ *
+ * ## Where a refusal lives, and why that is not enough
+ *
+ * A person's refusal of marketing email is stored on the record an operator
+ * keeps about them: an entry under {@link MARKETING_CONSENT_BY_HOST_FIELD}
+ * for the site they refused, or the top-level field for a refusal that names
+ * no site. The list gate reads it there. An operator adding people to a list
+ * by hand or by import states that they have permission to email them, and a
+ * stored refusal is the one fact that attestation cannot overrule: the
+ * person said no, and no operator's word turns that into a yes.
+ *
+ * The record, though, is the operator's, and the operator may delete it. A
+ * deleted record is an address with no record at all, which reads as
+ * `unrecorded` — nothing known either way — and the attestation is accepted.
+ * Deleting somebody from a CRM would then be the way to mail a person who
+ * refused, which is the one outcome the refusal exists to prevent.
+ *
+ * So a refusal is not the record's to lose. When a holder lets a shared
+ * record go, its refusal entries stay on the document for the holders that
+ * remain. When the last holder lets go, every refusal the document holds —
+ * every site's, not only the deleting holder's, and the unscoped one — is
+ * copied into {@link RETAINED_REFUSALS_COLLECTION} in the same transaction
+ * that deletes it, and the list gate reads that store beside the records.
+ *
+ * ## No address
+ *
+ * One document per person, keyed by `personKey` — the sha256 of the
+ * normalized address — and holding no address, as a suppression row keyed
+ * the same way holds none. The store answers one question about an address
+ * somebody already has in hand, "did this person refuse", and it has no
+ * business being a list of the people who did.
+ *
+ * ## The same field names as the record
+ *
+ * An entry keeps the record's own names, so a record merged with what was
+ * retained ({@link withRetainedRefusals}) is read by `readMarketingBasis`
+ * like any other — a second set of names would be a second parser for the
+ * two to disagree through. Each entry adds when it was retained and from
+ * which record.
+ *
+ * ## A newer grant wins, and nothing else does
+ *
+ * The person may come back. Signing up again on a form that asks writes a
+ * grant, and a grant given after the refusal is the person changing their
+ * mind — the merge lets it stand. A grant that is not strictly newer, a grant
+ * with no date, and every entry that is not a grant read as the refusal
+ * still: withholding mail is recoverable, and sending it is not.
+ *
+ * ## Carried like the refusals it came from
+ *
+ * The list gate reads a refusal across the CURRENT consent group, so two
+ * sites separating would stop one seeing the other's retained refusals. A
+ * consent group change therefore carries this store as it carries the site
+ * suppression lists and a record's own refusals: {@link retainedRefusalCarry}
+ * decides one document, and the executor pages the store.
+ */ import { MARKETING_CONSENT_BY_HOST_FIELD, MARKETING_CONSENT_FIELD } from "./marketing-consent.js";
+/** `orgs/{orgId}/retainedRefusals/{personKey}` — server-only, closed to every client. */ export const RETAINED_REFUSALS_COLLECTION = 'retainedRefusals';
+/** When a refusal was retained, epoch ms: on each entry and on the document. */ export const RETAINED_AT_FIELD = 'retainedAtMs';
+/** The record an entry was retained from, on each entry. */ export const RETAINED_FROM_RECORD_FIELD = 'retainedFromContactId';
+/** When the person gave the answer an entry records, as every writer stamps it. */ const GIVEN_AT_FIELD = 'marketingConsentAtMs';
+function mapOf(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+/** Epoch millis off a number, a `Date` or either SDK's `Timestamp`, else `null`. */ function millisOf(value) {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+    if (value instanceof Date) return value.getTime();
+    const toMillis = value == null ? void 0 : value.toMillis;
+    if (typeof toMillis === 'function') {
+        const millis = Number(toMillis.call(value));
+        return Number.isFinite(millis) ? millis : null;
+    }
+    return null;
+}
+/**
+ * Every refusal `record` holds, or `null` when it holds none.
+ *
+ * Every SITE, not the sites of one group: a record can carry a refusal for a
+ * site that let it go earlier, or one a consent group change carried onto
+ * it, and each is still somebody's "no". Reads a retained document as well
+ * as a person record, since the two share their field names.
+ */ export function refusalsOf(record) {
+    var _mapOf;
+    if (!record) return null;
+    const byHost = {};
+    for (const [hostId, value] of Object.entries((_mapOf = mapOf(record[MARKETING_CONSENT_BY_HOST_FIELD])) != null ? _mapOf : {})){
+        const entry = mapOf(value);
+        if (hostId && (entry == null ? void 0 : entry[MARKETING_CONSENT_FIELD]) === false) byHost[hostId] = _extends({}, entry);
+    }
+    const unscoped = record[MARKETING_CONSENT_FIELD] === false;
+    return unscoped || Object.keys(byHost).length ? {
+        byHost,
+        unscoped
+    } : null;
+}
+/** When a retained refusal counts as given: the person's own date, else the retention's. */ function refusedAtMs(refusal) {
+    var _millisOf;
+    return (_millisOf = millisOf(refusal[GIVEN_AT_FIELD])) != null ? _millisOf : millisOf(refusal[RETAINED_AT_FIELD]);
+}
+/**
+ * `record` with what was retained for the same person laid over it — the
+ * record a reader of the stored basis should read.
+ *
+ * Per retained site, the record's entry stands only when it is a GRANT whose
+ * date is strictly after the refusal's (the person's own date, or when it was
+ * retained where they gave none). Anything else — no entry, a refusal of its
+ * own, an older or undated grant — reads as the retained refusal. The
+ * unscoped refusal is laid on only where the record gives no top-level
+ * answer of its own.
+ *
+ * With nothing retained the record comes back as it was, `null` included, so
+ * a person with no retained refusal reads exactly as they did before this
+ * store existed.
+ */ export function withRetainedRefusals(record, retained) {
+    var _ref, _mapOf;
+    const hosts = Object.entries((_ref = retained == null ? void 0 : retained.byHost) != null ? _ref : {});
+    if (!retained || !hosts.length && !retained.unscoped) return record != null ? record : null;
+    const base = record != null ? record : {};
+    const byHost = _extends({}, (_mapOf = mapOf(base[MARKETING_CONSENT_BY_HOST_FIELD])) != null ? _mapOf : {});
+    for (const [hostId, refusal] of hosts){
+        const entry = mapOf(byHost[hostId]);
+        const grantedAt = (entry == null ? void 0 : entry[MARKETING_CONSENT_FIELD]) === true ? millisOf(entry[GIVEN_AT_FIELD]) : null;
+        const refusedAt = refusedAtMs(refusal);
+        const newerGrant = grantedAt !== null && refusedAt !== null && grantedAt > refusedAt;
+        if (!newerGrant) byHost[hostId] = refusal;
+    }
+    const merged = _extends({}, base, {
+        [MARKETING_CONSENT_BY_HOST_FIELD]: byHost
+    });
+    if (retained.unscoped && typeof base[MARKETING_CONSENT_FIELD] !== 'boolean') {
+        merged[MARKETING_CONSENT_FIELD] = false;
+    }
+    return merged;
+}
+/**
+ * The entries one retention writes: each refusal stamped with when it was
+ * retained and from which record, keyed by site.
+ */ export function retainedEntries(retained, recordId, nowMs) {
+    return Object.fromEntries(Object.entries(retained.byHost).map(([hostId, refusal])=>[
+            hostId,
+            _extends({}, refusal, {
+                [RETAINED_AT_FIELD]: nowMs,
+                [RETAINED_FROM_RECORD_FIELD]: recordId
+            })
+        ]));
+}
+/**
+ * One retained document's share of a consent group change's carry `to ← from`
+ * — the dotted-path patch that gives `to` the refusal `from` holds, or `null`
+ * when `from` holds none or `to` already has an entry.
+ *
+ * Never overwrites: every entry in this store is a refusal, so an entry on
+ * `to` is already the answer, and a re-run after a crash writes nothing.
+ */ export function retainedRefusalCarry(retained, carry, changeId) {
+    var _mapOf;
+    const byHost = (_mapOf = mapOf(retained == null ? void 0 : retained[MARKETING_CONSENT_BY_HOST_FIELD])) != null ? _mapOf : {};
+    const source = mapOf(byHost[carry.fromHostId]);
+    if ((source == null ? void 0 : source[MARKETING_CONSENT_FIELD]) !== false) return null;
+    if (byHost[carry.toHostId] !== undefined) return null;
+    return {
+        [`${MARKETING_CONSENT_BY_HOST_FIELD}.${carry.toHostId}`]: _extends({}, source, {
+            carriedFromHostId: carry.fromHostId,
+            carriedByChangeId: changeId
+        })
+    };
+}
+
+//# sourceMappingURL=retained-refusals.js.map

package/src/lib/app-utils/retained-refusals.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/retained-refusals.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * RETAINED REFUSALS — a person's \"no\" outlives the record it was written on\n * (AGL-3338).\n *\n * ## Where a refusal lives, and why that is not enough\n *\n * A person's refusal of marketing email is stored on the record an operator\n * keeps about them: an entry under {@link MARKETING_CONSENT_BY_HOST_FIELD}\n * for the site they refused, or the top-level field for a refusal that names\n * no site. The list gate reads it there. An operator adding people to a list\n * by hand or by import states that they have permission to email them, and a\n * stored refusal is the one fact that attestation cannot overrule: the\n * person said no, and no operator's word turns that into a yes.\n *\n * The record, though, is the operator's, and the operator may delete it. A\n * deleted record is an address with no record at all, which reads as\n * `unrecorded` — nothing known either way — and the attestation is accepted.\n * Deleting somebody from a CRM would then be the way to mail a person who\n * refused, which is the one outcome the refusal exists to prevent.\n *\n * So a refusal is not the record's to lose. When a holder lets a shared\n * record go, its refusal entries stay on the document for the holders that\n * remain. When the last holder lets go, every refusal the document holds —\n * every site's, not only the deleting holder's, and the unscoped one — is\n * copied into {@link RETAINED_REFUSALS_COLLECTION} in the same transaction\n * that deletes it, and the list gate reads that store beside the records.\n *\n * ## No address\n *\n * One document per person, keyed by `personKey` — the sha256 of the\n * normalized address — and holding no address, as a suppression row keyed\n * the same way holds none. The store answers one question about an address\n * somebody already has in hand, \"did this person refuse\", and it has no\n * business being a list of the people who did.\n *\n * ## The same field names as the record\n *\n * An entry keeps the record's own names, so a record merged with what was\n * retained ({@link withRetainedRefusals}) is read by `readMarketingBasis`\n * like any other — a second set of names would be a second parser for the\n * two to disagree through. Each entry adds when it was retained and from\n * which record.\n *\n * ## A newer grant wins, and nothing else does\n *\n * The person may come back. Signing up again on a form that asks writes a\n * grant, and a grant given after the refusal is the person changing their\n * mind — the merge lets it stand. A grant that is not strictly newer, a grant\n * with no date, and every entry that is not a grant read as the refusal\n * still: withholding mail is recoverable, and sending it is not.\n *\n * ## Carried like the refusals it came from\n *\n * The list gate reads a refusal across the CURRENT consent group, so two\n * sites separating would stop one seeing the other's retained refusals. A\n * consent group change therefore carries this store as it carries the site\n * suppression lists and a record's own refusals: {@link retainedRefusalCarry}\n * decides one document, and the executor pages the store.\n */\n\nimport {\n  MARKETING_CONSENT_BY_HOST_FIELD,\n  MARKETING_CONSENT_FIELD,\n} from './marketing-consent'\n\n/** `orgs/{orgId}/retainedRefusals/{personKey}` — server-only, closed to every client. */\nexport const RETAINED_REFUSALS_COLLECTION = 'retainedRefusals'\n\n/** When a refusal was retained, epoch ms: on each entry and on the document. */\nexport const RETAINED_AT_FIELD = 'retainedAtMs'\n\n/** The record an entry was retained from, on each entry. */\nexport const RETAINED_FROM_RECORD_FIELD = 'retainedFromContactId'\n\n/** When the person gave the answer an entry records, as every writer stamps it. */\nconst GIVEN_AT_FIELD = 'marketingConsentAtMs'\n\n/** Every refusal one person's record holds. */\nexport interface RetainedRefusals {\n  /** Each site's refusal entry, keyed by the site, as the record stored it. */\n  byHost: Record<string, Record<string, unknown>>\n  /** The top-level refusal, which names no site and is honored against every one. */\n  unscoped: boolean\n}\n\ntype Doc = Record<string, unknown>\n\nfunction mapOf(value: unknown): Doc | null {\n  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Doc) : null\n}\n\n/** Epoch millis off a number, a `Date` or either SDK's `Timestamp`, else `null`. */\nfunction millisOf(value: unknown): number | null {\n  if (typeof value === 'number') return Number.isFinite(value) ? value : null\n  if (value instanceof Date) return value.getTime()\n  const toMillis = (value as { toMillis?: unknown } | null)?.toMillis\n  if (typeof toMillis === 'function') {\n    const millis = Number(toMillis.call(value))\n    return Number.isFinite(millis) ? millis : null\n  }\n  return null\n}\n\n/**\n * Every refusal `record` holds, or `null` when it holds none.\n *\n * Every SITE, not the sites of one group: a record can carry a refusal for a\n * site that let it go earlier, or one a consent group change carried onto\n * it, and each is still somebody's \"no\". Reads a retained document as well\n * as a person record, since the two share their field names.\n */\nexport function refusalsOf(record: Doc | null | undefined): RetainedRefusals | null {\n  if (!record) return null\n  const byHost: Record<string, Doc> = {}\n  for (const [hostId, value] of Object.entries(mapOf(record[MARKETING_CONSENT_BY_HOST_FIELD]) ?? {})) {\n    const entry = mapOf(value)\n    if (hostId && entry?.[MARKETING_CONSENT_FIELD] === false) byHost[hostId] = { ...entry }\n  }\n  const unscoped = record[MARKETING_CONSENT_FIELD] === false\n  return unscoped || Object.keys(byHost).length ? { byHost, unscoped } : null\n}\n\n/** When a retained refusal counts as given: the person's own date, else the retention's. */\nfunction refusedAtMs(refusal: Doc): number | null {\n  return millisOf(refusal[GIVEN_AT_FIELD]) ?? millisOf(refusal[RETAINED_AT_FIELD])\n}\n\n/**\n * `record` with what was retained for the same person laid over it — the\n * record a reader of the stored basis should read.\n *\n * Per retained site, the record's entry stands only when it is a GRANT whose\n * date is strictly after the refusal's (the person's own date, or when it was\n * retained where they gave none). Anything else — no entry, a refusal of its\n * own, an older or undated grant — reads as the retained refusal. The\n * unscoped refusal is laid on only where the record gives no top-level\n * answer of its own.\n *\n * With nothing retained the record comes back as it was, `null` included, so\n * a person with no retained refusal reads exactly as they did before this\n * store existed.\n */\nexport function withRetainedRefusals(\n  record: Doc | null | undefined,\n  retained: RetainedRefusals | null | undefined,\n): Doc | null {\n  const hosts = Object.entries(retained?.byHost ?? {})\n  if (!retained || (!hosts.length && !retained.unscoped)) return record ?? null\n  const base = record ?? {}\n  const byHost: Doc = { ...(mapOf(base[MARKETING_CONSENT_BY_HOST_FIELD]) ?? {}) }\n  for (const [hostId, refusal] of hosts) {\n    const entry = mapOf(byHost[hostId])\n    const grantedAt = entry?.[MARKETING_CONSENT_FIELD] === true ? millisOf(entry[GIVEN_AT_FIELD]) : null\n    const refusedAt = refusedAtMs(refusal)\n    const newerGrant = grantedAt !== null && refusedAt !== null && grantedAt > refusedAt\n    if (!newerGrant) byHost[hostId] = refusal\n  }\n  const merged: Doc = { ...base, [MARKETING_CONSENT_BY_HOST_FIELD]: byHost }\n  if (retained.unscoped && typeof base[MARKETING_CONSENT_FIELD] !== 'boolean') {\n    merged[MARKETING_CONSENT_FIELD] = false\n  }\n  return merged\n}\n\n/**\n * The entries one retention writes: each refusal stamped with when it was\n * retained and from which record, keyed by site.\n */\nexport function retainedEntries(\n  retained: RetainedRefusals,\n  recordId: string,\n  nowMs: number,\n): Record<string, Doc> {\n  return Object.fromEntries(\n    Object.entries(retained.byHost).map(([hostId, refusal]) => [\n      hostId,\n      { ...refusal, [RETAINED_AT_FIELD]: nowMs, [RETAINED_FROM_RECORD_FIELD]: recordId },\n    ]),\n  )\n}\n\n/**\n * One retained document's share of a consent group change's carry `to ← from`\n * — the dotted-path patch that gives `to` the refusal `from` holds, or `null`\n * when `from` holds none or `to` already has an entry.\n *\n * Never overwrites: every entry in this store is a refusal, so an entry on\n * `to` is already the answer, and a re-run after a crash writes nothing.\n */\nexport function retainedRefusalCarry(\n  retained: Doc | null | undefined,\n  carry: { toHostId: string; fromHostId: string },\n  changeId: string,\n): Doc | null {\n  const byHost = mapOf(retained?.[MARKETING_CONSENT_BY_HOST_FIELD]) ?? {}\n  const source = mapOf(byHost[carry.fromHostId])\n  if (source?.[MARKETING_CONSENT_FIELD] !== false) return null\n  if (byHost[carry.toHostId] !== undefined) return null\n  return {\n    [`${MARKETING_CONSENT_BY_HOST_FIELD}.${carry.toHostId}`]: {\n      ...source,\n      carriedFromHostId: carry.fromHostId,\n      carriedByChangeId: changeId,\n    },\n  }\n}\n"],"names":["MARKETING_CONSENT_BY_HOST_FIELD","MARKETING_CONSENT_FIELD","RETAINED_REFUSALS_COLLECTION","RETAINED_AT_FIELD","RETAINED_FROM_RECORD_FIELD","GIVEN_AT_FIELD","mapOf","value","Array","isArray","millisOf","Number","isFinite","Date","getTime","toMillis","millis","call","refusalsOf","record","byHost","hostId","Object","entries","entry","unscoped","keys","length","refusedAtMs","refusal","withRetainedRefusals","retained","hosts","base","grantedAt","refusedAt","newerGrant","merged","retainedEntries","recordId","nowMs","fromEntries","map","retainedRefusalCarry","carry","changeId","source","fromHostId","toHostId","undefined","carriedFromHostId","carriedByChangeId"],"mappings":"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"}

package/src/lib/app-utils/scope-tokens.d.ts

@@ -247,3 +247,30 @@ export declare function scopeCovers(target: readonly string[] | undefined | null
  * org CDN URL. That keeps it safe to apply blindly at every pick site.
  */
 export declare function hostQualifiedCdnPath(cdnPath: string | undefined | null, visibleTo: readonly string[] | undefined | null, hostId: string | undefined | null): string | undefined;
+/** The map a scoped document records its visibility grants under. */
+export declare const SCOPE_GRANTS_FIELD = "sharing";
+/** The tokens a grant ADDED to `visibleTo`: seen through, never held. */
+export declare function grantedScopeTokens(doc: Readonly<Record<string, unknown>> | null | undefined): string[];
+/**
+ * The tokens that HOLD a document: `visibleTo` without the ones a grant
+ * added. Missing `visibleTo` is held by nobody, as it is seen by nobody.
+ *
+ * A site that created the document (`hostId`) or captured the person on it
+ * (`capturedByHostIds`) holds its token whatever the grants say: a record
+ * shared with a site that then captures the person itself is that site's
+ * own from the capture on, before anything re-evaluates the grants.
+ */
+export declare function heldScopeTokens(doc: Readonly<Record<string, unknown>> | null | undefined): string[];
+/**
+ * Whether a site HOLDS a document rather than only seeing it through a
+ * grant. The question a marketing audience, a list rule, a sequence and a
+ * holder count ask; {@link visibleToHost} is the one a reader asks.
+ */
+export declare function heldByHost(doc: Readonly<Record<string, unknown>> | null | undefined, hostId: string): boolean;
+/**
+ * Whether a site sees a document ONLY through a grant: it carries grants and
+ * the site does not hold it. The filter an audience sweep applies to what
+ * its scoped query returned — a document with no grants answers `false`, so
+ * every read that predates sharing keeps exactly the rows it had.
+ */
+export declare function seenOnlyThroughGrant(doc: Readonly<Record<string, unknown>> | null | undefined, hostId: string): boolean;

package/src/lib/app-utils/scope-tokens.js

@@ -327,5 +327,66 @@ export function isScopeToken(value) {
         ...tail
     ].join('/');
 }
+/*==========================================
+ * SEEN, AND HELD (AGL-3336).
+ *
+ * `visibleTo` answers one question, "who may see this", because it is the
+ * one field both enforcement layers can evaluate. A visibility GRANT — an
+ * org manager sharing a record with another site, by hand or by a rule —
+ * has to widen exactly that field, or the other site's lists, which are
+ * real `array-contains-any` queries, could never return the record.
+ *
+ * But a site a record was shared with does not HOLD it. It did not capture
+ * the person, it holds no consent from them, and letting go of the record
+ * is not its decision. So a document that carries a grant records which of
+ * its tokens the grant added, under `sharing.added`, and every question
+ * about holding — who may delete it, whose audience it joins, which site's
+ * list it enters — reads {@link heldScopeTokens} instead of `visibleTo`.
+ *
+ * A document without the field is held by everything that sees it, which
+ * is every document written before grants existed.
+ *=========================================*/ /** The map a scoped document records its visibility grants under. */ export const SCOPE_GRANTS_FIELD = 'sharing';
+/** The tokens a grant ADDED to `visibleTo`: seen through, never held. */ export function grantedScopeTokens(doc) {
+    const grants = (doc != null ? doc : {})[SCOPE_GRANTS_FIELD];
+    if (!grants || typeof grants !== 'object' || Array.isArray(grants)) return [];
+    const added = grants['added'];
+    return Array.isArray(added) ? added.filter((token)=>typeof token === 'string') : [];
+}
+/**
+ * The tokens that HOLD a document: `visibleTo` without the ones a grant
+ * added. Missing `visibleTo` is held by nobody, as it is seen by nobody.
+ *
+ * A site that created the document (`hostId`) or captured the person on it
+ * (`capturedByHostIds`) holds its token whatever the grants say: a record
+ * shared with a site that then captures the person itself is that site's
+ * own from the capture on, before anything re-evaluates the grants.
+ */ export function heldScopeTokens(doc) {
+    const visibleTo = (doc != null ? doc : {})['visibleTo'];
+    if (!Array.isArray(visibleTo)) return [];
+    const granted = new Set(grantedScopeTokens(doc));
+    const capturing = new Set();
+    const hostId = (doc != null ? doc : {})['hostId'];
+    if (typeof hostId === 'string' && hostId) capturing.add(hostScopeToken(hostId));
+    const captured = (doc != null ? doc : {})['capturedByHostIds'];
+    if (Array.isArray(captured)) {
+        for (const id of captured)if (typeof id === 'string' && id) capturing.add(hostScopeToken(id));
+    }
+    return visibleTo.filter((token)=>typeof token === 'string' && (!granted.has(token) || capturing.has(token)));
+}
+/**
+ * Whether a site HOLDS a document rather than only seeing it through a
+ * grant. The question a marketing audience, a list rule, a sequence and a
+ * holder count ask; {@link visibleToHost} is the one a reader asks.
+ */ export function heldByHost(doc, hostId) {
+    return visibleToHost(heldScopeTokens(doc), hostId);
+}
+/**
+ * Whether a site sees a document ONLY through a grant: it carries grants and
+ * the site does not hold it. The filter an audience sweep applies to what
+ * its scoped query returned — a document with no grants answers `false`, so
+ * every read that predates sharing keeps exactly the rows it had.
+ */ export function seenOnlyThroughGrant(doc, hostId) {
+    return grantedScopeTokens(doc).length > 0 && !heldByHost(doc, hostId);
+}
 
 //# sourceMappingURL=scope-tokens.js.map