@astrale-os/cli 1.0.0-beta.18 → 1.0.0-beta.19

package/dist/astrale.js

@@ -2578,7 +2578,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "1.0.0-beta.18",
+    version: "1.0.0-beta.19",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -9845,7 +9845,7 @@ var init_output = __esm(() => {
   init_dist();
   init_table();
   RAW_OUTPUT_OPTIONS = [
-    { flags: "--json", description: "Always-valid JSON (for jq)" },
+    { flags: "--json", description: "JSON; streaming commands emit one JSON value per line" },
     { flags: "--raw", description: "Unwrapped: bare scalar / raw bytes / JSON for objects" }
   ];
   NOISE_KEYS = new Set(["schema", "icon", "code", "inputSchema", "outputSchema"]);
@@ -82400,7 +82400,10 @@ var exports_logs = {};
 __export(exports_logs, {
   acceptJournalPage: () => acceptJournalPage,
   buildJournalInput: () => buildJournalInput,
-  default: () => logs_default
+  default: () => logs_default,
+  followLogs: () => followLogs,
+  formatFollowRecord: () => formatFollowRecord,
+  validateLogsOpts: () => validateLogsOpts
 });
 function buildJournalInput(opts) {
   const exact13 = nonEmpty4(opts.topic);
@@ -82473,8 +82476,12 @@ async function runOnce(opts) {
     }
   });
 }
