@volter/twin-segment 0.1.0

package/dist/src/segment-twin.js

@@ -0,0 +1,543 @@
+// Segment twin — SEMANTICS registry + THE request loop. The generated surface
+// (segment-surface.gen.ts) is data + pure helpers only; every judgment lives here, grounded in
+// the pinned SDK tarball and the vendor's own docs source (both cited per claim below).
+// Unknown route → vendor-shaped 404; a ratified but unmodeled operation → LOUD gap, never a
+// fake success. Flip a capability in segment-capabilities.ts only with a real verify().
+//
+// ── WHAT THE UNMODIFIED SDK ACTUALLY SENDS ───────────────────────────────────────────────────
+// @segment/analytics-node@2.3.0 has SIX typed call methods (track/identify/page/screen/group/
+// alias, src/app/analytics-node.ts) and exactly ONE wire route. Its Publisher fixes the URL in
+// its constructor — `tryCreateFormattedUrl(host ?? 'https://api.segment.io', path ?? '/v1/batch')`
+// (src/plugins/segmentio/publisher.ts:73-76) — and every send POSTs that same URL with
+//   JSON.stringify({ batch: events, writeKey: this._writeKey, sentAt: new Date() })   (:243-247)
+// so a batch is a LIST OF INDEPENDENT MESSAGES, each carrying its OWN `type`. Dispatch is
+// therefore PER MESSAGE. Discriminating on `batch[0]` would silently mis-route or lose every
+// message after the first, which is the defect var/line/mixpanel/REVIEW.md F2 records for the
+// sibling analytics pack — and it is not a corner case here either: `flushAt` defaults to 15
+// (src/app/analytics-node.ts), so an ordinary process flushes a mixed identify/track/page array.
+//
+// ── AUTH: THREE DOCUMENTED SCHEMES, AND `Bearer <writeKey>` IS NONE OF THEM ───────────────────
+// segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '### Authentication':
+//   1. writeKey IN THE BODY, no auth header at all ("For this auth type, you do not need to set
+//      any authentication header"). This is what analytics-node@2 and analytics-python send.
+//   2. HTTP Basic with the write key as the USERNAME and an EMPTY password — "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=='". This is what
+//      analytics-node v1 sends (`auth: { username: this.writeKey }`).
+//   3. OAuth `Authorization: Bearer <access token>` PLUS the write key still in the payload.
+// A twin that DEMANDED an Authorization header could not be reached by the pinned SDK at all.
+// (Ruled: var/line/segment/RULINGS.json, denominator:auth-is-three-documented-schemes-not-one.)
+//
+// ── WHAT SEGMENT ANSWERS ─────────────────────────────────────────────────────────────────────
+// "Segment returns a 200 response for all API requests except errors caused by large payloads
+// and JSON errors (which return 400 responses.)" (same page, '## Errors'). Events can therefore
+// be ACCEPTED-AND-DROPPED: a payload with neither userId nor anonymousId gets a `no_user_anon_id`
+// error, a Track with no `event` field is rejected, and a batch over 2500 events gets "a 200
+// response but rejects the event". This twin reproduces that exactly — 200, nothing folded into
+// `event`, and the drop recorded in a local `dropped` projection so the outcome is inspectable
+// (twin state, not vendor surface). The 400 body shape is `{code, message}`, grounded in the
+// first-party parser analytics-python uses: `raise APIError(res.status_code, payload["code"],
+// payload["message"])` (segment/analytics/request.py).
+import { applyTwinWriteAtomic, projectResources, worldNow } from '@volter/world-core';
+import { OPS, matchOp } from "./segment-surface.gen.js";
+const SERVICE = 'segment';
+const rows = (root) => projectResources(SERVICE, root);
+/** Every accepted message, oldest-first by ingestion ordinal. One row per Segment `messageId`. */
+export function events(root) {
+    return rows(root).filter((r) => r.type === 'event').sort((a, b) => Number(a.seq ?? 0) - Number(b.seq ?? 0));
+}
+/** Users as identify (and alias) have folded them: merged traits + the ids they answer to. */
+export function identities(root) {
+    return rows(root).filter((r) => r.type === 'identity');
+}
+/** Groups as `group` calls have folded them: merged group traits. */
+export function groups(root) {
+    return rows(root).filter((r) => r.type === 'group');
+}
+/** Messages the vendor ACCEPTS (200) and then drops. Twin-local observability, not vendor surface. */
+export function dropped(root) {
+    return rows(root).filter((r) => r.type === 'dropped').sort((a, b) => Number(a.seq ?? 0) - Number(b.seq ?? 0));
+}
+// ── vendor error envelope ───────────────────────────────────────────────────────────────────
+/** Segment's error body. The SHAPE is grounded — analytics-python reads `payload["code"]` and
+ *  `payload["message"]` off any non-200 (segment/analytics/request.py) — but the vendor
+ *  publishes no vocabulary of `code` VALUES. The single documented literal is
+ *  `no_user_anon_id` (http-api/index.md '## Errors'); every other code below is descriptive and
+ *  is NOT claimed to be the vendor's own string. The gap is filed as
+ *  segment.api.errors.code_vocabulary and no capability asserts a code the vendor never printed. */
+export const segmentError = (status, code, message) => ({
+    status,
+    body: { code, message },
+    headers: { 'content-type': 'application/json' },
+});
+// ── limits, as the vendor publishes them ────────────────────────────────────────────────────
+// '## Max request size': "There is a maximum of 32KB per normal API request. The batch API
+// endpoint accepts a maximum of 500KB per request, with a limit of 32KB per event in the batch...
+// Segment's API responds with 400 Bad Request if these limits are exceeded."
+// '## Errors': "Each batch request can only have up to 2500 events".
+export const SEGMENT_MAX_REQUEST_BYTES = 32 * 1024;
+export const SEGMENT_MAX_BATCH_BYTES = 500 * 1024;
+export const SEGMENT_MAX_BATCH_EVENTS = 2500;
+const byteLength = (s) => new TextEncoder().encode(s).length;
+/** Resolve the write key from whichever of the three documented schemes the caller used.
+ *  The BODY wins when it carries a writeKey, because the docs' OAuth example keeps the writeKey
+ *  in the payload while the header carries a different credential entirely; Basic is consulted
+ *  only when the body has none, which is exactly the analytics-node v1 shape. */
+export function resolveWriteKey(authorization, body) {
+    const header = (authorization ?? '').trim();
+    const bodyKey = body && typeof body === 'object' && typeof body.writeKey === 'string'
+        ? body.writeKey
+        : null;
+    if (/^basic /i.test(header)) {
+        // "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=='".
+        // Decoded as UTF-8 BYTES, not latin-1: `atob` alone yields one JS char per byte and mangles
+        // any non-ASCII credential (the var/line/mixpanel/REVIEW.md F1 class).
+        let decoded;
+        try {
+            const rawB64 = header.slice(6).trim();
+            decoded = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(atob(rawB64), (c) => c.charCodeAt(0)));
+        }
+        catch {
+            decoded = undefined;
+        }
+        const username = decoded?.split(':')[0];
+        if (username)
+            return { writeKey: bodyKey ?? username, scheme: bodyKey ? 'body' : 'basic', bearer: null };
+        return { writeKey: bodyKey, scheme: bodyKey ? 'body' : 'none', bearer: null };
+    }
+    if (/^bearer /i.test(header)) {
+        // OAuth: the access token is the header, the write key stays in the payload.
+        return { writeKey: bodyKey, scheme: 'oauth', bearer: header.slice(7).trim() || null };
+    }
+    return { writeKey: bodyKey, scheme: bodyKey ? 'body' : 'none', bearer: null };
+}
+const str = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
+const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+/** The five message types this twin models, plus the one it ratifies and refuses BY NAME.
+ *  The union is the SDK's own: `type SegmentEventType = 'track' | 'page' | 'identify' | 'alias'
+ *  | 'screen'` (src/app/types/segment-event.ts) widened with 'group', which the SDK's
+ *  `Analytics.group()` produces through CoreEventFactory. */
+export const MODELED_TYPES = ['track', 'identify', 'page', 'group', 'alias'];
+/** Ratified in SURFACE.json, deliberately not modeled: it earns the loud gap by name. */
+export const UNMODELED_TYPES = ['screen'];
+// ── validation, only where the vendor states the requirement in prose ───────────────────────
+/** "The HTTP API requires that each payload has a userId and/or anonymousId. If you send events
+ *  without either the userId or anonymousId, Segment's tracking API responds with an
+ *  no_user_anon_id error." (http-api/index.md '## Errors') */
+function dropReasonFor(msg, type) {
+    if (!str(msg.userId) && !str(msg.anonymousId))
+        return 'no_user_anon_id';
+    // "All Track events sent to Segment must have an `event` field."
+    if (type === 'track' && !str(msg.event))
+        return 'track_missing_event';
+    // '## Group' field table declares groupId; a group call with nothing to group is not a group.
+    if (type === 'group' && !str(msg.groupId))
+        return 'group_missing_group_id';
+    // '## Alias' field table declares previousId; the SDK's AliasParams requires it too.
+    if (type === 'alias' && !str(msg.previousId))
+        return 'alias_missing_previous_id';
+    return undefined;
+}
+// ── ids and ordinals ────────────────────────────────────────────────────────────────────────
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist. */
+function stableHex(seed, n) {
+    let out = '';
+    for (let round = 0; out.length < n; round += 1) {
+        let h = 0x811c9dc5;
+        const s = `${round}:${seed}`;
+        for (let i = 0; i < s.length; i += 1) {
+            h ^= s.charCodeAt(i);
+            h = Math.imul(h, 0x01000193) >>> 0;
+        }
+        out += h.toString(16).padStart(8, '0');
+    }
+    return out.slice(0, n);
+}
+/** The vendor's own dedupe key when the caller supplied one, a DERIVED uuid otherwise. Segment
+ *  mints this server-side too — "Segment deduplicates events using the messageId field, which is
+ *  automatically added to all payloads coming into Segment" — so a hand-rolled HTTP call with no
+ *  messageId still gets one.
+ *
+ *  It was `crypto.randomUUID()`, which made the stored feed differ byte-for-byte between two
+ *  identical worlds — invisible while this twin had no read surface, and a real R9 break the
+ *  moment the store doors opened. Still NEVER a module counter or a row count (ADDING_A_TWIN §5);
+ *  it is a HASH over the world instant, the flush's ingestion ordinal and the message's own
+ *  position in it, so it is unique per message, uniform over the id space, and identical across
+ *  identical worlds. */
+const messageIdOf = (msg, at, ordinal) => {
+    const supplied = str(msg.messageId);
+    if (supplied)
+        return supplied;
+    const hex = stableHex(`message:${at}:${ordinal}`, 32);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+};
+/** A strictly-increasing per-type ordinal read out of CURRENT state. It orders the feed AND makes
+ *  each write's content unique, so the kernel's content+millisecond dedupe can never mistake a
+ *  genuine repeat for a replay (ADDING_A_TWIN §5) — Segment BILLS per event, so two identical
+ *  events in one millisecond must both land. */
+const nextSeq = (resources, type) => resources.reduce((n, r) => (r.type === type ? Math.max(n, Number(r.seq ?? 0)) : n), 0) + 1;
+function eventFieldsFor(msg, type, env, endpoint, messageId, seq, receivedAt) {
+    // MERGE: "The same as Context for other calls, but it will be merged with any context inside
+    // each of the items in the batch" — and likewise for `integrations` (http-api/index.md, the
+    // batch field table). Message-level keys win over batch-level ones.
+    return {
+        // `type` is META-reserved by the kernel — see the docblock above.
+        messageType: type,
+        messageId,
+        endpoint,
+        userId: str(msg.userId) ?? null,
+        anonymousId: str(msg.anonymousId) ?? null,
+        writeKey: env.writeKey,
+        authScheme: env.scheme,
+        event: str(msg.event) ?? null,
+        name: str(msg.name) ?? null,
+        category: str(msg.category) ?? null,
+        groupId: str(msg.groupId) ?? null,
+        previousId: str(msg.previousId) ?? null,
+        properties: obj(msg.properties) ?? null,
+        traits: obj(msg.traits) ?? null,
+        context: { ...(env.context ?? {}), ...(obj(msg.context) ?? {}) },
+        integrations: { ...(env.integrations ?? {}), ...(obj(msg.integrations) ?? {}) },
+        // Four timestamps, per src/connections/spec/common.md '## Timestamps'. `timestamp` is the
+        // caller's (or the SDK's `new Date()`); `sentAt` rides on the envelope; `receivedAt` is
+        // "added to incoming messages as soon as they hit the API", i.e. server-set, here.
+        timestamp: typeof msg.timestamp === 'string' ? msg.timestamp : null,
+        sentAt: env.sentAt,
+        receivedAt,
+        seq,
+    };
+}
+/** Fold one validated message into the in-flight create list, merging over BOTH committed state
+ *  and anything an earlier message of the SAME request already produced (two identify calls for
+ *  one user in one flush must accumulate, not clobber). */
+function foldOne(msg, type, env, endpoint, ctx) {
+    // Always present: the caller mints it (or takes the caller's) before folding.
+    const messageId = str(msg.messageId);
+    const userId = str(msg.userId) ?? null;
+    const anonymousId = str(msg.anonymousId) ?? null;
+    const subject = userId ?? anonymousId;
+    const out = [];
+    ctx.seq.event += 1;
+    const eventFields = eventFieldsFor(msg, type, env, endpoint, messageId, ctx.seq.event, ctx.receivedAt);
+    out.push({ type: 'event', id: messageId, fields: eventFields });
+    /** Current fields for a subject: this request's pending version first, then committed state. */
+    const currentOf = (kind, id) => ctx.pending.get(`${kind}:${id}`)?.fields ??
+        ctx.resources.find((r) => r.type === kind && r.id === id);
+    if (type === 'identify') {
+        // '## 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." Later traits
+        // MERGE over earlier ones rather than replacing the profile.
+        const current = currentOf('identity', subject);
+        out.push({
+            type: 'identity',
+            id: subject,
+            fields: {
+                userId,
+                anonymousId: anonymousId ?? current?.anonymousId ?? null,
+                traits: { ...(obj(current?.traits) ?? {}), ...(obj(msg.traits) ?? {}) },
+                previousIds: current?.previousIds ?? [],
+                // A per-write ordinal: re-setting a trait to a value it previously held inside one
+                // millisecond would otherwise hash-collide with the earlier action and be dropped as
+                // `replayed` (ADDING_A_TWIN §5, the upstash class).
+                rev: Number(current?.rev ?? 0) + 1,
+            },
+        });
+    }
+    else if (type === 'group') {
+        const groupId = str(msg.groupId);
+        const current = currentOf('group', groupId);
+        out.push({
+            type: 'group',
+            id: groupId,
+            fields: {
+                groupId,
+                traits: { ...(obj(current?.traits) ?? {}), ...(obj(msg.traits) ?? {}) },
+                members: [...new Set([...(current?.members ?? []), subject])],
+                rev: Number(current?.rev ?? 0) + 1,
+            },
+        });
+    }
+    else if (type === 'alias') {
+        // '## Alias': "Alias is how you associate one identity with another" — previousId (a userId
+        // OR an anonymousId) becomes reachable as the new userId.
+        const previousId = str(msg.previousId);
+        const target = userId ?? subject;
+        const current = currentOf('identity', target);
+        const prior = currentOf('identity', previousId);
+        out.push({
+            type: 'identity',
+            id: target,
+            fields: {
+                userId: target,
+                anonymousId: current?.anonymousId ?? null,
+                // Aliasing carries the prior identity's traits forward for keys the target lacks; the
+                // target's own values win.
+                traits: { ...(obj(prior?.traits) ?? {}), ...(obj(current?.traits) ?? {}) },
+                previousIds: [...new Set([...(current?.previousIds ?? []), previousId])],
+                rev: Number(current?.rev ?? 0) + 1,
+            },
+        });
+    }
+    for (const c of out)
+        ctx.pending.set(`${c.type}:${c.id}`, c);
+    return out;
+}
+// ── the shared ingest path ──────────────────────────────────────────────────────────────────
+/** THE per-message dispatcher. Every route funnels through it, so `/v1/batch`, `/v1/track` and
+ *  their siblings can never disagree about what a message means.
+ *
+ *  Two refusal modes, and the difference is deliberate:
+ *   • a DOCUMENTED rejection (no identifier, Track without a name, an over-cap or oversize
+ *     batch member) is ACCEPTED-AND-DROPPED — 200, nothing folded into `event` — because that is
+ *     what Segment does: "Segment returns a 200 response for all API requests except errors
+ *     caused by large payloads and JSON errors", and its list of silently-rejected events names
+ *     exactly these cases;
+ *   • a message whose `type` this twin has RATIFIED but not MODELED (today: `screen`) fails
+ *     LOUDLY by name and the WHOLE payload is refused with nothing stored. That is a deliberate
+ *     deviation from the vendor's 200 (ruled:
+ *     denominator:200-for-nearly-everything-so-the-twin-gap-is-a-deliberate-deviation): a silent
+ *     200 storing nothing is indistinguishable from success, which is the one thing a twin may
+ *     never do. Validation of every message therefore precedes ANY fold. */
+export async function ingest(env, endpoint, root, at) {
+    const plan = [];
+    const drops = [];
+    for (const [index, entry] of env.messages.entries()) {
+        const msg = obj(entry);
+        if (!msg) {
+            return segmentError(400, 'invalid_message', `batch[${index}] is not an object — each batch item must be a Segment message`);
+        }
+        // "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."
+        if (env.batched && index >= SEGMENT_MAX_BATCH_EVENTS) {
+            drops.push({ msg, type: str(msg.type) ?? '', reason: 'batch_exceeds_2500_events' });
+            continue;
+        }
+        // "a limit of 32KB per event in the batch".
+        if (env.batched && byteLength(JSON.stringify(msg)) > SEGMENT_MAX_REQUEST_BYTES) {
+            drops.push({ msg, type: str(msg.type) ?? '', reason: 'event_exceeds_32kb' });
+            continue;
+        }
+        const type = str(msg.type);
+        if (!type) {
+            // The batch field table: "Each call must have an `type` property with a valid method name."
+            drops.push({ msg, type: '', reason: 'unknown_message_type' });
+            continue;
+        }
+        if (UNMODELED_TYPES.includes(type))
+            return gapForType(type, endpoint);
+        if (!MODELED_TYPES.includes(type)) {
+            drops.push({ msg, type, reason: 'unknown_message_type' });
+            continue;
+        }
+        const reason = dropReasonFor(msg, type);
+        if (reason)
+            drops.push({ msg, type, reason });
+        else
+            plan.push({ msg, type: type });
+    }
+    if (plan.length) {
+        // The WORLD instant, never wall time: `receivedAt` is STORED on every event row and served
+        // through the store door, so a `new Date()` here made the feed differ across worlds (R9).
+        const receivedAt = at;
+        await applyTwinWriteAtomic(SERVICE, (resources) => {
+            // "Segment deduplicates events using the messageId field" (http-api/index.md '## Errors').
+            // Checked under the same cross-process action lock the write takes, so two concurrent
+            // flushes of the same messageId cannot both pass it — and within one request too, so a
+            // batch that repeats a messageId folds it once.
+            const seen = new Set(resources.filter((r) => r.type === 'event').map((r) => r.id));
+            const ctx = {
+                resources,
+                pending: new Map(),
+                seq: { event: nextSeq(resources, 'event') - 1 },
+                receivedAt,
+            };
+            const creates = [];
+            let deduped = 0;
+            for (const { msg, type } of plan) {
+                // Minted INSIDE the lock, from the ordinal `foldOne` is about to assign this message:
+                // the same state snapshot the write lands on, so the id is unique per message with no
+                // entropy and no wall clock (R9).
+                const messageId = messageIdOf(msg, at, ctx.seq.event + 1);
+                if (seen.has(messageId)) {
+                    deduped += 1;
+                    continue;
+                }
+                seen.add(messageId);
+                creates.push(...foldOne({ ...msg, messageId }, type, env, endpoint, ctx));
+            }
+            // Later creates for the same subject supersede earlier ones (the kernel applies them in
+            // order and merges, but collapsing here keeps the action's projection minimal and makes
+            // the batch's net effect on each subject legible in one place).
+            const collapsed = [...new Map(creates.map((c) => [`${c.type}:${c.id}`, c])).values()];
+            const eventCreates = creates.filter((c) => c.type === 'event');
+            if (!eventCreates.length)
+                return { kind: 'skip', value: { stored: 0, deduped } };
+            const primary = eventCreates[0];
+            return {
+                kind: 'write',
+                value: { stored: eventCreates.length, deduped },
+                write: {
+                    // ONE ACTION PER FLUSH — see the "folding a request" docblock. `operation` names the
+                    // route rather than a single message type, because a batch is heterogeneous.
+                    operation: `ingest.${endpoint.replace(/^\/+/, '').replace(/\//g, '.')}`,
+                    subjectType: 'event',
+                    subjectId: primary.id,
+                    // The WORLD instant, never the kernel's wall-clock default: it lands on every row as
+                    // `updatedAt`, which the store doors serve (R9).
+                    occurredAt: at,
+                    fields: primary.fields,
+                    projection: { creates: collapsed },
+                    actor: { kind: 'agent' },
+                    // Every accepted flush is a BILLED occurrence, not an idempotent state write: two
+                    // byte-identical flushes in one millisecond must ledger as two actions. The messageIds
+                    // are what make them distinguishable, and a truly identical replay is already caught
+                    // by the messageId dedupe above.
+                    uniqueness: `${primary.id}:${eventCreates.length}`,
+                },
+            };
+        }, root);
+    }
+    if (drops.length) {
+        // Dropped messages never enter the event feed, so they have no ingestion ordinal of their
+        // own — they mint from a DISJOINT ordinal space (negative) so a drop's derived id can never
+        // collide with an accepted message's.
+        const dropCreates = drops.map((d, i) => ({ msg: d.msg, type: d.type, reason: d.reason, messageId: messageIdOf(d.msg, at, -(i + 1)) }));
+        await applyTwinWriteAtomic(SERVICE, (resources) => {
+            let seq = nextSeq(resources, 'dropped') - 1;
+            const creates = dropCreates.map((d) => {
+                seq += 1;
+                return {
+                    type: 'dropped',
+                    id: `drop_${d.messageId}`,
+                    fields: { messageType: d.type, messageId: d.messageId, endpoint, reason: d.reason, seq },
+                };
+            });
+            const primary = creates[0];
+            return {
+                kind: 'write',
+                value: null,
+                write: {
+                    operation: 'drop.messages',
+                    subjectType: 'dropped',
+                    subjectId: primary.id,
+                    occurredAt: at, // the WORLD instant (R9) — see the accepted-flush write above
+                    fields: primary.fields,
+                    projection: { creates },
+                    actor: { kind: 'agent' },
+                    uniqueness: `${primary.id}:${creates.length}`,
+                },
+            };
+        }, root);
+    }
+    // 200 is what the vendor answers for everything it did not refuse outright. The BODY is not
+    // documented on any 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) — so `{success:true}` is this twin's choice, filed as segment.api.batch.success_body
+    // and asserted by no capability.
+    return { status: 200, body: { success: true }, headers: { 'content-type': 'application/json' } };
+}
+/** The loud gap for a ratified-but-unmodeled MESSAGE TYPE inside an otherwise-modeled route. */
+function gapForType(type, endpoint) {
+    const op = OPS.find((o) => o.id === type);
+    return segmentError(404, 'twin_gap', `[twin gap] message type '${type}' (arriving at ${endpoint}${op ? `; ratified as ${op.method} ${op.path}` : ''}) is in the segment twin's ratified surface but is not yet modeled — the whole payload was refused and nothing was stored. DEVIATION: the real Segment answers 200 here and silently drops the message; that is indistinguishable from acceptance, so this twin refuses instead`);
+}
+/** The loud gap for a ratified-but-unmodeled OPERATION (a whole route). The reader of this 404 is
+ *  the one person who most needs to know it is a DEVIATION, so the body says so: the real vendor
+ *  would answer 200 here (and then drop the event), which is precisely why the twin may not. */
+function gap(op) {
+    return segmentError(404, 'twin_gap', `[twin gap] ${op.method} ${op.path} (${op.id}) is in the segment twin's ratified surface but not yet modeled — failing loudly instead of faking success. DEVIATION: the real Segment answers 200 to this request; a 200 that stores nothing is indistinguishable from acceptance, so this twin refuses instead. Grounding: ${op.evidence.slice(0, 120)}`);
+}
+// ── SEMANTICS ───────────────────────────────────────────────────────────────────────────────
+// One entry per DEMANDED op (var/line/segment/DEMAND.json, measured in
+// var/line/segment/DEMAND-EVIDENCE.json). Every handler receives the decoded envelope as `body`.
+const direct = (type) => async ({ op, body, root, occurredAt }) => {
+    const env = body;
+    // THE ROUTE WINS, and that is the safer of two undocumented readings. The vendor's own worked
+    // examples carry the matching "type" in the payload ('#### OAuth' posts {"type": "track"} to
+    // /v1/track) and it never says what a DISAGREEING type means. Letting the body decide would
+    // mean a `{"type": "group", "groupId": …}` body posted to /v1/track silently folds a group
+    // from the track endpoint — a payload field redirecting an addressed operation. The endpoint
+    // is the operation the caller addressed, so it names the type.
+    const messages = env.messages.map((m) => ({ ...m, type }));
+    return ingest({ ...env, messages }, op.path, root, occurredAt);
+};
+export const SEMANTICS = {
+    // POST /v1/batch — the one route every official server SDK sends to. Per-MESSAGE dispatch.
+    batch: async ({ op, body, root, occurredAt }) => ingest(body, op.path, root, occurredAt),
+    // The direct per-type routes the vendor's HTTP Tracking API documents. Same folding path as a
+    // batched message of that type, by construction.
+    track: direct('track'),
+    identify: direct('identify'),
+    page: direct('page'),
+    group: direct('group'),
+    alias: direct('alias'),
+};
+// ── the request loop ────────────────────────────────────────────────────────────────────────
+/** Decode a request body into the shared envelope. `/v1/batch` carries `{batch: [...]}`; a
+ *  direct route carries ONE message at the top level, with the writeKey alongside it. */
+export function decodeEnvelope(parsed, auth, isBatchRoute) {
+    const rootObj = obj(parsed);
+    if (!rootObj)
+        return undefined;
+    if (isBatchRoute) {
+        if (!Array.isArray(rootObj.batch))
+            return undefined;
+        return {
+            messages: rootObj.batch,
+            context: obj(rootObj.context),
+            integrations: obj(rootObj.integrations),
+            writeKey: auth.writeKey,
+            scheme: auth.scheme,
+            sentAt: str(rootObj.sentAt) ?? null,
+            batched: true,
+        };
+    }
+    return {
+        messages: [rootObj],
+        context: undefined,
+        integrations: undefined,
+        writeKey: auth.writeKey,
+        scheme: auth.scheme,
+        sentAt: str(rootObj.sentAt) ?? null,
+        batched: false,
+    };
+}
+export async function handleSegmentTwinRequest(req) {
+    const url = new URL(req.path, 'http://twin.local');
+    const match = matchOp({ method: req.method, path: url.pathname + url.search, body: req.body });
+    if (!match) {
+        return segmentError(404, 'unknown_endpoint', `unknown endpoint: ${req.method.toUpperCase()} ${url.pathname} — not an operation in the segment twin's ratified surface (var/line/segment/SURFACE.json)`);
+    }
+    const { op } = match;
+    const handler = SEMANTICS[op.id];
+    if (!handler)
+        return gap(op);
+    const raw = req.body ?? '';
+    const size = byteLength(raw);
+    const isBatchRoute = op.id === 'batch';
+    // "There is a maximum of 32KB per normal API request. The batch API endpoint accepts a maximum
+    // of 500KB per request... Segment's API responds with 400 Bad Request if these limits are
+    // exceeded." Checked on the RAW BYTES before parsing: an oversize body must not be parsed at all.
+    const cap = isBatchRoute ? SEGMENT_MAX_BATCH_BYTES : SEGMENT_MAX_REQUEST_BYTES;
+    if (size > cap) {
+        return segmentError(400, 'payload_too_large', `payload of ${size} bytes exceeds the ${cap}-byte maximum for ${op.method} ${op.path}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // "If you send an event with invalid JSON, Segment returns a 400 Bad Request error."
+        return segmentError(400, 'invalid_json', 'request body is not valid JSON');
+    }
+    const auth = resolveWriteKey(req.authorization, parsed);
+    const env = decodeEnvelope(parsed, auth, isBatchRoute);
+    if (!env) {
+        return segmentError(400, 'invalid_payload', isBatchRoute
+            ? 'POST /v1/batch requires a JSON object with a `batch` ARRAY of messages'
+            : `${op.method} ${op.path} requires a single JSON message object`);
+    }
+    // The serve path's only clock: the WORLD instant (R9 pins it as state), never wall time.
+    return handler({ op, params: match.params, query: match.query, body: env, root: req.root, occurredAt: req.occurredAt ?? worldNow() });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@volter/twin-segment",
+  "version": "0.1.0",
+  "description": "Local Segment twin - the HTTP Tracking API (POST /v1/batch and the direct /v1/{track,identify,page,screen,group,alias} routes) modeled over kernel state, so an unmodified @segment/analytics-node client round-trips offline. Built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/segment"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/segment#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-segment": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@segment/analytics-node": "^2.3.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { optionValue } from '@volter/world-core/args';
+import { createSegmentTwinServer } from './segment-server.ts';
+import { OPS } from './segment-surface.gen.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === 'serve') {
+  const port = Number(optionValue(rest, '--port', '0')) || undefined;
+  const root = optionValue(rest, '--root') || process.env.VOLTER_STATE_DIR;
+  const server = await createSegmentTwinServer({ port, root });
+  console.log(`segment twin listening on ${server.url}`);
+} else if (cmd === 'mirror') {
+  // The Source Debugger, and the tracking API behind it, on ONE origin — the screen and its data
+  // cannot drift onto different ports.
+  const { createSegmentMirrorServer } = await import('./segment-mirror-ui.ts');
+  const port = Number(optionValue(rest, '--port', '0')) || undefined;
+  const root = optionValue(rest, '--root') || process.env.VOLTER_STATE_DIR;
+  const server = await createSegmentMirrorServer({ port, root });
+  console.log(`segment Source Debugger + tracking API listening on http://127.0.0.1:${server.port}`);
+} else if (cmd === 'conformance') {
+  // Lazily imported so the dev-only conformance module never enters the runtime entrypoint graph.
+  const { checkSegmentConformance } = await import('./segment-conformance.ts');
+  const report = await checkSegmentConformance({ root: process.env.VOLTER_STATE_DIR });
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(report.ok ? 0 : 1);
+} else if (cmd === 'ops') {
+  for (const op of OPS) console.log(`${op.method.padEnd(6)} ${op.path}  [${op.id}]`);
+} else {
+  console.log('usage: world-segment serve [--port N] [--root DIR] | mirror [--port N] [--root DIR] | conformance | ops');
+}