mobile-automator 0.25.0 → 0.26.0

package/src/guide/content/execute.agnostic.md

@@ -52,15 +52,16 @@ Record each observation with `mauto result add-step --observation <type>:<messag
 
 ### 1. Pre-flight
 
-1. Read the scenario JSON.
-2. Verify a device is available with `mauto devices`. Read the device's `platform` field — store it for the duration of execution.
-3. **App under test.**
+1. **Name the run first.** Choose the run identifier for this execution (format `run_YYYYMMDD_HHMMSS`) and export it as `MAUTO_RUN_ID` before running any other verb — `export MAUTO_RUN_ID=run_20260905_141500`. Every verb then records into a trace for that run, and `mauto result finalize --run-id <the same id>` measures the run's duration from it instead of taking your word for it. Use the *same* id in both places; a different one means no trace to measure.
+2. Read the scenario JSON.
+3. Verify a device is available with `mauto devices`. Read the device's `platform` field — store it for the duration of execution.
+4. **App under test.**
    - If the user pointed you at a prebuilt app artifact, install it with `mauto install <path>`.
    - Otherwise verify the app is already installed; if it is not, halt and ask the user to install it. This guide never builds.
    - If the install fails because a different build is already on the device, uninstall it with `mauto uninstall <appId>` (the app identifier from `mobile-automator/config.json` — `android_package` / `ios_bundle_id`), install again, and report that app data was wiped — a scenario whose preconditions assume existing app state may now fail for that reason.
    - State which path you took before continuing.
-4. **Validate schema version:** read the `$schema_version` field; it must be `"2.1"`. If absent or unrecognized, report an error and halt.
-5. Validate the scenario with `mauto validate <path>` against `mauto schema scenario`.
+5. **Validate schema version:** read the `$schema_version` field; it must be `"2.1"`. If absent or unrecognized, report an error and halt.
+6. Validate the scenario with `mauto validate <path>` against `mauto schema scenario`.
 
 **Precondition `device_actions`** (from the scenario's `preconditions`, run before step replay):
 
@@ -117,6 +118,46 @@ For each step in the scenario:
 
 When executing a `capture_value` action: locate the element with `mauto elements`, extract its text, and store it in the session variable map under the step's `capture_to` name (`variables[<capture_to>] = <extracted_text>`). Report: "Captured `capture_to` = '<value>'".
 
+### When a step fails, find out whether the app is still alive
+
+An action that fails, or an `elements` call that comes back empty, has two very
+different explanations: the UI changed, or the app died. They lead to opposite
+conclusions, and only one of them is worth reporting as a test failure.
+
+`mauto` checks for you. A failed device action
+comes back with a `crashes` array in `data`, and the `hint` names the process
+that died. Three states, and they are not the same:
+
+- `crashes` present and non-empty — the app crashed. Stop reasoning about the
+  UI. Record it and stop the run.
+- `crashes` present and empty — the app is alive. This is a real UI failure;
+  carry on diagnosing it.
+- `crashes` absent — `mauto` could not check. Nothing has been claimed either
+  way; reason as you would have without it.
+
+To ask directly, at any time:
+
+```bash
+mauto crash list                     # reports since this device session began
+mauto crash list --since <iso>       # a window you choose
+mauto crash get <id>                 # the head of one report
+mauto crash get <id> --out <path>    # the whole report to a file
+```
+
+Record what you found so the result file carries it:
+
+```bash
+mauto result add-crash --run-id <run> --crash-id <id> --step-id <step> \
+  --process <package> --excerpt "<first lines of the report>"
+```
+
+Two cautions. Crash-report retention differs between device platforms — on
+some, reports age out of a device log within minutes; on others they persist as
+files for weeks. That is why `crash list` scopes to the current session by
+default — a report from last week is not evidence about this step. And a report
+whose own timestamp is unreadable is counted in `unattributed` rather than
+included; if that count is non-zero, widen `--since` and look yourself.
+
 ### 4. Validate Assertions (27 types)
 
 For each assertion, pick the type recorded in the scenario and evaluate it. The 27 types split into two tiers by **who decides pass/fail**:
@@ -163,6 +204,8 @@ Obtain the result schema by running `mauto schema result`, then finalize the run
 - `observations[]`: typed observations (`regression`, `flakiness`, `state_context`) recorded via `--observation` on `add-step`.
 - `captured_variables`: values recorded via `--capture` on `add-step`.
 
+`--duration` is now a cross-check rather than the recorded value: when a run trace exists the duration is measured from it, your figure is kept as `measurements.reported_duration_seconds`, and a disagreement beyond the tolerance is recorded as a `state_context` observation. Report the duration you believe is right and let the two be compared; do not reverse-engineer a number to match.
+
 ### 6. Flakiness & Resolution Reporting
 
 When a semantic action's primary resolution fails and the fallback succeeds, add a `flakiness` observation:

package/src/guide/content/execute.aware.md

@@ -51,6 +51,7 @@ Record each observation with `mauto result add-step --observation <type>:<messag
 
 ### 1. Pre-flight
 
