threadwire 0.1.5 → 0.1.6

package/src/cli.js

@@ -1,18 +1,20 @@
 // @ts-check
 
 import {readFile} from "node:fs/promises"
-import {resolve} from "node:path"
+import {randomUUID} from "node:crypto"
+import {isAbsolute, normalize, resolve} from "node:path"
 import {stdin, stderr, stdout} from "node:process"
 import {createFetchTransport} from "./notifiers/fetch-transport.js"
 import {createTelegramSender, parseTelegramTarget} from "./notifiers/telegram.js"
-import {NoticeQueue} from "./notice-queue.js"
 import {createProvider, PROVIDERS} from "./providers/index.js"
-import {Relay} from "./relay.js"
 import {runWorker} from "./run-worker.js"
 import {ActivityLog} from "./activity-log.js"
-import {HermesProtocol} from "./hermes-protocol.js"
-import {buildProviderEnvironment, parseTelegramRequestTimeoutMs, resolveFileBackedSettings} from "./telegram-ingress/config.js"
+import {DelegatedResultAdmission, validateContinuationHandle} from "./delegated-result-admission.js"
+import {buildProviderEnvironment, collectEvidenceRedactions, parseTelegramRequestTimeoutMs, resolveFileBackedSettings} from "./telegram-ingress/config.js"
 import {resolveWorkspaceProfile} from "./workspace-profile.js"
+import {WorkerControl} from "./worker-control.js"
+import {EvidenceStore} from "./evidence-store.js"
+import {ContextBudgetMetrics} from "./context-budget-metrics.js"
 
 const HELP = `Usage: threadwire run --provider <codex|claude|opencode> --target telegram:<chat-id> | telegram:<chat-id>:<thread-id>
   [--process-number <positive-integer>] [--cwd <directory>]
@@ -20,9 +22,12 @@ const HELP = `Usage: threadwire run --provider <codex|claude|opencode> --target
   [--tool-messages] [--max-output-length <positive-integer>]
   [--resume-session <provider-session-id>] [--activity-log <local-jsonl-path>]
   [--prompt <text> | --prompt-file <path> | stdin]
-  [-- <provider arguments...>]`
+  [-- <provider arguments...>]
+       threadwire evidence read --handle <opaque-handle>
+  (--bytes <offset>:<limit> | --lines <start>:<limit> | --query <literal> --context-bytes <limit>)`
 
 /** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, workspaceProfile?: string, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
+/** @typedef {{evidenceRead: true, request: unknown}} EvidenceParsedArguments */
 /**
  * @typedef {{
  *   env?: NodeJS.ProcessEnv,
@@ -31,6 +36,9 @@ const HELP = `Usage: threadwire run --provider <codex|claude|opencode> --target
  *   errorOutput?: NodeJS.WritableStream,
  *   transportFactory?: typeof createFetchTransport,
  *   workerRunner?: typeof runWorker,
+ *   evidenceStore?: EvidenceStore,
+ *   evidenceOwnerScope?: {destinationId: string, runId: string},
+ *   workerControlOptions?: Pick<ConstructorParameters<typeof WorkerControl>[0], "queueOptions">,
  *   workspaceProfileOperations?: import("./workspace-profile.js").WorkspaceProfileOperations
  * }} MainDependencies
  */
@@ -82,6 +90,46 @@ export function parseArguments(arguments_) {
   return /** @type {ParsedArguments} */ (parsed)
 }
 
