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

package/src/state/exchange-credentials.ts

@@ -5,24 +5,28 @@ import { dirname } from 'node:path'
 import { atomicWrite, withFileLock } from './files'
 import { EXCHANGE_CREDENTIALS_PATH } from './paths'
 
-const VERSION = 1
+const VERSION = 2
 const MINIMUM_REMAINING_SECONDS = 30
 
 export namespace exchange {
   export interface Artifact {
-    readonly version: 1
+    readonly version: 2
     readonly entries: Record<string, Entry>
   }
 
   export interface Key {
     readonly kernelIssuer: string
     readonly domainIssuer: string
-    readonly user: string
+    readonly sourceIssuer: string
+    readonly sourceSubject: string
   }
 
   export interface Entry {
     readonly credential: string
     readonly expiresAt: number
+    readonly user: string
+    readonly sourceIssuer: string
+    readonly sourceSubject: string
   }
 }
 
@@ -140,11 +144,15 @@ function validEntry(
   if (
     entry === null ||
     typeof entry !== 'object' ||
-    Reflect.ownKeys(entry).length !== 2 ||
+    Reflect.ownKeys(entry).length !== 5 ||
     typeof entry.credential !== 'string' ||
     entry.credential.length === 0 ||
     !Number.isSafeInteger(entry.expiresAt) ||
-    entry.expiresAt - now < minimumRemaining
+    entry.expiresAt - now < minimumRemaining ||
+    typeof entry.user !== 'string' ||
+    entry.user.length === 0 ||
+    entry.sourceIssuer !== key.sourceIssuer ||
+    entry.sourceSubject !== key.sourceSubject
   ) {
     return false
   }
@@ -178,7 +186,7 @@ function validEntry(
       inspected.claims.exp === entry.expiresAt &&
       !Object.hasOwn(inspected.claims, 'delegation') &&
       proof.iss === key.kernelIssuer &&
-      proof.sub === key.user &&
+      proof.sub === entry.user &&
       proof.aud === key.kernelIssuer
     )
   } catch {
@@ -187,7 +195,7 @@ function validEntry(
 }
 
 function encodeKey(key: exchange.Key): string {
-  return JSON.stringify([key.kernelIssuer, key.domainIssuer, key.user])
+  return JSON.stringify([key.kernelIssuer, key.domainIssuer, key.sourceIssuer, key.sourceSubject])
 }
 
 function decodeKey(input: string): exchange.Key | undefined {
@@ -195,12 +203,17 @@ function decodeKey(input: string): exchange.Key | undefined {
     const value = JSON.parse(input) as unknown
     if (
       !Array.isArray(value) ||
-      value.length !== 3 ||
+      value.length !== 4 ||
       value.some((part) => typeof part !== 'string' || part.length === 0)
     ) {
       return undefined
     }
-    return { kernelIssuer: value[0]!, domainIssuer: value[1]!, user: value[2]! }
+    return {
+      kernelIssuer: value[0]!,
+      domainIssuer: value[1]!,
+      sourceIssuer: value[2]!,
+      sourceSubject: value[3]!,
+    }
   } catch {
     return undefined
   }

package/src/state/files.ts

@@ -1,4 +1,13 @@
 import { randomUUID } from 'node:crypto'
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
 import { mkdir, open, readFile, rename, stat, unlink } from 'node:fs/promises'
 import { dirname } from 'node:path'
 
@@ -30,6 +39,38 @@ export async function atomicWrite(path: string, data: string): Promise<void> {
   }
 }
 
+/** Atomically publish one complete private state file for synchronous consumer capabilities. */
+export function atomicWriteSync(path: string, data: string): void {
+  const directory = dirname(path)
+  const temporary = `${path}.${randomUUID()}.tmp`
+  mkdirSync(directory, { recursive: true })
+
+  let descriptor: number | undefined
+  try {
+    descriptor = openSync(temporary, 'wx', 0o600)
+    writeFileSync(descriptor, data)
+    fsyncSync(descriptor)
+    closeSync(descriptor)
+    descriptor = undefined
+    renameSync(temporary, path)
+
+    const directoryDescriptor = openSync(directory, 'r')
+    try {
+      fsyncSync(directoryDescriptor)
+    } finally {
+      closeSync(directoryDescriptor)
+    }
+  } catch (error) {
+    if (descriptor !== undefined) closeSync(descriptor)
+    try {
+      unlinkSync(temporary)
+    } catch {
+      // The temporary file was either never created or was already renamed.
+    }
+    throw error
+  }
+}
+
 export interface FileLockOptions {
   readonly pollIntervalMs?: number
   readonly staleAfterMs?: number

package/src/state/index.ts

@@ -1,4 +1,4 @@
-export { atomicWrite, withFileLock } from './files'
+export { atomicWrite, atomicWriteSync, withFileLock } from './files'
 export type { FileLockOptions } from './files'
 export { ExchangeCredentialCache } from './exchange-credentials'
 export type { exchange } from './exchange-credentials'
@@ -23,7 +23,9 @@ export {
   INSTALL_PATH,
   INSTANCES_PATH,
   KEYS_DIR,
+  SESSION_ROUTES_PATH,
   createPaths,
   paths,
 } from './paths'
 export type { PathEnvironment, Paths } from './paths'
+export { FileSessionRouteStore, SESSION_ROUTE_STORE } from './session-routes'

package/src/state/paths.ts

@@ -18,6 +18,7 @@ export interface Paths {
   readonly idps: string
   readonly idpSessionsDir: string
   readonly exchangeCredentials: string
+  readonly sessionRoutes: string
   idpDir(name: string): string
   idpSession(identityName: string): string
 }
@@ -43,6 +44,7 @@ export function createPaths(home?: string, environment?: PathEnvironment): Paths
     idps: join(idpsDir, 'index.json'),
     idpSessionsDir,
     exchangeCredentials: join(base, 'exchange', 'credentials.json'),
+    sessionRoutes: join(base, 'session', 'routes.json'),
     idpDir: (name: string) => join(idpsDir, name),
     idpSession: (identityName: string) => join(idpSessionsDir, `${identityName}.json`),
   })