+- **Name the run first.** Choose the run identifier for this execution (format `run_YYYYMMDD_HHMMSS`) and export it as `MAUTO_RUN_ID` before running any other verb — `export MAUTO_RUN_ID=run_20260905_141500`. Every verb then records into a trace for that run, and `mauto result finalize --run-id <the same id>` measures the run's duration from it instead of taking your word for it. Use the *same* id in both places; a different one means no trace to measure.
 - Verify a device is available with `mauto devices`.
 - **App under test.** If the user pointed you at a prebuilt artifact, install it with `mauto install <path>` and do NOT build — reusing a ready artifact is the point.
 - If no artifact was named: check whether the app is already installed. If it is, say so and ask whether to rebuild before running the build command ({{build_command}}) — a previous run may have just built it. If it is not installed, build and install with the build command ({{build_command}}).
@@ -165,6 +166,46 @@ When executing a `capture_value` action:
 4. Also record it in the result file with `--capture <capture_to>=<extracted_text>` on that step's `mauto result add-step` call — the in-memory session variable map alone never reaches the result file; only the flag does.
 5. Report: "Captured `capture_to` = '<value>'".
 
+### When a step fails, find out whether the app is still alive
+
+An action that fails, or an `elements` call that comes back empty, has two very
+different explanations: the UI changed, or the app died. They lead to opposite
+conclusions, and only one of them is worth reporting as a test failure.
+
+`mauto` checks for you. A failed device action
+comes back with a `crashes` array in `data`, and the `hint` names the process
+that died. Three states, and they are not the same:
+
+- `crashes` present and non-empty — the app crashed. Stop reasoning about the
+  UI. Record it and stop the run.
+- `crashes` present and empty — the app is alive. This is a real UI failure;
+  carry on diagnosing it.
+- `crashes` absent — `mauto` could not check. Nothing has been claimed either
+  way; reason as you would have without it.
+
+To ask directly, at any time:
+
+```bash
+mauto crash list                     # reports since this device session began
+mauto crash list --since <iso>       # a window you choose
+mauto crash get <id>                 # the head of one report
+mauto crash get <id> --out <path>    # the whole report to a file
+```
+
+Record what you found so the result file carries it:
+
+```bash
+mauto result add-crash --run-id <run> --crash-id <id> --step-id <step> \
+  --process <package> --excerpt "<first lines of the report>"
+```
+
+Two cautions. Crash-report retention differs between platforms: on some the
+reports age out of a device log within minutes, on others they are files that
+persist for weeks. That is why `crash list` scopes to the current session by
+default — a report from last week is not evidence about this step. And a report
+whose own timestamp is unreadable is counted in `unattributed` rather than
+included; if that count is non-zero, widen `--since` and look yourself.
+
 ### 5. Validate Assertions (27 types)
 
 For each assertion in the scenario (evaluated after the referenced step), pick the type recorded in the scenario and evaluate it. The 27 types split into two tiers by **who decides pass/fail**:
@@ -219,7 +260,7 @@ For all Tier 2 assertions: take a screenshot, visually analyze it, and report pa
 
 ### 6. Generate the Result Report
 
