@shipfox/api-logs 2.0.0

package/src/core/append-logs.ts

@@ -0,0 +1,384 @@
+import {Buffer} from 'node:buffer';
+import {DEFAULT_HARNESS, type Harness, harnessSchema} from '@shipfox/api-agent-dto';
+import {
+  type LogRecord,
+  parseLogRecordLine,
+  parseRawLogRecordLine,
+  type RawLogRecord,
+} from '@shipfox/api-logs-dto';
+import {getStepById} from '@shipfox/api-workflows';
+import {logger} from '@shipfox/node-opentelemetry';
+import {config} from '#config.js';
+import {accrueStoredBytes, claimCap, ensureJobAccounting, isJobCapped} from '#db/accounting.js';
+import {insertChunk} from '#db/chunks.js';
+import {db, type Transaction} from '#db/db.js';
+import {
+  casExtendCommittedLength,
+  getAttemptStream,
+  getOrCreateAttemptStreamWithStatus,
+  setDeclaredTotalBytes,
+} from '#db/streams.js';
+import {
+  type LogRecordMetricKind,
+  recordAppendedCount,
+  streamClosedCount,
+  streamOpenedCount,
+} from '#metrics/instance.js';
+import {allowedBudget} from './budget.js';
+import {closeStream, controlTombstone} from './close-stream.js';
+import {MalformedLogChunkError, OffsetGapError} from './errors.js';
+import {parseSessionRecord} from './session/parse-session.js';
+import type {AgentSessionRecord} from './session/session-record.js';
+
+type StepLookup = (stepId: string) => Promise<{config: Record<string, unknown>} | undefined>;
+
+let stepLookup: StepLookup = getStepById;
+
+export function setStepLookupForTesting(lookup: StepLookup): () => void {
+  const previous = stepLookup;
+  stepLookup = lookup;
+  return () => {
+    stepLookup = previous;
+  };
+}
+
+export interface AppendLogsParams {
+  jobId: string;
+  workspaceId: string;
+  projectId: string;
+  workflowRunAttemptId: string;
+  stepId: string;
+  attempt: number;
+  offset: number;
+  body: Buffer;
+}
+
+export interface AppendLogsResult {
+  committedLength: number;
+  capped: boolean;
+}
+
+interface ParsedBody {
+  declaredTotalBytes?: number;
+  records: RawLogRecord[];
+  hasAgentSessionRecord: boolean;
+}
+
+/**
+ * Pure pre-transaction parse. Requires whole, newline-terminated lines so
+ * `committed_length` always lands on a line boundary (one body = one chunk = whole
+ * lines; no line ever spans two chunks). Runs before any lock is taken, so a
+ * malformed or large body never holds a row. The offset CAS uses the raw append byte length; the
+ * budget charges the normalized body built from these parsed records.
+ *
+ * Each line is validated against the raw record union (a forged server-only
+ * `capped`/`runner_lost` fails here); the declared total is pulled from an `end`
+ * record. A line that is a valid server-only record under the read union surfaces
+ * its type via `forgedType` for the narrowed audit warn.
+ */
+function parseAppendBody(body: Buffer): ParsedBody {
+  if (body.length === 0) return {records: [], hasAgentSessionRecord: false};
+
+  const text = body.toString('utf8');
+  if (!text.endsWith('\n')) {
+    throw new MalformedLogChunkError('append body must end with a newline (whole records only)');
+  }
+  const lines = text.split('\n');
+  lines.pop();
+
+  let declaredTotalBytes: number | undefined;
+  const records: RawLogRecord[] = [];
+  let hasAgentSessionRecord = false;
+  for (const line of lines) {
+    let record: ReturnType<typeof parseRawLogRecordLine>;
+    try {
+      record = parseRawLogRecordLine(line);
+    } catch {
+      throw new MalformedLogChunkError(
+        'append body contains an invalid NDJSON record',
+        detectForgedType(line),
+      );
+    }
+    records.push(record);
+    if (record.type === 'end') {
+      declaredTotalBytes = record.total_bytes;
+    }
+    // An agent_session line is one whole entry in one record; bound its size here (the DTO
+    // schema leaves `data` uncapped because it cannot read this runtime config). An over-cap
+    // line is rejected so a single entry can never blow the request body or the spool window.
+    if (
+      record.type === 'agent_session' &&
+      Buffer.byteLength(line, 'utf8') > config.LOG_MAX_SESSION_LINE_BYTES
+    ) {
+      throw new MalformedLogChunkError(
+        `agent_session line exceeds ${config.LOG_MAX_SESSION_LINE_BYTES} bytes`,
+      );
+    }
+    if (record.type === 'agent_session') {
+      hasAgentSessionRecord = true;
+    }
+  }
+
+  return declaredTotalBytes === undefined
+    ? {records, hasAgentSessionRecord}
+    : {declaredTotalBytes, records, hasAgentSessionRecord};
+}
+
+/**
+ * A line that fails the raw write union but is a valid record under the read union
+ * can only be a server-only `capped`/`runner_lost` tombstone — i.e. a forgery
+ * attempt. Returns its type for the audit warn, or undefined for plain garbage.
+ */
+function detectForgedType(line: string): string | undefined {
+  try {
+    return parseLogRecordLine(line).type;
+  } catch {
+    return undefined;
+  }
+}
+
+async function getSessionHarness(stepId: string): Promise<Harness> {
+  const step = await stepLookup(stepId);
+  const parsed = harnessSchema.safeParse(step?.config.harness);
+  return parsed.success ? parsed.data : DEFAULT_HARNESS;
+}
+
+/**
+ * Empty-body heartbeat: report the current committed length without materializing
+ * a stream, so a runner cannot mint unbounded rows with empty appends.
+ */
+async function readHeartbeat(tx: Transaction, params: AppendLogsParams): Promise<AppendLogsResult> {
+  const existing = await getAttemptStream(tx, {
+    jobId: params.jobId,
+    stepId: params.stepId,
+    attempt: params.attempt,
+  });
+  return {
+    committedLength: existing?.committedLength ?? 0,
+    capped: await isJobCapped(tx, params.jobId),
+  };
+}
+
+interface StoreChunkParams {
+  params: AppendLogsParams;
+  streamId: string;
+  body: Buffer;
+  committedLength: number;
+  declaredTotalBytes: number | undefined;
+}
+
+interface StoreChunkResult extends AppendLogsResult {
+  /**
+   * Whether the runner chunk was persisted. False only when the job was already
+   * capped and the body (including any `end` record) was dropped, so the stream is
+   * not whole and must not be declared-closed.
+   */
+  stored: boolean;
+  recordCounts: Partial<Record<LogRecord['type'], number>>;
+}
+
+/**
+ * Accrues the stored bytes, persists the chunk, and trips the per-job cap when
+ * this append crosses the budget. Runs only after the offset-CAS extended
+ * `committed_length`, so the committed length already reflects the accepted bytes.
+ */
+async function storeChunk(
+  tx: Transaction,
+  {params, streamId, body, committedLength, declaredTotalBytes}: StoreChunkParams,
+): Promise<StoreChunkResult> {
+  await ensureJobAccounting(tx, {jobId: params.jobId, workspaceId: params.workspaceId});
+  const storedByteLen = body.length;
+  const accrued = await accrueStoredBytes(tx, {jobId: params.jobId, delta: storedByteLen});
+
+  // Already capped: accept-and-drop. committed_length has advanced so the runner
+  // drains its spool cleanly instead of retry-looping; nothing is stored.
+  if (!accrued) return {committedLength, capped: true, stored: false, recordCounts: {}};
+
+  await insertChunk(tx, {
+    streamId,
+    streamOffset: params.offset,
+    byteLen: storedByteLen,
+    data: body,
+    origin: 'runner',
+  });
+  if (declaredTotalBytes !== undefined) {
+    await setDeclaredTotalBytes(tx, {streamId, declaredTotalBytes});
+  }
+
+  const allowed = allowedBudget({
+    baseBytes: config.LOG_BUDGET_BASE_BYTES,
+    ratePerMinuteBytes: config.LOG_BUDGET_RATE_BYTES_PER_MINUTE,
+    elapsedMs: Date.now() - accrued.startedAt.getTime(),
+  });
+  if (accrued.used <= allowed) {
+    return {committedLength, capped: false, stored: true, recordCounts: {}};
+  }
+
+  // Over budget. No hard ceiling: this crossing append is stored in full (overshoot
+  // bounded by one body). Claim the cap once and inject an in-band `capped` tombstone
+  // for the winner.
+  const won = await claimCap(tx, params.jobId);
+  if (won) {
+    const tombstone = controlTombstone('capped');
+    await insertChunk(tx, {
+      streamId,
+      streamOffset: committedLength,
+      byteLen: tombstone.length,
+      data: tombstone,
+      origin: 'control',
+    });
+  }
+  return {
+    committedLength,
+    capped: true,
+    stored: true,
+    recordCounts: won ? {capped: 1} : {},
+  };
+}
+
+function buildStoredBody(
+  records: readonly RawLogRecord[],
+  harness: Harness,
+): {body: Buffer; recordCounts: Partial<Record<LogRecord['type'], number>>} {
+  const storedRecords: LogRecord[] = [];
+  for (const record of records) {
+    if (record.type !== 'agent_session') {
+      storedRecords.push(record);
+      continue;
+    }
+
+    for (const row of parseSessionRecord(agentSessionRecord(record), harness)) {
+      storedRecords.push({v: 1, ts: row.timestamp, type: 'agent_session', row});
+    }
+  }
+
+  const body = Buffer.from(storedRecords.map((record) => `${JSON.stringify(record)}\n`).join(''));
+  const recordCounts: Partial<Record<LogRecord['type'], number>> = {};
+  for (const record of storedRecords) {
+    recordCounts[record.type] = (recordCounts[record.type] ?? 0) + 1;
+  }
+
+  return {body, recordCounts};
+}
+
+function agentSessionRecord(
+  record: Extract<RawLogRecord, {type: 'agent_session'}>,
+): AgentSessionRecord {
+  return {data: record.data, ts: record.ts};
+}
+
+/**
+ * Concurrency is serialized through Postgres row locks taken implicitly by the
+ * conditional UPDATEs, not an explicit `SELECT ... FOR UPDATE`. Appends for one
+ * job contend on its single accounting row, so the path is multi-instance safe
+ * but not lock-free.
+ */
+export async function appendLogs(params: AppendLogsParams): Promise<AppendLogsResult> {
+  let parsed: ParsedBody;
+  try {
+    parsed = parseAppendBody(params.body);
+  } catch (error) {
+    // Narrowed audit: only the detectable forgery case, never the payload or a token.
+    if (error instanceof MalformedLogChunkError && error.forgedType !== undefined) {
+      logger().warn(
+        {
+          jobId: params.jobId,
+          stepId: params.stepId,
+          offendingType: error.forgedType,
+        },
+        'Rejected forged server-only log record on append',
+      );
+    }
+    throw error;
+  }
+  const {declaredTotalBytes} = parsed;
+  const sessionHarness = parsed.hasAgentSessionRecord
+    ? await getSessionHarness(params.stepId)
+    : DEFAULT_HARNESS;
+  const stored = buildStoredBody(parsed.records, sessionHarness);
+  const commitByteLen = params.body.length;
+  const metrics = {
+    recordCounts: {} as Partial<Record<LogRecordMetricKind, number>>,
+    streamClosedReason: undefined as 'declared' | undefined,
+    streamOpened: false,
+  };
+
+  const result = await db().transaction(async (tx) => {
+    if (commitByteLen === 0) return readHeartbeat(tx, params);
+
+    const {created, stream} = await getOrCreateAttemptStreamWithStatus(tx, {
+      jobId: params.jobId,
+      stepId: params.stepId,
+      attempt: params.attempt,
+      workspaceId: params.workspaceId,
+      projectId: params.projectId,
+      workflowRunAttemptId: params.workflowRunAttemptId,
+    });
+    metrics.streamOpened = created;
+
+    // Closed stream (the runner's end already landed, or the job-terminated sweep ran):
+    // accept-and-drop so a late chunk can never race compaction. committed_length is
+    // frozen at close, so this reports the final offset and the runner stops cleanly.
+    if (stream.state === 'closed') {
+      return {committedLength: stream.committedLength, capped: await isJobCapped(tx, params.jobId)};
+    }
+
+    const cas = await casExtendCommittedLength(tx, {
+      streamId: stream.id,
+      offset: params.offset,
+      byteLen: commitByteLen,
+    });
+    if (cas.outcome === 'gap') throw new OffsetGapError(cas.committedLength);
+    if (cas.outcome === 'retry') {
+      return {committedLength: cas.committedLength, capped: await isJobCapped(tx, params.jobId)};
+    }
+
+    const {
+      recordCounts,
+      stored: chunkStored,
+      ...result
+    } = await storeChunk(tx, {
+      params,
+      streamId: stream.id,
+      body: stored.body,
+      committedLength: cas.committedLength,
+      declaredTotalBytes,
+    });
+    if (chunkStored) {
+      addRecordCounts(metrics.recordCounts, stored.recordCounts);
+    }
+    addRecordCounts(metrics.recordCounts, recordCounts);
+
+    // The runner's end record was committed in this append (offset-CAS guarantees
+    // everything before it is already committed), so the stream is whole. Declared-close
+    // it in-band so compaction starts at once instead of waiting for the timeout sweep.
+    // Only when the chunk was actually stored: an end body dropped because the job was
+    // already capped persists nothing, so the stream is not whole and stays open for the
+    // timeout sweep to close it as truncated.
+    if (declaredTotalBytes !== undefined && chunkStored) {
+      const closed = await closeStream(tx, {streamId: stream.id, reason: 'declared'});
+      if (closed) metrics.streamClosedReason = 'declared';
+    }
+
+    return result;
+  });
+
+  if (metrics.streamOpened) streamOpenedCount.add(1);
+  for (const [kind, count] of Object.entries(metrics.recordCounts)) {
+    if (count > 0) recordAppendedCount.add(count, {kind: kind as LogRecordMetricKind});
+  }
+  if (metrics.streamClosedReason) {
+    streamClosedCount.add(1, {reason: metrics.streamClosedReason});
+  }
+
+  return result;
+}
+
+function addRecordCounts(
+  target: Partial<Record<LogRecordMetricKind, number>>,
+  source: Partial<Record<LogRecordMetricKind, number>>,
+): void {
+  for (const [kind, count] of Object.entries(source)) {
+    target[kind as LogRecordMetricKind] = (target[kind as LogRecordMetricKind] ?? 0) + (count ?? 0);
+  }
+}