@@ -59,3 +61,4 @@ export const INSTANCES_PATH = paths.instances
 export const IDPS_PATH = paths.idps
 export const IDP_SESSIONS_DIR = paths.idpSessionsDir
 export const EXCHANGE_CREDENTIALS_PATH = paths.exchangeCredentials
+export const SESSION_ROUTES_PATH = paths.sessionRoutes

package/src/state/session-routes.ts

@@ -0,0 +1,34 @@
+import type { SessionRouteArtifact, SessionRouteStore } from '@astrale-os/sdk/client/session'
+
+import { chmodSync, mkdirSync, readFileSync, unlinkSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import { atomicWriteSync } from './files'
+import { SESSION_ROUTES_PATH } from './paths'
+
+/** CLI filesystem representation for Kernel Client's admitted confidential route artifact. */
+export class FileSessionRouteStore implements SessionRouteStore {
+  constructor(private readonly path = SESSION_ROUTES_PATH) {}
+
+  read(): unknown {
+    return JSON.parse(readFileSync(this.path, 'utf8')) as unknown
+  }
+
+  write(artifact: SessionRouteArtifact): void {
+    const directory = dirname(this.path)
+    mkdirSync(directory, { recursive: true, mode: 0o700 })
+    chmodSync(directory, 0o700)
+    atomicWriteSync(this.path, `${JSON.stringify(artifact)}\n`)
+    chmodSync(this.path, 0o600)
+  }
+
+  clear(): void {
+    try {
+      unlinkSync(this.path)
+    } catch (error) {
+      if ((error as { readonly code?: unknown }).code !== 'ENOENT') throw error
+    }
+  }
+}
+
+export const SESSION_ROUTE_STORE = Object.freeze(new FileSessionRouteStore())

package/src/telemetry/__tests__/analyze-log.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test'
+
+import { clampLog } from '../analyze'
+
+describe('clampLog', () => {
+  test('short output is written through untouched', () => {
+    const json = '{"is_error":false,"num_turns":3}'
+    expect(clampLog(json)).toBe(json)
+  })
+
+  test('output at exactly the limit is not clamped', () => {
+    const text = 'x'.repeat(1000)
+    expect(clampLog(text, 1000)).toBe(text)
+  })
+
+  test('oversized output keeps its head and its tail', () => {
+    // The JSON envelope opens at the top; a stack or error message closes at
+    // the bottom. Both must survive; the middle is what nobody reads.
+    const text = `HEAD${'x'.repeat(50_000)}TAIL`
+    const clamped = clampLog(text, 1000)
+    expect(clamped.startsWith('HEAD')).toBe(true)
+    expect(clamped.endsWith('TAIL')).toBe(true)
+    expect(clamped).toContain('bytes elided')
+  })
+
+  test('the result stays within a small constant of the limit', () => {
+    const clamped = clampLog('y'.repeat(10_000_000), 4096)
+    // head + tail + the elision marker, never the input.
+    expect(clamped.length).toBeLessThan(4096 + 128)
+  })
+
+  test('the elision count reports what was actually dropped', () => {
+    const clamped = clampLog('z'.repeat(10_000), 1000)
+    const elided = Number(/… (\d+) bytes elided …/u.exec(clamped)?.[1])
+    const kept = clamped.length - `\n… ${elided} bytes elided …\n`.length
+    expect(elided + kept).toBe(10_000)
+  })
+})

package/src/telemetry/__tests__/recorder.test.ts

@@ -91,6 +91,7 @@ describe('beginInvocation', () => {
   test('writes nothing for help/version-only invocations', () => {
     beginInvocation(['node', 'astrale', '--help'])(0)
     beginInvocation(['node', 'astrale', '--version'])(0)
+    beginInvocation(['node', 'astrale', '--cli-version'])(0)
     beginInvocation(['node', 'astrale'])(0)
     expect(listSessions()).toHaveLength(0)
   })

package/src/telemetry/__tests__/retention.test.ts

@@ -0,0 +1,267 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { SweepOptions, SweepResult } from '../retention'
+import type { RetentionBudget } from '../settings'
+import type { SessionScan } from '../store'
+
+// Set the home before the paths singleton is captured (dynamic imports below).
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-retention-'))
+
+let sweepByAge: (sessions: readonly SessionScan[], options?: SweepOptions) => SweepResult
+let sweepToBudget: (sessions: readonly SessionScan[], options?: SweepOptions) => SweepResult
+let sweepStore: (options?: SweepOptions) => SweepResult
+let tidySession: (id: string, options?: { keepPrompt?: boolean }) => string[]
+let scanSessions: () => SessionScan[]
+let sessionDir: (id: string) => string
+let sessionBytes: (id: string) => number
+let sessionsRoot: () => string
+
+const DAY = 24 * 60 * 60 * 1000
+const BUDGET: RetentionBudget = { maxAgeMs: 30 * DAY, maxBytes: 10_000 }
+
+beforeAll(async () => {
+  ;({ sweepByAge, sweepToBudget, sweepStore, tidySession } = await import('../retention'))
+  ;({ scanSessions, sessionDir, sessionBytes, sessionsRoot } = await import('../store'))
+})
+
+beforeEach(() => {
+  // Destructive cleanup must be provably confined to this file's mkdtemp home.
+  if (!sessionsRoot().startsWith(tmpdir())) throw new Error('refusing to clean a non-tmp home')
+  rmSync(sessionsRoot(), { recursive: true, force: true })
+  delete process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS
+  delete process.env.ASTRALE_TELEMETRY_MAX_BYTES
+})
+
+afterEach(() => {
+  rmSync(sessionsRoot(), { recursive: true, force: true })
+})
+
+type Seed = { ageMs?: number; analyzed?: boolean; bytes?: number; events?: boolean }
+
+function seed(id: string, { ageMs = 0, analyzed = false, bytes = 0, events = true }: Seed): void {
+  const dir = sessionDir(id)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'meta.json'), JSON.stringify({ id, root: '/w', explicit: false }))
+  if (bytes > 0) writeFileSync(join(dir, 'report.md'), 'x'.repeat(bytes))
+  if (analyzed) {
+    writeFileSync(
+      join(dir, '.analyzed'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'reported' }),
+    )
+  }
+  if (!events) return
+  writeFileSync(join(dir, 'events.jsonl'), '{}\n')
+  const when = new Date(Date.now() - ageMs)
+  utimesSync(join(dir, 'events.jsonl'), when, when)
+}
+
+const alive = (id: string): boolean => existsSync(sessionDir(id))
+
+describe('sweepByAge', () => {
+  test('drops sessions past the age bound whether or not they were analyzed', () => {
+    seed('old-analyzed', { ageMs: 40 * DAY, analyzed: true })
+    seed('old-unanalyzed', { ageMs: 40 * DAY })
+    seed('recent-analyzed', { ageMs: 2 * DAY, analyzed: true })
+    seed('recent-unanalyzed', { ageMs: 2 * DAY })
+
+    const { removed } = sweepByAge(scanSessions(), { budget: BUDGET })
+
+    expect(removed.sort()).toEqual(['old-analyzed', 'old-unanalyzed'])
+    expect(alive('recent-analyzed')).toBe(true)
+    expect(alive('recent-unanalyzed')).toBe(true)
+  })
+
+  test('never touches a session with no events — that is the invocation running now', () => {
+    seed('no-events-yet', { events: false })
+    expect(sweepByAge(scanSessions(), { budget: BUDGET }).removed).toEqual([])
+    expect(alive('no-events-yet')).toBe(true)
+  })
+
+  test('honours the removal cap so a backlog drains over several runs', () => {
+    for (let i = 0; i < 5; i++) seed(`stale-${i}`, { ageMs: 40 * DAY, analyzed: true })
+    expect(sweepByAge(scanSessions(), { budget: BUDGET, limit: 2 }).removed).toHaveLength(2)
+    expect(scanSessions()).toHaveLength(3)
+  })
+
+  test('respects the configured age bound', () => {
+    seed('week-old', { ageMs: 8 * DAY, analyzed: true })
+    const strict: RetentionBudget = { ...BUDGET, maxAgeMs: 7 * DAY }
+    expect(sweepByAge(scanSessions(), { budget: strict }).removed).toEqual(['week-old'])
+  })
+
+  test('protected ids survive the age bound', () => {
+    seed('old-but-mine', { ageMs: 40 * DAY, analyzed: true })
+    const options = { budget: BUDGET, protect: new Set(['old-but-mine']) }
+    expect(sweepByAge(scanSessions(), options).removed).toEqual([])
+    expect(alive('old-but-mine')).toBe(true)
+  })
+})
+
+describe('sweepToBudget', () => {
+  test('does nothing while the store fits', () => {
+    seed('small', { ageMs: DAY, analyzed: true, bytes: 100 })
+    expect(sweepToBudget(scanSessions(), { budget: BUDGET }).removed).toEqual([])
+    expect(alive('small')).toBe(true)
+  })
+
+  test('evicts oldest-first until the store is back under budget', () => {
+    seed('oldest', { ageMs: 5 * DAY, analyzed: true, bytes: 4_000 })
+    seed('middle', { ageMs: 3 * DAY, analyzed: true, bytes: 4_000 })
+    seed('newest', { ageMs: DAY, analyzed: true, bytes: 4_000 })
+
+    // 3 × ~4 KB against a 5 KB bound: two must go, and the newest must stay.
+    const { removed } = sweepToBudget(scanSessions(), { budget: { ...BUDGET, maxBytes: 5_000 } })
+
+    expect(removed).toEqual(['oldest', 'middle'])
+    expect(alive('newest')).toBe(true)
+  })
+
+  test('evicts analyzed sessions before unanalyzed ones of any age', () => {
+    seed('unanalyzed-oldest', { ageMs: 9 * DAY, bytes: 6_000 })
+    seed('analyzed-newest', { ageMs: DAY, analyzed: true, bytes: 6_000 })
+
+    expect(sweepToBudget(scanSessions(), { budget: BUDGET }).removed).toEqual(['analyzed-newest'])
+    expect(alive('unanalyzed-oldest')).toBe(true)
+  })
+
+  test('falls through to unanalyzed sessions when analyzed ones are not enough', () => {
+    seed('unanalyzed-old', { ageMs: 9 * DAY, bytes: 6_000 })
+    seed('analyzed-old', { ageMs: 8 * DAY, analyzed: true, bytes: 6_000 })
+    seed('unanalyzed-new', { ageMs: DAY, bytes: 6_000 })
+
+    const { removed } = sweepToBudget(scanSessions(), { budget: BUDGET })
+
+    expect(removed).toEqual(['analyzed-old', 'unanalyzed-old'])
+    expect(alive('unanalyzed-new')).toBe(true)
+  })
+
+  test('never evicts an open session, even when that leaves the store over budget', () => {
+    // No age offset → inside IDLE_WINDOW_MS → open.
+    seed('open-and-huge', { analyzed: true, bytes: 20_000 })
+    expect(sweepToBudget(scanSessions(), { budget: BUDGET }).removed).toEqual([])
+    expect(alive('open-and-huge')).toBe(true)
+  })
+
+  test('never evicts a protected session', () => {
+    seed('just-analyzed', { ageMs: DAY, analyzed: true, bytes: 20_000 })
+    const options = { budget: BUDGET, protect: new Set(['just-analyzed']) }
+    expect(sweepToBudget(scanSessions(), options).removed).toEqual([])
+  })
+
+  test('counts nested analyzer output — a session is bounded by all it holds', () => {
+    seed('nested', { ageMs: DAY, analyzed: true, bytes: 100 })
+    mkdirSync(join(sessionDir('nested'), 'scratch'), { recursive: true })
+    writeFileSync(join(sessionDir('nested'), 'scratch', 'dump.txt'), 'x'.repeat(5_000))
+
+    expect(sessionBytes('nested')).toBeGreaterThan(5_000)
+  })
+})
+
+describe('sweepStore', () => {
+  test('applies age first, then trims what survives to the size bound', () => {
+    seed('expired', { ageMs: 40 * DAY, analyzed: true, bytes: 6_000 })
+    seed('fresh-big', { ageMs: 2 * DAY, analyzed: true, bytes: 6_000 })
+    seed('fresh-small', { ageMs: DAY, analyzed: true, bytes: 100 })
+
+    // Age alone frees 6 KB, leaving ~6.1 KB — already under the 10 KB bound,
+    // so the size pass must find nothing left to do.
+    expect(sweepStore({ budget: BUDGET }).removed).toEqual(['expired'])
+    expect(alive('fresh-big')).toBe(true)
+    expect(alive('fresh-small')).toBe(true)
+  })
+
+  test('reads its budget from the environment when none is passed', () => {
+    process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS = '1'
+    seed('two-days-old', { ageMs: 2 * DAY, analyzed: true })
+    expect(sweepStore().removed).toEqual(['two-days-old'])
+  })
+})
+
+describe('sweepStore tidying', () => {
+  test('tidies analyzed survivors, so the bound applies to sessions already on disk', () => {
+    seed('store-tidy', { ageMs: DAY, analyzed: true, bytes: 100 })
+    writeFileSync(join(sessionDir('store-tidy'), 'calls.txt'), 'x'.repeat(50_000))
+
+    sweepStore({ budget: BUDGET })
+
+    expect(existsSync(join(sessionDir('store-tidy'), 'calls.txt'))).toBe(false)
+    expect(existsSync(join(sessionDir('store-tidy'), 'report.md'))).toBe(true)
+  })
+
+  test('an unanalyzed session is left alone — its analyzer may still be running', () => {
+    seed('store-pending', { ageMs: DAY, bytes: 100 })
+    writeFileSync(join(sessionDir('store-pending'), 'analyzer-prompt.md'), '# in flight')
+
+    sweepStore({ budget: BUDGET })
+
+    expect(existsSync(join(sessionDir('store-pending'), 'analyzer-prompt.md'))).toBe(true)
+  })
+
+  test('scratch is tidied before the size bound is measured, not after', () => {
+    // 60 KB of scratch against a 10 KB budget: tidying first brings the store
+    // back under on its own, so nothing should be evicted.
+    seed('store-bloated', { ageMs: DAY, analyzed: true, bytes: 100 })
+    writeFileSync(join(sessionDir('store-bloated'), 'calls.txt'), 'x'.repeat(60_000))
+
+    expect(sweepStore({ budget: BUDGET }).removed).toEqual([])
+    expect(existsSync(sessionDir('store-bloated'))).toBe(true)
+  })
+
+  test('a failed analysis keeps its prompt through the sweep', () => {
+    const dir = sessionDir('store-failed')
+    seed('store-failed', { ageMs: DAY, analyzed: true })
+    writeFileSync(
+      join(dir, '.analyzed'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'error', note: 'boom' }),
+    )
+    writeFileSync(join(dir, 'analyzer-prompt.md'), '# what we asked')
+
+    sweepStore({ budget: BUDGET })
+
+    expect(existsSync(join(dir, 'analyzer-prompt.md'))).toBe(true)
+  })
+})
+
+describe('tidySession', () => {
+  test('removes what the analyzer left behind, keeps the durable artifacts', () => {
+    const dir = sessionDir('tidy-scratch')
+    seed('tidy-scratch', { ageMs: DAY, analyzed: true, bytes: 100 })
+    writeFileSync(join(dir, 'analyzer.log'), 'exit 0')
+    writeFileSync(join(dir, 'analyzer-prompt.md'), '# prompt')
+    // Scratch: the analyzer runs with Write in here and answers to nobody.
+    writeFileSync(join(dir, 'calls.txt'), 'x'.repeat(50_000))
+    mkdirSync(join(dir, 'notes'), { recursive: true })
+    writeFileSync(join(dir, 'notes', 'draft.md'), 'scratch')
+
+    const removed = tidySession('tidy-scratch')
+
+    expect(removed.sort()).toEqual(['analyzer-prompt.md', 'calls.txt', 'notes'])
+    for (const keep of ['meta.json', 'events.jsonl', 'report.md', '.analyzed', 'analyzer.log']) {
+      expect(existsSync(join(dir, keep))).toBe(true)
+    }
+    expect(existsSync(join(dir, 'notes'))).toBe(false)
+  })
+
+  test('keepPrompt spares the prompt — the failing case is when it matters', () => {
+    const dir = sessionDir('tidy-failed')
+    seed('tidy-failed', { ageMs: DAY, analyzed: true })
+    writeFileSync(join(dir, 'analyzer-prompt.md'), '# prompt')
+    writeFileSync(join(dir, 'scratch.json'), '{}')
+
+    expect(tidySession('tidy-failed', { keepPrompt: true })).toEqual(['scratch.json'])
+    expect(existsSync(join(dir, 'analyzer-prompt.md'))).toBe(true)
+  })
+
+  test('a session with nothing to tidy is left exactly as it was', () => {
+    seed('tidy-clean', { ageMs: DAY, analyzed: true, bytes: 10 })
+    expect(tidySession('tidy-clean')).toEqual([])
+    expect(existsSync(sessionDir('tidy-clean'))).toBe(true)
+  })
+
+  test('a missing session directory is a no-op, not an error', () => {
+    expect(tidySession('tidy-absent')).toEqual([])
+  })
+})