-Obtain the result schema by running `mauto schema result`, then finalize the run with `mauto result finalize` (writing to `mobile-automator/results/<run_id>.json`), passing the run metadata you already know (`--device-model`, `--api-level`, `--app-version`, `--environment`) — the timestamp is filled in for you, and omitted fields are recorded as `unknown`. You may supply your own narrative with `--summary <text>`; omitting it keeps the generated default summary line. The result carries typed `observations` (`regression`, `flakiness`, `state_context`) gathered by the Observer traits above.
+Obtain the result schema by running `mauto schema result`, then finalize the run with `mauto result finalize` (writing to `mobile-automator/results/<run_id>.json`), passing the run metadata you already know (`--device-model`, `--api-level`, `--app-version`, `--environment`) — the timestamp is filled in for you, and omitted fields are recorded as `unknown`. You may supply your own narrative with `--summary <text>`; omitting it keeps the generated default summary line. The result carries typed `observations` (`regression`, `flakiness`, `state_context`) gathered by the Observer traits above. `--duration` is now a cross-check rather than the recorded value: when a run trace exists the duration is measured from it, your figure is kept as `measurements.reported_duration_seconds`, and a disagreement beyond the tolerance is recorded as a `state_context` observation. Report the duration you believe is right and let the two be compared; do not reverse-engineer a number to match.
 
 ### 7. Present the Summary
 

package/src/guide/content/execute.invariants.md

@@ -2,3 +2,4 @@
 - Drive the device **only** through `mauto` verbs; never assume resource-ids or OS-specific element IDs (use the semantic actions in platform-agnostic projects).
 - Every assertion is backed by a screenshot recorded with `mauto result add-step --screenshot`; record its verdict with `mauto result add-assertion` and any observations with `--observation <type>:<message>`.
 - If this workspace has memory, read it first with `mauto memory show`; save durable app facts and user corrections with `mauto memory add`.
+- Export `MAUTO_RUN_ID` before the first verb of a run, and pass the same identifier to every `mauto result` verb. Verb events are correlated by that value; without it the run has no trace and its recorded duration is your own estimate rather than a measurement.

package/src/observe/accepts.js

