@volter/supercode-teams 0.2.20

package/server/index.d.ts

@@ -0,0 +1,31 @@
+export interface TeamsClock {
+  nowMs(): number;
+}
+
+export interface TeamsIdSource {
+  next(kind: string): string;
+}
+
+export interface TeamsServerOptions {
+  dataDir: string;
+  listen?: { host?: string; port?: number };
+  publicOrigin?: string | null;
+  clock?: TeamsClock;
+  ids?: TeamsIdSource;
+  initTeam?: string;
+  /** Artifact cap in bytes. Defaults to the protocol maximum of 256 MiB. */
+  uploadLimitBytes?: number;
+}
+
+export interface StartedTeamsServer {
+  address: string;
+  server_id: string;
+}
+
+export interface TeamsServer {
+  readonly serverId: string | undefined;
+  start(): Promise<StartedTeamsServer>;
+  close(): Promise<void>;
+}
+
+export declare function createTeamsServer(options: TeamsServerOptions): TeamsServer;

package/server/index.mjs

@@ -0,0 +1,52 @@
+// The Node host: one process on a data directory (SQLite in a worker thread, the
+// bootstrap credential in a protected file beside it), serving HTTP and the
+// machine doors on one listener. The server itself is core.mjs's.
+import { identityOrganizationsFromEnv } from '@volter/teams/server/identity-orgs';
+import { createServer as createHttpServer } from 'node:http';
+import { mkdirSync, openSync, closeSync, writeFileSync, readFileSync, renameSync, chmodSync, unlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { TeamsStore } from './store-worker.mjs';
+import { makeToken } from '@volter/teams/server/auth';
+import { createHttpHandler, authenticate } from '@volter/teams/server/http';
+import { harnessRoutes } from './harness-routes.mjs';
+import { createMachineUpgradeHandler } from './node-upgrade.mjs';
+import { closeAttachmentRelays } from './attachment-relay.mjs';
+import { createTeamsApi, bootstrapServer, maintain, normalizePublicOrigin, productionClock, productionIds } from '@volter/teams/server/core';
+
+function atomicJson(path,value){const tmp=`${path}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`;let fd;try{fd=openSync(tmp,'wx',0o600);writeFileSync(fd,JSON.stringify(value,null,2)+'\n');closeSync(fd);fd=undefined;renameSync(tmp,path);chmodSync(path,0o600);}catch(error){if(fd!==undefined)closeSync(fd);try{unlinkSync(tmp);}catch{}throw error;}}
+
+export function createTeamsServer({dataDir,listen={host:'127.0.0.1',port:7331},publicOrigin=null,identityIssuer=null,delegatedIssuer=null,clock=productionClock,ids=productionIds,initTeam,uploadLimitBytes=256*1024*1024}={}) {
+  if(!dataDir) throw new TypeError('dataDir is required');
+  const loopback=['127.0.0.1','::1','localhost'].includes(listen.host??'127.0.0.1');
+  publicOrigin=normalizePublicOrigin(publicOrigin);
+  if(!loopback&&!publicOrigin?.startsWith('https:'))throw new TypeError('non-loopback Teams servers require an HTTPS publicOrigin');
+  const api=createTeamsApi({clock,ids,publicOrigin,identityIssuer,identityOrganizations:identityIssuer?identityOrganizationsFromEnv(process.env):null,delegatedIssuer,uploadLimitBytes});
+  // The harness's own routes on this server (harness-routes.mjs); the handler owns the neutral ones.
+  api.attach({harnessRoutes});
+  const events=api.events;
+  let store,http,upgrade,lockFd,maintenanceTimer,started=false;
+  api.start=async()=>{
+    if(started)throw new Error('Teams server already started'); mkdirSync(dataDir,{recursive:true,mode:0o700});chmodSync(dataDir,0o700);
+    const lock=join(dataDir,'server.lock'); const acquire=()=>{lockFd=openSync(lock,'wx',0o600);writeFileSync(lockFd,JSON.stringify({pid:process.pid,started_at:clock.nowMs()}));};try{acquire();}catch(e){let recover=false;try{const owner=JSON.parse(readFileSync(lock,'utf8'));if(Number.isInteger(owner.pid)&&owner.pid>1){try{process.kill(owner.pid,0);}catch(error){recover=error.code==='ESRCH';}}}catch{}if(!recover)throw new Error(`Teams data directory is already owned: ${dataDir}`,{cause:e});unlinkSync(lock);acquire();}
+    try { const dbPath=join(dataDir,'teams.sqlite'); store=new TeamsStore(dbPath); api.attach({store});
+      const existing=await store.one("SELECT value FROM server_meta WHERE key='server_id'");
+      const credentialPath=join(dataDir,'bootstrap-credential.json'),pendingPath=join(dataDir,'bootstrap-credential.pending.json');
+      let serverId;
+      if(!existing){
+        let bootstrap;if(existsSync(pendingPath))bootstrap=JSON.parse(readFileSync(pendingPath,'utf8'));else{const cid=ids.next('credential');bootstrap={version:1,server_id:ids.next('server'),team_id:ids.next('team'),principal_id:ids.next('user'),credential_id:cid,token:makeToken(cid)};atomicJson(pendingPath,bootstrap);}
+        serverId=await bootstrapServer(api,{initTeam,bootstrap});
+        renameSync(pendingPath,credentialPath);chmodSync(credentialPath,0o600);
+      } else {
+        if(initTeam!==undefined)throw new Error('initTeam is only valid when creating a new Teams data directory');
+        serverId=existing.value;
+        if(!existsSync(credentialPath)&&existsSync(pendingPath)){const pending=JSON.parse(readFileSync(pendingPath,'utf8'));if(pending.server_id!==serverId)throw new Error('bootstrap credential recovery does not match server identity');renameSync(pendingPath,credentialPath);chmodSync(credentialPath,0o600);}
+      }
+      api.attach({serverId});
+      await maintain(api);maintenanceTimer=setInterval(()=>{void maintain(api).catch(()=>{});},60000);maintenanceTimer.unref?.();
+      chmodSync(dbPath,0o600); http=createHttpServer(createHttpHandler(api));upgrade=createMachineUpgradeHandler(api,{authenticate});http.on('upgrade',upgrade); await new Promise((resolve,reject)=>{http.once('error',reject);http.listen(listen.port??0,listen.host??'127.0.0.1',resolve);});started=true;const addr=http.address();api.attach({localOrigin:`http://${addr.address.includes(':')?`[${addr.address}]`:addr.address}:${addr.port}`});return {address:`${addr.address}:${addr.port}`,server_id:serverId};
+    } catch(e){if(maintenanceTimer){clearInterval(maintenanceTimer);maintenanceTimer=undefined;}await store?.close().catch(()=>{});store=null;api.attach({store:null});if(lockFd!==undefined){closeSync(lockFd);lockFd=undefined;}try{unlinkSync(lock);}catch{}throw e;}
+  };
+  api.close=async()=>{if(!started&&lockFd===undefined)return;started=false;if(maintenanceTimer){clearInterval(maintenanceTimer);maintenanceTimer=undefined;}events.close();closeAttachmentRelays(api,'access_revoked');upgrade?.close();await new Promise(resolve=>http?.close(()=>resolve()));await store?.close();store=null;if(lockFd!==undefined){closeSync(lockFd);lockFd=undefined;}try{unlinkSync(join(dataDir,'server.lock'));}catch{}api.attach({store:null});};
+  return api;
+}

package/server/ingest.mjs

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson, ContractError, sha256 } from '@volter/teams/server/wire';
+export { sha256 };
+import { createOtlpHttpReceiver } from './otlp/receiver.mjs';
+import { encodeOtlpError } from './otlp/transport.mjs';
+import { projectOtlpBatch } from './otlp/projection.mjs';
+export function captureDigest(begin, parts, commit) { const copy={...commit}; delete copy.digest; return sha256(canonicalJson({begin,parts,commit:copy})); }
+export function validateArtifactName(name) { if(typeof name!=='string'||!name||name.includes('\\')||name.includes('\0')||name.startsWith('/')||name.split('/').includes('..')) throw new ContractError('artifact relative_name is not portable'); }
+export function captureMessages(parts) { const keys=new Set(); const out=[]; for(const part of parts)for(const message of part.messages){if(keys.has(message.native_key))throw Object.assign(new Error('duplicate native message key'),{code:'capture_conflict'});keys.add(message.native_key);out.push(message);} return out; }
+
+export async function handleOtlpRoute(api, req, res, auth, signal) {
+  const representation=String(req.headers['content-type']??'').split(';',1)[0].trim().toLowerCase()==='application/x-protobuf'?'protobuf':'json';
+  const write=output=>{res.writeHead(output.status,{...output.headers,'cache-control':'no-store'});res.end(output.body);};
+  if(!auth||auth.kind!=='ingest'||!auth.team_id||!auth.source_id){const body=await encodeOtlpError({representation,code:16,message:'valid ingestion credentials are required'});return write({status:401,headers:{'content-type':representation==='protobuf'?'application/x-protobuf':'application/json'},body});}
+  const rateKey=`otlp:${auth.credential_id}`,rateNow=api.clock.nowMs(),rate=api.rateState.get(rateKey)??{tokens:30,at:rateNow};rate.tokens=Math.min(30,rate.tokens+(rateNow-rate.at)*(120/60000));rate.at=rateNow;if(rate.tokens<1){api.rateState.set(rateKey,rate);const body=await encodeOtlpError({representation,code:8,message:'ingestion rate limit exceeded'});return write({status:429,headers:{'content-type':representation==='protobuf'?'application/x-protobuf':'application/json','retry-after':'1'},body});}rate.tokens-=1;api.rateState.set(rateKey,rate);
+  const receivedAt=api.clock.nowMs();
+  const receiver=createOtlpHttpReceiver({persist:async({records,rejectedCount,sourceAuthorization})=>{
+    const items=projectOtlpBatch(records,{teamId:sourceAuthorization.teamId,sourceId:sourceAuthorization.sourceId,ids:api.ids});
+    const receipt=await api.store.ingestOtlpBatch({teamId:sourceAuthorization.teamId,sourceId:sourceAuthorization.sourceId,credentialId:sourceAuthorization.credentialId,receivedAt,authorizationCheckedAt:api.clock.nowMs(),items,rejectedCount});
+    for(const changed of receipt.changedSessions)api.events.publish(sourceAuthorization.teamId,{type:'session_changed',cursor:String(changed.revision),revision:changed.revision,session_id:changed.sessionId,reason:'capture',read_required:true});
+  }});
+  try { return write(await receiver({signal,headers:req.headers,body:req,sourceAuthorization:{teamId:auth.team_id,sourceId:auth.source_id,credentialId:auth.credential_id},receivedAt})); }
+  catch(error){const status=error.status===401?401:503,code=status===401?16:14,message=status===401?'ingestion authorization changed':'ingestion commit did not complete';const body=await encodeOtlpError({representation,code,message});return write({status,headers:{'content-type':representation==='protobuf'?'application/x-protobuf':'application/json'},body});}
+}

