@volter/twin-segment 0.1.0

package/src/index.ts

@@ -0,0 +1,87 @@
+// 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.ts';
+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.ts';
+export { createSegmentTwinFetch, createSegmentTwinServer, type SegmentTwinFetchOptions } from './segment-server.ts';
+export {
+  createSegmentMirrorServer,
+  buildSegmentMirrorClient,
+  segmentMirrorHtml,
+  clockLabel,
+  messageLabel,
+  propertyChips,
+  subjectOf,
+  typeTone,
+  PILL_CLASS,
+  type PillTone,
+  type SegmentRow,
+} from './segment-mirror-ui.ts';
+export { liveSegmentExecute, syncSegmentFromReal, pushPendingSegmentActions, pushEnvelopeFor, stampEnvelope, SEGMENT_API_BASE } from './segment-connector.ts';
+export { SegmentBudget, SEGMENT_RATE_BUDGET, SEGMENT_BUDGET_CEILING, SEGMENT_CALL_WEIGHTS, segmentBudgetPath, segmentCallWeight } from './segment-budget.ts';
+
+// Registry descriptor (#1): the pack self-describes so tooling can discover it.
+// A consumer does `registerPack(pack)` after importing this package.
+import type { TwinPack } from '@volter/world-core';
+import { SEGMENT_RATE_BUDGET as RATE_BUDGET } from './segment-budget.ts';
+export const pack: TwinPack = {
+  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/src/segment-budget.ts

@@ -0,0 +1,138 @@
+// 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,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} 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,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, first-match-wins on `"<METHOD> <pathname>"`. */
+export const SEGMENT_RATE_BUDGET: RateBudgetDeclaration = {
+  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: string, path: string): number {
+  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: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+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 class SegmentBudget extends RateBudget {
+  constructor(opts: SegmentBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+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/src/segment-capabilities.gen.ts

@@ -0,0 +1,25 @@
+// 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.
+
+import type { CapabilitySpec } from '@volter/world-tooling';
+
+/** Every ratified op, born `todo` — flips only by hand with a real verify. */
+export const GENERATED_CAPABILITIES: CapabilitySpec[] = [
+ { 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" },
+];