@shipfox/api-logs 2.0.0

package/src/presentation/routes/read-logs.test.ts

@@ -0,0 +1,504 @@
+import {Buffer} from 'node:buffer';
+import {gunzipSync} from 'node:zlib';
+import {GetObjectCommand} from '@aws-sdk/client-s3';
+import {
+  AUTH_LEASED_JOB,
+  AUTH_USER,
+  buildUserContext,
+  setUserContext,
+} from '@shipfox/api-auth-context';
+import {parseLogRecordLine} from '@shipfox/api-logs-dto';
+import type {
+  LogOutcomeDto,
+  WorkflowsStepAttemptTerminatedEventDto,
+} from '@shipfox/api-workflows-dto';
+import {
+  type AuthMethod,
+  ClientError,
+  closeApp,
+  createApp,
+  type FastifyInstance,
+} from '@shipfox/node-fastify';
+import {MockActivityEnvironment} from '@temporalio/testing';
+import {eq, sql} from 'drizzle-orm';
+import type {FastifyRequest} from 'fastify';
+import {deleteObject, s3Client} from '#api/object-storage.js';
+import {config} from '#config.js';
+import type {AttemptStream} from '#core/entities/attempt-stream.js';
+import {buildLogReadResult} from '#core/read-logs.js';
+import {insertChunk} from '#db/chunks.js';
+import {db} from '#db/db.js';
+import {attemptStreams} from '#db/schema/attempt-streams.js';
+import {getOrCreateAttemptStream} from '#db/streams.js';
+import {
+  type CompactStreamResult,
+  compactStreamActivity,
+} from '#temporal/activities/compact-stream.js';
+import {ndjsonBody, outputLine, recordLine} from '#test/fixtures/ndjson.js';
+import {findStream} from '#test/queries.js';
+import {onStepAttemptTerminated} from '../subscribers/on-step-attempt-terminated.js';
+import {logsRoutes} from './index.js';
+
+// AUTH_USER stub: a `Bearer user` request is a member of whatever workspace it names in the
+// `x-test-workspace` header, so each test grants or withholds access against the arranged
+// stream's workspace. The lease method is stubbed only so the append group's auth resolves.
+const fakeUserAuth: AuthMethod = {
+  name: AUTH_USER,
+  authenticate: (request: FastifyRequest) => {
+    if (request.headers.authorization !== 'Bearer user') {
+      throw new ClientError('Invalid user token', 'unauthorized', {status: 401});
+    }
+    const header = request.headers['x-test-workspace'];
+    const workspaceId = Array.isArray(header) ? header[0] : header;
+    setUserContext(
+      request,
+      buildUserContext({
+        userId: 'user-1',
+        email: 'user@example.com',
+        memberships: workspaceId ? [{workspaceId, role: 'admin'}] : [],
+      }),
+    );
+    return Promise.resolve();
+  },
+};
+const stubLeaseAuth: AuthMethod = {name: AUTH_LEASED_JOB, authenticate: () => Promise.resolve()};
+
+interface ChunkSpec {
+  data: Buffer;
+  origin?: 'runner' | 'control';
+}
+
+async function arrangeStream(opts: {
+  workspaceId: string;
+  chunks: (Buffer | ChunkSpec)[];
+  state?: 'open' | 'closed';
+  truncated?: boolean;
+}): Promise<AttemptStream> {
+  const identity = {
+    jobId: crypto.randomUUID(),
+    stepId: crypto.randomUUID(),
+    attempt: 1,
+    workspaceId: opts.workspaceId,
+    projectId: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+  };
+  await db().transaction(async (tx) => {
+    const stream = await getOrCreateAttemptStream(tx, identity);
+    let offset = 0;
+    for (const chunk of opts.chunks) {
+      const spec = Buffer.isBuffer(chunk) ? {data: chunk, origin: 'runner' as const} : chunk;
+      const origin = spec.origin ?? 'runner';
+      await insertChunk(tx, {
+        streamId: stream.id,
+        streamOffset: offset,
+        byteLen: spec.data.length,
+        data: spec.data,
+        origin,
+      });
+      // Control chunks do not advance the runner byte axis (committed_length).
+      if (origin === 'runner') offset += spec.data.length;
+    }
+    await tx
+      .update(attemptStreams)
+      .set({
+        committedLength: offset,
+        state: opts.state ?? 'open',
+        ...(opts.state === 'closed' ? {closeReason: 'declared', closedAt: sql`now()`} : {}),
+        truncated: opts.truncated ?? false,
+      })
+      .where(eq(attemptStreams.id, stream.id));
+  });
+  const stream = await findStream(identity);
+  if (!stream) throw new Error('arranged stream missing');
+  return stream;
+}
+
+function terminatedEvent(opts: {
+  workspaceId: string;
+  logOutcome: LogOutcomeDto;
+}): WorkflowsStepAttemptTerminatedEventDto {
+  return {
+    jobId: crypto.randomUUID(),
+    stepId: crypto.randomUUID(),
+    attempt: 1,
+    workspaceId: opts.workspaceId,
+    projectId: crypto.randomUUID(),
+    workflowRunId: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    logOutcome: opts.logOutcome,
+  };
+}
+
+async function consumeTerminatedEvent(
+  payload: WorkflowsStepAttemptTerminatedEventDto,
+): Promise<void> {
+  await onStepAttemptTerminated(payload);
+}
+
+async function getObjectBytes(key: string): Promise<Buffer> {
+  const res = await s3Client().send(
+    new GetObjectCommand({Bucket: config.LOG_STORAGE_S3_BUCKET, Key: key}),
+  );
+  if (!res.Body) throw new Error('object has no body');
+  return Buffer.from(await res.Body.transformToByteArray());
+}
+
+function runCompaction(streamId: string): Promise<CompactStreamResult> {
+  return new MockActivityEnvironment().run(compactStreamActivity, {streamId});
+}
+
+async function compact(streamId: string): Promise<string> {
+  const result = await runCompaction(streamId);
+  if (result.outcome !== 'compacted') throw new Error(`expected compacted, got ${result.outcome}`);
+  return result.objectKey;
+}
+
+describe('GET /steps/:stepId/attempts/:attempt/logs', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createApp({
+      auth: [fakeUserAuth, stubLeaseAuth],
+      routes: logsRoutes,
+      swagger: false,
+    });
+    await app.ready();
+  });
+
+  afterAll(async () => {
+    await closeApp();
+  });
+
+  function readUrl(stepId: string, attempt: number, cursor: number): string {
+    return `/steps/${stepId}/attempts/${attempt}/logs?cursor=${cursor}`;
+  }
+
+  function authedGet(stream: AttemptStream, cursor: number, workspaceId = stream.workspaceId) {
+    return app.inject({
+      method: 'GET',
+      url: readUrl(stream.stepId, stream.attempt, cursor),
+      headers: {authorization: 'Bearer user', 'x-test-workspace': workspaceId},
+    });
+  }
+
+  it('rejects a request without a session token', async () => {
+    const res = await app.inject({method: 'GET', url: readUrl(crypto.randomUUID(), 1, 0)});
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json().code).toBe('unauthorized');
+  });
+
+  it('returns 404 for a step that has no stream', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: readUrl(crypto.randomUUID(), 1, 0),
+      headers: {authorization: 'Bearer user', 'x-test-workspace': crypto.randomUUID()},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+
+  it('returns 404 before the terminated event, then returns a closed empty drained stream', async () => {
+    const terminal = terminatedEvent({
+      workspaceId: crypto.randomUUID(),
+      logOutcome: 'drained',
+    });
+
+    const beforeEvent = await app.inject({
+      method: 'GET',
+      url: readUrl(terminal.stepId, terminal.attempt, 0),
+      headers: {authorization: 'Bearer user', 'x-test-workspace': terminal.workspaceId},
+    });
+    await consumeTerminatedEvent(terminal);
+    const afterEvent = await app.inject({
+      method: 'GET',
+      url: readUrl(terminal.stepId, terminal.attempt, 0),
+      headers: {authorization: 'Bearer user', 'x-test-workspace': terminal.workspaceId},
+    });
+
+    expect(beforeEvent.statusCode).toBe(404);
+    expect(beforeEvent.json().code).toBe('not-found');
+    expect(afterEvent.statusCode).toBe(200);
+    const body = afterEvent.json();
+    expect(body.mode).toBe('inline');
+    expect(body.state).toBe('closed');
+    expect(body.truncated).toBe(false);
+    expect(body.ndjson).toBe('');
+    const stream = await findStream(terminal);
+    expect(stream?.state).toBe('closed');
+    expect(stream?.closeReason).toBe('declared');
+  });
+
+  it('returns 404 before the terminated event, then returns a runner_lost abandoned stream', async () => {
+    const terminal = terminatedEvent({
+      workspaceId: crypto.randomUUID(),
+      logOutcome: 'abandoned',
+    });
+
+    const beforeEvent = await app.inject({
+      method: 'GET',
+      url: readUrl(terminal.stepId, terminal.attempt, 0),
+      headers: {authorization: 'Bearer user', 'x-test-workspace': terminal.workspaceId},
+    });
+    await consumeTerminatedEvent(terminal);
+    const afterEvent = await app.inject({
+      method: 'GET',
+      url: readUrl(terminal.stepId, terminal.attempt, 0),
+      headers: {authorization: 'Bearer user', 'x-test-workspace': terminal.workspaceId},
+    });
+
+    expect(beforeEvent.statusCode).toBe(404);
+    expect(beforeEvent.json().code).toBe('not-found');
+    expect(afterEvent.statusCode).toBe(200);
+    const body = afterEvent.json();
+    expect(body.mode).toBe('inline');
+    expect(body.state).toBe('closed');
+    expect(body.truncated).toBe(true);
+    const records = body.ndjson.split('\n').filter(Boolean).map(parseLogRecordLine);
+    expect(records).toMatchObject([{type: 'runner_lost'}]);
+    const stream = await findStream(terminal);
+    expect(stream?.state).toBe('closed');
+    expect(stream?.closeReason).toBe('timeout');
+  });
+
+  it('keeps returning 404 for a running missing attempt', async () => {
+    const running = {stepId: crypto.randomUUID(), attempt: 1, workspaceId: crypto.randomUUID()};
+
+    const res = await app.inject({
+      method: 'GET',
+      url: readUrl(running.stepId, running.attempt, 0),
+      headers: {authorization: 'Bearer user', 'x-test-workspace': running.workspaceId},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+
+  it('returns 404 (no existence leak) when the caller is not a member of the workspace', async () => {
+    const stream = await arrangeStream({
+      workspaceId: crypto.randomUUID(),
+      chunks: [ndjsonBody(outputLine('secret\n'))],
+    });
+
+    const res = await authedGet(stream, 0, crypto.randomUUID());
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+
+  it('serves an open stream inline with the next cursor and stream state', async () => {
+    const workspaceId = crypto.randomUUID();
+    const lineA = outputLine('alpha\n');
+    const lineB = outputLine('beta\n');
+    const stream = await arrangeStream({
+      workspaceId,
+      chunks: [ndjsonBody(lineA), ndjsonBody(lineB)],
+    });
+
+    const res = await authedGet(stream, 0);
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.mode).toBe('inline');
+    expect(body.state).toBe('open');
+    expect(body.truncated).toBe(false);
+    expect(body.has_more).toBe(false);
+    expect(body.ndjson).toBe(lineA + lineB);
+    const records = body.ndjson.split('\n').filter(Boolean).map(parseLogRecordLine);
+    expect(records).toEqual([
+      {v: 1, ts: 1, type: 'output', stream: 'stdout', data: 'alpha\n'},
+      {v: 1, ts: 1, type: 'output', stream: 'stdout', data: 'beta\n'},
+    ]);
+
+    const reread = await authedGet(stream, body.next_cursor);
+    expect(reread.json().ndjson).toBe('');
+    expect(reread.json().has_more).toBe(false);
+    expect(reread.json().next_cursor).toBe(body.next_cursor);
+  });
+
+  it('interleaves server control records with runner bytes in seq order', async () => {
+    const workspaceId = crypto.randomUUID();
+    const stream = await arrangeStream({
+      workspaceId,
+      state: 'closed',
+      chunks: [
+        {data: ndjsonBody(outputLine('a\n'))},
+        {data: ndjsonBody(recordLine({type: 'capped'})), origin: 'control'},
+        {data: ndjsonBody(outputLine('b\n'))},
+      ],
+    });
+
+    const res = await authedGet(stream, 0);
+
+    const records = res.json().ndjson.split('\n').filter(Boolean).map(parseLogRecordLine);
+    expect(records.map((record: {type: string}) => record.type)).toEqual([
+      'output',
+      'capped',
+      'output',
+    ]);
+  });
+
+  it('returns inline bytes byte-identical to the compacted object', async () => {
+    const workspaceId = crypto.randomUUID();
+    const stream = await arrangeStream({
+      workspaceId,
+      state: 'closed',
+      chunks: [ndjsonBody(outputLine('one\n')), ndjsonBody(outputLine('two\n'))],
+    });
+
+    const inline = await authedGet(stream, 0);
+    expect(inline.json().mode).toBe('inline');
+    const inlineNdjson = inline.json().ndjson;
+
+    const objectKey = await compact(stream.id);
+    const objectBytes = gunzipSync(await getObjectBytes(objectKey)).toString('utf8');
+    expect(objectBytes).toBe(inlineNdjson);
+
+    await deleteObject(objectKey);
+  });
+
+  it('pages a stream larger than the inline cap and drains via has_more', async () => {
+    const workspaceId = crypto.randomUUID();
+    // Test cap is 256 bytes (LOG_READ_INLINE_MAX_BYTES); these six lines exceed it.
+    const lines = Array.from({length: 6}, (_, i) => outputLine(`line-${i}\n`));
+    const stream = await arrangeStream({
+      workspaceId,
+      chunks: lines.map((line) => ndjsonBody(line)),
+    });
+
+    let cursor = 0;
+    let collected = '';
+    let pages = 0;
+    let hasMore = true;
+    while (hasMore && pages < 20) {
+      const body = (await authedGet(stream, cursor)).json();
+      collected += body.ndjson;
+      cursor = body.next_cursor;
+      hasMore = body.has_more;
+      pages += 1;
+    }
+
+    expect(pages).toBeGreaterThan(1);
+    expect(hasMore).toBe(false);
+    expect(collected).toBe(lines.join(''));
+  });
+
+  it('serves a closed-but-uncompacted stream inline and surfaces truncation', async () => {
+    const workspaceId = crypto.randomUUID();
+    const stream = await arrangeStream({
+      workspaceId,
+      state: 'closed',
+      truncated: true,
+      chunks: [ndjsonBody(outputLine('x\n'))],
+    });
+
+    const body = (await authedGet(stream, 0)).json();
+
+    expect(body.mode).toBe('inline');
+    expect(body.state).toBe('closed');
+    expect(body.truncated).toBe(true);
+  });
+
+  it('serves a compacted stream as a working presigned URL', async () => {
+    const workspaceId = crypto.randomUUID();
+    const ndjson = outputLine('hello\n');
+    const stream = await arrangeStream({
+      workspaceId,
+      state: 'closed',
+      chunks: [ndjsonBody(ndjson)],
+    });
+    const objectKey = await compact(stream.id);
+
+    const body = (await authedGet(stream, 0)).json();
+
+    expect(body.mode).toBe('presigned');
+    expect(body.state).toBe('closed');
+    expect(typeof body.url).toBe('string');
+    expect(body.total_bytes).toBe(stream.committedLength);
+    const ttlMs = config.LOG_READ_URL_TTL_SECONDS * 1000;
+    expect(Math.abs(Date.parse(body.expires_at) - (Date.now() + ttlMs))).toBeLessThan(60_000);
+
+    const fetched = await fetch(body.url);
+    expect(fetched.status).toBe(200);
+    const raw = Buffer.from(await fetched.arrayBuffer());
+    // undici may auto-decompress the gzip object (Content-Encoding: gzip), so accept either.
+    const content =
+      raw[0] === 0x1f && raw[1] === 0x8b ? gunzipSync(raw).toString('utf8') : raw.toString('utf8');
+    expect(content).toBe(ndjson);
+
+    await deleteObject(objectKey);
+  });
+
+  it('serves stream metadata on the logs endpoint for an existing stream', async () => {
+    const stream = await arrangeStream({
+      workspaceId: crypto.randomUUID(),
+      chunks: [],
+    });
+
+    const res = await authedGet(stream, 0);
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toMatchObject({
+      mode: 'inline',
+      state: 'open',
+      truncated: false,
+    });
+  });
+
+  it('serves normalized session records as log NDJSON with terminal stream state', async () => {
+    const row = {
+      kind: 'message',
+      timestamp: 1,
+      role: 'assistant',
+      label: 'assistant',
+      meta: [],
+      text: 'Done.',
+      terminalFailure: false,
+    } as const;
+    const stream = await arrangeStream({
+      workspaceId: crypto.randomUUID(),
+      state: 'closed',
+      truncated: true,
+      chunks: [ndjsonBody(recordLine({type: 'agent_session', row}))],
+    });
+
+    const res = await authedGet(stream, 0);
+    const body = res.json();
+
+    expect(res.statusCode).toBe(200);
+    expect(body).toMatchObject({
+      mode: 'inline',
+      state: 'closed',
+      truncated: true,
+    });
+    expect(parseLogRecordLine(body.ndjson.trim())).toEqual({
+      v: 1,
+      ts: 1,
+      type: 'agent_session',
+      row,
+    });
+  });
+});
+
+describe('buildLogReadResult compaction boundary', () => {
+  // The route always reloads the row, so the race the guard defends against (a closed stream
+  // that compacts between the load and the chunk read) can't be staged through HTTP. Exercise
+  // the guard directly: hand it a stale pre-compaction snapshot while the row has since compacted.
+  it('re-reads and serves presigned when a closed stream compacts after it was loaded', async () => {
+    const stale = await arrangeStream({
+      workspaceId: crypto.randomUUID(),
+      state: 'closed',
+      chunks: [],
+    });
+
+    await db()
+      .update(attemptStreams)
+      .set({objectKey: 'logs/compacted-after-load.ndjson.gz'})
+      .where(eq(attemptStreams.id, stale.id));
+
+    const result = await buildLogReadResult(stale, 0);
+
+    expect(result.mode).toBe('presigned');
+  });
+});

package/src/presentation/routes/read-logs.ts

@@ -0,0 +1,38 @@
+import {requireUserContext} from '@shipfox/api-auth-context';
+import {readLogsQuerySchema, readLogsResponseSchema} from '@shipfox/api-logs-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {buildLogReadResult} from '#core/read-logs.js';
+import {getStreamByStepAttempt} from '#db/streams.js';
+import {toReadLogsDto} from '#presentation/dto/read-logs.js';
+
+export const readLogsRoute = defineRoute({
+  method: 'GET',
+  path: '/:stepId/attempts/:attempt/logs',
+  description:
+    'Read a page of logs for a step attempt: inline NDJSON while the stream is hot, a presigned object URL once it is compacted.',
+  schema: {
+    params: z.object({
+      stepId: z.string().uuid(),
+      attempt: z.coerce.number().int().min(1),
+    }),
+    querystring: readLogsQuerySchema,
+    response: {
+      200: readLogsResponseSchema,
+    },
+  },
+  handler: async (request) => {
+    const user = requireUserContext(request);
+    const {stepId, attempt} = request.params;
+    const {cursor} = request.query;
+
+    const stream = await getStreamByStepAttempt({stepId, attempt});
+    // 404 covers both "no such stream" and "not your workspace" so the endpoint never
+    // leaks the existence of another workspace's step.
+    if (!stream || !user.canAccess(stream.workspaceId)) {
+      throw new ClientError('Logs not found', 'not-found', {status: 404});
+    }
+
+    return toReadLogsDto(await buildLogReadResult(stream, cursor));
+  },
+});

package/src/presentation/subscribers/on-job-terminated.test.ts

@@ -0,0 +1,64 @@
+import type {WorkflowsJobTerminatedEventDto} from '@shipfox/api-workflows-dto';
+import {config} from '#config.js';
+import {LOGS_LIFECYCLE_TASK_QUEUE} from '#temporal/constants.js';
+import {onJobTerminated} from './on-job-terminated.js';
+
+const startMock = vi.fn();
+
+vi.mock('@shipfox/node-temporal', () => ({
+  temporalClient: () => ({
+    workflow: {
+      start: startMock,
+    },
+  }),
+}));
+
+function buildPayload(jobId: string): WorkflowsJobTerminatedEventDto {
+  return {
+    jobId,
+    workflowRunId: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    status: 'failed',
+    statusReason: null,
+  };
+}
+
+function alreadyStartedError(): Error {
+  const error = new Error('Workflow execution already started');
+  error.name = 'WorkflowExecutionAlreadyStartedError';
+  return error;
+}
+
+describe('onJobTerminated', () => {
+  beforeEach(() => {
+    startMock.mockReset();
+    startMock.mockResolvedValue({});
+  });
+
+  it('arms the close-abandoned-streams workflow keyed on the job id', async () => {
+    const jobId = crypto.randomUUID();
+
+    await onJobTerminated(buildPayload(jobId));
+
+    expect(startMock).toHaveBeenCalledTimes(1);
+    expect(startMock).toHaveBeenCalledWith('closeAbandonedStreams', {
+      taskQueue: LOGS_LIFECYCLE_TASK_QUEUE,
+      workflowId: `logs-close:${jobId}`,
+      args: [{jobId, graceSeconds: config.LOG_STREAM_CLOSE_GRACE_SECONDS}],
+    });
+  });
+
+  it('swallows a redelivered event when the workflow is already started', async () => {
+    startMock.mockRejectedValue(alreadyStartedError());
+
+    await expect(onJobTerminated(buildPayload(crypto.randomUUID()))).resolves.toBeUndefined();
+  });
+
+  it('re-throws an unexpected start failure so the outbox retries delivery', async () => {
+    startMock.mockRejectedValue(new Error('temporal unreachable'));
+
+    await expect(onJobTerminated(buildPayload(crypto.randomUUID()))).rejects.toThrow(
+      'temporal unreachable',
+    );
+  });
+});

package/src/presentation/subscribers/on-job-terminated.ts

@@ -0,0 +1,26 @@
+import type {WorkflowsJobTerminatedEventDto} from '@shipfox/api-workflows-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {temporalClient} from '@shipfox/node-temporal';
+import {config} from '#config.js';
+import {LOGS_LIFECYCLE_TASK_QUEUE} from '#temporal/constants.js';
+
+/**
+ * A job reached a terminal state (any path: completion, cancellation, lease-expiry,
+ * timeout). Arm the grace-then-close workflow for any of its streams the runner never
+ * ended itself. Deduped by workflow id, so a redelivered event is a no-op.
+ */
+export async function onJobTerminated(payload: WorkflowsJobTerminatedEventDto): Promise<void> {
+  try {
+    await temporalClient().workflow.start('closeAbandonedStreams', {
+      taskQueue: LOGS_LIFECYCLE_TASK_QUEUE,
+      workflowId: `logs-close:${payload.jobId}`,
+      args: [{jobId: payload.jobId, graceSeconds: config.LOG_STREAM_CLOSE_GRACE_SECONDS}],
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === 'WorkflowExecutionAlreadyStartedError') {
+      logger().debug({jobId: payload.jobId}, 'Close-abandoned-streams workflow already started');
+      return;
+    }
+    throw error;
+  }
+}

package/src/presentation/subscribers/on-log-stream-closed.test.ts

@@ -0,0 +1,63 @@
+import type {LogStreamClosedEvent} from '@shipfox/api-logs-dto';
+import {LOGS_COMPACTION_TASK_QUEUE} from '#temporal/constants.js';
+import {onLogStreamClosed} from './on-log-stream-closed.js';
+
+const startMock = vi.hoisted(() => vi.fn());
+
+vi.mock('@shipfox/node-temporal', () => ({
+  temporalClient: () => ({
+    workflow: {
+      start: startMock,
+    },
+  }),
+}));
+
+function buildPayload(streamId: string): LogStreamClosedEvent {
+  return {
+    workspaceId: crypto.randomUUID(),
+    jobId: crypto.randomUUID(),
+    stepId: crypto.randomUUID(),
+    attempt: 1,
+    streamId,
+  };
+}
+
+function alreadyStartedError(): Error {
+  const error = new Error('Workflow execution already started');
+  error.name = 'WorkflowExecutionAlreadyStartedError';
+  return error;
+}
+
+describe('onLogStreamClosed', () => {
+  beforeEach(() => {
+    startMock.mockReset();
+    startMock.mockResolvedValue({});
+  });
+
+  it('starts the compaction workflow keyed on the stream id', async () => {
+    const streamId = crypto.randomUUID();
+
+    await onLogStreamClosed(buildPayload(streamId));
+
+    expect(startMock).toHaveBeenCalledTimes(1);
+    expect(startMock).toHaveBeenCalledWith('compactStream', {
+      taskQueue: LOGS_COMPACTION_TASK_QUEUE,
+      workflowId: `logs-compact:${streamId}`,
+      args: [{streamId}],
+    });
+  });
+
+  it('swallows a redelivered event when the workflow is already started', async () => {
+    startMock.mockRejectedValue(alreadyStartedError());
+
+    await expect(onLogStreamClosed(buildPayload(crypto.randomUUID()))).resolves.toBeUndefined();
+  });
+
+  it('re-throws an unexpected start failure so the outbox retries delivery', async () => {
+    startMock.mockRejectedValue(new Error('temporal unreachable'));
+
+    await expect(onLogStreamClosed(buildPayload(crypto.randomUUID()))).rejects.toThrow(
+      'temporal unreachable',
+    );
+  });
+});