package/src/core/budget.test.ts

@@ -0,0 +1,30 @@
+import {allowedBudget} from './budget.js';
+
+describe('allowedBudget', () => {
+  const baseBytes = 5_242_880;
+  const ratePerMinuteBytes = 1_048_576;
+
+  it('returns the base at the clock origin', () => {
+    const allowed = allowedBudget({baseBytes, ratePerMinuteBytes, elapsedMs: 0});
+
+    expect(allowed).toBe(baseBytes);
+  });
+
+  it('adds the full rate after two minutes', () => {
+    const allowed = allowedBudget({baseBytes, ratePerMinuteBytes, elapsedMs: 2 * 60_000});
+
+    expect(allowed).toBe(baseBytes + 2 * ratePerMinuteBytes);
+  });
+
+  it('floors a partial minute', () => {
+    const allowed = allowedBudget({baseBytes, ratePerMinuteBytes, elapsedMs: 90_000});
+
+    expect(allowed).toBe(baseBytes + Math.floor(1.5 * ratePerMinuteBytes));
+  });
+
+  it('treats negative elapsed time as the origin', () => {
+    const allowed = allowedBudget({baseBytes, ratePerMinuteBytes, elapsedMs: -10_000});
+
+    expect(allowed).toBe(baseBytes);
+  });
+});

