@prisma/streams-server 0.1.1 → 0.1.3

package/src/profiles/evlog.ts

@@ -0,0 +1,299 @@
+import { Result } from "better-result";
+import type {
+  CachedStreamProfile,
+  PreparedJsonRecord,
+  StreamProfileDefinition,
+  StreamProfilePersistResult,
+  StreamProfileReadResult,
+  StreamProfileSpec,
+} from "./profile";
+import {
+  cloneStreamProfileSpec,
+  expectPlainObjectResult,
+  isPlainObject,
+  normalizeProfileContentType,
+  parseStoredProfileJsonResult,
+  rejectUnknownKeysResult,
+} from "./profile";
+import { buildEvlogDefaultRegistry } from "./evlog/schema";
+
+export type EvlogStreamProfile = {
+  kind: "evlog";
+  redactKeys?: string[];
+};
+
+const DEFAULT_REDACT_KEYS = ["password", "token", "secret", "authorization", "cookie", "apikey"] as const;
+const REDACTED_VALUE = "[REDACTED]";
+const EVLOG_RESERVED_FIELDS = new Set([
+  "timestamp",
+  "level",
+  "service",
+  "environment",
+  "version",
+  "region",
+  "requestId",
+  "traceId",
+  "spanId",
+  "method",
+  "path",
+  "status",
+  "duration",
+  "message",
+  "why",
+  "fix",
+  "link",
+  "sampling",
+  "redaction",
+  "context",
+]);
+
+type RedactionResult = {
+  value: unknown;
+  paths: string[];
+};
+
+function cloneEvlogProfile(profile: EvlogStreamProfile): EvlogStreamProfile {
+  return cloneStreamProfileSpec(profile) as EvlogStreamProfile;
+}
+
+function cloneEvlogCache(cache: CachedStreamProfile | null): CachedStreamProfile | null {
+  if (!cache || cache.profile.kind !== "evlog") return null;
+  return {
+    profile: cloneEvlogProfile(cache.profile as EvlogStreamProfile),
+    updatedAtMs: cache.updatedAtMs,
+  };
+}
+
+function isEvlogProfile(profile: StreamProfileSpec | null | undefined): profile is EvlogStreamProfile {
+  return !!profile && profile.kind === "evlog";
+}
+
+function parseRedactKeysResult(raw: unknown, path: string): Result<string[] | undefined, { message: string }> {
+  if (raw === undefined) return Result.ok(undefined);
+  if (!Array.isArray(raw)) return Result.err({ message: `${path} must be an array of strings` });
+  if (raw.length > 64) return Result.err({ message: `${path} too large (max 64)` });
+
+  const normalized: string[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (typeof item !== "string") return Result.err({ message: `${path} must be an array of strings` });
+    const value = item.trim().toLowerCase();
+    if (value === "") return Result.err({ message: `${path} must not contain empty strings` });
+    if (seen.has(value)) continue;
+    seen.add(value);
+    normalized.push(value);
+  }
+  return Result.ok(normalized);
+}
+
+function validateEvlogProfileResult(raw: unknown, path: string): Result<EvlogStreamProfile, { message: string }> {
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  if (objRes.value.kind !== "evlog") {
+    return Result.err({ message: `${path}.kind must be evlog` });
+  }
+  const keyCheck = rejectUnknownKeysResult(objRes.value, ["kind", "redactKeys"], path);
+  if (Result.isError(keyCheck)) return keyCheck;
+  const redactKeysRes = parseRedactKeysResult(objRes.value.redactKeys, `${path}.redactKeys`);
+  if (Result.isError(redactKeysRes)) return redactKeysRes;
+  return Result.ok(redactKeysRes.value ? { kind: "evlog", redactKeys: redactKeysRes.value } : { kind: "evlog" });
+}
+
+function normalizeString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+function normalizeTraceField(input: Record<string, unknown>, field: "traceId" | "spanId"): string | null {
+  const direct = normalizeString(input[field]);
+  if (direct) return direct;
+  const traceContext = isPlainObject(input.traceContext) ? input.traceContext : null;
+  return traceContext ? normalizeString(traceContext[field]) : null;
+}
+
+function normalizeOptionalNumber(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  return null;
+}
+
+function normalizeOptionalInteger(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value) && Number.isInteger(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    if (Number.isFinite(n) && Number.isInteger(n)) return n;
+  }
+  return null;
+}
+
+function deriveLevel(input: Record<string, unknown>, status: number | null): string {
+  const direct = normalizeString(input.level)?.toLowerCase();
+  if (direct === "debug" || direct === "info" || direct === "warn" || direct === "error") {
+    return direct;
+  }
+  if (normalizeString(input.why) || normalizeString(input.fix) || normalizeString(input.link)) return "error";
+  if (status != null && status >= 500) return "error";
+  if (status != null && status >= 400) return "warn";
+  return "info";
+}
+
+function redactValue(value: unknown, redactKeys: Set<string>, path = ""): RedactionResult {
+  if (Array.isArray(value)) {
+    const items = value.map((item, index) => redactValue(item, redactKeys, path === "" ? String(index) : `${path}.${index}`));
+    return {
+      value: items.map((item) => item.value),
+      paths: items.flatMap((item) => item.paths),
+    };
+  }
+  if (!isPlainObject(value)) return { value: structuredClone(value), paths: [] };
+
+  const out: Record<string, unknown> = {};
+  const paths: string[] = [];
+  for (const [key, raw] of Object.entries(value)) {
+    const keyPath = path === "" ? key : `${path}.${key}`;
+    if (redactKeys.has(key.toLowerCase())) {
+      out[key] = REDACTED_VALUE;
+      paths.push(keyPath);
+      continue;
+    }
+    const nested = redactValue(raw, redactKeys, keyPath);
+    out[key] = nested.value;
+    paths.push(...nested.paths);
+  }
+  return { value: out, paths };
+}
+
+function buildContext(input: Record<string, unknown>): Record<string, unknown> {
+  const context: Record<string, unknown> = isPlainObject(input.context) ? structuredClone(input.context) : {};
+  for (const [key, value] of Object.entries(input)) {
+    if (EVLOG_RESERVED_FIELDS.has(key)) continue;
+    context[key] = structuredClone(value);
+  }
+  if (!isPlainObject(input.context) && Object.prototype.hasOwnProperty.call(input, "context")) {
+    context.context = structuredClone(input.context);
+  }
+  return context;
+}
+
+function normalizeEvlogRecordResult(profile: EvlogStreamProfile, value: unknown): Result<PreparedJsonRecord, { message: string }> {
+  const objRes = expectPlainObjectResult(value, "evlog record");
+  if (Result.isError(objRes)) return objRes;
+  const input = objRes.value;
+
+  const status = normalizeOptionalInteger(input.status);
+  const duration = normalizeOptionalNumber(input.duration);
+  const timestamp = normalizeString(input.timestamp) ?? new Date().toISOString();
+  const requestId = normalizeString(input.requestId);
+  const traceId = normalizeTraceField(input, "traceId");
+  const spanId = normalizeTraceField(input, "spanId");
+  const contextRes = redactValue(buildContext(input), new Set([...DEFAULT_REDACT_KEYS, ...(profile.redactKeys ?? [])]));
+
+  const normalized = {
+    timestamp,
+    level: deriveLevel(input, status),
+    service: normalizeString(input.service),
+    environment: normalizeString(input.environment),
+    version: normalizeString(input.version),
+    region: normalizeString(input.region),
+    requestId,
+    traceId,
+    spanId,
+    method: normalizeString(input.method),
+    path: normalizeString(input.path),
+    status,
+    duration,
+    message: normalizeString(input.message),
+    why: normalizeString(input.why),
+    fix: normalizeString(input.fix),
+    link: normalizeString(input.link),
+    sampling: Object.prototype.hasOwnProperty.call(input, "sampling") ? structuredClone(input.sampling) : null,
+    redaction: { keys: contextRes.paths },
+    context: contextRes.value as Record<string, unknown>,
+  };
+
+  return Result.ok({
+    value: normalized,
+    routingKey: requestId ?? traceId ?? null,
+  });
+}
+
+export const EVLOG_STREAM_PROFILE_DEFINITION: StreamProfileDefinition = {
+  kind: "evlog",
+  usesStoredProfileRow: true,
+
+  defaultProfile(): EvlogStreamProfile {
+    return { kind: "evlog" };
+  },
+
+  validateResult(raw, path) {
+    return validateEvlogProfileResult(raw, path);
+  },
+
+  readProfileResult({ row, cached }): Result<StreamProfileReadResult, { message: string }> {
+    if (!row) return Result.ok({ profile: { kind: "evlog" }, cache: null });
+    const cachedCopy = cloneEvlogCache(cached);
+    if (cachedCopy && cachedCopy.updatedAtMs === row.updated_at_ms) {
+      return Result.ok({
+        profile: cloneEvlogProfile(cachedCopy.profile as EvlogStreamProfile),
+        cache: cachedCopy,
+      });
+    }
+    const parsedRes = parseStoredProfileJsonResult(row.profile_json);
+    if (Result.isError(parsedRes)) return parsedRes;
+    const profileRes = validateEvlogProfileResult(parsedRes.value, "profile");
+    if (Result.isError(profileRes)) return profileRes;
+    const profile = cloneEvlogProfile(profileRes.value);
+    return Result.ok({
+      profile: cloneEvlogProfile(profile),
+      cache: { profile, updatedAtMs: row.updated_at_ms },
+    });
+  },
+
+  persistProfileResult({ db, registry, stream, streamRow, profile }): Result<StreamProfilePersistResult, { kind: "bad_request"; message: string; code?: string }> {
+    if (!isEvlogProfile(profile)) {
+      return Result.err({ kind: "bad_request", message: "invalid evlog profile" });
+    }
+    const contentType = normalizeProfileContentType(streamRow.content_type);
+    if (contentType !== "application/json") {
+      return Result.err({
+        kind: "bad_request",
+        message: "evlog profile requires application/json stream content-type",
+      });
+    }
+    if (streamRow.profile !== "evlog" && streamRow.next_offset > 0n) {
+      return Result.err({
+        kind: "bad_request",
+        message: "evlog profile must be installed before appending data",
+      });
+    }
+
+    const persistedProfile = cloneEvlogProfile(profile);
+    const registryRes = registry.replaceRegistryResult(stream, buildEvlogDefaultRegistry(stream));
+    if (Result.isError(registryRes)) {
+      return Result.err({ kind: "bad_request", message: registryRes.error.message });
+    }
+    db.updateStreamProfile(stream, persistedProfile.kind);
+    db.upsertStreamProfile(stream, JSON.stringify(persistedProfile));
+    db.deleteStreamTouchState(stream);
+    const row = db.getStreamProfile(stream);
+    return Result.ok({
+      profile: cloneEvlogProfile(persistedProfile),
+      cache: {
+        profile: persistedProfile,
+        updatedAtMs: row?.updated_at_ms ?? db.nowMs(),
+      },
+      schemaRegistry: registryRes.value,
+    });
+  },
+
+  jsonIngest: {
+    prepareRecordResult({ profile, value }) {
+      if (!isEvlogProfile(profile)) return Result.err({ message: "invalid evlog profile" });
+      return normalizeEvlogRecordResult(profile, value);
+    },
+  },
+};