package/server/node-upgrade.mjs

@@ -0,0 +1,39 @@
+// The Node host's WebSocket termination for the machine doors (machine-link.mjs):
+// the `ws` library upgrades, pings every 20 s, and hands the socket over as a stream.
+import { WebSocketServer, createWebSocketStream } from 'ws';
+import { authorizeMachineUpgrade, acceptMachineSocket, LINK_PROTOCOL, CHANNEL_PROTOCOL } from '@volter/teams/server/machine-link';
+
+const MAX_PAYLOAD = 16 * 1024 * 1024;
+const PING_MS = 20_000;
+
+/** The Node host's `upgrade` handler: the `ws` library terminates the WebSocket. */
+export function createMachineUpgradeHandler(api, { authenticate }) {
+  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_PAYLOAD, handleProtocols: (offered) => [...offered].find((p) => p === LINK_PROTOCOL || p === CHANNEL_PROTOCOL) ?? false });
+  const heartbeat = setInterval(() => {
+    for (const client of wss.clients) {
+      if (client.alive === false) { client.terminate(); continue; }
+      client.alive = false;
+      client.ping();
+    }
+  }, PING_MS);
+  heartbeat.unref?.();
+  const refuse = (socket, status, code, message) => {
+    const body = JSON.stringify({ error: { code, message } });
+    socket.end(`HTTP/1.1 ${status} ${code}\r\nContent-Type: application/json\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`);
+  };
+  const handler = async (req, socket, head) => {
+    try {
+      const decision = await authorizeMachineUpgrade(api, { authenticate, url: req.url, headers: req.headers });
+      if (decision.status) return refuse(socket, decision.status, decision.code, decision.message);
+      return wss.handleUpgrade(req, socket, head, (ws) => {
+        ws.alive = true; ws.on('pong', () => { ws.alive = true; });
+        void acceptMachineSocket(api, decision, createWebSocketStream(ws), (reason) => ws.close(1000, String(reason ?? 'closed').slice(0, 100)));
+      });
+    } catch (error) {
+      refuse(socket, 500, 'internal', error.message);
+    }
+  };
+  handler.close = () => { clearInterval(heartbeat); for (const client of wss.clients) client.terminate(); wss.close(); };
+  return handler;
+}
+