package/src/core/budget.ts

@@ -0,0 +1,19 @@
+export interface AllowedBudgetParams {
+  baseBytes: number;
+  ratePerMinuteBytes: number;
+  /** Time since the budget clock origin (first append) in milliseconds. */
+  elapsedMs: number;
+}
+
+/**
+ * Accrual budget in stored bytes: `base + rate * elapsedMinutes`, floored to an
+ * integer. No hard ceiling — job duration limits bound total volume.
+ */
+export function allowedBudget({
+  baseBytes,
+  ratePerMinuteBytes,
+  elapsedMs,
+}: AllowedBudgetParams): number {
+  const elapsed = Math.max(0, elapsedMs);
+  return baseBytes + Math.floor((ratePerMinuteBytes * elapsed) / 60_000);
+}

package/src/core/close-stream.ts

@@ -0,0 +1,72 @@
+import {Buffer} from 'node:buffer';
+import {LOG_STREAM_CLOSED, type LogRecord, type LogsEventMap} from '@shipfox/api-logs-dto';
+import {writeOutboxEvent} from '@shipfox/node-outbox';
+import type {AttemptStream, StreamCloseReason} from '#core/entities/attempt-stream.js';
+import {insertChunk} from '#db/chunks.js';
+import type {Transaction} from '#db/db.js';
+import {logsOutbox} from '#db/schema/outbox.js';
+import {markStreamClosed} from '#db/streams.js';
+
+export type TombstoneKind = 'capped' | 'runner_lost';
+
+/**
+ * Frames a server tombstone as one newline-terminated record. Typed against the
+ * shared contract so an envelope change breaks this at compile time. Stored as a
+ * `control`-origin chunk; like every server record it does NOT advance
+ * `committed_length`, so the CAS axis stays equal to runner spool bytes.
+ */
+export function controlTombstone(kind: TombstoneKind): Buffer {
+  const record: LogRecord = {v: 1, ts: Date.now(), type: kind};
+  return Buffer.from(`${JSON.stringify(record)}\n`, 'utf8');
+}
+
+export interface CloseStreamParams {
+  streamId: string;
+  reason: StreamCloseReason;
+}
+
+/**
+ * The guarded UPDATE (`WHERE state='open'`) in `markStreamClosed` is the lock and
+ * the idempotency gate: a stream already closed by the other path (append-time
+ * declared close vs the job-terminated timeout sweep) returns null, so no duplicate
+ * `LOG_STREAM_CLOSED` is written and no second tombstone lands. A timeout close sets
+ * `truncated` and injects a `runner_lost` tombstone in-band (a `capped` tombstone,
+ * if any, was injected earlier at the append that tripped the cap).
+ *
+ * The event drives compaction; it is written in the same transaction as the flip.
+ */
+export async function closeStream(
+  tx: Transaction,
+  params: CloseStreamParams,
+): Promise<AttemptStream | null> {
+  const closed = await markStreamClosed(tx, {
+    streamId: params.streamId,
+    reason: params.reason,
+    markTruncated: params.reason === 'timeout',
+  });
+  if (!closed) return null;
+
+  if (params.reason === 'timeout') {
+    const tombstone = controlTombstone('runner_lost');
+    await insertChunk(tx, {
+      streamId: closed.id,
+      streamOffset: closed.committedLength,
+      byteLen: tombstone.length,
+      data: tombstone,
+      origin: 'control',
+    });
+  }
+
+  await writeOutboxEvent<LogsEventMap>(tx, logsOutbox, {
+    type: LOG_STREAM_CLOSED,
+    payload: {
+      workspaceId: closed.workspaceId,
+      jobId: closed.jobId,
+      stepId: closed.stepId,
+      attempt: closed.attempt,
+      streamId: closed.id,
+    },
+  });
+
+  return closed;
+}