package/src/profiles/generic.ts

@@ -0,0 +1,47 @@
+import { Result } from "better-result";
+import type {
+  StreamProfileDefinition,
+  StreamProfilePersistResult,
+  StreamProfileReadResult,
+} from "./profile";
+import { cloneStreamProfileSpec, expectPlainObjectResult, rejectUnknownKeysResult, type StreamProfileSpec } from "./profile";
+
+export type GenericStreamProfile = {
+  kind: "generic";
+};
+
+function cloneGenericProfile(): GenericStreamProfile {
+  return { kind: "generic" };
+}
+
+export const GENERIC_STREAM_PROFILE_DEFINITION: StreamProfileDefinition = {
+  kind: "generic",
+  usesStoredProfileRow: false,
+
+  defaultProfile(): GenericStreamProfile {
+    return cloneGenericProfile();
+  },
+
+  validateResult(raw, path) {
+    const objRes = expectPlainObjectResult(raw, path);
+    if (Result.isError(objRes)) return objRes;
+    if (objRes.value.kind !== "generic") {
+      return Result.err({ message: `${path}.kind must be generic` });
+    }
+    const keyCheck = rejectUnknownKeysResult(objRes.value, ["kind"], path);
+    if (Result.isError(keyCheck)) return keyCheck;
+    return Result.ok(cloneGenericProfile());
+  },
+
+  readProfileResult(): Result<StreamProfileReadResult, { message: string }> {
+    return Result.ok({ profile: cloneGenericProfile(), cache: null });
+  },
+
+  persistProfileResult({ db, stream }): Result<StreamProfilePersistResult, { kind: "bad_request"; message: string; code?: string }> {
+    db.updateStreamProfile(stream, "generic");
+    db.deleteStreamProfile(stream);
+    db.deleteStreamTouchState(stream);
+    const profile: StreamProfileSpec = cloneStreamProfileSpec(cloneGenericProfile());
+    return Result.ok({ profile, cache: null, schemaRegistry: null });
+  },
+};