package/server/otlp/collector-config.d.ts

@@ -0,0 +1,2 @@
+export interface SourceCollectorConfig { format: "otel-collector"; source_id: string; endpoint: string; credential_env: string; content: string }
+export declare function renderSourceCollectorConfig(input: { sourceId: string; endpoint: string }): SourceCollectorConfig;

package/server/otlp/collector-config.mjs

@@ -0,0 +1,26 @@
+const SOURCE_ID = /^src_([0-9a-f]{32})$/;
+
+export function renderSourceCollectorConfig({ sourceId, endpoint }) {
+  const match = SOURCE_ID.exec(sourceId);
+  if (!match) throw new TypeError("sourceId must be src_ plus 32 lowercase hexadecimal digits");
+  let origin;
+  try { origin = new URL(endpoint); } catch { throw new TypeError("endpoint must be a trusted HTTP(S) origin"); }
+  if (!/^https?:$/.test(origin.protocol) || origin.username || origin.password || origin.pathname !== "/" || origin.search || origin.hash) {
+    throw new TypeError("endpoint must be a trusted HTTP(S) origin without credentials, path, query, or fragment");
+  }
+  const normalizedEndpoint = origin.origin;
+  const credentialEnv = `SUPERCODE_TEAMS_INGEST_TOKEN_${match[1].toUpperCase()}`;
+  const exporterId = `otlphttp/supercode_${sourceId}`;
+  const content = [
+    "# Add this exporter to your existing OpenTelemetry Collector configuration.",
+    "# Append its ID to every logs/traces/metrics pipeline that should reach Harness Teams.",
+    "# Keep all existing receivers, exporters, and pipelines; this fragment does not replace them.",
+    "exporters:",
+    `  ${exporterId}:`,
+    `    endpoint: ${normalizedEndpoint}`,
+    "    headers:",
+    `      authorization: "Bearer \${env:${credentialEnv}}"`,
+    ""
+  ].join("\n");
+  return { format: "otel-collector", source_id: sourceId, endpoint: normalizedEndpoint, credential_env: credentialEnv, content };
+}

package/server/otlp/decoders/index.d.ts

