@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/repeat-infringer.js

@@ -0,0 +1,188 @@
+/**
+ * @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.
+ */ /**
+ * REPEAT-INFRINGER POLICY — the §512(i) condition, with a counter behind it
+ * (AGL-1983).
+ *
+ * §512(i)(1)(A) conditions the ENTIRE safe harbour — every limitation in
+ * §512, not just the hosting one — on a provider having "adopted and
+ * reasonably implemented" a policy for terminating repeat infringers, and on
+ * informing subscribers of it. This is the condition providers most often
+ * lose on, and they lose on the second half: courts have declined to credit a
+ * policy that existed as prose while nothing in the product counted anything.
+ * A policy page alone would not close AGL-1983 and the issue says so.
+ *
+ * So this module is the counting. It answers three questions and nothing else:
+ * what is a strike, when does one go away, and what happens at the threshold.
+ *
+ * ## A strike is an ACTIONED notice, counted against the ACCOUNT
+ *
+ * Not a received notice — anyone can send one, and counting receipts would
+ * let a competitor terminate a customer by filing three complaints. A strike
+ * is recorded when staff action a DMCA report: the point at which a human
+ * looked and took content down.
+ *
+ * Counted against the **org**, not the site. A repeat infringer who loses one
+ * site and opens another inside the same workspace has not been terminated in
+ * any sense the statute would recognise, and the org is the account we bill,
+ * suspend and close. {@link STRIKE_LEDGER_SUBCOLLECTION} therefore hangs off
+ * `orgs/{orgId}`.
+ *
+ * ## A strike is keyed by its report, which is what makes withdrawal work
+ *
+ * One ledger document per actioned report, with the report's id AS the
+ * document id. Two properties fall out of that and both are load-bearing:
+ *
+ *  - **Idempotence.** Staff re-actioning a report they already actioned — or
+ *    a route retried — cannot inflate the count. A counter that can be pumped
+ *    by clicking twice is not one anybody should terminate an account on.
+ *  - **Exact withdrawal.** When a notice is withdrawn, or a counter-notice
+ *    leads to a restoration, the strike it created has to come off — and only
+ *    that one. §512(g) restoration means the takedown is being reversed; a
+ *    strike surviving it would count an infringement the process just
+ *    declined to affirm, which is the shape of unfairness that makes a policy
+ *    look unreasonable rather than reasonable. Deleting by report id removes
+ *    exactly the right strike without recomputing anything.
+ *
+ * {@link strikeWithdrawalReason} names the three ways a strike comes off, so
+ * the ledger records WHY rather than silently shrinking.
+ *
+ * ## The threshold has to do something
+ *
+ * "Reasonably implemented" is the whole fight, so the escalation is defined
+ * here as data rather than left to whoever reads the queue:
+ * {@link repeatInfringerVerdict} maps a count onto a level, and each level
+ * names the consequence in terms of levers this product actually has. At
+ * `terminate` the staff queue refuses to close a DMCA report without an
+ * explicit recorded decision — see the admin route — so the threshold cannot
+ * be passed silently. That refusal is the difference between a counter and a
+ * policy.
+ *
+ * What this module deliberately does NOT do is suspend anything by itself. An
+ * automatic termination on a third strike would be a product that closes a
+ * paying customer's account on three unverified assertions by strangers, with
+ * no human in the loop — and §512 nowhere asks for that. The policy is
+ * "terminate in appropriate circumstances", and judging the circumstances is
+ * exactly the part a person must do. The counter makes the decision
+ * unavoidable and recorded; it does not make it automatically.
+ */ /** Per-org strike ledger. One document per actioned DMCA report. */ export const STRIKE_LEDGER_SUBCOLLECTION = 'dmcaStrikes';
+/**
+ * Strikes at which each consequence begins.
+ *
+ * Three is the termination threshold, which is the number the phrase "repeat
+ * infringer" is conventionally read against and the number the operator's own
+ * published repeat-infringer policy has to state — §512(i)(1)(A) conditions the
+ * whole safe harbour on subscribers having been *informed* of the policy, so a
+ * threshold this ledger enforces silently earns nothing (AGL-2044, AGL-2007).
+ * On a self-host install that policy is the operator's document, not ours: they
+ * inherit a working ledger and owe their own text. The two below it exist so
+ * termination is never the first
+ * thing a customer hears about a problem: a subscriber who does not know they
+ * are on a strike cannot correct their behaviour, and a policy that only
+ * speaks at the end is one a court can call unreasonable in its
+ * implementation.
+ */ export const STRIKE_WARN_AT = 1;
+export const STRIKE_FINAL_AT = 2;
+export const STRIKE_TERMINATE_AT = 3;
+/**
+ * Strikes → verdict.
+ *
+ * A pure function of the count, so the staff surface, the admin route and the
+ * docs cannot disagree about where the line is. Anything at or above
+ * {@link STRIKE_TERMINATE_AT} is `terminate`, including a count that somehow
+ * ran past it — a fourth strike must not read as less serious than the third.
+ */ export function repeatInfringerVerdict(strikes) {
+    const count = typeof strikes === 'number' && Number.isFinite(strikes) && strikes > 0 ? Math.floor(strikes) : 0;
+    if (count >= STRIKE_TERMINATE_AT) {
+        return {
+            strikes: count,
+            level: 'terminate',
+            decisionRequired: true,
+            consequence: 'Termination threshold reached. A staff decision to terminate or to ' + 'record why not is required before any further copyright report on ' + 'this account can be closed.'
+        };
+    }
+    if (count >= STRIKE_FINAL_AT) {
+        return {
+            strikes: count,
+            level: 'final',
+            decisionRequired: false,
+            consequence: 'Final warning. One more upheld copyright notice reaches the ' + 'termination threshold.'
+        };
+    }
+    if (count >= STRIKE_WARN_AT) {
+        return {
+            strikes: count,
+            level: 'warn',
+            decisionRequired: false,
+            consequence: 'Warned. The account has one upheld copyright notice on record.'
+        };
+    }
+    return {
+        strikes: 0,
+        level: 'none',
+        decisionRequired: false,
+        consequence: 'No upheld copyright notices on record.'
+    };
+}
+/** Why a strike came off the ledger. Recorded, never silent. */ export const STRIKE_WITHDRAWAL_REASONS = [
+    /** The complainant retracted the notice. */ 'noticeWithdrawn',
+    /** A §512(g) counter-notice ran its course and access was restored. */ 'counterNoticeRestored',
+    /** Staff decided the notice should not have been actioned. */ 'staffReversed'
+];
+export function isStrikeWithdrawalReason(value) {
+    return typeof value === 'string' && STRIKE_WITHDRAWAL_REASONS.includes(value);
+}
+/**
+ * Does moving a DMCA report to `status` earn a strike?
+ *
+ * `actioned` only. `dismissed` is staff saying the notice did not hold up, so
+ * it must not count — and neither must `open` or `reviewing`, which are a
+ * report nobody has adjudicated yet. Counting anything but `actioned` would
+ * make the ledger a record of accusations rather than of upheld ones.
+ *
+ * The category gate matters as much as the status: the queue carries phishing
+ * and malware reports too, and a phishing takedown is not a copyright
+ * infringement. §512(i) is about infringement, so only `dmca` reports reach
+ * the ledger.
+ */ export function strikeEarnedBy(category, status) {
+    return category === 'dmca' && status === 'actioned';
+}
+/**
+ * Does moving a DMCA report to `status` REMOVE a strike it previously earned?
+ *
+ * The mirror of {@link strikeEarnedBy}, and the reason the pair is written as
+ * two functions rather than one: a report that goes `actioned` → `dismissed`
+ * has to give its strike back, and a naive "recount the actioned ones"
+ * implementation would get that right by accident while getting the
+ * counter-notice case wrong, because a restored counter-notice leaves the
+ * report `actioned` and reverses it by a different route.
+ */ export function strikeRemovedBy(category, status) {
+    return category === 'dmca' && (status === 'dismissed' || status === 'open' || status === 'reviewing');
+}
+/**
+ * Count the strikes standing, given ledger rows.
+ *
+ * Rows carry a `withdrawnAt` when they have been reversed rather than being
+ * deleted, so the ledger stays a complete history — "did we know, and when"
+ * is the question the abuse queue exists to answer, and a strike that was
+ * lifted is part of that answer. Only rows without one count.
+ */ export function countStandingStrikes(rows) {
+    if (!rows) return 0;
+    return rows.filter((row)=>(row == null ? void 0 : row.withdrawnAt) == null).length;
+}
+export default repeatInfringerVerdict;
+
+//# sourceMappingURL=repeat-infringer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/repeat-infringer.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 * REPEAT-INFRINGER POLICY — the §512(i) condition, with a counter behind it\n * (AGL-1983).\n *\n * §512(i)(1)(A) conditions the ENTIRE safe harbour — every limitation in\n * §512, not just the hosting one — on a provider having \"adopted and\n * reasonably implemented\" a policy for terminating repeat infringers, and on\n * informing subscribers of it. This is the condition providers most often\n * lose on, and they lose on the second half: courts have declined to credit a\n * policy that existed as prose while nothing in the product counted anything.\n * A policy page alone would not close AGL-1983 and the issue says so.\n *\n * So this module is the counting. It answers three questions and nothing else:\n * what is a strike, when does one go away, and what happens at the threshold.\n *\n * ## A strike is an ACTIONED notice, counted against the ACCOUNT\n *\n * Not a received notice — anyone can send one, and counting receipts would\n * let a competitor terminate a customer by filing three complaints. A strike\n * is recorded when staff action a DMCA report: the point at which a human\n * looked and took content down.\n *\n * Counted against the **org**, not the site. A repeat infringer who loses one\n * site and opens another inside the same workspace has not been terminated in\n * any sense the statute would recognise, and the org is the account we bill,\n * suspend and close. {@link STRIKE_LEDGER_SUBCOLLECTION} therefore hangs off\n * `orgs/{orgId}`.\n *\n * ## A strike is keyed by its report, which is what makes withdrawal work\n *\n * One ledger document per actioned report, with the report's id AS the\n * document id. Two properties fall out of that and both are load-bearing:\n *\n *  - **Idempotence.** Staff re-actioning a report they already actioned — or\n *    a route retried — cannot inflate the count. A counter that can be pumped\n *    by clicking twice is not one anybody should terminate an account on.\n *  - **Exact withdrawal.** When a notice is withdrawn, or a counter-notice\n *    leads to a restoration, the strike it created has to come off — and only\n *    that one. §512(g) restoration means the takedown is being reversed; a\n *    strike surviving it would count an infringement the process just\n *    declined to affirm, which is the shape of unfairness that makes a policy\n *    look unreasonable rather than reasonable. Deleting by report id removes\n *    exactly the right strike without recomputing anything.\n *\n * {@link strikeWithdrawalReason} names the three ways a strike comes off, so\n * the ledger records WHY rather than silently shrinking.\n *\n * ## The threshold has to do something\n *\n * \"Reasonably implemented\" is the whole fight, so the escalation is defined\n * here as data rather than left to whoever reads the queue:\n * {@link repeatInfringerVerdict} maps a count onto a level, and each level\n * names the consequence in terms of levers this product actually has. At\n * `terminate` the staff queue refuses to close a DMCA report without an\n * explicit recorded decision — see the admin route — so the threshold cannot\n * be passed silently. That refusal is the difference between a counter and a\n * policy.\n *\n * What this module deliberately does NOT do is suspend anything by itself. An\n * automatic termination on a third strike would be a product that closes a\n * paying customer's account on three unverified assertions by strangers, with\n * no human in the loop — and §512 nowhere asks for that. The policy is\n * \"terminate in appropriate circumstances\", and judging the circumstances is\n * exactly the part a person must do. The counter makes the decision\n * unavoidable and recorded; it does not make it automatically.\n */\n\n/** Per-org strike ledger. One document per actioned DMCA report. */\nexport const STRIKE_LEDGER_SUBCOLLECTION = 'dmcaStrikes'\n\n/**\n * Strikes at which each consequence begins.\n *\n * Three is the termination threshold, which is the number the phrase \"repeat\n * infringer\" is conventionally read against and the number the operator's own\n * published repeat-infringer policy has to state — §512(i)(1)(A) conditions the\n * whole safe harbour on subscribers having been *informed* of the policy, so a\n * threshold this ledger enforces silently earns nothing (AGL-2044, AGL-2007).\n * On a self-host install that policy is the operator's document, not ours: they\n * inherit a working ledger and owe their own text. The two below it exist so\n * termination is never the first\n * thing a customer hears about a problem: a subscriber who does not know they\n * are on a strike cannot correct their behaviour, and a policy that only\n * speaks at the end is one a court can call unreasonable in its\n * implementation.\n */\nexport const STRIKE_WARN_AT = 1\nexport const STRIKE_FINAL_AT = 2\nexport const STRIKE_TERMINATE_AT = 3\n\nexport type RepeatInfringerLevel = 'none' | 'warn' | 'final' | 'terminate'\n\nexport interface RepeatInfringerVerdict {\n  /** Strikes currently standing against the account. */\n  strikes: number\n  level: RepeatInfringerLevel\n  /**\n   * Does the account-level consequence require a recorded human decision\n   * before any further DMCA report on this org can be closed?\n   */\n  decisionRequired: boolean\n  /** One line naming the consequence, shown to staff and quoted to the org. */\n  consequence: string\n}\n\n/**\n * Strikes → verdict.\n *\n * A pure function of the count, so the staff surface, the admin route and the\n * docs cannot disagree about where the line is. Anything at or above\n * {@link STRIKE_TERMINATE_AT} is `terminate`, including a count that somehow\n * ran past it — a fourth strike must not read as less serious than the third.\n */\nexport function repeatInfringerVerdict(strikes: unknown): RepeatInfringerVerdict {\n  const count =\n    typeof strikes === 'number' && Number.isFinite(strikes) && strikes > 0\n      ? Math.floor(strikes)\n      : 0\n  if (count >= STRIKE_TERMINATE_AT) {\n    return {\n      strikes: count,\n      level: 'terminate',\n      decisionRequired: true,\n      consequence:\n        'Termination threshold reached. A staff decision to terminate or to ' +\n        'record why not is required before any further copyright report on ' +\n        'this account can be closed.',\n    }\n  }\n  if (count >= STRIKE_FINAL_AT) {\n    return {\n      strikes: count,\n      level: 'final',\n      decisionRequired: false,\n      consequence:\n        'Final warning. One more upheld copyright notice reaches the ' +\n        'termination threshold.',\n    }\n  }\n  if (count >= STRIKE_WARN_AT) {\n    return {\n      strikes: count,\n      level: 'warn',\n      decisionRequired: false,\n      consequence:\n        'Warned. The account has one upheld copyright notice on record.',\n    }\n  }\n  return {\n    strikes: 0,\n    level: 'none',\n    decisionRequired: false,\n    consequence: 'No upheld copyright notices on record.',\n  }\n}\n\n/** Why a strike came off the ledger. Recorded, never silent. */\nexport const STRIKE_WITHDRAWAL_REASONS = [\n  /** The complainant retracted the notice. */\n  'noticeWithdrawn',\n  /** A §512(g) counter-notice ran its course and access was restored. */\n  'counterNoticeRestored',\n  /** Staff decided the notice should not have been actioned. */\n  'staffReversed',\n] as const\nexport type StrikeWithdrawalReason = (typeof STRIKE_WITHDRAWAL_REASONS)[number]\n\nexport function isStrikeWithdrawalReason(\n  value: unknown,\n): value is StrikeWithdrawalReason {\n  return (\n    typeof value === 'string' &&\n    (STRIKE_WITHDRAWAL_REASONS as readonly string[]).includes(value)\n  )\n}\n\n/**\n * Does moving a DMCA report to `status` earn a strike?\n *\n * `actioned` only. `dismissed` is staff saying the notice did not hold up, so\n * it must not count — and neither must `open` or `reviewing`, which are a\n * report nobody has adjudicated yet. Counting anything but `actioned` would\n * make the ledger a record of accusations rather than of upheld ones.\n *\n * The category gate matters as much as the status: the queue carries phishing\n * and malware reports too, and a phishing takedown is not a copyright\n * infringement. §512(i) is about infringement, so only `dmca` reports reach\n * the ledger.\n */\nexport function strikeEarnedBy(category: unknown, status: unknown): boolean {\n  return category === 'dmca' && status === 'actioned'\n}\n\n/**\n * Does moving a DMCA report to `status` REMOVE a strike it previously earned?\n *\n * The mirror of {@link strikeEarnedBy}, and the reason the pair is written as\n * two functions rather than one: a report that goes `actioned` → `dismissed`\n * has to give its strike back, and a naive \"recount the actioned ones\"\n * implementation would get that right by accident while getting the\n * counter-notice case wrong, because a restored counter-notice leaves the\n * report `actioned` and reverses it by a different route.\n */\nexport function strikeRemovedBy(category: unknown, status: unknown): boolean {\n  return (\n    category === 'dmca' && (status === 'dismissed' || status === 'open' || status === 'reviewing')\n  )\n}\n\n/**\n * Count the strikes standing, given ledger rows.\n *\n * Rows carry a `withdrawnAt` when they have been reversed rather than being\n * deleted, so the ledger stays a complete history — \"did we know, and when\"\n * is the question the abuse queue exists to answer, and a strike that was\n * lifted is part of that answer. Only rows without one count.\n */\nexport function countStandingStrikes(\n  rows: readonly { withdrawnAt?: unknown }[] | null | undefined,\n): number {\n  if (!rows) return 0\n  return rows.filter((row) => row?.withdrawnAt == null).length\n}\n\nexport default repeatInfringerVerdict\n"],"names":["STRIKE_LEDGER_SUBCOLLECTION","STRIKE_WARN_AT","STRIKE_FINAL_AT","STRIKE_TERMINATE_AT","repeatInfringerVerdict","strikes","count","Number","isFinite","Math","floor","level","decisionRequired","consequence","STRIKE_WITHDRAWAL_REASONS","isStrikeWithdrawalReason","value","includes","strikeEarnedBy","category","status","strikeRemovedBy","countStandingStrikes","rows","filter","row","withdrawnAt","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiEC,GAED,kEAAkE,GAClE,OAAO,MAAMA,8BAA8B,cAAa;AAExD;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,iBAAiB,EAAC;AAC/B,OAAO,MAAMC,kBAAkB,EAAC;AAChC,OAAO,MAAMC,sBAAsB,EAAC;AAiBpC;;;;;;;CAOC,GACD,OAAO,SAASC,uBAAuBC,OAAgB;IACrD,MAAMC,QACJ,OAAOD,YAAY,YAAYE,OAAOC,QAAQ,CAACH,YAAYA,UAAU,IACjEI,KAAKC,KAAK,CAACL,WACX;IACN,IAAIC,SAASH,qBAAqB;QAChC,OAAO;YACLE,SAASC;YACTK,OAAO;YACPC,kBAAkB;YAClBC,aACE,wEACA,uEACA;QACJ;IACF;IACA,IAAIP,SAASJ,iBAAiB;QAC5B,OAAO;YACLG,SAASC;YACTK,OAAO;YACPC,kBAAkB;YAClBC,aACE,iEACA;QACJ;IACF;IACA,IAAIP,SAASL,gBAAgB;QAC3B,OAAO;YACLI,SAASC;YACTK,OAAO;YACPC,kBAAkB;YAClBC,aACE;QACJ;IACF;IACA,OAAO;QACLR,SAAS;QACTM,OAAO;QACPC,kBAAkB;QAClBC,aAAa;IACf;AACF;AAEA,8DAA8D,GAC9D,OAAO,MAAMC,4BAA4B;IACvC,0CAA0C,GAC1C;IACA,qEAAqE,GACrE;IACA,4DAA4D,GAC5D;CACD,CAAS;AAGV,OAAO,SAASC,yBACdC,KAAc;IAEd,OACE,OAAOA,UAAU,YACjB,AAACF,0BAAgDG,QAAQ,CAACD;AAE9D;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASE,eAAeC,QAAiB,EAAEC,MAAe;IAC/D,OAAOD,aAAa,UAAUC,WAAW;AAC3C;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASC,gBAAgBF,QAAiB,EAAEC,MAAe;IAChE,OACED,aAAa,UAAWC,CAAAA,WAAW,eAAeA,WAAW,UAAUA,WAAW,WAAU;AAEhG;AAEA;;;;;;;CAOC,GACD,OAAO,SAASE,qBACdC,IAA6D;IAE7D,IAAI,CAACA,MAAM,OAAO;IAClB,OAAOA,KAAKC,MAAM,CAAC,CAACC,MAAQA,CAAAA,uBAAAA,IAAKC,WAAW,KAAI,MAAMC,MAAM;AAC9D;AAEA,eAAevB,uBAAsB"}

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