package/src/profiles/index.ts

@@ -0,0 +1,205 @@
+import { Result } from "better-result";
+import type { SqliteDurableStore, StreamRow } from "../db/db";
+import type { SchemaRegistry, SchemaRegistryStore } from "../schema/registry";
+import { LruCache } from "../util/lru";
+import { dsError } from "../util/ds_error.ts";
+import { GENERIC_STREAM_PROFILE_DEFINITION } from "./generic";
+import { EVLOG_STREAM_PROFILE_DEFINITION } from "./evlog";
+import { METRICS_STREAM_PROFILE_DEFINITION } from "./metrics";
+import {
+  buildStreamProfileResource,
+  cloneStreamProfileSpec,
+  DEFAULT_STREAM_PROFILE,
+  parseProfileUpdateEnvelopeResult,
+  readProfileKindResult,
+  type CachedStreamProfile,
+  type StoredProfileRow,
+  type StreamProfileJsonIngestCapability,
+  type StreamProfileDefinition,
+  type StreamProfileMetricsCapability,
+  type StreamProfileReadError,
+  type StreamProfileResource,
+  type StreamProfileSpec,
+  type StreamProfileMutationError,
+  type StreamTouchCapability,
+} from "./profile";
+import { STATE_PROTOCOL_STREAM_PROFILE_DEFINITION } from "./stateProtocol";
+
+export * from "./profile";
+export { EVLOG_STREAM_PROFILE_DEFINITION } from "./evlog";
+export { GENERIC_STREAM_PROFILE_DEFINITION } from "./generic";
+export { METRICS_STREAM_PROFILE_DEFINITION } from "./metrics";
+export { STATE_PROTOCOL_STREAM_PROFILE_DEFINITION } from "./stateProtocol";
+
+const STREAM_PROFILE_DEFINITIONS: Record<string, StreamProfileDefinition> = {
+  [EVLOG_STREAM_PROFILE_DEFINITION.kind]: EVLOG_STREAM_PROFILE_DEFINITION,
+  [GENERIC_STREAM_PROFILE_DEFINITION.kind]: GENERIC_STREAM_PROFILE_DEFINITION,
+  [METRICS_STREAM_PROFILE_DEFINITION.kind]: METRICS_STREAM_PROFILE_DEFINITION,
+  [STATE_PROTOCOL_STREAM_PROFILE_DEFINITION.kind]: STATE_PROTOCOL_STREAM_PROFILE_DEFINITION,
+};
+// New built-in profiles are wired here. Core runtime paths must resolve the
+// definition and dispatch through its hooks rather than branching on profile
+// kinds directly.
+
+function supportedProfileKindsMessage(): string {
+  return listSupportedStreamProfileKinds().join("|");
+}
+
+export function listSupportedStreamProfileKinds(): string[] {
+  return Object.keys(STREAM_PROFILE_DEFINITIONS);
+}
+
+export function resolveStreamProfileDefinition(kind: string | null | undefined): StreamProfileDefinition | null {
+  const normalized = typeof kind === "string" && kind !== "" ? kind : DEFAULT_STREAM_PROFILE;
+  return STREAM_PROFILE_DEFINITIONS[normalized] ?? null;
+}
+
+function resolveStreamProfileDefinitionResult(
+  kind: string | null | undefined
+): Result<StreamProfileDefinition, StreamProfileReadError> {
+  const normalized = typeof kind === "string" && kind !== "" ? kind : DEFAULT_STREAM_PROFILE;
+  const definition = resolveStreamProfileDefinition(normalized);
+  if (!definition) {
+    return Result.err({ kind: "invalid_profile", message: `unknown stream profile: ${normalized}` });
+  }
+  return Result.ok(definition);
+}
+
+function cloneCachedProfile(cache: CachedStreamProfile | null): CachedStreamProfile | null {
+  if (!cache) return null;
+  return {
+    profile: cloneStreamProfileSpec(cache.profile),
+    updatedAtMs: cache.updatedAtMs,
+  };
+}
+
+export function parseProfileUpdateResult(body: unknown): Result<StreamProfileSpec, { message: string }> {
+  const envelopeRes = parseProfileUpdateEnvelopeResult(body);
+  if (Result.isError(envelopeRes)) return envelopeRes;
+  const kindRes = readProfileKindResult(envelopeRes.value, "profile");
+  if (Result.isError(kindRes)) return kindRes;
+  const definition = resolveStreamProfileDefinition(kindRes.value);
+  if (!definition) {
+    return Result.err({ message: `profile.kind must be ${supportedProfileKindsMessage()}` });
+  }
+  return definition.validateResult(envelopeRes.value, "profile");
+}
+
+export function resolveTouchCapability(profile: StreamProfileSpec | null | undefined): StreamTouchCapability | null {
+  if (!profile) return null;
+  return resolveStreamProfileDefinition(profile.kind)?.touch ?? null;
+}
+
+export function resolveJsonIngestCapability(profile: StreamProfileSpec | null | undefined): StreamProfileJsonIngestCapability | null {
+  if (!profile) return null;
+  return resolveStreamProfileDefinition(profile.kind)?.jsonIngest ?? null;
+}
+
+export function resolveMetricsCapability(profile: StreamProfileSpec | null | undefined): StreamProfileMetricsCapability | null {
+  if (!profile) return null;
+  return resolveStreamProfileDefinition(profile.kind)?.metrics ?? null;
+}
+
+export function resolveEnabledTouchCapability(
+  profile: StreamProfileSpec | null | undefined
+): { capability: StreamTouchCapability; touchCfg: NonNullable<ReturnType<StreamTouchCapability["getTouchConfig"]>> } | null {
+  const capability = resolveTouchCapability(profile);
+  if (!profile || !capability) return null;
+  const touchCfg = capability.getTouchConfig(profile);
+  if (!touchCfg) return null;
+  return { capability, touchCfg };
+}
+
+export function listTouchCapableProfileKinds(): string[] {
+  return Object.values(STREAM_PROFILE_DEFINITIONS)
+    .filter((definition) => !!definition.touch)
+    .map((definition) => definition.kind);
+}
+
+export type StreamProfileUpdateResult = {
+  resource: StreamProfileResource;
+  schemaRegistry: SchemaRegistry | null;
+};
+
+export class StreamProfileStore {
+  private readonly db: SqliteDurableStore;
+  private readonly registry: SchemaRegistryStore;
+  private readonly cache: LruCache<string, CachedStreamProfile>;
+
+  constructor(db: SqliteDurableStore, registry: SchemaRegistryStore, opts?: { cacheEntries?: number }) {
+    this.db = db;
+    this.registry = registry;
+    this.cache = new LruCache(opts?.cacheEntries ?? 1024);
+  }
+
+  private loadRow(stream: string): StoredProfileRow | null {
+    return this.db.getStreamProfile(stream);
+  }
+
+  getProfile(stream: string, streamRow?: StreamRow | null): StreamProfileSpec {
+    const res = this.getProfileResult(stream, streamRow);
+    if (Result.isError(res)) throw dsError(res.error.message, { code: res.error.code });
+    return res.value;
+  }
+
+  getProfileResult(stream: string, streamRow?: StreamRow | null): Result<StreamProfileSpec, StreamProfileReadError> {
+    const srow = streamRow ?? this.db.getStream(stream);
+    if (!srow) return Result.ok(GENERIC_STREAM_PROFILE_DEFINITION.defaultProfile());
+
+    const definitionRes = resolveStreamProfileDefinitionResult(srow.profile);
+    if (Result.isError(definitionRes)) return definitionRes;
+
+    const row = definitionRes.value.usesStoredProfileRow ? this.loadRow(stream) : null;
+    const cached = cloneCachedProfile(this.cache.get(stream) ?? null);
+    const readRes = definitionRes.value.readProfileResult({
+      row,
+      cached: cached && cached.profile.kind === definitionRes.value.kind ? cached : null,
+    });
+    if (Result.isError(readRes)) {
+      return Result.err({ kind: "invalid_profile", message: readRes.error.message });
+    }
+
+    if (readRes.value.cache) this.cache.set(stream, cloneCachedProfile(readRes.value.cache)!);
+    else this.cache.delete(stream);
+    return Result.ok(cloneStreamProfileSpec(readRes.value.profile));
+  }
+
+  getProfileResource(stream: string, streamRow?: StreamRow | null): StreamProfileResource {
+    const res = this.getProfileResourceResult(stream, streamRow);
+    if (Result.isError(res)) throw dsError(res.error.message, { code: res.error.code });
+    return res.value;
+  }
+
+  getProfileResourceResult(stream: string, streamRow?: StreamRow | null): Result<StreamProfileResource, StreamProfileReadError> {
+    const profileRes = this.getProfileResult(stream, streamRow);
+    if (Result.isError(profileRes)) return profileRes;
+    return Result.ok(buildStreamProfileResource(profileRes.value));
+  }
+
+  updateProfile(stream: string, streamRow: StreamRow, profile: StreamProfileSpec): StreamProfileResource {
+    const res = this.updateProfileResult(stream, streamRow, profile);
+    if (Result.isError(res)) throw dsError(res.error.message, { code: res.error.code });
+    return res.value.resource;
+  }
+
+  updateProfileResult(
+    stream: string,
+    streamRow: StreamRow,
+    profile: StreamProfileSpec
+  ): Result<StreamProfileUpdateResult, StreamProfileMutationError> {
+    const definition = resolveStreamProfileDefinition(profile.kind);
+    if (!definition) {
+      return Result.err({ kind: "bad_request", message: `profile.kind must be ${supportedProfileKindsMessage()}` });
+    }
+
+    const persistRes = definition.persistProfileResult({ db: this.db, registry: this.registry, stream, streamRow, profile });
+    if (Result.isError(persistRes)) return persistRes;
+
+    if (persistRes.value.cache) this.cache.set(stream, cloneCachedProfile(persistRes.value.cache)!);
+    else this.cache.delete(stream);
+    return Result.ok({
+      resource: buildStreamProfileResource(cloneStreamProfileSpec(persistRes.value.profile)),
+      schemaRegistry: persistRes.value.schemaRegistry ?? null,
+    });
+  }
+}