@@ -0,0 +1,63 @@
+import type { HarnessId, NormalizedMessage } from '@volter/supercode-harness-sdk';
+
+export type OtlpAnyValue =
+  | { stringValue: string }
+  | { boolValue: boolean }
+  | { intValue: string }
+  | { doubleValue: number }
+  | { bytesValue: string }
+  | { arrayValue: { values: OtlpAnyValue[] } }
+  | { kvlistValue: { values: OtlpKeyValue[] } };
+export interface OtlpKeyValue { key: string; value: OtlpAnyValue }
+export type AttributeInput = OtlpKeyValue[] | Record<string, unknown>;
+export interface OtlpLogRecord {
+  eventName?: string;
+  timeUnixNano?: string;
+  observedTimeUnixNano?: string;
+  traceId?: string;
+  spanId?: string;
+  /** Raw OTLP AnyValue, or a string from an upstream schema decoder. */
+  body?: OtlpAnyValue | string;
+  attributes?: AttributeInput;
+  [unknownField: string]: unknown;
+}
+export interface DecodeLogEvidenceInput {
+  record: OtlpLogRecord;
+  resourceAttributes?: AttributeInput;
+  scopeAttributes?: AttributeInput;
+  receivedAt: number;
+}
+export type DecodeIssueCode =
+  | 'invalid_record' | 'invalid_received_at' | 'invalid_attributes' | 'invalid_attribute'
+  | 'duplicate_attribute' | 'invalid_any_value' | 'invalid_int64' | 'int64_out_of_range'
+  | 'invalid_bytes_value' | 'invalid_attribute_type'
+  | 'invalid_event_name' | 'event_name_disagreement' | 'invalid_timestamp'
+  | 'uint64_out_of_range' | 'timestamp_out_of_range' | 'invalid_trace_id' | 'invalid_span_id';
+export interface DecodeIssue { code: DecodeIssueCode; path: string; message: string }
+export type CoverageReason =
+  | 'redacted' | 'truncated' | 'unsequenced' | 'unsupported_decoder' | 'parse_error';
+export interface EvidenceIdentityFacts {
+  native_event_id: string | null;
+  trace_id: string | null;
+  span_id: string | null;
+  event_index: string | null;
+  dedup_eligible: boolean;
+}
+export interface DecodedLogEvidence {
+  raw: DecodeLogEvidenceInput;
+  decoder: 'claude-code.logs.v1' | 'gemini.logs.v1' | 'codex.logs.v1' | 'grok.logs.v1' | null;
+  status: 'decoded' | 'activity' | 'unassociated' | 'decode_error';
+  event_name: string | null;
+  harness: Extract<HarnessId, 'claude-code' | 'gemini' | 'codex' | 'grok'> | null;
+  native_session_id: string | null;
+  /** Unverified vendor-reported identity; never a Teams principal mapping. */
+  reported_user: string | null;
+  recorded_at: number | null;
+  recorded_time_unix_nano: string | null;
+  message: NormalizedMessage | null;
+  coverage_reasons: CoverageReason[];
+  identity: EvidenceIdentityFacts | null;
+  errors: DecodeIssue[];
+}
+export declare function decodeLogEvidence(input: DecodeLogEvidenceInput): DecodedLogEvidence;
+export declare const DECODERS: Readonly<{ claude: 'claude-code.logs.v1'; gemini: 'gemini.logs.v1'; codex: 'codex.logs.v1'; grok: 'grok.logs.v1' }>;

package/server/otlp/decoders/index.mjs