+/** @param {string[]} arguments_ @returns {EvidenceParsedArguments} */
+function parseEvidenceArguments(arguments_) {
+  if (arguments_[1] !== "read") throw new Error(HELP)
+  /** @type {Record<string, string>} */
+  const options = {}
+  for (let index = 2; index < arguments_.length; index += 2) {
+    const name = arguments_[index]
+    const value = arguments_[index + 1]
+    if (!name || !value || !["--handle", "--bytes", "--lines", "--query", "--context-bytes"].includes(name)) throw new Error(HELP)
+    if (options[name] !== undefined) throw new Error(`Duplicate evidence option: ${name}`)
+    options[name] = value
+  }
+  const handle = options["--handle"]
+  if (!handle) throw new Error("--handle is required")
+  const selectors = ["--bytes", "--lines", "--query"].filter((name) => options[name] !== undefined)
+  if (selectors.length !== 1) throw new Error("Exactly one bounded evidence selector is required")
+  let request
+  if (options["--bytes"]) request = {handle, bytes: rangePair(options["--bytes"], true)}
+  else if (options["--lines"]) request = {handle, lines: rangePair(options["--lines"], false)}
+  else {
+    const context = options["--context-bytes"]
+    if (!context) throw new Error("--context-bytes is required with --query")
+    request = {handle, query: {literal: options["--query"], limit: 1, contextBytes: positiveInteger(context, "--context-bytes")}}
+  }
+  if (options["--query"] === undefined && options["--context-bytes"] !== undefined) throw new Error("--context-bytes requires --query")
+  return {evidenceRead: true, request}
+}
+
+/** @param {string} value @param {boolean} zeroStart */
+function rangePair(value, zeroStart) {
+  const match = /^(\d+):(\d+)$/u.exec(value)
+  if (!match) throw new Error("Evidence range must be <start>:<limit>")
+  const start = Number(match[1])
+  const limit = Number(match[2])
+  if (!Number.isSafeInteger(start) || (!zeroStart && start < 1) || (zeroStart && start < 0) || !Number.isSafeInteger(limit) || limit < 1) {
+    throw new Error("Evidence range must contain bounded safe integers")
+  }
+  return zeroStart ? {offset: start, limit} : {start, limit}
+}
+
 /**
  * @param {string[]} arguments_
  * @param {MainDependencies} [dependencies]
@@ -93,11 +141,24 @@ export async function main(arguments_, dependencies = {}) {
   let environment = sourceEnvironment
   const validateOnly = environment.THREADWIRE_VALIDATE_ONLY === "1"
   try {
-    const parsed = parseArguments(arguments_)
+    const parsed = arguments_[0] === "evidence" ? parseEvidenceArguments(arguments_) : parseArguments(arguments_)
     if ("help" in parsed) {
       if (!validateOnly) output.write(`${HELP}\n`)
       return 0
     }
+    if ("evidenceRead" in parsed) {
+      const root = evidenceRoot(sourceEnvironment.THREADWIRE_EVIDENCE_ROOT)
+      if (!root) throw new Error("THREADWIRE_EVIDENCE_ROOT is required")
+      if (validateOnly) return 0
+      const store = await EvidenceStore.open({root})
+      try {
+        const result = await store.readBearer(parsed.request)
+        output.write(`${JSON.stringify(result)}\n`)
+        return 0
+      } finally {
+        await store.close()
+      }
+    }
     const target = parseTelegramTarget(parsed.target)
     const resolvedWorkspace = parsed.workspaceProfile === undefined
       ? undefined
@@ -106,35 +167,57 @@ export async function main(arguments_, dependencies = {}) {
         dependencies.workspaceProfileOperations
       )
     if (validateOnly) return 0
-    environment = await resolveFileBackedSettings(sourceEnvironment, ["THREADWIRE_TELEGRAM_BOT_TOKEN"])
-    const hermes = new HermesProtocol({output})
+    const metrics = new ContextBudgetMetrics()
+    const admission = new DelegatedResultAdmission({output, metrics})
     let terminalExitCode = 2
+    /** @type {unknown} */
+    let evidenceError
     /** @type {ActivityLog | undefined} */
     let activity