-async function follow(opts) {
-  await runKernelCommand({
+async function followLogs(opts, dependencies = {
+  run: runKernelCommand,
+  pause: (milliseconds) => new Promise((resolve6) => setTimeout(resolve6, milliseconds))
+}) {
+  validateLogsOpts(opts);
+  await dependencies.run({
     opts,
     label: "Kernel journal",
     fn: async (context) => {
@@ -82483,9 +82490,9 @@ async function follow(opts) {
       for (;; ) {
         const page = await fetchPage(context, { ...resolved, cursor });
         for (const record12 of page.records)
-          printRecord(record12);
+          printRecord(record12, opts);
         cursor = page.cursor ?? cursor;
-        await new Promise((resolve6) => setTimeout(resolve6, FOLLOW_INTERVAL_MS));
+        await dependencies.pause(FOLLOW_INTERVAL_MS);
       }
     }
   });
@@ -82508,10 +82515,24 @@ function journalProjection(records) {
     paths: records.map((record12) => String(record12.sequence))
   };
 }
-function printRecord(record12) {
+function printRecord(record12, opts) {
+  if (isMachine(opts) || opts.format === "json") {
+    process.stdout.write(formatFollowRecord(record12));
+    return;
+  }
   process.stdout.write(`${source_default.dim(String(record12.sequence).padStart(6))} ${source_default.dim(record12.timestamp)} ${source_default.cyan(record12.topic)} ${source_default.dim(record12.principal ?? "")}
 `);
 }
+function formatFollowRecord(record12) {
+  return `${JSON.stringify(record12)}
+`;
+}
+function validateLogsOpts(opts) {
+  buildJournalInput(opts);
+  if (opts.follow && opts.format === "yaml" && !opts.json && !opts.raw) {
+    throw new TypeError("--follow does not support YAML; use --json for an NDJSON stream");
+  }
+}
 function acceptRecord(input, index3) {
   if (!isRecord7(input) || !Number.isSafeInteger(input.sequence) || typeof input.topic !== "string") {
     throw new TypeError(`Kernel journal record ${index3} is invalid`);
@@ -82521,8 +82542,13 @@ function acceptRecord(input, index3) {
   if (timestamp === undefined) {
     throw new TypeError(`Kernel journal record ${index3} is missing occurredAt/timestamp`);
   }
-  const correlation = isRecord7(input.correlation) ? input.correlation : undefined;
-  const correlationId = optionalText2(input.correlationId, index3, "correlationId") ?? optionalText2(correlation?.invocationId, index3, "correlation.invocationId");
+  const correlation = acceptCorrelation(input.correlation, index3);
+  const legacyCorrelationId = optionalIdentifier(input.correlationId, index3, "correlationId");
+  const structuredCorrelationId = correlation?.invocationId;
+  if (legacyCorrelationId !== undefined && structuredCorrelationId !== undefined && legacyCorrelationId !== structuredCorrelationId) {
+    throw new TypeError(`Kernel journal record ${index3} has conflicting correlation identifiers`);
+  }
+  const correlationId = structuredCorrelationId ?? legacyCorrelationId;
   const principal = optionalText2(input.principal, index3, "principal");
   return Object.freeze({
     sequence: input.sequence,
@@ -82532,10 +82558,35 @@ function acceptRecord(input, index3) {
     ...occurredAt === undefined ? {} : { occurredAt },
     ...optionalText2(input.committedAt, index3, "committedAt") === undefined ? {} : { committedAt: input.committedAt },
     ...principal === undefined ? {} : { principal },
+    ...correlation === undefined ? {} : { correlation },
     ...correlationId === undefined ? {} : { correlationId },
-    ...optionalText2(input.causationId, index3, "causationId") === undefined ? {} : { causationId: input.causationId }
+    ...optionalIdentifier(input.causationId, index3, "causationId") === undefined ? {} : { causationId: input.causationId }
   });
 }
+function acceptCorrelation(input, index3) {
+  if (input === undefined)
+    return;
+  if (!isRecord7(input)) {
+    throw new TypeError(`Kernel journal record ${index3}.correlation must be an object`);
+  }
+  const unknown2 = Object.keys(input).find((field) => !correlationFields.includes(field));
+  if (unknown2 !== undefined) {
+    throw new TypeError(`Kernel journal record ${index3}.correlation.${unknown2} is unsupported`);
+  }
+  return Object.freeze(Object.fromEntries(correlationFields.flatMap((field) => {
+    const value3 = optionalIdentifier(input[field], index3, `correlation.${field}`);
+    return value3 === undefined ? [] : [[field, value3]];
+  })));
+}
+function optionalIdentifier(input, index3, field) {
+  const value3 = optionalText2(input, index3, field);
+  if (value3 === undefined)
+    return;
+  if (value3.trim() === "" || new TextEncoder().encode(value3).byteLength > 256) {
+    throw new TypeError(`Kernel journal record ${index3}.${field} must be non-empty and at most 256 UTF-8 bytes`);
+  }
+  return value3;
+}
 function optionalText2(input, index3, field) {
   if (input === undefined)
     return;
@@ -82567,7 +82618,7 @@ function nonEmpty4(input) {
 function isRecord7(input) {
   return input !== null && typeof input === "object" && !Array.isArray(input);
 }
-var JOURNAL_PATH, DEFAULT_LIMIT2 = 200, FOLLOW_INTERVAL_MS = 2000, ISO_TIMESTAMP, CURSOR_TOKEN, logs_default;
+var JOURNAL_PATH, DEFAULT_LIMIT2 = 200, FOLLOW_INTERVAL_MS = 2000, ISO_TIMESTAMP, CURSOR_TOKEN, correlationFields, logs_default;
 var init_logs = __esm(() => {
   init_path3();
   init_schema9();
@@ -82578,6 +82629,15 @@ var init_logs = __esm(() => {
   JOURNAL_PATH = Path.project(K.functions.journal.ref).raw;
   ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
   CURSOR_TOKEN = /^[A-Za-z0-9._:+=/-]{8,}$/;
+  correlationFields = [
+    "operationId",
+    "parentOperationId",
+    "invocationId",
+    "rootInvocationId",
+    "parentInvocationId",
+    "traceId",
+    "spanId"
+  ];
   logs_default = {
     name: "logs",
     description: "Read or follow the authorized Kernel journal",
@@ -82586,7 +82646,8 @@ Behavior:
   Calls the public Kernel journal syscall and emits its { records, cursor }
   page. Topic selection is exact or prefix-based; cursors and timestamps are
   opaque strings owned by the journal backend. --follow reuses one Client Session
-  and advances only with the returned cursor.
+  and advances only with the returned cursor. Machine follow output is NDJSON:
+  one complete admitted record per line; YAML follow is unsupported.
 
   Historical event-glob lowering and the application-specific services-domain
   log buffer are not part of the Kernel V2 journal contract.
@@ -82608,12 +82669,12 @@ Examples:
     ],
     action: async (opts) => {
       try {
-        buildJournalInput(opts);
+        validateLogsOpts(opts);
       } catch (error52) {
         failInput(error52, opts);
       }
       if (opts.follow)
-        await follow(opts);
+        await followLogs(opts);
       else
         await runOnce(opts);
     }

package/dist/types/lib/output.d.ts

@@ -11,7 +11,7 @@ export type MachineOpts = RawOutputOpts & {
 };
 export declare const RAW_OUTPUT_OPTIONS: readonly [{
     readonly flags: '--json';
-    readonly description: 'Always-valid JSON (for jq)';
+    readonly description: 'JSON; streaming commands emit one JSON value per line';
 }, {
     readonly flags: '--raw';
     readonly description: 'Unwrapped: bare scalar / raw bytes / JSON for objects';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",

package/src/commands/__tests__/logs.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from 'bun:test'
 
-import { acceptJournalPage, buildJournalInput } from '../logs'
+import logsCommand, {
+  acceptJournalPage,
+  buildJournalInput,
+  followLogs,
+  formatFollowRecord,
+} from '../logs'
 
 describe('buildJournalInput', () => {
   /** @evidence TEST-CLI-LOGS-MAPS-EXACT-JOURNAL-INPUT */
@@ -81,7 +86,15 @@ describe('acceptJournalPage', () => {
           occurredAt: '2026-08-19T16:51:10.049Z',
           committedAt: '2026-08-19T16:51:10.070Z',
           payload: { outcome: 'rejected' },
-          correlation: { invocationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95' },
+          correlation: {
+            operationId: 'operation-child',
+            parentOperationId: 'operation-parent',
+            invocationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95',
+            rootInvocationId: 'invocation-root',
+            parentInvocationId: 'invocation-parent',
+            traceId: 'trace-1',
+            spanId: 'span-1',
+          },
         },
       ],
     })
@@ -91,7 +104,242 @@ describe('acceptJournalPage', () => {
       timestamp: '2026-08-19T16:51:10.049Z',
       occurredAt: '2026-08-19T16:51:10.049Z',
       committedAt: '2026-08-19T16:51:10.070Z',
+      correlation: {
+        operationId: 'operation-child',
+        parentOperationId: 'operation-parent',
+        invocationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95',
+        rootInvocationId: 'invocation-root',
+        parentInvocationId: 'invocation-parent',
+        traceId: 'trace-1',
+        spanId: 'span-1',
+      },
       correlationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95',
     })
   })
+
+  test('rejects malformed or invented structured correlation fields', () => {
+    const record = {
+      sequence: 1,
+      topic: 'function.invoke',
+      occurredAt: '2026-08-19T16:51:10.049Z',
+      payload: {},
+    }
+    expect(() => acceptJournalPage({ records: [{ ...record, correlation: 'opaque' }] })).toThrow(
+      'correlation must be an object',
+    )
+    expect(() =>
+      acceptJournalPage({ records: [{ ...record, correlation: { authority: 'forged' } }] }),
+    ).toThrow('correlation.authority is unsupported')
+    for (const field of [
+      'operationId',
+      'parentOperationId',
+      'invocationId',
+      'rootInvocationId',
+      'parentInvocationId',
+      'traceId',
+      'spanId',
+    ]) {
+      expect(() =>
+        acceptJournalPage({ records: [{ ...record, correlation: { [field]: 7 } }] }),
+      ).toThrow(`correlation.${field}`)
+    }
+    expect(() =>
+      acceptJournalPage({ records: [{ ...record, correlation: { invocationId: '   ' } }] }),
+    ).toThrow('must be non-empty')
+    expect(() =>
+      acceptJournalPage({
+        records: [{ ...record, correlation: { invocationId: 'x'.repeat(257) } }],
+      }),
+    ).toThrow('at most 256 UTF-8 bytes')
+    expect(
+      acceptJournalPage({
+        records: [{ ...record, correlation: { invocationId: 'x'.repeat(256) } }],
+      }).records[0].correlation?.invocationId,
+    ).toHaveLength(256)
+    expect(
+      acceptJournalPage({
+        records: [{ ...record, correlation: { invocationId: 'é'.repeat(128) } }],
+      }).records[0].correlation?.invocationId,
+    ).toHaveLength(128)
+    expect(() =>
+      acceptJournalPage({
+        records: [{ ...record, correlation: { invocationId: `${'é'.repeat(127)}€` } }],
+      }),
+    ).toThrow('at most 256 UTF-8 bytes')
+  })
+
+  test('keeps legacy identity compatibility coherent with structured correlation', () => {
+    const record = {
+      sequence: 1,
+      topic: 'function.invoke',
+      occurredAt: '2026-08-19T16:51:10.049Z',
+      payload: {},
+    }
+    expect(
+      acceptJournalPage({
+        records: [{ ...record, correlationId: 'legacy-only', causationId: 'legacy-cause' }],
+      }).records[0],
+    ).toMatchObject({ correlationId: 'legacy-only', causationId: 'legacy-cause' })
+    expect(
+      acceptJournalPage({
+        records: [
+          {
+            ...record,
+            correlationId: 'same',
+            correlation: { invocationId: 'same' },
+          },
+        ],
+      }).records[0],
+    ).toMatchObject({ correlationId: 'same', correlation: { invocationId: 'same' } })
+    expect(() =>
+      acceptJournalPage({
+        records: [
+          {
+            ...record,
+            correlationId: 'legacy',
+            correlation: { invocationId: 'structured' },
+          },
+        ],
+      }),
+    ).toThrow('conflicting correlation identifiers')
+  })
+
+  test('serializes one complete structured record per machine-follow line', () => {
+    const record = acceptJournalPage({
+      records: [
+        {
+          sequence: 2,
+          topic: 'function.invoke',
+          occurredAt: '2026-08-19T16:51:10.049Z',
+          payload: { outcome: 'completed' },
+          correlation: {
+            operationId: 'operation-child',
+            parentOperationId: 'operation-parent',
+            invocationId: 'invocation-child',
+            rootInvocationId: 'invocation-root',
+            parentInvocationId: 'invocation-parent',
+            traceId: 'trace-1',
+            spanId: 'span-1',
+          },
+        },
+      ],
+    }).records[0]
+    expect(formatFollowRecord(record).endsWith('\n')).toBe(true)
+    expect(JSON.parse(formatFollowRecord(record))).toEqual(record)
+  })
+})
+
+describe('follow output routing', () => {
+  const inputRecord = {
+    sequence: 2,
+    topic: 'function.invoke',
+    occurredAt: '2026-08-19T16:51:10.049Z',
+    payload: { outcome: 'completed' },
+    principal: 'principal-1',
+    correlation: {
+      invocationId: 'invocation-child',
+      rootInvocationId: 'invocation-root',
+      parentInvocationId: 'invocation-parent',
+    },
+  }
+  const admittedRecord = acceptJournalPage({ records: [inputRecord] }).records[0]
+
+  test('routes every effective machine mode through complete NDJSON records', async () => {
+    for (const { opts, tty } of [
+      { opts: { json: true }, tty: true },
+      { opts: { raw: true }, tty: true },
+      { opts: { format: 'json' as const }, tty: true },
+      { opts: { ci: true }, tty: true },
+      { opts: {}, tty: false },
+      { opts: { format: 'yaml' as const, json: true }, tty: true },
+      { opts: { format: 'yaml' as const, raw: true }, tty: true },
+    ]) {
+      const stdout = await captureFollowOutput({ ...opts, follow: true }, tty)
+      expect(stdout.endsWith('\n')).toBe(true)
+      expect(JSON.parse(stdout)).toEqual(admittedRecord)
+    }
+  })
+
+  test('keeps an unflagged TTY human-readable', async () => {
+    const stdout = await captureFollowOutput({ follow: true }, true)
+    expect(stdout).toContain('function.invoke')
+    expect(stdout).toContain('principal-1')
+    expect(stdout).not.toContain('invocation-child')
+    expect(() => JSON.parse(stdout)).toThrow()
+  })
+
+  test('rejects effective YAML before opening a Kernel session with INVALID_INPUT', async () => {
+    let runCalls = 0
+    await expect(
+      followLogs(
+        { follow: true, format: 'yaml' },
+        {
+          run: async () => {
+            runCalls += 1
+          },
+          pause: async () => {},
+        },
+      ),
+    ).rejects.toThrow('--follow does not support YAML')
+    expect(runCalls).toBe(0)
+
+    const originalExit = process.exit
+    const originalStderrWrite = process.stderr.write
+    let stderr = ''
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      stderr += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+      return true
+    }) as typeof process.stderr.write
+    process.exit = ((code?: string | number | null) => {
+      throw new Error(`exit:${String(code)}`)
+    }) as typeof process.exit
+    try {
+      await expect(logsCommand.action({ follow: true, format: 'yaml' })).rejects.toThrow('exit:1')
+      expect(JSON.parse(stderr)).toEqual({
+        error: 'INVALID_INPUT',
+        message: '--follow does not support YAML; use --json for an NDJSON stream',
+      })
+    } finally {
+      process.exit = originalExit
+      process.stderr.write = originalStderrWrite
+    }
+  })
+
+  async function captureFollowOutput(
+    opts: Parameters<typeof followLogs>[0],
+    tty: boolean,
+  ): Promise<string> {
+    const originalWrite = process.stdout.write
+    const originalTty = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY')
+    let stdout = ''
+    let pages = 0
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      stdout += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+      return true
+    }) as typeof process.stdout.write
+    Object.defineProperty(process.stdout, 'isTTY', { configurable: true, value: tty })
+    try {
+      await expect(
+        followLogs(opts, {
+          run: async (input) => {
+            await input.fn({
+              session: {
+                call: async () => {
+                  pages += 1
+                  if (pages === 1) return { records: [inputRecord] }
+                  throw new Error('end of controlled stream')
+                },
+              },
+            } as never)
+          },
+          pause: async () => {},
+        }),
+      ).rejects.toThrow('end of controlled stream')
+      return stdout
+    } finally {
+      process.stdout.write = originalWrite
+      if (originalTty === undefined) delete (process.stdout as { isTTY?: boolean }).isTTY
+      else Object.defineProperty(process.stdout, 'isTTY', originalTty)
+    }
+  }
 })

package/src/commands/logs.ts

@@ -33,10 +33,21 @@ export interface JournalRecord {
   readonly occurredAt?: string
   readonly committedAt?: string
   readonly principal?: string
+  readonly correlation?: JournalCorrelation
   readonly correlationId?: string
   readonly causationId?: string
 }
 
+export interface JournalCorrelation {
+  readonly operationId?: string
+  readonly parentOperationId?: string
+  readonly invocationId?: string
+  readonly rootInvocationId?: string
+  readonly parentInvocationId?: string
+  readonly traceId?: string
+  readonly spanId?: string
+}
+
 export interface JournalPage {
   readonly records: readonly JournalRecord[]
   readonly cursor?: string
@@ -133,8 +144,21 @@ async function runOnce(opts: LogsOpts): Promise<void> {
   })
 }
 
-async function follow(opts: LogsOpts): Promise<void> {
-  await runKernelCommand({
+type FollowDependencies = {
+  readonly run: typeof runKernelCommand
+  readonly pause: (milliseconds: number) => Promise<void>
+}
+
+/** Follow one admitted journal stream. Dependencies are explicit so routing is proven at the command boundary. */
+export async function followLogs(
+  opts: LogsOpts,
+  dependencies: FollowDependencies = {
+    run: runKernelCommand,
+    pause: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  },
+): Promise<void> {
+  validateLogsOpts(opts)
+  await dependencies.run({
     opts,
     label: 'Kernel journal',
     fn: async (context): Promise<never> => {
@@ -142,9 +166,9 @@ async function follow(opts: LogsOpts): Promise<void> {
       let cursor = resolved.cursor
       for (;;) {
         const page = await fetchPage(context, { ...resolved, cursor })
-        for (const record of page.records) printRecord(record)
+        for (const record of page.records) printRecord(record, opts)
         cursor = page.cursor ?? cursor
-        await new Promise((resolve) => setTimeout(resolve, FOLLOW_INTERVAL_MS))
+        await dependencies.pause(FOLLOW_INTERVAL_MS)
       }
     },
   })
@@ -169,12 +193,28 @@ function journalProjection(records: JournalRecord[]): ListProjection {
   }
 }
 
-function printRecord(record: JournalRecord): void {
+function printRecord(record: JournalRecord, opts: LogsOpts): void {
+  if (isMachine(opts) || opts.format === 'json') {
+    process.stdout.write(formatFollowRecord(record))
+    return
+  }
   process.stdout.write(
     `${chalk.dim(String(record.sequence).padStart(6))} ${chalk.dim(record.timestamp)} ${chalk.cyan(record.topic)} ${chalk.dim(record.principal ?? '')}\n`,
   )
 }
 
+/** Machine follow is an NDJSON stream: one complete admitted record per line. */
+export function formatFollowRecord(record: JournalRecord): string {
+  return `${JSON.stringify(record)}\n`
+}
+
+export function validateLogsOpts(opts: LogsOpts): void {
+  buildJournalInput(opts)
+  if (opts.follow && opts.format === 'yaml' && !opts.json && !opts.raw) {
+    throw new TypeError('--follow does not support YAML; use --json for an NDJSON stream')
+  }
+}
+
 function acceptRecord(input: unknown, index: number): JournalRecord {
   if (
     !isRecord(input) ||
@@ -188,10 +228,17 @@ function acceptRecord(input: unknown, index: number): JournalRecord {
   if (timestamp === undefined) {
     throw new TypeError(`Kernel journal record ${index} is missing occurredAt/timestamp`)
   }
-  const correlation = isRecord(input.correlation) ? input.correlation : undefined
-  const correlationId =
-    optionalText(input.correlationId, index, 'correlationId') ??
-    optionalText(correlation?.invocationId, index, 'correlation.invocationId')
+  const correlation = acceptCorrelation(input.correlation, index)
+  const legacyCorrelationId = optionalIdentifier(input.correlationId, index, 'correlationId')
+  const structuredCorrelationId = correlation?.invocationId
+  if (
+    legacyCorrelationId !== undefined &&
+    structuredCorrelationId !== undefined &&
+    legacyCorrelationId !== structuredCorrelationId
+  ) {
+    throw new TypeError(`Kernel journal record ${index} has conflicting correlation identifiers`)
+  }
+  const correlationId = structuredCorrelationId ?? legacyCorrelationId
   const principal = optionalText(input.principal, index, 'principal')
   return Object.freeze({
     sequence: input.sequence as number,
@@ -203,13 +250,56 @@ function acceptRecord(input: unknown, index: number): JournalRecord {
       ? {}
       : { committedAt: input.committedAt as string }),
     ...(principal === undefined ? {} : { principal }),
+    ...(correlation === undefined ? {} : { correlation }),
     ...(correlationId === undefined ? {} : { correlationId }),
-    ...(optionalText(input.causationId, index, 'causationId') === undefined
+    ...(optionalIdentifier(input.causationId, index, 'causationId') === undefined
       ? {}
       : { causationId: input.causationId as string }),
   })
 }
 
+const correlationFields = [
+  'operationId',
+  'parentOperationId',
+  'invocationId',
+  'rootInvocationId',
+  'parentInvocationId',
+  'traceId',
+  'spanId',
+] as const
+
+function acceptCorrelation(input: unknown, index: number): JournalCorrelation | undefined {
+  if (input === undefined) return undefined
+  if (!isRecord(input)) {
+    throw new TypeError(`Kernel journal record ${index}.correlation must be an object`)
+  }
+  const unknown = Object.keys(input).find(
+    (field) => !correlationFields.includes(field as (typeof correlationFields)[number]),
+  )
+  if (unknown !== undefined) {
+    throw new TypeError(`Kernel journal record ${index}.correlation.${unknown} is unsupported`)
+  }
+  return Object.freeze(
+    Object.fromEntries(
+      correlationFields.flatMap((field) => {
+        const value = optionalIdentifier(input[field], index, `correlation.${field}`)
+        return value === undefined ? [] : [[field, value]]
+      }),
+    ),
+  )
+}
+
+function optionalIdentifier(input: unknown, index: number, field: string): string | undefined {
+  const value = optionalText(input, index, field)
+  if (value === undefined) return undefined
+  if (value.trim() === '' || new TextEncoder().encode(value).byteLength > 256) {
+    throw new TypeError(
+      `Kernel journal record ${index}.${field} must be non-empty and at most 256 UTF-8 bytes`,
+    )
+  }
+  return value
+}
+
 function optionalText(input: unknown, index: number, field: string): string | undefined {
   if (input === undefined) return undefined
   if (typeof input !== 'string') {
@@ -251,7 +341,8 @@ Behavior:
   Calls the public Kernel journal syscall and emits its { records, cursor }
   page. Topic selection is exact or prefix-based; cursors and timestamps are
   opaque strings owned by the journal backend. --follow reuses one Client Session
-  and advances only with the returned cursor.
+  and advances only with the returned cursor. Machine follow output is NDJSON:
+  one complete admitted record per line; YAML follow is unsupported.
 
   Historical event-glob lowering and the application-specific services-domain
   log buffer are not part of the Kernel V2 journal contract.
@@ -273,11 +364,11 @@ Examples:
   ],
   action: async (opts: LogsOpts) => {
     try {
-      buildJournalInput(opts)
+      validateLogsOpts(opts)
     } catch (error) {
       failInput(error, opts)
     }
-    if (opts.follow) await follow(opts)
+    if (opts.follow) await followLogs(opts)
     else await runOnce(opts)
   },
 } satisfies CommandDefinition

package/src/lib/output.ts

@@ -17,7 +17,7 @@ export type RawOutputOpts = Pick<OutputOpts, 'raw' | 'json'>
 export type MachineOpts = RawOutputOpts & { readonly ci?: boolean }
 
 export const RAW_OUTPUT_OPTIONS = [
-  { flags: '--json', description: 'Always-valid JSON (for jq)' },
+  { flags: '--json', description: 'JSON; streaming commands emit one JSON value per line' },
   { flags: '--raw', description: 'Unwrapped: bare scalar / raw bytes / JSON for objects' },
 ] as const
 

package/src/program/__tests__/program.test.ts

@@ -195,7 +195,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      'd37c3d80b3067b3553b8527b10bf1c5632922d624b3d6072c3b03e7a507efc4f',
+      '958b54c4eeee1bab77efeac734bd11fe5a0b103aae69788de7db5418e5652f64',
     )
   })