@tokenoftrust/storefront-runner 4.9.2 → 4.10.0

package/apps/storefront/src/lib/fulfillment/fulfillmentService.ts

@@ -18,7 +18,6 @@ import {
   actorMayCommand,
   decideCommerceCommand,
   publicCommerceEvent,
-  readOwnerAddress,
   totalsMatch,
   type CommerceActor,
   type CommerceEvidence,
@@ -32,6 +31,7 @@ import {
   type StockState,
 } from "@tot/public-runtime";
 import { readD1 } from "@/lib/publication/shared/env";
+import { terminalTransitionExpiryStatement } from "@/lib/orders/vault/orderContactVault.js";
 import { decideAdminApiAccess } from "@/lib/access/auth/adminApiGuard";
 import { readViewerSession } from "@/lib/access/auth/route";
 import type { SessionRecord } from "@/lib/access/auth/session";
@@ -80,7 +80,6 @@ export interface SourceOrderSnapshot {
   totals: MinorTotals;
   evidence: CommerceEvidence;
   lines: readonly { sku: string; quantity: number }[];
-  address: Record<string, unknown> | null;
 }
 
 export interface PackingSlip {
@@ -279,7 +278,6 @@ function observedEvent(input: {
   label: LabelState;
   totals: MinorTotals;
   evidence: CommerceEvidence;
-  address: unknown;
 }): string {
   return jsonText(
     publicCommerceEvent({
@@ -294,7 +292,6 @@ function observedEvent(input: {
       label: input.label,
       totals: input.totals,
       verificationDetail: input.evidence,
-      address: input.address,
     }),
   );
 }
@@ -586,32 +583,6 @@ export class FulfillmentService {
     return ok({ batchId, orders });
   }
 
-  async readAddress(
-    actor: FulfillmentActor,
-    orderId: string,
-  ): Promise<FulfillmentResult<Record<string, unknown>>> {
-    const scope = { tenantId: actor.tenantId, stage: actor.stage };
-    let opened = false;
-    const gate = readOwnerAddress(actor, scope, () => {
-      opened = true;
-      return true;
-    });
-    if (!gate.ok || !opened || !isOpaqueId(actor.actorId)) return refuse("denied");
-    if (!isOpaqueId(orderId)) return refuse("not-found");
-    const row = await this.db.get<{ address_json: string }>(
-      `SELECT address_json FROM scrappy_order_addresses WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
-      [scope.tenantId, scope.stage, orderId],
-    );
-    if (!row) return refuse("not-found");
-    try {
-      const parsed = JSON.parse(row.address_json) as unknown;
-      if (!isRecord(parsed)) return refuse("unreadable");
-      return ok(parsed);
-    } catch {
-      return refuse("unreadable");
-    }
-  }
-
   async applySourceSnapshot(
     actor: FulfillmentActor,
     snapshot: SourceOrderSnapshot,
@@ -956,6 +927,7 @@ export class FulfillmentService {
             ],
           },
           auditStatement(state, actor.actorId, "transition", state.order.fulfillment, "handed_off", version, stamp(this.now(), state.auditCount + 1)),
+          terminalTransitionExpiryStatement(state.order, version, new Date(this.now())),
         ],
       };
     });
@@ -1177,21 +1149,6 @@ export class FulfillmentService {
     ];
     const gate = `tenant_id = ? AND stage = ? AND order_id = ? AND event_version = 1 AND source = ? AND source_order_id = ?`;
     const gateParams = [snapshot.tenantId, snapshot.stage, snapshot.orderId, snapshot.source, snapshot.sourceOrderId];
-    if (snapshot.address) {
-      statements.push({
-        sql: `INSERT INTO scrappy_order_addresses (tenant_id, stage, order_id, address_json)
-          SELECT tenant_id, stage, order_id, ?
-          FROM scrappy_commerce_orders
-          WHERE ${gate}
-            AND NOT EXISTS (
-              SELECT 1 FROM scrappy_order_addresses AS a
-              WHERE a.tenant_id = scrappy_commerce_orders.tenant_id
-                AND a.stage = scrappy_commerce_orders.stage
-                AND a.order_id = scrappy_commerce_orders.order_id
-            )`,
-        params: [jsonText(snapshot.address), ...gateParams],
-      });
-    }
     const stub = {
       order: {
         tenantId: snapshot.tenantId,
@@ -1215,7 +1172,6 @@ export class FulfillmentService {
       gatedAudit(stub, actor.actorId, "evidence", "none", jsonText(snapshot.evidence), at, gate, gateParams),
       gatedAudit(stub, actor.actorId, "lines", "none", jsonText(snapshot.lines), stamp(this.now(), 2), gate, gateParams),
       gatedAudit(stub, actor.actorId, "totals", "none", jsonText(snapshot.totals), stamp(this.now(), 3), gate, gateParams),
-      gatedAudit(stub, actor.actorId, "address-present", "none", snapshot.address ? "yes" : "no", stamp(this.now(), 4), gate, gateParams),
       gatedAudit(
         stub,
         actor.actorId,
@@ -1233,7 +1189,6 @@ export class FulfillmentService {
           label,
           totals: snapshot.totals,
           evidence: snapshot.evidence,
-          address: snapshot.address,
         }),
         stamp(this.now(), 5),
         gate,
@@ -1299,35 +1254,6 @@ export class FulfillmentService {
       statements.push(auditStatement(state, actor.actorId, "lines", "source", jsonText(snapshot.lines), nextVersion, stamp(this.now(), n)));
       n += 1;
       statements.push(auditStatement(state, actor.actorId, "totals", "source", jsonText(snapshot.totals), nextVersion, stamp(this.now(), n)));
-      if (snapshot.address) {
-        statements.push({
-          sql: `INSERT INTO scrappy_order_addresses (tenant_id, stage, order_id, address_json)
-            SELECT ?, ?, ?, ?
-            WHERE EXISTS (
-              SELECT 1 FROM scrappy_commerce_orders
-              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
-            )
-            ON CONFLICT(tenant_id, stage, order_id) DO UPDATE SET address_json = excluded.address_json
-            WHERE EXISTS (
-              SELECT 1 FROM scrappy_commerce_orders
-              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
-            )`,
-          params: [
-            snapshot.tenantId,
-            snapshot.stage,
-            snapshot.orderId,
-            jsonText(snapshot.address),
-            snapshot.tenantId,
-            snapshot.stage,
-            snapshot.orderId,
-            nextVersion,
-            snapshot.tenantId,
-            snapshot.stage,
-            snapshot.orderId,
-            nextVersion,
-          ],
-        });
-      }
       const storedFulfillment = state.order.fulfillment === "handed_off" ? "handed_off" : fulfillment;
       n += 1;
       statements.push(
@@ -1348,7 +1274,6 @@ export class FulfillmentService {
             label,
             totals: snapshot.totals,
             evidence: snapshot.evidence,
-            address: snapshot.address,
           }),
           nextVersion,
           stamp(this.now(), n),
@@ -1357,6 +1282,7 @@ export class FulfillmentService {
       if (confirmedCancel && state.order.fulfillment !== "handed_off") {
         n += 1;
         statements.push(auditStatement(state, actor.actorId, "pending-cancel", "open", "confirmed", nextVersion, stamp(this.now(), n)));
+        statements.push(terminalTransitionExpiryStatement(state.order, nextVersion, new Date(this.now())));
       }
       if (snapshot.sourceVersion !== undefined) statements.push(projectionCheckpoint(snapshot,nextVersion,this.now()));
       return { type: "write", statements, minimumChanges: 1 };
@@ -1657,7 +1583,6 @@ function validateSnapshot(snapshot: SourceOrderSnapshot): string | null {
   if (!oneOf(snapshot.label, LABEL_STATES) || !oneOf(snapshot.stage, ["preview", "publication"] as const)) return "malformed";
   if (!parseEvidence(snapshot.evidence) || !parseLines(snapshot.lines) || !parseTotals(snapshot.totals)) return "malformed";
   if (snapshot.amountMinor !== snapshot.totals.totalMinor || !totalsMatch(snapshot.totals)) return "malformed";
-  if (snapshot.address !== null && !isRecord(snapshot.address)) return "malformed";
   return null;
 }
 

package/apps/storefront/src/lib/integrations/integration/tenantAnalyticsDeclarations.ts

@@ -1,228 +1,68 @@
 /**
- * Tenant-owned analytics declaration surface (TIER 1).
+ * Runtime read of a tenant's own `analytics.json` (TIER 1) for the render hot path.
  *
- * Today a tenant cannot declare a measurement destination from its OWN tree: the
- * declaration lives in `tenant.integrations` (apps/storefront/src/config/tenants.ts),
- * which is platform code a tenant may not touch (customization golden rule #1). So a
- * merchant must file a request for what should be a self-serve, versioned, publishable
- * edit — exactly like `theme.json` or `content/*`.
- *
- * This module is the tenant-tree producer that closes that gap. A tenant commits an
- * `analytics.json` in its own tree (the tenant-owned surface, `tenants/<id>/**`), and
- * this materializes it into the SAME already-consumed declaration seam
- * ({@link IntegrationDeclarationInput}[], read by
- * {@link loadTenantIntegrationDeclarations} and merged into the render plan by the
- * interim bridge). It adds NO new runtime: it is a THIRD producer into an existing
- * consumer, alongside the platform-authored `tenant.integrations` and the D1-backed
- * managed installs.
- *
- * The heavy validation is NOT hand-rolled — each declared destination is built by the
- * shipped, reviewed {@link buildPlatformAdapterDeclaration}, which fail-closes on an
- * unknown adapter, a missing/invalid live id, an invalid per-stage id, or a non-live
- * stage that reuses the live id. That is the whole point: a tenant supplies only public
- * per-stage destination ids and gets a working, consent-gated, CSP-clean, non-live-safe
- * measurement integration with no renderer change.
- *
- * Two callers, one core:
- *   - PUBLISH validation — {@link materializeTenantAnalyticsDeclarations} returns
- *     structured {@link ContractViolation}s so the ship/customization pipeline can
- *     REFUSE an invalid `analytics.json` with an actionable, per-field message, exactly
- *     as it refuses an invalid `theme.json`.
- *   - RUNTIME materialization — {@link loadTenantAnalyticsDeclarations} is fail-closed:
- *     a missing or (defensively) invalid file yields the empty set, never a throw, so an
- *     undeclared tenant resolves the environment-only plan and a byte-identical page.
+ * The contract and its materializer live in `@tot/public-runtime`
+ * ({@link materializeTenantAnalyticsDeclarations}); publish validation refuses an invalid file
+ * before it can reach here. This loader is the defensive last line: fail-closed and value-free.
  */
 import {
-  buildPlatformAdapterDeclaration,
-  ENVIRONMENT_SCHEMA_VERSION,
-  Violations,
-  isEuUkVisitorPolicy,
-  isPlainObject,
-  rejectUnknownKeys,
-  type BrowserEnvironment,
-  type ContractViolation,
+  describeTenantAnalyticsViolations,
+  materializeTenantAnalyticsDeclarations,
   type IntegrationDeclarationInput,
-  type TenantConfig,
+  type TenantAnalyticsMaterialization,
 } from "@tot/public-runtime";
 
-/** The tenant-owned file that declares measurement destinations, in the tenant tree. */
-export const TENANT_ANALYTICS_FILE = "analytics.json";
-
-/** The current `analytics.json` contract version. */
-export const TENANT_ANALYTICS_SCHEMA_VERSION = 1 as const;
-
-/** One declared measurement destination: a first-class adapter + its per-stage public ids. */
-export interface TenantAnalyticsDestination {
-  /** The first-class platform adapter id, e.g. `platform.google-measurement`. */
-  adapter: string;
-  /** Public per-stage destination ids. `live` is required; non-live stages take SEPARATE test ids. */
-  ids: Record<string, unknown>;
-}
-
-/** The result of materializing a tenant's `analytics.json` into declarations. */
-export interface TenantAnalyticsMaterialization {
-  /** True only when EVERY declared destination validated; false surfaces `violations`. */
-  ok: boolean;
-  /** The materialized declarations, in declared order. Empty whenever `ok` is false. */
-  declarations: readonly IntegrationDeclarationInput[];
-  /**
-   * The declared `euUkVisitors` policy when it is not the `count-only` default. Absent
-   * whenever `ok` is false, so an invalid file never widens EU/UK collection.
-   */
-  euUkVisitors?: TenantConfig["euUkVisitors"];
-  /** Per-field violations for the publish surface. Empty whenever `ok` is true. */
-  violations: readonly ContractViolation[];
-}
-
-/**
- * The fixed environment the declaration is CONSTRUCTED against. A first-class adapter
- * declaration is environment-INDEPENDENT in content — its per-stage ids are all baked
- * into `publicConfig` and the client picks the current stage at render time — so the
- * environment here only satisfies {@link buildPlatformAdapterDeclaration}'s validation
- * and its plan-derived CSP requirements. The caller must supply the tenant's real
- * canonical host so those requirements authorize the same-site adapter frame that the
- * browser runtime will construct.
- */
-function constructionEnvironment(canonicalHost: string): BrowserEnvironment {
-  return {
-    schemaVersion: ENVIRONMENT_SCHEMA_VERSION,
-    siteSurface: "storefront",
-    environment: "live",
-    canonicalHost,
-    revision: "tenant-analytics-declaration",
-  };
-}
-
-const EMPTY: readonly IntegrationDeclarationInput[] = Object.freeze([]);
-
-/** Re-anchor a builder violation path under the declaring `destinations[i]` element. */
-function reanchor(violation: ContractViolation, index: number): ContractViolation {
-  const base = `destinations[${index}]`;
-  const path =
-    violation.path === "(root)" || violation.path === ""
-      ? base
-      : violation.path === "adapterId"
-        ? `${base}.adapter`
-        : violation.path.startsWith("adapterId.")
-          ? `${base}.adapter${violation.path.slice("adapterId".length)}`
-          : `${base}.${violation.path}`;
-  return { path, code: violation.code, message: violation.message };
-}
-
-/** Validate the closed shape of one declared destination before it reaches the builder. */
-function readDestination(
-  raw: unknown,
-  index: number,
-  v: Violations,
-): TenantAnalyticsDestination | undefined {
-  const base = `destinations[${index}]`;
-  if (!isPlainObject(raw)) {
-    v.add(base, "type", "A destination must be an object of { adapter, ids }.");
-    return undefined;
-  }
-  rejectUnknownKeys(raw, ["adapter", "ids"], v, base);
-  const adapter = raw["adapter"];
-  if (typeof adapter !== "string" || adapter.length === 0) {
-    v.add(`${base}.adapter`, "type", "A destination adapter must be a non-empty string.");
-    return undefined;
-  }
-  if (!isPlainObject(raw["ids"])) {
-    v.add(`${base}.ids`, "type", "ids must be an object of { stage: destinationId[] }.");
-    return undefined;
+function warnDeclaration(summary: string, violations: readonly { path: string; code: string }[]): void {
+  try {
+    console.warn(`[diag:analytics:declaration] ${summary}`, JSON.stringify({ violations }));
+  } catch {
+    /* diagnostics must never break the caller */
   }
-  return { adapter, ids: raw["ids"] };
 }
 
 /**
- * Parse and materialize a tenant's `analytics.json` content into first-class adapter
- * declarations. `raw` is the already-parsed JSON value (or `undefined`/`null` when the
- * tenant declares none). Fail-closed and whole-file: if ANY declared destination is
- * invalid, NO declaration is produced and the violations name every offending field —
- * a half-valid analytics file never partially materializes.
- */
-export function materializeTenantAnalyticsDeclarations(input: {
-  raw: unknown;
-  tenantPublicId: string;
-  canonicalHost: string;
-}): TenantAnalyticsMaterialization {
-  const { raw, tenantPublicId, canonicalHost } = input;
-  // An undeclared tenant (no file) is the zero-cost norm, not an error.
-  if (raw === undefined || raw === null) {
-    return { ok: true, declarations: EMPTY, violations: [] };
-  }
-
-  const v = new Violations();
-  if (!isPlainObject(raw)) {
-    v.add("(root)", "type", "analytics.json must be a JSON object with a `destinations` array.");
-    return { ok: false, declarations: EMPTY, violations: v.items };
-  }
-  rejectUnknownKeys(raw, ["schemaVersion", "destinations", "euUkVisitors"], v, "");
-  const euUkVisitors = raw["euUkVisitors"];
-  if ("euUkVisitors" in raw && !isEuUkVisitorPolicy(euUkVisitors)) {
-    v.add(
-      "euUkVisitors",
-      "unknown_enum",
-      'euUkVisitors must be "count-only" (the default), "full", or "none".',
-    );
-  }
-  if ("schemaVersion" in raw && raw["schemaVersion"] !== TENANT_ANALYTICS_SCHEMA_VERSION) {
-    v.add(
-      "schemaVersion",
-      "unsupported_version",
-      `schemaVersion must equal ${TENANT_ANALYTICS_SCHEMA_VERSION}.`,
-    );
-  }
-  const destinationsRaw = raw["destinations"];
-  if (!Array.isArray(destinationsRaw)) {
-    v.add("destinations", "type", "`destinations` must be an array.");
-    return { ok: false, declarations: EMPTY, violations: v.items };
-  }
-
-  const declarations: IntegrationDeclarationInput[] = [];
-  destinationsRaw.forEach((destinationRaw, index) => {
-    const destination = readDestination(destinationRaw, index, v);
-    if (!destination) return;
-    const built = buildPlatformAdapterDeclaration({
-      adapterId: destination.adapter,
-      ids: destination.ids,
-      tenantPublicId,
-      environment: constructionEnvironment(canonicalHost),
-    });
-    if (!built.ok) {
-      for (const violation of built.violations) v.items.push(reanchor(violation, index));
-      return;
-    }
-    // Namespace the ref so a tenant-declared adapter can never be mistaken for — or
-    // collide with — the same adapter installed through the managed D1 path.
-    declarations.push({ ...built.declaration, ref: `tenant-analytics:${destination.adapter}` });
-  });
-
-  if (!v.ok) return { ok: false, declarations: EMPTY, violations: v.items };
-  return {
-    ok: true,
-    declarations,
-    violations: [],
-    ...(euUkVisitors === "full" || euUkVisitors === "none" ? { euUkVisitors } : {}),
-  };
-}
-
-/**
- * Read a tenant's already-materialized analytics declarations for the render hot path,
- * fail-closed: a missing OR invalid file yields the empty set (never throws), so an
- * undeclared tenant resolves the environment-only plan and a defensively-invalid file
- * darks its own analytics rather than the page. Publish validation
- * ({@link materializeTenantAnalyticsDeclarations}) is what keeps an invalid file from
- * ever reaching here.
+ * Read a tenant's already-materialized analytics declarations, fail-closed: a missing OR
+ * invalid file yields the empty set (never throws), so an undeclared tenant resolves the
+ * environment-only plan and an invalid file darks its own analytics rather than the page.
+ * A file that is present but holds `null` is invalid; only an absent file (`undefined`)
+ * declares nothing.
+ *
+ * `installed` is what the tenant already declares in platform code. The plan resolves an app
+ * at most once and refuses the whole plan on a repeat, so a destination whose adapter is
+ * already installed there is dropped, keeping the platform's install and the rest of the plan.
+ *
+ * Neither a refusal nor a drop is silent: each emits one `[diag:analytics:declaration]`
+ * warning naming the field path and code. The warning carries no value from the file and no
+ * tenant or destination identifier.
  */
 export function loadTenantAnalyticsDeclarations(
   raw: unknown,
   tenantPublicId: string,
   canonicalHost: string,
+  installed: readonly IntegrationDeclarationInput[] = [],
 ): Pick<TenantAnalyticsMaterialization, "declarations" | "euUkVisitors"> {
-  const { declarations, euUkVisitors } = materializeTenantAnalyticsDeclarations({
+  if (raw === null) {
+    warnDeclaration("analytics.json refused; no analytics declared", [{ path: "(root)", code: "type" }]);
+    return { declarations: [] };
+  }
+  const { ok, declarations, euUkVisitors, violations } = materializeTenantAnalyticsDeclarations({
     raw,
     tenantPublicId,
     canonicalHost,
   });
-  return euUkVisitors ? { declarations, euUkVisitors } : { declarations };
+  if (!ok) {
+    warnDeclaration("analytics.json refused; no analytics declared", describeTenantAnalyticsViolations(violations));
+  }
+  const installedAppIds = new Set(installed.map((declaration) => declaration.manifest.app.id));
+  const dropped: { path: string; code: string }[] = [];
+  // A valid file materializes one declaration per destination, in order.
+  const kept = declarations.filter((declaration, index) => {
+    if (!installedAppIds.has(declaration.manifest.app.id)) return true;
+    dropped.push({ path: `destinations[${index}].adapter`, code: "platform_installed" });
+    return false;
+  });
+  if (dropped.length > 0) {
+    warnDeclaration("analytics.json destination dropped; the platform already installs its adapter", dropped);
+  }
+  return euUkVisitors ? { declarations: kept, euUkVisitors } : { declarations: kept };
 }

package/apps/storefront/src/lib/integrations/webhooks/deliveryEngine.ts

@@ -291,9 +291,13 @@ const COMMERCE_PRIVATE_KEYS = new Set([
   "phone",
   "line1",
   "line2",
+  "city",
+  "company",
   "postalCode",
   "shippingAddress",
   "billingAddress",
+  "shipTo",
+  "billTo",
   "address",
   "firstName",
   "lastName",

package/apps/storefront/src/lib/measurement/admin/analyticsRegionPolicy.ts

@@ -0,0 +1,151 @@
+/**
+ * The EU/UK visitor policy a tenant declares in its own `analytics.json` (`euUkVisitors`), read and
+ * rewritten as TEXT for the admin consent page.
+ *
+ * The rewrite touches only the top-level `euUkVisitors` member: every other byte of the file —
+ * `destinations` above all — is carried through unchanged, so a policy change never reformats or
+ * re-serializes the tenant's destination ids. `ask` is the default and is expressed by ABSENCE, so
+ * choosing it removes the key.
+ */
+import {
+  EU_UK_VISITOR_POLICIES,
+  TENANT_ANALYTICS_SCHEMA_VERSION,
+  isEuUkVisitorPolicy,
+  tenantAnalyticsDeclarationFindings,
+  type EuUkVisitorPolicy,
+  type TenantAnalyticsFinding,
+} from "@tot/public-runtime";
+
+export { EU_UK_VISITOR_POLICIES, isEuUkVisitorPolicy, type EuUkVisitorPolicy };
+
+const POLICY_KEY = "euUkVisitors";
+
+/** The declared policy, `ask` when the file or the key is absent. `null` when the file is not a JSON object. */
+export function readEuUkVisitorPolicy(text: string | null): EuUkVisitorPolicy | null {
+  if (text === null) return "ask";
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    if (err instanceof SyntaxError) return null;
+    throw err;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const value = (parsed as Record<string, unknown>)[POLICY_KEY];
+  if (value === undefined) return "ask";
+  return isEuUkVisitorPolicy(value) ? value : null;
+}
+
+/** Value-free violations for a requested policy: empty when it is one of the four policies. */
+export function euUkVisitorPolicyViolations(value: unknown): TenantAnalyticsFinding[] {
+  if (isEuUkVisitorPolicy(value)) return [];
+  return tenantAnalyticsDeclarationFindings(JSON.stringify({ [POLICY_KEY]: value ?? 0, destinations: [] }));
+}
+
+interface Member {
+  key: string;
+  start: number;
+  valueStart: number;
+  end: number;
+}
+
+function skipWhitespace(text: string, i: number): number {
+  while (i < text.length && /\s/.test(text[i]!)) i += 1;
+  return i;
+}
+
+function stringEnd(text: string, i: number): number {
+  let j = i + 1;
+  while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+  return j + 1;
+}
+
+function valueEnd(text: string, i: number): number {
+  if (text[i] === '"') return stringEnd(text, i);
+  if (text[i] === "{" || text[i] === "[") {
+    let depth = 0;
+    let j = i;
+    while (j < text.length) {
+      const c = text[j]!;
+      if (c === '"') {
+        j = stringEnd(text, j);
+        continue;
+      }
+      if (c === "{" || c === "[") depth += 1;
+      if (c === "}" || c === "]") depth -= 1;
+      j += 1;
+      if (depth === 0) return j;
+    }
+    return j;
+  }
+  let j = i;
+  while (j < text.length && !/[\s,}\]]/.test(text[j]!)) j += 1;
+  return j;
+}
+
+/** The top-level members of a JSON object text already known to parse, with their byte spans. */
+function topLevelMembers(text: string): { open: number; close: number; members: Member[] } {
+  const open = skipWhitespace(text, 0);
+  const members: Member[] = [];
+  let i = skipWhitespace(text, open + 1);
+  while (text[i] === '"') {
+    const keyEnd = stringEnd(text, i);
+    const key = JSON.parse(text.slice(i, keyEnd)) as string;
+    const valueStart = skipWhitespace(text, skipWhitespace(text, keyEnd) + 1);
+    const end = valueEnd(text, valueStart);
+    members.push({ key, start: i, valueStart, end });
+    i = skipWhitespace(text, end);
+    if (text[i] === ",") i = skipWhitespace(text, i + 1);
+  }
+  return { open, close: i, members };
+}
+
+export type PolicyEdit =
+  | { ok: true; changed: false }
+  | { ok: true; changed: true; text: string }
+  | { ok: false; violations: TenantAnalyticsFinding[] };
+
+/**
+ * Rewrite `analytics.json` so its `euUkVisitors` is `policy`, changing no other byte. An absent file
+ * gains a minimal valid declaration only when the policy is not the `ask` default. The result is
+ * validated as a whole file; a file the publish validator would refuse is returned as violations.
+ */
+export function editEuUkVisitorPolicy(text: string | null, policy: unknown): PolicyEdit {
+  const requested = euUkVisitorPolicyViolations(policy);
+  if (requested.length > 0) return { ok: false, violations: requested };
+  const next = policy as EuUkVisitorPolicy;
+  if (readEuUkVisitorPolicy(text) === next) return { ok: true, changed: false };
+
+  let updated: string;
+  if (text === null) {
+    updated = `${JSON.stringify({ schemaVersion: TENANT_ANALYTICS_SCHEMA_VERSION, [POLICY_KEY]: next, destinations: [] }, null, 2)}\n`;
+  } else {
+    const current = readEuUkVisitorPolicy(text);
+    if (current === null && tenantAnalyticsDeclarationFindings(text).some((f) => f.path === "(root)")) {
+      return { ok: false, violations: tenantAnalyticsDeclarationFindings(text) };
+    }
+    updated = rewrite(text, next);
+  }
+  const findings = tenantAnalyticsDeclarationFindings(updated);
+  if (findings.length > 0) return { ok: false, violations: findings };
+  return { ok: true, changed: true, text: updated };
+}
+
+function rewrite(text: string, policy: EuUkVisitorPolicy): string {
+  const { open, close, members } = topLevelMembers(text);
+  const index = members.findIndex((m) => m.key === POLICY_KEY);
+  const literal = JSON.stringify(policy);
+  if (index >= 0) {
+    const member = members[index]!;
+    if (policy !== "ask") return text.slice(0, member.valueStart) + literal + text.slice(member.end);
+    const following = members[index + 1];
+    if (following) return text.slice(0, member.start) + text.slice(following.start);
+    const previous = members[index - 1];
+    if (previous) return text.slice(0, previous.end) + text.slice(member.end);
+    return text.slice(0, open + 1) + text.slice(close);
+  }
+  const first = members[0];
+  if (!first) return `${text.slice(0, open + 1)}"${POLICY_KEY}": ${literal}${text.slice(close)}`;
+  const separator = text.slice(open + 1, first.start);
+  return `${text.slice(0, first.start)}"${POLICY_KEY}": ${literal},${separator}${text.slice(first.start)}`;
+}