+    /** @type {Awaited<ReturnType<EvidenceStore["createArtifact"]>> | undefined} */
+    let evidence
+    /** @type {EvidenceStore | undefined} */
+    let ownedEvidenceStore
+    let evidencePayloadBytes = 0
     try {
+      environment = await resolveFileBackedSettings(sourceEnvironment, ["THREADWIRE_TELEGRAM_BOT_TOKEN"])
       const prompt = await readPrompt(parsed, dependencies.input ?? stdin)
+      const configuredEvidenceRoot = evidenceRoot(sourceEnvironment.THREADWIRE_EVIDENCE_ROOT)
+      if (dependencies.evidenceStore === undefined && configuredEvidenceRoot !== undefined) {
+        ownedEvidenceStore = await EvidenceStore.open({root: configuredEvidenceRoot})
+      }
+      const evidenceStore = dependencies.evidenceStore ?? ownedEvidenceStore
+      if (evidenceStore !== undefined) {
+        const evidenceOwner = dependencies.evidenceOwnerScope ?? evidenceStore.createOwnerScope({
+          destinationId: `${target.chatId}:${target.threadId ?? "dm"}`,
+          runId: randomUUID()
+        })
+        evidence = await evidenceStore.createArtifact(evidenceOwner, {
+          contentType: "text/plain; charset=utf-8",
+          redactions: await collectEvidenceRedactions(environment)
+        })
+      }
+      if (evidence !== undefined) {
+        const promptEvidence = `prompt\n${prompt}\nprovider-stream\n`
+        await evidence.append("prompt", promptEvidence)
+        evidencePayloadBytes += Buffer.byteLength(promptEvidence, "utf8")
+      }
       const providerEnvironment = buildProviderEnvironment(environment)
       const provider = createProvider(parsed.provider, parsed.providerArguments, prompt, parsed.resumeSession, providerEnvironment)
+      if (parsed.resumeSession !== undefined) admission.setContinuationHandle(parsed.resumeSession)
       if (parsed.workspaceProfile !== undefined) {
         if (resolvedWorkspace === undefined) throw new Error("Workspace profile resolution failed")
-        hermes.write({
-          type: "execution_environment",
-          profile: resolvedWorkspace.profile,
-          environment: "container",
-          repositoryPath: resolvedWorkspace.cwd,
-          revision: resolvedWorkspace.revision,
-          sourceIdentity: resolvedWorkspace.sourceIdentity
-        })
       }
       const token = environment.THREADWIRE_TELEGRAM_BOT_TOKEN
       if (!token) throw new Error("THREADWIRE_TELEGRAM_BOT_TOKEN is required")
       const transport = (dependencies.transportFactory ?? createFetchTransport)(token, undefined, parseTelegramRequestTimeoutMs(environment))
-      const queue = new NoticeQueue({sender: createTelegramSender(target, transport)})
-      const relay = new Relay({
-        queue,
+      const control = new WorkerControl({
+        sender: createTelegramSender(target, transport),
         processNumber: parsed.processNumber ?? process.pid,
         toolMessages: parsed.toolMessages,
-        ...(parsed.maxOutputLength === undefined ? {} : {maxOutputLength: parsed.maxOutputLength})
+        ...(dependencies.workerControlOptions ?? {}),
+        ...(parsed.maxOutputLength === undefined ? {} : {maxOutputLength: parsed.maxOutputLength}),
+        metrics
       })
       activity = parsed.activityLog === undefined ? undefined : new ActivityLog(parsed.activityLog)
       if (activity && resolvedWorkspace) {
@@ -152,30 +235,121 @@ export async function main(arguments_, dependencies = {}) {
         environment: providerEnvironment,
         parse: provider.parse,
         onEvent: (event) => {
-          relay.accept(event)
-          hermes.accept(event)
+          validateNormalizedWorkerEvent(event)
+          if (event.type !== "text-delta") {
+            metrics.recordRejected(`${event.type}_progress`, Buffer.byteLength(JSON.stringify(event), "utf8"))
+          }
+          acceptAdmissionEvent(admission, event)
+          return control.accept(event)
         },
         onSpawn: (pid) => {
           if (activity && pid !== undefined) activity.recordStarted(provider.name, pid)
         },
         onRecord: (record) => {
+          metrics.recordParsedProviderRecord("provider_stdout")
           const id = provider.sessionId(record)
-          if (id !== undefined) activity?.recordSession(provider.name, id)
+          if (id !== undefined) {
+            admission.setContinuationHandle(id)
+            activity?.recordSession(provider.name, id)
+          }
+        },
+        onStdoutChunk: (chunk) => {
+          metrics.recordRawChildChunk("provider_stdout", chunk.length)
+          metrics.recordRejected("provider_stream", chunk.length)
+          if (evidence === undefined) return undefined
+          return evidence.append("provider-stdout", chunk).then(() => { evidencePayloadBytes += chunk.length })
+        },
+        onStderrChunk: (chunk) => {
+          metrics.recordRawChildChunk("provider_stderr", chunk.length)
+          metrics.recordRejected("stderr", chunk.length)
+          if (evidence === undefined) return undefined
+          return evidence.append("provider-stderr", chunk).then(() => { evidencePayloadBytes += chunk.length })
         }
       })
-      await relay.close()
+      await control.close()
       terminalExitCode = exitCode
-      return exitCode
     } finally {
-      hermes.complete(terminalExitCode)
+      if (evidence !== undefined) {
+        try {
+          admission.addArtifactHandle(evidence.handle)
+          const terminal = {state: /** @type {"completed" | "failed"} */ (terminalExitCode === 0 ? "completed" : "failed"), exitCode: terminalExitCode}
+          metrics.recordAdmission(admission.preview(terminal))
+          const projectedArtifactBytes = metrics.projectSelfInclusiveArtifact(evidencePayloadBytes, 1)
+          await evidence.append("context-metrics", `${JSON.stringify(metrics.snapshot())}\n`)
+          const artifact = await evidence.finalize()
+          assertArtifactProjection(artifact.bytes, projectedArtifactBytes)
+        } catch (error) {
+          await evidence.abort()
+          admission.removeArtifactHandle(evidence.handle)
+          metrics.clearArtifact()
+          terminalExitCode = 2
+          evidenceError = error
+        }
+      }
+      admission.complete({state: terminalExitCode === 0 ? "completed" : "failed", exitCode: terminalExitCode})
+      errorOutput.write(`threadwire-context-metrics ${JSON.stringify(metrics.conciseDiagnostic())}\n`)
       activity?.close()
+      await ownedEvidenceStore?.close()
     }
+    if (evidenceError !== undefined) throw evidenceError
+    return terminalExitCode
   } catch (error) {
     errorOutput.write(`threadwire: ${safeMessage(error)}\n`)
     return 2
   }
 }
 