package/src/core/compaction.ts

@@ -0,0 +1,68 @@
+import type {Buffer} from 'node:buffer';
+import {Readable} from 'node:stream';
+import {createGzip} from 'node:zlib';
+import {readChunksKeyset} from '#db/chunks.js';
+
+// Chunks are capped at ~256KB each by the runner flush, so a small fixed page count gives a
+// predictable memory bound (page x ~256KB) without a byte-budgeted query.
+const CHUNK_PAGE_SIZE = 64;
+
+export interface CompactionStreamStats {
+  chunkCount: number;
+  lastSeq: number;
+  uncompressedBytes: number;
+}
+
+export interface CompactedGzipStream {
+  body: Readable;
+  stats: CompactionStreamStats;
+}
+
+export interface CompactedGzipStreamParams {
+  streamId: string;
+  /**
+   * Invoked once per fetched chunk page (after the read, before the page's bytes flow on).
+   * Lets the caller heartbeat off read progress, so the pre-upload phase and a slow first
+   * part still emit liveness instead of waiting on the upload's per-part progress event.
+   */
+  onPage?: () => void;
+}
+
+/**
+ * Builds a gzip stream of a closed stream's chunk bytes in `seq` order. Keyset-paginates
+ * so memory stays flat at any stream size, and fills `stats` as bytes flow so the caller
+ * can check the streamed totals against the table before deleting the source rows. A
+ * source error is forwarded to the gzip stream, so the upload consuming it rejects rather
+ * than silently truncating.
+ */
+export function compactedGzipStream(params: CompactedGzipStreamParams): CompactedGzipStream {
+  const stats: CompactionStreamStats = {chunkCount: 0, lastSeq: 0, uncompressedBytes: 0};
+
+  async function* chunks(): AsyncGenerator<Buffer> {
+    let afterSeq = 0;
+    while (true) {
+      const page = await readChunksKeyset({
+        streamId: params.streamId,
+        afterSeq,
+        limit: CHUNK_PAGE_SIZE,
+      });
+      if (page.length === 0) break;
+      params.onPage?.();
+      for (const row of page) {
+        stats.chunkCount += 1;
+        stats.lastSeq = row.seq;
+        stats.uncompressedBytes += row.data.length;
+        yield row.data;
+      }
+      afterSeq = page.at(-1)?.seq ?? afterSeq;
+      if (page.length < CHUNK_PAGE_SIZE) break;
+    }
+  }
+
+  const source = Readable.from(chunks());
+  const gzip = createGzip();
+  source.once('error', (error) => gzip.destroy(error));
+  source.pipe(gzip);
+
+  return {body: gzip, stats};
+}