@@ -0,0 +1,115 @@
+/**
+ * @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 { AglynAttributeSchema } from '../foundation/definitions/components.types';
+import type { RepeatableDataset } from './expand-repeatables';
+/**
+ * Where a repeat's rows come from, for the editor (AGL-3111).
+ *
+ * Any element can repeat, and the platform decides what a repeat MEANS — the
+ * scope, the copies, the bounds (`expand-repeatables.ts`). What it does not
+ * decide is what an element repeats OVER. That belongs to the plugin that owns
+ * the rows, which registers a source here from the registration function its
+ * loader calls by name. Core names no source.
+ *
+ * Reached by path, never through a barrel: nothing on a published page asks
+ * where rows come from, so nothing here is in a published page's download.
+ */
+/**
+ * What a source answers for one key.
+ *
+ * - `loading` — no answer yet.
+ * - `missing` — the key names nothing this site may use. The published page
+ *   renders the element once, as written.
+ * - `error` — the read failed. Nothing is known about the rows.
+ * - `ready` — the rows, read and bounded exactly as the published page's
+ *   composition reads them.
+ */
+export type RepeatRowsAnswer = {
+    status: 'loading';
+} | {
+    status: 'missing';
+} | {
+    status: 'error';
+} | {
+    status: 'ready';
+    /** The name authors know the entry by, for the canvas badge. */
+    label: string;
+    /**
+     * The rows under every key the expansion looks them up by: the key as
+     * the node stores it, the entry's id, and each entry a one-hop reference
+     * in the rows reads (`{{item.ref.field}}`).
+     */
+    rowsByKey: Readonly<Record<string, RepeatableDataset>>;
+};
+/** One read a source is asked for. */
+export interface RepeatRowsRequest {
+    /** The site the canvas edits. A source answers only what it may show. */
+    hostId: string;
+    /** The key exactly as the node stores it. */
+    key: string;
+}
+/** One kind of thing an element can repeat over. */
+export interface RepeatSource {
+    /** Stable id, e.g. the plugin's name for the kind. */
+    id: string;
+    /** What the Attributes panel calls the kind. */
+    label: string;
+    /**
+     * The node prop the chosen key persists under. Persisted in documents, so a
+     * source never renames it.
+     */
+    keyProp: string;
+    /**
+     * The attribute that picks a key, drawn by the Attributes panel as any
+     * component attribute is. The panel names the field after `keyProp`.
+     */
+    keyAttribute: Omit<AglynAttributeSchema, 'name'>;
+    /**
+     * 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,
+     * so its identity must not change after registration.
+     */
+    useRows(request: RepeatRowsRequest): RepeatRowsAnswer;
+}
+/**
+ * Registers a source, replacing any registered under its id. Returns the
+ * unregister, which removes the source only if it is still the one registered.
+ *
+ * Call it from a registration function the plugin loader calls BY NAME, never
+ * from a module's top level: a bundler deletes a module imported only for its
+ * side effect when its package says it has none (AGL-3025).
+ */
+export declare function registerRepeatSource(source: RepeatSource): () => void;
+/**
+ * Every registered source, in registration order. The SAME array until the
+ * registered set changes, so it can be read as a store snapshot.
+ */
+export declare function listRepeatSources(): readonly RepeatSource[];
+/** The source registered under `id`. */
+export declare function getRepeatSource(id: string): RepeatSource | undefined;
+/** Called after the registered set changes. Returns the unsubscribe. */
+export declare function subscribeRepeatSources(listener: () => void): () => void;
+/** Moves on every change — the snapshot `useSyncExternalStore` reads. */
+export declare function getRepeatSourcesVersion(): number;
+/**
+ * The registered source a node repeats over, and the key it names, trimmed.
+ * `undefined` for a node that repeats over nothing a registered source owns.
+ */
+export declare function repeatSourceOf(node: unknown): {
+    source: RepeatSource;
+    key: string;
+} | undefined;

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