package/src/profiles/metrics/block_format.ts

@@ -0,0 +1,109 @@
+import { Result } from "better-result";
+import { zstdCompressSync, zstdDecompressSync } from "node:zlib";
+import { BinaryCursor, BinaryPayloadError, BinaryWriter, readI64 } from "../../search/binary/codec";
+import type { MetricsBlockRecord } from "./normalize";
+
+export type MetricsBlockSectionInput = {
+  record_count: number;
+  min_window_start_ms?: number;
+  max_window_end_ms?: number;
+  records: MetricsBlockRecord[];
+};
+
+export type MetricsBlockFormatError = { kind: "invalid_metrics_block"; message: string };
+const METRICS_BLOCK_COMPRESSION_NONE = 0;
+const METRICS_BLOCK_COMPRESSION_ZSTD = 1;
+
+function invalidMetricsBlock<T = never>(message: string): Result<T, MetricsBlockFormatError> {
+  return Result.err({ kind: "invalid_metrics_block", message });
+}
+
+export class MetricsBlockSectionView {
+  private recordsCache: MetricsBlockRecord[] | null = null;
+  private decodedPayload: Uint8Array | null = null;
+
+  constructor(
+    readonly recordCount: number,
+    readonly minWindowStartMs: number | null,
+    readonly maxWindowEndMs: number | null,
+    private readonly compression: number,
+    private readonly recordsPayload: Uint8Array
+  ) {}
+
+  records(): MetricsBlockRecord[] {
+    if (!this.recordsCache) {
+      this.recordsCache = JSON.parse(new TextDecoder().decode(this.payloadBytes())) as MetricsBlockRecord[];
+    }
+    return this.recordsCache;
+  }
+
+  private payloadBytes(): Uint8Array {
+    if (this.decodedPayload) return this.decodedPayload;
+    if (this.compression === METRICS_BLOCK_COMPRESSION_NONE) {
+      this.decodedPayload = this.recordsPayload;
+      return this.decodedPayload;
+    }
+    if (this.compression !== METRICS_BLOCK_COMPRESSION_ZSTD) {
+      throw new BinaryPayloadError(`unsupported metrics block compression ${this.compression}`);
+    }
+    try {
+      this.decodedPayload = new Uint8Array(zstdDecompressSync(this.recordsPayload));
+    } catch (error: unknown) {
+      throw new BinaryPayloadError(`invalid compressed metrics block payload: ${String((error as Error)?.message ?? error)}`);
+    }
+    return this.decodedPayload;
+  }
+}
+
+export function encodeMetricsBlockSegmentCompanion(input: MetricsBlockSectionInput): Uint8Array {
+  const jsonPayload = new TextEncoder().encode(JSON.stringify(input.records));
+  const payload = compressPayload(jsonPayload);
+  const writer = new BinaryWriter();
+  writer.writeU32(input.record_count);
+  writer.writeI64(BigInt(input.min_window_start_ms ?? -1));
+  writer.writeI64(BigInt(input.max_window_end_ms ?? -1));
+  writer.writeU8(payload.compression);
+  writer.writeU8(0);
+  writer.writeU16(0);
+  writer.writeU32(payload.bytes.byteLength);
+  writer.writeBytes(payload.bytes);
+  return writer.finish();
+}
+
+export function decodeMetricsBlockSegmentCompanionResult(bytes: Uint8Array): Result<MetricsBlockSectionView, MetricsBlockFormatError> {
+  try {
+    const cursor = new BinaryCursor(bytes);
+    const recordCount = cursor.readU32();
+    const minWindowStartMs = Number(readI64(bytes, 4));
+    const maxWindowEndMs = Number(readI64(bytes, 12));
+    cursor.readI64();
+    cursor.readI64();
+    const compression = cursor.readU8();
+    cursor.readU8();
+    cursor.readU16();
+    const payloadLength = cursor.readU32();
+    const payload = cursor.readBytes(payloadLength);
+    return Result.ok(
+      new MetricsBlockSectionView(
+        recordCount,
+        minWindowStartMs < 0 ? null : minWindowStartMs,
+        maxWindowEndMs < 0 ? null : maxWindowEndMs,
+        compression,
+        payload
+      )
+    );
+  } catch (e: unknown) {
+    return invalidMetricsBlock(String((e as any)?.message ?? e));
+  }
+}
+
+function compressPayload(jsonPayload: Uint8Array): { compression: number; bytes: Uint8Array } {
+  if (jsonPayload.byteLength === 0) {
+    return { compression: METRICS_BLOCK_COMPRESSION_NONE, bytes: jsonPayload };
+  }
+  const compressed = new Uint8Array(zstdCompressSync(jsonPayload));
+  if (compressed.byteLength >= jsonPayload.byteLength) {
+    return { compression: METRICS_BLOCK_COMPRESSION_NONE, bytes: jsonPayload };
+  }
+  return { compression: METRICS_BLOCK_COMPRESSION_ZSTD, bytes: compressed };
+}