@tokenoftrust/storefront-runner 1.3.4-rc.4 → 1.4.1

package/apps/storefront/src/lib/activity/changeActorAttribution.ts

@@ -0,0 +1,85 @@
+/**
+ * Owner-facing "who did this" attribution for a candidate change or aggregate —
+ * DELIBERATELY separate from the anonymized activity spine. `ActivityActor.id`
+ * is a salted, non-reversible hash by design (see `recordActivity.ts`'s header:
+ * a raw PII id in the core zone would defeat the D0 contract), so it can never
+ * answer "who submitted/accepted/rejected/shipped this" for an owner reviewing
+ * `/admin#publish`. This persists the real email (never joined into the general
+ * `queryActivity()` surface, never cross-tenant) alongside the existing hashed
+ * event, so the two concerns stay separate: analytics stays anonymized, and
+ * this stays a narrow, owner-only-readable accountability record.
+ *
+ * `sub` (the tot20-issued, stable user id) would be a better key than email —
+ * email is a mutable account attribute, not the identity itself — but `sub`
+ * is dropped before `SessionRecord` today (see `auth/session.ts`). Threading
+ * it through is a real follow-up, not done here; email is what every call site
+ * already has.
+ */
+import { displayNameFromEmail } from "./recordActivity";
+
+export type ChangeActorAction = "submit" | "reject" | "accept" | "ship" | "build";
+
+export interface ChangeActorRecord {
+  email: string;
+  /** Best-effort display name — no real name is captured anywhere today, so
+   *  this is always {@link displayNameFromEmail}'s local-part guess. Swap the
+   *  source here (not the callers) if a real name ever becomes available. */
+  name: string;
+  at: string;
+}
+
+export interface ChangeActorKv {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+}
+
+function attributionKey(tenantId: string, subjectId: string, action: ChangeActorAction): string {
+  return `cust:change-actor:${tenantId}:${subjectId}:${action}`;
+}
+
+/**
+ * Persist who took `action` on `subjectId` (a `changeId` for reject/accept/build,
+ * or the aggregate id for ship). Best-effort — never blocks or fails the
+ * mutation it describes; a write fault is swallowed, mirroring `recordActivity`.
+ */
+export async function recordChangeActor(
+  kv: ChangeActorKv,
+  tenantId: string,
+  subjectId: string,
+  action: ChangeActorAction,
+  email: string,
+): Promise<void> {
+  try {
+    const record: ChangeActorRecord = {
+      email,
+      name: displayNameFromEmail(email),
+      at: new Date().toISOString(),
+    };
+    await kv.put(attributionKey(tenantId, subjectId, action), JSON.stringify(record));
+  } catch {
+    /* best-effort — the mutation it describes already succeeded */
+  }
+}
+
+/** Read every recorded action's attribution for one subject. Best-effort per
+ *  action: a missing/corrupt record is simply absent from the result, never
+ *  a thrown error. */
+export async function readChangeActors(
+  kv: ChangeActorKv,
+  tenantId: string,
+  subjectId: string,
+): Promise<Partial<Record<ChangeActorAction, ChangeActorRecord>>> {
+  const actions: ChangeActorAction[] = ["submit", "reject", "accept", "ship", "build"];
+  const out: Partial<Record<ChangeActorAction, ChangeActorRecord>> = {};
+  await Promise.all(
+    actions.map(async (action) => {
+      try {
+        const raw = await kv.get(attributionKey(tenantId, subjectId, action));
+        if (raw) out[action] = JSON.parse(raw) as ChangeActorRecord;
+      } catch {
+        /* a corrupt/missing record just isn't shown */
+      }
+    }),
+  );
+  return out;
+}

package/apps/storefront/src/lib/activity/deployVersion.ts