@@ -0,0 +1,86 @@
+/**
+ * @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.
+ */ const sources = new Map();
+const listeners = new Set();
+let version = 0;
+/**
+ * Replaced only when the registered set changes, never rebuilt per call: it is
+ * the snapshot `useSyncExternalStore` compares, and a fresh array every time
+ * is a render loop rather than a wasted allocation.
+ */ let snapshot = [];
+const notify = ()=>{
+    version += 1;
+    snapshot = [
+        ...sources.values()
+    ];
+    for (const listener of [
+        ...listeners
+    ])listener();
+};
+/**
+ * Registers a source, replacing any registered under its id. Returns the
+ * unregister, which removes the source only if it is still the one registered.
+ *
+ * Call it from a registration function the plugin loader calls BY NAME, never
+ * from a module's top level: a bundler deletes a module imported only for its
+ * side effect when its package says it has none (AGL-3025).
+ */ export function registerRepeatSource(source) {
+    if (sources.get(source.id) !== source) {
+        sources.set(source.id, source);
+        notify();
+    }
+    return ()=>{
+        if (sources.get(source.id) !== source) return;
+        sources.delete(source.id);
+        notify();
+    };
+}
+/**
+ * Every registered source, in registration order. The SAME array until the
+ * registered set changes, so it can be read as a store snapshot.
+ */ export function listRepeatSources() {
+    return snapshot;
+}
+/** The source registered under `id`. */ export function getRepeatSource(id) {
+    return sources.get(id);
+}
+/** Called after the registered set changes. Returns the unsubscribe. */ export function subscribeRepeatSources(listener) {
+    listeners.add(listener);
+    return ()=>{
+        listeners.delete(listener);
+    };
+}
+/** Moves on every change — the snapshot `useSyncExternalStore` reads. */ export function getRepeatSourcesVersion() {
+    return version;
+}
+/**
+ * The registered source a node repeats over, and the key it names, trimmed.
+ * `undefined` for a node that repeats over nothing a registered source owns.
+ */ export function repeatSourceOf(node) {
+    const props = node == null ? void 0 : node.props;
+    if (!props) return undefined;
+    for (const source of sources.values()){
+        const value = props[source.keyProp];
+        const key = typeof value === 'string' ? value.trim() : '';
+        if (key) return {
+            source,
+            key
+        };
+    }
+    return undefined;
+}
+
+//# sourceMappingURL=repeat-sources.js.map

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

