@volter/twin-segment 0.1.0

package/src/segment-conformance.ts

@@ -0,0 +1,123 @@
+// Segment conformance — vendor-property checks over the modeled tracking plane. Each check
+// asserts a property of SEGMENT (a status, an envelope shape, a stored VALUE, a documented
+// refusal), never twin self-consistency, and each goes red if its handler is deleted.
+//
+// The third direction the probe⇄claim pair is blind to is closed by ROUTER_SURFACE below: every
+// method/path pair the ratified surface declares is exercised, and anything that answers neither
+// a modeled outcome nor the vendor-shaped loud gap is a failure. That is what catches
+// served-but-unclaimed surface (the googleoauth precedent, ADDING_A_TWIN §6).
+import { OPS } from './segment-surface.gen.ts';
+import { events, groups, handleSegmentTwinRequest, identities } from './segment-twin.ts';
+
+export type SegmentConformanceReport = { ok: boolean; checksRun: number; failures: string[] };
+
+const KEY = 'conformance_write_key';
+const body = (o: unknown) => JSON.stringify(o);
+
+/** The five modeled ops, as a LITERAL. Deliberately not derived from SEMANTICS: two constants
+ *  asserting about each other is not a check (the tinybird shape, ADDING_A_TWIN §6) — deleting a
+ *  handler must make this table disagree with the router, not follow it. */
+const MODELED_OPS = new Set(['batch', 'track', 'identify', 'page', 'group', 'alias']);
+
+export async function checkSegmentConformance(options: { root?: string } = {}): Promise<SegmentConformanceReport> {
+  const failures: string[] = [];
+  // COUNTED, never a literal: a hardcoded `checksRun` is satisfied by a report that ran FEWER
+  // checks than it claims, so deleting a check would leave the suite green — the
+  // two-constants-asserting-about-each-other shape (var/line/mixpanel/REVIEW.md F8).
+  let checksRun = 0;
+  const check = (name: string, ok: boolean) => { checksRun += 1; if (!ok) failures.push(name); };
+  const h = (method: string, path: string, payload?: string, authorization?: string) =>
+    handleSegmentTwinRequest({ method, path, body: payload, authorization, root: options.root });
+
+  // 1. The envelope the unmodified SDK sends is accepted with a 2xx — the ONLY thing
+  //    @segment/analytics-node@2 reads (`response.status >= 200 && response.status < 300`).
+  const flushed = await h('POST', '/v1/batch', body({
+    batch: [
+      { type: 'identify', userId: 'conf_user', traits: { plan: 'pro' }, messageId: 'conf_m1' },
+      { type: 'track', userId: 'conf_user', event: 'Conformance Ran', properties: { n: 1 }, messageId: 'conf_m2' },
+    ],
+    writeKey: KEY,
+    sentAt: '2026-08-24T00:00:00.000Z',
+  }));
+  check('POST /v1/batch answers 2xx for the SDK envelope', flushed.status >= 200 && flushed.status < 300);
+  check('every message in the batch folded, not just batch[0]', events(options.root).filter((e) => ['conf_m1', 'conf_m2'].includes(String(e.messageId))).length === 2);
+  check('the identify folded its traits into an identity', (identities(options.root).find((i) => i.id === 'conf_user')?.traits as Record<string, unknown> | undefined)?.plan === 'pro');
+  check('the track kept its event name and properties', events(options.root).some((e) => e.event === 'Conformance Ran' && (e.properties as Record<string, unknown>).n === 1));
+  check('the writeKey travelled from the ENVELOPE onto each message', events(options.root).find((e) => e.messageId === 'conf_m2')?.writeKey === KEY);
+
+  // 2. Basic auth with the write key as the USERNAME and an empty password — analytics-node v1's
+  //    wire shape, documented at http-api/index.md '#### Basic authentication'.
+  await h('POST', '/v1/track', body({ userId: 'conf_basic', event: 'Basic Auth', messageId: 'conf_m3' }), `Basic ${Buffer.from('basic_key:', 'utf8').toString('base64')}`);
+  const basic = events(options.root).find((e) => e.messageId === 'conf_m3');
+  check('Basic <base64(writeKey:)> resolves the write key from the header', basic?.writeKey === 'basic_key' && basic?.authScheme === 'basic');
+
+  // 3. A group call folds a group with its traits; an alias links previousId onto the userId.
+  await h('POST', '/v1/group', body({ userId: 'conf_user', groupId: 'conf_group', traits: { name: 'Initech' }, writeKey: KEY, messageId: 'conf_m4' }));
+  check('POST /v1/group folds group traits', (groups(options.root).find((g) => g.id === 'conf_group')?.traits as Record<string, unknown> | undefined)?.name === 'Initech');
+  await h('POST', '/v1/alias', body({ userId: 'conf_user', previousId: 'conf_anon', writeKey: KEY, messageId: 'conf_m5' }));
+  check('POST /v1/alias records previousId on the identity', ((identities(options.root).find((i) => i.id === 'conf_user')?.previousIds as string[] | undefined) ?? []).includes('conf_anon'));
+
+  // 4. The documented ACCEPT-AND-DROP: "The HTTP API requires that each payload has a userId
+  //    and/or anonymousId... Segment's tracking API responds with an no_user_anon_id error", and
+  //    the page's own rule is that everything but oversize/invalid-JSON answers 200.
+  const before = events(options.root).length;
+  const anon = await h('POST', '/v1/track', body({ event: 'No Identifier', writeKey: KEY, messageId: 'conf_m6' }));
+  check('a payload with neither userId nor anonymousId still answers 200', anon.status === 200);
+  check('...and is NOT folded into the event feed', events(options.root).length === before);
+
+  // 5. "If you send an event with invalid JSON, Segment returns a 400 Bad Request error" — and
+  //    the body is {code, message}, the shape analytics-python parses off any non-200.
+  const bad = await h('POST', '/v1/batch', '{not json');
+  const badBody = bad.body as { code?: unknown; message?: unknown };
+  check('invalid JSON answers 400 with the vendor {code, message} envelope', bad.status === 400 && typeof badBody.code === 'string' && typeof badBody.message === 'string');
+
+  // 6. "There is a maximum of 32KB per normal API request... Segment's API responds with 400 Bad
+  //    Request if these limits are exceeded."
+  const oversize = await h('POST', '/v1/track', body({ userId: 'u', event: 'Big', properties: { blob: 'x'.repeat(33 * 1024) }, writeKey: KEY }));
+  check('a >32KB direct request answers 400', oversize.status === 400);
+
+  // 7. A ratified-but-unmodeled op fails LOUDLY by name — never the vendor's blanket 200, which
+  //    would be indistinguishable from success.
+  const gap = await h('POST', '/v1/screen', body({ userId: 'u', name: 'Home', writeKey: KEY }));
+  const gapMsg = String((gap.body as { message?: unknown }).message ?? '');
+  check('an unmodeled route answers the loud [twin gap] naming the op', gap.status === 404 && gapMsg.includes('[twin gap]') && gapMsg.includes('screen'));
+
+  // 8. The sharper one: an unmodeled message TYPE riding INSIDE a modeled route. `screen` is a
+  //    type the unmodified SDK can put in a /v1/batch envelope, so the per-message dispatcher has
+  //    to refuse it by name rather than inherit /v1/batch's success.
+  const countBefore = events(options.root).length;
+  const mixed = await h('POST', '/v1/batch', body({ batch: [{ type: 'track', userId: 'u', event: 'Rides Along', messageId: 'conf_m7' }, { type: 'screen', userId: 'u', name: 'Home', messageId: 'conf_m8' }], writeKey: KEY }));
+  const mixedMsg = String((mixed.body as { message?: unknown }).message ?? '');
+  check('an unmodeled TYPE inside a modeled batch fails loudly by name', mixed.status === 404 && mixedMsg.includes('screen'));
+  check('...and nothing from that batch was stored', events(options.root).length === countBefore);
+
+  // 9. "Segment deduplicates events using the messageId field."
+  await h('POST', '/v1/track', body({ userId: 'conf_user', event: 'Deduped', writeKey: KEY, messageId: 'conf_dupe' }));
+  await h('POST', '/v1/track', body({ userId: 'conf_user', event: 'Deduped Again', writeKey: KEY, messageId: 'conf_dupe' }));
+  check('a repeated messageId folds exactly once', events(options.root).filter((e) => e.messageId === 'conf_dupe').length === 1);
+
+  // 10. Non-ASCII survives byte for byte. In-process fixtures can hide an encoding bug the wire
+  //     exposes, so this value is also driven through the real SDK in the integration suite.
+  await h('POST', '/v1/track', body({ userId: 'conf_uni', event: 'Café ☕', properties: { name: '日本語', emoji: '🎉' }, writeKey: KEY, messageId: 'conf_uni' }));
+  const uni = events(options.root).find((e) => e.messageId === 'conf_uni');
+  check('a non-ASCII payload round-trips unmangled', uni?.event === 'Café ☕' && (uni.properties as Record<string, unknown>).name === '日本語');
+
+  // 11. Unknown route: the vendor-shaped error envelope, not a bare string or an HTML page.
+  const unknown = await h('GET', '/never-a-real-endpoint');
+  const unknownBody = unknown.body as { code?: unknown; message?: unknown };
+  check('an unknown route answers 404 with the {code, message} envelope', unknown.status === 404 && typeof unknownBody.code === 'string' && typeof unknownBody.message === 'string');
+
+  // 12. ROUTER_SURFACE: every ratified op is exercised, and each must answer EITHER a modeled
+  //     outcome or the loud gap. A route that is served but not claimed here shows up as a
+  //     modeled-looking answer for an op MODELED_OPS does not list.
+  let surfaceOk = true;
+  for (const op of OPS) {
+    const probe = await h(op.method, op.path, op.method === 'GET' ? undefined : body({ userId: 'probe_user', event: 'Probe', groupId: 'g', previousId: 'p', batch: [], writeKey: KEY }));
+    const msg = String((probe.body as { message?: unknown } | undefined)?.message ?? '');
+    const isGap = probe.status === 404 && msg.includes('[twin gap]');
+    if (MODELED_OPS.has(op.id) ? isGap : !isGap) surfaceOk = false;
+  }
+  check('every ratified op answers either a modeled outcome or the loud gap, and no other', surfaceOk);
+
+  return { ok: failures.length === 0, checksRun, failures };
+}