@@ -0,0 +1,311 @@
+const DECODERS = Object.freeze({
+  claude: 'claude-code.logs.v1',
+  gemini: 'gemini.logs.v1',
+  codex: 'codex.logs.v1',
+  grok: 'grok.logs.v1',
+});
+
+// Per decoder: the event-name prefix that selects it, the harness it attributes records to, the
+// log attribute that carries the harness's native session id, and whether LogRecord.eventName is
+// a tracing callsite label ("event <file>:<line>") rather than the event, so only event.name names it.
+const DECODER_FACTS = Object.freeze({
+  [DECODERS.claude]: { prefix: 'claude_code.', harness: 'claude-code', session: 'session.id', callsiteEventName: false },
+  [DECODERS.gemini]: { prefix: 'gemini_cli.', harness: 'gemini', session: 'session.id', callsiteEventName: false },
+  // codex-rs/otel/src/events/shared.rs (log_event!) + otel/src/provider.rs (OpenTelemetryTracingBridge) @ rust-v0.156.1.
+  [DECODERS.codex]: { prefix: 'codex.', harness: 'codex', session: 'conversation.id', callsiteEventName: true },
+  // grok 1.0.41 bundled docs 24-monitoring-usage.md, "Events (OTLP log records)": every event carries session.id.
+  [DECODERS.grok]: { prefix: 'grok_code.', harness: 'grok', session: 'session.id', callsiteEventName: false },
+});
+
+const MESSAGE_EVENTS = Object.freeze({
+  'claude_code.user_prompt': { decoder: DECODERS.claude, harness: 'claude-code', role: 'user', content: 'prompt' },
+  'claude_code.assistant_response': { decoder: DECODERS.claude, harness: 'claude-code', role: 'assistant', content: 'response' },
+  'gemini_cli.user_prompt': { decoder: DECODERS.gemini, harness: 'gemini', role: 'user', content: 'prompt' },
+  'gemini_cli.api_response': { decoder: DECODERS.gemini, harness: 'gemini', role: 'assistant', content: 'response_text' },
+  // codex-rs/otel/src/events/session_telemetry.rs (SessionTelemetry::user_prompt) @ rust-v0.156.1; Codex logs no assistant text.
+  'codex.user_prompt': { decoder: DECODERS.codex, harness: 'codex', role: 'user', content: 'prompt' },
+  // grok 1.0.41 bundled docs 24-monitoring-usage.md: `prompt` present only under OTEL_LOG_USER_PROMPTS.
+  'grok_code.user_prompt': { decoder: DECODERS.grok, harness: 'grok', role: 'user', content: 'prompt' },
+  // grok 1.0.41 bundled docs 24-monitoring-usage.md: `response` present only under OTEL_LOG_ASSISTANT_RESPONSES.
+  'grok_code.assistant_response': { decoder: DECODERS.grok, harness: 'grok', role: 'assistant', content: 'response' },
+});
+
+const DECIMAL_INT64 = /^-?(?:0|[1-9][0-9]*)$/;
+const INT64_MIN = -9_223_372_036_854_775_808n;
+const INT64_MAX = 9_223_372_036_854_775_807n;
+const UINT64_MAX = 18_446_744_073_709_551_615n;
+const HEX_TRACE = /^[0-9a-fA-F]{32}$/;
+const HEX_SPAN = /^[0-9a-fA-F]{16}$/;
+const ZERO_TRACE = '0'.repeat(32);
+const ZERO_SPAN = '0'.repeat(16);
+const BASE64 = /^[A-Za-z0-9+/_-]*={0,2}$/;
+const REDACTION_MARKERS = new Set(['<REDACTED>', '[REDACTED]']);
+const TRUNCATION_MARKERS = ['<TRUNCATED>', '[TRUNCATED]'];
+
+function issue(code, path, message) {
+  return { code, path, message };
+}
+
+function decodeAnyValue(value, path, errors) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push(issue('invalid_any_value', path, 'AnyValue must be an object'));
+    return undefined;
+  }
+  const fields = ['stringValue', 'boolValue', 'intValue', 'doubleValue', 'bytesValue', 'arrayValue', 'kvlistValue'];
+  const present = fields.filter((field) => Object.hasOwn(value, field));
+  if (present.length !== 1) {
+    errors.push(issue('invalid_any_value', path, 'AnyValue must contain exactly one value field'));
+    return undefined;
+  }
+  const field = present[0];
+  const raw = value[field];
+  if (field === 'stringValue') {
+    if (typeof raw !== 'string') errors.push(issue('invalid_any_value', `${path}.stringValue`, 'must be a string'));
+    return typeof raw === 'string' ? raw : undefined;
+  }
+  if (field === 'boolValue') {
+    if (typeof raw !== 'boolean') errors.push(issue('invalid_any_value', `${path}.boolValue`, 'must be a boolean'));
+    return typeof raw === 'boolean' ? raw : undefined;
+  }
+  if (field === 'intValue') {
+    if (typeof raw !== 'string' || !DECIMAL_INT64.test(raw)) {
+      errors.push(issue('invalid_int64', `${path}.intValue`, 'OTLP int64 must be a canonical decimal string'));
+      return undefined;
+    }
+    // A signed int64 has at most 19 digits (plus a sign); reject longer input before BigInt parsing.
+    if (raw.length > 20 || (raw[0] !== '-' && raw.length > 19)) {
+      errors.push(issue('int64_out_of_range', `${path}.intValue`, 'OTLP int64 is outside the signed 64-bit range'));
+      return undefined;
+    }
+    const parsed = BigInt(raw);
+    if (parsed < INT64_MIN || parsed > INT64_MAX) {
+      errors.push(issue('int64_out_of_range', `${path}.intValue`, 'OTLP int64 is outside the signed 64-bit range'));
+      return undefined;
+    }
+    return raw;
+  }
+  if (field === 'doubleValue') {
+    if (typeof raw !== 'number' || !Number.isFinite(raw)) errors.push(issue('invalid_any_value', `${path}.doubleValue`, 'must be a finite number'));
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;
+  }
+  if (field === 'bytesValue') {
+    const padding = typeof raw === 'string' ? raw.length - raw.replace(/=+$/, '').length : 0;
+    const dataLength = typeof raw === 'string' ? raw.length - padding : 0;
+    const validLength = padding > 0 ? raw.length % 4 === 0 : dataLength % 4 !== 1;
+    if (typeof raw !== 'string' || !BASE64.test(raw) || !validLength) {
+      errors.push(issue('invalid_bytes_value', `${path}.bytesValue`, 'must be valid standard or URL-safe base64'));
+      return undefined;
+    }
+    return raw;
+  }
+  if (field === 'arrayValue') {
+    if (!raw || typeof raw !== 'object' || !Array.isArray(raw.values)) {
+      errors.push(issue('invalid_any_value', `${path}.arrayValue`, 'must contain a values array'));
+      return undefined;
+    }
+    return raw.values.map((entry, index) => decodeAnyValue(entry, `${path}.arrayValue.values[${index}]`, errors));
+  }
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.values)) {
+    errors.push(issue('invalid_any_value', `${path}.kvlistValue`, 'must contain a values array'));
+    return undefined;
+  }
+  return decodeAttributes(raw.values, `${path}.kvlistValue.values`, errors);
+}
+
+function decodeAttributes(attributes, path, errors) {
+  if (attributes === undefined || attributes === null) return {};
+  if (!Array.isArray(attributes)) {
+    if (typeof attributes === 'object') return { ...attributes };
+    errors.push(issue('invalid_attributes', path, 'attributes must be an OTLP KeyValue array or object'));
+    return {};
+  }
+  const result = Object.create(null);
+  for (let index = 0; index < attributes.length; index += 1) {
+    const entry = attributes[index];
+    const entryPath = `${path}[${index}]`;
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || typeof entry.key !== 'string' || !entry.key) {
+      errors.push(issue('invalid_attribute', entryPath, 'attribute must have a non-empty string key'));
+      continue;
+    }
+    if (Object.hasOwn(result, entry.key)) {
+      errors.push(issue('duplicate_attribute', `${entryPath}.key`, `duplicate attribute ${entry.key}`));
+      continue;
+    }
+    Object.defineProperty(result, entry.key, {
+      value: decodeAnyValue(entry.value, `${entryPath}.value`, errors),
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+  }
+  return result;
+}
+
+function normalizeName(name) {
+  if (name === 'user_prompt') return 'claude_code.user_prompt';
+  if (name === 'assistant_response') return 'claude_code.assistant_response';
+  return name;
+}
+
+function decoderFor(name) {
+  if (!name) return null;
+  return Object.keys(DECODER_FACTS).find((decoder) => name.startsWith(DECODER_FACTS[decoder].prefix)) ?? null;
+}
+
+function milliseconds(raw, path, errors) {
+  if (raw === undefined || raw === null || raw === '0') return null;
+  if (typeof raw !== 'string' || !/^(?:0|[1-9][0-9]*)$/.test(raw)) {
+    errors.push(issue('invalid_timestamp', path, 'OTLP nanoseconds must be a non-negative canonical decimal string'));
+    return null;
+  }
+  if (raw.length > 20) {
+    errors.push(issue('uint64_out_of_range', path, 'OTLP nanoseconds exceed the unsigned 64-bit range'));
+    return null;
+  }
+  const nanos = BigInt(raw);
+  if (nanos > UINT64_MAX) {
+    errors.push(issue('uint64_out_of_range', path, 'OTLP nanoseconds exceed the unsigned 64-bit range'));
+    return null;
+  }
+  const value = nanos / 1_000_000n;
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    errors.push(issue('timestamp_out_of_range', path, 'millisecond timestamp exceeds Number.MAX_SAFE_INTEGER'));
+    return null;
+  }
+  return Number(value);
+}
+
+function stringAttribute(attributes, key, errors) {
+  const value = attributes[key];
+  if (value === undefined) return null;
+  if (typeof value !== 'string') {
+    errors.push(issue('invalid_attribute_type', `attributes.${key}`, `${key} must be a string`));
+    return null;
+  }
+  return value;
+}
+
+function coverageForContent(content) {
+  if (content === null) return [];
+  if (REDACTION_MARKERS.has(content)) return ['redacted'];
+  if (TRUNCATION_MARKERS.some((marker) => content.includes(marker))) return ['truncated'];
+  return [];
+}
+
+function identityFacts(record, attributes, eventName, errors) {
+  const traceId = record.traceId === '' ? null : record.traceId ?? null;
+  const spanId = record.spanId === '' ? null : record.spanId ?? null;
+  if (traceId !== null && (typeof traceId !== 'string' || !HEX_TRACE.test(traceId))) {
+    errors.push(issue('invalid_trace_id', 'record.traceId', 'traceId must be 32 hexadecimal characters'));
+  }
+  if (spanId !== null && (typeof spanId !== 'string' || !HEX_SPAN.test(spanId))) {
+    errors.push(issue('invalid_span_id', 'record.spanId', 'spanId must be 16 hexadecimal characters'));
+  }
+  const messageUuid = attributes['message.uuid'];
+  if (messageUuid !== undefined && typeof messageUuid !== 'string') {
+    errors.push(issue('invalid_attribute_type', 'attributes.message.uuid', 'message.uuid must be a string'));
+  }
+  const nativeEventId = (eventName === 'claude_code.user_prompt' || eventName === 'claude_code.assistant_response')
+    && typeof messageUuid === 'string' && messageUuid
+    ? messageUuid
+    : null;
+  const validTrace = typeof traceId === 'string' && HEX_TRACE.test(traceId) && traceId !== ZERO_TRACE;
+  const validSpan = typeof spanId === 'string' && HEX_SPAN.test(spanId) && spanId !== ZERO_SPAN;
+  return {
+    native_event_id: nativeEventId,
+    trace_id: validTrace ? traceId.toLowerCase() : null,
+    span_id: validSpan ? spanId.toLowerCase() : null,
+    event_index: null,
+    dedup_eligible: nativeEventId !== null,
+  };
+}
+
+/** Decode one already-unmarshalled OTLP LogRecord without adding source identity or persistence policy. */
+export function decodeLogEvidence({ record, resourceAttributes = [], scopeAttributes = [], receivedAt }) {
+  const raw = { record, resourceAttributes, scopeAttributes, receivedAt };
+  const errors = [];
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    return {
+      raw, decoder: null, status: 'decode_error', event_name: null, harness: null,
+      native_session_id: null, recorded_at: null, recorded_time_unix_nano: null,
+      message: null, coverage_reasons: ['parse_error'], identity: null,
+      errors: [issue('invalid_record', 'record', 'record must be an object')],
+    };
+  }
+  if (!Number.isSafeInteger(receivedAt) || receivedAt < 0) {
+    errors.push(issue('invalid_received_at', 'receivedAt', 'receivedAt must be a non-negative safe integer millisecond timestamp'));
+  }
+  const resource = decodeAttributes(resourceAttributes, 'resourceAttributes', errors);
+  decodeAttributes(scopeAttributes, 'scopeAttributes', errors);
+  const local = decodeAttributes(record.attributes, 'record.attributes', errors);
+  const attributes = { ...resource, ...local };
+  const topName = record.eventName === undefined ? null : record.eventName;
+  if (topName !== null && typeof topName !== 'string') errors.push(issue('invalid_event_name', 'record.eventName', 'eventName must be a string'));
+  const attributeName = stringAttribute(attributes, 'event.name', errors);
+  const normalizedAttribute = attributeName ? normalizeName(attributeName) : null;
+  const attributeDecoder = decoderFor(normalizedAttribute);
+  const topIsCallsite = attributeDecoder !== null && DECODER_FACTS[attributeDecoder].callsiteEventName;
+  const normalizedTop = typeof topName === 'string' && topName && !topIsCallsite ? normalizeName(topName) : null;
+  if (normalizedTop && normalizedAttribute && normalizedTop !== normalizedAttribute) {
+    errors.push(issue('event_name_disagreement', 'record.eventName', 'eventName and event.name disagree after normalization'));
+  }
+  const body = typeof record.body === 'string'
+    ? record.body
+    : record.body === undefined ? undefined : decodeAnyValue(record.body, 'record.body', errors);
+  const legacyBodyName = !normalizedTop && !normalizedAttribute && typeof body === 'string' && body ? normalizeName(body) : null;
+  const eventName = normalizedTop ?? normalizedAttribute ?? legacyBodyName;
+  const decoder = decoderFor(eventName);
+  const definition = eventName ? MESSAGE_EVENTS[eventName] : undefined;
+  const sessionId = stringAttribute(attributes, decoder ? DECODER_FACTS[decoder].session : 'session.id', errors);
+  const reportedUser = ['user.email','user.account_id','user.account_uuid','user.id'].map(key=>stringAttribute(attributes,key,errors)).find(Boolean) ?? null;
+  // OTLP: a zero or absent time_unix_nano means the event time is unknown and consumers use
+  // observed_time_unix_nano (Codex sends "0" on every record).
+  const eventAt = milliseconds(record.timeUnixNano, 'record.timeUnixNano', errors);
+  const observedAt = record.observedTimeUnixNano !== undefined ? milliseconds(record.observedTimeUnixNano, 'record.observedTimeUnixNano', errors) : null;
+  const recordedAt = eventAt ?? observedAt;
+  const identity = identityFacts(record, attributes, eventName, errors);
+  const reasons = [];
+  let message = null;
+  let status = 'activity';
+  if (!decoder) reasons.push('unsupported_decoder');
+  if (decoder && !sessionId) {
+    status = 'unassociated';
+  }
+  if (definition) {
+    const contentValue = attributes[definition.content];
+    if (contentValue !== undefined && typeof contentValue !== 'string') {
+      errors.push(issue('invalid_attribute_type', `attributes.${definition.content}`, `${definition.content} must be a string`));
+    }
+    const content = typeof contentValue === 'string' && contentValue.length > 0 ? contentValue : null;
+    reasons.push(...coverageForContent(content));
+    if (sessionId && content && !REDACTION_MARKERS.has(content)) {
+      message = {
+        role: definition.role,
+        content,
+        metadata: { telemetry_decoder: definition.decoder, telemetry_event_name: eventName },
+      };
+      status = 'decoded';
+    }
+  }
+  // Log records lack a trusted process-incarnation + documented sequence pair. Dedup identity
+  // does not establish ordering, so every projection from this decoder remains unsequenced.
+  reasons.push('unsequenced');
+  if (errors.length > 0) status = 'decode_error';
+  return {
+    raw,
+    decoder,
+    status,
+    event_name: eventName,
+    harness: definition?.harness ?? (decoder ? DECODER_FACTS[decoder].harness : null),
+    native_session_id: sessionId,
+    reported_user: reportedUser,
+    recorded_at: recordedAt,
+    recorded_time_unix_nano: eventAt !== null && typeof record.timeUnixNano === 'string' ? record.timeUnixNano : observedAt !== null && typeof record.observedTimeUnixNano === 'string' ? record.observedTimeUnixNano : null,
+    message: errors.length === 0 ? message : null,
+    coverage_reasons: [...new Set(errors.length ? ['parse_error', ...reasons] : reasons)],
+    identity,
+    errors,
+  };
+}
+
+export { DECODERS };