package/src/core/entities/attempt-stream.ts

@@ -0,0 +1,38 @@
+/** Lifecycle state of an attempt's log stream. */
+export type StreamState = 'open' | 'closed';
+
+/** Why a stream was closed, once it is. */
+export type StreamCloseReason = 'declared' | 'timeout';
+
+/**
+ * A single `(job, step, attempt)` log stream. Identity is scoped to the lease's
+ * job. `workspaceId`, `projectId`, and `workflowRunAttemptId` are stamped from the lease on
+ * stream creation and asserted on subsequent appends, so reads can authorize
+ * per-project without joining back to workflows. `committedLength` is the
+ * offset-CAS axis: raw NDJSON spool bytes the server has durably accepted from
+ * the runner.
+ *
+ * `truncated` is an out-of-band terminal flag set when the timeout sweep
+ * force-closes a stream the runner never ended. Budget exhaustion ("capped") is a
+ * job-level signal recorded in `job_accounting` and surfaced in-band by a `capped`
+ * tombstone record, not on the stream row.
+ */
+export interface AttemptStream {
+  id: string;
+  jobId: string;
+  stepId: string;
+  attempt: number;
+  workspaceId: string;
+  projectId: string;
+  workflowRunAttemptId: string;
+  committedLength: number;
+  state: StreamState;
+  closeReason: StreamCloseReason | null;
+  declaredTotalBytes: number | null;
+  truncated: boolean;
+  objectKey: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+  /** When the stream was closed (either close path); null while open. Retention anchor. */
+  closedAt: Date | null;
+}