@@ -0,0 +1,108 @@
+'use strict';
+
+// The check that makes a `sends: true` classification TRUE.
+//
+// A `sends: true` field used to carry a `basis` word — computed, closed-set,
+// csprng, constant — as a pure self-declaration. Nothing tied the word to the
+// value: telemetryPayload() copied whatever was on the event, and the lint
+// guard only checked that the word was in a list. So a new field could write
+// `basis: 'computed'` and ship `com.acme.unreleased` without any test noticing.
+//
+// Here the basis is DERIVED instead. Each helper below returns a predicate
+// tagged with the kind of guarantee it enforces, and `sendable()` reads the
+// catalog entry's `basis` off that tag. There is no hand-written basis string
+// left to lie with, and telemetryPayload() (src/observe/event.js) applies the
+// predicate to every value before it can reach the wire.
+//
+// Predicates are TOTAL: they take any value — an object, NaN, a getter-free
+// hostile string — and answer true or false, never throw. Each is a positive
+// check ("is one of these", "matches exactly this shape") rather than a
+// rejection list, so an unforeseen value fails closed.
+
+// The closed set of mechanisms that can make a `sends: true` classification
+// true. Each is what one helper below enforces:
+//
+//   'computed'   — a number, boolean or timestamp this code derives, checked
+//                  for type and range. Never a string copied from a caller.
+//   'closed-set' — the value is one of a fixed vocabulary we define or a
+//                  runtime-level enum (os, errno). See src/observe/vocab.js.
+//   'csprng'     — a zero-arity CSPRNG token, checked for its exact shape.
+//   'constant'   — a fixed fact about the build/runtime (a version string),
+//                  checked for its shape, never for equality with the running
+//                  process: an event spooled before an upgrade is flushed after
+//                  it, and must not be dropped for being from the old version.
+const SEND_BASES = ['computed', 'closed-set', 'csprng', 'constant'];
+
+function tag(fn, basis) {
+  if (!SEND_BASES.includes(basis)) throw new Error(`unknown telemetry basis: ${basis}`);
+  fn.basis = basis;
+  return Object.freeze(fn);
+}
+
+// value is exactly one of `list`. The list is copied into a private Set, so a
+// consumer that mutates the array it passed cannot widen the check later.
+function oneOf(list) {
+  const set = new Set(list);
+  return tag((value) => typeof value === 'string' && set.has(value), 'closed-set');
+}
+
+// value is a string with exactly the shape `regex` describes. `basis` says why
+// that shape is a guarantee: 'csprng' for random tokens, 'constant' for version
+// strings. Anchor the regex — an unanchored one accepts a match anywhere in
+// caller text.
+function matches(regex, basis) {
+  if (basis !== 'csprng' && basis !== 'constant') {
+    throw new Error(`matches() basis must be 'csprng' or 'constant', got ${basis}`);
+  }
+  return tag((value) => typeof value === 'string' && regex.test(value), basis);
+}
+
+// value is an integer in [min, max]. The default max is MAX_SAFE_INTEGER, which
+// is what rejects 1e21 (an integer to Number.isInteger, and not one we minted).
+function integer({ min = -Number.MAX_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER } = {}, basis = 'computed') {
+  if (basis !== 'computed' && basis !== 'constant') {
+    throw new Error(`integer() basis must be 'computed' or 'constant', got ${basis}`);
+  }
+  return tag((value) => Number.isInteger(value) && value >= min && value <= max, basis);
+}
+
+function boolean() {
+  return tag((value) => typeof value === 'boolean', 'computed');
+}
+
+// What Date#toISOString mints, and only that: a string of this exact shape that
+// Date.parse also reads as a real instant (so month 13 fails).
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+function isoTimestamp() {
+  return tag(
+    (value) => typeof value === 'string' && ISO_TIMESTAMP.test(value) && Number.isFinite(Date.parse(value)),
+    'computed'
+  );
+}
+
+// The catalog-entry builder. `basis` is read OFF the check, never restated.
+function sendable(accepts, why) {
+  if (typeof accepts !== 'function' || !SEND_BASES.includes(accepts.basis)) {
+    throw new Error('sendable() needs a check built by an accepts helper');
+  }
+  return { sends: true, basis: accepts.basis, accepts, why };
+}
+
+// PURE: the names of `sends: true` entries in `catalog` whose classification is
+// not backed by an enforced check — no `accepts` function, a basis outside
+// SEND_BASES, or a basis that disagrees with the check it sits on. Empty for a
+// sound catalog. Takes the catalog as an argument so a test can hand it a
+// doctored CLONE and prove a lying entry is caught (tests/lint/telemetry-redaction.test.js)
+// without ever mutating the real one.
+function findUnenforced(catalog) {
+  return Object.entries(catalog)
+    .filter(([, def]) => def && def.sends === true)
+    .filter(([, def]) => {
+      if (typeof def.accepts !== 'function') return true;
+      if (!SEND_BASES.includes(def.basis)) return true;
+      return def.accepts.basis !== def.basis;
+    })
+    .map(([name]) => name);
+}
+
+module.exports = { SEND_BASES, oneOf, matches, integer, boolean, isoTimestamp, sendable, findUnenforced };

package/src/observe/event.js

