diff --git a/.github/workflows/e2e-cli.yml b/.github/workflows/e2e-cli.yml index 21f381d802..ff9ec067f0 100644 --- a/.github/workflows/e2e-cli.yml +++ b/.github/workflows/e2e-cli.yml @@ -389,6 +389,7 @@ jobs: .llm/tmp/e2e-report-scaffold-runtime*.ndjson .llm/tmp/e2e-image-pulls.json .llm/tmp/cli-e2e/*/.netscript/e2e/listener-unreachable-receipt.json + .llm/tmp/e2e-invocation-diagnostics/*-diagnostic.json .llm/tmp/gate-receipts/scaffold-runtime/agent.aspire-mcp-smoke* include-hidden-files: true if-no-files-found: ignore @@ -507,6 +508,7 @@ jobs: .llm/tmp/e2e-report-scaffold-runtime-sqlite*.ndjson .llm/tmp/e2e-image-pulls.json .llm/tmp/cli-e2e/*/.netscript/e2e/listener-unreachable-receipt.json + .llm/tmp/e2e-invocation-diagnostics/*-diagnostic.json .llm/tmp/gate-receipts/scaffold-runtime-sqlite/agent.aspire-mcp-smoke* .llm/tmp/showcase-ai-browser/ include-hidden-files: true diff --git a/.llm/tools/docs/assert-corpus-bytes.ts b/.llm/tools/docs/assert-corpus-bytes.ts new file mode 100644 index 0000000000..93d7ab8b0e --- /dev/null +++ b/.llm/tools/docs/assert-corpus-bytes.ts @@ -0,0 +1,22 @@ +/** Exact byte comparison with bounded failure diagnostics, never an expanded corpus diff. */ +import { AssertionError } from '@std/assert'; + +async function digest(value: Uint8Array): Promise { + const copy = new Uint8Array(value.byteLength); + copy.set(value); + return [...new Uint8Array(await crypto.subtle.digest('SHA-256', copy))] + .map((byte) => byte.toString(16).padStart(2, '0')).join(''); +} + +export async function assertExactCorpusBytes( + actual: Uint8Array, + expected: Uint8Array, +): Promise { + let equal = actual.byteLength === expected.byteLength; + for (let i = 0; equal && i < actual.byteLength; i++) equal = actual[i] === expected[i]; + if (equal) return; + throw new AssertionError( + `Corpus bytes differ: length ${actual.byteLength}/${expected.byteLength}; ` + + `SHA256 ${await digest(actual)}/${await digest(expected)}`, + ); +} diff --git a/.llm/tools/docs/assert-corpus-bytes_test.ts b/.llm/tools/docs/assert-corpus-bytes_test.ts new file mode 100644 index 0000000000..306d7bc4e0 --- /dev/null +++ b/.llm/tools/docs/assert-corpus-bytes_test.ts @@ -0,0 +1,20 @@ +import { assert, AssertionError, assertRejects } from '@std/assert'; +import { assertExactCorpusBytes } from './assert-corpus-bytes.ts'; + +Deno.test('exact corpus bytes accept identical and empty payloads', async () => { + await assertExactCorpusBytes(new Uint8Array(), new Uint8Array()); + await assertExactCorpusBytes(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); +}); +Deno.test('length or same-length last-byte mismatch stays red with bounded payload-free diagnostics', async () => { + const actual = new Uint8Array(2 << 20).fill(65), expected = actual.slice(); + expected[expected.length - 1] = 66; + for (const pair of [[actual, expected], [actual, expected.subarray(1)]]) { + const error = await assertRejects( + () => assertExactCorpusBytes(pair[0], pair[1]), + AssertionError, + ); + assert(error.message.length < 256); + assert(error.message.includes('SHA256')); + assert(!error.message.includes('AAAA')); + } +}); diff --git a/.llm/tools/docs/export-corpus-doc-command.ts b/.llm/tools/docs/export-corpus-doc-command.ts new file mode 100644 index 0000000000..11a2b99516 --- /dev/null +++ b/.llm/tools/docs/export-corpus-doc-command.ts @@ -0,0 +1,73 @@ +/** Explicit static-documentation child policy; ordinary callers keep their existing loader. */ +import { isAbsolute, join, resolve } from '@std/path'; + +export interface ExportCorpusDocOptions { + readonly lockfile?: string; + readonly importHosts?: readonly string[]; + readonly cacheDir?: string; + readonly compilerFlags?: string; + readonly onChild?: (notice: { + readonly packageName: string; + readonly ordinal: number; + readonly total: number; + readonly phase: 'attempt' | 'complete'; + readonly exitCode?: number; + }) => void; +} + +/** Construct only supported Deno doc flags and a sterile strict-mode environment. */ +export function exportCorpusDocCommand( + root: string, + entrypoints: readonly string[], + options: ExportCorpusDocOptions, + ordinaryEnvironment: () => Record, +): { args: string[]; env: Record } { + const strict = options.lockfile !== undefined || options.importHosts !== undefined || + options.cacheDir !== undefined; + if (!strict) return { args: ['doc', '--json', ...entrypoints], env: ordinaryEnvironment() }; + const lockfile = options.lockfile && resolve(root, options.lockfile); + const cache = options.cacheDir && resolve(options.cacheDir); + const hosts = options.importHosts; + if ( + lockfile !== resolve(root, 'deno.lock') || !cache || !isAbsolute(options.cacheDir!) || + cache === resolve(root) || !hosts?.length || hosts.length > 16 || + new Set(hosts).size !== hosts.length + ) { + throw new Error( + 'Locked documentation requires the repository lock, explicit cache and public import hosts', + ); + } + for (const host of hosts) { + if ( + !/^[a-z0-9]+(?:[.-][a-z0-9]+)*\.[a-z]{2,}$/.test(host) || + /(?:^|\.)(?:localhost|local|internal|invalid|test)$/.test(host) + ) { + throw new Error('Documentation import host is not an explicit public hostname'); + } + } + if ( + options.compilerFlags && !/^--max-old-space-size=[1-9][0-9]{1,4}$/.test(options.compilerFlags) + ) { + throw new Error('Unsupported documentation compiler flags'); + } + const home = join(cache, 'home'); + return { + args: [ + 'doc', + '--json', + '--lock', + lockfile, + '--frozen-lockfile', + '--allow-import=' + hosts.join(','), + '--node-modules-dir=none', + ...entrypoints, + ], + env: { + DENO_DIR: cache, + HOME: home, + USERPROFILE: home, + NO_COLOR: '1', + ...(options.compilerFlags ? { DENO_V8_FLAGS: options.compilerFlags } : {}), + }, + }; +} diff --git a/.llm/tools/docs/export-corpus-doc-command_test.ts b/.llm/tools/docs/export-corpus-doc-command_test.ts new file mode 100644 index 0000000000..3566688df6 --- /dev/null +++ b/.llm/tools/docs/export-corpus-doc-command_test.ts @@ -0,0 +1,98 @@ +import { assertEquals, assertThrows } from '@std/assert'; +import { exportCorpusDocCommand } from './export-corpus-doc-command.ts'; +import { parseExportCorpusOptions } from './export-corpus-git-read.ts'; + +const options = { + lockfile: '/synthetic/repository/deno.lock', + cacheDir: '/synthetic/cache', + importHosts: ['jsr.io', 'registry.npmjs.org'], + compilerFlags: '--max-old-space-size=1152', +}; +Deno.test('locked documentation composes supported exact child flags and never copies caller auth environment', () => { + let environmentReads = 0; + const neverRead = () => { + environmentReads++; + return { SYNTHETIC_AUTH_TOKEN: 'never-copy-fixture' }; + }; + const plan = exportCorpusDocCommand( + '/synthetic/repository', + ['first.ts', 'second.ts'], + options, + neverRead, + ); + assertEquals(plan.args, [ + 'doc', + '--json', + '--lock', + options.lockfile, + '--frozen-lockfile', + '--allow-import=jsr.io,registry.npmjs.org', + '--node-modules-dir=none', + 'first.ts', + 'second.ts', + ]); + assertEquals(plan.env, { + DENO_DIR: '/synthetic/cache', + HOME: '/synthetic/cache/home', + USERPROFILE: '/synthetic/cache/home', + NO_COLOR: '1', + DENO_V8_FLAGS: '--max-old-space-size=1152', + }); + assertEquals( + Object.keys(plan.env).some((key) => /token|auth|proxy|session|force_color/i.test(key)), + false, + ); + assertEquals(plan.args.includes('--cached-only'), false); + assertEquals(environmentReads, 0); +}); +Deno.test('strict documentation refuses incomplete locks, private hosts, cache overrides and arbitrary compiler flags', () => { + const ordinary = () => ({}); + for ( + const invalid of [ + { ...options, lockfile: '/elsewhere/deno.lock' }, + { ...options, cacheDir: '/synthetic/repository' }, + { ...options, cacheDir: 'relative-cache' }, + { ...options, importHosts: ['localhost'] }, + { ...options, importHosts: ['service.internal'] }, + { ...options, importHosts: ['127.0.0.1'] }, + { ...options, importHosts: ['https://jsr.io'] }, + { ...options, importHosts: ['jsr.io', 'jsr.io'] }, + { ...options, compilerFlags: '--allow-natives-syntax' }, + { cacheDir: '/synthetic/cache' }, + { lockfile: options.lockfile }, + ] + ) { + assertThrows(() => + exportCorpusDocCommand('/synthetic/repository', ['first.ts'], invalid, ordinary) + ); + } +}); +Deno.test('ordinary documentation command and colour-normalized environment remain unchanged', () => { + const env = { NO_COLOR: '1', EXAMPLE: 'unchanged' }; + assertEquals(exportCorpusDocCommand('/synthetic/repository', ['first.ts'], {}, () => env), { + args: ['doc', '--json', 'first.ts'], + env, + }); +}); +Deno.test('documented strict CLI flags map to typed policy without accepting unsupported native cached-only', () => { + assertEquals( + parseExportCorpusOptions([ + '--doc-lockfile', + options.lockfile, + '--doc-cache-dir', + options.cacheDir, + '--doc-import-hosts', + 'jsr.io,registry.npmjs.org', + ]), + { + check: false, + allowDirty: false, + gitReadWrapper: undefined, + docLockfile: options.lockfile, + docCacheDir: options.cacheDir, + docImportHosts: options.importHosts, + }, + ); + assertThrows(() => parseExportCorpusOptions(['--cached-only'])); + assertThrows(() => parseExportCorpusOptions(['--doc-lockfile'])); +}); diff --git a/.llm/tools/docs/export-corpus-git-read.ts b/.llm/tools/docs/export-corpus-git-read.ts new file mode 100644 index 0000000000..148d094187 --- /dev/null +++ b/.llm/tools/docs/export-corpus-git-read.ts @@ -0,0 +1,133 @@ +/** Explicit Git-read delegation for the generator's existing clean-source guard. */ +import { resolve } from '@std/path'; + +export interface GeneratorGitCommand { + readonly executable: string; + readonly args: string[]; + readonly cwd: string; + readonly strict: boolean; +} +export interface GeneratorGitOutput { + readonly success: boolean; + readonly code: number; + readonly stdout: Uint8Array; + readonly stderr: Uint8Array; +} +export type GeneratorGitExecutor = (command: GeneratorGitCommand) => Promise; + +/** Parse supported generator options without treating wrapper values as new flags. */ +export function parseExportCorpusOptions(args: readonly string[]): { + check: boolean; + allowDirty: boolean; + gitReadWrapper?: string; + docLockfile?: string; + docCacheDir?: string; + docImportHosts?: string[]; +} { + const check = args.includes('--check'), allowDirty = args.includes('--allow-dirty'); + const index = args.indexOf('--git-read-wrapper'); + const gitReadWrapper = index < 0 ? undefined : args[index + 1]; + if ( + index >= 0 && (!gitReadWrapper || gitReadWrapper.startsWith('--') || + args.lastIndexOf('--git-read-wrapper') !== index) + ) throw new Error('--git-read-wrapper requires one executable'); + const docFlags = ['--doc-lockfile', '--doc-cache-dir', '--doc-import-hosts']; + const docValues: (string | undefined)[] = []; + const consumed = new Set(); + for (const flag of docFlags) { + const at = args.indexOf(flag), value = at < 0 ? undefined : args[at + 1]; + if (at >= 0) { + if (!value || value.startsWith('--') || args.lastIndexOf(flag) !== at) { + throw new Error(`${flag} requires one value`); + } + consumed.add(at); + consumed.add(at + 1); + } + docValues.push(value); + } + const unknown = args.filter((value, position) => + !consumed.has(position) && + value !== '--check' && value !== '--allow-dirty' && + !(index >= 0 && (position === index || position === index + 1)) + ); + if (unknown.length) throw new Error(`unknown argument: ${unknown[0]}`); + if (check && allowDirty) { + throw new Error('--allow-dirty is only valid when writing the generated corpus'); + } + if (gitReadWrapper && allowDirty) throw new Error('--git-read-wrapper cannot use --allow-dirty'); + return { + check, + allowDirty, + gitReadWrapper, + ...(docValues[0] !== undefined ? { docLockfile: docValues[0] } : {}), + ...(docValues[1] !== undefined ? { docCacheDir: docValues[1] } : {}), + ...(docValues[2] !== undefined ? { docImportHosts: docValues[2].split(',') } : {}), + }; +} + +/** The wrapper receives the actual resolved workspace and the exact source read set. */ +export function generatorGitCommand(root: string, wrapper?: string): GeneratorGitCommand { + const cwd = resolve(root); + const args = ['status', '--porcelain', '--', 'packages', 'plugins']; + return wrapper + ? { executable: wrapper, args: [cwd, '--', ...args], cwd, strict: true } + : { executable: 'git', args, cwd, strict: false }; +} + +async function execute(command: GeneratorGitCommand): Promise { + return await new Deno.Command(command.executable, { + args: command.args, + cwd: command.cwd, + stdout: 'piped', + stderr: 'piped', + ...(command.strict ? { signal: AbortSignal.timeout(20_000) } : {}), + }).output(); +} + +/** + * Preserve the ordinary generator guard; explicit delegation refuses closed. + * A wrapper failure never falls back to Git or a separate earlier clean proof. + */ +export async function guardGeneratorWrite( + root: string, + options: { readonly allowDirty: boolean; readonly gitReadWrapper?: string }, + run: GeneratorGitExecutor = execute, +): Promise { + if (options.gitReadWrapper && options.allowDirty) { + throw new Error('An approved Git read wrapper cannot be combined with --allow-dirty'); + } + const command = generatorGitCommand(root, options.gitReadWrapper); + let output: GeneratorGitOutput; + try { + output = await run(command); + } catch (error) { + if (command.strict) { + throw new Error('Approved Git read did not confirm clean generator sources'); + } + console.warn( + 'WARNING: Git is unavailable; continuing MCP export-corpus generation without ' + + `clean-tree verification (${error instanceof Error ? error.message : String(error)}).`, + ); + return; + } + if (!output.success) { + if (command.strict) throw new Error('Approved Git read refused generator source verification'); + const detail = new TextDecoder().decode(output.stderr).trim() || `exit ${output.code}`; + console.warn( + 'WARNING: Git status is unavailable; continuing MCP export-corpus generation without ' + + `clean-tree verification (${detail}).`, + ); + return; + } + const dirty = new TextDecoder().decode(output.stdout).trimEnd(); + if (!dirty) return; + const summary = `MCP export-corpus generator read set is dirty:\n${dirty}`; + if (options.allowDirty) { + console.warn(`WARNING: ${summary}\nProceeding because --allow-dirty was explicitly supplied.`); + return; + } + throw new Error( + `${summary}\nRefusing to generate from uncommitted package/plugin sources. ` + + 'Commit or stash them, or deliberately rerun with --allow-dirty.', + ); +} diff --git a/.llm/tools/docs/export-corpus-git-read_test.ts b/.llm/tools/docs/export-corpus-git-read_test.ts new file mode 100644 index 0000000000..844d880c9f --- /dev/null +++ b/.llm/tools/docs/export-corpus-git-read_test.ts @@ -0,0 +1,109 @@ +import { assertEquals, assertRejects, assertThrows } from '@std/assert'; +import { + generatorGitCommand, + guardGeneratorWrite, + parseExportCorpusOptions, +} from './export-corpus-git-read.ts'; + +const root = '/synthetic/repository'; +const wrapper = '/synthetic/tools/approved-read'; +const clean = { success: true, code: 0, stdout: new Uint8Array(), stderr: new Uint8Array() }; + +Deno.test('explicit Git delegation composes the exact resolved source guard without raw fallback', async () => { + const calls: unknown[] = []; + await guardGeneratorWrite(root, { allowDirty: false, gitReadWrapper: wrapper }, (command) => { + calls.push(command); + return Promise.resolve(clean); + }); + assertEquals(calls, [{ + executable: wrapper, + args: [root, '--', 'status', '--porcelain', '--', 'packages', 'plugins'], + cwd: root, + strict: true, + }]); + assertEquals(generatorGitCommand(root), { + executable: 'git', + args: ['status', '--porcelain', '--', 'packages', 'plugins'], + cwd: root, + strict: false, + }); +}); + +for (const reason of ['spawn refusal', 'timeout', 'permission refusal']) { + Deno.test(`approved reader ${reason} fails closed and never invokes fallback`, async () => { + let calls = 0; + await assertRejects( + () => + guardGeneratorWrite(root, { allowDirty: false, gitReadWrapper: wrapper }, () => { + calls++; + throw new Error(reason); + }), + Error, + 'Approved Git read did not confirm', + ); + assertEquals(calls, 1); + }); +} +Deno.test('approved reader nonzero is refusal rather than unverified success', async () => { + let calls = 0; + await assertRejects( + () => + guardGeneratorWrite(root, { allowDirty: false, gitReadWrapper: wrapper }, () => { + calls++; + return Promise.resolve({ ...clean, success: false, code: 2 }); + }), + Error, + 'Approved Git read refused', + ); + assertEquals(calls, 1); +}); +Deno.test('approved read preserves the committed package/plugin guard and rejects bypass', async () => { + await assertRejects( + () => + guardGeneratorWrite( + root, + { allowDirty: false, gitReadWrapper: wrapper }, + () => + Promise.resolve({ + ...clean, + stdout: new TextEncoder().encode(' M packages/example/mod.ts\n'), + }), + ), + Error, + 'read set is dirty', + ); + await assertRejects( + () => + guardGeneratorWrite( + root, + { allowDirty: true, gitReadWrapper: wrapper }, + () => Promise.resolve(clean), + ), + Error, + 'cannot be combined', + ); +}); +Deno.test('generator flags reject unknown first arguments and ambiguous wrapper/bypass combinations', () => { + assertEquals(parseExportCorpusOptions([]), { + check: false, + allowDirty: false, + gitReadWrapper: undefined, + }); + assertEquals(parseExportCorpusOptions(['--git-read-wrapper', wrapper]), { + check: false, + allowDirty: false, + gitReadWrapper: wrapper, + }); + for ( + const args of [ + ['--unknown'], + ['--git-read-wrapper'], + ['--git-read-wrapper', '--check'], + ['--git-read-wrapper', wrapper, '--git-read-wrapper', wrapper], + ['--check', '--allow-dirty'], + ['--git-read-wrapper', wrapper, '--allow-dirty'], + ] + ) { + assertThrows(() => parseExportCorpusOptions(args)); + } +}); diff --git a/.llm/tools/docs/generate-export-surface-corpus.ts b/.llm/tools/docs/generate-export-surface-corpus.ts index bc8d53dde2..2bcbb26d1a 100644 --- a/.llm/tools/docs/generate-export-surface-corpus.ts +++ b/.llm/tools/docs/generate-export-surface-corpus.ts @@ -1,10 +1,13 @@ /** Generate the version-pinned MCP export corpus from Deno's structured documentation surface. */ import { dirname, fromFileUrl, join, resolve, toFileUrl } from '@std/path'; +import { guardGeneratorWrite, parseExportCorpusOptions } from './export-corpus-git-read.ts'; +import { + exportCorpusDocCommand, + type ExportCorpusDocOptions, +} from './export-corpus-doc-command.ts'; const REPO_ROOT = resolve(dirname(fromFileUrl(import.meta.url)), '../../..'); -const ALLOW_DIRTY_ARGUMENT = '--allow-dirty'; -const GENERATOR_READ_SET = ['packages', 'plugins'] as const; /** Repository-relative generated corpus staged by release preparation. */ export const EXPORT_SURFACE_CORPUS_OUTPUT = 'packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts'; @@ -240,6 +243,7 @@ ${rows.join('\n\n')} /** Generate the complete first-party export corpus from current package export maps. */ export async function buildExportSurfaceCorpus( root: string = REPO_ROOT, + docOptions: ExportCorpusDocOptions = {}, ): Promise { const rootManifest = await readManifest(join(root, 'deno.json')); if (typeof rootManifest.version !== 'string' || !rootManifest.version.trim()) { @@ -255,17 +259,37 @@ export async function buildExportSurfaceCorpus( } const entries: GeneratedExportSurfaceEntry[] = []; - for (const packageName of [...new Set(sources.map((source) => source.packageName))].sort()) { + const packageNames = [...new Set(sources.map((source) => source.packageName))].sort(); + for (const [index, packageName] of packageNames.entries()) { const packageSources = sources.filter((source) => source.packageName === packageName); + const plan = exportCorpusDocCommand( + root, + packageSources.map((source) => source.entrypoint), + docOptions, + colorInvariantChildEnv, + ); const command = new Deno.Command(Deno.execPath(), { - args: ['doc', '--json', ...packageSources.map((source) => source.entrypoint)], + args: plan.args, cwd: root, - env: colorInvariantChildEnv(), + env: plan.env, clearEnv: true, stdout: 'piped', stderr: 'piped', }); + docOptions.onChild?.({ + packageName, + ordinal: index + 1, + total: packageNames.length, + phase: 'attempt', + }); const output = await command.output(); + docOptions.onChild?.({ + packageName, + ordinal: index + 1, + total: packageNames.length, + phase: 'complete', + exitCode: output.code, + }); if (!output.success) { throw new Error( `deno doc failed for ${packageName}: ${new TextDecoder().decode(output.stderr).trim()}`, @@ -526,48 +550,6 @@ export function colorInvariantChildEnv(): Record { return env; } -async function guardGeneratorWrite(root: string, allowDirty: boolean): Promise { - let output: Deno.CommandOutput; - try { - output = await new Deno.Command('git', { - args: ['status', '--porcelain', '--', ...GENERATOR_READ_SET], - cwd: root, - stdout: 'piped', - stderr: 'piped', - }).output(); - } catch (error) { - console.warn( - `WARNING: Git is unavailable; continuing MCP export-corpus generation without ` + - `clean-tree verification (${error instanceof Error ? error.message : String(error)}).`, - ); - return; - } - - if (!output.success) { - const detail = new TextDecoder().decode(output.stderr).trim() || `exit ${output.code}`; - console.warn( - `WARNING: Git status is unavailable; continuing MCP export-corpus generation without ` + - `clean-tree verification (${detail}).`, - ); - return; - } - - const dirty = new TextDecoder().decode(output.stdout).trimEnd(); - if (!dirty) return; - - const summary = `MCP export-corpus generator read set is dirty:\n${dirty}`; - if (allowDirty) { - console.warn( - `WARNING: ${summary}\nProceeding because ${ALLOW_DIRTY_ARGUMENT} was explicitly supplied.`, - ); - return; - } - throw new Error( - `${summary}\nRefusing to generate from uncommitted package/plugin sources. ` + - `Commit or stash them, or deliberately rerun with ${ALLOW_DIRTY_ARGUMENT}.`, - ); -} - async function formatTypeScript(source: string): Promise { const child = new Deno.Command(Deno.execPath(), { args: ['fmt', '--ext', 'ts', '-'], @@ -589,18 +571,35 @@ async function formatTypeScript(source: string): Promise { } if (import.meta.main) { - const check = Deno.args.includes('--check'); - const allowDirty = Deno.args.includes(ALLOW_DIRTY_ARGUMENT); - const unknown = Deno.args.filter((argument) => - argument !== '--check' && argument !== ALLOW_DIRTY_ARGUMENT - ); - if (unknown.length > 0) throw new Error(`unknown argument: ${unknown[0]}`); - if (check && allowDirty) { - throw new Error(`${ALLOW_DIRTY_ARGUMENT} is only valid when writing the generated corpus`); + if (Deno.args.includes('--help')) { + console.log([ + 'Generate/check the structured MCP export corpus.', + '--check Compare without writing.', + '--allow-dirty Explicit ordinary-mode bypass; incompatible with approved reader.', + '--git-read-wrapper Delegate exact committed-source status read; refusal fails closed.', + '--doc-lockfile Exact repository deno.lock for frozen public-source documentation.', + '--doc-import-hosts Comma-separated explicit public import hostnames.', + '--doc-cache-dir Dedicated absolute child cache; sterile child home/environment.', + 'Supply all three --doc-* flags together. No reload, lock write, root node_modules or app execution.', + ].join('\n')); + Deno.exit(0); } - if (!check) await guardGeneratorWrite(REPO_ROOT, allowDirty); + const { check, allowDirty, gitReadWrapper, docLockfile, docCacheDir, docImportHosts } = + parseExportCorpusOptions(Deno.args); + if (!check) await guardGeneratorWrite(REPO_ROOT, { allowDirty, gitReadWrapper }); const current = await Deno.readTextFile(OUTPUT_PATH).catch(() => ''); - const asset = await createGeneratedAsset(await buildExportSurfaceCorpus(), current); + const asset = await createGeneratedAsset( + await buildExportSurfaceCorpus(REPO_ROOT, { + lockfile: docLockfile, + cacheDir: docCacheDir, + importHosts: docImportHosts, + compilerFlags: docCacheDir ? Deno.env.get('DENO_V8_FLAGS') : undefined, + onChild: docCacheDir + ? (notice) => console.error(JSON.stringify({ docChild: notice })) + : undefined, + }), + current, + ); if (check) { if (current !== asset.source) { throw new Error('MCP export-surface corpus is stale; run deno task gen:mcp-export-corpus'); diff --git a/.llm/tools/docs/generate-export-surface-corpus_test.ts b/.llm/tools/docs/generate-export-surface-corpus_test.ts index 6124e50417..715ca04ff2 100644 --- a/.llm/tools/docs/generate-export-surface-corpus_test.ts +++ b/.llm/tools/docs/generate-export-surface-corpus_test.ts @@ -1,5 +1,6 @@ import { assert, assertEquals, assertMatch } from '@std/assert'; import { EmbeddedExportSurfaceCorpus } from '../../../packages/mcp/mod.ts'; +import { assertExactCorpusBytes } from './assert-corpus-bytes.ts'; import { colorInvariantChildEnv, createGeneratedAsset, @@ -270,7 +271,7 @@ Deno.test('write mode generates the artifact from a clean committed tree', async const generated = await runGenerator(worktree); assertEquals(generated.code, 0, generated.stderr); - assertEquals(await Deno.readFile(corpusPath(worktree)), before); + await assertExactCorpusBytes(await Deno.readFile(corpusPath(worktree)), before); await assertArtifactWasWritten(worktree, oldTime); }); }); diff --git a/.llm/tools/validation/fixtures/aspire-surface-manifest.tsv b/.llm/tools/validation/fixtures/aspire-surface-manifest.tsv index 4512961013..e3ea7eee99 100644 --- a/.llm/tools/validation/fixtures/aspire-surface-manifest.tsv +++ b/.llm/tools/validation/fixtures/aspire-surface-manifest.tsv @@ -365,9 +365,14 @@ packages/cli/e2e/src/application/gates/scaffold/runtime/credential-secret-surfac packages/cli/e2e/src/application/gates/scaffold/runtime/dashboard-config_test.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/dashboard-config.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/describe-capture.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/describe-follow.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/doctor.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/resource-command.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/listener-fault-controller.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/listener-readiness-gates.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) diff --git a/packages/cli/e2e/src/adapters/commands/deno-command-adapter.ts b/packages/cli/e2e/src/adapters/commands/deno-command-adapter.ts index 8a782677ee..2ae73e41d3 100644 --- a/packages/cli/e2e/src/adapters/commands/deno-command-adapter.ts +++ b/packages/cli/e2e/src/adapters/commands/deno-command-adapter.ts @@ -8,22 +8,36 @@ const decoder = new TextDecoder(); /** Deno.Command-backed process adapter. */ export class DenoCommandAdapter implements CommandExecutor { + constructor( + private readonly native: { + capture(command: string, options: Deno.CommandOptions): Promise; + status(command: string, options: Deno.CommandOptions): Promise; + } = { + capture: (command, options) => new Deno.Command(command, options).output(), + status: (command, options) => new Deno.Command(command, options).spawn().status, + }, + ) {} async run(request: CommandRequest): Promise { const controller = new AbortController(); + let deadlineExpired = false; + const settlementSignal = () => ({ abortRequested: controller.signal.aborted, deadlineExpired }); const timeout = request.timeoutMs - ? setTimeout(() => controller.abort(), request.timeoutMs) + ? setTimeout(() => { + deadlineExpired = true; + controller.abort(); + }, request.timeoutMs) : undefined; try { const [command, ...args] = request.command; if (request.outputMode === 'discard') { - const child = new Deno.Command(command, { + const status = await this.native.status(command, { args, cwd: request.cwd, stdout: 'null', stderr: 'null', signal: controller.signal, - }).spawn(); - const status = await child.status; + }); + const signalAtSettlement = settlementSignal(); return { command: request.command, cwd: request.cwd, @@ -31,27 +45,31 @@ export class DenoCommandAdapter implements CommandExecutor { stdout: '', stderr: status.code === 0 ? '' : request.failureHint ?? 'Command failed while output capture was disabled. Re-run the command directly to inspect its output.', - timedOut: false, + timedOut: signalAtSettlement.deadlineExpired, + signalAtSettlement, }; } - const output = await new Deno.Command(command, { + const output = await this.native.capture(command, { args, cwd: request.cwd, stdout: 'piped', stderr: 'piped', signal: controller.signal, - }).output(); + }); + const signalAtSettlement = settlementSignal(); return { command: request.command, cwd: request.cwd, code: output.code, stdout: decoder.decode(output.stdout), stderr: decoder.decode(output.stderr), - timedOut: false, + timedOut: signalAtSettlement.deadlineExpired, + signalAtSettlement, }; } catch (error) { - const timedOut = error instanceof DOMException && error.name === 'AbortError'; + const signalAtSettlement = settlementSignal(); + const timedOut = signalAtSettlement.deadlineExpired; return { command: request.command, cwd: request.cwd, @@ -59,6 +77,7 @@ export class DenoCommandAdapter implements CommandExecutor { stdout: '', stderr: timedOut ? 'Command timed out.' : String(error), timedOut, + signalAtSettlement, }; } finally { if (timeout) clearTimeout(timeout); diff --git a/packages/cli/e2e/src/application/gates/command-gate.ts b/packages/cli/e2e/src/application/gates/command-gate.ts index a84eee32db..f8ca861980 100644 --- a/packages/cli/e2e/src/application/gates/command-gate.ts +++ b/packages/cli/e2e/src/application/gates/command-gate.ts @@ -38,6 +38,7 @@ export class CommandGate { for (let attempt = 1; attempt <= maxAttempts; attempt++) { const started = performance.now(); + const startedAt = new Date().toISOString(); const result = await this.executor.run({ cwd: this.definition.cwd(context), command: this.definition.command(context), @@ -46,6 +47,12 @@ export class CommandGate { failureHint: this.definition.failureHint, }); const durationMs = Math.round(performance.now() - started); + const completedAt = new Date().toISOString(); + try { + await this.definition.afterCommand?.({ context, result, startedAt, completedAt }); + } catch { + console.warn('Command diagnostic unavailable; original outcome preserved.'); + } const missingOutput = (this.definition.stdoutIncludes ?? []).filter((value) => !result.stdout.includes(value) ); @@ -70,6 +77,7 @@ export class CommandGate { cwd: result.cwd, code: result.code, timedOut: result.timedOut, + signalAtSettlement: result.signalAtSettlement ?? null, stdoutTail: tail(result.stdout), stderrTail: tail(result.stderr), }, diff --git a/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts b/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts index ed348a7754..18af765509 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts @@ -1,3 +1,4 @@ +import { databaseGenerateEvidence } from './runtime/evidence/database-generate-diagnostic.ts'; import { join } from '@std/path'; import { GATE, GATE_PHASE } from '../../../domain/cli-surface.ts'; import type { GateDefinition } from '../../../domain/gate-definition.ts'; @@ -76,21 +77,24 @@ export function createDatabaseGates(): readonly GateDefinition[] { ], (context) => context.project.projectRoot, ), - commandGate( - GATE.DATABASE_GENERATE, - 'Generate database clients', - GATE_PHASE.DATABASE, - (context) => - cli( - context, - 'db', - 'generate', - '--project-root', - context.project.projectRoot, - '--db', - context.request.options.database, - ), - ), + { + ...commandGate( + GATE.DATABASE_GENERATE, + 'Generate database clients', + GATE_PHASE.DATABASE, + (context) => + cli( + context, + 'db', + 'generate', + '--project-root', + context.project.projectRoot, + '--db', + context.request.options.database, + ), + ), + afterCommand: databaseGenerateEvidence(), + }, commandGate( GATE.DATABASE_DEPLOY, 'Apply pending migrations without creating one', diff --git a/packages/cli/e2e/src/application/gates/scaffold/gate-factory.ts b/packages/cli/e2e/src/application/gates/scaffold/gate-factory.ts index 8c75b05e8e..68f49cf7c4 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/gate-factory.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/gate-factory.ts @@ -4,8 +4,8 @@ import { PACKAGE_SOURCE } from '../../../domain/extension-axes.ts'; import { resolve } from '@std/path'; import type { CommandFactory, + CommandGateDefinition, CommandGateRetryPolicy, - GateDefinition, GateFailureClass, HttpGateDefinition, } from '../../../domain/gate-definition.ts'; @@ -57,7 +57,7 @@ export function commandGate( retry?: CommandGateRetryPolicy, timeoutMs?: number, failureClass?: GateFailureClass, -): GateDefinition { +): CommandGateDefinition { return { id, title, diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts index aba0a5150a..572acda1b9 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts @@ -1,4 +1,6 @@ +import { saveOwnedInvocationDiagnostics } from './owned-invocation-diagnostic.ts'; import { basename, dirname, isAbsolute, relative, resolve } from '@std/path'; +import { type CapturedInvocation, withInvocationEvidence } from './invocation-diagnostic.ts'; export const ASPIRE_MOUNTS = 'com.microsoft.developer.usvc-dev.mountsLabel'; export const ASPIRE_CREATOR_PID = 'com.microsoft.developer.usvc-dev.creatorProcessId'; @@ -182,64 +184,99 @@ export async function stopAndProbe( projectRoot: string, cleanup: boolean, receiptPath: string, + options: { + readonly runnerRoot?: string; + readonly run?: typeof capture; + readonly wait?: (ms: number) => Promise; + readonly diagnostic?: ( + transcripts: readonly CapturedInvocation[], + evaluation?: PostStopProbeEvaluation, + ) => Promise; + } = {}, ): Promise { - const commands: (readonly string[])[] = [ - stopCommand(appHost, false), - ...(cleanup ? [stopCommand(appHost, true)] : []), - ]; - const transcripts = []; - for (const command of commands) { - transcripts.push(await capture(command[0] ?? 'aspire', command.slice(1))); - } - const idsOutput = await requireSuccess('docker', ['ps', '-aq']); - const vanishedContainerIds = new Set(); - const initialInspection = await inspectAllContainers(); - initialInspection.vanishedContainerIds.forEach((id) => vanishedContainerIds.add(id)); - // Container teardown is asynchronous to `aspire stop`, so a first probe can observe a container - // that is already on its way out. Re-probe with one forced exact-AppHost stop between attempts, - // bounded, retaining every observation as evidence. - let observedContainers = initialInspection.containers; - const { evaluation, attempts } = await resolveOwnedSurvivors( - async () => { - const inspection = await inspectAllContainers(); - observedContainers = inspection.containers; - inspection.vanishedContainerIds.forEach((id) => vanishedContainerIds.add(id)); - return evaluatePostStopProbe( - { appHost, projectRoot, containers: observedContainers, processes: [] }, - projectRoot, - ); - }, - async () => { - const forced = stopCommand(appHost, true); - transcripts.push(await capture(forced[0] ?? 'aspire', forced.slice(1))); - commands.push(forced); - }, - (ms) => new Promise((resolve) => setTimeout(resolve, ms)), - ); - const receipt = { - appHost, - cleanup, - commands, - transcripts, - docker: { - ids: idsOutput, - containers: observedContainers, - vanishedContainerIds: [...vanishedContainerIds], - }, - survivorAttempts: attempts, - evaluation, - }; - await Deno.mkdir(dirname(receiptPath), { recursive: true }); - await Deno.writeTextFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`); - assertNoOwnedSurvivors(evaluation); - const terminalStop = transcripts.at(-1); - if (!terminalStop || terminalStop.code !== 0) { - throw new Error( - `Aspire stop did not complete: ${ - terminalStop?.stderr || terminalStop?.stdout || 'no transcript' - }`, + const run = options.run ?? capture; + const transcripts: CapturedInvocation[] = []; + let finalEvaluation: PostStopProbeEvaluation | undefined; + await withInvocationEvidence(async () => { + const commands: (readonly string[])[] = [ + stopCommand(appHost, false), + ...(cleanup ? [stopCommand(appHost, true)] : []), + ]; + for (const command of commands) { + transcripts.push(await run(command[0] ?? 'aspire', command.slice(1))); + } + const idsOutput = await requireSuccess('docker', ['ps', '-aq'], run); + const vanishedContainerIds = new Set(); + const initialInspection = await inspectAllContainers(run); + initialInspection.vanishedContainerIds.forEach((id) => vanishedContainerIds.add(id)); + // Container teardown is asynchronous to `aspire stop`, so a first probe can observe a container + // that is already on its way out. Re-probe with one forced exact-AppHost stop between attempts, + // bounded, retaining every observation as evidence. + let observedContainers = initialInspection.containers; + const { evaluation, attempts } = await resolveOwnedSurvivors( + async () => { + const inspection = await inspectAllContainers(run); + observedContainers = inspection.containers; + inspection.vanishedContainerIds.forEach((id) => vanishedContainerIds.add(id)); + return evaluatePostStopProbe( + { appHost, projectRoot, containers: observedContainers, processes: [] }, + projectRoot, + ); + }, + async () => { + const forced = stopCommand(appHost, true); + transcripts.push(await run(forced[0] ?? 'aspire', forced.slice(1))); + commands.push(forced); + }, + options.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))), ); - } + finalEvaluation = evaluation; + const receipt = { + appHost, + cleanup, + commands, + transcripts, + docker: { + ids: idsOutput, + containers: observedContainers, + vanishedContainerIds: [...vanishedContainerIds], + }, + survivorAttempts: attempts, + evaluation, + }; + await Deno.mkdir(dirname(receiptPath), { recursive: true }); + await Deno.writeTextFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`); + assertNoOwnedSurvivors(evaluation); + const terminalStop = transcripts.at(-1); + if (!terminalStop || terminalStop.code !== 0) { + throw new Error( + `Aspire stop did not complete: ${ + terminalStop?.stderr || terminalStop?.stdout || 'no transcript' + }`, + ); + } + }, async () => { + if (options.diagnostic) return await options.diagnostic(transcripts, finalEvaluation); + const home = Deno.env.get('HOME') ?? Deno.env.get('USERPROFILE'); + const uid = (await Deno.stat(projectRoot)).uid; + if (!home || uid === null) throw new Error('diagnostic_owner_unavailable'); + await saveOwnedInvocationDiagnostics({ + projectRoot, + appHost, + kind: 'cleanup', + runnerRoot: options.runnerRoot, + home, + uid, + transcripts, + survivorCounts: finalEvaluation + ? { + ownedContainers: finalEvaluation.ownedContainers.length, + foreignContainers: finalEvaluation.foreignContainers.length, + unprovenContainers: finalEvaluation.unprovenContainers.length, + } + : undefined, + }); + }); } /** Inspect every container currently known to Docker, so each probe sees the present state. */ @@ -287,13 +324,16 @@ export function stopCommand(appHost: string, force: boolean): readonly string[] async function capture( command: string, args: readonly string[], -): Promise<{ readonly code: number; readonly stdout: string; readonly stderr: string }> { +): Promise { + const startedAt = new Date().toISOString(); const output = await new Deno.Command(command, { args: [...args], stdout: 'piped', stderr: 'piped', }).output(); const result = { + startedAt, + completedAt: new Date().toISOString(), code: output.code, stdout: new TextDecoder().decode(output.stdout), stderr: new TextDecoder().decode(output.stderr), @@ -378,9 +418,9 @@ function record(value: unknown, label: string): Record { } if (import.meta.main) { - const [appHost, projectRoot, cleanupValue, receiptPath] = Deno.args; + const [appHost, projectRoot, cleanupValue, receiptPath, runnerRoot] = Deno.args; if (!appHost || !projectRoot || !cleanupValue || !receiptPath) { throw new Error('cleanup requires AppHost, project root, cleanup boolean, and receipt path'); } - await stopAndProbe(appHost, projectRoot, cleanupValue === 'true', receiptPath); + await stopAndProbe(appHost, projectRoot, cleanupValue === 'true', receiptPath, { runnerRoot }); } diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts new file mode 100644 index 0000000000..485ec90f66 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts @@ -0,0 +1,134 @@ +import type { CommandSignalAtSettlement } from '../../../../../ports/command-executor.ts'; +import type { CommandObservation } from '../../../../../domain/gate-definition.ts'; +/** Test-only evidence around the original database.generate command; no additional Aspire calls. */ +import { saveOwnedInvocationDiagnostics } from './owned-invocation-diagnostic.ts'; +import { type CapturedInvocation, diagnosticResourceName } from './invocation-diagnostic.ts'; +import { generatedAppName } from '../generated-app-name.ts'; + +/** The nested Aspire exit is reported by the CLI, distinct from the captured database CLI exit. */ +export function reportedRestartFailure( + text: string, + appHost: string, + scoped: readonly string[] = [], +) { + const match = + /Database client generated, but ([a-z][a-z0-9-]{0,127}) restart failed \(Aspire exit ([0-9]{1,3})\)\./ + .exec(text); + if ( + !match || diagnosticResourceName(match[1], scoped) === null || Number(match[2]) > 255 || + !text.includes(`Run: aspire resource ${match[1]} restart --apphost ${JSON.stringify(appHost)}`) + ) return undefined; + return { resource: match[1], exit: Number(match[2]) }; +} + +/** Build a diagnostic observer for the existing direct command executor, never a subprocess wrapper. */ +export function databaseGenerateEvidence( + collect: ( + input: { + readonly projectRoot: string; + readonly appHost: string; + readonly runnerRoot: string; + readonly invocation: CapturedInvocation; + }, + ) => Promise = save, +): (observation: CommandObservation) => Promise { + return ({ context, result, startedAt, completedAt }) => + collectDatabaseGenerateExecution({ + projectRoot: context.project.projectRoot, + appHost: context.project.appHost, + runnerRoot: context.project.repoRoot, + result, + scopedResources: ['users', generatedAppName(context)], + startedAt, + completedAt, + }, collect); +} + +/** Evidence from a direct documented command, using the same safe owning collector. */ +export function collectDatabaseGenerateExecution(input: { + readonly projectRoot: string; + readonly appHost: string; + readonly runnerRoot: string; + readonly result: Pick< + CommandObservation['result'], + 'code' | 'stdout' | 'stderr' | 'timedOut' | 'signalAtSettlement' + >; + readonly scopedResources?: readonly string[]; + readonly startedAt: string; + readonly completedAt: string; +}, collect: Parameters[0] = save): Promise { + return collect({ + projectRoot: input.projectRoot, + appHost: input.appHost, + runnerRoot: input.runnerRoot, + invocation: { + code: input.result.code, + stdout: input.result.stdout, + stderr: input.result.stderr, + timedOut: input.result.timedOut, + signalAtSettlement: input.result.signalAtSettlement, + scopedResources: input.scopedResources, + startedAt: input.startedAt, + completedAt: input.completedAt, + process: 'database_cli', + reportedRestart: reportedRestartFailure( + input.result.stderr + '\n' + input.result.stdout, + input.appHost, + input.scopedResources, + ), + }, + }); +} + +/** Select only the actual documented database-generation command, before native execution. */ +export function documentedDatabaseGenerateEvidence( + words: readonly string[], + scope: { readonly projectRoot: string; readonly appHost: string; readonly runnerRoot: string }, + collect?: Parameters[0], +): + | (( + output: { + result: Deno.CommandOutput; + startedAt: string; + completedAt: string; + signalAtSettlement: CommandSignalAtSettlement; + }, + ) => Promise) + | undefined { + if (words[0] !== 'netscript' || words[1] !== 'db' || words[2] !== 'generate') return undefined; + return ({ result, startedAt, completedAt, signalAtSettlement }) => + collectDatabaseGenerateExecution({ + ...scope, + startedAt, + completedAt, + result: { + code: result.code, + stdout: new TextDecoder().decode(result.stdout), + stderr: new TextDecoder().decode(result.stderr), + timedOut: signalAtSettlement.deadlineExpired, + signalAtSettlement, + }, + }, collect); +} + +async function save( + input: { + readonly projectRoot: string; + readonly appHost: string; + readonly runnerRoot: string; + readonly invocation: CapturedInvocation; + }, +): Promise { + const home = Deno.env.get('HOME') ?? Deno.env.get('USERPROFILE'); + const uid = (await Deno.stat(input.projectRoot)).uid; + if (!home || uid === null) throw new Error('diagnostic_owner_unavailable'); + await saveOwnedInvocationDiagnostics({ + projectRoot: input.projectRoot, + appHost: input.appHost, + runnerRoot: input.runnerRoot, + kind: 'restart', + home, + uid, + transcripts: [input.invocation], + }); +} diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts new file mode 100644 index 0000000000..71518c0eb6 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts @@ -0,0 +1,275 @@ +import { documentedScaffoldCommand } from '../../verify-documented-scaffold.ts'; +import { assert, assertEquals } from '@std/assert'; +import { + databaseGenerateEvidence, + documentedDatabaseGenerateEvidence, + reportedRestartFailure, +} from './database-generate-diagnostic.ts'; +import { CommandGate } from '../../../command-gate.ts'; +import { createDatabaseGates } from '../../database-gates.ts'; +import type { RunContext } from '../../../../../domain/run-context.ts'; +import type { GateResult } from '../../../../../domain/gate-definition.ts'; + +const context: RunContext = { + request: { + suiteId: 'scaffold.runtime', + options: { + repoRoot: '/repo', + cliEntrypoint: 'packages/cli/bin/netscript.ts', + smokeRoot: '/repo/run', + projectName: 'app', + database: 'postgres', + packageSource: 'local', + plugins: [], + samples: true, + cache: true, + cleanup: true, + format: 'pretty', + commandTimeoutMs: 900000, + httpTimeoutMs: 30000, + }, + }, + project: { + repoRoot: '/repo', + cliEntrypoint: 'packages/cli/bin/netscript.ts', + smokeRoot: '/repo/run', + projectName: 'app', + projectRoot: '/repo/run/app', + appHost: '/repo/run/app/aspire/apphost.mts', + }, +}; +const appHost = context.project.appHost; +const failure = + `Database client generated, but web restart failed (Aspire exit 16). summary\nRun: aspire resource web restart --apphost ${ + JSON.stringify(appHost) + }`; + +Deno.test('database generate remains the direct child; evidence follows original success failure and timeout settlement', async () => { + const definition = createDatabaseGates().find((g) => g.id === 'database.generate'); + assert(definition?.kind === 'command'); + assert(definition.afterCommand); + const expected = [ + 'deno', + 'run', + '-A', + '/repo/packages/cli/bin/netscript.ts', + 'db', + 'generate', + '--project-root', + '/repo/run/app', + '--db', + 'postgres', + ]; + assertEquals(definition.command(context), expected); + for ( + const outcome of [{ code: 0, timedOut: false }, { code: 1, timedOut: false }, { + code: 124, + timedOut: true, + }] + ) { + let calls = 0, collected = 0, settled = false; + const afterCommand = databaseGenerateEvidence((input) => { + assert(settled); + collected++; + assertEquals(input.invocation.code, outcome.code); + assertEquals(input.invocation.timedOut, outcome.timedOut); + assertEquals(input.invocation.process, 'database_cli'); + assertEquals( + input.invocation.reportedRestart, + outcome.code === 1 ? { resource: 'web', exit: 16 } : undefined, + ); + return Promise.reject(new Error('SECRET_COLLECTOR')); + }); + const gate = new CommandGate({ ...definition, afterCommand }, { + run: async (request) => { + calls++; + assertEquals(request.command, expected); + assertEquals(request.timeoutMs, 900000); + await Promise.resolve(); + settled = true; + return { + command: request.command, + cwd: request.cwd, + ...outcome, + stdout: 'detail', + stderr: outcome.code === 1 ? failure : '', + }; + }, + }); + let thrown: unknown; + let result: GateResult | undefined; + try { + result = await gate.execute(context); + } catch (error) { + thrown = error; + } + assertEquals(thrown, undefined, 'evidence collection must preserve original settlement'); + assert(result); + assertEquals(result.verdict, outcome.code === 0 ? 'passed' : 'failed'); + assertEquals(result.attempts[0].exitCode, outcome.code); + assertEquals(result.retried, false); + assertEquals(calls, 1); + assertEquals(collected, 1); + } +}); +Deno.test('nested restart result requires the exact reported target and never becomes a captured process status', () => { + assertEquals(reportedRestartFailure(failure, appHost), { resource: 'web', exit: 16 }); + assertEquals(reportedRestartFailure(failure, '/foreign/apphost.mts'), undefined); + assertEquals(reportedRestartFailure(failure.replace('exit 16', 'exit 999'), appHost), undefined); +}); + +Deno.test('documented database command observes original native output without replacing failure or running another child', async () => { + const scope = { projectRoot: context.project.projectRoot, appHost, runnerRoot: '/repo' }; + let calls = 0, collections = 0, settled = false; + const words = ['netscript', 'db', 'generate']; + const args = ['run', '-A', '/repo/cli.ts', ...words.slice(1)]; + const collect: Parameters[2] = (input) => { + assert(settled); + collections++; + assertEquals(input.projectRoot, scope.projectRoot); + assertEquals(input.runnerRoot, '/repo'); + assertEquals(input.invocation.code, 1); + assertEquals(input.invocation.reportedRestart, { resource: 'web', exit: 16 }); + return Promise.reject(new Error('SECRET_DIAGNOSTIC_FAILURE')); + }; + let failure: unknown; + try { + await documentedScaffoldCommand(words, words.slice(1), { + ...scope, + cwd: scope.projectRoot, + cliEntrypoint: '/repo/cli.ts', + repoRoot: '/repo', + }, { + collect, + execute: (program, options) => { + calls++; + assertEquals(program, Deno.execPath()); + assertEquals(options.args, args); + assertEquals(options.cwd, scope.projectRoot); + assertEquals(options.stdin, 'null'); + assertEquals(options.stdout, 'piped'); + assertEquals(options.stderr, 'piped'); + assert(options.signal); + settled = true; + return Promise.resolve({ + code: 1, + signal: null, + success: false, + stdout: new TextEncoder().encode('original stdout'), + stderr: new TextEncoder().encode(failureText), + }); + }, + }); + } catch (error) { + failure = error; + } + assert(failure instanceof Error); + assertEquals( + failure.message, + `${Deno.execPath()} ${args.join(' ')} exited 1: ${failureText}\noriginal stdout`, + ); + assertEquals(calls, 1); + assertEquals(collections, 1); + for ( + const other of [['netscript', 'db', 'seed'], ['aspire', 'start'], ['deno', 'db', 'generate']] + ) { + assertEquals(documentedDatabaseGenerateEvidence(other, scope), undefined); + } +}); +const failureText = failure; + +Deno.test('documented command keeps successful output and original native rejection when diagnostics are unavailable', async () => { + const words = ['netscript', 'db', 'generate']; + const input = { + cwd: '/repo/run/app', + projectRoot: '/repo/run/app', + appHost, + repoRoot: '/repo', + cliEntrypoint: '/repo/cli.ts', + }; + let calls = 0, collections = 0; + const success = await documentedScaffoldCommand(words, words.slice(1), input, { + execute: () => { + calls++; + return Promise.resolve({ + code: 0, + signal: null, + success: true, + stdout: new TextEncoder().encode('original success'), + stderr: new Uint8Array(), + }); + }, + collect: () => { + collections++; + return Promise.reject(new Error('SECRET_COLLECTOR')); + }, + }); + assertEquals(success, 'original success'); + assertEquals(calls, 1); + assertEquals(collections, 1); + const original = new Error('fixture_native_rejection'); + let caught: unknown; + try { + await documentedScaffoldCommand(words, words.slice(1), input, { + execute: () => { + calls++; + return Promise.reject(original); + }, + collect: () => { + collections++; + return Promise.resolve(); + }, + }); + } catch (error) { + caught = error; + } + assertEquals(caught, original); + assertEquals(calls, 2); + assertEquals(collections, 1); +}); + +Deno.test('database evidence binds a generated consumer name to the actual run scope', async () => { + const scoped: RunContext = { + ...context, + request: { + ...context.request, + options: { ...context.request.options, projectName: 'synthetic-smoke' }, + }, + }; + const name = 'synthetic-smoke-web'; + const text = + `Database client generated, but ${name} restart failed (Aspire exit 16).\nRun: aspire resource ${name} restart --apphost ${ + JSON.stringify(appHost) + }`; + let reported: unknown; + await databaseGenerateEvidence((input) => { + reported = input.invocation.reportedRestart; + return Promise.resolve(); + })({ + context: scoped, + result: { command: ['deno'], cwd: '/repo', code: 1, stdout: '', stderr: text, timedOut: false }, + startedAt: '2026-01-01T23:01:18.000Z', + completedAt: '2026-01-01T23:01:47.000Z', + }); + assertEquals(reported, { resource: name, exit: 16 }); +}); + +Deno.test('generated restart reporting refuses foreign names or another host even with an apparently valid remedy', () => { + const scoped = ['synthetic-smoke-web']; + const text = (name: string, host: string) => + `Database client generated, but ${name} restart failed (Aspire exit 16).\nRun: aspire resource ${name} restart --apphost ${ + JSON.stringify(host) + }`; + assertEquals(reportedRestartFailure(text('synthetic-smoke-web', appHost), appHost, scoped), { + resource: 'synthetic-smoke-web', + exit: 16, + }); + assertEquals( + reportedRestartFailure(text('foreign-smoke-web', appHost), appHost, scoped), + undefined, + ); + assertEquals( + reportedRestartFailure(text('synthetic-smoke-web', '/foreign/apphost.mts'), appHost, scoped), + undefined, + ); +}); diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts new file mode 100644 index 0000000000..a6b3f0fce7 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts @@ -0,0 +1,342 @@ +/** Bounded allowlisted evidence from an already-executed owned Aspire invocation. No process calls. */ +import { basename, isAbsolute, relative, resolve } from '@std/path'; + +const MAX_BYTES = 256 << 10; +const CLI_LOG = /^cli_(\d{8}T\d{6})_[a-f0-9]{8,32}\.log$/i; +const APPHOST_LOG = /^cli_\d{8}T\d{9}_detach-child_[a-f0-9]{8,32}\.log$/i; +const KINDS = new Set(['container', 'volume', 'network', 'process', 'project', 'executable']); +const NAMES = new Set([ + 'web', + 'api', + 'workers', + 'postgres', + 'redis', + 'garnet', + 'streams', + 'dashboard', +]); +const ERRORS = new Set(['permission_denied', 'not_found', 'in_use', 'timeout', 'cleanup_failed']); +export interface CapturedInvocation { + readonly code: number; + readonly stdout: string; + readonly stderr: string; + readonly startedAt?: string; + readonly completedAt?: string; + readonly process?: 'aspire' | 'database_cli'; + readonly timedOut?: boolean; + readonly reportedRestart?: { readonly resource: string; readonly exit: number }; + /** Trusted fixture scope, never taken from command output. */ + readonly scopedResources?: readonly string[]; + readonly signalAtSettlement?: { + readonly abortRequested: boolean; + readonly deadlineExpired: boolean; + }; +} +export interface DiagnosticRecord { + readonly resourceKind: string | null; + readonly resourceName: string | null; + readonly errorCode: string | null; + readonly stopState?: 'requested' | 'not_terminal' | 'confirmed'; +} +/** Names beyond the fixed vocabulary require an exact server-owned run binding. */ +export function diagnosticResourceName( + name: unknown, + scoped: readonly string[] = [], +): string | null { + if (typeof name !== 'string') return null; + if (NAMES.has(name)) return name; + return scoped.length <= 16 && scoped.includes(name) && /^[a-z][a-z0-9-]{0,127}$/.test(name) + ? name + : null; +} +function recordTime(row: Record | null): number | null { + const value = row?.Timestamp ?? row?.timestamp ?? row?.['@t']; + if (typeof value !== 'string') return null; + const at = Date.parse(value); + return Number.isFinite(at) ? at : null; +} + +function withinInvocation(at: number | null, invocation: CapturedInvocation): boolean { + const start = Date.parse(invocation.startedAt ?? ''), + end = Date.parse(invocation.completedAt ?? ''); + return at !== null && Number.isFinite(at) && Number.isFinite(start) && Number.isFinite(end) && + end >= start && at >= start && at <= end; +} + +/** Pinned CLI file-log prefix and closed DcpExecutor templates; no free-form message is retained. */ +function scopedStopRecord( + line: string, + scoped: readonly string[], + window?: CapturedInvocation, +): DiagnosticRecord | null { + const prefix = + /^\[(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}\.\d{3})\] \[[A-Z]{3,5}\] \[(?:AppHost|DcpExecutor|Aspire\.Hosting\.Dcp\.DcpExecutor)\] (.+)$/ + .exec(line); + if (!prefix) return null; + const at = Date.parse(prefix[1] + 'T' + prefix[2] + 'Z'); + if (!Number.isFinite(at) || window && !withinInvocation(at, window)) return null; + const match = + /^(?:Stopping resource '([^']+)'\.\.\.|Executable '([^']+)' (was stopped\.|is still running; trying again to stop it\.\.\.))$/ + .exec(prefix[3]); + if (!match) return null; + const physical = match[1] ?? match[2]; + const candidates = [...NAMES, ...scoped.slice(0, 16)]; + const logical = candidates.find((name) => + diagnosticResourceName(name, scoped) !== null && + (physical === name || + physical.startsWith(name + '-') && /^[a-z0-9]{8}$/.test(physical.slice(name.length + 1))) + ); + if (!logical) return null; + return { + resourceKind: 'executable', + resourceName: logical, + errorCode: null, + stopState: match[1] ? 'requested' : match[3] === 'was stopped.' ? 'confirmed' : 'not_terminal', + }; +} + +function object(value: unknown): Record | null { + return value !== null && typeof value === 'object' && !Array.isArray(value) + ? value as Record + : null; +} +function records(text: string, scoped: readonly string[] = [], window?: CapturedInvocation) { + const result: DiagnosticRecord[] = []; + let ignored = 0; + for (const line of text.split(/\r?\n/)) { + if (!line.trim()) continue; + let row: Record | null = null; + try { + row = object(JSON.parse(line)); + } catch { /* Free-form text never crosses this boundary. */ } + if (!row) { + const stop = scopedStopRecord(line, scoped, window); + if (stop && result.length < 16) { + result.push(stop); + continue; + } + } + if (window) { + const at = recordTime(row); + if (!withinInvocation(at, window)) { + ignored++; + continue; + } + } + const properties = object(row?.Properties) ?? row; + const kind = properties?.resourceKind ?? properties?.ResourceKind; + const name = properties?.resourceName ?? properties?.ResourceName; + const error = properties?.errorCode ?? properties?.ErrorCode; + const value = { + resourceKind: typeof kind === 'string' && KINDS.has(kind) ? kind : null, + resourceName: diagnosticResourceName(name, scoped), + errorCode: typeof error === 'string' && ERRORS.has(error) ? error : null, + }; + if (Object.values(value).some((v) => v !== null) && result.length < 16) result.push(value); + else ignored++; + } + return { records: result, ignoredLines: ignored }; +} +async function sha(bytes: Uint8Array): Promise { + const copy = new Uint8Array(bytes.length); + copy.set(bytes); + return [...new Uint8Array(await crypto.subtle.digest('SHA-256', copy))] + .map((byte) => byte.toString(16).padStart(2, '0')).join(''); +} +async function textEvidence(text: string, scoped: readonly string[] = []) { + const tail = text.slice(-MAX_BYTES); + const encoded = new TextEncoder().encode(tail); + const bytes = encoded.slice(-MAX_BYTES); + const truncated = tail.length !== text.length || encoded.length !== bytes.length; + return { + totalCharacters: text.length, + readBytes: bytes.length, + truncated, + capturedSha256: await sha(bytes), + ...records(new TextDecoder().decode(bytes), scoped), + }; +} +function logReferences(text: string): string[] { + const references = new Set(); + for ( + const match of text.slice(-MAX_BYTES).matchAll( + /(?:[A-Za-z]:[\\/]|\/)[^\s<>"']*cli_[A-Za-z0-9_-]+\.log/g, + ) + ) { + references.add(match[0]); + if (references.size === 3) break; + } + return [...references]; +} +function inside(path: string, root: string) { + const delta = relative(root, path); + return delta !== '' && !delta.startsWith('..') && !isAbsolute(delta); +} +function secondStamp(iso: string | undefined): string | null { + if (!iso || !Number.isFinite(Date.parse(iso))) return null; + return new Date(iso).toISOString().slice(0, 19).replaceAll('-', '').replaceAll(':', ''); +} + +/** The same identity check is used before and after opening a selected log. */ +export function ownedDiagnosticFile(input: { + readonly file: boolean; + readonly symlink: boolean; + readonly uid: number | null; + readonly expectedUid: number; + readonly path: string; + readonly actualPath: string; + readonly root: string; + readonly actualRoot: string; +}): boolean { + return input.file && !input.symlink && input.uid === input.expectedUid && + input.actualPath === resolve(input.path) && input.actualRoot === resolve(input.root); +} + +/** One exact reference is admitted; no directory listing, home scan or raw body persistence. */ +export async function selectedInvocationLog( + path: string, + root: string, + invocation: CapturedInvocation, + uid: number, + appHost = false, +) { + const name = basename(path), match = CLI_LOG.exec(name); + const start = secondStamp(invocation.startedAt), end = secondStamp(invocation.completedAt); + if (!isAbsolute(path) || !inside(resolve(path), resolve(root))) { + return { status: 'refused' as const, reason: 'outside_log_scope' as const }; + } + if (!(appHost ? APPHOST_LOG.test(name) : match !== null)) { + return { status: 'refused' as const, reason: 'filename_unproven' as const }; + } + if (!appHost && (!start || !end || match![1] < start || match![1] > end)) { + return { status: 'refused' as const, reason: 'outside_invocation_window' as const }; + } + try { + const before = await Deno.lstat(path); + if ( + !ownedDiagnosticFile({ + file: before.isFile, + symlink: before.isSymlink, + uid: before.uid, + expectedUid: uid, + path, + actualPath: await Deno.realPath(path), + root, + actualRoot: await Deno.realPath(root), + }) + ) return { status: 'refused' as const }; + const file = await Deno.open(path, { read: true }); + try { + const opened = await file.stat(); + if (opened.ino !== before.ino || opened.dev !== before.dev || opened.uid !== uid) { + return { status: 'refused' as const }; + } + const size = Math.min(MAX_BYTES, opened.size), bytes = new Uint8Array(size); + await file.seek(Math.max(0, opened.size - size), Deno.SeekMode.Start); + const read = size ? await file.read(bytes) : 0; + const after = await file.stat(); + if ( + read !== size || after.ino !== before.ino || after.dev !== before.dev || + await Deno.realPath(path) !== resolve(path) + ) return { status: 'unreadable' as const }; + const text = new TextDecoder().decode(bytes); + return { + status: 'available' as const, + totalBytes: opened.size, + readBytes: size, + truncated: opened.size > size, + capturedSha256: await sha(bytes), + ...records(text, invocation.scopedResources, appHost ? invocation : undefined), + linkedAppHost: appHost + ? [] + : logReferences(text).filter((value) => APPHOST_LOG.test(basename(value))).slice(0, 2), + }; + } finally { + file.close(); + } + } catch (error) { + return { + status: error instanceof Deno.errors.NotFound ? 'missing' as const : 'unreadable' as const, + }; + } +} + +/** Keep stdout and stderr separately; stderr summaries never erase safe stdout detail. */ +export async function invocationDiagnostic(input: { + readonly invocation: CapturedInvocation; + readonly logRoot: string; + readonly uid: number; + readonly ordinal: number; + readonly operation: 'stop' | 'restart'; + readonly targetMatches: boolean; +}) { + const { invocation } = input; + const candidates = logReferences(invocation.stdout + '\n' + invocation.stderr).filter((path) => + CLI_LOG.test(basename(path)) + ); + const log = !input.targetMatches ? { status: 'refused' as const } : candidates.length !== 1 + ? { + status: candidates.length === 0 + ? 'missing_reference' as const + : 'ambiguous_reference' as const, + } + : await selectedInvocationLog(candidates[0], input.logRoot, invocation, input.uid); + const linked = 'linkedAppHost' in log ? log.linkedAppHost : []; + const linkedLog = linked.length === 1 + ? await selectedInvocationLog(linked[0], input.logRoot, invocation, input.uid, true) + : null; + // Reference paths are consumed only for exact local reads, never serialized into the artifact. + const { linkedAppHost: _paths, ...safeLog } = 'linkedAppHost' in log + ? log + : { ...log, linkedAppHost: [] }; + const { linkedAppHost: _nested, ...safeLinked } = linkedLog && 'linkedAppHost' in linkedLog + ? linkedLog + : { ...linkedLog, linkedAppHost: [] }; + return { + ordinal: input.ordinal, + operation: input.operation, + nativeExit: invocation.process === 'database_cli' ? null : invocation.code, + executorExit: invocation.process === 'database_cli' ? invocation.code : null, + timedOut: invocation.timedOut ?? false, + signalAtSettlement: invocation.signalAtSettlement + ? { + abortRequested: invocation.signalAtSettlement.abortRequested, + deadlineExpired: invocation.signalAtSettlement.deadlineExpired, + } + : null, + process: invocation.process ?? 'aspire', + reportedRestart: invocation.reportedRestart && + diagnosticResourceName(invocation.reportedRestart.resource, invocation.scopedResources) !== + null && + Number.isInteger(invocation.reportedRestart.exit) && invocation.reportedRestart.exit >= 0 && + invocation.reportedRestart.exit <= 255 + ? { resource: invocation.reportedRestart.resource, exit: invocation.reportedRestart.exit } + : null, + targetMatches: input.targetMatches, + stdout: await textEvidence(invocation.stdout, invocation.scopedResources), + stderr: await textEvidence(invocation.stderr, invocation.scopedResources), + log: safeLog, + linkedState: linked.length === 0 + ? 'missing_reference' + : linked.length === 1 + ? 'selected' + : 'ambiguous_reference', + linkedLog: linkedLog ? safeLinked : null, + }; +} + +/** Evidence retention never changes an already-executed invocation's result. */ +export async function withInvocationEvidence( + run: () => Promise, + collect: () => Promise, +): Promise { + try { + return await run(); + } finally { + try { + await collect(); + } catch { + console.warn('Owned invocation diagnostic unavailable; original outcome preserved.'); + } + } +} diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts new file mode 100644 index 0000000000..6b02ad3549 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts @@ -0,0 +1,347 @@ +import { saveOwnedInvocationDiagnostics } from './owned-invocation-diagnostic.ts'; +import { assert, assertEquals, assertRejects } from '@std/assert'; +import { join } from '@std/path'; +import { + invocationDiagnostic, + ownedDiagnosticFile, + selectedInvocationLog, + withInvocationEvidence, +} from './invocation-diagnostic.ts'; +import { stopAndProbe } from './cleanup.ts'; + +const times = { startedAt: '2026-01-01T00:00:00.000Z', completedAt: '2026-01-01T00:00:02.000Z' }; +const safeDetail = JSON.stringify({ + resourceKind: 'container', + resourceName: 'redis', + errorCode: 'in_use', + Config: { Env: ['SECRET_ENV_SENTINEL'] }, + message: 'SECRET_MESSAGE_SENTINEL', +}); + +Deno.test('both output streams retain only safe details; exact linked logs are bounded and private', async () => { + const root = await Deno.makeTempDir(); + try { + const home = join(root, 'home'), logs = join(home, '.aspire', 'logs'); + await Deno.mkdir(logs, { recursive: true }); + await Deno.mkdir(join(root, '.netscript')); + const uid = (await Deno.stat(root)).uid; + if (uid === null) throw new Error('fixture requires filesystem UID'); + const log = join(logs, 'cli_20260101T000001_deadbeef.log'); + const app = join(logs, 'cli_20260101T000000000_detach-child_deadbeef.log'); + await Deno.writeTextFile( + app, + JSON.stringify({ ...JSON.parse(safeDetail), Timestamp: '2026-01-01T00:00:01.000Z' }), + ); + await Deno.writeTextFile(log, safeDetail + '\n' + app + '\nSECRET_LOG_SENTINEL'); + const invocation = { + ...times, + code: 16, + stdout: safeDetail + '\n' + log, + stderr: 'summary SECRET_STDERR_SENTINEL', + }; + const result = await invocationDiagnostic({ + invocation, + logRoot: logs, + uid, + ordinal: 1, + operation: 'stop', + targetMatches: true, + }); + assertEquals(result.nativeExit, 16); + assertEquals(result.stdout.records.length, 1); + assertEquals(result.stderr.records.length, 0); + assertEquals(result.log.status, 'available'); + assert(result.linkedLog && 'status' in result.linkedLog); + assertEquals(result.linkedLog.status, 'available'); + await saveOwnedInvocationDiagnostics({ + projectRoot: root, + appHost: join(root, 'apphost.cs'), + kind: 'cleanup', + home, + uid, + transcripts: [invocation], + survivorCounts: { ownedContainers: 0, foreignContainers: 1, unprovenContainers: 2 }, + }); + const output = await Deno.readTextFile(join(root, '.netscript/e2e-cleanup-diagnostic.json')); + assert(!output.includes('SECRET_')); + assert(!output.includes(log)); + assert(!output.includes(home)); + assert(!output.includes('Config')); + assert(output.includes('in_use')); + assert(output.includes('not_collected')); + await Deno.writeTextFile(log, 'x'.repeat(300000) + '\n' + safeDetail); + const bounded = await selectedInvocationLog(log, logs, invocation, uid); + assertEquals(bounded.status, 'available'); + if (bounded.status === 'available') { + assertEquals(bounded.readBytes, 256 << 10); + assert(bounded.truncated); + } + } finally { + await Deno.remove(root, { recursive: true }); + } +}); + +Deno.test('missing, foreign, escaped, symlink and ambiguous log evidence fail closed', async () => { + const root = await Deno.makeTempDir(); + try { + const uid = (await Deno.stat(root)).uid; + if (uid === null) throw new Error('fixture requires filesystem UID'); + const path = join(root, 'cli_20260101T000001_deadbeef.log'), + invocation = { ...times, code: 1, stdout: '', stderr: '' }; + assertEquals((await selectedInvocationLog(path, root, invocation, uid)).status, 'missing'); + assertEquals( + (await selectedInvocationLog( + join(root, '../cli_20260101T000001_deadbeef.log'), + root, + invocation, + uid, + )).status, + 'refused', + ); + await Deno.writeTextFile(path, safeDetail); + assertEquals((await selectedInvocationLog(path, root, invocation, uid + 1)).status, 'refused'); + const identity = { + file: true, + symlink: false, + uid, + expectedUid: uid, + path, + actualPath: path, + root, + actualRoot: root, + }; + assert(ownedDiagnosticFile(identity)); + assert(!ownedDiagnosticFile({ ...identity, symlink: true })); + assert(!ownedDiagnosticFile({ ...identity, actualPath: join(root, 'different') })); + assert(!ownedDiagnosticFile({ ...identity, actualRoot: join(root, 'different') })); + const missing = await invocationDiagnostic({ + invocation, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: true, + }); + assertEquals(missing.log.status, 'missing_reference'); + const ambiguous = await invocationDiagnostic({ + invocation: { + ...invocation, + stdout: path + '\n' + join(root, 'cli_20260101T000002_cafebabe.log'), + }, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: true, + }); + assertEquals(ambiguous.log.status, 'ambiguous_reference'); + const refused = await invocationDiagnostic({ + invocation: { ...invocation, stdout: path }, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: false, + }); + assertEquals(refused.log.status, 'refused'); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); + +Deno.test('collector rejection cannot mask original failure or turn successful work into failure', async () => { + const original = new Error('original invocation failure'); + let collected = 0; + const error = await assertRejects(() => + withInvocationEvidence(() => Promise.reject(original), () => { + collected++; + return Promise.reject(new Error('SECRET_COLLECTOR')); + }) + ); + assertEquals(error, original); + assertEquals(collected, 1); + assertEquals( + await withInvocationEvidence( + () => Promise.resolve(17), + () => Promise.reject(new Error('SECRET_COLLECTOR')), + ), + 17, + ); +}); + +Deno.test('actual stop-and-probe retains nonzero outcome and exact command count with diagnostic failure', async () => { + const root = await Deno.makeTempDir(); + let retained = 0; + const calls: string[][] = []; + try { + await assertRejects( + () => + stopAndProbe( + join(root, 'apphost.cs'), + root, + false, + join(root, '.netscript/cleanup-private.json'), + { + run: (command, args) => { + calls.push([command, ...args]); + return Promise.resolve( + command === 'aspire' + ? { ...times, code: 16, stdout: safeDetail, stderr: 'original stop failure' } + : { code: 0, stdout: '', stderr: '' }, + ); + }, + diagnostic: (transcripts, evaluation) => { + retained++; + assertEquals(transcripts.length, 1); + assertEquals(transcripts[0].code, 16); + assertEquals(evaluation?.ownedContainers.length, 0); + return Promise.reject(new Error('SECRET_COLLECTOR')); + }, + }, + ), + Error, + 'Aspire stop did not complete: original stop failure', + ); + assertEquals(calls.filter((call) => call[0] === 'aspire').length, 1); + assertEquals(retained, 1); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); + +Deno.test('owned restart evidence reads only the canonical command log and invocation-scoped records from its older linked host log', async () => { + const root = await Deno.makeTempDir(); + try { + const home = join(root, 'home'), logs = join(home, '.aspire', 'logs'); + await Deno.mkdir(logs, { recursive: true }); + await Deno.mkdir(join(root, '.netscript')); + const uid = (await Deno.stat(root)).uid; + assert(uid !== null); + const log = join(logs, 'cli_20260101T230130_deadbeef.log'); + const app = join(logs, 'cli_20260101T230011987_detach-child_deadbeef.log'); + const detail = (at: string) => + JSON.stringify({ + Timestamp: at, + resourceKind: 'executable', + resourceName: 'synthetic-smoke-web', + errorCode: 'in_use', + Config: { Env: ['SECRET_ENV_SENTINEL'] }, + }); + await Deno.writeTextFile( + app, + detail('2026-01-01T23:00:12.000Z') + '\n' + detail('2026-01-01T23:01:35.000Z'), + ); + await Deno.writeTextFile(log, app + '\n' + detail('2026-01-01T23:01:36.000Z')); + const invocation = { + code: 1, + process: 'database_cli' as const, + timedOut: false, + scopedResources: ['synthetic-smoke-web'], + reportedRestart: { resource: 'synthetic-smoke-web', exit: 16 }, + startedAt: '2026-01-01T23:01:18.000Z', + completedAt: '2026-01-01T23:01:47.000Z', + stdout: '', + stderr: log, + }; + await saveOwnedInvocationDiagnostics({ + projectRoot: root, + appHost: join(root, 'apphost.mts'), + kind: 'restart', + home, + uid, + transcripts: [invocation], + }); + const result = JSON.parse( + await Deno.readTextFile(join(root, '.netscript/e2e-restart-diagnostic.json')), + ); + const record = result.commands[0]; + assertEquals(record.log.status, 'available'); + assertEquals(record.reportedRestart, { resource: 'synthetic-smoke-web', exit: 16 }); + assertEquals(record.nativeExit, null); + assertEquals(record.executorExit, 1); + assertEquals(record.linkedLog.status, 'available'); + assertEquals( + record.linkedLog.records.length, + 1, + 'older host records must not become current-invocation evidence', + ); + assertEquals(record.linkedLog.ignoredLines, 1); + assert(!JSON.stringify(result).includes('SECRET_')); + assert(!JSON.stringify(result).includes(home)); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); + +Deno.test('linked host evidence admits only in-window closed stop templates and preserves unknown linkage', async () => { + const root = await Deno.makeTempDir(); + try { + const uid = (await Deno.stat(root)).uid; + assert(uid !== null); + const log = join(root, 'cli_20260101T230130_deadbeef.log'); + const app = join(root, 'cli_20260101T230011987_detach-child_deadbeef.log'); + const line = (at: string, name: string) => + `[2026-01-01 ${at}] [DBG] [DcpExecutor] Executable '${name}-abcdefgh' is still running; trying again to stop it...`; + await Deno.writeTextFile(log, app); + await Deno.writeTextFile( + app, + [ + line('23:00:12.000', 'synthetic-smoke-web'), + line('23:01:35.000', 'synthetic-smoke-web'), + line('23:01:36.000', 'foreign-web'), + 'SECRET_ENV_SENTINEL', + 'Executable without a clock was stopped.', + ].join('\n'), + ); + const invocation = { + code: 1, + stdout: '', + stderr: log, + process: 'database_cli' as const, + scopedResources: ['synthetic-smoke-web'], + startedAt: '2026-01-01T23:01:18.000Z', + completedAt: '2026-01-01T23:01:47.000Z', + timedOut: false, + signalAtSettlement: { abortRequested: false, deadlineExpired: false }, + }; + const result = await invocationDiagnostic({ + invocation, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: true, + }); + assert(result.linkedLog && 'records' in result.linkedLog); + assertEquals(result.linkedLog.records, [{ + resourceKind: 'executable', + resourceName: 'synthetic-smoke-web', + errorCode: null, + stopState: 'not_terminal', + }]); + assertEquals(result.signalAtSettlement, { abortRequested: false, deadlineExpired: false }); + assertEquals(result.timedOut, false); + assertEquals(result.nativeExit, null); + assert(!JSON.stringify(result).includes('SECRET_')); + await Deno.writeTextFile(log, 'no proved linked host reference'); + const unlinked = await invocationDiagnostic({ + invocation, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: true, + }); + assertEquals(unlinked.linkedLog, null); + assertEquals(unlinked.linkedState, 'missing_reference'); + const outside = await selectedInvocationLog( + join(root, 'cli_20260101T230010_deadbeef.log'), + root, + invocation, + uid, + ); + assertEquals(outside, { status: 'refused', reason: 'outside_invocation_window' }); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-staging_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-staging_test.ts new file mode 100644 index 0000000000..8ab4015402 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-staging_test.ts @@ -0,0 +1,103 @@ +import { assert, assertEquals, assertRejects } from '@std/assert'; +import { join } from '@std/path'; +import { + INVOCATION_ARTIFACT_DIRECTORY, + saveOwnedInvocationDiagnostics, +} from './owned-invocation-diagnostic.ts'; + +Deno.test('known nested workspace diagnostics stage flat without visiting unrelated protected data', async () => { + const supplied = Deno.env.get('NETSCRIPT_E2E_DIAGNOSTIC_FIXTURE_ROOT'); + const runner = supplied ?? await Deno.makeTempDir(); + try { + const uid = (await Deno.stat(runner)).uid; + if (uid === null) throw new Error('fixture requires filesystem UID'); + for (const variant of ['skip-seed-handoff', 'drop-link', 'restored']) { + const projectRoot = join(runner, 'documented', variant, 'app'); + await Deno.mkdir(projectRoot, { recursive: true }); + const forbidden = join(projectRoot, '.data'); + if (!supplied) { + await Deno.mkdir(join(forbidden, 'postgres/18/docker'), { recursive: true }); + await Deno.writeTextFile(join(forbidden, 'private.txt'), 'SECRET_UNRELATED_SUBTREE'); + } + if (supplied) { + await assertRejects(async () => { + for await (const _entry of Deno.readDir(forbidden)) { /* negative permission control */ } + }, Deno.errors.NotCapable); + } + await saveOwnedInvocationDiagnostics({ + runnerRoot: runner, + projectRoot, + appHost: join(projectRoot, 'host.mts'), + kind: 'cleanup', + home: join(runner, 'home'), + uid, + transcripts: [{ code: 0, stdout: 'SECRET_RAW_SENTINEL', stderr: 'SECRET_STDERR_SENTINEL' }], + }); + } + const directory = join(runner, INVOCATION_ARTIFACT_DIRECTORY); + const files = []; + for await (const entry of Deno.readDir(directory)) files.push(entry); + assertEquals(files.length, 3); + for (const entry of files) { + assert(entry.isFile); + assert(/^cleanup-[a-f0-9]{64}-diagnostic\.json$/.test(entry.name)); + const text = await Deno.readTextFile(join(directory, entry.name)); + assert(!text.includes('SECRET_')); + assert(!text.includes(runner)); + assert(!text.includes('.data')); + const value = JSON.parse(text); + assertEquals(value.status, 'collected'); + assertEquals(value.commands[0].log.status, 'missing_reference'); + } + } finally { + if (!supplied) await Deno.remove(runner, { recursive: true }); + } +}); +Deno.test('staging refuses a foreign root or target and never broadens discovery', async () => { + const root = await Deno.makeTempDir(); + try { + const runner = join(root, 'runner'), projectRoot = join(root, 'foreign'); + await Deno.mkdir(runner); + await Deno.mkdir(projectRoot); + const uid = (await Deno.stat(root)).uid; + if (uid === null) throw new Error('fixture requires filesystem UID'); + const input = { + runnerRoot: runner, + projectRoot, + appHost: join(projectRoot, 'host.mts'), + kind: 'cleanup' as const, + home: root, + uid, + transcripts: [], + }; + await assertRejects( + () => saveOwnedInvocationDiagnostics(input), + Error, + 'diagnostic_workspace_refused', + ); + await assertRejects( + () => saveOwnedInvocationDiagnostics({ ...input, projectRoot: runner }), + Error, + 'diagnostic_target_refused', + ); + await assertRejects( + () => Deno.stat(join(runner, INVOCATION_ARTIFACT_DIRECTORY)), + Deno.errors.NotFound, + ); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); + +Deno.test('both runtime uploads select only the flat safe diagnostic files', async () => { + const source = await Deno.readTextFile( + new URL('../../../../../../../../../.github/workflows/e2e-cli.yml', import.meta.url), + ); + const paths = source.split(/\r?\n/).map((line) => line.trim()).filter((line) => + line.startsWith('.llm/tmp/') && line.includes('diagnostic') + ); + assertEquals(paths, [ + '.llm/tmp/e2e-invocation-diagnostics/*-diagnostic.json', + '.llm/tmp/e2e-invocation-diagnostics/*-diagnostic.json', + ]); +}); diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts new file mode 100644 index 0000000000..80aff2ead7 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts @@ -0,0 +1,130 @@ +/** Credential-safe artifact construction at known write sites; no directory discovery. */ +import { isAbsolute, join, relative, resolve } from '@std/path'; +import { type CapturedInvocation, invocationDiagnostic } from './invocation-diagnostic.ts'; + +export const INVOCATION_ARTIFACT_DIRECTORY = '.llm/tmp/e2e-invocation-diagnostics'; +const MAX_ARTIFACT_BYTES = 64 << 10; +function within(root: string, path: string): boolean { + const delta = relative(resolve(root), resolve(path)); + return delta !== '' && !delta.startsWith('..') && !isAbsolute(delta); +} +async function hash(text: string): Promise { + return [...new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)))] + .map((value) => value.toString(16).padStart(2, '0')).join(''); +} +async function ownedDirectory(path: string, uid: number): Promise { + const entry = await Deno.lstat(path); + if ( + !entry.isDirectory || entry.isSymlink || entry.uid !== uid || + await Deno.realPath(path) !== resolve(path) + ) throw new Error('diagnostic_directory_refused'); +} +async function runnerArtifactDirectory(root: string, uid: number): Promise { + const resolved = resolve(root); + await ownedDirectory(resolved, uid); + let current = resolved; + for (const name of INVOCATION_ARTIFACT_DIRECTORY.split('/')) { + current = join(current, name); + try { + await Deno.mkdir(current, { mode: 0o700 }); + } catch (error) { + if (!(error instanceof Deno.errors.AlreadyExists)) throw error; + } + await ownedDirectory(current, uid); + } + return current; +} +async function writeArtifact( + parent: string, + path: string, + value: unknown, + uid: number, +): Promise { + // Private function: only the complete explicit safe projection below reaches this boundary. + const text = JSON.stringify(value) + '\n'; + if (new TextEncoder().encode(text).length > MAX_ARTIFACT_BYTES) { + throw new Error('diagnostic_budget_exceeded'); + } + await ownedDirectory(parent, uid); + const temporary = await Deno.makeTempFile({ dir: parent, prefix: '.diagnostic-' }); + try { + await Deno.writeTextFile(temporary, text); + await ownedDirectory(parent, uid); + await Deno.rename(temporary, path); + } finally { + await Deno.remove(temporary).catch(() => {}); + } +} + +/** Collect directly into the owned flat artifact root, never recurse through workspace data. */ +export async function saveOwnedInvocationDiagnostics(input: { + readonly projectRoot: string; + readonly appHost: string; + readonly kind: 'cleanup' | 'restart'; + readonly home: string; + readonly uid: number; + readonly runnerRoot?: string; + readonly transcripts: readonly CapturedInvocation[]; + readonly survivorCounts?: { + readonly ownedContainers: number; + readonly foreignContainers: number; + readonly unprovenContainers: number; + }; +}): Promise { + const { projectRoot, kind } = input; + await ownedDirectory(resolve(projectRoot), input.uid); + const delta = relative(resolve(projectRoot), resolve(input.appHost)); + const targetMatches = delta !== '' && !delta.startsWith('..') && !isAbsolute(delta); + if (!targetMatches) throw new Error('diagnostic_target_refused'); + const workspaceKey = await hash(resolve(projectRoot)); + let parent: string, output: string; + if (input.runnerRoot) { + if (!within(input.runnerRoot, projectRoot)) throw new Error('diagnostic_workspace_refused'); + parent = await runnerArtifactDirectory(input.runnerRoot, input.uid); + output = join(parent, `${kind}-${workspaceKey}-diagnostic.json`); + } else { + parent = join(resolve(projectRoot), '.netscript'); + await ownedDirectory(parent, input.uid); + output = join(parent, `e2e-${kind}-diagnostic.json`); + } + // A failed collector leaves an explicit unavailable record, never a fabricated complete artifact. + await writeArtifact(parent, output, { + schema: 1, + kind, + workspaceKey, + status: 'unavailable', + reason: 'collection_incomplete', + }, input.uid); + const commands = []; + for (const [index, invocation] of input.transcripts.slice(0, 4).entries()) { + commands.push( + await invocationDiagnostic({ + invocation, + ordinal: index + 1, + operation: kind === 'cleanup' ? 'stop' : 'restart', + targetMatches, + logRoot: join(input.home, '.aspire', 'logs'), + uid: input.uid, + }), + ); + } + const counts = input.survivorCounts; + const value = { + schema: 1, + kind, + workspaceKey, + status: 'collected', + target: delta, + targetMatches, + processes: 'not_collected', + survivorCounts: counts + ? { + ownedContainers: counts.ownedContainers, + foreignContainers: counts.foreignContainers, + unprovenContainers: counts.unprovenContainers, + } + : null, + commands, + }; + await writeArtifact(parent, output, value, input.uid); +} diff --git a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts index 7b50084231..fe548da3ba 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts @@ -1,5 +1,7 @@ /** Execute the documented scaffold order without the main suite's repair fixtures. @module */ import { join, resolve } from '@std/path'; +import type { CommandSignalAtSettlement } from '../../../ports/command-executor.ts'; +import { documentedDatabaseGenerateEvidence } from './runtime/evidence/database-generate-diagnostic.ts'; import { buildStreamUrl } from '@netscript/plugin-streams-core'; import { z } from 'zod'; import { @@ -26,22 +28,58 @@ type Outcome = { readonly passed: true; readonly id: string } | { readonly error: unknown; }; -async function command(executable: string, args: readonly string[], cwd: string): Promise { +/** Original direct native command; evidence is observed only after its output settles. */ +export async function documentedCommand( + executable: string, + args: readonly string[], + cwd: string, + afterCommand?: ( + output: { + result: Deno.CommandOutput; + startedAt: string; + completedAt: string; + signalAtSettlement: CommandSignalAtSettlement; + }, + ) => Promise, + execute: (executable: string, options: Deno.CommandOptions) => Promise = ( + program, + options, + ) => new Deno.Command(program, options).output(), +): Promise { const startingAspire = executable === 'aspire' && args[0] === 'start'; const startTimeout = Deno.env.get('ASPIRE_CLI_START_TIMEOUT') ?? String(DEFAULT_ASPIRE_START_TIMEOUT_SECONDS); const ceiling = startingAspire ? Math.max(COMMAND_CEILING_MS, (Number(startTimeout) + 30) * 1_000) : COMMAND_CEILING_MS; - const result = await new Deno.Command(executable, { + const startedAt = new Date().toISOString(); + const commandSignal = AbortSignal.timeout(ceiling); + const result = await execute(executable, { args: [...args], cwd, stdin: 'null', stdout: 'piped', stderr: 'piped', - signal: AbortSignal.timeout(ceiling), + signal: commandSignal, ...(startingAspire ? { env: { ASPIRE_CLI_START_TIMEOUT: startTimeout } } : {}), - }).output(); + }); + const signalAtSettlement = { + abortRequested: commandSignal.aborted, + deadlineExpired: commandSignal.aborted && commandSignal.reason instanceof DOMException && + commandSignal.reason.name === 'TimeoutError', + }; + if (afterCommand) { + try { + await afterCommand({ + result, + startedAt, + completedAt: new Date().toISOString(), + signalAtSettlement, + }); + } catch { + console.warn('Documented command diagnostic collection unavailable'); + } + } const stdout = new TextDecoder().decode(result.stdout); if (!result.success) { throw new Error( @@ -53,6 +91,45 @@ async function command(executable: string, args: readonly string[], cwd: string) return stdout; } +/** The actual walkthrough call site, shared with inert command-boundary controls. */ +export function documentedScaffoldCommand( + words: readonly string[], + args: readonly string[], + input: { + cwd: string; + cliEntrypoint: string; + projectRoot: string; + appHost: string; + repoRoot: string; + }, + seams: { + execute?: Parameters[4]; + collect?: Parameters[2]; + } = {}, +): Promise { + return documentedCommand( + words[0] === 'netscript' ? Deno.execPath() : 'aspire', + words[0] === 'netscript' + ? [ + 'run', + '-A', + ...(input.cliEntrypoint.startsWith('jsr:@netscript/cli@') + ? ['--minimum-dependency-age=0'] + : []), + input.cliEntrypoint, + ...args, + ] + : args, + input.cwd, + documentedDatabaseGenerateEvidence(words, { + projectRoot: input.projectRoot, + appHost: input.appHost, + runnerRoot: input.repoRoot, + }, seams.collect), + seams.execute, + ); +} + async function responseJson(url: string | URL): Promise { const response = await fetch(url, { signal: AbortSignal.timeout(10_000) }); if (!response.ok) { @@ -120,7 +197,7 @@ async function workerPid(appHost: string, cwd: string): Promise { properties: z.record(z.string(), z.unknown()), })), }).parse(JSON.parse( - await command('aspire', [ + await documentedCommand('aspire', [ 'describe', '--apphost', appHost, @@ -140,16 +217,18 @@ async function workerPid(appHost: string, cwd: string): Promise { async function cleanup(repoRoot: string, projectRoot: string): Promise { const receiptPath = join(projectRoot, '.netscript/e2e-cleanup.json'); - await command(Deno.execPath(), [ + await documentedCommand(Deno.execPath(), [ 'run', '--allow-read', '--allow-write', '--allow-run=aspire,docker', + '--allow-env=HOME,USERPROFILE', join(repoRoot, 'packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts'), join(projectRoot, 'aspire/apphost.mts'), projectRoot, 'true', receiptPath, + repoRoot, ], projectRoot); const receipt = z.object({ evaluation: z.object({ @@ -218,7 +297,7 @@ async function runVariant( await Deno.writeTextFile(runtime, broken); } if (words[0] === 'netscript' && args[0] === 'db' && args[1] === 'seed') { - await command('aspire', [ + await documentedCommand('aspire', [ 'wait', 'workers', '--status', @@ -233,21 +312,13 @@ async function runVariant( beforeSeedPid = await workerPid(appHost, cwd); } if (words[0] === 'aspire' && args[0] === 'start') appHostStarted = true; - await command( - words[0] === 'netscript' ? Deno.execPath() : 'aspire', - words[0] === 'netscript' - ? [ - 'run', - '-A', - ...(cliEntrypoint.startsWith('jsr:@netscript/cli@') - ? ['--minimum-dependency-age=0'] - : []), - cliEntrypoint, - ...args, - ] - : args, + await documentedScaffoldCommand(words, args, { cwd, - ); + cliEntrypoint, + projectRoot, + appHost, + repoRoot, + }); } const seed = await outcome(() => seedExecution(appHost, projectRoot)); const stream = await outcome(() => activity(appHost, projectRoot)); diff --git a/packages/cli/e2e/src/domain/gate-definition.ts b/packages/cli/e2e/src/domain/gate-definition.ts index 74cdffa618..1609086549 100644 --- a/packages/cli/e2e/src/domain/gate-definition.ts +++ b/packages/cli/e2e/src/domain/gate-definition.ts @@ -1,7 +1,7 @@ import type { Evidence } from './evidence.ts'; import type { RunContext } from './run-context.ts'; import type { GateId, GatePhase } from './cli-surface.ts'; -import type { CommandOutputMode } from '../ports/command-executor.ts'; +import type { CommandOutputMode, CommandResult } from '../ports/command-executor.ts'; import type { ExecutionPlatform } from './platform.ts'; import type { HttpExchangeContract } from './http-contract.ts'; @@ -43,6 +43,14 @@ export type CommandFactory = (context: RunContext) => readonly string[]; /** Resolve a working directory from the current run context. */ export type WorkingDirectoryFactory = (context: RunContext) => string; +/** Evidence from the original awaited executor; observers never own another process. */ +export interface CommandObservation { + readonly context: RunContext; + readonly result: CommandResult; + readonly startedAt: string; + readonly completedAt: string; +} + /** Resolve an HTTP URL from the current run context. */ export type UrlFactory = (context: RunContext) => string; @@ -85,6 +93,8 @@ export interface CommandGateDefinition extends BaseGateDefinition { readonly timeoutMs?: number; /** Stable failure class for commands whose boundary is known before execution. */ readonly failureClass?: GateFailureClass; + /** Optional evidence only; a failed observer must preserve the original command result. */ + readonly afterCommand?: (observation: CommandObservation) => Promise; } /** diff --git a/packages/cli/e2e/src/ports/command-executor.ts b/packages/cli/e2e/src/ports/command-executor.ts index a7290cc023..9f8f92172a 100644 --- a/packages/cli/e2e/src/ports/command-executor.ts +++ b/packages/cli/e2e/src/ports/command-executor.ts @@ -10,6 +10,12 @@ export interface CommandRequest { readonly failureHint?: string; } +/** Actual existing cancellation state, sampled immediately after native settlement. */ +export interface CommandSignalAtSettlement { + readonly abortRequested: boolean; + readonly deadlineExpired: boolean; +} + /** Captured subprocess result. */ export interface CommandResult { readonly command: readonly string[]; @@ -18,6 +24,7 @@ export interface CommandResult { readonly stdout: string; readonly stderr: string; readonly timedOut: boolean; + readonly signalAtSettlement?: CommandSignalAtSettlement; } /** Port for running external commands. */ diff --git a/packages/cli/e2e/tests/adapters/commands/deno-command-adapter_test.ts b/packages/cli/e2e/tests/adapters/commands/deno-command-adapter_test.ts new file mode 100644 index 0000000000..2c61c56e49 --- /dev/null +++ b/packages/cli/e2e/tests/adapters/commands/deno-command-adapter_test.ts @@ -0,0 +1,61 @@ +import { assertEquals } from '@std/assert'; +import { DenoCommandAdapter } from '../../../src/adapters/commands/deno-command-adapter.ts'; + +for (const outputMode of ['capture', 'discard'] as const) { + Deno.test(`native ${outputMode} settlement retains the actual deadline state even if output resolves`, async () => { + let calls = 0; + const status = (options: Deno.CommandOptions): Promise => { + calls++; + return new Promise((resolve) => + options.signal!.addEventListener( + 'abort', + () => resolve({ code: 0, success: true, signal: null }), + { once: true }, + ) + ); + }; + const adapter = new DenoCommandAdapter({ + capture: async (_command, options) => ({ + ...await status(options), + stdout: new Uint8Array(), + stderr: new Uint8Array(), + }), + status: (_command, options) => status(options), + }); + const result = await adapter.run({ + command: ['inert-native'], + cwd: '.', + timeoutMs: 1, + outputMode, + }); + assertEquals(calls, 1); + assertEquals(result.code, 0); + assertEquals(result.signalAtSettlement, { abortRequested: true, deadlineExpired: true }); + assertEquals(result.timedOut, true, 'resolved output does not erase an observed deadline'); + }); +} +Deno.test('native nonzero and local exception do not imply a deadline or an observed child exit', async () => { + const native = { + capture: () => + Promise.resolve({ + code: 16, + success: false, + signal: null, + stdout: new Uint8Array(), + stderr: new Uint8Array(), + }), + status: () => Promise.resolve({ code: 16, success: false, signal: null }), + }; + const result = await new DenoCommandAdapter(native).run({ command: ['inert-native'], cwd: '.' }); + assertEquals(result.code, 16); + assertEquals(result.timedOut, false); + assertEquals(result.signalAtSettlement, { abortRequested: false, deadlineExpired: false }); + const failed = await new DenoCommandAdapter({ + ...native, + capture: () => Promise.reject(new Error('fixture-local-failure')), + }) + .run({ command: ['inert-native'], cwd: '.' }); + assertEquals(failed.code, 124); + assertEquals(failed.timedOut, false); + assertEquals(failed.signalAtSettlement, { abortRequested: false, deadlineExpired: false }); +}); diff --git a/packages/kv/README.md b/packages/kv/README.md index 0480e8b08d..1cefbfeee3 100644 --- a/packages/kv/README.md +++ b/packages/kv/README.md @@ -19,6 +19,24 @@ The watch capability is the differentiator: `watch` and `watchPrefix` turn the s source, streaming typed change events as keys are written — the primitive NetScript's own reactive features build on. +## Redis atomic confirmation and recovery + +`atomic()` confirms every queued command before returning `ok: true` or publishing watch changes. A +null Redis `EXEC` response is an optimistic conflict and retains bounded conflict retries. A failed +version check returns `ok: false` without executing mutations. + +Redis can apply other commands in a transaction even when one command fails. A rejected EXEC, +command error, or malformed receipt throws `KvAtomicCommitUnconfirmedError`, exported from +`@netscript/kv`. Its payload-free `reason` is `command_failed`, `malformed_result`, or +`execution_unconfirmed`, and `possiblyApplied` is true. This is not a rollback or harmless +contention result. Reconcile expected versions and durable identities before retrying, especially +for non-idempotent mutations. Applications that advance source cursors need discoverable recovery +intent before the mutation batch, since an intent written only inside that batch can also fail. + +An `ok: true` result confirms data mutation, not receipt of watch notifications. A later watch +publication failure does not undo or automatically replay committed data. Work that requires durable +delivery must use its delivery receipts and reconciliation separately from watch hints. + ## Why teams use it - **One contract, interchangeable backends** — `KvStore` and `WatchableKv` give every adapter the @@ -83,34 +101,34 @@ for await (const events of kv.watch([['users', 'alice']])) { ## Ordered listing and cursor pages -`list({ prefix, start, end, limit, reverse })` returns descendants of `prefix` in global key -order. The prefix key itself is excluded. `start` is an exclusive lower bound and `end` an -exclusive upper bound in either direction; `limit` counts entries after filtering. Advance a -forward cursor with `start: lastEntry.key`; advance a reverse cursor with `end: lastEntry.key`. -The kvdex bridge presents native Deno selectors, whose `start` is inclusive. It translates that -boundary explicitly while direct `KvStore.list` calls retain the exclusive contract above. - -Redis has no maintained ordering index. Each output window scans the whole Redis database -(including keys outside the selected namespace/prefix) and keeps -only the next K distinct matching key names in a heap, then fetches those values with `MGET`. -K is at most `REDIS_MGET_BATCH_SIZE` (default 500), or the remaining limit if smaller. A page of -up to K live entries usually needs one full SCAN cycle, even with `limit: 1`. Missing/expired or -malformed values do not consume the limit; listing advances past examined keys and refills. - -Retained candidate memory is O(K), plus one SCAN reply and one MGET reply. Redis SCAN's COUNT -is a work hint, so it does not strictly bound an individual server reply. For N scanned names, -selection costs O(N log K) per window. Larger or unlimited lists rescan for successive windows, -trading O(N × ceil(examined candidates / K) × log K) work for memory independent of prefix size. -This avoids adding an index that would need backfill and changes to writes, expiry, and atomic -transactions. Prefix watch discovery uses a private unordered single-pass scan instead, preserving -one SCAN cycle per baseline or poll. Neither listing nor watches promise snapshot isolation across -concurrent writes. +`list({ prefix, start, end, limit, reverse })` returns descendants of `prefix` in global key order. +The prefix key itself is excluded. `start` is an exclusive lower bound and `end` an exclusive upper +bound in either direction; `limit` counts entries after filtering. Advance a forward cursor with +`start: lastEntry.key`; advance a reverse cursor with `end: lastEntry.key`. The kvdex bridge +presents native Deno selectors, whose `start` is inclusive. It translates that boundary explicitly +while direct `KvStore.list` calls retain the exclusive contract above. + +Redis has no maintained ordering index. Each output window scans the whole Redis database (including +keys outside the selected namespace/prefix) and keeps only the next K distinct matching key names in +a heap, then fetches those values with `MGET`. K is at most `REDIS_MGET_BATCH_SIZE` (default 500), +or the remaining limit if smaller. A page of up to K live entries usually needs one full SCAN cycle, +even with `limit: 1`. Missing/expired or malformed values do not consume the limit; listing advances +past examined keys and refills. + +Retained candidate memory is O(K), plus one SCAN reply and one MGET reply. Redis SCAN's COUNT is a +work hint, so it does not strictly bound an individual server reply. For N scanned names, selection +costs O(N log K) per window. Larger or unlimited lists rescan for successive windows, trading O(N × +ceil(examined candidates / K) × log K) work for memory independent of prefix size. This avoids +adding an index that would need backfill and changes to writes, expiry, and atomic transactions. +Prefix watch discovery uses a private unordered single-pass scan instead, preserving one SCAN cycle +per baseline or poll. Neither listing nor watches promise snapshot isolation across concurrent +writes. Existing storage-key encoding limitations remain: Redis colon-separated keys coerce all-digit -segments to numbers and do not preserve arbitrary key-part types. Memory compares parts as -strings, while native Deno KV has typed ordering. The shared pagination contract tests use -round-trippable, non-numeric ASCII string parts (for example `k0001`); they do not establish -universal typed-key parity. +segments to numbers and do not preserve arbitrary key-part types. Memory compares parts as strings, +while native Deno KV has typed ordering. The shared pagination contract tests use round-trippable, +non-numeric ASCII string parts (for example `k0001`); they do not establish universal typed-key +parity. ## Startup consistency @@ -168,18 +186,18 @@ cleanly, while an actual adapter failure still rejects iteration. Fixed-key Redis watches restore live subscriptions after a lost connection, including when the driver has exhausted its native reconnect attempts. After Redis acknowledges each restored -subscription, the watch rereads its keys and emits current state. Missing keys appear as -`delete` events with null values. Recovery batches have no `initial` marker and may repeat -unchanged values. Intermediate mutations during an outage can coalesce: this is a current-state -watch, not a durable event log. No idle keyspace scan is added to fixed-key watches. - -Recovery has a 30-second total budget from disconnect, including connection attempts, -subscription acknowledgements and state rereads. A watch that cannot recover rejects iteration -with `KvConnectionError`, preserving the cause. Import `KvError`, `KvConnectionError` or -`KvClosedError` from `@netscript/kv` or `@netscript/kv/redis` to catch them. Closing an adapter -rejects its active watches with `KvClosedError`; aborting a watch's own signal completes it -normally. Releasing one watch preserves its siblings, and releasing the last watch cancels its -pending recovery. A new watch can start a fresh recovery after failed watches have ended. +subscription, the watch rereads its keys and emits current state. Missing keys appear as `delete` +events with null values. Recovery batches have no `initial` marker and may repeat unchanged values. +Intermediate mutations during an outage can coalesce: this is a current-state watch, not a durable +event log. No idle keyspace scan is added to fixed-key watches. + +Recovery has a 30-second total budget from disconnect, including connection attempts, subscription +acknowledgements and state rereads. A watch that cannot recover rejects iteration with +`KvConnectionError`, preserving the cause. Import `KvError`, `KvConnectionError` or `KvClosedError` +from `@netscript/kv` or `@netscript/kv/redis` to catch them. Closing an adapter rejects its active +watches with `KvClosedError`; aborting a watch's own signal completes it normally. Releasing one +watch preserves its siblings, and releasing the last watch cancels its pending recovery. A new watch +can start a fresh recovery after failed watches have ended. Prefix watches share subscription restoration and typed failure/close handling. Their existing `pollInterval` still controls discovery of keys changed without a delivered publication. diff --git a/packages/kv/adapters/redis.adapter.ts b/packages/kv/adapters/redis.adapter.ts index cc4eeebbec..e80b18943a 100644 --- a/packages/kv/adapters/redis.adapter.ts +++ b/packages/kv/adapters/redis.adapter.ts @@ -15,7 +15,11 @@ */ import { createWatchHandle } from '../application/watch-handle.ts'; -import { KvConnectionError, KvError } from '../application/errors.ts'; +import { + KvAtomicCommitUnconfirmedError, + KvConnectionError, + KvError, +} from '../application/errors.ts'; import { createPackageLogger } from '@netscript/logger'; import { combineAtomicValue } from '../application/atomic-combine.ts'; import { generateVersionstamp, keyHasPrefix, keyToString } from '../application/keys.ts'; @@ -41,6 +45,7 @@ import { type WatchMessage, } from './redis/codec.ts'; import { RedisConnectionManager } from './redis/connection.ts'; +import { assertRedisAtomicResult } from './redis/atomic-result.ts'; import { listEntries, scanEntries } from './redis/list-entries.ts'; import { keyToRedisKey } from './redis/serialization.ts'; import { WatchBatchQueue } from './redis/watch-batch-queue.ts'; @@ -353,14 +358,25 @@ export class RedisKvAdapter implements WatchableKv { const multi = client.multi(); const changes = this.queueMutations(multi, mutations, current, versionstamp); - if ((await multi.exec()) === null) { + let executed: unknown; + try { + executed = await multi.exec(); + } catch { + throw new KvAtomicCommitUnconfirmedError('execution_unconfirmed'); + } + if (executed === null) { return 'conflict'; } + assertRedisAtomicResult(executed, mutations.length); await this.publishChanges(changes, versionstamp); return { ok: true, versionstamp }; } catch (error: unknown) { - await client.unwatch(); + try { + await client.unwatch(); + } catch { + logger.warn('Redis atomic cleanup failed after an operation failure'); + } throw error; } } @@ -662,10 +678,8 @@ export class RedisKvAdapter implements WatchableKv { pipeline.publish(this.getWatchChannel(), encodeEnvelope({ ...message })); } await pipeline.exec(); - } catch (error: unknown) { - logger.warn('Failed to publish Redis KV watch event', { - error: error instanceof Error ? error.message : String(error), - }); + } catch { + logger.warn('Redis KV write committed but watch publication is unconfirmed'); } } diff --git a/packages/kv/adapters/redis/atomic-result.ts b/packages/kv/adapters/redis/atomic-result.ts new file mode 100644 index 0000000000..83187bece5 --- /dev/null +++ b/packages/kv/adapters/redis/atomic-result.ts @@ -0,0 +1,31 @@ +/** Validate the complete Redis EXEC receipt before certifying a commit. */ +import { KvAtomicCommitUnconfirmedError } from '../../application/errors.ts'; + +/** + * Require one successful command tuple for every queued mutation. + * + * Null EXEC is handled by the caller as an optimistic conflict. A null detail + * inside a successful tuple is valid; only its explicit null error slot proves + * command success. ioredis wraps a failed command as a one-element `[Error]` + * tuple. A command failure can leave other mutations applied. + * + * @param result - Non-null result returned by the transport. + * @param commands - Exact number of queued Redis commands. + * @throws {KvAtomicCommitUnconfirmedError} On missing or failed confirmation. + */ +export function assertRedisAtomicResult(result: unknown, commands: number): void { + if (!Array.isArray(result) || result.length !== commands) { + throw new KvAtomicCommitUnconfirmedError('malformed_result'); + } + for (const command of result) { + if (!Array.isArray(command) || command.length < 1 || command.length > 2) { + throw new KvAtomicCommitUnconfirmedError('malformed_result'); + } + if (command[0] instanceof Error) { + throw new KvAtomicCommitUnconfirmedError('command_failed'); + } + if (command.length !== 2 || command[0] !== null) { + throw new KvAtomicCommitUnconfirmedError('malformed_result'); + } + } +} diff --git a/packages/kv/application/errors.ts b/packages/kv/application/errors.ts index 5e5ffacb71..28d21420fb 100644 --- a/packages/kv/application/errors.ts +++ b/packages/kv/application/errors.ts @@ -23,3 +23,30 @@ export class KvConnectionError extends KvError {} /** An operation or active watch failed because its adapter was closed. */ export class KvClosedError extends KvError {} + +/** Why a Redis transaction cannot be confirmed after EXEC was attempted. */ +export type KvAtomicCommitUnconfirmedReason = + | 'command_failed' + | 'malformed_result' + | 'execution_unconfirmed'; + +/** + * An attempted transaction may have applied only some mutations. + * + * This is not a failed version check. Do not retry non-idempotent mutations + * without reconciling durable state. Command payloads and original errors are + * deliberately excluded from this public failure. + */ +export class KvAtomicCommitUnconfirmedError extends KvError { + /** Some or all mutations may already be durable. */ + readonly possiblyApplied = true; + + /** + * Create a payload-free transaction uncertainty failure. + * + * @param reason - Safe classification of the missing confirmation. + */ + constructor(readonly reason: KvAtomicCommitUnconfirmedReason) { + super('KV atomic commit is unconfirmed; mutations may have applied.'); + } +} diff --git a/packages/kv/mod.ts b/packages/kv/mod.ts index 2c0426754d..707e9e1ce1 100644 --- a/packages/kv/mod.ts +++ b/packages/kv/mod.ts @@ -40,7 +40,13 @@ export type { export { isWatchable } from './types/mod.ts'; -export { KvClosedError, KvConnectionError, KvError } from './application/errors.ts'; +export { + KvAtomicCommitUnconfirmedError, + type KvAtomicCommitUnconfirmedReason, + KvClosedError, + KvConnectionError, + KvError, +} from './application/errors.ts'; export { DenoKvAdapter } from './adapters/deno-kv.adapter.ts'; export { MemoryKvAdapter } from './adapters/memory.adapter.ts'; diff --git a/packages/kv/tests/redis-atomic-outcomes_test.ts b/packages/kv/tests/redis-atomic-outcomes_test.ts new file mode 100644 index 0000000000..d0185ea4df --- /dev/null +++ b/packages/kv/tests/redis-atomic-outcomes_test.ts @@ -0,0 +1,232 @@ +/** Owning Redis adapter tests; the command transport is inert before any operation. */ +import { assert, assertEquals, assertRejects } from '@std/assert'; +import { RedisKvAdapter } from '../redis.ts'; +import type { AtomicMutation } from '../types/kv-store.ts'; + +type Reply = (commands: number, attempt: number) => unknown; +/** ioredis5.11.1 built/utils/index.js51–68: transaction.js passes EXEC through wrapMultiResult. + * The pinned normalizer wraps Error as [error], and ordinary details as [null, detail]. + * This source-proven fixture models that normalization before the actual owning adapter runs. + */ +function ioredisExecReplies(values: readonly unknown[]): unknown[] { + return values.map((item) => item instanceof Error ? [item] : [null, item]); +} +function fixture( + reply: Reply, + options: { cleanupFails?: boolean; publicationFails?: boolean } = {}, +) { + let attempts = 0; + let notifications = 0; + let unwatches = 0; + let closed = false; + const client = { + watch: () => Promise.resolve('OK'), + unwatch() { + unwatches++; + return options.cleanupFails + ? Promise.reject(new Error('synthetic cleanup failure')) + : Promise.resolve('OK'); + }, + mget: (...keys: string[]) => Promise.resolve(keys.map(() => null)), + multi() { + let commands = 0; + const multi = { + set() { + commands++; + return multi; + }, + psetex() { + commands++; + return multi; + }, + del() { + commands++; + return multi; + }, + exec() { + attempts++; + return Promise.resolve().then(() => reply(commands, attempts)); + }, + }; + return multi; + }, + pipeline() { + let commands = 0; + const pipeline = { + publish() { + notifications++; + commands++; + return pipeline; + }, + exec: () => + options.publicationFails + ? Promise.reject(new Error('synthetic publication failure')) + : Promise.resolve(Array.from({ length: commands }, () => [null, 1])), + }; + return pipeline; + }, + }; + const kv = new RedisKvAdapter({ url: 'redis://fixture.invalid', namespace: 'atomic-outcomes' }); + Object.defineProperty(kv, 'connection', { + value: { + ensureClient: () => Promise.resolve(client), + close: () => { + closed = true; + return Promise.resolve(); + }, + }, + }); + return { + kv, + attempts: () => attempts, + notifications: () => notifications, + unwatches: () => unwatches, + closed: () => closed, + }; +} +const mutations: AtomicMutation[] = [ + { type: 'set', key: ['first'], value: 'synthetic value' }, + { type: 'delete', key: ['middle'] }, + { type: 'set', key: ['last'], value: 1, expireIn: 1000 }, +]; +const success: Reply = (count) => Array.from({ length: count }, () => [null, 'OK']); + +Deno.test('pinned ioredis normalization keeps one-element Error tuples and null success details', () => { + const failure = new Error('synthetic'); + assertEquals(ioredisExecReplies(['OK', failure, null]), [[null, 'OK'], [failure], [null, null]]); +}); + +Deno.test('ioredis command failure survives failed task cleanup without notification or retry', async () => { + const f = fixture(() => ioredisExecReplies([new Error('synthetic private detail'), 'OK', 'OK']), { + cleanupFails: true, + }); + try { + const error = await assertRejects(() => f.kv.atomic([], mutations)); + assert(error instanceof Error); + assertEquals(Reflect.get(error, 'reason'), 'command_failed'); + assertEquals(Reflect.get(error, 'cause'), undefined); + assertEquals(f.notifications(), 0); + assertEquals(f.attempts(), 1); + } finally { + await f.kv.close(); + } +}); + +Deno.test('Redis atomic validates all successful command tuples before notifying', async () => { + const f = fixture((count) => Array.from({ length: count }, () => [null, null])); + try { + assert((await f.kv.atomic([], mutations)).ok); + assertEquals(f.attempts(), 1); + assertEquals(f.notifications(), 3); + } finally { + await f.kv.close(); + } + assert(f.closed()); +}); + +Deno.test('Redis null EXEC retries conflict and check mismatch never executes', async () => { + const f = fixture((count, attempt) => attempt === 1 ? null : success(count, attempt)); + try { + assert((await f.kv.atomic([], mutations)).ok); + assertEquals(f.attempts(), 2); + assertEquals(f.notifications(), 3); + assertEquals(await f.kv.atomic([{ key: ['absent'], versionstamp: 'expected' }], mutations), { + ok: false, + }); + assertEquals(f.attempts(), 2); + } finally { + await f.kv.close(); + } +}); + +Deno.test('Redis repeated null EXEC retains bounded conflict failure', async () => { + const f = fixture(() => null); + try { + assertEquals(await f.kv.atomic([], mutations), { ok: false }); + assertEquals(f.attempts(), 5); + assertEquals(f.notifications(), 0); + } finally { + await f.kv.close(); + } +}); + +for (const failed of [0, 1, 2]) { + Deno.test(`Redis command failure at position ${failed} is unconfirmed without retry or notification`, async () => { + const f = fixture((count) => + ioredisExecReplies(Array.from( + { length: count }, + (_, i) => i === failed ? new Error('synthetic command payload must remain private') : 'OK', + )) + ); + try { + const error = await assertRejects(() => f.kv.atomic([], mutations)); + assert(error instanceof Error); + assertEquals(error.name, 'KvAtomicCommitUnconfirmedError'); + assertEquals(Reflect.get(error, 'reason'), 'command_failed'); + assertEquals(Reflect.get(error, 'possiblyApplied'), true); + assertEquals(Reflect.get(error, 'cause'), undefined); + assertEquals(error.message.includes('synthetic command payload'), false); + assertEquals(f.attempts(), 1); + assertEquals(f.notifications(), 0); + } finally { + await f.kv.close(); + } + }); +} + +for ( + const [label, result] of [ + ['missing', undefined], + ['nonarray', {}], + ['short', [[null, 'OK']]], + ['long', [[null, 1], [null, 1], [null, 1], [null, 1]]], + ['malformed tuple', [[null, 1], [null], [null, 1]]], + ['missing error slot', [[null, 1], [undefined, 'OK'], [null, 1]]], + ['non-error singleton', [[null, 1], ['unexpected'], [null, 1]]], + ['non-error error slot', [[null, 1], ['unexpected', null], [null, 1]]], + ['oversized error tuple', [[null, 1], [new Error('synthetic'), null, null], [null, 1]]], + ] as const +) { + Deno.test(`Redis ${label} EXEC result cannot certify a complete commit`, async () => { + const f = fixture(() => result); + try { + const error = await assertRejects(() => f.kv.atomic([], mutations)); + assert(error instanceof Error); + assertEquals(error.name, 'KvAtomicCommitUnconfirmedError'); + assertEquals(Reflect.get(error, 'reason'), 'malformed_result'); + assertEquals(f.attempts(), 1); + assertEquals(f.notifications(), 0); + } finally { + await f.kv.close(); + } + }); +} + +Deno.test('Redis rejected EXEC stays unconfirmed when unwatch cleanup also fails', async () => { + const f = fixture(() => { + throw new Error('synthetic execution rejection'); + }, { cleanupFails: true }); + try { + const error = await assertRejects(() => f.kv.atomic([], mutations)); + assert(error instanceof Error); + assertEquals(error.name, 'KvAtomicCommitUnconfirmedError'); + assertEquals(Reflect.get(error, 'reason'), 'execution_unconfirmed'); + assertEquals(f.attempts(), 1); + assertEquals(f.unwatches(), 1); + assertEquals(f.notifications(), 0); + } finally { + await f.kv.close(); + } + assert(f.closed()); +}); + +Deno.test('Redis committed data is not replayed when later notification fails', async () => { + const f = fixture(success, { publicationFails: true }); + try { + assert((await f.kv.atomic([], mutations)).ok); + assertEquals(f.attempts(), 1); + assertEquals(f.notifications(), 3); + } finally { + await f.kv.close(); + } +}); diff --git a/packages/kv/types/common.ts b/packages/kv/types/common.ts index 46b3c347bf..9bbebf4c02 100644 --- a/packages/kv/types/common.ts +++ b/packages/kv/types/common.ts @@ -139,7 +139,12 @@ export interface AtomicCheck { * Result returned from an atomic operation. */ export interface AtomicResult { - /** Whether the operation was successful */ + /** + * Whether every mutation was confirmed committed. This does not confirm + * delivery of watch notifications. Redis may instead throw a payload-free + * KvAtomicCommitUnconfirmedError when mutations may have partially applied; + * callers must reconcile rather than treating that as an ordinary false check. + */ ok: boolean; /** New versionstamp if successful */ versionstamp?: string; diff --git a/packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts b/packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts index a2dce334df..5ee5095e4e 100644 --- a/packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts +++ b/packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts @@ -187,7 +187,7 @@ export const EXPORT_SURFACE_ROWS: readonly (readonly [string, string, string, st ["fresh-ui","./tokens","rVhtbxs3Ev4rAyFAUkAN0gL3xck5SGy19V1jG5bh3iEJCmo5KxHmknskV5ZQ3H8/zJC7y5Wo1Af0k7V8GT6ceeaZoT9/nn24vf39/uafi+vff7r6dbGczWfCe3ThJ7VuxL19RHMtGvSz+WzVKS15hL4+dkoH/prNZxJr0aXPpe1cxRsu0au16dcsdq11AaOF2XyG/D0e87EzUuNsPuOhC6s1VkFZWlpYVA9D43m87EE4JVa8RjUnTri9WzxcLX47uPcdequ36KLB2XwWpy8X18ur+yteEkdu7xbLxf34vbz4ZfEpzsdjlJY3LWH3k7E79J0O/dCFNQF34aYLbTcMXqLxKuzHT6e2Inkhjtiqa9AMGz5hEFIEMXyr3fGmW4cehy39PfvvZbXBBoevjZD26djG6Gb+fBC6w9nX+eeZwxodGvZY3Zk+ZtlPZQK6WhyuyIf/miXZcI4q7Fv8oJUg8NuRHvmSbPjUmfnv3GL++zl7n2Pzz9dMPA/HSdy7AorZ/Koa0sufQWcejX0y353B1irJCrA3FQwmssR/Jdz6Tb7j1tlGeXx3yPLzHDmMYgG4C2ikh4kcwB/gUEhr9B5cpKc8g5Fob8dpzzxchr3G92fgg1NmfTR9Y/T+/RmsrNUoDPw3d0hBq159lw4bST5iz1Qsh/mCYlEA8GJLgE+AfyHRV06xNpTQv2DveArL+8HLDH/Ec9JxJwAlPEfjlfcPwhUmWhE2w+HZ+AZ3Jcy10Holqsdhburussy/UqbtQk6kgkyPdz4oCfmtRyYXsDVW4kjwiVNivvtTXj6Ekx+5RUchOoMvsx/f/Pi31z+8+TLLHVvIrSOG+injpj47Km6n8vUkaSelMMduRFMiQ+ROAWxl27IHKytxuTdBFEnxJzxnTvozuEsD7+6wsk6+iwvn/XHn51O/lAv6MZfSr1zjoVzz6d4wLfzw92x/ZY0PcNAIlA847A3yralDyDeOsTpqGiZJLdwawygGeZ463Cp88qPQTSc97zvyvd2ic0qSek46imOKvi9wtAQ7Kn6Oulb6W+GNf8/PJ3TibqhItXiXBCb2MiUsk4YqR1PYP6E4tT/9Vfkjm3X4nw59QJk6s95p8SvPIK6Pp+88lsDEaqZebmxCvHy2b8UmCw4u30cR/oDPj7jv4/71lL5NmsfcWfZRV5si32LBKFGq8v5ZlSHfIgKurdsXT5J05ZGggwNy2yQCJ7sAnj1ZQY8b5dwBj8pIkvZG7Q5l3ZbK5ZOicnk8jGq9CWdgumaFLudbKyr8JrRE8QyTkoUTtDDrTqxLcl5rsbXFUAXi9/KEovDkJytLJtdO7E9MiapCE05MRignJqPQDKlVKCOFpCu5rJfwYpk+PhbDc4rPtJFQtUL3f27jXrYjht04iW4a9THFo+p8K70PX2Ulwnpe8yzO2rr2GP5dmFnp7vSGfxXpTD/7iVJs+vJx3OO7s2n08sgnPfuGwye6dySq3HpnLqUHE/0XwtSWijy1L9/bJ4Ny6AVBSTRBBYUehJHw2+Ijt0seVlhbh6mVBetAGR+E1hyK1+mfIRJwiy6rGH1NY4WA5eWc8suA6wwsL6G2rhHB018QWoNErbbouCl9/cVcW7i6AVtVnfOwQYdv4eLXK8bViupRrBFih+WB+BQ2qBzYWPqkclgF6xR6Are8fOmHV1VsvUDRSBCK7k8IuKdi6wTaCR/mIJ7EHmpnG1g5++TRwYr7LTZ6v0HwosE0JvueAYRDEFuhdHSpAQFtt9LKb3CETgcJ8JWoa6sl2bsxCJf3Fz/HOvoWKtu01quAqVdku1uhlRTkWnZp2CARU1VK6FjGRW8qhgplNDdncyIogjRslfywA2e7gC89WKfWyggNjTCqRh/I1oU1W3QBBFvQyHgSXbwRrd/YAMFG6OkxME+upacQV1Pywviw6yGOLT10Hj2oFEpRBbVFfrrA00ZpTLEjc4Le/jEADwes3UPTV3MfxN4TGbySyau9E40EQzQFiS0/w61Jsb+6ZLMX7Pf0gOi3DS7DnfKBgPQJHCPZhY11TPimtYa6kNgNkUE29NL3yeM3osU5PGIbQJmIgjbYmoG+9PwUga2txKrTwu3jXWPcoTPBdZxbwQnj2SJfmWA4rKi35WwagpRuwDSmG7A3BnEh47P57MN4n0hjqISBFdFXK4OU8WOfL4btNP6P5c01tJYlj6x9kFJRTIVOLowljDTFIMo+G6rE15EXCQrlVXiyk1U4dMej1vCb5y2Itu1JQb+5K/DMSLqsx0aYoCoICkm0kkIlawxX6141VvuAnkKI0VsO18oHpLhynwWXitkq3L4Xr57Ko+QNfmzRNV2ItYqCQ+yu1Q4lYF0T7beY+nKWqK5N+Zoq/qCdLMDMATTSEm/7EtgrWLz/96mwpwvHsPMNY8jXznYtBawPHs1dY1iyiI65Iy1FygaoNsKs8+wZjCezXFuhUTtw2AhlKLsiFvL0kfvjpnhl9oRP0RA75cGGDToIG2FSyAeNHTyTSwwMfh64uLKdkSlfRndGkNFkwh3bBMoW1RKzON997P2irvWwpWqSZg0hZHtkp6+7UZgJpVYoYcVNJFRCayrn9DunBPGG3AtXN2wkk6bOj9vHuLCOZHf7+vV/","idLAvkAMGAWysmnMvDtbPhfxbanTQya2Dd0AevG9pr4=",6323,32], - ["kv",".","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",8861,30], + ["kv",".","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",9468,32], ["kv","./kvdex","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",7982,23],