package/src/core/entities/job-accounting.ts

@@ -0,0 +1,11 @@
+/**
+ * Per-job accrual-budget state: how many stored bytes a job has used, the budget
+ * clock origin, and whether it has been capped.
+ */
+export interface JobAccounting {
+  jobId: string;
+  workspaceId: string;
+  storedBytesUsed: number;
+  startedAt: Date;
+  cappedAt: Date | null;
+}

package/src/core/entities/log-object.test.ts

@@ -0,0 +1,25 @@
+import {logObjectKey} from './log-object.js';
+
+describe('logObjectKey', () => {
+  it('builds the {prefix}/{workspace}/{job}/{step}/{attempt} key', () => {
+    const key = logObjectKey('logs', {
+      workspaceId: 'ws',
+      jobId: 'job',
+      stepId: 'step',
+      attempt: 2,
+    });
+
+    expect(key).toBe('logs/ws/job/step/2');
+  });
+
+  it('uses the given prefix so one bucket can host several modules', () => {
+    const key = logObjectKey('shipfox-logs', {
+      workspaceId: 'ws',
+      jobId: 'job',
+      stepId: 'step',
+      attempt: 2,
+    });
+
+    expect(key).toBe('shipfox-logs/ws/job/step/2');
+  });
+});

package/src/core/entities/log-object.ts

@@ -0,0 +1,18 @@
+export interface LogObjectKeyParams {
+  workspaceId: string;
+  jobId: string;
+  stepId: string;
+  attempt: number;
+}
+
+/**
+ * Object layout `{prefix}/{workspace}/{job}/{step}/{attempt}` so retention and workspace
+ * deletion are prefix operations. `prefix` is the configurable bucket prefix
+ * (`LOG_STORAGE_S3_PREFIX`, default `logs`), so one bucket can host several modules.
+ */
+export function logObjectKey(
+  prefix: string,
+  {workspaceId, jobId, stepId, attempt}: LogObjectKeyParams,
+): string {
+  return `${prefix}/${workspaceId}/${jobId}/${stepId}/${attempt}`;
+}