package/src/telemetry/__tests__/settings.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { RetentionBudget } from '../settings'
+
+// Set the home before the paths singleton is captured (dynamic imports below).
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-settings-'))
+
+let retentionBudget: () => RetentionBudget
+let telemetryEnabled: () => boolean
+let DEFAULT_MAX_AGE_DAYS: number
+let DEFAULT_MAX_BYTES: number
+let configPath: string
+
+const DAY = 24 * 60 * 60 * 1000
+
+beforeAll(async () => {
+  const settings = await import('../settings')
+  retentionBudget = settings.retentionBudget
+  telemetryEnabled = settings.telemetryEnabled
+  DEFAULT_MAX_AGE_DAYS = settings.DEFAULT_MAX_AGE_DAYS
+  DEFAULT_MAX_BYTES = settings.DEFAULT_MAX_BYTES
+  configPath = join(process.env.ASTRALE_HOME!, 'config.json')
+})
+
+function writeConfig(telemetry: unknown): void {
+  writeFileSync(configPath, JSON.stringify({ telemetry }))
+}
+
+beforeEach(() => {
+  rmSync(configPath, { force: true })
+  delete process.env.ASTRALE_TELEMETRY
+  delete process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS
+  delete process.env.ASTRALE_TELEMETRY_MAX_BYTES
+})
+
+afterEach(() => {
+  rmSync(configPath, { force: true })
+  delete process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS
+  delete process.env.ASTRALE_TELEMETRY_MAX_BYTES
+})
+
+describe('retentionBudget', () => {
+  test('defaults when nothing is configured', () => {
+    expect(retentionBudget()).toEqual({
+      maxAgeMs: DEFAULT_MAX_AGE_DAYS * DAY,
+      maxBytes: DEFAULT_MAX_BYTES,
+    })
+  })
+
+  test('reads both bounds from config.json', () => {
+    writeConfig({ maxAgeDays: 7, maxBytes: 1_048_576 })
+    expect(retentionBudget()).toEqual({ maxAgeMs: 7 * DAY, maxBytes: 1_048_576 })
+  })
+
+  test('env wins over config', () => {
+    writeConfig({ maxAgeDays: 7, maxBytes: 1_048_576 })
+    process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS = '2'
+    process.env.ASTRALE_TELEMETRY_MAX_BYTES = '4096'
+    expect(retentionBudget()).toEqual({ maxAgeMs: 2 * DAY, maxBytes: 4096 })
+  })
+
+  test('a bad env value falls through to config rather than unbounding the store', () => {
+    writeConfig({ maxAgeDays: 7 })
+    process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS = 'soon'
+    expect(retentionBudget().maxAgeMs).toBe(7 * DAY)
+  })
+
+  test.each([
+    ['zero', 0],
+    ['negative', -1],
+    ['not a number', 'lots'],
+    ['null', null],
+  ])('%s config values fall back to the default', (_label, maxBytes) => {
+    writeConfig({ maxBytes })
+    expect(retentionBudget().maxBytes).toBe(DEFAULT_MAX_BYTES)
+  })
+
+  test('a broken config yields defaults instead of throwing', () => {
+    writeFileSync(configPath, '{ not json')
+    expect(retentionBudget().maxBytes).toBe(DEFAULT_MAX_BYTES)
+  })
+})
+
+describe('telemetryEnabled', () => {
+  test('on by default, and unaffected by retention keys', () => {
+    writeConfig({ maxAgeDays: 7 })
+    expect(telemetryEnabled()).toBe(true)
+  })
+
+  test('off via config', () => {
+    writeConfig({ enabled: false })
+    expect(telemetryEnabled()).toBe(false)
+  })
+
+  test.each(['0', 'false', 'off', 'OFF', ' off '])('off via ASTRALE_TELEMETRY=%p', (value) => {
+    process.env.ASTRALE_TELEMETRY = value
+    expect(telemetryEnabled()).toBe(false)
+  })
+})