package/src/segment-connector.ts

@@ -0,0 +1,233 @@
+// Segment CONNECTOR — pull/push against an INJECTED `SegmentExecute`, so every test and every
+// capability verify runs offline against a deterministic fake (the repo-wide connector
+// discipline: the real network exists only inside liveSegmentExecute).
+//
+// v1 scope, honestly: PUSH replays locally-ingested messages back through the injected execute
+// onto the vendor's real POST /v1/batch. PULL mirrors NOTHING, and that is a FACT about this
+// vendor rather than an unfinished job: Segment's tracking plane has NO read-back operation at
+// all. Every one of the sixteen ratified ops in var/line/segment/SURFACE.json is a WRITE (fifteen
+// ingestion routes plus an OAuth token exchange); the vendor's own answer to "did my event land"
+// is the browser Source Debugger, a live websocket view (segment-docs src/connections/sources/
+// debugger.md), not an API. The nearest read surface is the Profile API on a DIFFERENT host
+// (profiles.segment.com/v1/spaces/{spaceId}/collections/users/profiles/{id}/{traits,events,
+// external_ids,metadata,links}) behind a DIFFERENT credential (an Engage access token as HTTP
+// Basic username) and a different product tier, and it returns resolved PROFILES, never the raw
+// ingested events this twin folds. So there is nothing on the modeled plane to mirror. The gap is
+// FILED as the segment.connector.pull todo in segment-capabilities.ts and ruled in
+// var/line/segment/RULINGS.json (denominator:profile-api-is-the-only-read-back) — never faked
+// with an empty resource list, because a connector that maps "no read path" to "an empty account"
+// hands syncPull an empty account to fold over real observed state (ADDING_A_TWIN §6).
+import { assertBudgetGuardIntact, assertFastForward, confirmAction, NonFastForwardPushError, pendingActions, syncPull } from '@volter/world-core';
+import type { SyncResource, TwinAction } from '@volter/world-core';
+import { SegmentBudget, SegmentBudgetError, segmentCallWeight, type SegmentBudgetOptions } from './segment-budget.ts';
+
+export type SegmentExecute = (req: { method: string; path: string; body?: unknown }) => Promise<{ status: number; data: unknown }>;
+
+const SERVICE = 'segment';
+
+/** The real Segment tracking host. The ONLY place this pack names it as a live target. */
+export const SEGMENT_API_BASE = 'https://api.segment.io';
+
+/**
+ * THE CHOKE POINT — the one place this pack builds a `SegmentExecute` that really reaches
+ * api.segment.io. Reads the source write key from `SEGMENT_WRITE_KEY` (never a literal).
+ *
+ * AUTH: this sends the scheme the PINNED SDK sends, not the scaffold's guess. @segment/
+ * analytics-node@2 puts the write key IN THE BODY and sets no Authorization header at all
+ * (src/plugins/segmentio/publisher.ts:230-247 — Content-Type and User-Agent only, plus a Bearer
+ * header ONLY when oauthSettings are configured), and the vendor documents that as its first
+ * auth option: "The authentication writeKey should be sent as part of the body of the request...
+ * For this auth type, you do not need to set any authentication header." A `Bearer <writeKey>`
+ * header — what the S4 scaffold emits by default — is not one of the three documented schemes and
+ * would authenticate nothing (ruled: denominator:auth-is-three-documented-schemes-not-one). So
+ * the key is STAMPED INTO THE ENVELOPE here, and `sentAt` alongside it, exactly as the SDK does.
+ * No vendor SDK is imported: real-transport `fetch` keeps the pack SDK-free at runtime (B3).
+ */
+export function liveSegmentExecute(
+  opts: {
+    apiKey?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executes. Omit and one is constructed. Cannot be null. */
+    budget?: SegmentBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: SegmentBudgetOptions;
+    /** Frozen clock for the envelope's `sentAt`; tests inject it, production omits it. */
+    now?: () => Date;
+  } = {},
+): SegmentExecute {
+  const apiKey = opts.apiKey ?? process.env.SEGMENT_WRITE_KEY;
+  const base = (opts.baseUrl ?? SEGMENT_API_BASE).replace(/\/$/, '');
+  const doFetch = opts.fetchImpl ?? fetch;
+  const now = opts.now ?? (() => new Date());
+  if (!apiKey) throw new Error('liveSegmentExecute: SEGMENT_WRITE_KEY is not set (never pass a literal)');
+  // No caller value yields an unguarded execute: omitted/null builds the default; anything else
+  // must be an UNMODIFIED SegmentBudget. `instanceof` alone is NOT a check — a one-line subclass
+  // or a Proxy trapping `get` satisfies it and disables the ceiling — so the kernel's
+  // method-identity assertion is used instead (docs/contributing/architecture.md D8).
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, SegmentBudget, 'liveSegmentExecute')
+    : new SegmentBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async ({ method, path, body }) => {
+    const weight = segmentCallWeight(method, path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const payload = body === undefined ? undefined : stampEnvelope(body, apiKey, now());
+    const res = await doFetch(`${base}${path}`, {
+      method,
+      // "To send data to Segment's HTTP API, a content-type header must be set to
+      // 'application/json'." (http-api/index.md '### Content-Type')
+      headers: payload === undefined ? {} : { 'content-type': 'application/json' },
+      ...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
+    });
+    const headers: Record<string, string> = {};
+    res.headers.forEach((v, k) => (headers[k.toLowerCase()] = v));
+    const text = await res.text();
+    // Settles the reservation; a 429/Retry-After arms the persisted cooldown (and may throw).
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer Segment ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, headers, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof SegmentBudgetError) || !res.ok) throw error;
+    }
+    let data: unknown = null;
+    if (text) { try { data = JSON.parse(text); } catch { data = text; } }
+    return { status: res.status, data };
+  };
+}
+
+/** The auth step the docblock above promises, made real: the write key rides INSIDE the envelope
+ *  (`writeKey`), with `sentAt` beside it, exactly as @segment/analytics-node@2's Publisher builds
+ *  it. Only an ABSENT key is filled — an envelope that already names one (a different source, a
+ *  caller override) is left exactly as it is. This is the mixpanel F7 class, pre-empted: a
+ *  docblock claiming a stamping no call site performed sent every replayed message unauthenticated. */
+export function stampEnvelope(body: unknown, writeKey: string, sentAt: Date): unknown {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return body;
+  const env = body as Record<string, unknown>;
+  return {
+    ...env,
+    ...(typeof env.writeKey === 'string' && env.writeKey ? {} : { writeKey }),
+    ...(typeof env.sentAt === 'string' && env.sentAt ? {} : { sentAt: sentAt.toISOString() }),
+  };
+}
+
+/**
+ * A pull's `occurredAt` must MOVE, never be pinned. The kernel hashes an observed event over
+ * (`occurredAt` + post-state), so under a fixed poll time a vendor value that REVERTS (A->B->A
+ * across polls) collides with its own earlier observation: `syncPull` reports a delta while
+ * nothing lands, and the projection keeps serving the stale value. Wall clock alone is not quite
+ * enough either — two polls inside one millisecond hand the kernel the same stamp — so it is
+ * forced strictly increasing within the process (the dynadot `pollTimestamp` precedent).
+ */
+let lastPollAt = 0;
+function pollTimestamp(): string {
+  const now = Math.max(Date.now(), lastPollAt + 1);
+  lastPollAt = now;
+  return new Date(now).toISOString();
+}
+
+/** D7 entry point. v1 pulls nothing — see the file header for the vendor fact that makes it so,
+ *  and segment-capabilities.ts's `segment.connector.pull` todo for the filed gap. `syncPull` is
+ *  still called with the (empty) resource list so the shadow-diff contract holds and a later
+ *  version only has to fill the array. */
+export async function syncSegmentFromReal(_execute: SegmentExecute, options: { root?: string; occurredAt?: string } = {}): Promise<{ pulled: number }> {
+  const resources: SyncResource[] = [];
+  // Kernel API takes an OPTIONS OBJECT; occurredAt is required (positional args die at runtime).
+  syncPull({
+    service: SERVICE,
+    resources,
+    occurredAt: options.occurredAt ?? pollTimestamp(),
+    ...(options.root !== undefined ? { root: options.root } : {}),
+  });
+  return { pulled: resources.length };
+}
+
+/** Replay locally-ingested messages through the injected execute (push half of D7). Sends the
+ *  vendor's own batch envelope — `{batch: [<message>...], writeKey, sentAt}` — which is exactly
+ *  what @segment/analytics-node@2's Publisher puts on the wire, so the replay is byte-shaped like
+ *  a real SDK flush rather than like this twin's internal rows. */
+export async function pushPendingSegmentActions(
+  execute: SegmentExecute,
+  options: { root?: string; writeKey?: string } = {},
+): Promise<{ pushed: number; failed: number; refused: number }> {
+  let pushed = 0;
+  let failed = 0;
+  let refused = 0;
+  for (const action of pendingActions(SERVICE, options.root) as TwinAction[]) {
+    // Only ingested flushes are pushable in v1; a `drop.messages` action records messages the
+    // VENDOR would have rejected, so replaying them would re-send data Segment already refused.
+    if (!action.operation?.startsWith('ingest.')) continue;
+    // R14 non-fast-forward gate (THE reference enrollment for the connector sweep): the mirror
+    // moving past this action's stamped basis means someone else changed the remote since it was
+    // authored — pushing would overwrite them. The action is SKIPPED (stays pending, per-ref like
+    // git), counted, and the operator fetches + reconciles, then reverts/re-authors or pushes
+    // with a reviewed force through the kernel seam. The check sits IMMEDIATELY before the
+    // vendor write: any later and the refusal arrives after the damage.
+    try {
+      assertFastForward(SERVICE, action.id, options.root);
+    } catch (error) {
+      if (error instanceof NonFastForwardPushError) { refused += 1; continue; }
+      throw error;
+    }
+    const envelope = pushEnvelopeFor(action, options.writeKey);
+    const res = await execute({ method: 'POST', path: '/v1/batch', body: envelope });
+    // "Segment returns a 200 response for all API requests except errors caused by large payloads
+    // and JSON errors (which return 400 responses.)" — so any 2xx is acceptance of the REQUEST.
+    // Anything else leaves the action pending rather than silently confirming it.
+    if (res.status >= 200 && res.status < 300) {
+      // The kernel's confirmAction takes an OPTIONS OBJECT — it records the pushed fields as an
+      // OBSERVED event and maps the local action onto it, so the change is counted exactly once.
+      //
+      // AND IT HAS TO CARRY THE WHOLE FLUSH. `projectResources` SUPPRESSES a confirmed action's
+      // projection outright — `if (reverted.has(a.id) || confirmed.has(a.id)) continue`
+      // (control-plane/src/actions.ts) — and rebuilds that state from the observed events the
+      // confirm wrote instead. A Segment flush is ONE action whose projection carries EVERY
+      // message of the batch plus the identities and groups they folded, so confirming with
+      // `fields` alone observes batch[0] only and DELETES the rest of the flush from the
+      // projection the moment it is pushed. Every other resource of the action therefore rides in
+      // `additionalObservations`, the kernel's own seam for a compound action
+      // (npm-registry-connector.ts is the precedent).
+      const primaryKey = `${action.subject.type}:${action.subject.id}`;
+      const additionalObservations = (action.projection?.creates ?? [])
+        .filter((c) => `${c.type}:${c.id}` !== primaryKey)
+        .map((c) => ({ subject: { type: c.type, id: c.id }, fields: c.fields }));
+      confirmAction({
+        service: SERVICE,
+        actionId: action.id,
+        subject: action.subject,
+        fields: action.fields ?? {},
+        ...(additionalObservations.length ? { additionalObservations } : {}),
+        occurredAt: new Date().toISOString(),
+        ...(options.root ? { root: options.root } : {}),
+      });
+      pushed += 1;
+    } else failed += 1;
+  }
+  return { pushed, failed, refused };
+}
+
+/** Rebuild the vendor ENVELOPE this action recorded. The twin folds one flush into ONE action
+ *  whose `projection.creates` carries every event row of that flush, so the replay reconstructs
+ *  the same `{batch: [...]}` the SDK originally sent rather than exploding it into single-message
+ *  requests. Two traps this closes:
+ *   • the twin stores the discriminator as `messageType`, because the kernel's META set silently
+ *     drops a field literally named `type` (control-plane/src/actions.ts) — so the replay has to
+ *     map it BACK to `type`, or every replayed message would reach the real vendor typeless;
+ *   • `action.fields` alone is only the FIRST message of the flush, so reading it instead of the
+ *     projection would silently push one message and confirm the whole batch. */
+export function pushEnvelopeFor(action: TwinAction, writeKey?: string): Record<string, unknown> {
+  const creates = (action.projection?.creates ?? []).filter((c) => c.type === 'event');
+  const rows = creates.length ? creates.map((c) => c.fields as Record<string, unknown>) : [(action.fields ?? {}) as Record<string, unknown>];
+  const batch = rows.map((f) => {
+    const message: Record<string, unknown> = { type: f.messageType, messageId: f.messageId };
+    for (const key of ['userId', 'anonymousId', 'event', 'name', 'category', 'groupId', 'previousId', 'properties', 'traits', 'context', 'integrations', 'timestamp'] as const) {
+      if (f[key] !== null && f[key] !== undefined) message[key] = f[key];
+    }
+    return message;
+  });
+  const first = rows[0] ?? {};
+  const resolved = writeKey ?? (typeof first.writeKey === 'string' ? first.writeKey : undefined);
+  return { batch, ...(resolved ? { writeKey: resolved } : {}) };
+}

