@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-replatform/resources/rp-target-wix/lib/write-verification.js

@@ -0,0 +1,3 @@
+'use strict';
+// Compatibility entry point; receipt comparison is shared runtime code.
+module.exports = require('../../../lib/write-verification');

package/skills/wix-replatform/resources/rp-target-wix/scripts/docs-survey-sync.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+'use strict';
+
+// Fetch a domain's dev.wix.com docs menu(s) and sync
+// domains/<domain>/docs-survey.json. The script owns the surface list (id,
+// title, url, group); verdict fields are authored by hand and preserved
+// across syncs. New surfaces arrive as "unreviewed", which fails validation
+// until triaged; surfaces gone from the docs are marked "removed", which
+// also fails validation until the entry is deleted or its facts revisited.
+//
+// Usage: node docs-survey-sync.js <domain> [<domain>...]
+// Requires domains/<domain>/domain.json to declare docsRoots[] (paths under
+// https://dev.wix.com/docs/, e.g. "api-reference/business-solutions/events").
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { knowledgeRoot, writeJson } = require('../lib/domain-knowledge.js');
+
+const DOCS_BASE = 'https://dev.wix.com/docs/';
+const HEADING_RE = /^(#{1,6}) \[([^\]]+)\]\((https:\/\/dev\.wix\.com\/docs\/[^)]+?)(?:\.md)?\)\s*$/;
+
+async function fetchMenuMarkdown(root) {
+  const url = `${DOCS_BASE}${root}.md`;
+  const response = await fetch(url, { redirect: 'follow' });
+  if (!response.ok) throw new Error(`GET ${url} -> HTTP ${response.status}`);
+  return response.text();
+}
+
+// A menu page lists its whole ancestry too (# Api Reference, ## Business
+// Solutions, ...). Only headings strictly below the fetched root are the
+// domain's own; among those, the surfaces are the deepest headings — the
+// ones with no child headings.
+function extractSurfaces(markdown, root) {
+  const headings = [];
+  let rootTitle = null;
+  for (const line of markdown.split('\n')) {
+    const match = line.match(HEADING_RE);
+    if (!match) continue;
+    const docsPath = match[3].slice(DOCS_BASE.length);
+    if (docsPath === root) rootTitle = match[2];
+    if (!docsPath.startsWith(`${root}/`)) continue;
+    headings.push({ level: match[1].length, title: match[2], docsPath });
+  }
+
+  // A flat tree (all methods as bullets, no sub-headings) is still one
+  // surface — the root itself. Never let a root vanish silently.
+  if (headings.length === 0) {
+    return [
+      {
+        id: root,
+        title: rootTitle || root.split('/').pop(),
+        url: `${DOCS_BASE}${root}`,
+        group: null,
+      },
+    ];
+  }
+
+  const surfaces = [];
+  for (let i = 0; i < headings.length; i += 1) {
+    const heading = headings[i];
+    const next = headings[i + 1];
+    const hasChildren = next && next.level > heading.level;
+    if (hasChildren) continue;
+    const group = [];
+    for (let j = i - 1, level = heading.level; j >= 0; j -= 1) {
+      if (headings[j].level < level) {
+        group.unshift(headings[j].title);
+        level = headings[j].level;
+      }
+    }
+    surfaces.push({
+      id: heading.docsPath,
+      title: heading.title,
+      url: `${DOCS_BASE}${heading.docsPath}`,
+      group: group.join(' › ') || null,
+    });
+  }
+  return surfaces;
+}
+
+function mergeSurvey(existing, domain, roots, fetched) {
+  const previous = new Map(((existing && existing.surfaces) || []).map((entry) => [entry.id, entry]));
+  const surfaces = fetched.map((surface) => {
+    const kept = previous.get(surface.id);
+    previous.delete(surface.id);
+    const verdictFields = kept
+      ? {
+          verdict: kept.verdict,
+          refs: kept.refs,
+          reason: kept.reason,
+          tracking: kept.tracking,
+          reviewedOn: kept.reviewedOn,
+        }
+      : { verdict: 'unreviewed' };
+    for (const key of Object.keys(verdictFields)) {
+      if (verdictFields[key] === undefined) delete verdictFields[key];
+    }
+    return { ...surface, ...verdictFields };
+  });
+  for (const gone of previous.values()) {
+    surfaces.push({ ...gone, removed: true });
+  }
+  surfaces.sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    schemaVersion: 1,
+    domain,
+    fetchedAt: new Date().toISOString().slice(0, 10),
+    roots,
+    surfaces,
+  };
+}
+
+async function syncDomain(domainsDir, domain) {
+  const domainJsonPath = path.join(domainsDir, domain, 'domain.json');
+  const domainJson = JSON.parse(fs.readFileSync(domainJsonPath, 'utf8'));
+  const roots = domainJson.docsRoots;
+  if (!Array.isArray(roots) || roots.length === 0) {
+    throw new Error(`${domain}/domain.json has no docsRoots[]; declare the domain's docs menu roots first`);
+  }
+  const fetchedByRoot = await Promise.all(
+    roots.map((root) => fetchMenuMarkdown(root).then((md) => extractSurfaces(md, root))),
+  );
+  const fetched = fetchedByRoot.flat();
+
+  const surveyPath = path.join(domainsDir, domain, 'docs-survey.json');
+  const existing = fs.existsSync(surveyPath) ? JSON.parse(fs.readFileSync(surveyPath, 'utf8')) : null;
+  const survey = mergeSurvey(existing, domain, roots, fetched);
+  writeJson(surveyPath, survey);
+
+  const unreviewed = survey.surfaces.filter((s) => s.verdict === 'unreviewed').length;
+  const removed = survey.surfaces.filter((s) => s.removed).length;
+  process.stdout.write(
+    `${domain}: ${survey.surfaces.length} surfaces (${unreviewed} unreviewed, ${removed} removed) -> ${path.relative(process.cwd(), surveyPath)}\n`
+  );
+}
+
+async function main() {
+  const domains = process.argv.slice(2).filter((arg) => !arg.startsWith('--'));
+  if (domains.length === 0) {
+    process.stderr.write('Usage: docs-survey-sync.js <domain> [<domain>...]\n');
+    process.exit(2);
+  }
+  const domainsDir = knowledgeRoot(path.resolve(__dirname, '..'));
+  for (const domain of domains) await syncDomain(domainsDir, domain);
+}
+
+main().catch((error) => {
+  process.stderr.write(`ERROR: ${error.message}\n`);
+  process.exit(1);
+});