@@ -0,0 +1,127 @@
+/**
+ * deploy.version_observed — the deploy-provenance / deploy-skew signal (card D2).
+ *
+ * "A deployed worker version/commit was observed." This is the DERIVED signal D5's
+ * query surface reads to answer *deploy skew* — is the build serving traffic the
+ * pushed umbrella tip, or is a stale isolate still live? D2's job is just to make
+ * `worker_commit` reliably present on server events and to EMIT this observation at
+ * least once per running build; the actual "== umbrella tip?" comparison and the
+ * timeline query are D5's (this module intentionally does no comparison — it has no
+ * notion of what the tip is, only what THIS build is).
+ *
+ * WHAT IT PRODUCES. A catalog `deploy.version_observed` event (ACTION_CATALOG:
+ * actors [system|dev], source server, sinks logs+analytics+timeline). The FULL
+ * 40-char commit rides `scope.workerCommit` — the CORE zone, which createActivityEvent
+ * never redacts — because that is where the authoritative, unscrubbed sha belongs.
+ *
+ * DELIBERATELY the full sha does NOT go in `payload`. The action's argsAllow names
+ * `commit`, but a 40-char hex sha trips D0's `high_entropy` VALUE canary (redaction.ts:
+ * ≥28 chars of base64url) — it would be scrubbed to «redacted» AND set
+ * `report.canaryTripped`, which D6/D7 alert on, firing a FALSE PII alarm on every cold
+ * start. So payload carries only the SHORT `version` (7 chars, safe) plus `env` +
+ * `observedFrom`; a reader wanting the full sha reads scope.workerCommit (a git sha is
+ * public, so the core zone is its correct, alert-free home). See the D2 report note for
+ * D5/D8: treat scope.workerCommit as the authoritative provenance, payload.version as a
+ * human-eyeball convenience.
+ *
+ * WHERE IT'S EMITTED. observeDeployVersion() fires ONCE PER WORKER ISOLATE (guarded
+ * by a module-level flag) from the middleware's front door — a cold start emits one
+ * observation, not one per request, so the stream is low-volume and honest. Until
+ * D1's recordActivity()/D4's ingest+store land, the emission goes to the universal
+ * `logs` sink (structured `[activity]` JSON to Workers Logs — the same pipeline the
+ * interim recordActivity.ts uses, already provisioned via `[observability]`). When
+ * D1's recordActivity() exists, swap `emitToLogs` for it (it will fan out to the
+ * analytics+timeline sinks the action declares); the EVENT this module builds is
+ * unchanged.
+ */
+import { createActivityEvent } from "@tot/public-runtime";
+import type { ActivityEvent, RedactionReport } from "@tot/public-runtime";
+import { workerCommit, workerCommitShort, UNKNOWN_COMMIT } from "./workerCommit.js";
+import { isActivityDisabled } from "./killSwitch.js";
+
+export interface DeployVersionObservedInput {
+  /** Deploy env/target name (e.g. "preview", "production"), when known. Optional. */
+  env?: string;
+  /** What surfaced the observation (e.g. "startup", "health"). Defaults "startup". */
+  observedFrom?: string;
+  /** Opaque actor id. Defaults "system" (the platform observed its own build). */
+  actorId?: string;
+  /** Override the build commit — tests only. Real callers omit (reads __GIT_SHA__). */
+  commit?: string;
+}
+
+/**
+ * Build (do not emit) the `deploy.version_observed` ActivityEvent for the running
+ * build. Pure + side-effect-free — the piece D5 ultimately consumes and the piece
+ * tests assert against. Returns the safe-constructed event plus its redaction report.
+ */
+export function buildDeployVersionObservedEvent(
+  input: DeployVersionObservedInput = {},
+): { event: ActivityEvent; report: RedactionReport } {
+  const commit = workerCommit(input.commit);
+  const version = workerCommitShort(input.commit);
+  return createActivityEvent({
+    action: "deploy.version_observed",
+    actor: { kind: "system", id: input.actorId ?? "system" },
+    source: "server",
+    outcome: { status: "succeeded" },
+    // worker_commit (full sha) in the CORE zone — never redacted; the authoritative
+    // provenance every server event carries and D5 derives skew from.
+    scope: commit !== UNKNOWN_COMMIT ? { workerCommit: commit } : {},
+    // Payload carries the SHORT version (safe from the high_entropy canary that would
+    // scrub a full sha) + env + observedFrom. Unknown builds omit `version` rather than
+    // store the sentinel, but still emit the observation.
+    payload: {
+      args: {
+        ...(commit !== UNKNOWN_COMMIT ? { version } : {}),
+        ...(input.env ? { env: input.env } : {}),
+        observedFrom: input.observedFrom ?? "startup",
+      },
+    },
+  });
+}
+
+/**
+ * Serialize an ActivityEvent to the universal `logs` sink (Workers Logs). Interim
+ * transport until D1's recordActivity() fans out to all of the action's sinks;
+ * mirrors the `[activity]` tag the existing recordActivity.ts slice already emits so
+ * one grep finds both. Best-effort, never throws.
+ */
+function emitToLogs(event: ActivityEvent): void {
+  try {
+    console.log(`[activity] ${JSON.stringify(event)}`);
+  } catch {
+    // best-effort only — telemetry must never break a request
+  }
+}
+
+/** Per-isolate guard: emit the observation once per cold start, not per request. */
+let observedThisIsolate = false;
+
+/**
+ * Emit `deploy.version_observed` ONCE for this worker isolate. Idempotent within an
+ * isolate (subsequent calls are no-ops), best-effort, never throws — safe to call on
+ * every request from the middleware front door. Returns the event it emitted (or
+ * `undefined` if it already fired this isolate) so callers/tests can inspect it.
+ */
+export function observeDeployVersion(
+  input: DeployVersionObservedInput = {},
+): ActivityEvent | undefined {
+  if (observedThisIsolate) return undefined;
+  // Kill switch (D8): telemetry off ⇒ skip the observation entirely (fail-open). Do
+  // NOT set the per-isolate guard, so re-enabling emits the observation on the next call.
+  if (isActivityDisabled()) return undefined;
+  observedThisIsolate = true;
+  try {
+    const { event } = buildDeployVersionObservedEvent(input);
+    emitToLogs(event);
+    return event;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Test-only: reset the per-isolate guard so a test can re-exercise the first-fire path. */
+export function __resetDeployVersionObservedForTest(): void {
+  observedThisIsolate = false;
+}

package/apps/storefront/src/lib/activity/ingest.ts

@@ -0,0 +1,188 @@
+/**
+ * Ingest validation + server-side redaction for `POST /api/activity` (card D4).
+ *
+ * PURE (no I/O) so it is unit-testable and the route stays a thin auth/parse/
+ * respond shell. Takes the raw JSON events an emitter posted (CLI cohort D3, UI
+ * cohort D6 — both send JSON matching the `ActivityEvent` shape) plus the
+ * AUTHENTICATED tenant id, and returns the accepted events (already rebuilt
+ * through `createActivityEvent`, so re-redacted server-side) and the rejections.
+ *
+ * DEFENSE IN DEPTH (D8's future attack surface). Even though every emitter is
+ * expected to have run the redaction contract itself, ingest NEVER trusts that:
+ * it rebuilds each event through `createActivityEvent()`, which re-applies the
+ * default-deny allowlist + canary scan. A malicious/careless client that posts a
+ * secret in an un-allowlisted (or even allowlisted) payload field has it dropped/
+ * redacted here regardless of what it claimed to send.
+ *
+ * TENANT ISOLATION. `scope.tenantId` on the stored event is ALWAYS the
+ * authenticated tenant (from the HMAC-bound header), never the client-supplied
+ * body value — a client cannot write into another tenant's scope.
+ */
+import {
+  createActivityEvent,
+  isActionKey,
+  isActorAllowed,
+  isIsoTimestamp,
+  getActionSpec,
+  scanCoreIdentifier,
+  type ActivityEvent,
+  type ActorKind,
+  type ActivitySource,
+  type ActivityStatus,
+  type ActivityPayload,
+  type RedactionFieldHit,
+} from "@tot/public-runtime";
+
+const ACTOR_KINDS = new Set<ActorKind>(["dev", "merchant", "admin", "agent", "system"]);
+const SOURCES = new Set<ActivitySource>(["cli", "server", "ui"]);
+const STATUSES = new Set<ActivityStatus>(["invoked", "succeeded", "failed", "refused"]);
+
+export interface IngestRejection {
+  /** Index of the offending event in the posted batch. */
+  index: number;
+  /** Coarse machine reason — mirrors the `system.ingest.rejected` catalog args. */
+  reason:
+    | "not_object"
+    | "unknown_action"
+    | "actor_invalid"
+    | "actor_not_allowed"
+    | "source_invalid"
+    | "source_mismatch"
+    | "status_invalid"
+    | "bad_timestamp"
+    /** A client-supplied CORE-zone id (actor.id/ref, scope.changeId/traceId) carried a
+     *  raw PII/secret SHAPE. The core zone is unredacted, so this is refused outright
+     *  (never stored) rather than scrubbed — see `scanCoreIdentifier`. */
+    | "core_pii";
+  /** The action string the client attempted (for self-telemetry), when present. */
+  attemptedAction?: string;
+}
+
+export interface AcceptedActivity {
+  event: ActivityEvent;
+  /** True when a value-canary fired during server-side redaction — the signal
+   *  the route emits self-telemetry for and D6/D7 alert on. */
+  canaryTripped: boolean;
+  /** The redaction hits (fact-of, never the value) for D8 audit / logging. */
+  redactionHits: RedactionFieldHit[];
+}
+
+export interface IngestOutcome {
+  accepted: AcceptedActivity[];
+  rejected: IngestRejection[];
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * Validate + redact one posted event under the authenticated tenant. Returns the
+ * accepted (rebuilt) event or a rejection. The rebuild forces the tenant scope
+ * and re-runs redaction; it preserves the client's `id` (idempotency key) and
+ * `at` (emit clock) when they are well-formed.
+ */
+export function ingestOne(index: number, raw: unknown, tenantId: string): AcceptedActivity | IngestRejection {
+  if (!raw || typeof raw !== "object") return { index, reason: "not_object" };
+  const e = raw as Record<string, unknown>;
+
+  const action = e.action;
+  if (typeof action !== "string" || !isActionKey(action)) {
+    return { index, reason: "unknown_action", attemptedAction: typeof action === "string" ? action : undefined };
+  }
+  const spec = getActionSpec(action)!;
+
+  const rawActor = e.actor;
+  if (!rawActor || typeof rawActor !== "object") return { index, reason: "actor_invalid", attemptedAction: action };
+  const actorKind = (rawActor as Record<string, unknown>).kind;
+  const actorId = (rawActor as Record<string, unknown>).id;
+  const actorRef = (rawActor as Record<string, unknown>).ref;
+  if (typeof actorKind !== "string" || !ACTOR_KINDS.has(actorKind as ActorKind) || typeof actorId !== "string" || !actorId) {
+    return { index, reason: "actor_invalid", attemptedAction: action };
+  }
+  // Spoof guard: a `dev`-cohort caller cannot claim an `admin` lifecycle action.
+  if (!isActorAllowed(action, actorKind as ActorKind)) {
+    return { index, reason: "actor_not_allowed", attemptedAction: action };
+  }
+
+  const source = e.source;
+  if (typeof source !== "string" || !SOURCES.has(source as ActivitySource)) {
+    return { index, reason: "source_invalid", attemptedAction: action };
+  }
+  // The catalog declares exactly one legitimate source per action (1:1 grounding).
+  if (source !== spec.source) return { index, reason: "source_mismatch", attemptedAction: action };
+
+  const rawOutcome = e.outcome;
+  const status = rawOutcome && typeof rawOutcome === "object" ? (rawOutcome as Record<string, unknown>).status : undefined;
+  if (typeof status !== "string" || !STATUSES.has(status as ActivityStatus)) {
+    return { index, reason: "status_invalid", attemptedAction: action };
+  }
+  const errorClass = asString((rawOutcome as Record<string, unknown>).errorClass);
+  const durationRaw = (rawOutcome as Record<string, unknown>).durationMs;
+  const durationMs = typeof durationRaw === "number" && Number.isFinite(durationRaw) ? durationRaw : undefined;
+
+  // `at`: keep the emit clock when well-formed; a PRESENT-but-malformed `at` is a
+  // reject (a broken clock corrupts the D5 timeline ordering), a MISSING one is
+  // stamped server-side by createActivityEvent.
+  const at = e.at;
+  if (at !== undefined && !isIsoTimestamp(at)) return { index, reason: "bad_timestamp", attemptedAction: action };
+
+  const rawScope = (e.scope && typeof e.scope === "object" ? e.scope : {}) as Record<string, unknown>;
+
+  // CORE-ZONE PII GUARD (D8 hardening). actor.id / actor.ref and the client-supplied
+  // scope ids land UNREDACTED in the core zone, whose contract is "opaque, never raw
+  // PII/secret". The payload contract is enforced by re-redaction below, but the core
+  // ids were NOT checked — a buggy/malicious (though authenticated) emitter could
+  // smuggle a raw email/token into actor.id and have it stored in D1/Analytics/logs
+  // verbatim. Refuse any core id with a raw PII/secret SHAPE (opaque hashes/UUIDs pass;
+  // see `scanCoreIdentifier`). Rejected → self-telemetried as `system.ingest.rejected`.
+  const changeId = asString(rawScope.changeId);
+  const traceId = asString(rawScope.traceId);
+  if (
+    scanCoreIdentifier(actorId) ||
+    (typeof actorRef === "string" && actorRef && scanCoreIdentifier(actorRef)) ||
+    (changeId && scanCoreIdentifier(changeId)) ||
+    (traceId && scanCoreIdentifier(traceId))
+  ) {
+    return { index, reason: "core_pii", attemptedAction: action };
+  }
+
+  const built = createActivityEvent({
+    action,
+    actor: {
+      kind: actorKind as ActorKind,
+      id: actorId,
+      ...(typeof actorRef === "string" && actorRef ? { ref: actorRef } : {}),
+    },
+    source: source as ActivitySource,
+    outcome: {
+      status: status as ActivityStatus,
+      ...(errorClass ? { errorClass } : {}),
+      ...(durationMs !== undefined ? { durationMs } : {}),
+    },
+    scope: {
+      // AUTHENTICATED tenant only — the client's scope.tenantId is DISCARDED.
+      tenantId,
+      ...(changeId ? { changeId } : {}),
+      ...(traceId ? { traceId } : {}),
+    },
+    ...(typeof at === "string" ? { at } : {}),
+    ...(asString(e.id) ? { id: e.id as string } : {}),
+    // RAW payload — createActivityEvent re-redacts it (defense in depth).
+    ...(e.payload && typeof e.payload === "object" ? { payload: e.payload as ActivityPayload } : {}),
+  });
+
+  return { event: built.event, canaryTripped: built.report.canaryTripped, redactionHits: built.report.hits };
+}
+
+/** Validate + redact a whole posted batch under the authenticated tenant. */
+export function ingestEvents(events: unknown[], tenantId: string): IngestOutcome {
+  const accepted: AcceptedActivity[] = [];
+  const rejected: IngestRejection[] = [];
+  events.forEach((raw, i) => {
+    const r = ingestOne(i, raw, tenantId);
+    if ("event" in r) accepted.push(r);
+    else rejected.push(r);
+  });
+  return { accepted, rejected };
+}

package/apps/storefront/src/lib/activity/ingestAuth.ts

@@ -0,0 +1,105 @@
+/**
+ * Service-auth for `POST /api/activity` (card D4) — HMAC-SHA256 over the raw
+ * body, with the authenticated TENANT bound into the signed material.
+ *
+ * WHY HMAC (not the bare `x-mcp-service-secret` shared-secret seam the
+ * webhook receivers use). Those receivers authenticate ONE trusted forwarder
+ * (tot-mcp) and read the tenant from a body the forwarder itself constructed —
+ * fine there. Activity ingest is different in two ways that make a plain shared
+ * secret insufficient:
+ *   1. It is fed by MANY emitters (the CLI dev cohort, the UI cohort) whose
+ *      payloads must not be tamperable in flight — the redaction canaries key
+ *      off byte-exact values, so body INTEGRITY is load-bearing.
+ *   2. Every row is TENANT-SCOPED and the scope must come from the authenticated
+ *      identity, not a client-set field. So the tenant is part of the SIGNED
+ *      material (`<tenant>\n<body>`): a caller cannot assert a tenant it was not
+ *      issued a signature for without holding the ingest secret, and cannot swap
+ *      the tenant without invalidating the signature. The route then writes
+ *      `scope.tenantId` from THIS verified header and discards any body value.
+ *
+ * The signing key is the `ACTIVITY_INGEST_SECRET` Worker secret, shared with the
+ * emitters' gateway (the CLI/UI post through a signer that holds it — the
+ * per-emitter key-distribution/rotation story is a downstream concern, noted as
+ * a TODO). Everything here is WebCrypto (`crypto.subtle`) so the edge bundle
+ * never imports `node:crypto`, matching the node-free posture of the contract.
+ */
+
+/** Header carrying the authenticated tenant assertion (bound into the HMAC). */
+export const TENANT_HEADER = "x-tot-activity-tenant";
+/** Header carrying the hex HMAC-SHA256 signature over `<tenant>\n<rawBody>`. */
+export const SIGNATURE_HEADER = "x-tot-activity-signature";
+
+export type IngestAuthResult =
+  | { ok: true; tenantId: string }
+  | { ok: false; status: 401 | 503; reason: string };
+
+/** Length-independent constant-time string compare — mirrors the shared-secret
+ *  seam in `api/changes/candidate-reconcile.ts`; avoids leaking the signature by
+ *  timing. */
+export function timingSafeEqual(a: string, b: string): boolean {
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) {
+    diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  }
+  return diff === 0;
+}
+
+const encoder = new TextEncoder();
+
+function toHex(buf: ArrayBuffer): string {
+  const b = new Uint8Array(buf);
+  let out = "";
+  for (let i = 0; i < b.length; i++) out += (b[i] as number).toString(16).padStart(2, "0");
+  return out;
+}
+
+/**
+ * Hex HMAC-SHA256 of `message` under `secret`. Exported so the tests (and any
+ * server-side signer/gateway) sign with the exact same construction the verifier
+ * checks — a single source of truth for the wire format.
+ */
+export async function hmacSha256Hex(secret: string, message: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  return toHex(sig);
+}
+
+/** The exact bytes signed: the authenticated tenant, then the raw request body,
+ *  separated by a newline the tenant can never contain (it is validated as a
+ *  single-line id upstream). Binding both means neither can be swapped
+ *  independently of the signature. */
+export function signingMaterial(tenantId: string, rawBody: string): string {
+  return `${tenantId}\n${rawBody}`;
+}
+
+/**
+ * Verify an inbound ingest request. `secret` is the resolved
+ * `ACTIVITY_INGEST_SECRET` (the route returns 503 BEFORE calling this when it is
+ * unset — an unconfigured seam is not an auth failure). Returns the authenticated
+ * `tenantId` on success; a 401 with a coarse reason otherwise (never echoes the
+ * expected signature or the secret).
+ */
+export async function verifyIngestAuth(
+  headers: Headers,
+  rawBody: string,
+  secret: string,
+): Promise<IngestAuthResult> {
+  const tenantId = (headers.get(TENANT_HEADER) ?? "").trim();
+  const presented = (headers.get(SIGNATURE_HEADER) ?? "").trim();
+  if (!tenantId) return { ok: false, status: 401, reason: "missing tenant" };
+  // A newline in the tenant id would let a caller forge the material framing.
+  if (/[\r\n]/.test(tenantId)) return { ok: false, status: 401, reason: "invalid tenant" };
+  if (!presented) return { ok: false, status: 401, reason: "missing signature" };
+  const expected = await hmacSha256Hex(secret, signingMaterial(tenantId, rawBody));
+  if (!timingSafeEqual(presented.toLowerCase(), expected)) {
+    return { ok: false, status: 401, reason: "bad signature" };
+  }
+  return { ok: true, tenantId };
+}

package/apps/storefront/src/lib/activity/killSwitch.ts

@@ -0,0 +1,80 @@
+/**
+ * The single operational KILL SWITCH for the whole activity-telemetry pipeline (D8).
+ *
+ * ONE flag — the `ACTIVITY_TELEMETRY_DISABLED` env var / Worker secret — switches
+ * EVERY server-side emit path to a no-op in one place:
+ *   • `recordActivity()` (D1 server emitter) — and therefore `recordUiActivity()`
+ *     (D6 UI cohort), which is a thin wrapper over it;
+ *   • `observeDeployVersion()` (D2 deploy-provenance observer);
+ *   • `POST /api/activity` (D4 ingest) — accepts-and-drops so emitters never error.
+ * The out-of-process CLI (`emitActivity`, D3) honours the SAME flag name in its own
+ * JS mirror. Wiring it at these SHARED chokepoints means no call site checks it.
+ *
+ * FAIL-OPEN — this gates ONLY the observability layer. The underlying operation
+ * (reconcile, preview-serve, ship, invite, a CLI command) never depends on telemetry
+ * and is never blocked by it; flipping the switch turns emits into no-ops while
+ * everything else runs unchanged. An unset/unknown flag ⇒ telemetry ENABLED (the
+ * normal state). Reading the flag can never throw.
+ *
+ * SYNC + PRIMED — `recordActivity()` is a synchronous, fire-and-forget best-effort
+ * call, so the switch must be checkable WITHOUT awaiting. `isActivityDisabled()`
+ * consults (a) a value PRIMED once per isolate from the async Worker env
+ * (`primeActivityKillSwitch()`, called at the middleware front door) and (b) the
+ * synchronously-available build/process env — so a build-time var takes effect in
+ * dev/tests immediately, and a Worker secret takes effect from the first primed
+ * request of each isolate.
+ */
+import { readEnv } from "../env.js";
+
+/** The one canonical flag name — shared verbatim by the server and the CLI mirror. */
+export const ACTIVITY_KILL_SWITCH_FLAG = "ACTIVITY_TELEMETRY_DISABLED";
+
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+
+function truthy(v: string | null | undefined): boolean {
+  return typeof v === "string" && TRUTHY.has(v.trim().toLowerCase());
+}
+
+/** Primed once per isolate from the async Worker env. `undefined` until primed. */
+let primedDisabled: boolean | undefined;
+
+/** Synchronously-available env only (build-time `import.meta.env` + `process.env`) —
+ *  does NOT see Worker-only secrets, which arrive via {@link primeActivityKillSwitch}. */
+function fromSyncEnv(): boolean {
+  try {
+    const meta = (import.meta as unknown as { env?: Record<string, string | undefined> }).env;
+    if (meta && truthy(meta[ACTIVITY_KILL_SWITCH_FLAG])) return true;
+  } catch {
+    /* import.meta.env unavailable — ignore */
+  }
+  if (typeof process !== "undefined" && process.env && truthy(process.env[ACTIVITY_KILL_SWITCH_FLAG])) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * True when the entire activity pipeline is switched off. Sync + never throws.
+ * Fail-open: an unknown/unset flag ⇒ `false` (telemetry enabled).
+ */
+export function isActivityDisabled(): boolean {
+  return primedDisabled === true || fromSyncEnv();
+}
+
+/**
+ * Prime the kill switch from the (async) Worker env, once per isolate. Best-effort:
+ * a read fault leaves telemetry ENABLED (fail-open). Call at the middleware front door
+ * so every subsequent route emit in the isolate observes a Worker-secret flag.
+ */
+export async function primeActivityKillSwitch(): Promise<void> {
+  try {
+    primedDisabled = truthy(await readEnv(ACTIVITY_KILL_SWITCH_FLAG));
+  } catch {
+    primedDisabled = false;
+  }
+}
+
+/** Test-only: clear the primed cache so a test can re-exercise the prime path. */
+export function __resetActivityKillSwitchForTest(): void {
+  primedDisabled = undefined;
+}