@volter/twin-segment 0.1.0

package/dist/src/segment-capabilities.js

@@ -0,0 +1,907 @@
+// Segment capability manifest — the REAL vendor surface as the denominator.
+//
+// ── WHERE THIS DENOMINATOR CAME FROM, AND WHERE IT STOPS ─────────────────────────────────────
+// Segment publishes NO machine-readable spec for its ingestion surface, so the denominator was
+// AUTHORED from evidence at var/line/segment/SURFACE.json (the line's A0 station) and compiled
+// into segment-capabilities.gen.ts. Sixteen operations, each carrying the evidence it was
+// ratified on, in two tiers of strength:
+//   • SDK WIRE LITERAL (2): POST /v1/batch — the single URL @segment/analytics-node@2.3.0's
+//     Publisher ever posts to — and POST /token on the OAuth authorization server.
+//   • DOCS ONLY, NOT VERIFIED OFFLINE (14): the six direct POST /v1/<type> routes, the mobile
+//     batch route POST /v1/b, analytics.js's POST /v1/t, and the six literal Pixel Routes
+//     GET /v1/pixel/<type>. All grounded in github.com/segmentio/segment-docs, the vendor's own
+//     docs SOURCE repository (segment.com answers 403 to non-browser clients).
+// Rulings and the ratified vendor facts: var/line/segment/RULINGS.json + FACTS.json.
+//
+// FIVE THINGS THIS DENOMINATOR EXCLUDES, each ruled rather than silently omitted:
+//   1. The Segment PUBLIC API (api.segmentapis.com) — workspaces, sources, destinations,
+//      warehouses, tracking plans — a different product on a different host behind a workspace
+//      token. Ruled denominator:public-api-plane-is-out-of-scope; NOT claimed in the injector
+//      host map, so a Public API call from a world still leaves for the real vendor.
+//   2. The PROFILE API (profiles.segment.com) — the vendor's only nearby read surface, on a
+//      different host, credential and product tier, returning resolved profiles rather than
+//      ingested events. Ruled denominator:profile-api-is-the-only-read-back; it is the reason
+//      connector pull is a filed gap rather than an unfinished job.
+//   3. cdn.segment.com/v1/projects/{writeKey}/settings — real and first-party, but that host also
+//      serves the analytics.js BUNDLE, so routing it into the twin would break loading the real
+//      library. Ruled denominator:cdn-settings-plane-named-but-not-claimed; left OUT rather than
+//      added-and-unreachable.
+//   4. Inbound webhooks — this vendor has none on the tracking plane (checked: no
+//      webhooks.segment.com anywhere in the docs tree, no generic Webhook Source page). Ruled
+//      denominator:no-inbound-webhook-surface, so the absence of webhook capabilities is a
+//      finding, not an oversight.
+//   5. The OBJECTS APIs — objects.segment.com/v1/set and the four /v0 routes of
+//      objects-bulk-api.segmentapis.com. Real, first-party, and on the SAME server-source catalog
+//      branch as the two API planes this pack did ratify, behind the SAME source write key and the
+//      same HTTP Basic pair; A0 missed them, and A3 filed them. They stay out — the plane is
+//      beta on its own page, is warehouse-object loading rather than event ingestion, and no
+//      `analytics-<language>` client can reach it, so this article's SDK-anchored method has
+//      nothing to verify against. Ruled denominator:object-apis-plane-named-but-not-claimed.
+//      Neither host is claimed in the injector map, so those calls still leave for the real
+//      vendor: the same named exposure the Public API carries, and the same follow-up.
+//
+// ── A MIRROR IS OWED AND FILED, NOT FABRICATED ───────────────────────────────────────────────
+// Segment fails the "API is the product" test the same way its sibling analytics pack does: the
+// instrumentation half is written in code, but the vendor's core job — wiring sources to
+// destinations, reading the live Source Debugger, editing tracking plans — happens in a browser.
+// ui-scope.json rules needsUi TRUE and the screens are filed as todos below rather than invented.
+// What this pack models today is the INGESTION half, which is genuinely code-first.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { checkCapabilities, verifyBoundary } from '@volter/world-tooling';
+import { buildSegmentMirrorClient, createSegmentMirrorServer } from "./segment-mirror-ui.js";
+import { DroppedRow, EventRow } from "../client/segment-mirror.js";
+import { GENERATED_CAPABILITIES } from "./segment-capabilities.gen.js";
+import { liveSegmentExecute, pushPendingSegmentActions, syncSegmentFromReal } from "./segment-connector.js";
+import { OPS } from "./segment-surface.gen.js";
+import { dropped, events, groups, handleSegmentTwinRequest, identities, SEGMENT_MAX_BATCH_EVENTS, SEGMENT_MAX_REQUEST_BYTES, SEMANTICS, } from "./segment-twin.js";
+/** Run a verify against a FRESH temp root so it proves the capability from nothing. An omitted
+ *  root would not error — the kernel falls back to the operator's real ~/.volter state dir, which
+ *  is gitignored, so the verify would pass while poisoning later runs. */
+async function withRoot(fn) {
+    const root = mkdtempSync(join(tmpdir(), 'segment-cap-'));
+    const h = (method, path, body, authorization) => handleSegmentTwinRequest({
+        method,
+        path,
+        body: body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body),
+        authorization,
+        root,
+    });
+    try {
+        return await verifyBoundary('segment.withRoot', () => fn(h, root));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+/** The mirror's browser bundle, built ONCE per process. `Bun.build` has a per-process ceiling
+ *  (~6), so every UI verify shares this one promise — see ADDING_A_TWIN §9's measurement note. */
+let bundle = null;
+const mirrorBundle = () => (bundle ??= buildSegmentMirrorClient());
+/** Run a verify against a FRESH temp root with the REAL mirror server listening on a real socket,
+ *  so what is asserted is what a browser would actually be served — not an in-process collector's
+ *  view of it (the azure `data: [DONE]` class: a structurally invisible wire frame). */
+async function withMirrorRoot(fn) {
+    const root = mkdtempSync(join(tmpdir(), 'segment-mirror-cap-'));
+    const server = await createSegmentMirrorServer({ root, port: 0 });
+    const h = (method, path, body, authorization) => handleSegmentTwinRequest({
+        method,
+        path,
+        body: body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body),
+        authorization,
+        root,
+    });
+    const fetchOrigin = (path) => fetch(`http://127.0.0.1:${server.port}${path}`);
+    try {
+        return await verifyBoundary('segment.withMirrorRoot', () => fn(fetchOrigin, h, root));
+    }
+    finally {
+        server.stop();
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+const KEY = 'twin_write_key';
+/** The envelope shape @segment/analytics-node@2's Publisher builds (publisher.ts:243-247). */
+const flush = (messages, extra = {}) => ({
+    batch: messages,
+    writeKey: KEY,
+    sentAt: '2026-08-24T12:00:00.000Z',
+    ...extra,
+});
+const ok = (r) => r.status >= 200 && r.status < 300;
+const msg = (r) => String(r.body?.message ?? '');
+const code = (r) => String(r.body?.code ?? '');
+/** Filed-gap helper (the `todo('<id>'…)` literal form scripts/pull-audit.ts greps for). */
+function todo(id, area, dimension, title, tier) {
+    return { id, area, title, dimension, expected: 'todo', tier };
+}
+const HAND_CAPABILITIES = [
+    // ── batch: the one route every official server SDK sends to ──────────────────────────────
+    {
+        id: 'segment.api.batch',
+        area: 'batch',
+        title: 'POST /v1/batch accepts the envelope @segment/analytics-node builds — {batch, writeKey, sentAt} — with a 2xx, and every message folds into twin state with its own type, ids, event/traits and properties',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            const res = await h('POST', '/v1/batch', flush([
+                { type: 'identify', userId: 'u_1', traits: { email: 'a@b.test', plan: 'pro' }, messageId: 'm_1', timestamp: '2026-08-24T11:59:00.000Z' },
+                { type: 'track', userId: 'u_1', event: 'Order Completed', properties: { revenue: 14.99 }, messageId: 'm_2' },
+            ]));
+            // The ONLY thing the pinned SDK reads off the response: `response.status >= 200 &&
+            // response.status < 300` (src/plugins/segmentio/publisher.ts). A 4xx here fails delivery.
+            if (!ok(res))
+                return false;
+            const feed = events(root);
+            if (feed.length !== 2)
+                return false;
+            const [first, second] = feed;
+            if (first?.messageType !== 'identify' || first.userId !== 'u_1' || first.messageId !== 'm_1')
+                return false;
+            // The caller's own `timestamp` survives, and the envelope's `sentAt` is carried onto each
+            // message (src/connections/spec/common.md '## Timestamps' — four distinct timestamps).
+            if (first.timestamp !== '2026-08-24T11:59:00.000Z' || first.sentAt !== '2026-08-24T12:00:00.000Z')
+                return false;
+            if (typeof first.receivedAt !== 'string')
+                return false;
+            if (second?.messageType !== 'track' || second.event !== 'Order Completed')
+                return false;
+            if (second.properties.revenue !== 14.99)
+                return false;
+            // …and the identify folded a projectable identity carrying its traits.
+            const who = identities(root).find((i) => i.id === 'u_1');
+            return who?.traits?.email === 'a@b.test';
+        }),
+    },
+    {
+        id: 'segment.api.batch.per_message_dispatch',
+        area: 'batch',
+        title: 'a MIXED batch is discriminated per MESSAGE by its own `type`, never by batch[0] — identify/track/group/page/alias in one flush each reach their own semantics, in either order, and none is lost or judged by its neighbour\'s rules',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            // Not a contrived input: `flushAt` defaults to 15 (src/app/analytics-node.ts), so an
+            // ordinary process flushes a heterogeneous array. Discriminating on batch[0] would route
+            // every later message through the first one's validation — the defect
+            // var/line/mixpanel/REVIEW.md F2 records for the sibling analytics pack.
+            const forward = await h('POST', '/v1/batch', flush([
+                { type: 'page', userId: 'u_2', name: 'Pricing', properties: { path: '/pricing' }, messageId: 'p_1' },
+                { type: 'identify', userId: 'u_2', traits: { plan: 'free' }, messageId: 'p_2' },
+                { type: 'group', userId: 'u_2', groupId: 'g_1', traits: { name: 'Initech' }, messageId: 'p_3' },
+            ]));
+            if (!ok(forward))
+                return false;
+            // A `group` message NOT first still created its group; an `identify` NOT first still
+            // created its identity; the `page` kept the page-only fields.
+            if (groups(root).find((g) => g.id === 'g_1')?.traits?.name !== 'Initech')
+                return false;
+            if (identities(root).find((i) => i.id === 'u_2')?.traits?.plan !== 'free')
+                return false;
+            if (events(root).find((e) => e.messageId === 'p_1')?.name !== 'Pricing')
+                return false;
+            // …and the reverse order: an identify FIRST must not make the twin judge the rest of the
+            // flush by identify's rules (a track has no traits; a page has no event name).
+            const reversed = await h('POST', '/v1/batch', flush([
+                { type: 'identify', userId: 'u_3', traits: { plan: 'pro' }, messageId: 'r_1' },
+                { type: 'track', userId: 'u_3', event: 'Signed Up', messageId: 'r_2' },
+                { type: 'alias', userId: 'u_3', previousId: 'anon_3', messageId: 'r_3' },
+            ]));
+            if (!ok(reversed))
+                return false;
+            if (!(identities(root).find((i) => i.id === 'u_3')?.previousIds ?? []).includes('anon_3'))
+                return false;
+            // Six messages across two flushes, every one of them in the feed, in order.
+            return events(root).map((e) => e.messageId).join(',') === 'p_1,p_2,p_3,r_1,r_2,r_3';
+        }),
+    },
+    {
+        id: 'segment.api.batch.envelope_merge',
+        area: 'batch',
+        title: 'batch-level `context` and `integrations` are MERGED into each message (the vendor\'s own words), with message-level keys winning — and the envelope\'s writeKey reaches every message',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'common',
+        verify: () => withRoot(async (h, root) => {
+            // http-api/index.md, the batch field table: context is "The same as Context for other
+            // calls, but it will be merged with any context inside each of the items in the batch",
+            // and integrations likewise.
+            const res = await h('POST', '/v1/batch', flush([
+                { type: 'track', userId: 'u_4', event: 'A', messageId: 'e_1', context: { locale: 'en-GB' } },
+                { type: 'track', userId: 'u_4', event: 'B', messageId: 'e_2' },
+            ], { context: { device: { type: 'phone' }, locale: 'en-US' }, integrations: { All: false, Mixpanel: true } }));
+            if (!ok(res))
+                return false;
+            const a = events(root).find((e) => e.messageId === 'e_1');
+            const b = events(root).find((e) => e.messageId === 'e_2');
+            const aCtx = a.context;
+            const bCtx = b.context;
+            // e_1 declared its own locale, so the message wins; the batch-level device still merges in.
+            if (aCtx.locale !== 'en-GB' || aCtx.device.type !== 'phone')
+                return false;
+            // e_2 declared nothing, so it inherits both batch-level keys.
+            if (bCtx.locale !== 'en-US' || bCtx.device.type !== 'phone')
+                return false;
+            if (a.integrations.Mixpanel !== true)
+                return false;
+            return a.writeKey === KEY && b.writeKey === KEY;
+        }),
+    },
+    {
+        id: 'segment.api.batch.unmodeled_type_fails_loudly',
+        area: 'batch',
+        title: 'a ratified-but-unmodeled message TYPE riding inside a modeled batch (`screen`) is refused BY NAME with nothing stored — it may not inherit /v1/batch\'s success, and a silent 200 storing nothing would be indistinguishable from acceptance',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            // `screen` is a type the UNMODIFIED SDK can put in an envelope: its SegmentEventType union
+            // is 'track'|'page'|'identify'|'alias'|'screen' (src/app/types/segment-event.ts) and
+            // Analytics.screen() produces one. So this is a real flush shape, not a synthetic probe.
+            await h('POST', '/v1/batch', flush([{ type: 'track', userId: 'u_5', event: 'Before', messageId: 'g_0' }]));
+            const before = events(root).length;
+            const res = await h('POST', '/v1/batch', flush([
+                { type: 'track', userId: 'u_5', event: 'Rides Along', messageId: 'g_1' },
+                { type: 'screen', userId: 'u_5', name: 'Home', messageId: 'g_2' },
+            ]));
+            if (res.status !== 404 || code(res) !== 'twin_gap')
+                return false;
+            if (!msg(res).includes('[twin gap]') || !msg(res).includes('screen'))
+                return false;
+            // NOTHING from the refused flush landed — not even the well-formed track beside it.
+            if (events(root).length !== before)
+                return false;
+            // …and the SAME type at its own ratified route earns the same named refusal.
+            const direct = await h('POST', '/v1/screen', { userId: 'u_5', name: 'Home', writeKey: KEY });
+            return direct.status === 404 && msg(direct).includes('[twin gap]') && msg(direct).includes('/v1/screen');
+        }),
+    },
+    {
+        id: 'segment.api.batch.event_cap',
+        area: 'batch',
+        title: 'the vendor\'s documented batch caps are enforced as ACCEPT-AND-DROP, not as a 4xx: past 2,500 events and past 32KB per batched event the request still answers 200 and the offending messages are simply not folded',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'common',
+        verify: () => withRoot(async (h, root) => {
+            // "Each batch request can only have up to 2500 events... Segment returns a 200 response
+            // but rejects the event when the number of batched events exceeds the limit."
+            const many = Array.from({ length: SEGMENT_MAX_BATCH_EVENTS + 2 }, (_, i) => ({
+                type: 'track', userId: 'u_6', event: 'Bulk', messageId: `cap_${i}`,
+            }));
+            const res = await h('POST', '/v1/batch', flush(many));
+            if (!ok(res))
+                return false; // a 400 here would be wrong: the vendor answers 200
+            if (events(root).length !== SEGMENT_MAX_BATCH_EVENTS)
+                return false;
+            const overflow = dropped(root).filter((d) => d.reason === 'batch_exceeds_2500_events');
+            if (overflow.length !== 2 || !overflow.some((d) => d.messageId === `cap_${SEGMENT_MAX_BATCH_EVENTS}`))
+                return false;
+            // "a limit of 32KB per event in the batch" — the OVERSIZE MEMBER is dropped while its
+            // well-formed batch-mate still lands, which is what makes this a per-event cap and not a
+            // per-request one.
+            const fat = { type: 'track', userId: 'u_6', event: 'Fat', messageId: 'fat_1', properties: { blob: 'x'.repeat(SEGMENT_MAX_REQUEST_BYTES + 1) } };
+            const mixed = await h('POST', '/v1/batch', flush([fat, { type: 'track', userId: 'u_6', event: 'Slim', messageId: 'slim_1' }]));
+            if (!ok(mixed))
+                return false;
+            if (events(root).some((e) => e.messageId === 'fat_1'))
+                return false;
+            if (!events(root).some((e) => e.messageId === 'slim_1'))
+                return false;
+            return dropped(root).some((d) => d.messageId === 'fat_1' && d.reason === 'event_exceeds_32kb');
+        }),
+    },
+    todo('segment.api.batch.success_body', 'batch', 'api', 'the BODY the vendor returns on an accepted request is undocumented on every first-party page, and no pinned client reads it (analytics-node@2 checks only `response.status >= 200 && < 300`; analytics-python returns the response unparsed on 200). This twin answers {"success": true}, which is a CHOICE, not a grounded claim — no capability asserts it. Settling it needs a real-account probe this station does not have', 'niche'),
+    // ── the direct per-type routes ────────────────────────────────────────────────────────────
+    {
+        id: 'segment.api.track',
+        area: 'track',
+        title: 'POST /v1/track folds an event with its name and properties, and answers 200 — including when the body states its own `type`, as the vendor\'s own OAuth example does',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            const res = await h('POST', '/v1/track', { userId: '019mr8mf4r', event: 'Item Purchased', properties: { name: 'Leap to Conclusions Mat', revenue: 14.99 }, context: { ip: '24.5.68.47' }, timestamp: '2012-12-02T00:30:12.984Z', writeKey: KEY });
+            if (!ok(res))
+                return false;
+            const [e] = events(root);
+            if (e?.messageType !== 'track' || e.event !== 'Item Purchased' || e.userId !== '019mr8mf4r')
+                return false;
+            if (e.properties.revenue !== 14.99)
+                return false;
+            if (e.context.ip !== '24.5.68.47')
+                return false;
+            // The direct route and the batched form must agree: this is the SAME body inside an
+            // envelope, and it has to fold identically rather than through a second code path.
+            await h('POST', '/v1/batch', flush([{ type: 'track', userId: '019mr8mf4r', event: 'Item Purchased', properties: { revenue: 14.99 }, messageId: 'same_1' }]));
+            const batched = events(root).find((x) => x.messageId === 'same_1');
+            return batched?.messageType === 'track' && batched.event === 'Item Purchased' && batched.endpoint === '/v1/batch' && e.endpoint === '/v1/track';
+        }),
+    },
+    {
+        id: 'segment.api.track.requires_event_name',
+        area: 'track',
+        title: '"All Track events sent to Segment must have an `event` field" — a nameless Track is ACCEPTED (200, as the vendor answers) and then dropped rather than folded, and the drop is attributable',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'common',
+        verify: () => withRoot(async (h, root) => {
+            const res = await h('POST', '/v1/track', { userId: 'u_7', properties: { a: 1 }, writeKey: KEY, messageId: 'noname_1' });
+            // The vendor's own rule: "Segment returns a 200 response for all API requests except
+            // errors caused by large payloads and JSON errors". A 4xx here would be infidelity.
+            if (res.status !== 200)
+                return false;
+            if (events(root).length !== 0)
+                return false;
+            return dropped(root).some((d) => d.messageId === 'noname_1' && d.reason === 'track_missing_event');
+        }),
+    },
+    {
+        id: 'segment.api.identify',
+        area: 'identify',
+        title: 'POST /v1/identify folds a user with its traits, and a LATER identify MERGES over the earlier one rather than replacing the profile — the deliberate dirty-state verify',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            // '## Identify': "Segment recommends calling Identify a single time when the user's
+            // account is first created, and only identifying again later when their traits change" —
+            // so a later call names only what changed and must not erase the rest.
+            await h('POST', '/v1/identify', { userId: 'pgibbons', traits: { email: 'pgibbons@example.com', name: 'Peter Gibbons', industry: 'Technology' }, writeKey: KEY, messageId: 'id_1' });
+            await h('POST', '/v1/identify', { userId: 'pgibbons', traits: { industry: 'Software' }, writeKey: KEY, messageId: 'id_2' });
+            // …and the same value written back at a later instant must not vanish into the kernel's
+            // content+millisecond dedupe (the `rev` ordinal in segment-twin.ts).
+            await h('POST', '/v1/identify', { userId: 'pgibbons', traits: { industry: 'Technology' }, writeKey: KEY, messageId: 'id_3' });
+            const who = identities(root).find((i) => i.id === 'pgibbons');
+            if (!who)
+                return false;
+            const traits = who.traits;
+            if (traits.industry !== 'Technology')
+                return false;
+            if (traits.email !== 'pgibbons@example.com' || traits.name !== 'Peter Gibbons')
+                return false;
+            if (Number(who.rev) !== 3)
+                return false;
+            return events(root).length === 3;
+        }),
+    },
+    {
+        id: 'segment.api.page',
+        area: 'page',
+        title: 'POST /v1/page folds a page view keeping the vendor\'s page-only fields (name, category, properties) — and a page is not a track: it carries no `event`',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            const res = await h('POST', '/v1/page', { userId: '019mr8mf4r', name: 'Tracking HTTP API', category: 'Docs', properties: { path: '/docs', url: 'https://example.test/docs' }, timestamp: '2012-12-02T00:31:29.738Z', writeKey: KEY, messageId: 'pg_1' });
+            if (!ok(res))
+                return false;
+            const p = events(root).find((e) => e.messageId === 'pg_1');
+            if (p?.messageType !== 'page' || p.name !== 'Tracking HTTP API' || p.category !== 'Docs')
+                return false;
+            if (p.properties.path !== '/docs')
+                return false;
+            if (p.event !== null)
+                return false;
+            // A page with no identifier at all is the documented accept-and-drop, not a fold.
+            await h('POST', '/v1/page', { name: 'Anonymous', writeKey: KEY, messageId: 'pg_2' });
+            return dropped(root).some((d) => d.messageId === 'pg_2' && d.reason === 'no_user_anon_id');
+        }),
+    },
+    {
+        id: 'segment.api.group',
+        area: 'group',
+        title: 'POST /v1/group folds a group with merged traits and its member users, and a group call with no `groupId` has nothing to group — accepted (200) and dropped',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            const res = await h('POST', '/v1/group', { userId: '019mr8mf4r', groupId: '8e9df332ac', traits: { name: 'Initech', industry: 'Technology', employees: 420 }, writeKey: KEY, messageId: 'gr_1' });
+            if (!ok(res))
+                return false;
+            const g = groups(root).find((x) => x.id === '8e9df332ac');
+            if (g?.traits?.employees !== 420)
+                return false;
+            if (!(g?.members ?? []).includes('019mr8mf4r'))
+                return false;
+            // A second member, and a trait update that must MERGE rather than replace.
+            await h('POST', '/v1/group', { userId: 'second_user', groupId: '8e9df332ac', traits: { employees: 500 }, writeKey: KEY, messageId: 'gr_2' });
+            const after = groups(root).find((x) => x.id === '8e9df332ac');
+            const traits = after.traits;
+            if (traits.employees !== 500 || traits.name !== 'Initech')
+                return false;
+            if (after.members.length !== 2)
+                return false;
+            const bad = await h('POST', '/v1/group', { userId: 'u_8', traits: { name: 'Nowhere' }, writeKey: KEY, messageId: 'gr_3' });
+            return bad.status === 200 && dropped(root).some((d) => d.messageId === 'gr_3' && d.reason === 'group_missing_group_id');
+        }),
+    },
+    {
+        id: 'segment.api.alias',
+        area: 'alias',
+        title: 'POST /v1/alias associates a `previousId` with a `userId`: the prior identity\'s traits carry forward, the link is projectable, and an alias with no previousId is accepted-and-dropped',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'common',
+        verify: () => withRoot(async (h, root) => {
+            // The dirty-state half: the anonymous user is identified FIRST, so aliasing has real
+            // prior state to carry rather than an empty subject.
+            await h('POST', '/v1/identify', { anonymousId: '39239-239239', traits: { plan: 'trial' }, writeKey: KEY, messageId: 'al_0' });
+            const res = await h('POST', '/v1/alias', { previousId: '39239-239239', userId: '019mr8mf4r', timestamp: '2012-12-02T00:31:29.738Z', writeKey: KEY, messageId: 'al_1' });
+            if (!ok(res))
+                return false;
+            const who = identities(root).find((i) => i.id === '019mr8mf4r');
+            if (!(who?.previousIds ?? []).includes('39239-239239'))
+                return false;
+            if (who?.traits?.plan !== 'trial')
+                return false;
+            // A second alias accumulates rather than replacing the first.
+            await h('POST', '/v1/alias', { previousId: 'anon_zzz', userId: '019mr8mf4r', writeKey: KEY, messageId: 'al_2' });
+            if ((identities(root).find((i) => i.id === '019mr8mf4r')?.previousIds ?? []).length !== 2)
+                return false;
+            const bad = await h('POST', '/v1/alias', { userId: 'u_9', writeKey: KEY, messageId: 'al_3' });
+            return bad.status === 200 && dropped(root).some((d) => d.messageId === 'al_3' && d.reason === 'alias_missing_previous_id');
+        }),
+    },
+    // ── auth: three documented schemes ────────────────────────────────────────────────────────
+    {
+        id: 'segment.api.auth.write_key_in_body',
+        area: 'auth',
+        title: 'the DEFAULT scheme — writeKey in the JSON body with NO Authorization header at all — is accepted, and the key that lands on each message is the envelope\'s. This is what the pinned SDK sends; a twin demanding a header could not be reached by it',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            // "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." And publisher.ts
+            // sets only Content-Type and User-Agent unless oauthSettings are configured.
+            const res = await h('POST', '/v1/batch', flush([{ type: 'track', userId: 'u_a', event: 'No Header', messageId: 'auth_1' }]));
+            if (!ok(res))
+                return false;
+            const e = events(root).find((x) => x.messageId === 'auth_1');
+            return e?.writeKey === KEY && e.authScheme === 'body';
+        }),
+    },
+    {
+        id: 'segment.api.auth.basic',
+        area: 'auth',
+        title: 'HTTP Basic with the write key as the USERNAME and an empty password resolves the key from the header — the analytics-node v1 wire shape (`auth: { username: writeKey }`), which sends no writeKey in the body at all',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'common',
+        verify: () => withRoot(async (h, root) => {
+            // "taking a Segment source Write Key, 'abc123', as the username, adding a colon, and then
+            // the password field is left empty. After base64 encoding 'abc123:' becomes 'YWJjMTIzOg=='".
+            // The literal below is that exact documented pair — a fixture the vendor itself printed.
+            const res = await h('POST', '/v1/batch', { batch: [{ type: 'track', userId: 'u_b', event: 'Basic', messageId: 'auth_2' }] }, 'Basic YWJjMTIzOg==');
+            if (!ok(res))
+                return false;
+            const e = events(root).find((x) => x.messageId === 'auth_2');
+            if (e?.writeKey !== 'abc123' || e.authScheme !== 'basic')
+                return false;
+            // The base64 carries UTF-8 BYTES: a write key above U+00FF must survive, which `atob`
+            // alone cannot do (it yields one JS char per byte) — the mixpanel F1 encoding class.
+            const uni = 'ключ_日本';
+            const header = `Basic ${Buffer.from(`${uni}:`, 'utf8').toString('base64')}`;
+            await h('POST', '/v1/batch', { batch: [{ type: 'track', userId: 'u_b', event: 'Unicode Key', messageId: 'auth_3' }] }, header);
+            return events(root).find((x) => x.messageId === 'auth_3')?.writeKey === uni;
+        }),
+    },
+    {
+        id: 'segment.api.auth.oauth_bearer_keeps_body_key',
+        area: 'auth',
+        title: 'under OAuth the Bearer token is a DIFFERENT credential from the write key: the header does not become the write key, and the payload\'s writeKey is still what identifies the source',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'common',
+        verify: () => withRoot(async (h, root) => {
+            // '#### OAuth': "Include the access token in the Authorization header as a Bearer token
+            // along with your project's write key in the payload of the request." publisher.ts does
+            // exactly that: `Authorization: Bearer ${token.access_token}` PLUS writeKey in the body.
+            const res = await h('POST', '/v1/batch', flush([{ type: 'track', userId: 'u_c', event: 'OAuth', messageId: 'auth_4' }]), 'Bearer an_access_token_not_a_write_key');
+            if (!ok(res))
+                return false;
+            const e = events(root).find((x) => x.messageId === 'auth_4');
+            // The bug this pins: treating the Bearer value as the credential would store the access
+            // token as the write key and lose the source identity entirely.
+            return e?.writeKey === KEY && e.authScheme === 'oauth';
+        }),
+    },
+    todo('segment.api.auth.rejects_unknown_write_key', 'auth', 'api', 'what the vendor answers for a MISSING or INVALID write key is documented nowhere first-party — the HTTP API page lists only oversize payloads and invalid JSON as 400 causes, and names no auth failure. This twin therefore accepts the request and records writeKey:null rather than inventing a refusal status or code', 'common'),
+    todo('segment.api.oauth_token', 'oauth', 'api', 'POST /token on oauth2.segment.io / oauth2.eu1.segmentapis.com — the client-credentials exchange the SDK\'s TokenManager drives (RS256 JWT client assertion, grant_type=client_credentials, scope tracking_api:write). Modeling it means real RS256 verification against a registered public key plus the 400/401/415/429 branches TokenManager treats as unrecoverable; not built in v1, and the route answers the loud gap', 'niche'),
+    // ── common fields the Spec defines for every call ─────────────────────────────────────────
+    {
+        id: 'segment.api.common.requires_an_identifier',
+        area: 'common',
+        title: '"The HTTP API requires that each payload has a userId and/or anonymousId" — a message with neither is ACCEPTED with 200 and dropped as `no_user_anon_id` (the vendor\'s own error name), and an anonymousId ALONE is sufficient',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            const none = await h('POST', '/v1/batch', flush([{ type: 'track', event: 'Homeless', messageId: 'c_1' }]));
+            if (none.status !== 200)
+                return false;
+            if (events(root).length !== 0)
+                return false;
+            if (!dropped(root).some((d) => d.messageId === 'c_1' && d.reason === 'no_user_anon_id'))
+                return false;
+            // …and the other half of "and/or": anonymousId alone is a legitimate identifier.
+            const anon = await h('POST', '/v1/batch', flush([{ type: 'track', anonymousId: '507f191e810c19729de860ea', event: 'Anonymous', messageId: 'c_2' }]));
+            if (!ok(anon))
+                return false;
+            const e = events(root).find((x) => x.messageId === 'c_2');
+            return e?.anonymousId === '507f191e810c19729de860ea' && e.userId === null;
+        }),
+    },
+    {
+        id: 'segment.api.common.message_id_dedupe',
+        area: 'common',
+        title: '"Segment deduplicates events using the messageId field" — a replayed messageId is accepted (200) and folded EXACTLY once, across separate requests and within one batch; a message that carries none gets one minted server-side, as the vendor does',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            // This is the retry path of every official SDK: `maxRetries` defaults to 3
+            // (src/app/analytics-node.ts) and a retried flush re-sends the same messageIds.
+            await h('POST', '/v1/batch', flush([{ type: 'track', userId: 'u_d', event: 'Once', messageId: 'dupe_1' }]));
+            const replay = await h('POST', '/v1/batch', flush([{ type: 'track', userId: 'u_d', event: 'Once Again', messageId: 'dupe_1' }]));
+            if (!ok(replay))
+                return false; // a retry is accepted, not refused
+            if (events(root).filter((e) => e.messageId === 'dupe_1').length !== 1)
+                return false;
+            if (events(root).find((e) => e.messageId === 'dupe_1').event !== 'Once')
+                return false;
+            // …and within ONE flush, which a per-request-only check would miss.
+            await h('POST', '/v1/batch', flush([
+                { type: 'track', userId: 'u_d', event: 'Inner A', messageId: 'dupe_2' },
+                { type: 'track', userId: 'u_d', event: 'Inner B', messageId: 'dupe_2' },
+            ]));
+            if (events(root).filter((e) => e.messageId === 'dupe_2').length !== 1)
+                return false;
+            // A message with NO messageId is still folded, with one minted for it — the vendor adds
+            // it server-side ("automatically added to all payloads coming into Segment"). Two such
+            // messages must not collide into one row.
+            await h('POST', '/v1/batch', flush([
+                { type: 'track', userId: 'u_d', event: 'Mintable' },
+                { type: 'track', userId: 'u_d', event: 'Mintable' },
+            ]));
+            const minted = events(root).filter((e) => e.event === 'Mintable');
+            return minted.length === 2 && minted[0].messageId !== minted[1].messageId && typeof minted[0].messageId === 'string';
+        }),
+    },
+    todo('segment.api.common.message_id_length', 'common', 'api', '"ensure all events have unique messageId values with fewer than 100 characters" — what the vendor does with a longer one (truncate, drop, ignore) is not stated on any first-party page, so this twin neither enforces nor rejects it rather than guessing a behaviour', 'niche'),
+    todo('segment.api.common.timestamp_skew_correction', 'common', 'api', 'Segment computes `timestamp = receivedAt - (sentAt - originalTimestamp)` server-side (src/connections/spec/common.md \'## Timestamps\'), and rewrites the caller\'s `timestamp` into `originalTimestamp`. This twin stores all of timestamp/sentAt/receivedAt faithfully but does NOT yet perform that arithmetic or mint originalTimestamp', 'common'),
+    todo('segment.api.common.context_direct_ip', 'common', 'api', '"When sending a HTTP call from a user\'s device, you can collect the IP address by setting context.direct to true" (\'## Collecting IP Address\'), i.e. the server fills context.ip from the connection. A local twin has no meaningful client IP to fill, so the flag is stored and otherwise ignored', 'niche'),
+    todo('segment.api.common.integrations_routing', 'common', 'api', 'the `integrations` object turns individual destinations on and off ("\'All\': false says that no destination should be enabled unless otherwise specified"), and Segment defaults it to {All: true, Salesforce: false}. This twin stores the object verbatim and merges batch-level over message-level, but models no destination fan-out, so the flags change nothing locally', 'common'),
+    todo('segment.api.common.event_property_cap', 'common', 'api', '"Events ingested by Segment have a limit of 10,000 properties per individual event received... Segment will not persist properties beyond this limit, and will drop any corresponding values" (src/connections/rate-limits.md, updated January 25, 2024). Not enforced by this twin', 'niche'),
+    // ── errors and limits ─────────────────────────────────────────────────────────────────────
+    {
+        id: 'segment.api.errors.envelope_and_400s',
+        area: 'errors',
+        title: 'the only two documented 400 causes — invalid JSON and an oversize payload — answer 400 with the vendor\'s {code, message} envelope, the shape analytics-python parses off every non-200; everything else the vendor accepts still answers 200',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            // "If you send an event with invalid JSON, Segment returns a 400 Bad Request error."
+            const badJson = await h('POST', '/v1/batch', '{"batch": [');
+            if (badJson.status !== 400)
+                return false;
+            const body = badJson.body;
+            // The SHAPE is grounded: analytics-python does
+            // `raise APIError(res.status_code, payload["code"], payload["message"])`.
+            if (typeof body.code !== 'string' || typeof body.message !== 'string')
+                return false;
+            if (badJson.headers?.['content-type'] !== 'application/json')
+                return false;
+            // "There is a maximum of 32KB per normal API request... Segment's API responds with
+            // 400 Bad Request if these limits are exceeded."
+            const fat = await h('POST', '/v1/track', { userId: 'u_e', event: 'Fat', properties: { blob: 'x'.repeat(SEGMENT_MAX_REQUEST_BYTES) }, writeKey: KEY });
+            if (fat.status !== 400 || typeof fat.body.code !== 'string')
+                return false;
+            // …and the SAME payload under /v1/batch's own 500KB cap is accepted, so the cap is really
+            // per-route and not one global number.
+            const inBatch = await h('POST', '/v1/batch', flush([{ type: 'track', userId: 'u_e', event: 'Fat But Batched', messageId: 'fat_ok', properties: { blob: 'x'.repeat(20 * 1024) } }]));
+            if (!ok(inBatch))
+                return false;
+            if (!events(root).some((e) => e.messageId === 'fat_ok'))
+                return false;
+            // A 500KB+ batch does cross its own cap.
+            const huge = await h('POST', '/v1/batch', flush([{ type: 'track', userId: 'u_e', event: 'Huge', properties: { blob: 'x'.repeat(600 * 1024) } }]));
+            return huge.status === 400;
+        }),
+    },
+    todo('segment.api.errors.code_vocabulary', 'errors', 'api', 'Segment publishes NO vocabulary of error `code` values. The only literal on a first-party page is `no_user_anon_id`; the shape {code, message} is grounded in analytics-python\'s parser but the strings this twin emits for invalid JSON / oversize payloads are descriptive placeholders, not vendor strings, and no capability asserts them. Settling this needs a real-account probe', 'common'),
+    todo('segment.api.limits.rate_limit_429', 'limits', 'api', '"Requests that exceed acceptable limits may be rejected with HTTP Status Code 429. When Segment rejects the requests, the response header contains Retry-After and X-RateLimit-Reset headers" — the SDK\'s Publisher reads x-ratelimit-reset and waits (publisher.ts:283-296). This twin never throttles and never emits a 429, so that whole SDK branch is unexercised; arming a deterministic 429 through a twin-only control route is the way in', 'common'),
+    todo('segment.api.limits.content_type_required', 'limits', 'api', '"To send data to Segment\'s HTTP API, a content-type header must be set to \'application/json\'" — what the vendor does when it is absent or wrong is not stated, so this twin parses the body regardless rather than inventing a refusal', 'niche'),
+    todo('segment.api.limits.gzipped_request_body', 'limits', 'api', 'Segment ACCEPTS a gzip-compressed ingestion body: the first-party analytics-python client sets `Content-Encoding: gzip` and posts the deflated bytes to /v1/batch (segment/analytics/request.py), exposed as the documented `gzip` Client argument ("`True` to compress data with gzip before sending, `False` by default" — segment-docs .../server/python/index.md). This twin reads the body as text and never decodes the encoding, so a gzip=True client gets a 400 `invalid_json` where the real vendor accepts. Verified against the booted server, A3. Off by default in every first-party client and absent from @segment/analytics-node@2 entirely, so it is filed rather than built', 'common'),
+    // ── regional ──────────────────────────────────────────────────────────────────────────────
+    todo('segment.api.regional.eu_endpoint', 'regional', 'api', 'EU workspaces send to events.eu1.segmentapis.com instead of api.segment.io ("If you are located in the EU and use the https://api.segment.io/v1/ endpoint, you might not see any errors, but your events will not appear in the Segment app"). Both hosts are routed to this twin by the injector, but the twin does not model the region as STATE — an EU-destined event is indistinguishable from a US one once it lands', 'common'),
+    // ── the routes ratified but not modeled ───────────────────────────────────────────────────
+    {
+        id: 'segment.api.fail_loudly',
+        area: 'conformance',
+        title: 'DELIBERATE DEVIATION (the real Segment answers 200 to these): every RATIFIED but unmodeled operation answers a LOUD vendor-shaped 404 naming the op, the deviation and its grounding — the mobile /v1/b, analytics.js\'s /v1/t, /v1/screen, the six Pixel Routes and the OAuth token exchange — and an endpoint outside the ratified surface answers a different, equally loud refusal',
+        dimension: 'api',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            // A deliberate deviation from the vendor's blanket 200, and it is the one deviation the
+            // twins bar REQUIRES: a 200 that stores nothing is indistinguishable from success.
+            // EVERY unmodeled op, not a sample of them: a list that stopped at the interesting ones
+            // would leave four ratified pixel routes claimed by a capability nothing exercised.
+            const unmodeled = [
+                ['POST', '/v1/b', 'mobile_batch'],
+                ['POST', '/v1/t', 'browser_track'],
+                ['POST', '/v1/screen', 'screen'],
+                ['GET', '/v1/pixel/track', 'pixel_track'],
+                ['GET', '/v1/pixel/identify', 'pixel_identify'],
+                ['GET', '/v1/pixel/page', 'pixel_page'],
+                ['GET', '/v1/pixel/screen', 'pixel_screen'],
+                ['GET', '/v1/pixel/group', 'pixel_group'],
+                ['GET', '/v1/pixel/alias', 'pixel_alias'],
+                ['POST', '/token', 'oauth_token'],
+            ];
+            // …and that list IS the ratified surface minus what SEMANTICS models — checked, not
+            // assumed, so a seventeenth ratified op cannot slip in unexercised.
+            if (unmodeled.length !== OPS.length - Object.keys(SEMANTICS).length)
+                return false;
+            for (const [method, path, id] of unmodeled) {
+                const res = await h(method, path, method === 'GET' ? undefined : { userId: 'u', writeKey: KEY });
+                if (res.status !== 404 || code(res) !== 'twin_gap')
+                    return false;
+                if (!msg(res).includes('[twin gap]') || !msg(res).includes(id) || !msg(res).includes(path))
+                    return false;
+                // The gap must carry the grounding, so a reader can tell a ratified gap from a typo…
+                if (!msg(res).includes('Grounding:'))
+                    return false;
+                // …and it must NAME the deviation, because the reader of this 404 is exactly the person
+                // who would otherwise conclude that the real Segment 404s here.
+                if (!msg(res).includes('DEVIATION: the real Segment answers 200'))
+                    return false;
+            }
+            // A path the surface never ratified is refused too — but as an UNKNOWN endpoint, not as a
+            // twin gap, so the two cases stay distinguishable on the wire.
+            const unknown = await h('POST', '/v1/pixel/nonsense', { userId: 'u' });
+            if (unknown.status !== 404 || code(unknown) !== 'unknown_endpoint')
+                return false;
+            // A modeled path with the WRONG method is not a modeled call either.
+            const wrongMethod = await h('GET', '/v1/batch');
+            if (wrongMethod.status !== 404 || code(wrongMethod) !== 'unknown_endpoint')
+                return false;
+            // …and none of that wrote anything.
+            return events(root).length === 0 && dropped(root).length === 0;
+        }),
+    },
+    // ── connector ─────────────────────────────────────────────────────────────────────────────
+    {
+        id: 'segment.connector.push',
+        area: 'connector',
+        title: 'push replays locally-ingested flushes onto the vendor\'s real POST /v1/batch through the INJECTED execute, rebuilding the SDK\'s own envelope (every message of the flush, `type` restored from the kernel-safe `messageType`), confirms an action only on a 2xx — and the flush SURVIVES its own confirm: every message, identity and group is still projectable afterwards',
+        dimension: 'connector',
+        expected: 'done',
+        tier: 'core',
+        verify: () => withRoot(async (h, root) => {
+            await h('POST', '/v1/batch', flush([
+                { type: 'identify', userId: 'u_push', traits: { plan: 'pro' }, messageId: 'push_1' },
+                { type: 'track', userId: 'u_push', event: 'Pushed Event', properties: { n: 1 }, messageId: 'push_2' },
+            ]));
+            const sent = [];
+            // A fake execute — the real network exists only inside liveSegmentExecute (D4/D5).
+            const okPush = await pushPendingSegmentActions(async (req) => { sent.push(req); return { status: 200, data: { success: true } }; }, { root });
+            if (okPush.pushed !== 1 || okPush.failed !== 0)
+                return false;
+            if (sent.length !== 1 || sent[0].method !== 'POST' || sent[0].path !== '/v1/batch')
+                return false;
+            const envelope = sent[0].body;
+            // THE WHOLE flush, not just its first message — reading action.fields alone would push
+            // one message and confirm the batch.
+            if (!Array.isArray(envelope.batch) || envelope.batch.length !== 2)
+                return false;
+            // `type` restored: the kernel's META set drops a field named `type`, so the twin stores
+            // `messageType` and the replay has to map it back or the vendor gets typeless messages.
+            if (envelope.batch[0].type !== 'identify' || envelope.batch[1].type !== 'track')
+                return false;
+            if (envelope.batch[1].event !== 'Pushed Event')
+                return false;
+            if (envelope.batch[0].traits.plan !== 'pro')
+                return false;
+            if (envelope.writeKey !== KEY)
+                return false;
+            // THE FLUSH SURVIVES ITS OWN CONFIRM. `projectResources` suppresses a confirmed action's
+            // projection and rebuilds that state from the observed events the confirm wrote
+            // (control-plane/src/actions.ts), so a confirm carrying only `action.fields` deletes every
+            // message after batch[0] — and the identity the flush folded — the moment it is pushed.
+            // Read AFTER the push, which is the only order that can see it.
+            if (events(root).map((e) => e.messageId).join(',') !== 'push_1,push_2')
+                return false;
+            if (identities(root).find((i) => i.id === 'u_push')?.traits?.plan !== 'pro')
+                return false;
+            // Confirmed, so it is no longer pending: a second push must send NOTHING.
+            const again = await pushPendingSegmentActions(async (req) => { sent.push(req); return { status: 200, data: null }; }, { root });
+            if (again.pushed !== 0 || sent.length !== 1)
+                return false;
+            // A NON-2xx is a refusal: the action stays pending rather than being silently confirmed.
+            await h('POST', '/v1/batch', flush([{ type: 'track', userId: 'u_push', event: 'Refused', messageId: 'push_3' }]));
+            const refused = await pushPendingSegmentActions(async () => ({ status: 400, data: { code: 'invalid_json', message: 'no' } }), { root });
+            if (refused.pushed !== 0 || refused.failed !== 1)
+                return false;
+            const retry = await pushPendingSegmentActions(async () => ({ status: 200, data: null }), { root });
+            if (retry.pushed !== 1)
+                return false;
+            // …and the LIVE execute — the only thing that ever reaches api.segment.io — stamps the
+            // write key where this vendor's default auth actually lives: INSIDE the envelope, with no
+            // Authorization header. Driven here through its own injected fetchImpl, so no network is
+            // touched. The S4 scaffold's `Bearer <SEGMENT_WRITE_KEY>` guess would authenticate nothing.
+            const seen = [];
+            const live = liveSegmentExecute({
+                apiKey: 'live_write_key',
+                budgetOptions: { path: join(root, 'budget.json') },
+                now: () => new Date('2026-08-24T12:34:56.000Z'),
+                fetchImpl: (async (url, init) => {
+                    seen.push({ url: String(url), init: init ?? {} });
+                    return new Response(JSON.stringify({ success: true }), { status: 200, headers: { 'content-type': 'application/json' } });
+                }),
+            });
+            const answer = await live({ method: 'POST', path: '/v1/batch', body: { batch: [{ type: 'track', userId: 'u', event: 'Unkeyed' }] } });
+            if (answer.status !== 200)
+                return false;
+            const wire = JSON.parse(String(seen[0].init.body));
+            if (wire.writeKey !== 'live_write_key' || wire.sentAt !== '2026-08-24T12:34:56.000Z')
+                return false;
+            if (seen[0].init.headers?.authorization !== undefined)
+                return false;
+            return seen[0].init.headers?.['content-type'] === 'application/json' && seen[0].url === 'https://api.segment.io/v1/batch';
+        }),
+    },
+    {
+        id: 'segment.connector.pull_is_impossible_not_empty',
+        area: 'connector',
+        title: 'syncSegmentFromReal folds NOTHING and says so — every one of the sixteen ratified ops is a WRITE, so there is no read-back to mirror; the pull must not fabricate an empty account over real observed state, and must not disturb what is already there',
+        dimension: 'connector',
+        expected: 'done',
+        tier: 'common',
+        verify: () => withRoot(async (h, root) => {
+            await h('POST', '/v1/batch', flush([{ type: 'track', userId: 'u_p', event: 'Local', messageId: 'pull_1' }]));
+            const before = events(root).length;
+            // The injected execute must never be CALLED: a v1 pull that reached the vendor would be
+            // spending a live allowance to learn nothing.
+            let calls = 0;
+            const result = await syncSegmentFromReal(async () => { calls += 1; return { status: 200, data: null }; }, { root });
+            if (result.pulled !== 0 || calls !== 0)
+                return false;
+            // ADDING_A_TWIN §6: a connector that maps "no read path" to "an empty account" hands
+            // syncPull an empty account to fold OVER real observed state. Nothing may vanish.
+            if (events(root).length !== before)
+                return false;
+            return events(root).some((e) => e.messageId === 'pull_1');
+        }),
+    },
+    todo('segment.connector.pull', 'connector', 'api', 'pull real-account state: Segment\'s tracking plane exposes NO read-back operation — its own answer to "did my event land" is the browser Source Debugger, a live websocket view, not an API. The nearest read surface is the Profile API on profiles.segment.com behind an Engage access token (HTTP Basic username) in a different product tier, and it returns resolved profiles, never the raw ingested events this twin folds. v1 therefore mirrors nothing rather than faking an empty account', 'common'),
+    // ── surface the Spec declares that this twin stores but does not INTERPRET ────────────────
+    todo('segment.api.identify.reserved_traits', 'identify', 'api', "the Spec reserves seventeen identify traits with defined types and meanings (src/connections/spec/identify.md: address, age, avatar, birthday, company, createdAt, description, email, firstName, gender, id, lastName, name, phone, title, username, website), and Segment DERIVES from them — \"If you only pass a first and last name, Segment automatically fills in the full name for you.\" This twin stores the traits object verbatim and performs no derivation and no type checking", 'common'),
+    todo('segment.api.group.reserved_traits', 'group', 'api', 'the Spec reserves twelve group traits (src/connections/spec/group.md: address, avatar, createdAt, description, email, employees, id, industry, name, phone, website, plan). This twin merges the traits object verbatim and neither validates their types nor treats any of them specially', 'niche'),
+    todo('segment.api.pixel.always_200_gif', 'pixel', 'api', "the Pixel API's defining contract: \"Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs\", with the payload in a base64 `?data=` blob OR plain query parameters (the base64 \"is optional, however it prevents special character interpretation\"). Modeling it means a GET decoder, real GIF BYTES on the wire and a response that can never be a JSON error — including never this twin's own loud gap. Today all six pixel routes answer the gap instead", 'niche'),
+    todo('segment.api.track.spec_event_vocabularies', 'track', 'api', "the Segment Spec's third component — the industry event vocabularies Segment maps to destination features (E-Commerce, Mobile, Video, B2B SaaS, AI Copilot) and the cloud-source specs (Email, Live Chat, A/B Testing), each with reserved event names and property shapes. Real vendor contract, entirely uninterpreted here: this twin accepts any `event` string with any properties", 'niche'),
+    todo('segment.api.regional.custom_domain', 'regional', 'api', "Segment-Managed Custom Domain moves the whole tracking surface onto a customer subdomain — \"modify the endpoint from Segment's default domain (https://api.segment.io/v1/pixel/track) to your custom domain (https://api.mysubdomain.mydomain.com/v1/pixel/track)\" (src/connections/sources/custom-domain.md), with server sources using `host` and mobile sources `apiHost`. The twin serves the paths on whatever host it is pointed at, but the injector host map claims only the two Segment-owned tracking hosts, so a custom-domain SDK's traffic would not be intercepted", 'niche'),
+    todo('segment.api.common.version_field', 'common', 'api', "`version` is one of the ten common fields on every call (src/connections/spec/common.md's structure block shows `\"version\": 2`). This twin neither reads it nor stamps one, so a caller pinning a payload version gets no different behaviour", 'niche'),
+    // ── the mirror this vendor is owed ────────────────────────────────────────────────────────
+    // THE SOURCE DEBUGGER. The screen the vendor tells you to open when an event returns 200 and
+    // never arrives — and the reason it cannot be an API capability is that this API is WRITE-ONLY:
+    // all sixteen ratified operations are ingests and none of them reads a message back. So the
+    // mirror reads the twin's OWN store door (`GET /twin/store/{events,dropped}`), the kernel's
+    // read-only named-projection door.
+    //
+    // ONE capability, not two. A §9 review was right that a second id over the store door would be
+    // DENOMINATOR PADDING: §6 names a twin-only route as scaffolding that must stay out of the
+    // manifest, and the door, its 404 and its determinism all predate this screen and are already
+    // graded by the R9 replay and R5c. So the door assertions belong HERE, where they are not a
+    // coverage claim but the proof that the screen's data path is the twin's real one — read over a
+    // REAL SOCKET, because a verify that only looks in-process is structurally unable to see what a
+    // browser is served (the azure `data: [DONE]` class).
+    {
+        id: 'segment.ui.debugger',
+        area: 'mirror',
+        title: 'The Source Debugger: the live accepted/dropped stream read over the RUNNING mirror\'s own store door and rendered by the mirror\'s real components — an event sent through the tracking API appears with its type, label, subject and properties, and a message the vendor would silently drop appears with its REASON',
+        dimension: 'ui',
+        expected: 'done',
+        tier: 'core',
+        verify: async () => await withMirrorRoot(async (fetchOrigin, h, root) => {
+            // (1) the BUILT bundle carries the debugger's static literal markers. Template-literal
+            //     class names would be erased by the minifier, which is why PILL_CLASS is a table.
+            const js = await mirrorBundle();
+            if (!['Source Debugger', 'event-row', 'dropped-row', 'pill pill-track', 'pill pill-dropped', 'drop-reason'].every((m) => js.includes(m)))
+                return false;
+            // (2) seed through the twin's OWN write path — the vendor's real route, not a hand-built
+            //     log. One message that is ACCEPTED, one the vendor silently drops (no userId and no
+            //     anonymousId is the vendor's own documented `no_user_anon_id`).
+            const sent = await h('POST', '/v1/batch', flush([
+                { type: 'track', userId: 'u_debug', event: 'Order Completed', properties: { revenue: 14.99, currency: 'USD' }, messageId: 'm_ok' },
+                { type: 'track', event: 'Orphan Event', messageId: 'm_drop' },
+            ]));
+            if (!ok(sent))
+                return false;
+            // (3) read them back THE WAY THE BROWSER DOES — over the wire, off the running mirror's
+            //     store door, on the same origin the ingest route was served on. The bytes must equal
+            //     the in-process projection: the door is the projection, not a second copy.
+            const accepted = (await (await fetchOrigin('/twin/store/events')).json());
+            const refused = (await (await fetchOrigin('/twin/store/dropped')).json());
+            if (JSON.stringify(accepted) !== JSON.stringify(events(root)))
+                return false;
+            if (JSON.stringify(refused) !== JSON.stringify(dropped(root)))
+                return false;
+            if (accepted.length !== 1 || refused.length !== 1)
+                return false;
+            if (accepted[0].event !== 'Order Completed' || refused[0].messageId !== 'm_drop')
+                return false;
+            // ...and the SHELL comes off that same origin, so screen and data cannot drift onto two
+            // ports — which is the only thing that makes "the browser sees this" true.
+            const shell = await fetchOrigin('/');
+            // the shell loads the bundle relative to its <base> (the hosted mirror mounts it under a path), and it is served
+            if (shell.status !== 200 || !(await shell.text()).includes('src="assets/app.js"') || (await fetchOrigin('/assets/app.js')).status !== 200)
+                return false;
+            // (4) render the mirror's OWN exported components over those fetched rows and assert the
+            //     seeded values survive into the emitted markup. This is the claim about the SHIPPED
+            //     component, not a lookalike.
+            const acceptedMarkup = renderToStaticMarkup(createElement(EventRow, { row: accepted[0] }));
+            const droppedMarkup = renderToStaticMarkup(createElement(DroppedRow, { row: refused[0] }));
+            return (acceptedMarkup.includes('event-row') &&
+                acceptedMarkup.includes('pill pill-track') &&
+                acceptedMarkup.includes('Order Completed') &&
+                acceptedMarkup.includes('u_debug') &&
+                acceptedMarkup.includes('revenue') && acceptedMarkup.includes('14.99') &&
+                acceptedMarkup.includes('currency') && acceptedMarkup.includes('USD') &&
+                droppedMarkup.includes('dropped-row') &&
+                droppedMarkup.includes('pill pill-dropped') &&
+                droppedMarkup.includes(String(refused[0].reason)) &&
+                droppedMarkup.includes('drop-reason') &&
+                // ...and the two rows are not the SAME markup with a different string in it: each
+                // carries the landmarks of its own stream and NEITHER of the other's. The negative half
+                // was half-vacuous before (§9) — a `DroppedRow` that rendered nothing satisfied it —
+                // so both directions now assert a landmark that must be PRESENT as well as one absent.
+                !acceptedMarkup.includes('pill pill-dropped') && !acceptedMarkup.includes('drop-reason') &&
+                !droppedMarkup.includes('pill pill-track') && !droppedMarkup.includes('u_debug'));
+        }),
+    },
+    todo('segment.ui.connections', 'mirror', 'ui', 'the Connections screen — sources wired to destinations, which is the vendor\'s core browser job and the thing its Public API also manages. Unmodeled: this pack twins the ingestion plane only', 'common'),
+    todo('segment.ui.profiles', 'mirror', 'ui', 'a user/group explorer over the identity and group projections identify/group calls fold', 'common'),
+];
+const HAND_IDS = new Set(HAND_CAPABILITIES.map((c) => c.id));
+// Generated inventory minus any op the hand file supersedes (each earned done replaces its
+// generated todo — matched by capability id).
+const generated = GENERATED_CAPABILITIES.filter((c) => !HAND_IDS.has(c.id));
+export const SEGMENT_CAPABILITIES = [...HAND_CAPABILITIES, ...generated];
+/** Committed area census (TWIN-87/F1), enumerated TOP-DOWN from the vendor's own documentation
+ *  nav rather than from this manifest. The nine op areas are the ones SURFACE.json ratified
+ *  (batch, track, identify, page, screen, group, alias, pixel, oauth); `auth`, `common`, `errors`,
+ *  `limits` and `regional` are the H2 sections of the vendor's HTTP Tracking API page that carry
+ *  behaviour rather than routes ('### Authentication', the Spec's common fields, '## Errors',
+ *  '## Rate limits' + '## Max request size', '## Regional configuration'); `conformance`,
+ *  `connector` and `mirror` are this pack's structural areas. A regeneration that DROPS an area
+ *  reddens the census test instead of silently shrinking the denominator. */
+export const SEGMENT_AREAS = [
+    'alias',
+    'auth',
+    'batch',
+    'common',
+    'conformance',
+    'connector',
+    'errors',
+    'group',
+    'identify',
+    'limits',
+    'mirror',
+    'oauth',
+    'page',
+    'pixel',
+    'regional',
+    'screen',
+    'track',
+];
+export function segmentCapabilities() {
+    return checkCapabilities('segment', SEGMENT_CAPABILITIES);
+}