package/skills/wix-replatform/resources/rp-target-wix/scripts/domain-knowledge-validate.js

@@ -2,11 +2,49 @@
 'use strict';
 
 const path = require('node:path');
-const { knowledgeRoot, validateKnowledge, writeJson } = require('../lib/domain-knowledge.js');
+const { knowledgeRoot, validateKnowledge, writeJson, listMissingDependsOn, checkScope } = require('../lib/domain-knowledge.js');
 
 function main() {
-  const args = new Set(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  const args = new Set(argv);
   const domainsDir = knowledgeRoot(path.resolve(__dirname, '..'));
+
+  if (args.has('--list-missing-deps')) {
+    // The live backlog — entities that have never had dependsOn authored at all.
+    // Non-blocking report, not a validation error; this is the thing to run instead of
+    // trusting a hand-maintained list to stay accurate.
+    const missing = listMissingDependsOn(domainsDir);
+    process.stdout.write(`${missing.length} entit${missing.length === 1 ? 'y has' : 'ies have'} no dependsOn yet:\n`);
+    for (const ref of missing) process.stdout.write(`  ${ref}\n`);
+    return;
+  }
+
+  const checkScopeIndex = argv.indexOf('--check-scope');
+  if (checkScopeIndex !== -1) {
+    // The rp-mapper review-gate check: pass only the plan's own selected scope — checkScope
+    // walks the transitive closure itself. --check-scope stores/product,gift-cards/gift-card,ecom/order
+    const inScopeRefs = (argv[checkScopeIndex + 1] || '').split(',').map((s) => s.trim()).filter(Boolean);
+    if (inScopeRefs.length === 0) {
+      process.stderr.write('ERROR: --check-scope requires a comma-separated list of domain/entity refs\n');
+      process.exit(1);
+    }
+    const result = checkScope(domainsDir, inScopeRefs);
+    if (result.ok) {
+      process.stdout.write('OK: every selected ref resolves, every reachable dependency is in scope, and every reachable entity has been reviewed\n');
+      return;
+    }
+    for (const ref of result.unknownRefs) {
+      process.stdout.write(`UNKNOWN: ${ref} does not resolve to a real domain/entity file\n`);
+    }
+    for (const { ref, missing } of result.missingDependencies) {
+      process.stdout.write(`MISSING: ${ref} depends on ${missing.join(', ')}, not in scope for this plan\n`);
+    }
+    for (const ref of result.unreviewedRefs) {
+      process.stdout.write(`UNREVIEWED: ${ref} is reachable from this scope but has never had dependsOn authored\n`);
+    }
+    process.exit(1);
+  }
+
   const result = validateKnowledge(domainsDir);
 
   if (args.has('--write-index')) {

package/skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 'use strict';
+const { startDevProbe } = require('../../../lib/execution-capability');
 
 const fs = require('fs');
 const path = require('path');
@@ -13,6 +14,7 @@ const {
 function usage() {
   console.error(`Usage:
   node scripts/verify-stores.js stores subscription-create --artifact <file> [--proposal-artifact <file>] [--marker <id>] [--no-cleanup]
+  node scripts/verify-stores.js stores inventory-import --env <test-target-config> --artifact <file>
   node scripts/verify-stores.js stores product-count --artifact <file>
   node scripts/verify-stores.js stores product-by-source-marker --marker-path <path> --marker-value <value> --artifact <file>
   node scripts/verify-stores.js stores delete-probe --product-id <id> --artifact <file>
@@ -60,7 +62,7 @@ function loadEnvFile(file) {
   const authToken = process.env.WIX_AUTH_TOKEN;
   const siteId = process.env.WIX_SITE_ID;
   if (!authToken || !siteId) throw new Error('WIX_AUTH_TOKEN and WIX_SITE_ID are required');
-  const wix = w.createWixClient({ authToken, siteId });
+  const wix = w.createWixClient({ authToken, capability: startDevProbe({ siteId, confirmation: process.env.RP_SENTINEL_CONFIRM }) });
   const common = { wix, siteId, artifactPath: options.artifact };
 
   let result;
@@ -84,6 +86,9 @@ function loadEnvFile(file) {
         fs.writeFileSync(options.artifact, `${JSON.stringify(result, null, 2)}\n`);
       }
     }
+  } else if (command === 'inventory-import') {
+    if (!options.artifact) throw new Error('inventory-import requires --artifact for recovery and verification evidence');
+    result = await verify.verifyStoresInventoryImport(common);
   } else if (command === 'product-count') {
     result = await verify.verifyStoresProductCount(common);
   } else if (command === 'product-by-source-marker') {

package/skills/wix-replatform/resources/rp-telemetry/SKILL.md

@@ -60,10 +60,20 @@ what to fix.
 | `meter [--api-ms N --model-ms N --script-ms N --input-tokens N …]` | Measured latency/token counts for a stage. Call it whenever you have real numbers; see "Metering" below. |
 | `wait start [--halt <subtype> --skill <s> [--what '<text>']]` / `wait end` | The moment the run halts for the user, and the moment it resumes. This is how user latency stays out of `active_ms` — never estimate elapsed time yourself. Pass `--halt` for a needs-user halt and the recorder emits the paired `halt_needs_user` event for you. |
 | `record '<event-json>'` | The moment something observable happens (taxonomy below). |
+| `digest --transcript <path> [--offline]` | Just before `finalize` — a deterministic parse of this run's Claude Code session transcript (cost, turn counts, tool failures, retry loops, hook errors). Never authored by you; `--offline` re-runs it later against a checkpointed or local transcript for a run that died before calling it. |
 | `finalize '<rollup-json>'` | When the run reaches a terminal state. |
 | `rebuild [--attempt <n>] [--push]` | Only on request, to re-assemble a past run's signal document from its archived journal after a recorder fix — never during a run. `--push` re-emits the rebuilt run to the BI sink (backfill after an outage; idempotent — the reviewer dedupes at query time). |
 | `status` | To orient after a resume. |
 
+Preflight reads that same `status` and reports whether a journal exists — `active`,
+`absent`, `finalized_only` or `unreadable` — as a non-blocking line in its result. When
+nothing is recording, the preflight script then calls `start` itself (moving an
+unreplayable journal aside first) and adds a `recovery` field to that line. This is a
+safety net, not the main path: `start` at run begin below stays required. A
+`recovery: failed` reading falls under the "never mention" rule below — it is recorded for
+the RePlatform team in the preflight result and progress log, never told to the person
+running the migration, and never blocks the run.
+
 ### Run lifecycle
 
 1. **`start`** as the first telemetry act of the run, with whatever dimensions are already
@@ -80,6 +90,23 @@ what to fix.
    one more session) and closes any open wait interval. `start` after a finalized run
    opens the next attempt. Never try to manage run identity yourself.
 
+   **Always `start` on resume, even mid-stage.** Besides the session accounting, the
+   resume is a BI heal point: the recorder re-pushes everything the previous session's
+   transport may have lost (push failures are journaled, then healed at the next
+   opportunity — a halted run may never reach finalize, so skipping the resume `start`
+   can strand the run's tail in the local journal). `status` shows `bi_backlog: true`
+   when unpushed rows are pending.
+
+   A safety net backs this up, and it does not replace your `start`: the start of a
+   `replatform run`/`resume` supervisor process, and the orchestration route script after
+   at least 15 minutes of journal silence, record the resumed session themselves on an
+   open recording (tagged with a `trigger`). A `start` within a minute of such an automatic
+   session, or at any point during the live supervisor run that opened it, joins that
+   session instead of opening another — it still records the dimensions you pass. The
+   15-minute gap is a heuristic about sittings, not a detected session. A failed or
+   skipped automatic resume falls under the "never mention" rule below: it goes only to
+   the progress log or the supervisor's run record.
+
    `source_acquisition` is an open set of class tokens, but reuse an established one
    (`admin_api`, `public_storefront`, `public_content`, `file_export`) rather than
    minting a synonym — cross-run folding depends on stable tokens.
@@ -104,6 +131,29 @@ what to fix.
    dims (a runtime with better provenance than the recorder can infer), but normally you
    leave them to auto-resolve.
 
+   **Operator identity is auto-stamped too — you don't pass it, and you must not
+   invent it.** At `start` the recorder resolves `wix_user_id` (the operator's Wix
+   user GUID) from the Wix CLI's login artifact, `~/.wix/auth/account.json`. If the
+   CLI isn't logged in, resolution returns nothing and the run proceeds
+   **unattributed**: it completes normally, its local record is untouched and
+   authoritative, but **BI receives nothing** — the sink cannot route a row without a
+   real user, and a fabricated subject was verified to ingest nothing. The
+   loss is journaled as `no_operator_identity` and flagged in the rollup as
+   `operator_identity_unresolved`; `rebuild --push` backfills it if identity later
+   becomes available.
+
+   **Never mention any of this to the person running the migration.** Telemetry
+   health is our signal, not theirs: it says nothing about whether their migration
+   worked, and an unattributed run is complete and correct. It is read from BI and
+   the local rollup, not narrated in a completion report. The same goes for push
+   failures and `bi_push` counts — they belong in the telemetry record only.
+
+   You may pass `wix_user_id` explicitly in the `start` dims and it wins over
+   resolution, but only when the runtime genuinely knows better (a hosted runner
+   that authenticated the operator itself). Never pass a GUID you guessed, copied
+   from another run, or read off a site — a wrong identity misattributes the run to
+   a real person and is worse than no identity at all.
+
 2. **Stage boundaries** as the pipeline moves. Map orchestrator steps to stages like this:
 
    | Stage | Covers |
@@ -131,9 +181,14 @@ what to fix.
    `extract` stage exists to prevent.
 
    When the `discovery` stage ends, **always** stamp what it learned:
-   `dims '{"source_platform_version":"...","source_extensions":["..."]}'` — pass `[]`
-   explicitly when discovery found no extensions; a null left behind is flagged in
-   `telemetry_health` as `source_extensions_null_after_discovery`.
+   `dims '{"source_platform_version":"...","source_extensions":["..."],
+   "discovered_entity_types":["post","product","event"]}'` — pass `[]` explicitly when
+   discovery found no extensions (or, improbably, no entity types); a null left behind is
+   flagged in `telemetry_health` as `source_extensions_null_after_discovery` /
+   `discovered_entity_types_null_after_discovery`. `discovered_entity_types` lists every
+   source entity class discovery found in use — including classes with no Wix target; it
+   is what finalize cross-checks the `volumes` rows against, so the "what we couldn't
+   import" demand signal cannot be silently under-reported.
 
 3. **`wait start` / `wait end`** around every needs-user halt: credential requests, the
    mapping-review checkpoint, the approval gate, any halt-to-needs-user. Pass the halt
@@ -151,7 +206,12 @@ what to fix.
 4. **`record`** events as they happen (next section). Record in the moment, not
    retrospectively — improvisation and halts are only reliably knowable when they occur.
 
-5. **`finalize`** once, at a terminal state, with the rollup:
+5. **`digest --transcript <path to this session's CC transcript>`** just before `finalize`.
+   It parses the Claude Code session transcript, deterministically — no model, no
+   judgment, nothing for you to say. If it fails, carry on to `finalize` anyway;
+   telemetry never blocks a migration.
+
+6. **`finalize`** once, at a terminal state, with the rollup:
 
    ```bash
    node scripts/rp-telemetry.js finalize '{"terminal_state":"completed",
@@ -171,7 +231,9 @@ what to fix.
      skipped: N`, `target: none` where no target exists, `planned` 0 or null). "What we
      cannot or chose not to import" must be signal-layer arithmetic, never an evidence
      dig — rows only for imported types silently erase the excluded half of the approved
-     plan.
+     plan. This is enforced mechanically: on a completed run, any class stamped in
+     `discovered_entity_types` with no volume row is flagged
+     `volume_row_missing:<type>` in `telemetry_health`.
    - `verification` makes the finish step's spot-checks countable. `checked: 0` is an
      honest "written but unverified" — report it rather than papering over it.
    - Do **not** finalize a halt you expect the user to resume — leave the run unfinalized
@@ -179,6 +241,17 @@ what to fix.
      being closed out in a stalled state. A user who declines the plan is
      `abandoned_by_user` (plus a `user_decision` event with `subtype: declined`), never
      `halted_needs_user` or `failed`.
+   - **Check the returned `bi_push`.** If it reports `failed > 0` or `skipped > 0`, the
+     run (or part of it) did not reach the central BI record: retry once with
+     `rebuild --push`, and if it still fails, tell the operator in the completion report
+     that the run exists only locally — never let a run silently vanish from the shared
+     record. `skipped > 0` means `RP_TELEMETRY_BI_DISABLED` was set during the session;
+     on a real migration run that env var must never be set. **A clean `bi_push` result
+     (`failed: 0`, `skipped: 0`) means the rows were handed to frog, not that they have
+     arrived in BI** — per `bi-sink.js`'s own transport code, a 2xx is not an ingestion
+     receipt; only a Trino read-back proves arrival, and no such read-back is available
+     from inside a run. Report `bi_push` success as "handed off," never as "confirmed in
+     BI."
 
 ### Metering — splitting `active_ms` into where the time actually went
 
@@ -201,8 +274,8 @@ node scripts/meter-from-audit.js --project <migration dir> --stage import   # --
 
 It reads `logs/import-audit.ndjson` and emits measured `api_ms` / `api_calls` / `api_retries`.
 It exists because a bulk write logs **one audit row per item, each carrying the batch's total
-latency** — summing rows multiplies one call's latency by its item count, which on a real run
-reported 1,050,992 ms of API time inside a stage that only existed for 346,505 ms. The helper
+latency** — summing rows multiplies one call's latency by its item count, which can
+report several times more API time than the stage existed for. The helper
 collapses rows per distinct `(runId, endpoint, batch, latencyMs)`, so a batch counts once while
 genuinely separate calls each count.
 
@@ -234,6 +307,34 @@ The rollup's `timing.agentic_ms` vs `timing.deterministic_ms` (and `agentic_shar
 that shows whether moving work into deterministic code is paying off. `agentic_share` is `null` when
 nothing was metered rather than `0`, which would falsely read as a fully deterministic run.
 
+### Source key/value reads — the one capability that widened what we can read
+
+The WordPress bridge can read key/value ("EAV") tables like `postmeta`, key-scoped.
+That is the largest widening of source-read reach this pipeline has taken, so it is counted.
+
+```bash
+node scripts/rp-telemetry.js source-read --discovery-queries 1 --discovery-table postmeta --redacted-values 0 --project <dir>
+node scripts/rp-telemetry.js source-read --scoped-queries 6 --scoped-table postmeta --redacted-values 2 --project <dir>
+node scripts/rp-telemetry.js source-read --tier-refusals 1 --project <dir>
+```
+
+Counts accumulate across calls, so report per batch rather than holding a running total.
+`wix-wp-plugin-v2-client.js` derives the per-read counts for you and hands them to its
+`onSourceRead` hook — use that rather than counting at a call site, because the call site that
+forgets is what makes a run's total quietly wrong.
+
+**`redacted_values` is the field worth watching across runs.** The other three describe how one
+migration read one site. A non-zero redaction total means a source site keeps a credential in a
+column nobody expected, which is a fleet-level signal no single run can see. `tier_refusals` has
+to be reported by the caller rather than inferred, because the plugin answers a tier violation
+with the same 400 as a nonexistent column — deliberately, so a refusal never discloses which
+column holds the values.
+
+**Key names are never telemetry.** The run's own artifacts hold those. `discovery_tables` and
+`scoped_tables` carry bare WordPress table names (`postmeta`), which are structural, not customer
+data; the validator rejects anything that is not `^[A-Za-z0-9_]+$`, and rejects a `pinned_keys`
+field outright as unknown. Nothing here should ever be able to carry a value.
+
 ### Collecting `operator_acceptance`
 
 At the finish handoff, ask the operator one plain question: does the migrated result look
@@ -319,6 +420,41 @@ active `rp-*` resource, e.g. `"rp-mapper"`), `severity` (`blocking` | `degraded`
    or misleading as evidence) | `other`. Name the artifacts and their states in
    `what_happened` — names and states, never contents.
 
+9. **`source_plugin_coverage`** — which of the source site's plugins we could **not** resolve,
+   plus one run-level summary. Record after discovery writes
+   `discovery/plugin-coverage.json`.
+
+   **Record one event per unresolved item only.** The unresolved set is: every `pending` row
+   (including `reason: cannot-tell` and unread candidate namespaces), every
+   `requires-development` row, and every row carrying `blocked[]` entries (a
+   `user-file` / `credential` / `surface-changed` blocker, declined or not). **These are the
+   whole point of this event type** — they are the only signal that says which plugin profile
+   to write next, and without them that ordering is guesswork.
+
+   **Do not emit a per-row event for anything already resolved**: `migration-planned` rows
+   with `confidence: confirmed`, or `no-need-to-migrate` rows with `basis: list` or
+   `basis: decision` (a human already signed that verdict). On a
+   55-plugin store that would be ~29 events restating a checked-in list — telemetry with no
+   information content, which makes the real backlog harder to see, not easier. (A
+   `migration-planned` or `no-need-to-migrate` row that automation *derived* —
+   `confidence: proposed` / `basis: proposed` — is reported through `skill_coverage_gap`
+   (`guessed_value`), not here.)
+
+   **Emit exactly one aggregate event per run** carrying the distribution: plugins installed,
+   counts by the four statuses (and by `via` / `confidence` for planned rows), blocked counts
+   by kind, and whether the plugin list was available. That preserves the cross-run view of
+   how coverage is trending without one event per plugin.
+
+   Per-event fields: `subtype` is the row's status (`pending` | `requires_development`) or
+   `blocked` for a blocker entry (then also carry the blocker `kind`); carry the plugin slug
+   and version, the capability, the read channel, whether the row was `recognized`, and
+   `source_api_surface` as the endpoint class. Slug and version are required — without them
+   a cross-run view cannot tell which plugin caused what. Plugin slugs and versions are
+   software identifiers, not client data; still never record site URLs or record contents.
+
+   A `requires-development` row additionally pairs with `api_gap`, and a lossy `via: cms` row
+   with `fidelity_loss` — this event reports *distribution and backlog*, never the gap itself.
+
 ### `evidence_refs` — rare, not routine
 
 Author every event to be **self-sufficient**: coded fields + bounded free text +
@@ -333,7 +469,11 @@ when files regenerate). Never reference secret-bearing config files.
 - Never hand-write, edit, or re-read `run-telemetry.json` or `telemetry/` files — the
   recorder appends; you only call it.
 - Never record client data values, names, URLs beyond the recorded source origin, or
-  secrets — in any field, including shapes and locators.
+  secrets — in any field, including shapes and locators. For a credential-bearing source
+  surface such as a payment gateway's configuration, telemetry may carry the **field name** and
+  its state (`present` / `blank` / `absent`) and nothing else: never the value, never a prefix
+  of it, never its length, never a hash. A length narrows a brute force and a hash confirms a
+  guess, so neither is a safe substitute for the value.
 - Never record a fix, root cause, or recommendation — observations only.
 - Never estimate durations — timing comes from `stage`/`wait` boundary calls.
 - Never skip a rejected call: fix the listed fields and retry. Rejections are counted

package/skills/wix-replatform/resources/rp-telemetry/lib/bi-sink.js

@@ -1,8 +1,8 @@
 'use strict';
 
-// Wix BI sink for the telemetry recorder — the one transport path (spec 0007).
+// Wix BI sink for the telemetry recorder — the one transport path.
 //
-// Wire format (proven end-to-end 2026-07-26, see research/bi-ingestion-surface.md):
+// Wire format (proven end-to-end 2026-07-26):
 // POST https://frog.wix.com/migration-data-validator with a JSON batch envelope
 //   {"dt":0,"g":{"src":10,"evid":<evid>},"e":[{"dt":0,"f":{...fields}}]}
 // capped at 100 events / ~240KB per request. No transport auth — identity is the
@@ -15,6 +15,10 @@
 //   2. Every GUID-typed field must be a real GUID; a non-hex value fails
 //      validation before routing and drops the whole event.
 //   3. Every row carries `logged_user_id` = the operator's wix_user_id (GUID).
+//      A run with no identity is NOT pushed: BI discards rows whose subject is not
+//      a real user, so a fabricated one (verified 2026-09-02 with the nil UUID)
+//      returns 2xx and ingests nothing. Better to journal the loss than to fake a
+//      success.
 //
 // frog's HTTP status is not an ingestion receipt — only a Trino read-back proves
 // arrival. The recorder treats any non-2xx or network error as a push failure
@@ -84,9 +88,12 @@ function startedRunRow(runStart, wixUserId) {
 }
 
 // `replatform_run` phase:finalized — the complete rollup. Local names map to the
-// as-registered BI names here and nowhere else (spec 0007, Registration notes):
-// schema_version→schemaVersions, verification→verificationType. skills_commit is
-// local-only (not a registered BI column) and deliberately not sent.
+// as-registered BI names here and nowhere else (see the Registration notes):
+// schema_version→schemaVersions, verification→verificationType. skills_commit and
+// discovered_entity_types are local-only (not registered BI columns) and
+// deliberately not sent — the entity-class demand signal reaches BI through the
+// `volumes` column; the dim exists for the finalize cross-check, whose flags
+// travel in telemetryHealth.
 function finalizedRunRow(rollup) {
   const f = { phase: 'finalized' };
   put(f, 'runId', rollup.run_id, { guid: true });
@@ -118,6 +125,31 @@ function finalizedRunRow(rollup) {
   put(f, 'runStarted', rollup.run_started);
   put(f, 'runEnded', rollup.run_ended);
   put(f, 'bundleManifest', rollup.bundle_manifest, { json: true });
+  // The transcript_digest is a run-grain fact, so it rides the
+  // existing finalized row rather than opening a new BI call — one JSON field,
+  // matching how `stages`/`volumes` already travel, rather than one registered
+  // column per sub-field. A run with no digest (offline recompute skipped, or
+  // a run that predates 1.5.0) simply omits the field, same as any unknown.
+  //
+  // Known limitation (verified live): as of 2026-08-17, `bi_events_raw`
+  // shows evid 5012 rows with an EMPTY dimensions/measures map for every one of them —
+  // this field will land alongside `terminalState`/`volumes`/every other field already
+  // on this row and be equally unqueryable until whoever owns the BI schema resolves
+  // why 5012/5013 aren't materializing their payload. Nothing to fix here: this `put()`
+  // call matches the pattern every other field on the row already uses correctly.
+  put(f, 'transcriptDigest', rollup.transcript_digest, { json: true });
+  // The run's key/value source-read counts. Rides the finalized row as one
+  // JSON field, exactly like transcript_digest above and for the same reason -- it is a
+  // run-grain fact, not a new grain.
+  //
+  // This has to leave the machine to be worth anything. `redacted_values` is explicitly a
+  // CROSS-RUN signal: one run's non-zero count says little, while a rate across runs says
+  // some sites keep credentials where nobody expects them, and that is a fleet-level fact no
+  // single run can see. Computing it into a local file and stopping there would satisfy the
+  // letter of "record it" and none of the point.
+  //
+  // Same known 5012/5013 materialization limitation the comment above documents applies.
+  put(f, 'sourceReads', rollup.source_reads, { json: true });
   return { evid: EVID_RUN, fields: f };
 }
 
@@ -173,28 +205,54 @@ function shedOversize(event) {
   return shed ? { ...event, f } : null;
 }
 
-async function sendBatch(evid, events) {
+// `signal` (optional) is the caller's cancellation. The request is aborted when either the
+// per-request PUSH_TIMEOUT_MS expires or the caller aborts; the combined signal is built with a
+// local controller (listener + cleared timer) so nothing outlives the call and no Node API newer
+// than the supported runtime is needed. A caller abort maps to `aborted`; the timeout stays
+// `timeout`.
+async function sendBatch(evid, events, signal) {
   const body = envelopeBody(evid, events);
+  if (signal && signal.aborted) return 'aborted';
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, PUSH_TIMEOUT_MS);
+  const onAbort = () => controller.abort();
+  if (signal) signal.addEventListener('abort', onAbort, { once: true });
   try {
     const res = await fetch(endpoint(), {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body,
-      signal: AbortSignal.timeout(PUSH_TIMEOUT_MS),
+      signal: controller.signal,
     });
     if (!res.ok) return `http_${res.status}`;
     return null;
-  } catch (error) {
-    return error && error.name === 'TimeoutError' ? 'timeout' : 'network_error';
+  } catch {
+    if (signal && signal.aborted) return 'aborted';
+    return timedOut ? 'timeout' : 'network_error';
+  } finally {
+    clearTimeout(timer);
+    if (signal) signal.removeEventListener('abort', onAbort);
   }
 }
 
 // Push rows (from the builders above) as the given operator. Never throws:
-// returns { sent, failures: [{evid, rows, detail}], truncated } and the caller
-// journals the failures — telemetry must never block a migration.
-async function pushRows(rows, loggedUserId) {
-  const out = { sent: 0, failures: [], truncated: 0 };
-  if (disabled() || rows.length === 0) return out;
+// returns { sent, failures: [{evid, rows, detail}], truncated, skipped } and
+// the caller journals the failures — telemetry must never block a migration.
+// A disabled sink reports the rows it swallowed in `skipped` instead of
+// masquerading as a successful push — the caller journals those too, so a
+// kill-switch leaking into a production session is visible, never silent.
+//
+// `signal` (optional): once it aborts, nothing more is sent and every row not yet sent is
+// reported as ONE failure `{ detail: 'aborted' }` — the caller journals a single marker and the
+// rows stay backlog for the next heal. Without a signal, behavior is unchanged.
+async function pushRows(rows, loggedUserId, { signal } = {}) {
+  const out = { sent: 0, failures: [], truncated: 0, skipped: 0 };
+  if (rows.length === 0) return out;
+  if (disabled()) {
+    out.skipped = rows.length;
+    return out;
+  }
   if (!isGuid(loggedUserId)) {
     out.failures.push({ evid: null, rows: rows.length, detail: 'no_operator_identity' });
     return out;
@@ -204,9 +262,15 @@ async function pushRows(rows, loggedUserId) {
     if (!byEvid.has(row.evid)) byEvid.set(row.evid, []);
     byEvid.get(row.evid).push({ dt: 0, f: { ...row.fields, logged_user_id: loggedUserId } });
   }
+  let accounted = 0;
+  const abortRest = () => {
+    out.failures.push({ evid: null, rows: rows.length - accounted, detail: 'aborted' });
+    return out;
+  };
   for (const [evid, events] of byEvid) {
     const queue = [events];
     while (queue.length > 0) {
+      if (signal && signal.aborted) return abortRest();
       let chunk = queue.shift();
       if (chunk.length > MAX_EVENTS_PER_REQUEST) {
         const mid = Math.ceil(chunk.length / 2);
@@ -222,14 +286,17 @@ async function pushRows(rows, loggedUserId) {
         const slimmed = shedOversize(chunk[0]);
         if (!slimmed || Buffer.byteLength(envelopeBody(evid, [slimmed])) > MAX_BODY_BYTES) {
           out.failures.push({ evid, rows: 1, detail: 'oversized_event' });
+          accounted += 1;
           continue;
         }
         out.truncated += 1;
         chunk = [slimmed];
       }
-      const failureDetail = await sendBatch(evid, chunk);
+      const failureDetail = await sendBatch(evid, chunk, signal);
+      if (failureDetail === 'aborted') return abortRest();
       if (failureDetail) out.failures.push({ evid, rows: chunk.length, detail: failureDetail });
       else out.sent += chunk.length;
+      accounted += chunk.length;
     }
   }
   return out;
@@ -241,6 +308,7 @@ module.exports = {
   EVID_RUN_EVENT,
   MAX_EVENTS_PER_REQUEST,
   MAX_BODY_BYTES,
+  PUSH_TIMEOUT_MS,
   isGuid,
   disabled,
   startedRunRow,