package/src/segment-journey.uitest.ts

@@ -0,0 +1,116 @@
+// SEGMENT UI JOURNEY — the pack's registered read journey (ui-scope.json
+// `segment.journey.debugger`). Seed real state through the pack's OWN write path
+// (`handleSegmentTwinRequest` against the vendor's real `/v1/batch`, never a hand-written events
+// log), boot the real mirror server (`createSegmentMirrorServer`) on an ephemeral port, and drive
+// it with real headless Playwright chromium using role/text locators ONLY.
+//
+// Proves the journey the census names: open the Source Debugger and SEE the events a source
+// received, with their type, label, subject and properties — and then switch to the Dropped stream
+// and see the message that returned 200 and never arrived, with the REASON it was dropped. That
+// second half is the whole point of the screen: the Segment tracking API answers 200 and then
+// silently drops a message it cannot attribute, so without this stream "200 but missing" is
+// invisible.
+//
+// Every step writes a filmstrip frame (the `visible`/`clickByName` helpers do this), which is the
+// evidence a reviewer certifies the UI rung from.
+//
+// Must never SILENTLY skip: `requireBrowser` throws with the fix command when chromium is missing,
+// unless the operator sets the loud opt-out env var.
+import { describe, test } from 'bun:test';
+import { requireBrowser, runUiJourney, JOURNEY_TIMEOUT_MS, visible, gone, clickByName } from '@volter/world-tooling';
+import { handleSegmentTwinRequest } from './segment-twin.ts';
+import { createSegmentMirrorServer } from './segment-mirror-ui.ts';
+
+const JOURNEY_LABEL = 'segment UI journey';
+const KEY = 'twin_journey_write_key';
+const AUTH = `Basic ${Buffer.from(`${KEY}:`).toString('base64')}`;
+const OCC = '2026-03-01T09:41:07.000Z';
+
+/**
+ * Seed one batch through the vendor's REAL route: a named track with properties, a page view, an
+ * identify — and one message carrying neither `userId` nor `anonymousId`, which is the vendor's
+ * own documented drop and the row the second half of the journey looks for.
+ */
+async function seedWorld(root: string) {
+  await handleSegmentTwinRequest({
+    method: 'POST',
+    path: '/v1/batch',
+    authorization: AUTH,
+    body: JSON.stringify({
+      writeKey: KEY,
+      sentAt: OCC,
+      batch: [
+        { type: 'track', userId: 'u_journey', event: 'Order Completed', properties: { revenue: 14.99, currency: 'USD' }, messageId: 'm_track' },
+        { type: 'page', userId: 'u_journey', name: 'Pricing', properties: { path: '/pricing' }, messageId: 'm_page' },
+        { type: 'identify', userId: 'u_journey', traits: { email: 'journey@example.test' }, messageId: 'm_identify' },
+        { type: 'track', event: 'Orphan Event', messageId: 'm_orphan' },
+      ],
+    }),
+    root,
+    occurredAt: OCC,
+  });
+}
+
+const serve = async (root: string) => {
+  const server = await createSegmentMirrorServer({ root, port: 0 });
+  return { url: `http://127.0.0.1:${server.port}`, stop: () => server.stop() };
+};
+
+describe('segment UI journey', () => {
+  test('the Source Debugger streams the events the source received, with their properties', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    await runUiJourney({
+      label: 'segment the source debugger streams the events the source received',
+      seed: seedWorld,
+      serve,
+      journey: async (page) => {
+        // 1. The accepted stream is the default screen and names each message the way the vendor
+        //    does — a track by its event, a page by its name, an identify by its subject.
+        await visible(page, 'Order Completed');
+        await visible(page, 'Pricing');
+        await visible(page, 'u_journey');
+
+        // 2. The properties are on the row. This is what a debugger reader is actually after when
+        //    an event "arrived but is wrong", and no header or nav renders these strings.
+        await visible(page, 'revenue');
+        await visible(page, '14.99');
+        await visible(page, 'currency');
+        await visible(page, 'USD');
+
+        // 3. The counts are live: three messages were attributed, one was not.
+        await visible(page, '3 accepted');
+        await visible(page, '1 dropped');
+      },
+    });
+  }, JOURNEY_TIMEOUT_MS);
+
+  test('the Dropped stream shows the message that returned 200 and never arrived, with its reason', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    await runUiJourney({
+      label: 'segment the dropped stream shows the 200-but-never-arrived message and its reason',
+      seed: seedWorld,
+      serve,
+      journey: async (page) => {
+        await visible(page, 'Order Completed');
+
+        // The nav item is a real role-reachable <button>; its destination must show the row the
+        // twin recorded as REFUSED — a shell that rendered but read nothing would fail here.
+        await clickByName(page, /^Dropped$/);
+        await visible(page, 'no_user_anon_id');
+        await visible(page, '/v1/batch');
+        // ...and the accepted stream's content is GONE from this screen: two streams, not one
+        // list. A POSITIVE assertion on the word "dropped" was dead — the header renders
+        // "N dropped" on every screen and the nav button says "Dropped", so it passed with both
+        // streams deleted (§9). `gone` is the assertion that has teeth.
+        await gone(page, 'Order Completed');
+        await gone(page, 'Pricing');
+
+        // …and back to Accepted, which still has its live data (no unmount damage).
+        await clickByName(page, /^Accepted$/);
+        await visible(page, 'Pricing');
+      },
+    });
+  }, JOURNEY_TIMEOUT_MS);
+});

