@volter/twin-segment 0.1.0

package/dist/client/segment-mirror.css

@@ -0,0 +1,45 @@
+:root {
+  --bg: #0f1115;
+  --panel: #171a21;
+  --line: #262b35;
+  --text: #e6e9ef;
+  --muted: #9aa4b2;
+  --accent: #292929;
+  --track: #52bd94;
+  --identity: #6aa9f0;
+  --screenish: #b98cf0;
+  --dropped: #d24b4b;
+}
+* { box-sizing: border-box; }
+body { margin: 0; font-family: -apple-system, system-ui, sans-serif; background: var(--bg); color: var(--text); }
+.app { max-width: 1040px; margin: 0 auto; padding: 0 20px 32px; }
+.app-header { display: flex; align-items: center; justify-content: space-between; height: 60px; border-bottom: 1px solid var(--line); }
+.app-title { font-size: 18px; font-weight: 700; margin: 0; letter-spacing: 0.02em; }
+.counts { display: flex; gap: 14px; font-size: 13px; color: var(--muted); font-variant-numeric: tabular-nums; }
+.count-dropped { color: var(--dropped); }
+.app-nav { display: flex; gap: 6px; padding: 14px 0; }
+.nav-item { background: none; border: 1px solid transparent; color: var(--muted); padding: 7px 14px; border-radius: 999px; cursor: pointer; font-size: 14px; }
+.nav-item:hover { color: var(--text); }
+.nav-item-active { background: var(--accent); border-color: var(--line); color: var(--text); }
+.event-stream, .dropped-stream { list-style: none; margin: 0; padding: 0; background: var(--panel); border: 1px solid var(--line); border-radius: 10px; overflow: hidden; }
+.event-row, .dropped-row { padding: 12px 14px; border-bottom: 1px solid var(--line); }
+.event-row:last-child, .dropped-row:last-child { border-bottom: none; }
+.event-head { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+.event-clock { color: var(--muted); font-size: 12px; font-variant-numeric: tabular-nums; }
+.event-label { font-weight: 600; font-size: 14px; }
+.event-subject, .drop-endpoint { color: var(--muted); font-size: 12px; margin-left: auto; }
+.drop-reason { color: var(--dropped); font-size: 13px; }
+.drop-reason-twin { font-size: 11px; color: var(--muted); border: 1px dashed var(--line); border-radius: 4px; padding: 1px 6px; }
+.stream-note { color: var(--muted); font-size: 12px; margin: 0 0 10px; }
+.stream-note code { color: var(--text); }
+.pill { padding: 3px 10px; border-radius: 999px; font-size: 12px; white-space: nowrap; }
+.pill-track { background: rgba(82,189,148,0.18); color: var(--track); }
+.pill-identity { background: rgba(106,169,240,0.18); color: var(--identity); }
+.pill-screenish { background: rgba(185,140,240,0.18); color: var(--screenish); }
+.pill-dropped { background: rgba(210,75,75,0.18); color: var(--dropped); }
+.chips { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
+.chips-empty { color: var(--muted); font-size: 12px; }
+.chip { display: inline-flex; gap: 6px; background: var(--bg); border: 1px solid var(--line); border-radius: 6px; padding: 3px 8px; font-size: 12px; }
+.chip-key { color: var(--muted); }
+.chip-value { font-variant-numeric: tabular-nums; }
+.empty { color: var(--muted); padding: 24px; background: var(--panel); border: 1px solid var(--line); border-radius: 10px; }

package/dist/client/segment-mirror.d.ts

@@ -0,0 +1,34 @@
+import { type SegmentRow } from '../src/segment-mirror-ui.js';
+/** Read one named projection off the twin's store door. */
+export declare function store(name: string): Promise<SegmentRow[]>;
+/** The property/trait chips on an expanded row — what a debugger reader is actually looking for
+ *  when an event "arrived but is wrong". */
+export declare function PropertyChips({ row }: {
+    row: SegmentRow;
+}): import("react").JSX.Element;
+/** One row of the accepted stream. */
+export declare function EventRow({ row }: {
+    row: SegmentRow;
+}): import("react").JSX.Element;
+/**
+ * One row of the dropped stream.
+ *
+ * THIS PANE IS THE TWIN'S, NOT THE VENDOR'S, and the screen says so. Segment's real Source
+ * Debugger shows what a source RECEIVED; it has no "accepted-then-silently-dropped, with a reason"
+ * view, because the vendor answers 200 and discards. This twin records the refusal instead, which
+ * is the only way "returned 200 and never arrived" becomes observable — a superset of the vendor's
+ * screen, and the honest label for it. Only `no_user_anon_id` is a reason Segment itself prints
+ * (its Errors page); the other six are this pack's own descriptive strings, which is why the row
+ * marks them.
+ */
+export declare function DroppedRow({ row }: {
+    row: SegmentRow;
+}): import("react").JSX.Element;
+/** The accepted stream, newest last (the order the source received them). */
+export declare function EventStream({ rows }: {
+    rows: SegmentRow[];
+}): import("react").JSX.Element;
+/** The dropped stream. */
+export declare function DroppedStream({ rows }: {
+    rows: SegmentRow[];
+}): import("react").JSX.Element;

package/dist/client/segment-mirror.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Segment mirror — the SOURCE DEBUGGER, as a React/TSX client. Every byte on screen is fetched
+// from the twin's OWN store door on the same origin (`/twin/store/events`, `/twin/store/dropped`)
+// — the kernel's read-only named-projection door, and the sanctioned way a mirror reads twin
+// state. API↔UI parity: this is the projection the ingest routes fold into, not a second copy.
+import { createRoot } from 'react-dom/client';
+import { useEffect, useState } from 'react';
+import { PILL_CLASS, clockLabel, messageLabel, propertyChips, subjectOf, typeTone, } from "../src/segment-mirror-ui.js";
+// WHERE THIS MIRROR LIVES. Served at a vendor root the base is '' (fetches are root-relative, as
+// before); served under a path prefix with a <base> tag every read and write resolves inside that
+// prefix instead of escaping it.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+const STREAMS = [
+    { key: 'events', label: 'Accepted' },
+    { key: 'dropped', label: 'Dropped' },
+];
+/** Read one named projection off the twin's store door. */
+export async function store(name) {
+    const res = await fetch(`${WIRE_BASE}/twin/store/${name}`);
+    if (!res.ok)
+        return [];
+    const body = (await res.json());
+    return Array.isArray(body) ? body : [];
+}
+/** The property/trait chips on an expanded row — what a debugger reader is actually looking for
+ *  when an event "arrived but is wrong". */
+export function PropertyChips({ row }) {
+    const chips = [...propertyChips(row.properties), ...propertyChips(row.traits)];
+    if (chips.length === 0)
+        return _jsx("div", { className: "chips chips-empty", children: "no properties" });
+    return (_jsx("div", { className: "chips", children: chips.map((c) => (_jsxs("span", { className: "chip", children: [_jsx("span", { className: "chip-key", children: c.key }), _jsx("span", { className: "chip-value", children: c.value })] }, c.key))) }));
+}
+/** One row of the accepted stream. */
+export function EventRow({ row }) {
+    const tone = typeTone(row.messageType);
+    return (_jsxs("li", { className: "event-row", "data-message-id": String(row.messageId ?? ''), children: [_jsxs("div", { className: "event-head", children: [_jsx("span", { className: "event-clock", children: clockLabel(row.receivedAt) }), _jsx("span", { className: PILL_CLASS[tone], children: String(row.messageType ?? '') }), _jsx("span", { className: "event-label", children: messageLabel(row) }), _jsx("span", { className: "event-subject", children: subjectOf(row) })] }), _jsx(PropertyChips, { row: row })] }));
+}
+/**
+ * One row of the dropped stream.
+ *
+ * THIS PANE IS THE TWIN'S, NOT THE VENDOR'S, and the screen says so. Segment's real Source
+ * Debugger shows what a source RECEIVED; it has no "accepted-then-silently-dropped, with a reason"
+ * view, because the vendor answers 200 and discards. This twin records the refusal instead, which
+ * is the only way "returned 200 and never arrived" becomes observable — a superset of the vendor's
+ * screen, and the honest label for it. Only `no_user_anon_id` is a reason Segment itself prints
+ * (its Errors page); the other six are this pack's own descriptive strings, which is why the row
+ * marks them.
+ */
+export function DroppedRow({ row }) {
+    return (_jsx("li", { className: "dropped-row", "data-message-id": String(row.messageId ?? ''), children: _jsxs("div", { className: "event-head", children: [_jsx("span", { className: PILL_CLASS.dropped, children: "dropped" }), _jsx("span", { className: "event-label", children: String(row.messageType ?? '') }), _jsx("span", { className: "drop-reason", children: String(row.reason ?? 'unknown') }), String(row.reason ?? '') === 'no_user_anon_id'
+                    ? null
+                    : _jsx("span", { className: "drop-reason-twin", title: "This reason is a twin-authored label. Segment prints only `no_user_anon_id`.", children: "twin label" }), _jsx("span", { className: "drop-endpoint", children: String(row.endpoint ?? '') })] }) }));
+}
+/** The accepted stream, newest last (the order the source received them). */
+export function EventStream({ rows }) {
+    if (rows.length === 0)
+        return _jsx("div", { className: "empty", children: "No events yet. Send one and it appears here." });
+    return _jsx("ul", { className: "event-stream", children: rows.map((r) => _jsx(EventRow, { row: r }, String(r.messageId))) });
+}
+/** The dropped stream. */
+export function DroppedStream({ rows }) {
+    if (rows.length === 0)
+        return _jsx("div", { className: "empty", children: "Nothing dropped. Every message this source received was attributed." });
+    return (_jsxs(_Fragment, { children: [_jsxs("p", { className: "stream-note", children: ["Segment answers 200 and discards these; the twin records them. Only ", _jsx("code", { children: "no_user_anon_id" }), " is a reason Segment itself prints \u2014 the rest carry a ", _jsx("span", { className: "drop-reason-twin", children: "twin label" }), "."] }), _jsx("ul", { className: "dropped-stream", children: rows.map((r) => _jsx(DroppedRow, { row: r }, String(r.messageId))) })] }));
+}
+function App() {
+    const [stream, setStream] = useState('events');
+    const [events, setEvents] = useState([]);
+    const [dropped, setDropped] = useState([]);
+    useEffect(() => {
+        void (async () => {
+            setEvents(await store('events'));
+            setDropped(await store('dropped'));
+        })();
+    }, []);
+    return (_jsxs("main", { className: "app", children: [_jsxs("header", { className: "app-header", children: [_jsx("h1", { className: "app-title", children: "Source Debugger" }), _jsxs("span", { className: "counts", children: [_jsxs("span", { className: "count-accepted", "data-count": events.length, children: [events.length, " accepted"] }), _jsxs("span", { className: "count-dropped", "data-count": dropped.length, children: [dropped.length, " dropped"] })] })] }), _jsx("nav", { className: "app-nav", children: STREAMS.map((s) => (_jsx("button", { className: stream === s.key ? 'nav-item nav-item-active' : 'nav-item', onClick: () => setStream(s.key), children: s.label }, s.key))) }), stream === 'events' ? _jsx(EventStream, { rows: events }) : _jsx(DroppedStream, { rows: dropped })] }));
+}
+const mount = typeof document === 'undefined' ? null : document.getElementById('root');
+if (mount)
+    createRoot(mount).render(_jsx(App, {}));

package/dist/client/segment-mirror.tsx

@@ -0,0 +1,154 @@
+// Segment mirror — the SOURCE DEBUGGER, as a React/TSX client. Every byte on screen is fetched
+// from the twin's OWN store door on the same origin (`/twin/store/events`, `/twin/store/dropped`)
+// — the kernel's read-only named-projection door, and the sanctioned way a mirror reads twin
+// state. API↔UI parity: this is the projection the ingest routes fold into, not a second copy.
+import { createRoot } from 'react-dom/client';
+import { useEffect, useState } from 'react';
+import {
+  PILL_CLASS,
+  clockLabel,
+  messageLabel,
+  propertyChips,
+  subjectOf,
+  typeTone,
+  type SegmentRow,
+} from '../src/segment-mirror-ui.ts';
+
+// WHERE THIS MIRROR LIVES. Served at a vendor root the base is '' (fetches are root-relative, as
+// before); served under a path prefix with a <base> tag every read and write resolves inside that
+// prefix instead of escaping it.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+
+const STREAMS = [
+  { key: 'events', label: 'Accepted' },
+  { key: 'dropped', label: 'Dropped' },
+] as const;
+type StreamKey = (typeof STREAMS)[number]['key'];
+
+/** Read one named projection off the twin's store door. */
+export async function store(name: string): Promise<SegmentRow[]> {
+  const res = await fetch(`${WIRE_BASE}/twin/store/${name}`);
+  if (!res.ok) return [];
+  const body = (await res.json()) as unknown;
+  return Array.isArray(body) ? (body as SegmentRow[]) : [];
+}
+
+/** The property/trait chips on an expanded row — what a debugger reader is actually looking for
+ *  when an event "arrived but is wrong". */
+export function PropertyChips({ row }: { row: SegmentRow }) {
+  const chips = [...propertyChips(row.properties), ...propertyChips(row.traits)];
+  if (chips.length === 0) return <div className="chips chips-empty">no properties</div>;
+  return (
+    <div className="chips">
+      {chips.map((c) => (
+        <span className="chip" key={c.key}>
+          <span className="chip-key">{c.key}</span>
+          <span className="chip-value">{c.value}</span>
+        </span>
+      ))}
+    </div>
+  );
+}
+
+/** One row of the accepted stream. */
+export function EventRow({ row }: { row: SegmentRow }) {
+  const tone = typeTone(row.messageType);
+  return (
+    <li className="event-row" data-message-id={String(row.messageId ?? '')}>
+      <div className="event-head">
+        <span className="event-clock">{clockLabel(row.receivedAt)}</span>
+        <span className={PILL_CLASS[tone]}>{String(row.messageType ?? '')}</span>
+        <span className="event-label">{messageLabel(row)}</span>
+        <span className="event-subject">{subjectOf(row)}</span>
+      </div>
+      <PropertyChips row={row} />
+    </li>
+  );
+}
+
+/**
+ * One row of the dropped stream.
+ *
+ * THIS PANE IS THE TWIN'S, NOT THE VENDOR'S, and the screen says so. Segment's real Source
+ * Debugger shows what a source RECEIVED; it has no "accepted-then-silently-dropped, with a reason"
+ * view, because the vendor answers 200 and discards. This twin records the refusal instead, which
+ * is the only way "returned 200 and never arrived" becomes observable — a superset of the vendor's
+ * screen, and the honest label for it. Only `no_user_anon_id` is a reason Segment itself prints
+ * (its Errors page); the other six are this pack's own descriptive strings, which is why the row
+ * marks them.
+ */
+export function DroppedRow({ row }: { row: SegmentRow }) {
+  return (
+    <li className="dropped-row" data-message-id={String(row.messageId ?? '')}>
+      <div className="event-head">
+        <span className={PILL_CLASS.dropped}>dropped</span>
+        <span className="event-label">{String(row.messageType ?? '')}</span>
+        <span className="drop-reason">{String(row.reason ?? 'unknown')}</span>
+        {String(row.reason ?? '') === 'no_user_anon_id'
+          ? null
+          : <span className="drop-reason-twin" title="This reason is a twin-authored label. Segment prints only `no_user_anon_id`.">twin label</span>}
+        <span className="drop-endpoint">{String(row.endpoint ?? '')}</span>
+      </div>
+    </li>
+  );
+}
+
+/** The accepted stream, newest last (the order the source received them). */
+export function EventStream({ rows }: { rows: SegmentRow[] }) {
+  if (rows.length === 0) return <div className="empty">No events yet. Send one and it appears here.</div>;
+  return <ul className="event-stream">{rows.map((r) => <EventRow row={r} key={String(r.messageId)} />)}</ul>;
+}
+
+/** The dropped stream. */
+export function DroppedStream({ rows }: { rows: SegmentRow[] }) {
+  if (rows.length === 0) return <div className="empty">Nothing dropped. Every message this source received was attributed.</div>;
+  return (
+    <>
+      <p className="stream-note">
+        Segment answers 200 and discards these; the twin records them. Only <code>no_user_anon_id</code> is
+        a reason Segment itself prints — the rest carry a <span className="drop-reason-twin">twin label</span>.
+      </p>
+      <ul className="dropped-stream">{rows.map((r) => <DroppedRow row={r} key={String(r.messageId)} />)}</ul>
+    </>
+  );
+}
+
+function App() {
+  const [stream, setStream] = useState<StreamKey>('events');
+  const [events, setEvents] = useState<SegmentRow[]>([]);
+  const [dropped, setDropped] = useState<SegmentRow[]>([]);
+
+  useEffect(() => {
+    void (async () => {
+      setEvents(await store('events'));
+      setDropped(await store('dropped'));
+    })();
+  }, []);
+
+  return (
+    <main className="app">
+      <header className="app-header">
+        <h1 className="app-title">Source Debugger</h1>
+        <span className="counts">
+          <span className="count-accepted" data-count={events.length}>{events.length} accepted</span>
+          <span className="count-dropped" data-count={dropped.length}>{dropped.length} dropped</span>
+        </span>
+      </header>
+      <nav className="app-nav">
+        {STREAMS.map((s) => (
+          <button
+            key={s.key}
+            className={stream === s.key ? 'nav-item nav-item-active' : 'nav-item'}
+            onClick={() => setStream(s.key)}
+          >
+            {s.label}
+          </button>
+        ))}
+      </nav>
+      {stream === 'events' ? <EventStream rows={events} /> : <DroppedStream rows={dropped} />}
+    </main>
+  );
+}
+
+const mount = typeof document === 'undefined' ? null : document.getElementById('root');
+if (mount) createRoot(mount).render(<App />);

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { optionValue } from '@volter/world-core/args';
+import { createSegmentTwinServer } from "./segment-server.js";
+import { OPS } from "./segment-surface.gen.js";
+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.js");
+    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.js");
+    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');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export { OPS, matchOp } from './segment-surface.gen.js';
+export { SEMANTICS, handleSegmentTwinRequest, events, identities, groups, dropped, ingest, decodeEnvelope, resolveWriteKey, segmentError, MODELED_TYPES, UNMODELED_TYPES, SEGMENT_MAX_REQUEST_BYTES, SEGMENT_MAX_BATCH_BYTES, SEGMENT_MAX_BATCH_EVENTS, } from './segment-twin.js';
+export { createSegmentTwinFetch, createSegmentTwinServer, type SegmentTwinFetchOptions } from './segment-server.js';
+export { createSegmentMirrorServer, buildSegmentMirrorClient, segmentMirrorHtml, clockLabel, messageLabel, propertyChips, subjectOf, typeTone, PILL_CLASS, type PillTone, type SegmentRow, } from './segment-mirror-ui.js';
+export { liveSegmentExecute, syncSegmentFromReal, pushPendingSegmentActions, pushEnvelopeFor, stampEnvelope, SEGMENT_API_BASE } from './segment-connector.js';
+export { SegmentBudget, SEGMENT_RATE_BUDGET, SEGMENT_BUDGET_CEILING, SEGMENT_CALL_WEIGHTS, segmentBudgetPath, segmentCallWeight } from './segment-budget.js';
+import type { TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,53 @@
+// The pack's RUNTIME surface — what a real app imports. Dev-only tooling (the conformance
+// harness, the capability manifest) is deliberately absent: docs/contributing/architecture.md E2 requires a twin
+// to run without @volter/world-tooling installed, and both of those import it. Reach them
+// through `world-segment conformance` or a direct module import instead.
+// `errorBody` is deliberately NOT re-exported from the generated module: its {success, message}
+// shape is scripts/sdk-compile.ts's scaffold default, and Segment's real error envelope is
+// {code, message} (grounded in analytics-python's own parser). Re-exporting it would advertise a
+// shape this vendor never sends. Use `segmentError` below instead.
+export { OPS, matchOp } from "./segment-surface.gen.js";
+export { SEMANTICS, handleSegmentTwinRequest, events, identities, groups, dropped, ingest, decodeEnvelope, resolveWriteKey, segmentError, MODELED_TYPES, UNMODELED_TYPES, SEGMENT_MAX_REQUEST_BYTES, SEGMENT_MAX_BATCH_BYTES, SEGMENT_MAX_BATCH_EVENTS, } from "./segment-twin.js";
+export { createSegmentTwinFetch, createSegmentTwinServer } from "./segment-server.js";
+export { createSegmentMirrorServer, buildSegmentMirrorClient, segmentMirrorHtml, clockLabel, messageLabel, propertyChips, subjectOf, typeTone, PILL_CLASS, } from "./segment-mirror-ui.js";
+export { liveSegmentExecute, syncSegmentFromReal, pushPendingSegmentActions, pushEnvelopeFor, stampEnvelope, SEGMENT_API_BASE } from "./segment-connector.js";
+export { SegmentBudget, SEGMENT_RATE_BUDGET, SEGMENT_BUDGET_CEILING, SEGMENT_CALL_WEIGHTS, segmentBudgetPath, segmentCallWeight } from "./segment-budget.js";
+import { SEGMENT_RATE_BUDGET as RATE_BUDGET } from "./segment-budget.js";
+export const pack = {
+    vendor: 'segment',
+    // The SAME object segment-budget.ts declares at module load — one source of truth, so
+    // registering the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-segment',
+    // The subject types the twin stores (segment-twin.ts projections); `dropped` is a real stored
+    // row — a message the tracking plane refused, kept rather than discarded.
+    resources: ['event', 'identity', 'group', 'dropped'],
+    specSource: 'NO first-party machine-readable spec exists for this surface — the denominator was AUTHORED op by ' +
+        'op at var/line/segment/SURFACE.json (16 operations, each carrying its evidence) and compiled into ' +
+        'segment-surface.gen.ts / segment-capabilities.gen.ts; docs grounding is github.com/segmentio/' +
+        'segment-docs, the vendor\'s own documentation source. See spec-sources.json.',
+    description: "Segment HTTP Tracking API twin — 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, plus the Source Debugger mirror: the live accepted/dropped stream this ' +
+        'write-only API has no way to read back.',
+    // Adoption: the Node tracking client this pack round-trips unmodified, plus the SEGMENT_*
+    // credential stem — declared HERE rather than in the central maps (adoption-facts sweep
+    // 2026-08-31). `@segment/analytics-next` is deliberately NOT claimed: it is the browser
+    // build surface (CDN settings fetch), not this HTTP Tracking API.
+    adoption: {
+        // Segment's official Python analytics library under both distribution names it has published
+        // under (the older `analytics-python` is still pinned widely).
+        pypi: ['segment-analytics-python', 'analytics-python'],
+        sdks: ['@segment/analytics-node'], envStems: ['SEGMENT'],
+    },
+    // Interception, moved off the hand VENDOR_HOSTS table unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31): the US and EU tracking hosts plus their OAuth token endpoints.
+    hosts: [
+        { host: 'api.segment.io' },
+        { host: 'events.eu1.segmentapis.com' },
+        { host: 'oauth2.segment.io' },
+        { host: 'oauth2.eu1.segmentapis.com' },
+    ],
+};

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

@@ -0,0 +1,41 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. Matches the kernel fallback: no vendor figure licenses a longer one. */
+export declare const SEGMENT_BUDGET_WINDOW_MS = 60000;
+/** Weighted units per window. Deliberately EQUAL to the kernel fallback's ceiling — see header. */
+export declare const SEGMENT_BUDGET_CEILING = 60;
+/** Seconds. A Retry-After above this means the credential is blocked, not throttled — fail loudly. */
+export declare const SEGMENT_BUDGET_MAX_RETRY_AFTER_S = 300;
+export declare const SEGMENT_CALL_WEIGHTS: {
+    /** Tracking-plane writes: /v1/batch, the mobile /v1/b, analytics.js's /v1/t, the six direct
+     *  /v1/<type> routes and the six /v1/pixel/* routes. The kernel fallback's default weight. */
+    readonly ingestion: 2;
+    /** POST /token on oauth2.segment.io — credential minting, with its own unrecoverable-error
+     *  handling in the SDK's TokenManager. Three times an ingest write. */
+    readonly oauth: 6;
+    /** Everything this pack has not classified. Equal to the ingestion weight so an UNKNOWN
+     *  endpoint is never cheaper than a known one — and never free. */
+    readonly other: 2;
+};
+/** THE PACK'S DECLARATION — pure data, first-match-wins on `"<METHOD> <pathname>"`. */
+export declare const SEGMENT_RATE_BUDGET: RateBudgetDeclaration;
+/** Price one call, keyed off the request the connector is about to make — an unclassified
+ *  endpoint still costs `defaultWeight`; an unknown endpoint must never be free. */
+export declare function segmentCallWeight(method: string, path: string): number;
+/** Where Segment's ledger lives. Key-keyed and cwd-independent by default (the allowance is per
+ *  source write key; a cwd-scoped ledger would hand one credential a fresh allowance per checkout). */
+export declare function segmentBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+export type SegmentBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/** Segment's budget — the shared kernel guard bound to this vendor's declaration. A real subclass
+ *  so `SegmentBudget` means "accounts against SEGMENT's ledger under ITS ceiling". It overrides
+ *  nothing: `assertBudgetGuardIntact` in the connector checks the guard methods are the kernel's
+ *  own, so an override here would be REFUSED rather than trusted. */
+export declare class SegmentBudget extends RateBudget {
+    constructor(opts?: SegmentBudgetOptions);
+}
+export { RateBudgetError as SegmentBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as SegmentBudgetErrorKind } from '@volter/world-core';
+export type SegmentBudgetReservation = RateBudgetReservation;
+export type SegmentBudgetSnapshot = RateBudgetSnapshot;

package/dist/src/segment-budget.js

@@ -0,0 +1,112 @@
+// Segment's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveSegmentExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → rateBudget.ts). Transcribed from
+// packages/twin/mixpanel/src/mixpanel-budget.ts, the sibling analytics pack; the METHOD is
+// copied, the NUMBERS are this vendor's own.
+//
+// ── HOW THE CEILING WAS CHOSEN ───────────────────────────────────────────────────────────────
+// Unlike Mixpanel, Segment DOES publish scalars. Live-fetched during this build, on 2026-08-24,
+// from the docs' own source repository (github.com/segmentio/segment-docs — segment.com itself
+// answers 403 to non-browser clients, so the rendered page was not read):
+//   • src/connections/sources/catalog/libraries/server/http-api/index.md '## Rate limits':
+//     "For each workspace, Segment recommends you to not exceed 1,000 requests per second with
+//     the HTTP 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".
+//   • src/connections/rate-limits.md ("These limits were updated on January 25, 2024"): the same
+//     1,000-per-second inbound ingestion figure, plus 10,000 properties per individual event.
+//   • '## Max request size': 32KB per normal request, 500KB per batch request, 32KB per event in
+//     a batch, and (from '## Errors') 2,500 events per batch request.
+//
+// 1,000 req/s is NOT adopted as this ceiling, and that is the whole judgement. It is a
+// WORKSPACE-WIDE production-throughput recommendation for an entire company's live traffic — the
+// number above which Segment "reserves the right to queue" — not an allowance handed to one
+// connector. This pack's only live caller is a REPLAY path (pushPendingSegmentActions), so
+// spending a production firehose's allowance from a dev machine would be dressing a vendor
+// recommendation up as a client budget. The declaration therefore claims NO extra permissiveness
+// over the kernel fallback: 60 weighted units per 60s at defaultWeight 2 — 30 calls/minute, the
+// fallback's exact shape — which is also why no VENDOR_BURST_ANCHOR is owed (that obligation
+// binds only a declaration that out-bursts the fallback). An operator who knows their own plan
+// can only TIGHTEN from here.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN ──────────────────────────────────────────────────────────────
+// Never cheaper than the default — a discount claims allowance no published figure licenses.
+// Ingestion writes sit at the default 2. The OAuth token exchange costs 6 because it is a
+// CREDENTIAL-MINTING call on a different host with its own 429 handling (the SDK's TokenManager
+// treats 400/401/415 there as unrecoverable and STOPS its poller), so a runaway auth loop must
+// halt three times sooner than a runaway ingest loop. That 2:6 ratio is a judgement about
+// relative risk, not a published cost, and is stated as such.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'segment';
+/** Rolling window, in ms. Matches the kernel fallback: no vendor figure licenses a longer one. */
+export const SEGMENT_BUDGET_WINDOW_MS = 60_000;
+/** Weighted units per window. Deliberately EQUAL to the kernel fallback's ceiling — see header. */
+export const SEGMENT_BUDGET_CEILING = 60;
+/** Seconds. A Retry-After above this means the credential is blocked, not throttled — fail loudly. */
+export const SEGMENT_BUDGET_MAX_RETRY_AFTER_S = 300;
+export const SEGMENT_CALL_WEIGHTS = {
+    /** Tracking-plane writes: /v1/batch, the mobile /v1/b, analytics.js's /v1/t, the six direct
+     *  /v1/<type> routes and the six /v1/pixel/* routes. The kernel fallback's default weight. */
+    ingestion: 2,
+    /** POST /token on oauth2.segment.io — credential minting, with its own unrecoverable-error
+     *  handling in the SDK's TokenManager. Three times an ingest write. */
+    oauth: 6,
+    /** Everything this pack has not classified. Equal to the ingestion weight so an UNKNOWN
+     *  endpoint is never cheaper than a known one — and never free. */
+    other: 2,
+};
+/** THE PACK'S DECLARATION — pure data, first-match-wins on `"<METHOD> <pathname>"`. */
+export const SEGMENT_RATE_BUDGET = {
+    windowMs: SEGMENT_BUDGET_WINDOW_MS,
+    ceiling: SEGMENT_BUDGET_CEILING,
+    defaultWeight: SEGMENT_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: SEGMENT_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [
+        { match: '^POST /v1/(batch|b|t)$', weight: SEGMENT_CALL_WEIGHTS.ingestion },
+        { match: '^POST /v1/(track|identify|page|screen|group|alias)$', weight: SEGMENT_CALL_WEIGHTS.ingestion },
+        { match: '^GET /v1/pixel/(track|identify|page|screen|group|alias)$', weight: SEGMENT_CALL_WEIGHTS.ingestion },
+        { match: '^POST /token$', weight: SEGMENT_CALL_WEIGHTS.oauth },
+    ],
+    reason: "Segment publishes scalar limits and this declaration deliberately does NOT adopt the headline one. " +
+        "Live-fetched 2026-08-24 from github.com/segmentio/segment-docs (the docs' own source; segment.com " +
+        'answers 403 to non-browser clients): src/connections/sources/catalog/libraries/server/http-api/index.md ' +
+        "'## Rate limits' — \"For each workspace, Segment recommends you to not exceed 1,000 requests per second " +
+        'with the HTTP 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"; ' +
+        'src/connections/rate-limits.md (updated January 25, 2024) repeats the 1,000/second inbound figure. That ' +
+        'number is a WORKSPACE-WIDE production-throughput recommendation, not a per-connector allowance, and this ' +
+        "pack's only live caller is a replay path — so adopting it would dress a vendor recommendation up as a " +
+        'client budget. The ceiling is therefore exactly the kernel fallback shape: 60 weighted units / 60s at ' +
+        'defaultWeight 2 (30 calls/minute, same burst), claiming no extra permissiveness and owing no burst anchor. ' +
+        "The vendor's cost STRUCTURE appears only in the relative weights, all at or above the default — tracking " +
+        'writes 2, the OAuth token exchange 6 — so a runaway auth loop halts three times sooner than a runaway ' +
+        'ingest loop. That 2:6 ratio is a judgement about relative risk, not a published cost. Size limits from the ' +
+        "same page ('## Max request size': 32KB per request, 500KB per batch, 32KB per batched event; '## Errors': " +
+        '2,500 events per batch) are enforced in segment-twin.ts, not here — they bound payloads, not call rate.',
+};
+// Declared at module load: importing this module (which segment-connector.ts does) arms the ceiling.
+declareRateBudget(VENDOR, SEGMENT_RATE_BUDGET);
+/** Price one call, keyed off the request the connector is about to make — an unclassified
+ *  endpoint still costs `defaultWeight`; an unknown endpoint must never be free. */
+export function segmentCallWeight(method, path) {
+    const q = path.indexOf('?');
+    const pathname = q < 0 ? path : path.slice(0, q);
+    return rateBudgetWeight(VENDOR, `${(method || 'GET').toUpperCase()} ${pathname}`, {});
+}
+/** Where Segment's ledger lives. Key-keyed and cwd-independent by default (the allowance is per
+ *  source write key; a cwd-scoped ledger would hand one credential a fresh allowance per checkout). */
+export function segmentBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/** Segment's budget — the shared kernel guard bound to this vendor's declaration. A real subclass
+ *  so `SegmentBudget` means "accounts against SEGMENT's ledger under ITS ceiling". It overrides
+ *  nothing: `assertBudgetGuardIntact` in the connector checks the guard methods are the kernel's
+ *  own, so an override here would be REFUSED rather than trusted. */
+export class SegmentBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+export { RateBudgetError as SegmentBudgetError } from '@volter/world-core';

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

@@ -0,0 +1,12 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const SEGMENT_CAPABILITIES: CapabilitySpec[];
+/** 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 declare const SEGMENT_AREAS: readonly ["alias", "auth", "batch", "common", "conformance", "connector", "errors", "group", "identify", "limits", "mirror", "oauth", "page", "pixel", "regional", "screen", "track"];
+export declare function segmentCapabilities(): Promise<CapabilityReport>;

package/dist/src/segment-capabilities.gen.d.ts

@@ -0,0 +1,3 @@
+import type { CapabilitySpec } from '@volter/world-tooling';
+/** Every ratified op, born `todo` — flips only by hand with a real verify. */
+export declare const GENERATED_CAPABILITIES: CapabilitySpec[];

package/dist/src/segment-capabilities.gen.js

@@ -0,0 +1,22 @@
+// GENERATED by scripts/sdk-compile.ts from var/line/segment/SURFACE.json — the vendor
+// publishes no machine-readable spec; every op below carries the evidence it was ratified on.
+// Data only; regenerate, never hand-edit.
+/** Every ratified op, born `todo` — flips only by hand with a real verify. */
+export const GENERATED_CAPABILITIES = [
+    { id: 'segment.api.alias', area: "alias", title: "POST /v1/alias — associate one identity with another: a `previousId` (userId or anonymousId) is aliased onto a new `userId` [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "common" },
+    { id: 'segment.api.batch', area: "batch", title: "POST /v1/batch — the SERVER-side batched ingestion envelope every official server SDK sends: {batch:[<message>...], writeKey, sentAt}, each message discriminated by its own `type` [grounding: SDK WIRE LITERAL. @segment/analytics-node@2.3.0 src/plugins/segmentio/publisher.ts:73-76 builds the ]", dimension: 'api', expected: 'todo', tier: "core" },
+    { id: 'segment.api.browser_track', area: "track", title: "POST /v1/t — analytics.js's short-form tracking route on the api.segment.io/v1 base — the path a browser proxy must forward [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "niche" },
+    { id: 'segment.api.group', area: "group", title: "POST /v1/group — associate an identified user with a group (company/account/team) and record group traits [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "core" },
+    { id: 'segment.api.identify', area: "identify", title: "POST /v1/identify — tie a user to their actions and record `traits` about them [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "core" },
+    { id: 'segment.api.mobile_batch', area: "batch", title: "POST /v1/b — the MOBILE batch endpoint — a distinct route from /v1/batch, which the vendor reserves for server-side sending [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "common" },
+    { id: 'segment.api.oauth_token', area: "oauth", title: "POST /token — OAuth 2.0 client-credentials token exchange on the regional authorization server: a signed RS256 JWT client assertion is traded for a short-lived access token [grounding: SDK WIRE LITERAL (interpolated, which is why wire.json's plain-string grep missed it). @segment/anal]", dimension: 'api', expected: 'todo', tier: "niche" },
+    { id: 'segment.api.page', area: "page", title: "POST /v1/page — record a web page view, with optional category, name and properties [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "core" },
+    { id: 'segment.api.pixel_alias', area: "pixel", title: "GET /v1/pixel/alias — Tracking Pixel API: an alias call carried in the query string, answering 200 with a 1x1 transparent GIF [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "niche" },
+    { id: 'segment.api.pixel_group', area: "pixel", title: "GET /v1/pixel/group — Tracking Pixel API: a group call carried in the query string, answering 200 with a 1x1 transparent GIF [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "niche" },
+    { id: 'segment.api.pixel_identify', area: "pixel", title: "GET /v1/pixel/identify — Tracking Pixel API: an identify call carried in the query string, answering 200 with a 1x1 transparent GIF [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "niche" },
+    { id: 'segment.api.pixel_page', area: "pixel", title: "GET /v1/pixel/page — Tracking Pixel API: a page call carried in the query string, answering 200 with a 1x1 transparent GIF [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "niche" },
+    { id: 'segment.api.pixel_screen', area: "pixel", title: "GET /v1/pixel/screen — Tracking Pixel API: a screen call carried in the query string, answering 200 with a 1x1 transparent GIF [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "niche" },
+    { id: 'segment.api.pixel_track', area: "pixel", title: "GET /v1/pixel/track — Tracking Pixel API: a track call carried in the query string (base64 `?data=` or plain params), answering 200 with a 1x1 transparent GIF [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "niche" },
+    { id: 'segment.api.screen', area: "screen", title: "POST /v1/screen — record a mobile app screen view, with optional category, name and properties [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "common" },
+    { id: 'segment.api.track', area: "track", title: "POST /v1/track — record an action a user performed: required `event` name plus optional `properties` [grounding: DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/l]", dimension: 'api', expected: 'todo', tier: "core" },
+];