@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

package/src/commands/logs.ts

@@ -1,21 +1,16 @@
 import { Path } from '@astrale-os/sdk/graph/path'
-import { syscalls } from '@astrale-os/sdk/schema/kernel'
+import { K } from '@astrale-os/sdk/schema'
 import chalk from 'chalk'
 
 import type { ConnectionContext, KernelCommandOpts } from '../connection'
 import type { Column, ListProjection } from '../lib/output'
 import type { CommandDefinition } from '../program/index'
 
-import {
-  createPathCall,
-  expandSelfInPath,
-  runKernelCommand,
-  withClientSession,
-} from '../connection'
-import { failClosed } from '../lib/log'
+import { createPathCall, expandSelfInPath, runKernelCommand } from '../connection'
+import { failInput } from '../lib/log'
 import { isMachine, output, presentList } from '../lib/output'
 
-const JOURNAL_PATH = Path.project(syscalls.journal.ref).raw
+const JOURNAL_PATH = Path.project(K.functions.journal.ref).raw
 const DEFAULT_LIMIT = 200
 const FOLLOW_INTERVAL_MS = 2_000
 
@@ -38,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
@@ -127,7 +133,7 @@ async function runOnce(opts: LogsOpts): Promise<void> {
   await runKernelCommand({
     opts,
     label: 'Kernel journal',
-    fn: (context) => fetchPage(context, opts),
+    fn: async (context) => fetchPage(context, await resolveLogsOpts(opts, context)),
     format: (page, format) => {
       if (isMachine(format) || format.format !== undefined) output(page, format)
       else {
@@ -138,15 +144,33 @@ async function runOnce(opts: LogsOpts): Promise<void> {
   })
 }
 
-async function follow(opts: LogsOpts): Promise<void> {
-  await withClientSession(opts, async (context) => {
-    let cursor = opts.cursor
-    for (;;) {
-      const page = await fetchPage(context, { ...opts, cursor })
-      for (const record of page.records) printRecord(record)
-      cursor = page.cursor ?? cursor
-      await new Promise((resolve) => setTimeout(resolve, FOLLOW_INTERVAL_MS))
-    }
+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> => {
+      const resolved = await resolveLogsOpts(opts, context)
+      let cursor = resolved.cursor
+      for (;;) {
+        const page = await fetchPage(context, { ...resolved, cursor })
+        for (const record of page.records) printRecord(record, opts)
+        cursor = page.cursor ?? cursor
+        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') {
@@ -227,11 +317,10 @@ function positiveInteger(flag: string, raw: string): number {
   return value
 }
 
-async function prepareLogsOpts(opts: LogsOpts): Promise<LogsOpts> {
-  buildJournalInput(opts)
+async function resolveLogsOpts(opts: LogsOpts, context: ConnectionContext): Promise<LogsOpts> {
   const principal = nonEmpty(opts.principal)
   if (principal !== '@self') return opts
-  const { path } = await expandSelfInPath('@self', opts)
+  const { path } = await expandSelfInPath('@self', context)
   return { ...opts, principal: path.startsWith('@') ? path.slice(1) : path }
 }
 
@@ -252,10 +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.
-
-  Historical event-glob lowering and the application-specific services-domain
-  log buffer are not part of the Kernel V2 journal contract.
+  and advances only with the returned cursor. With --json, follow output is
+  NDJSON with one complete admitted record per line; YAML follow is unsupported.
 
 Examples:
   $ astrale logs -i staging --limit 50
@@ -274,11 +361,11 @@ Examples:
   ],
   action: async (opts: LogsOpts) => {
     try {
-      const prepared = await prepareLogsOpts(opts)
-      if (prepared.follow) await follow(prepared)
-      else await runOnce(prepared)
+      validateLogsOpts(opts)
     } catch (error) {
-      failClosed(error, opts)
+      failInput(error, opts)
     }
+    if (opts.follow) await followLogs(opts)
+    else await runOnce(opts)
   },
 } satisfies CommandDefinition

package/src/commands/mutate.ts

@@ -7,8 +7,9 @@ import type { KernelCommandOpts } from '../connection'
 import type { CommandDefinition } from '../program/index'
 
 import { runKernelCommand } from '../connection'
+import { AstraleError } from '../errors'
 import { prepareMutation } from '../graph/index'
-import { failClosed } from '../lib/log'
+import { failInput } from '../lib/log'
 import { output } from '../lib/output'
 import { renderTable } from '../lib/table'
 
@@ -23,7 +24,7 @@ export async function mutateCommand(opts: MutateOpts): Promise<void> {
   try {
     mutation = prepareMutation(await readDocument(opts))
   } catch (error) {
-    failClosed(error, opts)
+    failInput(error, opts)
   }
 
   if (opts.dry) {
@@ -51,9 +52,9 @@ async function readDocument(opts: MutateOpts): Promise<unknown> {
     try {
       raw = await readFile(opts.file, 'utf8')
     } catch (error) {
-      throw new Error(
-        `Cannot read --file ${opts.file}: ${error instanceof Error ? error.message : error}`,
-      )
+      throw new AstraleError('FILE_READ_FAILED', `Cannot read --file ${opts.file}.`, undefined, {
+        cause: error,
+      })
     }
     return parseJson(raw, opts.file)
   }

package/src/commands/query.ts

@@ -6,14 +6,15 @@ import type { KernelCommandOpts, SelfExpansionMeta } from '../connection'
 import type { CommandDefinition } from '../program/index'
 
 import { expandSelfInPath, runKernelCommand, withSelfHint } from '../connection'
+import { AstraleError } from '../errors'
 import { prepareQuery, type QueryCommandInput } from '../graph/index'
-import { failClosed } from '../lib/log'
+import { failInput } from '../lib/log'
 import { isMachine, output } from '../lib/output'
 
 type QueryOpts = KernelCommandOpts & {
   ast?: string
   file?: string
-  definition?: string
+  class?: string
   edge?: string
   direction?: QueryDirection
   limit?: string
@@ -22,48 +23,49 @@ type QueryOpts = KernelCommandOpts & {
 
 export async function queryCommand(sources: string[], opts: QueryOpts): Promise<void> {
   let input: QueryCommandInput
-  let meta: SelfExpansionMeta | undefined
   try {
     const ast = await readAst(opts)
-    if (ast === undefined) {
-      const expanded = await Promise.all(sources.map((source) => expandSelfInPath(source, opts)))
-      input = {
-        sources: expanded.map(({ path }) => path),
-        definition: opts.definition,
-        edge: opts.edge,
-        direction: opts.direction,
-        limit: opts.limit,
-        cursor: opts.cursor,
-      }
-      meta = expanded.find((entry) => entry.meta !== undefined)?.meta
-    } else {
-      input = {
-        sources,
-        ast,
-        definition: opts.definition,
-        edge: opts.edge,
-        direction: opts.direction,
-        limit: opts.limit,
-        cursor: opts.cursor,
-      }
+    input = {
+      sources,
+      ...(ast === undefined ? {} : { ast }),
+      class: opts.class,
+      edge: opts.edge,
+      direction: opts.direction,
+      limit: opts.limit,
+      cursor: opts.cursor,
     }
   } catch (error) {
-    failClosed(error, opts)
+    failInput(error, opts)
   }
 
   let prepared
   try {
     prepared = prepareQuery(input)
   } catch (error) {
-    failClosed(error, opts)
+    failInput(error, opts)
   }
 
   await runKernelCommand({
     opts,
     label: 'Query',
-    fn: ({ graph }) => withSelfHint(() => graph.query(prepared.ast, { page: prepared.page }), meta),
+    fn: async (context) => {
+      const expanded = await Promise.all(sources.map((source) => expandSelfInPath(source, context)))
+      const meta: SelfExpansionMeta | undefined = expanded.find(
+        (entry) => entry.meta !== undefined,
+      )?.meta
+      const resolved =
+        meta === undefined
+          ? prepared
+          : prepareQuery({ ...input, sources: expanded.map(({ path }) => path) })
+      return withSelfHint(() => context.graph.query(resolved.ast, { page: resolved.page }), meta)
+    },
     format: (response, format) => {
-      output(response.result, format)
+      output(
+        response.page.next === undefined
+          ? response.result
+          : { ...response.result, page: { next: response.page.next } },
+        format,
+      )
       if (response.page.next && !isMachine(format)) {
         process.stderr.write(`  cursor: ${response.page.next}\n`)
       }
@@ -81,9 +83,9 @@ async function readAst(opts: QueryOpts): Promise<unknown | undefined> {
   try {
     raw = await readFile(opts.file, 'utf8')
   } catch (error) {
-    throw new Error(
-      `Cannot read --file ${opts.file}: ${error instanceof Error ? error.message : error}`,
-    )
+    throw new AstraleError('FILE_READ_FAILED', `Cannot read --file ${opts.file}.`, undefined, {
+      cause: error,
+    })
   }
   return parseJson(raw, opts.file)
 }
@@ -101,18 +103,19 @@ export default {
   description: 'Run one canonical Query V6 graph read',
   afterHelpText: `
 Behavior:
-  Positional Paths and --definition author a finite Query V6 read. --edge adds
+  Positional Paths and --class author a finite Query V6 read. --edge adds
   one exact Edge-Class expansion; --direction defaults to outgoing. --ast and
   --file accept a complete canonical astrale.graph.query/v6 document, including
   Property ordering and Node or Edge reference/value projections. --cursor resumes
-  one caller-bound query scope.
+  one caller-bound query scope. Machine output adds page.next only when another
+  page exists; pass that opaque value back through --cursor.
 
   Legacy depth/children selector JSON and raw Cypher are not portable Kernel
   V2 query contracts and are not accepted.
 
 Examples:
   $ astrale query /:notes.example.dev:class.Note --limit 50
-  $ astrale query --definition /:notes.example.dev:class.Note --limit 50
+  $ astrale query --class /:notes.example.dev:class.Note --limit 50
   $ astrale query @note --edge /:notes.example.dev:class.references --direction outgoing --limit 25
   $ astrale query --file query.v6.json --cursor "$CURSOR"
 `,
@@ -121,8 +124,8 @@ Examples:
     { flags: '--ast <json>', description: 'Canonical Query V6 JSON document' },
     { flags: '-f, --file <path>', description: 'Read a canonical Query V6 document from a file' },
     {
-      flags: '--definition <path>',
-      description: 'Select Nodes implementing one exact Class or Interface',
+      flags: '--class <path>',
+      description: 'Select Nodes satisfying one exact Class',
     },
     { flags: '--edge <class>', description: 'Expand one exact Edge Class' },
     {

package/src/commands/session/analyze.ts

@@ -4,13 +4,23 @@ import type { CommandDefinition } from '../../program/index'
 
 import { log } from '../../lib/log'
 import { analyzeSession } from '../../telemetry/analyze'
-import { listSessions } from '../../telemetry/store'
+import { sweepStore } from '../../telemetry/retention'
+import { scanSessions } from '../../telemetry/store'
 import { restampLock, releaseLock } from '../../telemetry/trigger'
 
 export default {
   name: 'analyze',
   description: 'Analyze a recorded session for DX frictions (dry-run: writes report.md)',
-  arguments: [{ name: 'id', description: 'Session id (default: most recent closed, unanalyzed)' }],
+  arguments: [
+    // Optional: the action resolves the most recent closed, unanalyzed session
+    // when no id is given, which is how a human is meant to invoke this. The
+    // opportunistic trigger always passes an explicit id.
+    {
+      name: 'id',
+      description: 'Session id (default: most recent closed, unanalyzed)',
+      required: false,
+    },
+  ],
   options: [
     { flags: '--file', description: 'File cleared findings as issues on the admin tracker' },
     { flags: '--model <model>', description: 'Model for the analyzer pass' },
@@ -22,10 +32,10 @@ export default {
     opts: { file?: boolean; model?: string; force?: boolean; auto?: boolean },
   ) => {
     if (opts.auto) restampLock()
+    let target = id
     try {
-      let target = id
       if (!target) {
-        const candidate = listSessions().find((s) => s.closed && (opts.force || !s.analyzed))
+        const candidate = scanSessions().find((s) => s.closed && (opts.force || !s.analyzed))
         if (!candidate) {
           if (!opts.auto) log.dim('Nothing to analyze — no closed, unanalyzed session.')
           return
@@ -45,6 +55,18 @@ export default {
       }
     } finally {
       if (opts.auto) releaseLock()
+      // The size bound is enforced here, not on the CLI's critical path:
+      // measuring every file of every session is only affordable in this
+      // process, and this is precisely where the store just grew. The session
+      // just analyzed is protected — it is the freshest evidence on disk.
+      try {
+        const swept = sweepStore({ protect: new Set(target === undefined ? [] : [target]) })
+        if (!opts.auto && swept.removed.length > 0) {
+          log.dim(`retention: removed ${swept.removed.length} session(s)`)
+        }
+      } catch {
+        /* retention must never fail the command that triggered it */
+      }
     }
   },
 } satisfies CommandDefinition

package/src/commands/token.ts

@@ -1,4 +1,4 @@
-import { issuer } from '@astrale-os/sdk/auth'
+import { issuer, type AuthApi, type IssuerId, type MintedCredential } from '@astrale-os/sdk/auth'
 
 import type { KernelCommandOpts } from '../connection'
 import type { CommandDefinition } from '../program/index'
@@ -6,12 +6,12 @@ import type { CommandDefinition } from '../program/index'
 import { runKernelCommand } from '../connection'
 import { AstraleError } from '../errors'
 import { decodeJwtExpiration } from '../lib/local-status'
-import { failClosed, log } from '../lib/log'
+import { failInput, log } from '../lib/log'
 import { output } from '../lib/output'
 
 /**
- * `astrale token` — mint a fresh delegation token for the active instance
- * + active identity through the bound AuthApi.
+ * `astrale token` — mint a fresh audience-bound token for the active instance
+ * and selected identity through the bound AuthApi.
  */
 export type TokenOpts = KernelCommandOpts & {
   audience?: string
@@ -21,23 +21,25 @@ export type TokenOpts = KernelCommandOpts & {
   for?: string
 }
 
+const DEFAULT_TOKEN_TTL_SECONDS = 4 * 60
+
 export async function tokenCommand(opts: TokenOpts): Promise<void> {
   const commandOpts: TokenOpts = opts.for && !opts.as ? { ...opts, as: opts.for } : opts
-  const ttl = parseTtl(commandOpts.ttl)
+  let ttl: number
+  try {
+    ttl = parseTtl(commandOpts.ttl)
+  } catch (error) {
+    failInput(error, opts)
+  }
   await runKernelCommand<string>({
     opts: commandOpts,
-    label: 'Minting delegation token',
+    label: 'Minting token',
     fn: async (ctx) => {
       const audience =
         commandOpts.audience === undefined
           ? ctx.target.kernelIssuer
           : issuer.accept(commandOpts.audience)
-      const self = await ctx.auth.whoami()
-      return ctx.auth.delegate(self.id, {
-        audience,
-        ttlSeconds: ttl,
-        attenuation: { kind: 'identity', self: true },
-      })
+      return issueToken(ctx.auth, ctx.target.kernelIssuer, audience, ttl)
     },
     format: (token, fmtOpts) => {
       if (fmtOpts.json || fmtOpts.format !== undefined) {
@@ -45,15 +47,31 @@ export async function tokenCommand(opts: TokenOpts): Promise<void> {
         return
       }
       if (!fmtOpts.raw && (process.stdout.isTTY ?? false)) {
-        log.dim('  (delegation token — ES256, self-identity)')
+        log.dim('  (audience-bound token — ES256, self-identity)')
       }
       process.stdout.write(`${token}\n`)
     },
   })
 }
 
+/** Issue either a top-level Kernel credential or an external-audience delegation. */
+export async function issueToken(
+  auth: Pick<AuthApi, 'delegate' | 'mint' | 'whoami'>,
+  kernel: IssuerId,
+  audience: IssuerId,
+  ttlSeconds: number,
+): Promise<MintedCredential> {
+  if (audience === kernel) return auth.mint({ ttlSeconds })
+  const self = await auth.whoami()
+  return auth.delegate(self.id, {
+    audience,
+    ttlSeconds,
+    attenuation: { kind: 'identity', self: true },
+  })
+}
+
 export function parseTtl(raw: string | undefined): number {
-  if (raw === undefined) return 3600
+  if (raw === undefined) return DEFAULT_TOKEN_TTL_SECONDS
   if (!/^\d+$/.test(raw)) {
     throw new AstraleError(
       'INVALID_FLAG',
@@ -72,16 +90,17 @@ export function parseTtl(raw: string | undefined): number {
 
 export default {
   name: 'token',
-  description: 'Mint a fresh delegation token for the active instance + identity',
+  description: 'Mint a fresh audience-bound credential for the active instance + identity',
   afterHelpText: `
 Behavior:
-  Delegates the selected authenticated identity for 3600 seconds by default.
-  The default audience is the target Kernel issuer; choose --audience when the
-  credential is intended for another service. --for is an alias of --as.
+  Mints a token for the selected authenticated identity for 240 seconds by default.
+  The default Kernel audience produces a top-level Grant credential reusable with
+  --creds. A different --audience produces a delegated service envelope. --for is
+  an alias of --as.
 
-  The receiver must admit the exact token audience. A Kernel-audience token can
-  be reused with --creds; a service-audience token can be sent as a Bearer token
-  to that service's authenticated endpoint.
+  Every receiver must admit the exact token audience. A service-audience token can
+  be sent as a Bearer token only to that service's authenticated endpoint. The
+  requested lifetime cannot exceed the selected source credential's remaining life.
 
 Examples:
   $ export TOKEN=$(astrale token --audience shell.astrale.ai --raw)
@@ -93,14 +112,10 @@ Examples:
       flags: '--audience <aud>',
       description: 'Token audience (default: target Kernel issuer)',
     },
-    { flags: '--ttl <sec>', description: 'TTL in seconds (default: 3600)' },
+    { flags: '--ttl <sec>', description: 'TTL in seconds (default: 240)' },
     { flags: '--for <identity>', description: 'Mint the token for this identity (alias of --as)' },
   ],
   action: async (opts) => {
-    try {
-      await tokenCommand(opts as Parameters<typeof tokenCommand>[0])
-    } catch (error) {
-      failClosed(error, opts as TokenOpts)
-    }
+    await tokenCommand(opts as Parameters<typeof tokenCommand>[0])
   },
 } satisfies CommandDefinition