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

package/src/lib/app-utils/wire-nodes.d.ts

@@ -16,22 +16,39 @@
  */
 /**
  * A published page's node map as it crosses from the server into the
- * browser, without the two fields the map already states (AGL-3401).
+ * browser, stating each node's id once (AGL-3401, AGL-3438).
  *
- * The map rides in the page's flight payload, inside its HTML, and on
- * aglyn.com it was 242 KB of it. Every node repeats its own key as `$id` and
- * its parent's key as `parentId`, though the key IS the id and the parent's
- * `nodes` list already says whose child it is. Both are random ids, which is
- * the part of the map compression does least with: dropping them took the
- * map from 34.5 KB to about 28.5 KB gzipped on that page.
+ * The map rides in the page's flight payload, inside its HTML, and it is
+ * nearly all of that payload: 346 KB of aglyn.com/press's 376 KB. A stored
+ * map names every node three times — as its key, as its `$id`, and in its
+ * parent's `nodes` list — and once more as `parentId` in each child. The
+ * ids are random, which is the part of the map compression does least with,
+ * so every repeat costs close to its full length on the wire.
+ *
+ * Packed, the map is a TREE in document order: each node is an entry
+ * `[id, fields, ...children]`, and a child is either its own entry, inlined
+ * where its parent lists it, or its bare id when the node is inlined
+ * somewhere else or is not in the map at all. The id is stated once, by its
+ * entry; `$id`, `parentId` and `nodes` are left out of `fields` whenever the
+ * entry's position says the same thing. On aglyn.com/press that is 6.8 KB
+ * less HTML on the wire than the AGL-3401 packing, which only dropped
+ * `$id` and `parentId`.
  *
  * `packNodesForWire` drops a field only when `unpackWireNodes` will put back
- * the same value — an `$id` that differs from its key, or a `parentId` no
- * single parent's `nodes` list agrees with, is left in place — so a node that
- * carries both comes back exactly as it left, well-formed map or not. (One
- * that carried neither comes back with them.) Unpacking is idempotent, which is
- * what lets a full map (a withheld panel's patch from `/api/screen/nodes`, a
- * members-only tree) be merged over a packed one and unpacked together.
+ * the same value — an `$id` that differs from its key, a `parentId` other
+ * than the parent the node is inlined under, or a `nodes` value that is not
+ * a list of ids stays in `fields` — so every node comes back equal to the
+ * one that left, well-formed map or not. (One that carried no `$id`, or no
+ * `parentId` under a parent that lists it, comes back with them.) A child
+ * two parents list is inlined under the first and named by id in the other,
+ * a cycle is cut where it closes, and a node no list reaches is an entry of
+ * its own at the top level — so every key comes back, in document order.
+ *
+ * Unpacking also takes the flat form — a full map, or one packed by the
+ * AGL-3401 format — and fills in each `$id` and `parentId` it can from the
+ * keys and `nodes` lists, so it is idempotent. That is what lets a full patch
+ * (a withheld panel from `/api/screen/nodes`) be merged over an unpacked map
+ * and unpacked again.
  *
  * Banner-free and dependency-free: the tenant's server page packs and its
  * client root unpacks, so it must be importable from both.
@@ -45,9 +62,11 @@ type WireNode = Record<string, unknown> & {
 /** A node map, packed or not. */
 export type WireNodeMap<N = WireNode> = Record<string, N | null | undefined>;
 /**
- * The map without each `$id` that equals its key and each `parentId` its
- * parent's `nodes` list states. A new map of new node objects; the argument
- * is never mutated, because the server's is the cached loader's.
+ * The map as a tree of entries in document order: every node reachable from
+ * a node no list names, then any node that leaves out (a cycle, or a subtree
+ * whose only parent is unreachable), each as an entry of its own. A new
+ * structure throughout; the argument is never mutated, because the server's
+ * is the cached loader's.
  *
  * Typed as the map it is handed rather than as a looser one: the packed form
  * has one reader, `unpackWireNodes`, and the prop it travels in is read
@@ -55,10 +74,11 @@ export type WireNodeMap<N = WireNode> = Record<string, N | null | undefined>;
  */
 export declare function packNodesForWire<M extends WireNodeMap | null | undefined>(nodes: M): M;
 /**
- * The map with every node's `$id` and `parentId` back, from its key and its
+ * The map with every node whole: from a packed tree, each entry back under
+ * its id with its `$id`, its `parentId` and its `nodes` list restored; from a
+ * flat map, each node's `$id` and `parentId` filled in from its key and its
  * parent's `nodes` list. A node that already carries either keeps its own,
- * so an unpacked map comes back equal and a packed one merged with an
- * unpacked patch comes back whole.
+ * so a full map comes back equal.
  */
 export declare function unpackWireNodes<M extends WireNodeMap | null | undefined>(nodes: M): M;
 export {};

package/src/lib/app-utils/wire-nodes.js

@@ -15,27 +15,51 @@
  * limitations under the License.
  */ /**
  * A published page's node map as it crosses from the server into the
- * browser, without the two fields the map already states (AGL-3401).
+ * browser, stating each node's id once (AGL-3401, AGL-3438).
  *
- * The map rides in the page's flight payload, inside its HTML, and on
- * aglyn.com it was 242 KB of it. Every node repeats its own key as `$id` and
- * its parent's key as `parentId`, though the key IS the id and the parent's
- * `nodes` list already says whose child it is. Both are random ids, which is
- * the part of the map compression does least with: dropping them took the
- * map from 34.5 KB to about 28.5 KB gzipped on that page.
+ * The map rides in the page's flight payload, inside its HTML, and it is
+ * nearly all of that payload: 346 KB of aglyn.com/press's 376 KB. A stored
+ * map names every node three times — as its key, as its `$id`, and in its
+ * parent's `nodes` list — and once more as `parentId` in each child. The
+ * ids are random, which is the part of the map compression does least with,
+ * so every repeat costs close to its full length on the wire.
+ *
+ * Packed, the map is a TREE in document order: each node is an entry
+ * `[id, fields, ...children]`, and a child is either its own entry, inlined
+ * where its parent lists it, or its bare id when the node is inlined
+ * somewhere else or is not in the map at all. The id is stated once, by its
+ * entry; `$id`, `parentId` and `nodes` are left out of `fields` whenever the
+ * entry's position says the same thing. On aglyn.com/press that is 6.8 KB
+ * less HTML on the wire than the AGL-3401 packing, which only dropped
+ * `$id` and `parentId`.
  *
  * `packNodesForWire` drops a field only when `unpackWireNodes` will put back
- * the same value — an `$id` that differs from its key, or a `parentId` no
- * single parent's `nodes` list agrees with, is left in place — so a node that
- * carries both comes back exactly as it left, well-formed map or not. (One
- * that carried neither comes back with them.) Unpacking is idempotent, which is
- * what lets a full map (a withheld panel's patch from `/api/screen/nodes`, a
- * members-only tree) be merged over a packed one and unpacked together.
+ * the same value — an `$id` that differs from its key, a `parentId` other
+ * than the parent the node is inlined under, or a `nodes` value that is not
+ * a list of ids stays in `fields` — so every node comes back equal to the
+ * one that left, well-formed map or not. (One that carried no `$id`, or no
+ * `parentId` under a parent that lists it, comes back with them.) A child
+ * two parents list is inlined under the first and named by id in the other,
+ * a cycle is cut where it closes, and a node no list reaches is an entry of
+ * its own at the top level — so every key comes back, in document order.
+ *
+ * Unpacking also takes the flat form — a full map, or one packed by the
+ * AGL-3401 format — and fills in each `$id` and `parentId` it can from the
+ * keys and `nodes` lists, so it is idempotent. That is what lets a full patch
+ * (a withheld panel from `/api/screen/nodes`) be merged over an unpacked map
+ * and unpacked again.
  *
  * Banner-free and dependency-free: the tenant's server page packs and its
  * client root unpacks, so it must be importable from both.
  */ /** A node as the map carries it: an object, keyed by its id. */ import { _ as _extends } from "@swc/helpers/_/_extends";
 import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * The one key a packed map has. `~` is outside the alphabet node ids are