package/src/segment-mirror-ui.ts

@@ -0,0 +1,157 @@
+// SEGMENT MIRROR UI — the SOURCE DEBUGGER, served as a React/TSX app (bundled by Bun).
+//
+// WHY THIS SCREEN AND NOT ANOTHER. The Segment HTTP Tracking API is WRITE-ONLY: every one of its
+// sixteen ratified operations is an ingest, and none of them reads a message back. So the vendor's
+// own answer to "my event returned 200 and never arrived" is not an API call — it is the Source
+// Debugger, the live stream of what the source actually received. That asymmetry is exactly why
+// ui-scope.json rules this vendor OWED a mirror, and it is why the debugger is the FIRST screen:
+// without it a caller has a 200 and nothing else.
+//
+// DATA COUPLING. The client reads the twin's OWN store door (`GET /twin/store/events`,
+// `…/dropped`), the kernel's read-only named-projection door and the sanctioned way a mirror reads
+// twin state. There is no mirror-local view model and no second copy of the projection: what the
+// screen shows is what `events(root)` folded from real ingests, so a caller who POSTs through the
+// unmodified `@segment/analytics-node` client sees that message on this screen.
+//
+// THE DROPPED PANE IS THE POINT. Segment answers 200 and then silently drops a message it cannot
+// attribute; this twin RECORDS the refusal (`dropped(root)`, with a reason). The debugger shows
+// both streams side by side, so "returned 200 and never arrived" stops being invisible — which is
+// the exact failure the vendor tells you to open this screen for.
+//
+// PURE FRONTEND (R3): this module imports no handler and no twin internals. It MOUNTS the pack's
+// own fetch adapter as the API backend and the client reads every byte of state back over the wire.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createSegmentTwinFetch } from './segment-server.ts';
+
+const CLIENT_ENTRY = () => new URL('../client/segment-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects a top-level relative import.meta.url
+const CLIENT_CSS = () => new URL('../client/segment-mirror.css', import.meta.url).pathname;  // lazy: same
+
+// ---------------------------------------------------------------------------
+// Pure, dependency-free render/format helpers (importable by the React client; Bun tree-shakes
+// the server-only exports out of the browser bundle). Free of @volter/world-core, Bun and the handler.
+// ---------------------------------------------------------------------------
+
+/** One row of the `events` / `dropped` store projections, as the door serves it. */
+export type SegmentRow = Record<string, any>;
+
+/** The tone a message-type pill gets. `alias` and `group` are the identity-plumbing calls, so they
+ *  read differently from `track`, which is the one carrying a business event name. */
+export type PillTone = 'track' | 'identity' | 'screenish' | 'dropped';
+
+/** STATIC literal class names — a template-literal class (`pill-${tone}`) is erased by the
+ *  bundler, so the mirror emits these and the verifies assert them (ADDING_A_TWIN §6). */
+export const PILL_CLASS: Record<PillTone, string> = {
+  track: 'pill pill-track',
+  identity: 'pill pill-identity',
+  screenish: 'pill pill-screenish',
+  dropped: 'pill pill-dropped',
+};
+
+/** The tone for a message type. Pure function of the vendor's own six call types. */
+export function typeTone(messageType: unknown): PillTone {
+  switch (String(messageType ?? '')) {
+    case 'track': return 'track';
+    case 'identify':
+    case 'alias':
+    case 'group': return 'identity';
+    default: return 'screenish';
+  }
+}
+
+/**
+ * The LABEL the debugger shows for a message — what the vendor's own stream leads each row with.
+ * A `track` is named by its `event`; a `page`/`screen` by its `name`; the identity calls by the
+ * subject they resolve. Never the message id, which tells a reader nothing.
+ */
+export function messageLabel(row: SegmentRow): string {
+  const type = String(row.messageType ?? '');
+  if (type === 'track') return String(row.event ?? '(unnamed event)');
+  if (type === 'page' || type === 'screen') return String(row.name ?? '(unnamed page)');
+  if (type === 'group') return `group ${String(row.groupId ?? '?')}`;
+  if (type === 'alias') return `alias ${String(row.previousId ?? '?')} → ${String(row.userId ?? '?')}`;
+  return String(row.userId ?? row.anonymousId ?? '(anonymous)');
+}
+
+/** The subject a row is attributed to — `userId` when Segment could resolve one, else the
+ *  anonymous id. A row with neither is precisely the one the vendor drops. */
+export function subjectOf(row: SegmentRow): string {
+  const userId = row.userId === null || row.userId === undefined ? '' : String(row.userId);
+  if (userId !== '') return userId;
+  const anon = row.anonymousId === null || row.anonymousId === undefined ? '' : String(row.anonymousId);
+  return anon === '' ? '—' : `anon:${anon}`;
+}
+
+/** Flatten one level of a properties/traits object into `key=value` chips, sorted so a rendered
+ *  row is byte-identical on replay. Nested values render as compact JSON. */
+export function propertyChips(value: unknown): Array<{ key: string; value: string }> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return [];
+  return Object.entries(value as Record<string, unknown>)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, v]) => ({ key, value: typeof v === 'string' ? v : JSON.stringify(v) ?? 'null' }));
+}
+
+/** `2026-03-01T12:00:00.000Z` → `12:00:00` — the wall-position the debugger's stream reads by.
+ *  Pure string slicing, so it neither reads a clock nor depends on the machine's zone. */
+export function clockLabel(iso: unknown): string {
+  const s = String(iso ?? '');
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(s) ? s.slice(11, 19) : '—';
+}
+
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>Segment Source Debugger (twin)</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+
+let clientBundle: Promise<string> | null = null;
+/** Build the React/TSX debugger client to browser JS (Bun bundles TSX); cached per process. */
+export function buildSegmentMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(CLIENT_ENTRY())
+      .catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+/** Serve the Source Debugger mirror (React app) + the twin's own fetch adapter behind it. */
+export async function createSegmentMirrorServer(options: { root?: string; port?: number } = {}): Promise<{ port: number; stop: () => void }> {
+  const twin = createSegmentTwinFetch(options);
+  const server = await serveHttp({
+    // LOOPBACK-SPECIFIC bind: with the default wildcard hostname, `port: 0` can be handed a port
+    // some long-running app already LISTENS on at 127.0.0.1, and that more specific listener then
+    // shadows this server for every 127.0.0.1 fetch — the verify would talk to a stranger.
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try { return new Response(await buildSegmentMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      // Everything else → the twin's OWN FETCH ADAPTER (composition, R2). The client reads
+      // `/twin/store/events` and `/twin/store/dropped` on this same origin, and the adapter is the
+      // same closure `createSegmentTwinServer` serves — so there is exactly ONE serving code path
+      // and the mirror port cannot drift from the API port.
+      return twin(request);
+    },
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+/** The app-shell HTML (pure, for tests). The debugger itself is the React client. */
+export function segmentMirrorHtml(): string {
+  return APP_SHELL;
+}
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function segmentMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}