@volter/twin-segment 0.1.0

package/dist/src/segment-conformance.d.ts

@@ -0,0 +1,8 @@
+export type SegmentConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    failures: string[];
+};
+export declare function checkSegmentConformance(options?: {
+    root?: string;
+}): Promise<SegmentConformanceReport>;

package/dist/src/segment-conformance.js

@@ -0,0 +1,106 @@
+// 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.js";
+import { events, groups, handleSegmentTwinRequest, identities } from "./segment-twin.js";
+const KEY = 'conformance_write_key';
+const body = (o) => 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 = {}) {
+    const failures = [];
+    // 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, ok) => { checksRun += 1; if (!ok)
+        failures.push(name); };
+    const h = (method, path, payload, authorization) => 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?.plan === 'pro');
+    check('the track kept its event name and properties', events(options.root).some((e) => e.event === 'Conformance Ran' && e.properties.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?.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 ?? []).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;
+    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.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.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.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;
+    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?.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/dist/src/segment-connector.d.ts

@@ -0,0 +1,76 @@
+import type { TwinAction } from '@volter/world-core';
+import { SegmentBudget, type SegmentBudgetOptions } from './segment-budget.js';
+export type SegmentExecute = (req: {
+    method: string;
+    path: string;
+    body?: unknown;
+}) => Promise<{
+    status: number;
+    data: unknown;
+}>;
+/** The real Segment tracking host. The ONLY place this pack names it as a live target. */
+export declare 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 declare 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;
+/** 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 declare function stampEnvelope(body: unknown, writeKey: string, sentAt: Date): unknown;
+/** 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 declare function syncSegmentFromReal(_execute: SegmentExecute, options?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    pulled: number;
+}>;
+/** 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 declare function pushPendingSegmentActions(execute: SegmentExecute, options?: {
+    root?: string;
+    writeKey?: string;
+}): Promise<{
+    pushed: number;
+    failed: number;
+    refused: number;
+}>;
+/** 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 declare function pushEnvelopeFor(action: TwinAction, writeKey?: string): Record<string, unknown>;

package/dist/src/segment-connector.js

@@ -0,0 +1,226 @@
+// 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 { SegmentBudget, SegmentBudgetError, segmentCallWeight } from "./segment-budget.js";
+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 = {}) {
+    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 = {};
+        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 = 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, writeKey, sentAt) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return body;
+    const env = body;
+    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() {
+    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, options = {}) {
+    const resources = [];
+    // 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, options = {}) {
+    let pushed = 0;
+    let failed = 0;
+    let refused = 0;
+    for (const action of pendingActions(SERVICE, options.root)) {
+        // 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, writeKey) {
+    const creates = (action.projection?.creates ?? []).filter((c) => c.type === 'event');
+    const rows = creates.length ? creates.map((c) => c.fields) : [(action.fields ?? {})];
+    const batch = rows.map((f) => {
+        const message = { type: f.messageType, messageId: f.messageId };
+        for (const key of ['userId', 'anonymousId', 'event', 'name', 'category', 'groupId', 'previousId', 'properties', 'traits', 'context', 'integrations', 'timestamp']) {
+            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/dist/src/segment-mirror-ui.d.ts

@@ -0,0 +1,42 @@
+/** 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 declare const PILL_CLASS: Record<PillTone, string>;
+/** The tone for a message type. Pure function of the vendor's own six call types. */
+export declare function typeTone(messageType: unknown): PillTone;
+/**
+ * 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 declare function messageLabel(row: SegmentRow): string;
+/** 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 declare function subjectOf(row: SegmentRow): string;
+/** 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 declare function propertyChips(value: unknown): Array<{
+    key: string;
+    value: string;
+}>;
+/** `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 declare function clockLabel(iso: unknown): string;
+/** Build the React/TSX debugger client to browser JS (Bun bundles TSX); cached per process. */
+export declare function buildSegmentMirrorClient(): Promise<string>;
+/** Serve the Source Debugger mirror (React app) + the twin's own fetch adapter behind it. */
+export declare function createSegmentMirrorServer(options?: {
+    root?: string;
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+/** The app-shell HTML (pure, for tests). The debugger itself is the React client. */
+export declare function segmentMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function segmentMirrorStyles(): Promise<string>;

package/dist/src/segment-mirror-ui.js

@@ -0,0 +1,143 @@
+// 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.js";
+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
+/** 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 = {
+    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) {
+    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) {
+    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) {
+    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) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    return Object.entries(value)
+        .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) {
+    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 = null;
+/** Build the React/TSX debugger client to browser JS (Bun bundles TSX); cached per process. */
+export function buildSegmentMirrorClient() {
+    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 = {}) {
+    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() {
+    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() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

package/dist/src/segment-server.d.ts

@@ -0,0 +1,25 @@
+/** Options every Segment-twin HTTP surface needs, independent of who owns the socket. */
+export interface SegmentTwinFetchOptions {
+    root?: string;
+}
+/** The twin's HTTP face. Two things it must get right, both invisible to an in-process verify:
+ *  1. THE AUTHORIZATION HEADER IS PART OF THE PAYLOAD on this vendor. Two of Segment's three
+ *     documented auth schemes live in that header (Basic with the write key as the username;
+ *     OAuth Bearer), so a fetch that dropped it would make an analytics-node v1 client — which
+ *     sends `auth: { username: writeKey }` and NO writeKey in the body — arrive anonymous.
+ *  2. An empty-body status must serve a genuinely EMPTY body: `Response.json(null)` puts the
+ *     four bytes "null" on the wire (the A3-caught serialization class in
+ *     var/line/mixpanel/REVIEW.md).
+ *
+ *  FETCH-FIRST (runtime contract R12b): this is the pack's whole HTTP surface as a plain fetch,
+ *  and `createSegmentTwinServer` is one line of `Bun.serve` around it. It is a CUSTOM fetch, not
+ *  the kernel adapter (`createTwinFetchFromHandler`): the authorization threading (1) and the
+ *  handler-throw guard (below) are this pack's own. The keyless `GET /twin` manifest door the
+ *  adapter would have provided is mounted here by hand, answering the same
+ *  `statefulTwinManifest` shape — discovery is a door every twin owes (serve-path determinism
+ *  R9 replays it), and `/twin` shadows no Segment route: the Tracking API lives under `/v1/*`. */
+export declare function createSegmentTwinFetch(options?: SegmentTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createSegmentTwinServer(options?: {
+    port?: number;
+    root?: string;
+}): Promise<import("@volter/world-core").HttpServer>;