package/server/otlp/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./transport.mjs";
+export * from "./receiver.mjs";
+export * from "./collector-config.mjs";
+export * from "./projection.mjs";

package/server/otlp/index.mjs

@@ -0,0 +1,4 @@
+export * from "./transport.mjs";
+export * from "./receiver.mjs";
+export * from "./collector-config.mjs";
+export * from "./projection.mjs";

package/server/otlp/projection.d.ts

@@ -0,0 +1,5 @@
+import type { RawOtlpEvidence } from "./transport.mjs";
+import type { DecodedLogEvidence } from "./decoders/index.mjs";
+export interface ProjectedOtlpEvidence { teamId: string; sourceId: string; evidenceId: string; proposedSessionId: string; proposedMessageId: string; nativeEventKey: string | null; signal: "logs"|"traces"|"metrics"; raw: RawOtlpEvidence; decoded: DecodedLogEvidence | null }
+export declare function projectOtlpEvidence(evidence: RawOtlpEvidence, context: { teamId: string; sourceId: string; ids: { next(kind: string): string } }): ProjectedOtlpEvidence;
+export declare function projectOtlpBatch(records: RawOtlpEvidence[], context: { teamId: string; sourceId: string; ids: { next(kind: string): string } }): ProjectedOtlpEvidence[];

