@shipfox/api-logs-dto 10.2.0 → 16.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-logs-dto",
   "license": "MIT",
-  "version": "10.2.0",
+  "version": "16.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -15,10 +15,15 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./inter-module": {
+      "types": "./dist/inter-module.d.ts",
+      "default": "./dist/inter-module.js"
     }
   },
   "dependencies": {
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@shipfox/inter-module": "0.2.3"
   },
   "imports": {
     "#*": "./dist/*"

package/src/index.ts

@@ -11,7 +11,9 @@ export {
   appendLogsQuerySchema,
   appendLogsResponseSchema,
   type LogRecord,
+  type LogWriterConflictResponseDto,
   logRecordSchema,
+  logWriterConflictResponseSchema,
   MAX_RECORD_DATA_BYTES,
   MAX_RECORD_NAME_BYTES,
   type OffsetGapResponseDto,
@@ -25,6 +27,7 @@ export {
   readLogsQuerySchema,
   readLogsResponseSchema,
   SESSION_VIEW_VERSION,
+  type ServerLogRecord,
   type SessionViewDto,
   type SessionViewLifecycleRow,
   type SessionViewMessageRow,
@@ -34,6 +37,7 @@ export {
   type SessionViewThinkingRow,
   type SessionViewToolCallRow,
   type SessionViewToolResultRow,
+  serverLogRecordSchema,
   sessionViewLifecycleRowSchema,
   sessionViewMessageRowSchema,
   sessionViewRawRowSchema,

package/src/inter-module.test.ts

@@ -0,0 +1,69 @@
+import {logsInterModuleContract} from './inter-module.js';
+
+describe('logsInterModuleContract', () => {
+  test('accepts server-origin append commands', () => {
+    const input = logsInterModuleContract.methods.appendServerRecords.input.parse({
+      jobId: '00000000-0000-4000-8000-000000000001',
+      workspaceId: '00000000-0000-4000-8000-000000000002',
+      projectId: '00000000-0000-4000-8000-000000000003',
+      workflowRunAttemptId: '00000000-0000-4000-8000-000000000004',
+      stepId: '00000000-0000-4000-8000-000000000005',
+      attempt: 1,
+      records: [
+        {v: 1, ts: 1, type: 'output', stream: 'stdout', data: 'hello'},
+        {v: 1, ts: 1, type: 'group_start', group_id: 'g1', parent_group_id: null, name: 'call'},
+        {v: 1, ts: 1, type: 'group_end', group_id: 'g1'},
+      ],
+    });
+
+    expect(input.attempt).toBe(1);
+    expect(input.records).toHaveLength(3);
+    expect(input.records[1]).toMatchObject({type: 'group_start'});
+  });
+
+  test('rejects records outside the server-writable stored union', () => {
+    const result = logsInterModuleContract.methods.appendServerRecords.input.safeParse({
+      jobId: '00000000-0000-4000-8000-000000000001',
+      workspaceId: '00000000-0000-4000-8000-000000000002',
+      projectId: '00000000-0000-4000-8000-000000000003',
+      workflowRunAttemptId: '00000000-0000-4000-8000-000000000004',
+      stepId: '00000000-0000-4000-8000-000000000005',
+      attempt: 1,
+      records: [{v: 1, ts: 1, type: 'agent_session', data: 'raw entry, not yet normalized'}],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects server-only tombstones', () => {
+    const result = logsInterModuleContract.methods.appendServerRecords.input.safeParse({
+      jobId: '00000000-0000-4000-8000-000000000001',
+      workspaceId: '00000000-0000-4000-8000-000000000002',
+      projectId: '00000000-0000-4000-8000-000000000003',
+      workflowRunAttemptId: '00000000-0000-4000-8000-000000000004',
+      stepId: '00000000-0000-4000-8000-000000000005',
+      attempt: 1,
+      records: [{v: 1, ts: 1, type: 'capped'}],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('keeps identity, attempt, and output bounds enforced', () => {
+    const input = {
+      jobId: '00000000-0000-4000-8000-000000000001',
+      workspaceId: '00000000-0000-4000-8000-000000000002',
+      projectId: '00000000-0000-4000-8000-000000000003',
+      workflowRunAttemptId: '00000000-0000-4000-8000-000000000004',
+      stepId: '00000000-0000-4000-8000-000000000005',
+      attempt: 1,
+      records: [],
+    };
+    const schema = logsInterModuleContract.methods.appendServerRecords;
+
+    expect(schema.input.safeParse({...input, attempt: 0}).success).toBe(false);
+    expect(schema.input.safeParse({...input, attempt: 2_147_483_648}).success).toBe(false);
+    expect(schema.input.safeParse({...input, jobId: 'not-a-uuid'}).success).toBe(false);
+    expect(schema.output.safeParse({committedLength: 0, capped: true}).success).toBe(true);
+  });
+});

package/src/inter-module.ts

@@ -0,0 +1,69 @@
+import {defineInterModuleContract, type InterModuleClient} from '@shipfox/inter-module';
+import {z} from 'zod';
+import {serverLogRecordSchema} from './schemas/index.js';
+
+const idSchema = z.string().uuid();
+
+/**
+ * Producer-owned Logs commands used by synchronous callers. The only method
+ * today is the server-origin append for server-executed steps (the tool step
+ * executor): it writes already-normalized stored records through the same
+ * offset-CAS and budget pipeline as the lease-bound runner route, but with
+ * chunk `origin` `server` and a tail-derived CAS offset (the caller owns no
+ * spool cursor). This is a trusted internal boundary, not an authorization
+ * boundary: the caller must derive the identity fields from its execution
+ * context rather than pass through arbitrary external input.
+ */
+export const logsInterModuleContract = defineInterModuleContract({
+  module: 'logs',
+  methods: {
+    appendServerRecords: {
+      input: z.object({
+        jobId: idSchema,
+        workspaceId: idSchema,
+        projectId: idSchema,
+        workflowRunAttemptId: idSchema,
+        stepId: idSchema,
+        attempt: z
+          .number()
+          .int()
+          .min(1)
+          .max(2_147_483_647)
+          .describe('Attempt number of the step this batch belongs to.'),
+        /**
+         * Already-normalized server-writable stored records (the read union
+         * without server-only tombstones), serialized to whole newline-terminated
+         * NDJSON lines on ingest. Server-origin records skip the raw-to-stored
+         * normalization the runner path applies: they are stored verbatim. Callers should
+         * coalesce records into batches up to (but never over) `LOG_APPEND_BODY_LIMIT_BYTES`;
+         * an empty batch is reserved for a heartbeat. A server-origin writer owns its stream;
+         * it cannot be mixed with a lease-bound runner writer because their byte cursors differ.
+         */
+        records: z.array(serverLogRecordSchema),
+      }),
+      output: z.object({
+        committedLength: z
+          .number()
+          .int()
+          .min(0)
+          .describe(
+            'New server-held byte position of the stream after this batch was applied (the tail the next call continues from).',
+          ),
+        capped: z
+          .boolean()
+          .describe(
+            'When true, the per-job log budget is exhausted and further output is dropped.',
+          ),
+      }),
+      errors: {
+        'lease-stream-mismatch': z.object({}),
+        'malformed-log-chunk': z.object({}),
+        'append-body-too-large': z.object({maxBytes: z.number().int().positive()}),
+        'runner-writer-active': z.object({}),
+        'offset-gap': z.object({committedLength: z.number().int().nonnegative()}),
+      },
+    },
+  },
+});
+
+export type LogsModuleClient = InterModuleClient<typeof logsInterModuleContract>;

package/src/schemas/append.ts

@@ -4,7 +4,7 @@ import {z} from 'zod';
  * Append endpoint contract: `POST .../steps/:stepId/logs?attempt=N&offset=B`.
  *
  * The body is raw NDJSON bytes (whole records, newline-terminated), not a
- * Zod-validated object — it is parsed line by line against the raw log record
+ * Zod-validated object: it is parsed line by line against the raw log record
  * union (`rawLogRecordSchema`). `offset` is a position in the raw
  * NDJSON spool stream; both `offset` and the returned `committed_length` are
  * bounded far below 2^53 by the accrual budget, so JavaScript `number` is safe.
@@ -53,3 +53,10 @@ export const offsetGapResponseSchema = z.object({
 });
 
 export type OffsetGapResponseDto = z.infer<typeof offsetGapResponseSchema>;
+
+/** A lease append was attempted on a stream owned by a server-origin writer. */
+export const logWriterConflictResponseSchema = z.object({
+  code: z.literal('log-writer-conflict'),
+});
+
+export type LogWriterConflictResponseDto = z.infer<typeof logWriterConflictResponseSchema>;

package/src/schemas/index.ts

@@ -3,6 +3,8 @@ export {
   type AppendLogsResponseDto,
   appendLogsQuerySchema,
   appendLogsResponseSchema,
+  type LogWriterConflictResponseDto,
+  logWriterConflictResponseSchema,
   type OffsetGapResponseDto,
   offsetGapResponseSchema,
 } from './append.js';
@@ -21,6 +23,8 @@ export {
   parseRawLogRecordLine,
   type RawLogRecord,
   rawLogRecordSchema,
+  type ServerLogRecord,
+  serverLogRecordSchema,
 } from './record.js';
 export {
   SESSION_VIEW_VERSION,

package/src/schemas/read.ts

@@ -70,7 +70,9 @@ const readLogsPresignedSchema = z.object({
     .number()
     .int()
     .min(0)
-    .describe('Committed append byte position for the attempt. This is the runner CAS axis.'),
+    .describe(
+      'Committed append byte position for the attempt. This is the active writer CAS axis.',
+    ),
   truncated: z
     .boolean()
     .describe('True when the stream was force-closed because the runner stopped reporting.'),

package/src/schemas/record.ts

@@ -2,10 +2,10 @@ import {z} from 'zod';
 import {sessionViewRowSchema} from './session-view.js';
 
 /**
- * NDJSON log record contract — one JSON object per line, runner-framed.
+ * NDJSON log record contract: one JSON object per line, runner-framed.
  *
  * `offset` / `committed_length` are byte positions in the raw append NDJSON spool stream
- * (envelope included) — the offset-CAS axis the runner tracks. The per-job accrual
+ * (envelope included): the offset-CAS axis the runner tracks. The per-job accrual
  * budget charges the normalized NDJSON bytes the server stores, so framing and control records
  * count against it too. The per-record byte caps below bound each record so a single
  * entry's overhead is known and a runner cannot grow storage without moving the
@@ -123,19 +123,27 @@ export const rawLogRecordSchema = z.discriminatedUnion('type', [
 ]);
 
 /** Stored/read records: regular records, normalized agent sessions, and tombstones. */
-export const logRecordSchema = z.discriminatedUnion('type', [
+const storedLogRecordSchemas = [
   logOutput,
   logGroupStart,
   logGroupEnd,
   logEnd,
   logGap,
   agentSession,
+] as const;
+
+export const logRecordSchema = z.discriminatedUnion('type', [
+  ...storedLogRecordSchemas,
   logCapped,
   logRunnerLost,
 ]);
 
+/** Records a trusted server-origin writer may append: stored records without tombstones. */
+export const serverLogRecordSchema = z.discriminatedUnion('type', storedLogRecordSchemas);
+
 export type RawLogRecord = z.infer<typeof rawLogRecordSchema>;
 export type LogRecord = z.infer<typeof logRecordSchema>;
+export type ServerLogRecord = z.infer<typeof serverLogRecordSchema>;
 
 export function parseLogRecordLine(line: string): LogRecord {
   return logRecordSchema.parse(JSON.parse(line));
@@ -144,7 +152,7 @@ export function parseLogRecordLine(line: string): LogRecord {
 /**
  * Parses one NDJSON line against the raw write union. A forged
  * server-only `capped` / `runner_lost` record fails here even though it is valid
- * under the read union — this is the write-path forgery guard.
+ * under the read union: this is the write-path forgery guard.
  */
 export function parseRawLogRecordLine(line: string): RawLogRecord {
   return rawLogRecordSchema.parse(JSON.parse(line));