+/** @param {string | undefined} value */
+function evidenceRoot(value) {
+  if (value === undefined) return undefined
+  if (!isAbsolute(value) || normalize(value) !== value) throw new Error("THREADWIRE_EVIDENCE_ROOT must be a normalized absolute path")
+  return value
+}
+
+/** @param {number} actual @param {number} projected */
+function assertArtifactProjection(actual, projected) {
+  if (actual !== projected) throw new Error("Context metrics artifact projection mismatch")
+}
+
+/** @param {DelegatedResultAdmission} admission @param {import("./types.js").WorkerEvent} event */
+function acceptAdmissionEvent(admission, event) {
+  if (event.type === "text-delta") admission.acceptConclusionEvent(event)
+}
+
+/** @param {unknown} event */
+function validateNormalizedWorkerEvent(event) {
+  if (!isPlainObject(event) || typeof event.type !== "string") {
+    throw new Error("invalid normalized worker event")
+  }
+  if (event.type === "text-delta") {
+    if (!hasExactEnumerableFields(event, ["type", "text", "streamId"]) || typeof event.text !== "string" || typeof event.streamId !== "string") {
+      throw new Error("invalid normalized worker event")
+    }
+    return
+  }
+  if (event.type === "lifecycle") {
+    if (
+      !hasExactEnumerableFields(event, ["type", "phase", "summary"])
+      || (event.phase !== "started" && event.phase !== "completed" && event.phase !== "failed")
+      || typeof event.summary !== "string"
+    ) throw new Error("invalid normalized worker event")
+    return
+  }
+  if (event.type === "diagnostic") {
+    if (
+      !hasExactEnumerableFields(event, ["type", "level", "summary"])
+      || (event.level !== "warning" && event.level !== "error")
+      || typeof event.summary !== "string"
+    ) throw new Error("invalid normalized worker event")
+    return
+  }
+  if (event.type === "tool") {
+    if (!isToolEventShape(event)) throw new Error("invalid normalized worker event")
+    return
+  }
+  throw new Error("Worker emitted an unknown normalized event kind")
+}
+
 /** @param {ParsedArguments} parsed @param {NodeJS.ReadableStream & {isTTY?: boolean}} input */
 async function readPrompt(parsed, input) {
   let prompt
@@ -207,6 +381,53 @@ function positiveInteger(value, option) {
 
 /** @param {string} value */
 function sessionId(value) {
-  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u.test(value)) throw new Error("--resume-session must be a valid provider session ID")
-  return value
+  try {
+    return validateContinuationHandle(value)
+  } catch {
+    throw new Error("--resume-session must be a valid provider session ID")
+  }
+}
+
+/** @param {Record<string, unknown>} event */
+function isToolEventShape(event) {
+  const allowed = event.phase === "finished"
+    ? ["type", "phase", "name", "key", "detail", "output"]
+    : ["type", "phase", "name", "key", "detail"]
+  if (
+    !hasOnlyAllowedEnumerableFields(event, allowed, ["type", "phase", "name", "key"])
+    || (event.phase !== "started" && event.phase !== "finished")
+    || typeof event.name !== "string"
+    || typeof event.key !== "string"
+    || (event.detail !== undefined && typeof event.detail !== "string")
+    || (event.output !== undefined && typeof event.output !== "string")
+  ) return false
+  if (event.phase === "started" && event.output !== undefined) return false
+  return true
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+/** @param {Record<string, unknown>} value @param {string[]} expected */
+function hasExactEnumerableFields(value, expected) {
+  const fields = Reflect.ownKeys(value)
+  return fields.length === expected.length && fields.every((field) => (
+    typeof field === "string"
+    && expected.includes(field)
+    && Object.prototype.propertyIsEnumerable.call(value, field)
+  ))
+}
+
+/** @param {Record<string, unknown>} value @param {string[]} allowed @param {string[]} required */
+function hasOnlyAllowedEnumerableFields(value, allowed, required) {
+  const fields = Reflect.ownKeys(value)
+  return required.every((field) => Object.prototype.propertyIsEnumerable.call(value, field)) && fields.every((field) => (
+    typeof field === "string"
+    && allowed.includes(field)
+    && Object.prototype.propertyIsEnumerable.call(value, field)
+  ))
 }

package/src/context-budget-metrics.js

@@ -0,0 +1,180 @@
+// @ts-check
+
+export const METRIC_COUNTER_LIMIT = 2_147_483_647
+export const CONTEXT_GROWTH_METADATA_ALLOWANCE_BYTES = 256
+
+const RAW_CLASSES = ["provider_stdout", "provider_stderr"]
+const REJECTED_CLASSES = ["provider_stream", "stderr", "lifecycle_progress", "diagnostic_progress", "tool_progress"]
+const PROGRESS_CLASSES = ["assistant", "lifecycle", "diagnostic", "tool"]
+const ENVELOPE_FIELDS = [
+  "version", "type", "state", "exitCode", "conclusion", "blocker", "decisionRequest",
+  "continuationHandle", "artifactHandles", "references", "validationSummary"
+]
+
+export class ContextBudgetMetrics {
+  constructor() {
+    this.streamBytes = 0
+    this.streamChunks = 0
+    this.streamBytesByClass = counters(RAW_CLASSES)
+    this.streamChunksByClass = counters(RAW_CLASSES)
+    this.parsedRecords = 0
+    this.parsedRecordsByClass = counters(RAW_CLASSES)
+    this.rejectedBytes = counters(REJECTED_CLASSES)
+    this.rejectedEvents = counters(REJECTED_CLASSES)
+    this.progress = progressCounters()
+    this.artifactBytes = 0
+    this.artifactHandles = 0
+    this.admittedBytes = 0
+    this.admittedTokens = 0
+    this.admittedEnvelopeFields = counters(ENVELOPE_FIELDS)
+  }
+
+  /** @param {string} metricClass @param {number} bytes */
+  recordRawChildChunk(metricClass, bytes) {
+    addClass(this.streamBytesByClass, metricClass, bytes)
+    addClass(this.streamChunksByClass, metricClass, 1)
+    this.streamBytes = saturatingAdd(this.streamBytes, bytes)
+    this.streamChunks = saturatingAdd(this.streamChunks, 1)
+  }
+
+  /** Backward-compatible name for callers outside the package. @param {string} metricClass @param {number} bytes */
+  recordRawChildEvent(metricClass, bytes) {
+    this.recordRawChildChunk(metricClass, bytes)
+  }
+
+  /** @param {string} metricClass @param {number} [records] */
+  recordParsedProviderRecord(metricClass, records = 1) {
+    addClass(this.parsedRecordsByClass, metricClass, records)
+    this.parsedRecords = saturatingAdd(this.parsedRecords, records)
+  }
+
+  /** @param {string} metricClass @param {number} bytes */
+  recordRejected(metricClass, bytes) {
+    addClass(this.rejectedBytes, metricClass, bytes)
+    addClass(this.rejectedEvents, metricClass, 1)
+  }
+
+  /** @param {string} metricClass @param {number} bytes */
+  recordProgress(metricClass, bytes, outcome = "delivered") {
+    if (!Object.prototype.hasOwnProperty.call(this.progress, outcome)) throw new Error("Invalid context progress outcome")
+    const target = this.progress[outcome]
+    if (target === undefined) throw new Error("Invalid context progress outcome")
+    addClass(target.bytesByClass, metricClass, bytes)
+    addClass(target.eventsByClass, metricClass, 1)
+    target.bytes = saturatingAdd(target.bytes, bytes)
+    target.events = saturatingAdd(target.events, 1)
+  }
+
+  /** @param {number} bytes @param {number} handles */
+  recordArtifact(bytes, handles) {
+    this.artifactBytes = saturatingAdd(this.artifactBytes, bytes)
+    this.artifactHandles = saturatingAdd(this.artifactHandles, handles)
+  }
+
+  /**
+   * Set the final logical payload size for an artifact containing this snapshot.
+   * The returned fixed point includes the snapshot's own newline-terminated bytes.
+   * @param {number} bytesBeforeMetrics @param {number} handles
+   */
+  projectSelfInclusiveArtifact(bytesBeforeMetrics, handles) {
+    const base = bounded(bytesBeforeMetrics)
+    this.artifactHandles = bounded(handles)
+    this.artifactBytes = base
+    for (let iteration = 0; iteration < 16; iteration += 1) {
+      const projected = saturatingAdd(base, Buffer.byteLength(`${JSON.stringify(this.snapshot())}\n`, "utf8"))
+      if (projected === this.artifactBytes) return projected
+      this.artifactBytes = projected
+    }
+    throw new Error("Context metrics artifact projection did not converge")
+  }
+
+  clearArtifact() {
+    this.artifactBytes = 0
+    this.artifactHandles = 0
+  }
+
+  /** @param {Record<string, unknown>} envelope */
+  recordAdmission(envelope) {
+    const serialized = `${JSON.stringify(envelope)}\n`
+    this.admittedBytes = bounded(Buffer.byteLength(serialized, "utf8"))
+    this.admittedTokens = bounded(Math.ceil(this.admittedBytes / 4))
+    for (const field of ENVELOPE_FIELDS) {
+      if (!Object.prototype.hasOwnProperty.call(envelope, field)) continue
+      this.admittedEnvelopeFields[field] = bounded(Buffer.byteLength(JSON.stringify(envelope[field]), "utf8"))
+    }
+  }
+
+  snapshot() {
+    return {
+      version: 1,
+      units: {bytes: "utf8", tokens: "estimated_ceiling_bytes_div_4", events: "count"},
+      rawChild: {
+        streamBytes: this.streamBytes,
+        streamChunks: this.streamChunks,
+        streamBytesByClass: {...this.streamBytesByClass},
+        streamChunksByClass: {...this.streamChunksByClass},
+        parsedRecords: this.parsedRecords,
+        parsedRecordsByClass: {...this.parsedRecordsByClass}
+      },
+      admitted: {bytes: this.admittedBytes, estimatedTokens: this.admittedTokens},
+      rejected: {bytesByClass: {...this.rejectedBytes}, eventsByClass: {...this.rejectedEvents}},
+      artifacts: {bytes: this.artifactBytes, handles: this.artifactHandles},
+      progress: Object.fromEntries(Object.entries(this.progress).map(([outcome, values]) => [
+        outcome,
+        {bytes: values.bytes, events: values.events, bytesByClass: {...values.bytesByClass}, eventsByClass: {...values.eventsByClass}}
+      ])),
+      admittedEnvelopeFields: {...this.admittedEnvelopeFields},
+      parentContextDeltaBytes: this.admittedBytes
+    }
+  }
+
+  conciseDiagnostic() {
+    return {
+      version: 1,
+      rawBytes: this.streamBytes,
+      rawChunks: this.streamChunks,
+      parsedRecords: this.parsedRecords,
+      admittedBytes: this.admittedBytes,
+      rejectedBytes: sumCounters(this.rejectedBytes),
+      artifactBytes: this.artifactBytes,
+      artifactHandles: this.artifactHandles,
+      progressEvents: this.progress.delivered?.events ?? 0,
+      parentContextDeltaBytes: this.admittedBytes
+    }
+  }
+}
+
+/** @returns {Record<string, {bytes: number, events: number, bytesByClass: Record<string, number>, eventsByClass: Record<string, number>}>} */
+function progressCounters() {
+  return Object.fromEntries(["attempted", "suppressed", "coalesced", "delivered"].map((outcome) => [
+    outcome,
+    {bytes: 0, events: 0, bytesByClass: counters(PROGRESS_CLASSES), eventsByClass: counters(PROGRESS_CLASSES)}
+  ]))
+}
+
+/** @param {string[]} classes */
+function counters(classes) {
+  return Object.fromEntries(classes.map((metricClass) => [metricClass, 0]))
+}
+
+/** @param {Record<string, number>} target @param {string} metricClass @param {number} increment */
+function addClass(target, metricClass, increment) {
+  if (!Object.prototype.hasOwnProperty.call(target, metricClass)) throw new Error("Invalid context metric class")
+  target[metricClass] = saturatingAdd(target[metricClass] ?? 0, increment)
+}
+
+/** @param {number} current @param {number} increment */
+function saturatingAdd(current, increment) {
+  return Math.min(METRIC_COUNTER_LIMIT, current + bounded(increment))
+}
+
+/** @param {number} value */
+function bounded(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("Invalid context metric counter")
+  return Math.min(value, METRIC_COUNTER_LIMIT)
+}
+
+/** @param {Record<string, number>} values */
+function sumCounters(values) {
+  return Object.values(values).reduce((total, value) => saturatingAdd(total, value), 0)
+}