package/server/otlp/projection.mjs

@@ -0,0 +1,17 @@
+import { decodeLogEvidence } from "./decoders/index.mjs";
+
+function attributes(value) { return value?.attributes ?? []; }
+export function projectOtlpEvidence(evidence, { teamId, sourceId, ids }) {
+  const decoded = evidence.signal === "logs" && evidence.evidenceKind === "log_record"
+    ? decodeLogEvidence({ record: evidence.record, resourceAttributes: attributes(evidence.resource), scopeAttributes: attributes(evidence.scope), receivedAt: evidence.receivedAt })
+    : null;
+  const nativeEventKey = decoded?.identity?.dedup_eligible
+    ? `${decoded.harness}:${decoded.native_session_id ?? ""}:${decoded.identity.native_event_id}` : null;
+  return {
+    teamId, sourceId, evidenceId: ids.next("evidence"), proposedSessionId: ids.next("session"),
+    proposedMessageId: ids.next("message"), nativeEventKey, signal: evidence.signal,
+    raw: evidence, decoded,
+  };
+}
+
+export function projectOtlpBatch(records, context) { return records.map((record) => projectOtlpEvidence(record, context)); }

package/server/otlp/receiver.d.ts

@@ -0,0 +1,3 @@
+import type { RawOtlpEvidence, OtlpSignal } from "./transport.mjs";
+export interface OtlpHttpResponse { status: number; headers: Record<string, string>; body: Uint8Array }
+export declare function createOtlpHttpReceiver<T>(options: { persist(input: { records: RawOtlpEvidence[]; rejectedCount: number; sourceAuthorization: T }): Promise<void>; maxUncompressedBytes?: number }): (request: { signal: OtlpSignal; headers: Headers | Record<string, string | string[] | undefined>; body: Uint8Array | string | AsyncIterable<Uint8Array | string>; sourceAuthorization: T; receivedAt?: number }) => Promise<OtlpHttpResponse>;