@@ -0,0 +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"}

package/src/lib/app-utils/request-geo.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @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.
+ */
+/**
+ * The ONE request-geo reader (AGL-1492/1498).
+ *
+ * Extracted from the console's sanctions module so the tenant's consent-mode
+ * endpoint reads the identical signal the sanctions gate does — two geo
+ * layers would eventually disagree about the same request. The sanctions
+ * POLICY (embargo sets, verdicts, the 451) stays in
+ * `apps/console/constants/sanctions-geo.ts`; this is only the signal.
+ */
+/**
+ * The headers carrying the request's country, subdivision and city, named by
+ * configuration with Vercel's own as the default (AGL-2436).
+ *
+ * These were bare `x-vercel-*` literals, under a comment calling them "the
+ * only geo signal this deployment has" — true of Aglyn's cloud and false of
+ * every self-host install, where no edge sets them. Nothing else supplies the
+ * signal, so on a container `readRequestGeo` returned `null` for every request
+ * and the two things built on it were off in production:
+ *
+ *  - the sanctions gate FAILED OPEN on every request, logging it once per
+ *    instance — an embargo control that is silently not running,
+ *  - the tenant's consent-region endpoint had no region to answer with,
+ *  - the new-device sign-in alert reported "Unknown location" to every user,
+ *    and stored that string, so the breach-notification report that reads a
+ *    data subject's country back off it counted nobody.
+ *
+ * An operator's proxy has the signal under its own name: Cloudflare sends
+ * `cf-ipcountry`, and Caddy/nginx/Traefik can set whatever they are told to.
+ * Naming the header is all that was missing.
+ *
+ * ⚠️ Read with DOT notation and mapped through the `env` block of both
+ * `next.config.js` files, because `apps/console/middleware.ts` imports the
+ * sanctions gate and therefore this module into the EDGE bundle. Next inlines
+ * `process.env.NAME` there at build time and never the bracket form (AGL-2037)
+ * — so these are fixed when the image is built, not when it starts, exactly
+ * like `AGLYN_TENANT_HOST_CNAME`.
+ *
+ * Lower-cased because the value is used as a `Vary` header, where it is echoed
+ * verbatim rather than matched case-insensitively.
+ */
+export declare const GEO_COUNTRY_HEADER: string;
+export declare const GEO_REGION_HEADER: string;
+export declare const GEO_CITY_HEADER: string;
+export interface RequestGeo {
+    /** ISO 3166-1 alpha-2, uppercased. `null` when the edge sent no signal. */
+    country: string | null;
+    /** Bare ISO 3166-2 subdivision code, uppercased. `null` when absent. */
+    region: string | null;
+}
+/** A minimal `Headers`, so route handlers and middleware share one reader. */
+export interface HeaderReader {
+    get(name: string): string | null;
+}
+/**
+ * Every header consulted for the country, in order, configured one first.
+ *
+ * Exported because a caller that varies a cached response on the country has
+ * to name ALL of them: a `Vary` that lists only the configured header is
+ * correct on the one platform whose header that is, and on every other one it
+ * lets a CDN serve a US answer to a European visitor from cache. Aglyn is
+ * self-hostable on Docker with the operator's own Firebase and no particular
+ * edge, so "the one platform" is not an assumption this may make.
+ */
+export declare const GEO_COUNTRY_HEADERS: readonly string[];
+/** Every header consulted for the subdivision, in order, configured one first. */
+export declare const GEO_REGION_HEADERS: readonly string[];
+export declare function readRequestGeo(headers: HeaderReader): RequestGeo;
+/**
+ * The subdivision as a person should read it, rather than as an embargo set
+ * matches it.
+ *
+ * `readRequestGeo().region` is upper-cased and zero-padded because
+ * `EMBARGOED_UA_REGIONS` is an exact-membership test that every spelling of a
+ * code has to land on. That normalization is wrong for anything a person
+ * reads: a proxy configured to send a subdivision NAME rather than a code
+ * reaches a user's security email shouting `CAPITAL`.
+ *
+ * Same headers, same precedence — only the normalization differs, so the two
+ * readers can never disagree about WHICH subdivision a request came from.
+ */
+export declare function readRequestRegionLabel(headers: HeaderReader): string | null;
+/** Every header consulted for the city, in order, configured one first. */
+export declare const GEO_CITY_HEADERS: readonly string[];
+/**
+ * The request's city, decoded, or `null` when no edge sent one.
+ *
+ * Percent-decoded because every edge that sends this header sends non-ASCII
+ * names encoded (`S%C3%A3o%20Paulo`), and an undecoded value reaches a person
+ * as mojibake in a security email. A value that is not valid percent-encoding
+ * is kept verbatim rather than dropped — a literal `%` in a name is not a
+ * reason to lose the city.
+ *
+ * Commas become spaces. Callers join city, region and country with `", "`
+ * into one stored string, and `deviceLocationCountry` reads the country back
+ * off the LAST comma-separated token; a comma arriving inside the city half
+ * would add a token to a string that a breach-notification report parses.
+ */
+export declare function readRequestCity(headers: HeaderReader): string | null;