+ * drawn from; a map that nevertheless has that key ships flat rather than
+ * risk being read back as a tree.
+ */ const WIRE_TREE_KEY = '~';
+const isNode = (value)=>Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+/** A `nodes` value the tree can carry as its children: ids, and only ids. */ const childIds = (node)=>Array.isArray(node.nodes) && node.nodes.length > 0 && node.nodes.every((child)=>typeof child === 'string') ? node.nodes : undefined;
 /** Each child id to the key of the node whose `nodes` list names it. */ function parentsOf(nodes) {
     const parents = new Map();
     const claimed = new Set();
@@ -53,43 +77,84 @@ import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_wi
     }
     return parents;
 }
+/** Whether `value` is a map packed by {@link packNodesForWire}. */ function isPackedTree(value) {
+    if (!value || typeof value !== 'object') return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === WIRE_TREE_KEY && Array.isArray(value[WIRE_TREE_KEY]);
+}
 /**
- * The map without each `$id` that equals its key and each `parentId` its
- * parent's `nodes` list states. A new map of new node objects; the argument
- * is never mutated, because the server's is the cached loader's.
+ * The map as a tree of entries in document order: every node reachable from
+ * a node no list names, then any node that leaves out (a cycle, or a subtree
+ * whose only parent is unreachable), each as an entry of its own. A new
+ * structure throughout; the argument is never mutated, because the server's
+ * is the cached loader's.
  *
  * Typed as the map it is handed rather than as a looser one: the packed form
  * has one reader, `unpackWireNodes`, and the prop it travels in is read
  * nowhere else, so a second type would buy a cast at both ends.
  */ export function packNodesForWire(nodes) {
     if (!nodes) return nodes;
-    const parents = parentsOf(nodes);
-    const packed = {};
-    for (const [key, node] of Object.entries(nodes)){
-        if (!node || typeof node !== 'object') {
-            packed[key] = node;
-            continue;
-        }
-        const { $id, parentId } = node, rest = _object_without_properties_loose(node, [
+    if (Object.prototype.hasOwnProperty.call(nodes, WIRE_TREE_KEY)) return nodes;
+    const map = nodes;
+    const listed = new Set();
+    for (const node of Object.values(map)){
+        var _childIds;
+        if (!isNode(node)) continue;
+        for (const child of (_childIds = childIds(node)) != null ? _childIds : [])listed.add(child);
+    }
+    const entered = new Set();
+    const enter = (key, parent)=>{
+        entered.add(key);
+        const node = map[key];
+        if (!isNode(node)) return [
+            key,
+            node
+        ];
+        const { $id, parentId, nodes: list } = node, rest = _object_without_properties_loose(node, [
             "$id",
-            "parentId"
+            "parentId",
+            "nodes"
         ]);
-        const out = rest;
-        if ($id !== key) out.$id = $id;
-        if (parentId !== undefined && parentId !== parents.get(key)) {
-            out.parentId = parentId;
+        const fields = rest;
+        if ('$id' in node && $id !== key) fields.$id = $id;
+        if ('parentId' in node && parentId !== parent) fields.parentId = parentId;
+        const children = childIds(node);
+        if (!children) {
+            if ('nodes' in node) fields.nodes = list;
+            return [
+                key,
+                fields
+            ];
+        }
+        const entry = [
+            key,
+            fields
+        ];
+        for (const child of children){
+            entry.push(Object.prototype.hasOwnProperty.call(map, child) && !entered.has(child) ? enter(child, key) : child);
         }
-        packed[key] = out;
+        return entry;
+    };
+    const tree = [];
+    for (const key of Object.keys(map)){
+        if (!listed.has(key) && !entered.has(key)) tree.push(enter(key, undefined));
+    }
+    for (const key of Object.keys(map)){
+        if (!entered.has(key)) tree.push(enter(key, undefined));
     }
-    return packed;
+    return {
+        [WIRE_TREE_KEY]: tree
+    };
 }
 /**
- * The map with every node's `$id` and `parentId` back, from its key and its
+ * The map with every node whole: from a packed tree, each entry back under
+ * its id with its `$id`, its `parentId` and its `nodes` list restored; from a
+ * flat map, each node's `$id` and `parentId` filled in from its key and its
  * parent's `nodes` list. A node that already carries either keeps its own,
- * so an unpacked map comes back equal and a packed one merged with an
- * unpacked patch comes back whole.
+ * so a full map comes back equal.
  */ export function unpackWireNodes(nodes) {
     if (!nodes) return nodes;
+    if (isPackedTree(nodes)) return unpackTree(nodes[WIRE_TREE_KEY]);
     const parents = parentsOf(nodes);
     const unpacked = {};
     for (const [key, node] of Object.entries(nodes)){
@@ -108,5 +173,26 @@ import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_wi
     }
     return unpacked;
 }
+function unpackTree(tree) {
+    const out = {};
+    const visit = (entry, parent)=>{
+        const [key, fields, ...children] = entry;
+        if (!isNode(fields)) {
+            out[key] = fields;
+            return;
+        }
+        const node = _extends({
+            $id: key
+        }, fields);
+        if (children.length) {
+            node.nodes = children.map((child)=>typeof child === 'string' ? child : child[0]);
+        }
+        if (parent !== undefined && !('parentId' in fields)) node.parentId = parent;
+        out[key] = node;
+        for (const child of children)if (typeof child !== 'string') visit(child, key);
+    };
+    for (const entry of tree)visit(entry, undefined);
+    return out;
+}
 
 //# sourceMappingURL=wire-nodes.js.map

package/src/lib/app-utils/wire-nodes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/wire-nodes.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 published page's node map as it crosses from the server into the\n * browser, without the two fields the map already states (AGL-3401).\n *\n * The map rides in the page's flight payload, inside its HTML, and on\n * aglyn.com it was 242 KB of it. Every node repeats its own key as `$id` and\n * its parent's key as `parentId`, though the key IS the id and the parent's\n * `nodes` list already says whose child it is. Both are random ids, which is\n * the part of the map compression does least with: dropping them took the\n * map from 34.5 KB to about 28.5 KB gzipped on that page.\n *\n * `packNodesForWire` drops a field only when `unpackWireNodes` will put back\n * the same value — an `$id` that differs from its key, or a `parentId` no\n * single parent's `nodes` list agrees with, is left in place — so a node that\n * carries both comes back exactly as it left, well-formed map or not. (One\n * that carried neither comes back with them.) Unpacking is idempotent, which is\n * what lets a full map (a withheld panel's patch from `/api/screen/nodes`, a\n * members-only tree) be merged over a packed one and unpacked together.\n *\n * Banner-free and dependency-free: the tenant's server page packs and its\n * client root unpacks, so it must be importable from both.\n */\n\n/** A node as the map carries it: an object, keyed by its id. */\ntype WireNode = Record<string, unknown> & {\n  $id?: unknown\n  parentId?: unknown\n  nodes?: unknown\n}\n\n/** A node map, packed or not. */\nexport type WireNodeMap<N = WireNode> = Record<string, N | null | undefined>\n\n/** Each child id to the key of the node whose `nodes` list names it. */\nfunction parentsOf(nodes: WireNodeMap): Map<string, string> {\n  const parents = new Map<string, string>()\n  const claimed = new Set<string>()\n  for (const [key, node] of Object.entries(nodes)) {\n    const children = node?.nodes\n    if (!Array.isArray(children)) continue\n    for (const child of children) {\n      if (typeof child !== 'string') continue\n      // A child two parents list has no single answer, so neither may stand\n      // in for the `parentId` it stores.\n      if (claimed.has(child)) parents.delete(child)\n      else parents.set(child, key)\n      claimed.add(child)\n    }\n  }\n  return parents\n}\n\n/**\n * The map without each `$id` that equals its key and each `parentId` its\n * parent's `nodes` list states. A new map of new node objects; the argument\n * is never mutated, because the server's is the cached loader's.\n *\n * Typed as the map it is handed rather than as a looser one: the packed form\n * has one reader, `unpackWireNodes`, and the prop it travels in is read\n * nowhere else, so a second type would buy a cast at both ends.\n */\nexport function packNodesForWire<M extends WireNodeMap | null | undefined>(\n  nodes: M,\n): M {\n  if (!nodes) return nodes\n  const parents = parentsOf(nodes)\n  const packed: WireNodeMap = {}\n  for (const [key, node] of Object.entries(nodes)) {\n    if (!node || typeof node !== 'object') {\n      packed[key] = node\n      continue\n    }\n    const { $id, parentId, ...rest } = node\n    const out: WireNode = rest\n    if ($id !== key) out.$id = $id\n    if (parentId !== undefined && parentId !== parents.get(key)) {\n      out.parentId = parentId\n    }\n    packed[key] = out\n  }\n  return packed as M\n}\n\n/**\n * The map with every node's `$id` and `parentId` back, from its key and its\n * parent's `nodes` list. A node that already carries either keeps its own,\n * so an unpacked map comes back equal and a packed one merged with an\n * unpacked patch comes back whole.\n */\nexport function unpackWireNodes<M extends WireNodeMap | null | undefined>(\n  nodes: M,\n): M {\n  if (!nodes) return nodes\n  const parents = parentsOf(nodes)\n  const unpacked: WireNodeMap = {}\n  for (const [key, node] of Object.entries(nodes)) {\n    if (!node || typeof node !== 'object') {\n      unpacked[key] = node\n      continue\n    }\n    const parent = parents.get(key)\n    const needsId = !('$id' in node)\n    const needsParent = !('parentId' in node) && parent !== undefined\n    unpacked[key] =\n      needsId || needsParent\n        ? {\n            ...(needsId ? { $id: key } : {}),\n            ...node,\n            ...(needsParent ? { parentId: parent } : {}),\n          }\n        : node\n  }\n  return unpacked as M\n}\n"],"names":["parentsOf","nodes","parents","Map","claimed","Set","key","node","Object","entries","children","Array","isArray","child","has","delete","set","add","packNodesForWire","packed","$id","parentId","rest","out","undefined","get","unpackWireNodes","unpacked","parent","needsId","needsParent"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED,8DAA8D;;AAU9D,sEAAsE,GACtE,SAASA,UAAUC,KAAkB;IACnC,MAAMC,UAAU,IAAIC;IACpB,MAAMC,UAAU,IAAIC;IACpB,KAAK,MAAM,CAACC,KAAKC,KAAK,IAAIC,OAAOC,OAAO,CAACR,OAAQ;QAC/C,MAAMS,WAAWH,wBAAAA,KAAMN,KAAK;QAC5B,IAAI,CAACU,MAAMC,OAAO,CAACF,WAAW;QAC9B,KAAK,MAAMG,SAASH,SAAU;YAC5B,IAAI,OAAOG,UAAU,UAAU;YAC/B,sEAAsE;YACtE,mCAAmC;YACnC,IAAIT,QAAQU,GAAG,CAACD,QAAQX,QAAQa,MAAM,CAACF;iBAClCX,QAAQc,GAAG,CAACH,OAAOP;YACxBF,QAAQa,GAAG,CAACJ;QACd;IACF;IACA,OAAOX;AACT;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASgB,iBACdjB,KAAQ;IAER,IAAI,CAACA,OAAO,OAAOA;IACnB,MAAMC,UAAUF,UAAUC;IAC1B,MAAMkB,SAAsB,CAAC;IAC7B,KAAK,MAAM,CAACb,KAAKC,KAAK,IAAIC,OAAOC,OAAO,CAACR,OAAQ;QAC/C,IAAI,CAACM,QAAQ,OAAOA,SAAS,UAAU;YACrCY,MAAM,CAACb,IAAI,GAAGC;YACd;QACF;QACA,MAAM,EAAEa,GAAG,EAAEC,QAAQ,EAAW,GAAGd,MAATe,wCAASf;;;;QACnC,MAAMgB,MAAgBD;QACtB,IAAIF,QAAQd,KAAKiB,IAAIH,GAAG,GAAGA;QAC3B,IAAIC,aAAaG,aAAaH,aAAanB,QAAQuB,GAAG,CAACnB,MAAM;YAC3DiB,IAAIF,QAAQ,GAAGA;QACjB;QACAF,MAAM,CAACb,IAAI,GAAGiB;IAChB;IACA,OAAOJ;AACT;AAEA;;;;;CAKC,GACD,OAAO,SAASO,gBACdzB,KAAQ;IAER,IAAI,CAACA,OAAO,OAAOA;IACnB,MAAMC,UAAUF,UAAUC;IAC1B,MAAM0B,WAAwB,CAAC;IAC/B,KAAK,MAAM,CAACrB,KAAKC,KAAK,IAAIC,OAAOC,OAAO,CAACR,OAAQ;QAC/C,IAAI,CAACM,QAAQ,OAAOA,SAAS,UAAU;YACrCoB,QAAQ,CAACrB,IAAI,GAAGC;YAChB;QACF;QACA,MAAMqB,SAAS1B,QAAQuB,GAAG,CAACnB;QAC3B,MAAMuB,UAAU,CAAE,CAAA,SAAStB,IAAG;QAC9B,MAAMuB,cAAc,CAAE,CAAA,cAAcvB,IAAG,KAAMqB,WAAWJ;QACxDG,QAAQ,CAACrB,IAAI,GACXuB,WAAWC,cACP,aACMD,UAAU;YAAET,KAAKd;QAAI,IAAI,CAAC,GAC3BC,MACCuB,cAAc;YAAET,UAAUO;QAAO,IAAI,CAAC,KAE5CrB;IACR;IACA,OAAOoB;AACT"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/wire-nodes.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 published page's node map as it crosses from the server into the\n * browser, stating each node's id once (AGL-3401, AGL-3438).\n *\n * The map rides in the page's flight payload, inside its HTML, and it is\n * nearly all of that payload: 346 KB of aglyn.com/press's 376 KB. A stored\n * map names every node three times — as its key, as its `$id`, and in its\n * parent's `nodes` list — and once more as `parentId` in each child. The\n * ids are random, which is the part of the map compression does least with,\n * so every repeat costs close to its full length on the wire.\n *\n * Packed, the map is a TREE in document order: each node is an entry\n * `[id, fields, ...children]`, and a child is either its own entry, inlined\n * where its parent lists it, or its bare id when the node is inlined\n * somewhere else or is not in the map at all. The id is stated once, by its\n * entry; `$id`, `parentId` and `nodes` are left out of `fields` whenever the\n * entry's position says the same thing. On aglyn.com/press that is 6.8 KB\n * less HTML on the wire than the AGL-3401 packing, which only dropped\n * `$id` and `parentId`.\n *\n * `packNodesForWire` drops a field only when `unpackWireNodes` will put back\n * the same value — an `$id` that differs from its key, a `parentId` other\n * than the parent the node is inlined under, or a `nodes` value that is not\n * a list of ids stays in `fields` — so every node comes back equal to the\n * one that left, well-formed map or not. (One that carried no `$id`, or no\n * `parentId` under a parent that lists it, comes back with them.) A child\n * two parents list is inlined under the first and named by id in the other,\n * a cycle is cut where it closes, and a node no list reaches is an entry of\n * its own at the top level — so every key comes back, in document order.\n *\n * Unpacking also takes the flat form — a full map, or one packed by the\n * AGL-3401 format — and fills in each `$id` and `parentId` it can from the\n * keys and `nodes` lists, so it is idempotent. That is what lets a full patch\n * (a withheld panel from `/api/screen/nodes`) be merged over an unpacked map\n * and unpacked again.\n *\n * Banner-free and dependency-free: the tenant's server page packs and its\n * client root unpacks, so it must be importable from both.\n */\n\n/** A node as the map carries it: an object, keyed by its id. */\ntype WireNode = Record<string, unknown> & {\n  $id?: unknown\n  parentId?: unknown\n  nodes?: unknown\n}\n\n/** A node map, packed or not. */\nexport type WireNodeMap<N = WireNode> = Record<string, N | null | undefined>\n\n/**\n * One node of the packed tree: its id, the fields its position does not\n * already state, and its children — each an entry of its own, or the id of a\n * node that is entered elsewhere or nowhere.\n */\ntype WireEntry = [id: string, fields: unknown, ...children: WireChild[]]\ntype WireChild = WireEntry | string\n\n/**\n * The one key a packed map has. `~` is outside the alphabet node ids are\n * drawn from; a map that nevertheless has that key ships flat rather than\n * risk being read back as a tree.\n */\nconst WIRE_TREE_KEY = '~'\n\nconst isNode = (value: unknown): value is WireNode =>\n  Boolean(value) && typeof value === 'object' && !Array.isArray(value)\n\n/** A `nodes` value the tree can carry as its children: ids, and only ids. */\nconst childIds = (node: WireNode): string[] | undefined =>\n  Array.isArray(node.nodes) &&\n  node.nodes.length > 0 &&\n  node.nodes.every((child) => typeof child === 'string')\n    ? (node.nodes as string[])\n    : undefined\n\n/** Each child id to the key of the node whose `nodes` list names it. */\nfunction parentsOf(nodes: WireNodeMap): Map<string, string> {\n  const parents = new Map<string, string>()\n  const claimed = new Set<string>()\n  for (const [key, node] of Object.entries(nodes)) {\n    const children = node?.nodes\n    if (!Array.isArray(children)) continue\n    for (const child of children) {\n      if (typeof child !== 'string') continue\n      // A child two parents list has no single answer, so neither may stand\n      // in for the `parentId` it stores.\n      if (claimed.has(child)) parents.delete(child)\n      else parents.set(child, key)\n      claimed.add(child)\n    }\n  }\n  return parents\n}\n\n/** Whether `value` is a map packed by {@link packNodesForWire}. */\nfunction isPackedTree(\n  value: unknown,\n): value is { [WIRE_TREE_KEY]: WireEntry[] } {\n  if (!value || typeof value !== 'object') return false\n  const keys = Object.keys(value)\n  return (\n    keys.length === 1 &&\n    keys[0] === WIRE_TREE_KEY &&\n    Array.isArray((value as Record<string, unknown>)[WIRE_TREE_KEY])\n  )\n}\n\n/**\n * The map as a tree of entries in document order: every node reachable from\n * a node no list names, then any node that leaves out (a cycle, or a subtree\n * whose only parent is unreachable), each as an entry of its own. A new\n * structure throughout; the argument is never mutated, because the server's\n * is the cached loader's.\n *\n * Typed as the map it is handed rather than as a looser one: the packed form\n * has one reader, `unpackWireNodes`, and the prop it travels in is read\n * nowhere else, so a second type would buy a cast at both ends.\n */\nexport function packNodesForWire<M extends WireNodeMap | null | undefined>(\n  nodes: M,\n): M {\n  if (!nodes) return nodes\n  if (Object.prototype.hasOwnProperty.call(nodes, WIRE_TREE_KEY)) return nodes\n  const map = nodes as WireNodeMap\n  const listed = new Set<string>()\n  for (const node of Object.values(map)) {\n    if (!isNode(node)) continue\n    for (const child of childIds(node) ?? []) listed.add(child)\n  }\n  const entered = new Set<string>()\n  const enter = (key: string, parent: string | undefined): WireEntry => {\n    entered.add(key)\n    const node = map[key]\n    if (!isNode(node)) return [key, node]\n    const { $id, parentId, nodes: list, ...rest } = node\n    const fields: WireNode = rest\n    if ('$id' in node && $id !== key) fields.$id = $id\n    if ('parentId' in node && parentId !== parent) fields.parentId = parentId\n    const children = childIds(node)\n    if (!children) {\n      if ('nodes' in node) fields.nodes = list\n      return [key, fields]\n    }\n    const entry: WireEntry = [key, fields]\n    for (const child of children) {\n      entry.push(\n        Object.prototype.hasOwnProperty.call(map, child) && !entered.has(child)\n          ? enter(child, key)\n          : child,\n      )\n    }\n    return entry\n  }\n  const tree: WireEntry[] = []\n  for (const key of Object.keys(map)) {\n    if (!listed.has(key) && !entered.has(key)) tree.push(enter(key, undefined))\n  }\n  for (const key of Object.keys(map)) {\n    if (!entered.has(key)) tree.push(enter(key, undefined))\n  }\n  return { [WIRE_TREE_KEY]: tree } as unknown as M\n}\n\n/**\n * The map with every node whole: from a packed tree, each entry back under\n * its id with its `$id`, its `parentId` and its `nodes` list restored; from a\n * flat map, each node's `$id` and `parentId` filled in from its key and its\n * parent's `nodes` list. A node that already carries either keeps its own,\n * so a full map comes back equal.\n */\nexport function unpackWireNodes<M extends WireNodeMap | null | undefined>(\n  nodes: M,\n): M {\n  if (!nodes) return nodes\n  if (isPackedTree(nodes)) return unpackTree(nodes[WIRE_TREE_KEY]) as M\n  const parents = parentsOf(nodes)\n  const unpacked: WireNodeMap = {}\n  for (const [key, node] of Object.entries(nodes)) {\n    if (!node || typeof node !== 'object') {\n      unpacked[key] = node\n      continue\n    }\n    const parent = parents.get(key)\n    const needsId = !('$id' in node)\n    const needsParent = !('parentId' in node) && parent !== undefined\n    unpacked[key] =\n      needsId || needsParent\n        ? {\n            ...(needsId ? { $id: key } : {}),\n            ...node,\n            ...(needsParent ? { parentId: parent } : {}),\n          }\n        : node\n  }\n  return unpacked as M\n}\n\nfunction unpackTree(tree: readonly WireEntry[]): WireNodeMap {\n  const out: WireNodeMap = {}\n  const visit = (entry: WireEntry, parent: string | undefined): void => {\n    const [key, fields, ...children] = entry\n    if (!isNode(fields)) {\n      out[key] = fields as WireNode | null | undefined\n      return\n    }\n    const node: WireNode = { $id: key, ...fields }\n    if (children.length) {\n      node.nodes = children.map((child) =>\n        typeof child === 'string' ? child : child[0],\n      )\n    }\n    if (parent !== undefined && !('parentId' in fields)) node.parentId = parent\n    out[key] = node\n    for (const child of children) if (typeof child !== 'string') visit(child, key)\n  }\n  for (const entry of tree) visit(entry, undefined)\n  return out\n}\n"],"names":["WIRE_TREE_KEY","isNode","value","Boolean","Array","isArray","childIds","node","nodes","length","every","child","undefined","parentsOf","parents","Map","claimed","Set","key","Object","entries","children","has","delete","set","add","isPackedTree","keys","packNodesForWire","prototype","hasOwnProperty","call","map","listed","values","entered","enter","parent","$id","parentId","list","rest","fields","entry","push","tree","unpackWireNodes","unpackTree","unpacked","get","needsId","needsParent","out","visit"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCC,GAED,8DAA8D;;AAkB9D;;;;CAIC,GACD,MAAMA,gBAAgB;AAEtB,MAAMC,SAAS,CAACC,QACdC,QAAQD,UAAU,OAAOA,UAAU,YAAY,CAACE,MAAMC,OAAO,CAACH;AAEhE,2EAA2E,GAC3E,MAAMI,WAAW,CAACC,OAChBH,MAAMC,OAAO,CAACE,KAAKC,KAAK,KACxBD,KAAKC,KAAK,CAACC,MAAM,GAAG,KACpBF,KAAKC,KAAK,CAACE,KAAK,CAAC,CAACC,QAAU,OAAOA,UAAU,YACxCJ,KAAKC,KAAK,GACXI;AAEN,sEAAsE,GACtE,SAASC,UAAUL,KAAkB;IACnC,MAAMM,UAAU,IAAIC;IACpB,MAAMC,UAAU,IAAIC;IACpB,KAAK,MAAM,CAACC,KAAKX,KAAK,IAAIY,OAAOC,OAAO,CAACZ,OAAQ;QAC/C,MAAMa,WAAWd,wBAAAA,KAAMC,KAAK;QAC5B,IAAI,CAACJ,MAAMC,OAAO,CAACgB,WAAW;QAC9B,KAAK,MAAMV,SAASU,SAAU;YAC5B,IAAI,OAAOV,UAAU,UAAU;YAC/B,sEAAsE;YACtE,mCAAmC;YACnC,IAAIK,QAAQM,GAAG,CAACX,QAAQG,QAAQS,MAAM,CAACZ;iBAClCG,QAAQU,GAAG,CAACb,OAAOO;YACxBF,QAAQS,GAAG,CAACd;QACd;IACF;IACA,OAAOG;AACT;AAEA,iEAAiE,GACjE,SAASY,aACPxB,KAAc;IAEd,IAAI,CAACA,SAAS,OAAOA,UAAU,UAAU,OAAO;IAChD,MAAMyB,OAAOR,OAAOQ,IAAI,CAACzB;IACzB,OACEyB,KAAKlB,MAAM,KAAK,KAChBkB,IAAI,CAAC,EAAE,KAAK3B,iBACZI,MAAMC,OAAO,CAAC,AAACH,KAAiC,CAACF,cAAc;AAEnE;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAAS4B,iBACdpB,KAAQ;IAER,IAAI,CAACA,OAAO,OAAOA;IACnB,IAAIW,OAAOU,SAAS,CAACC,cAAc,CAACC,IAAI,CAACvB,OAAOR,gBAAgB,OAAOQ;IACvE,MAAMwB,MAAMxB;IACZ,MAAMyB,SAAS,IAAIhB;IACnB,KAAK,MAAMV,QAAQY,OAAOe,MAAM,CAACF,KAAM;YAEjB1B;QADpB,IAAI,CAACL,OAAOM,OAAO;QACnB,KAAK,MAAMI,UAASL,YAAAA,SAASC,iBAATD,YAAkB,EAAE,CAAE2B,OAAOR,GAAG,CAACd;IACvD;IACA,MAAMwB,UAAU,IAAIlB;IACpB,MAAMmB,QAAQ,CAAClB,KAAamB;QAC1BF,QAAQV,GAAG,CAACP;QACZ,MAAMX,OAAOyB,GAAG,CAACd,IAAI;QACrB,IAAI,CAACjB,OAAOM,OAAO,OAAO;YAACW;YAAKX;SAAK;QACrC,MAAM,EAAE+B,GAAG,EAAEC,QAAQ,EAAE/B,OAAOgC,IAAI,EAAW,GAAGjC,MAATkC,wCAASlC;;;;;QAChD,MAAMmC,SAAmBD;QACzB,IAAI,SAASlC,QAAQ+B,QAAQpB,KAAKwB,OAAOJ,GAAG,GAAGA;QAC/C,IAAI,cAAc/B,QAAQgC,aAAaF,QAAQK,OAAOH,QAAQ,GAAGA;QACjE,MAAMlB,WAAWf,SAASC;QAC1B,IAAI,CAACc,UAAU;YACb,IAAI,WAAWd,MAAMmC,OAAOlC,KAAK,GAAGgC;YACpC,OAAO;gBAACtB;gBAAKwB;aAAO;QACtB;QACA,MAAMC,QAAmB;YAACzB;YAAKwB;SAAO;QACtC,KAAK,MAAM/B,SAASU,SAAU;YAC5BsB,MAAMC,IAAI,CACRzB,OAAOU,SAAS,CAACC,cAAc,CAACC,IAAI,CAACC,KAAKrB,UAAU,CAACwB,QAAQb,GAAG,CAACX,SAC7DyB,MAAMzB,OAAOO,OACbP;QAER;QACA,OAAOgC;IACT;IACA,MAAME,OAAoB,EAAE;IAC5B,KAAK,MAAM3B,OAAOC,OAAOQ,IAAI,CAACK,KAAM;QAClC,IAAI,CAACC,OAAOX,GAAG,CAACJ,QAAQ,CAACiB,QAAQb,GAAG,CAACJ,MAAM2B,KAAKD,IAAI,CAACR,MAAMlB,KAAKN;IAClE;IACA,KAAK,MAAMM,OAAOC,OAAOQ,IAAI,CAACK,KAAM;QAClC,IAAI,CAACG,QAAQb,GAAG,CAACJ,MAAM2B,KAAKD,IAAI,CAACR,MAAMlB,KAAKN;IAC9C;IACA,OAAO;QAAE,CAACZ,cAAc,EAAE6C;IAAK;AACjC;AAEA;;;;;;CAMC,GACD,OAAO,SAASC,gBACdtC,KAAQ;IAER,IAAI,CAACA,OAAO,OAAOA;IACnB,IAAIkB,aAAalB,QAAQ,OAAOuC,WAAWvC,KAAK,CAACR,cAAc;IAC/D,MAAMc,UAAUD,UAAUL;IAC1B,MAAMwC,WAAwB,CAAC;IAC/B,KAAK,MAAM,CAAC9B,KAAKX,KAAK,IAAIY,OAAOC,OAAO,CAACZ,OAAQ;QAC/C,IAAI,CAACD,QAAQ,OAAOA,SAAS,UAAU;YACrCyC,QAAQ,CAAC9B,IAAI,GAAGX;YAChB;QACF;QACA,MAAM8B,SAASvB,QAAQmC,GAAG,CAAC/B;QAC3B,MAAMgC,UAAU,CAAE,CAAA,SAAS3C,IAAG;QAC9B,MAAM4C,cAAc,CAAE,CAAA,cAAc5C,IAAG,KAAM8B,WAAWzB;QACxDoC,QAAQ,CAAC9B,IAAI,GACXgC,WAAWC,cACP,aACMD,UAAU;YAAEZ,KAAKpB;QAAI,IAAI,CAAC,GAC3BX,MACC4C,cAAc;YAAEZ,UAAUF;QAAO,IAAI,CAAC,KAE5C9B;IACR;IACA,OAAOyC;AACT;AAEA,SAASD,WAAWF,IAA0B;IAC5C,MAAMO,MAAmB,CAAC;IAC1B,MAAMC,QAAQ,CAACV,OAAkBN;QAC/B,MAAM,CAACnB,KAAKwB,QAAQ,GAAGrB,SAAS,GAAGsB;QACnC,IAAI,CAAC1C,OAAOyC,SAAS;YACnBU,GAAG,CAAClC,IAAI,GAAGwB;YACX;QACF;QACA,MAAMnC,OAAiB;YAAE+B,KAAKpB;WAAQwB;QACtC,IAAIrB,SAASZ,MAAM,EAAE;YACnBF,KAAKC,KAAK,GAAGa,SAASW,GAAG,CAAC,CAACrB,QACzB,OAAOA,UAAU,WAAWA,QAAQA,KAAK,CAAC,EAAE;QAEhD;QACA,IAAI0B,WAAWzB,aAAa,CAAE,CAAA,cAAc8B,MAAK,GAAInC,KAAKgC,QAAQ,GAAGF;QACrEe,GAAG,CAAClC,IAAI,GAAGX;QACX,KAAK,MAAMI,SAASU,SAAU,IAAI,OAAOV,UAAU,UAAU0C,MAAM1C,OAAOO;IAC5E;IACA,KAAK,MAAMyB,SAASE,KAAMQ,MAAMV,OAAO/B;IACvC,OAAOwC;AACT"}

package/src/lib/data-transfer/access.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @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.
+ */
+import type { TransferImportRole, TransferResourceDescriptor } from './resource';
+import { type TransferApiRoute, type TransferPlanRequiredResponse } from './transfer-api';
+/** What a resource declares about who may read and import its records. */
+export type TransferReadDeclaration = Pick<TransferResourceDescriptor, 'readPermission' | 'readableByMembers' | 'importRoles'>;
+/** What a resource declares about the plan that moves its records. */
+export type TransferPlanDeclaration = Pick<TransferResourceDescriptor, 'featureFlag' | 'featureFlagExempt'>;
+/** What a member is doing with a resource's records. */
+export type TransferAccessIntent = 'import' | 'export';
+/** The permission every import asks for. */
+export declare const TRANSFER_MANAGE_PERMISSION = "data.manage";
+/** The routes that only read records, and so ask for export access. */
+export declare const TRANSFER_EXPORT_ROUTES: readonly TransferApiRoute[];
+/** The intent a transfer route asks with. */
+export declare function transferRouteIntent(route: TransferApiRoute): TransferAccessIntent;
+/**
+ * The permissions any ONE of which admits a member to `intent` on a
+ * resource. Empty means membership is enough (and, for a collaborator,
+ * reaching the named site).
+ */
+export declare function transferAccessPermissions(intent: TransferAccessIntent, descriptor: TransferReadDeclaration | null | undefined): readonly string[];
+/** How one member's permissions resolve where the records are. */
+export interface TransferMemberAxis {
+    /** Whether the member holds `permission` on the named site, or on the workspace when none is named. */
+    holds(permission: string): boolean;
+    /** Whether the member reaches the named site; `true` when none is named or the member is org-wide. */
+    reachesSite: boolean;
+    /**
+     * The member's role where the records are — on the named site
+     * (`hostRoleFor`), or on the workspace (`transferWorkspaceRole`) — for a
+     * resource that names `importRoles`; `null` for none.
+     */
+    role?: TransferImportRole | null;
+}
+/** Whether a member may `intent` a resource's records: see the block above. */
+export declare function transferAccessAllowed(intent: TransferAccessIntent, descriptor: TransferReadDeclaration | null | undefined, axis: TransferMemberAxis): boolean;
+/**
+ * Whether a member in `role` may `intent` the records, as far as the
+ * resource's `importRoles` say: always for an export, or a resource that
+ * names none (AGL-3554).
+ */
+export declare function transferImportRoleAllowed(intent: TransferAccessIntent, descriptor: Pick<TransferResourceDescriptor, 'importRoles'> | null | undefined, role: TransferImportRole | null): boolean;
+/**
+ * A workspace role as the site role it is on every site, for a workspace's
+ * records: an owner or an admin is every site's admin (`hostRoleFor`), and
+ * any other role is itself.
+ */
+export declare function transferWorkspaceRole(role: string | null | undefined): TransferImportRole | null;
+/** The sentence refusing a member whose role is not among the resource's `importRoles`. */
+export declare function transferImportRoleRefusal(descriptor: Pick<TransferResourceDescriptor, 'importRoles' | 'label' | 'scope'>): string;
+/**
+ * The plan feature a workspace needs to `intent` a resource's records, or
+ * `null` when every plan may — no `featureFlag`, or an intent the resource
+ * exempts. The entitlement itself is the caller's to resolve
+ * (`checkEntitlement`), from the workspace document it already holds.
+ */
+export declare function transferPlanFeature(intent: TransferAccessIntent, descriptor: TransferPlanDeclaration | null | undefined): string | null;
+/** Whether a refusal's body is one for the workspace's plan. */
+export declare function isTransferPlanRequired(body: unknown): body is TransferPlanRequiredResponse;

package/src/lib/data-transfer/access.js

@@ -0,0 +1,93 @@
+/**
+ * @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.
+ */ import { TRANSFER_PLAN_REQUIRED } from "./transfer-api.js";
+/** The permission every import asks for. */ export const TRANSFER_MANAGE_PERMISSION = 'data.manage';
+/** The routes that only read records, and so ask for export access. */ export const TRANSFER_EXPORT_ROUTES = [
+    'fields',
+    'export'
+];
+/** The intent a transfer route asks with. */ export function transferRouteIntent(route) {
+    return TRANSFER_EXPORT_ROUTES.includes(route) ? 'export' : 'import';
+}
+/**
+ * The permissions any ONE of which admits a member to `intent` on a
+ * resource. Empty means membership is enough (and, for a collaborator,
+ * reaching the named site).
+ */ export function transferAccessPermissions(intent, descriptor) {
+    var _descriptor_readPermission;
+    if (intent === 'import') return [
+        TRANSFER_MANAGE_PERMISSION
+    ];
+    if ((descriptor == null ? void 0 : descriptor.readableByMembers) === true) return [];
+    const read = descriptor == null ? void 0 : (_descriptor_readPermission = descriptor.readPermission) == null ? void 0 : _descriptor_readPermission.trim();
+    // Whoever may write the records may read them.
+    return read && read !== TRANSFER_MANAGE_PERMISSION ? [
+        read,
+        TRANSFER_MANAGE_PERMISSION
+    ] : [
+        TRANSFER_MANAGE_PERMISSION
+    ];
+}
+/** Whether a member may `intent` a resource's records: see the block above. */ export function transferAccessAllowed(intent, descriptor, axis) {
+    var _axis_role;
+    if (!axis.reachesSite) return false;
+    if (!transferImportRoleAllowed(intent, descriptor, (_axis_role = axis.role) != null ? _axis_role : null)) return false;
+    const needed = transferAccessPermissions(intent, descriptor);
+    return !needed.length || needed.some((permission)=>axis.holds(permission));
+}
+/**
+ * Whether a member in `role` may `intent` the records, as far as the
+ * resource's `importRoles` say: always for an export, or a resource that
+ * names none (AGL-3554).
+ */ export function transferImportRoleAllowed(intent, descriptor, role) {
+    const roles = descriptor == null ? void 0 : descriptor.importRoles;
+    if (intent !== 'import' || !(roles == null ? void 0 : roles.length)) return true;
+    return role !== null && roles.includes(role);
+}
+/**
+ * A workspace role as the site role it is on every site, for a workspace's
+ * records: an owner or an admin is every site's admin (`hostRoleFor`), and
+ * any other role is itself.
+ */ export function transferWorkspaceRole(role) {
+    if (role === 'owner' || role === 'admin') return 'admin';
+    return role === 'editor' || role === 'author' || role === 'viewer' ? role : null;
+}
+/** The sentence refusing a member whose role is not among the resource's `importRoles`. */ export function transferImportRoleRefusal(descriptor) {
+    var _descriptor_importRoles;
+    const roles = (_descriptor_importRoles = descriptor.importRoles) != null ? _descriptor_importRoles : [];
+    const what = /^[A-Z][a-z]/.test(descriptor.label) ? descriptor.label.charAt(0).toLowerCase() + descriptor.label.slice(1) : descriptor.label;
+    if (roles.length === 1 && roles[0] === 'admin') {
+        return descriptor.scope === 'host' ? `Only the workspace’s owners and admins, and the site’s admins, can import ${what}.` : `Only the workspace’s owners and admins can import ${what}.`;
+    }
+    const named = roles.map((role)=>role.charAt(0).toUpperCase() + role.slice(1)).join(', ');
+    return `Importing ${what} needs one of these roles${descriptor.scope === 'host' ? ' on the site' : ''}: ${named}.`;
+}
+/**
+ * The plan feature a workspace needs to `intent` a resource's records, or
+ * `null` when every plan may — no `featureFlag`, or an intent the resource
+ * exempts. The entitlement itself is the caller's to resolve
+ * (`checkEntitlement`), from the workspace document it already holds.
+ */ export function transferPlanFeature(intent, descriptor) {
+    var _descriptor_featureFlag, _descriptor_featureFlagExempt;
+    const feature = descriptor == null ? void 0 : (_descriptor_featureFlag = descriptor.featureFlag) == null ? void 0 : _descriptor_featureFlag.trim();
+    if (!feature) return null;
+    return (descriptor == null ? void 0 : (_descriptor_featureFlagExempt = descriptor.featureFlagExempt) == null ? void 0 : _descriptor_featureFlagExempt.includes(intent)) ? null : feature;
+}
+/** Whether a refusal's body is one for the workspace's plan. */ export function isTransferPlanRequired(body) {
+    return Boolean(body && typeof body === 'object' && body.reason === TRANSFER_PLAN_REQUIRED);
+}
+
+//# sourceMappingURL=access.js.map

package/src/lib/data-transfer/access.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/data-transfer/access.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 { TransferImportRole, TransferResourceDescriptor } from './resource'\nimport { TRANSFER_PLAN_REQUIRED, type TransferApiRoute, type TransferPlanRequiredResponse } from './transfer-api'\n\n/*==========================================\n * WHO MAY MOVE A RESOURCE'S RECORDS (AGL-3546)\n *\n * Two intents, answered the same way by the transfer routes' gate and by the\n * console's display of Import and Export, so a button is never offered that\n * the route refuses:\n *\n *  - IMPORT (upload, analyze, plan, apply, status, undo — and the job list\n *    and packages, which the gate asks with the same intent) writes records, and\n *    needs `data.manage` — on the named site, or on the workspace. A\n *    resource stricter than that names its `importRoles` (AGL-3554): the\n *    member's role where the records are must also be one of them (gift\n *    cards: a site's admins, which a workspace's owners and admins are).\n *  - EXPORT (export, and `fields`, which the export dialog opens with) only\n *    reads them, and asks what the resource declares: `readableByMembers`\n *    admits any member (a collaborator who reaches the named site), the\n *    way datasets are read; a `readPermission` admits whoever holds it; and\n *    a resource that declares neither keeps `data.manage`, because its\n *    records may be ones the rules let only managers read (CRM contacts).\n *    `data.manage` always admits. Which records a reader then sees is the\n *    resource's own business: `readPage` and `count` honor the reader's\n *    `scopeTokens`, as every other door onto the records does.\n *\n * And one question of the WORKSPACE, asked after the member's (AGL-3555):\n * a resource that declares a `featureFlag` is moved only by a workspace\n * whose plan carries that feature, for every intent but the ones it lists\n * in `featureFlagExempt`. {@link transferPlanFeature} names the feature an\n * intent needs; the gate refuses without it (403 `plan_required`, the\n * feature as `code`), staff included, and the console's `can` answers\n * `false`, so neither button is offered on a plan the route refuses.\n *==========================================*/\n\n/** What a resource declares about who may read and import its records. */\nexport type TransferReadDeclaration = Pick<TransferResourceDescriptor, 'readPermission' | 'readableByMembers' | 'importRoles'>\n\n/** What a resource declares about the plan that moves its records. */\nexport type TransferPlanDeclaration = Pick<TransferResourceDescriptor, 'featureFlag' | 'featureFlagExempt'>\n\n/** What a member is doing with a resource's records. */\nexport type TransferAccessIntent = 'import' | 'export'\n\n/** The permission every import asks for. */\nexport const TRANSFER_MANAGE_PERMISSION = 'data.manage'\n\n/** The routes that only read records, and so ask for export access. */\nexport const TRANSFER_EXPORT_ROUTES: readonly TransferApiRoute[] = ['fields', 'export']\n\n/** The intent a transfer route asks with. */\nexport function transferRouteIntent(route: TransferApiRoute): TransferAccessIntent {\n  return TRANSFER_EXPORT_ROUTES.includes(route) ? 'export' : 'import'\n}\n\n/**\n * The permissions any ONE of which admits a member to `intent` on a\n * resource. Empty means membership is enough (and, for a collaborator,\n * reaching the named site).\n */\nexport function transferAccessPermissions(\n  intent: TransferAccessIntent,\n  descriptor: TransferReadDeclaration | null | undefined,\n): readonly string[] {\n  if (intent === 'import') return [TRANSFER_MANAGE_PERMISSION]\n  if (descriptor?.readableByMembers === true) return []\n  const read = descriptor?.readPermission?.trim()\n  // Whoever may write the records may read them.\n  return read && read !== TRANSFER_MANAGE_PERMISSION ? [read, TRANSFER_MANAGE_PERMISSION] : [TRANSFER_MANAGE_PERMISSION]\n}\n\n/** How one member's permissions resolve where the records are. */\nexport interface TransferMemberAxis {\n  /** Whether the member holds `permission` on the named site, or on the workspace when none is named. */\n  holds(permission: string): boolean\n  /** Whether the member reaches the named site; `true` when none is named or the member is org-wide. */\n  reachesSite: boolean\n  /**\n   * The member's role where the records are — on the named site\n   * (`hostRoleFor`), or on the workspace (`transferWorkspaceRole`) — for a\n   * resource that names `importRoles`; `null` for none.\n   */\n  role?: TransferImportRole | null\n}\n\n/** Whether a member may `intent` a resource's records: see the block above. */\nexport function transferAccessAllowed(\n  intent: TransferAccessIntent,\n  descriptor: TransferReadDeclaration | null | undefined,\n  axis: TransferMemberAxis,\n): boolean {\n  if (!axis.reachesSite) return false\n  if (!transferImportRoleAllowed(intent, descriptor, axis.role ?? null)) return false\n  const needed = transferAccessPermissions(intent, descriptor)\n  return !needed.length || needed.some((permission) => axis.holds(permission))\n}\n\n/**\n * Whether a member in `role` may `intent` the records, as far as the\n * resource's `importRoles` say: always for an export, or a resource that\n * names none (AGL-3554).\n */\nexport function transferImportRoleAllowed(\n  intent: TransferAccessIntent,\n  descriptor: Pick<TransferResourceDescriptor, 'importRoles'> | null | undefined,\n  role: TransferImportRole | null,\n): boolean {\n  const roles = descriptor?.importRoles\n  if (intent !== 'import' || !roles?.length) return true\n  return role !== null && roles.includes(role)\n}\n\n/**\n * A workspace role as the site role it is on every site, for a workspace's\n * records: an owner or an admin is every site's admin (`hostRoleFor`), and\n * any other role is itself.\n */\nexport function transferWorkspaceRole(role: string | null | undefined): TransferImportRole | null {\n  if (role === 'owner' || role === 'admin') return 'admin'\n  return role === 'editor' || role === 'author' || role === 'viewer' ? role : null\n}\n\n/** The sentence refusing a member whose role is not among the resource's `importRoles`. */\nexport function transferImportRoleRefusal(\n  descriptor: Pick<TransferResourceDescriptor, 'importRoles' | 'label' | 'scope'>,\n): string {\n  const roles = descriptor.importRoles ?? []\n  const what = /^[A-Z][a-z]/.test(descriptor.label)\n    ? descriptor.label.charAt(0).toLowerCase() + descriptor.label.slice(1)\n    : descriptor.label\n  if (roles.length === 1 && roles[0] === 'admin') {\n    return descriptor.scope === 'host'\n      ? `Only the workspace’s owners and admins, and the site’s admins, can import ${what}.`\n      : `Only the workspace’s owners and admins can import ${what}.`\n  }\n  const named = roles.map((role) => role.charAt(0).toUpperCase() + role.slice(1)).join(', ')\n  return `Importing ${what} needs one of these roles${descriptor.scope === 'host' ? ' on the site' : ''}: ${named}.`\n}\n\n/**\n * The plan feature a workspace needs to `intent` a resource's records, or\n * `null` when every plan may — no `featureFlag`, or an intent the resource\n * exempts. The entitlement itself is the caller's to resolve\n * (`checkEntitlement`), from the workspace document it already holds.\n */\nexport function transferPlanFeature(\n  intent: TransferAccessIntent,\n  descriptor: TransferPlanDeclaration | null | undefined,\n): string | null {\n  const feature = descriptor?.featureFlag?.trim()\n  if (!feature) return null\n  return descriptor?.featureFlagExempt?.includes(intent) ? null : feature\n}\n\n/** Whether a refusal's body is one for the workspace's plan. */\nexport function isTransferPlanRequired(body: unknown): body is TransferPlanRequiredResponse {\n  return Boolean(body && typeof body === 'object' && (body as { reason?: unknown }).reason === TRANSFER_PLAN_REQUIRED)\n}\n"],"names":["TRANSFER_PLAN_REQUIRED","TRANSFER_MANAGE_PERMISSION","TRANSFER_EXPORT_ROUTES","transferRouteIntent","route","includes","transferAccessPermissions","intent","descriptor","readableByMembers","read","readPermission","trim","transferAccessAllowed","axis","reachesSite","transferImportRoleAllowed","role","needed","length","some","permission","holds","roles","importRoles","transferWorkspaceRole","transferImportRoleRefusal","what","test","label","charAt","toLowerCase","slice","scope","named","map","toUpperCase","join","transferPlanFeature","feature","featureFlag","featureFlagExempt","isTransferPlanRequired","body","Boolean","reason"],"mappings":"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"}