package/server/otlp/receiver.mjs

@@ -0,0 +1,36 @@
+import { decodeContentEncoding, decodeOtlpRequest, encodeOtlpError, encodeOtlpResponse, MAX_UNCOMPRESSED_BODY_BYTES, readBoundedBody } from "./transport.mjs";
+
+function header(headers, name) {
+  if (!headers) return undefined;
+  if (typeof headers.get === "function") return headers.get(name) ?? undefined;
+  const key = Object.keys(headers).find((candidate) => candidate.toLowerCase() === name);
+  const value = key ? headers[key] : undefined;
+  return Array.isArray(value) ? value[0] : value;
+}
+
+export function createOtlpHttpReceiver({ persist, maxUncompressedBytes = MAX_UNCOMPRESSED_BODY_BYTES }) {
+  if (typeof persist !== "function") throw new TypeError("persist callback is required");
+  return async function handle({ signal, headers, body, sourceAuthorization, receivedAt = Date.now() }) {
+    const contentType = String(header(headers, "content-type") ?? "").split(";", 1)[0].trim().toLowerCase();
+    const representation = contentType === "application/json" ? "json" : contentType === "application/x-protobuf" ? "protobuf" : null;
+    if (!representation) return response(415, "application/json", await encodeOtlpError({ representation: "json", code: 12, message: "unsupported OTLP content type" }));
+    let decoded;
+    try {
+      const compressed = await readBoundedBody(body, maxUncompressedBytes);
+      const bytes = decodeContentEncoding(compressed, header(headers, "content-encoding"), maxUncompressedBytes);
+      decoded = await decodeOtlpRequest({ signal, representation, bytes, receivedAt });
+    } catch (error) {
+      const status = error?.code === "BODY_TOO_LARGE" ? 413 : error?.code === "UNSUPPORTED_ENCODING" ? 415 : 400;
+      const code = status === 413 ? 8 : status === 415 ? 12 : 3;
+      const message = status === 413 ? "OTLP request body exceeds the configured limit" : status === 415 ? "unsupported OTLP content encoding" : "malformed OTLP request";
+      return response(status, contentType, await encodeOtlpError({ representation, code, message }));
+    }
+    // This callback is the commit boundary. A response is constructed only after it resolves.
+    if (decoded.records.length || decoded.rejected.length) await persist({ records: decoded.records, rejectedCount: decoded.rejected.length, sourceAuthorization });
+    const payload = await encodeOtlpResponse({ signal, representation, rejectedCount: decoded.rejected.length,
+      errorMessage: decoded.rejected.length ? "one or more records were rejected" : "" });
+    return response(200, contentType, payload);
+  };
+}
+
+function response(status, contentType, body) { return { status, headers: { "content-type": contentType }, body }; }