@@ -0,0 +1,241 @@
+'use strict';
+
+// Single source of truth for every field a mauto observability event can
+// carry, and — critically — whether that field may ever cross a network.
+//
+// This mirrors src/device/action-catalog.js and src/result/capability-catalog.js:
+// one entry per item, consumed by a lint guard (tests/lint/telemetry-redaction.test.js)
+// so a field that gains a network path fails the build instead of silently
+// shipping a user's unreleased app id to a third party.
+//
+//   sends: true  — may appear in slice 5's telemetry payload. Only enumerated
+//                  values, counts, versions and durations qualify, and the
+//                  entry carries an `accepts(value)` check that ENFORCES that
+//                  at the wire (see below).
+//   sends: false — local logs only. telemetryPayload() cannot serialize it.
+//
+// The allowlist direction is deliberate: a field nobody has classified is
+// silently DROPPED from telemetry rather than silently sent, and so is a
+// classified field whose value fails its check.
+//
+// A `sends: true` entry is built with sendable(accepts(...), why). The helper
+// tags the check with the kind of guarantee it enforces and `basis` is read off
+// that tag — there is no hand-written basis to lie with. Validation happens at
+// the WIRE (telemetryPayload), not in makeEvent: local logs stay lossless, and
+// tests deliberately record arbitrary strings.
+
+const pkg = require('../../package.json');
+const {
+  SEND_BASES,
+  oneOf,
+  matches,
+  integer,
+  boolean,
+  isoTimestamp,
+  sendable,
+  findUnenforced,
+} = require('./accepts');
+const { OS_NAMES, EVENT_NAMES, VERB_NAMES, STOP_REASONS, ERROR_CODES } = require('./vocab');
+const { ERROR_KINDS } = require('../output/envelope');
+// Pure module with no requires, so this adds no cycle. It is THE closed set of
+// mobile-mcp primitive names and must not be restated here.
+const { MOBILE_MCP_TOOL_NAMES } = require('../device/mobile-mcp-tools');
+
+const EVENT_VERSION = 1;
+
+// The shape of a session_id: what session-handle.newSessionId() mints (8 CSPRNG
+// bytes as hex) and the only shape readSessionId() will return. session_id is
+// sends:true on the grounds that it is random and carries no user content; the
+// handle file it is read back from is just a file, so the shape is what keeps
+// that true for a stale or hand-edited one.
+const SESSION_ID_PATTERN = /^[0-9a-f]{16}$/;
+
+// Ascending severity. Index order is the comparison order.
+const LEVELS = ['debug', 'info', 'warn', 'error'];
+
+// Shapes of the `constant` and `csprng` string fields. Anchored: an unanchored
+// pattern would accept a match anywhere inside caller text.
+const SEMVER = /^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$/;
+const NODE_VERSION = /^v\d+\.\d+\.\d+$/;
+const MSG_ID = /^[0-9a-f]{32}$/;
+
+const EVENT_FIELDS = {
+  // --- ambient, stamped by makeEvent -------------------------------------
+  ts: sendable(isoTimestamp(), 'ISO timestamp; carries no user content'),
+  v: sendable(integer({ min: 1 }, 'constant'), 'event schema version'),
+  // Shape, not equality with pkg.version: a spooled event may be flushed after an
+  // upgrade, and must not be dropped for naming the version that wrote it.
+  mauto_version: sendable(matches(SEMVER, 'constant'), 'our own package version'),
+  node: sendable(matches(NODE_VERSION, 'constant'), 'node runtime version'),
+  os: sendable(oneOf(OS_NAMES), 'process.platform; one of a fixed set'),
+
+  // --- classification ----------------------------------------------------
+  level: sendable(oneOf(LEVELS), 'enumerated: debug|info|warn|error'),
+  src: sendable(oneOf(['cli', 'daemon']), 'enumerated: cli|daemon'),
+  event: sendable(oneOf(EVENT_NAMES), 'enumerated event name'),
+
+  // --- outcome -----------------------------------------------------------
+  // The justification is only true if the value is enforced to be one, and it
+  // is enforced twice: cli.js takes it from commander's resolved command, never
+  // from argv (so an unparseable invocation records no verb rather than a
+  // user-supplied token), and the accepts check below rejects anything outside
+  // VERB_NAMES at the wire.
+  verb: sendable(oneOf(VERB_NAMES), 'the mauto verb name; a fixed vocabulary we ship'),
+  ok: sendable(boolean(), 'boolean outcome'),
+  // ERROR_KINDS is derived from the envelope's own taxonomy, not copied.
+  error_kind: sendable(oneOf(ERROR_KINDS), 'enumerated envelope taxonomy (device|timeout|...)'),
+  exit_code: sendable(integer({ min: 0, max: 255 }), 'process exit code; 0..255'),
+  dur_ms: sendable(integer({ min: 0 }), 'duration; carries no user content'),
+
+  // --- daemon ------------------------------------------------------------
+  // Random per-daemon-lifetime id, generated by session-handle.newSessionId()
+  // from crypto.randomBytes and derived from NOTHING — not the project root,
+  // not the device, not the pid. Deliberately NOT persisted across restarts: a
+  // stable id would be a machine fingerprint, whereas this one changes exactly
+  // when the daemon does, which is the fact it exists to report. Enforced on
+  // the mint side by tests/unit/device/session-handle.test.js and on the read
+  // side by readSessionId() checking SESSION_ID_PATTERN — and at the wire by
+  // the same pattern, so a stale or hand-edited handle file cannot ship text.
+  session_id: sendable(matches(SESSION_ID_PATTERN, 'csprng'), 'random id scoped to one daemon lifetime; no user-derived content'),
+  // As with `verb`, the justification holds only because the value is enforced
+  // to be one: src/device/device-call.js records this field ONLY when
+  // isKnownTool() accepts it (src/device/mobile-mcp-tools.js), because it
+  // arrives inside a socket frame and the socket is reachable by anything on
+  // the machine. It is checked there — in the one wrapper every daemon call
+  // goes through — rather than at the daemon's frame router, so a second call
+  // site cannot appear that forgets to check. The accepts check below applies
+  // the same set again at the wire, so a later recording site that forgets
+  // still cannot ship an unknown name.
+  tool: sendable(oneOf(MOBILE_MCP_TOOL_NAMES), 'mobile-mcp primitive name, checked against the pinned tool set'),
+  // Monotonic integer minted by startDaemon, one per device call, scoped to one
+  // daemon lifetime. It is what makes call.start and call.end PAIRABLE: every
+  // call in a lifetime shares session_id and the daemon multiplexes, so a
+  // start-without-end — the only trace a call that never returned can leave —
+  // is undecidable without a per-call identity.
+  //
+  // The daemon already has a correlation id in the socket frame's `req.id`, and
+  // deliberately does not use it: that value is client-chosen and the socket is
+  // reachable by any process on the machine, so recording it would put caller
+  // text on a sends:true field — the same concern that produced
+  // src/device/mobile-mcp-tools.js. A daemon-minted counter needs no redaction
+  // argument at all, on exactly the grounds dur_ms is cleared.
+  call_id: sendable(integer({ min: 1 }), 'daemon-minted counter scoped to one session; never the client-supplied frame id'),
+  stop_reason: sendable(oneOf(STOP_REASONS), 'enumerated: idle|signal|shutdown|crash|explicit'),
+  // Errno NAMES only: the numeric codes an MCP server reports, and Node's
+  // ERR_* codes, fail the check and are dropped rather than sent.
+  error_code: sendable(oneOf(ERROR_CODES), 'Node/libuv errno string (EADDRINUSE|EACCES|…) plus our own ELOCKED'),
+
+  // --- crash (slice 4) ---------------------------------------------------
+  // The ONLY new field slice 4 mints. As with `verb`, `tool` and `session_id`,
+  // the sends:true justification is only true if the value is enforced to be
+  // one: every record site coerces with Number.isFinite before recording, so a
+  // malformed engine payload records no field rather than an arbitrary value,
+  // and the accepts check below re-verifies a non-negative integer at the wire.
+  //
+  // Deliberately no crash_process / crash_excerpt / crash_path fields: a
+  // crashed process name IS an app id, a stack excerpt IS free text and a
+  // report location IS a filesystem path. Those three entries already carry the
+  // right classification, and a near-copy would be a second decision to keep in
+  // sync with the first.
+  crash_count: sendable(integer({ min: 0 }), 'integer count of crash reports observed; carries no user content'),
+
+  // --- telemetry transport (slice 5) --------------------------------------
+  // Zero-arity CSPRNG token, generated per EVENT at spool time by
+  // src/observe/spool.js newMessageId() and derived from NOTHING — not the
+  // project root, not the pid, not the clock. It is sent as the PostHog
+  // event's `uuid` so a re-sent batch (delivery is at-least-once; see
+  // src/observe/flush.js) deduplicates at ingestion. Per-event and never
+  // reused, so it cannot correlate two events, let alone two machines — the
+  // opposite of the stable install id this design deliberately does not have.
+  // It is sends:true on EXACTLY the grounds session_id is.
+  msg_id: sendable(matches(MSG_ID, 'csprng'), 'zero-arity CSPRNG per-event delivery id; carries no user content'),
+  // Integer this code computes (batch size), never a caller-supplied value.
+  count: sendable(integer({ min: 0 }), 'integer count (batch size); carries no user content'),
+  // Integer our own telemetry endpoint returns; never a caller-supplied value.
+  http_status: sendable(integer({ min: 100, max: 599 }), 'integer HTTP status from our own telemetry endpoint'),
+
+  // --- local only: every one of these can carry user content -------------
+  run_id: { sends: false, why: 'agent-chosen; routinely names an unreleased feature' },
+  scenario_id: { sends: false, why: "names the user's feature under test" },
+  app_id: { sends: false, why: "an unreleased product's package name" },
+  device_id: { sends: false, why: 'hardware identifier / serial' },
+  device_model: { sends: false, why: 'narrows a device to an individual tester' },
+  project_name: { sends: false, why: "the user's project name" },
+  pid: { sends: false, why: 'process id; no aggregate value, and a weak host correlator with ts' },
+  message: { sends: false, why: 'free text; may embed labels, paths, typed input' },
+  hint: { sends: false, why: 'free text; may embed filesystem paths' },
+  path: { sends: false, why: 'filesystem path; leaks usernames and project layout' },
+};
+
+// Names that must ALWAYS be sends:false. Kept separate from EVENT_FIELDS so
+// the guard tests a stated intention against the catalog rather than reading
+// the catalog and agreeing with itself.
+const NEVER_SENDS = [
+  'run_id',
+  'scenario_id',
+  'app_id',
+  'device_id',
+  'device_model',
+  'project_name',
+  'pid',
+  'message',
+  'hint',
+  'path',
+];
+
+// The ambient fields are classified sends:true on the grounds that makeEvent
+// computes them itself. That is only true if a caller cannot override them, so
+// the caller loop in makeEvent skips them.
+const AMBIENT_FIELDS = new Set(['ts', 'v', 'mauto_version', 'node', 'os']);
+
+// Build an event from caller fields. Unknown keys are dropped (not an error:
+// a caller that invents a field must not be able to smuggle it into a log),
+// and undefined values are omitted so events stay sparse rather than
+// null-padded. Values are NOT validated here: local logs stay lossless, and
+// the wire check lives in telemetryPayload.
+function makeEvent(fields = {}) {
+  const out = {
+    ts: new Date().toISOString(),
+    v: EVENT_VERSION,
+    mauto_version: pkg.version,
+    node: process.version,
+    os: process.platform,
+  };
+  for (const [k, val] of Object.entries(fields)) {
+    if (AMBIENT_FIELDS.has(k)) continue;
+    if (!Object.prototype.hasOwnProperty.call(EVENT_FIELDS, k)) continue;
+    if (val === undefined) continue;
+    out[k] = val;
+  }
+  return out;
+}
+
+// The ONLY function permitted to build a network payload. Allowlist by
+// construction: it iterates the catalog, never the event. A sends:true field
+// is copied only if its `accepts` check passes; a failing value is OMITTED,
+// never coerced and never sent, so a field's classification is enforced here
+// rather than merely declared.
+function telemetryPayload(event = {}) {
+  const out = {};
+  for (const [name, def] of Object.entries(EVENT_FIELDS)) {
+    if (!def.sends) continue;
+    if (!Object.prototype.hasOwnProperty.call(event, name)) continue;
+    const value = event[name];
+    if (value === undefined) continue;
+    if (typeof def.accepts !== 'function' || !def.accepts(value)) continue;
+    out[name] = value;
+  }
+  return out;
+}
+
+module.exports = {
+  EVENT_VERSION,
+  SESSION_ID_PATTERN,
+  LEVELS,
+  EVENT_FIELDS,
+  NEVER_SENDS,
+  SEND_BASES,
+  makeEvent,
+  telemetryPayload,
+  findUnenforced,
+};