@volter/editor-core 0.5.57

package/server/gameplay-session-retention.ts

@@ -0,0 +1,149 @@
+/** Byte-budget retention for editor-managed Gameplay Session artifacts. */
+
+import { appendFile, lstat, readdir, rm, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  GAMEPLAY_SESSION_CLIP_BUDGET_BYTES,
+  GAMEPLAY_SESSION_LOG_BUDGET_BYTES,
+} from './support/play/session-record';
+
+/** Structured logs are the durable Analytics source. At the current event
+ * density this keeps hundreds of substantial sessions, without allowing one
+ * project to grow forever. */
+/** Automatically named session clips are working evidence, not keepsakes.
+ * Two GiB provides a useful history while making long recordings pay their
+ * actual disk cost. Explicitly named recordings are outside this budget. */
+export {
+  GAMEPLAY_SESSION_CLIP_BUDGET_BYTES,
+  GAMEPLAY_SESSION_LOG_BUDGET_BYTES,
+} from './support/play/session-record';
+
+interface SizedFile {
+  readonly file: string;
+  readonly bytes: number;
+}
+
+async function sizedFiles(directory: string, files: readonly string[]): Promise<SizedFile[]> {
+  const sized = await Promise.all(
+    files.map(async (file): Promise<SizedFile | null> => {
+      const info = await stat(join(directory, file)).catch(() => null);
+      return info?.isFile() ? { file, bytes: info.size } : null;
+    }),
+  );
+  return sized.filter((value): value is SizedFile => value !== null);
+}
+
+async function unlinkIfPresent(path: string): Promise<boolean> {
+  try {
+    await unlink(path);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ENOENT';
+  }
+}
+
+async function pathBytes(path: string): Promise<number> {
+  const info = await lstat(path).catch(() => null);
+  if (!info) return 0;
+  if (info.isFile()) return info.size;
+  if (!info.isDirectory()) return 0;
+  const children = await readdir(path).catch(() => []);
+  const sizes = await Promise.all(children.map((child) => pathBytes(join(path, child))));
+  return sizes.reduce((sum, bytes) => sum + bytes, 0);
+}
+
+async function removeReplaySidecar(recordingsDir: string, stem: string): Promise<void> {
+  await rm(join(recordingsDir, `${stem}.replay`), { recursive: true, force: true });
+}
+
+/** Prune oldest durable records only when their combined bytes exceed the log
+ * allotment. The newest record is always retained, even if it alone is large. */
+export async function pruneGameplaySessionLogs(
+  projectRoot: string,
+  budgetBytes = GAMEPLAY_SESSION_LOG_BUDGET_BYTES,
+): Promise<string[]> {
+  const logsDir = join(projectRoot, 'logs');
+  const files = (await readdir(logsDir).catch(() => []))
+    .filter((file) => file.startsWith('play-') && file.endsWith('.jsonl'))
+    .sort();
+  const sized = await sizedFiles(logsDir, files);
+  let total = sized.reduce((sum, value) => sum + value.bytes, 0);
+  const removed: string[] = [];
+  for (const value of sized.slice(0, -1)) {
+    if (total <= budgetBytes) break;
+    const clipRemoved = await unlinkIfPresent(
+      join(projectRoot, '.vgai', 'recordings', `${value.file.slice(0, -'.jsonl'.length)}.webm`),
+    );
+    if (!clipRemoved) continue;
+    await removeReplaySidecar(
+      join(projectRoot, '.vgai', 'recordings'),
+      value.file.slice(0, -'.jsonl'.length),
+    );
+    const logRemoved = await unlinkIfPresent(join(logsDir, value.file));
+    if (!logRemoved) continue;
+    total -= value.bytes;
+    removed.push(value.file);
+  }
+  return removed;
+}
+
+/** Prune only automatic clips paired by stem with a durable session log.
+ * Named recordings are caller-owned keepsakes and never enter this pool. The
+ * log remains when its optional clip is evicted, so Analytics history stays. */
+export async function pruneGameplaySessionClips(
+  projectRoot: string,
+  budgetBytes = GAMEPLAY_SESSION_CLIP_BUDGET_BYTES,
+): Promise<string[]> {
+  const logsDir = join(projectRoot, 'logs');
+  const recordingsDir = join(projectRoot, '.vgai', 'recordings');
+  const logStems = new Set(
+    (await readdir(logsDir).catch(() => []))
+      .filter((file) => file.startsWith('play-') && file.endsWith('.jsonl'))
+      .map((file) => file.slice(0, -'.jsonl'.length)),
+  );
+  const files = (await readdir(recordingsDir).catch(() => []))
+    .filter((file) => file.endsWith('.webm') && logStems.has(file.slice(0, -'.webm'.length)))
+    .sort();
+  const sized = await Promise.all(
+    (await sizedFiles(recordingsDir, files)).map(async (value) => ({
+      ...value,
+      bytes:
+        value.bytes +
+        (await pathBytes(join(recordingsDir, `${value.file.slice(0, -'.webm'.length)}.replay`))),
+    })),
+  );
+  let total = sized.reduce((sum, value) => sum + value.bytes, 0);
+  const removed: string[] = [];
+  for (const value of sized.slice(0, -1)) {
+    if (total <= budgetBytes) break;
+    const logFile = join(logsDir, `${value.file.slice(0, -'.webm'.length)}.jsonl`);
+    const evictedAt = Date.now();
+    const recorded = await appendFile(
+      logFile,
+      `${JSON.stringify({
+        t: evictedAt,
+        level: 'info',
+        source: 'gameplay-recording',
+        msg: 'evicted',
+        meta: {
+          file: value.file,
+          bytes: value.bytes,
+          reason: 'managed-clip-byte-budget',
+          evictedAt,
+        },
+      })}\n`,
+      'utf-8',
+    )
+      .then(() => true)
+      .catch(() => false);
+    if (!recorded) continue;
+    const deleted = await unlink(join(recordingsDir, value.file))
+      .then(() => true)
+      .catch(() => false);
+    if (!deleted) continue;
+    await removeReplaySidecar(recordingsDir, value.file.slice(0, -'.webm'.length));
+    total -= value.bytes;
+    removed.push(value.file);
+  }
+  return removed;
+}

package/server/gameplay-sessions.ts

@@ -0,0 +1,123 @@
+/**
+ * Durable Gameplay Sessions, derived from the artifacts Play already owns.
+ *
+ * The JSONL log is the session record. Recording lifecycle entries inside that
+ * same record associate an optional WebM without a second manifest that can
+ * drift. A server restart reconstructs the complete catalog from disk.
+ *
+ * The PARSE RULES live in the browser-safe core
+ * (`@vgai/sdk`'s `play/session-record.ts`), and this module is the Node
+ * wiring: the stat-keyed cache, the directory walk, and the recording
+ * route/paths only a server has.
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import {
+  type GameplaySessionRecord,
+  materializeGameplaySession,
+  type ParsedGameplaySession,
+  parsePlayLogText,
+} from './support/play/session-record';
+
+export type {
+  GameplaySessionRecord,
+  GameplaySessionRecording,
+} from './support/play/session-record';
+
+interface CachedGameplaySession {
+  readonly size: number;
+  readonly mtimeMs: number;
+  readonly parsed: ParsedGameplaySession | null;
+}
+
+const sessionCache = new Map<string, CachedGameplaySession>();
+
+async function parseGameplaySession(
+  projectRoot: string,
+  file: string,
+): Promise<ParsedGameplaySession | null> {
+  const absolute = join(projectRoot, 'logs', file);
+  const fileStats = await stat(absolute).catch(() => null);
+  if (!fileStats) return null;
+  const cached = sessionCache.get(absolute);
+  if (cached && cached.size === fileStats.size && cached.mtimeMs === fileStats.mtimeMs) {
+    return cached.parsed;
+  }
+  let raw: string;
+  try {
+    raw = await readFile(absolute, 'utf-8');
+  } catch {
+    return null;
+  }
+  const parsed = parsePlayLogText(raw, {
+    file,
+    fallbackEndedAt: fileStats.mtimeMs,
+    recordingUrl: (sessionId) =>
+      `/__editor/gameplay-sessions/${encodeURIComponent(sessionId)}/recording`,
+  });
+  sessionCache.set(absolute, { size: fileStats.size, mtimeMs: fileStats.mtimeMs, parsed });
+  return parsed;
+}
+
+async function readGameplaySession(
+  projectRoot: string,
+  file: string,
+  activeLogFile: string | null,
+): Promise<GameplaySessionRecord | null> {
+  const parsed = await parseGameplaySession(projectRoot, file);
+  return parsed
+    ? materializeGameplaySession(parsed, {
+        activeLogBaseName: activeLogFile === null ? null : basename(activeLogFile),
+        now: Date.now(),
+      })
+    : null;
+}
+
+export async function listGameplaySessions(
+  projectRoot: string,
+  activeLogFile: string | null,
+): Promise<GameplaySessionRecord[]> {
+  const files = await readdir(join(projectRoot, 'logs')).catch(() => []);
+  const playFiles = files
+    .filter((file) => file.startsWith('play-') && file.endsWith('.jsonl'))
+    .sort()
+    .reverse();
+  const livePaths = new Set(playFiles.map((file) => join(projectRoot, 'logs', file)));
+  for (const cachedPath of sessionCache.keys()) {
+    if (!livePaths.has(cachedPath)) sessionCache.delete(cachedPath);
+  }
+  const sessions = await Promise.all(
+    playFiles.map((file) => readGameplaySession(projectRoot, file, activeLogFile)),
+  );
+  return sessions.filter((session): session is GameplaySessionRecord => session !== null);
+}
+
+/** Metadata-only catalog for the one-second rail poll. Entries are fetched
+ * only for the selected session, so twenty long runs never cross the wire on
+ * every live-edge update. */
+export async function listGameplaySessionCatalog(
+  projectRoot: string,
+  activeLogFile: string | null,
+): Promise<GameplaySessionRecord[]> {
+  const sessions = await listGameplaySessions(projectRoot, activeLogFile);
+  return sessions.map((session) => ({ ...session, entries: [] }));
+}
+
+export async function getGameplaySession(
+  projectRoot: string,
+  id: string,
+  activeLogFile: string | null,
+): Promise<GameplaySessionRecord | null> {
+  if (basename(id) !== id || !id.startsWith('play-')) return null;
+  return readGameplaySession(projectRoot, `${id}.jsonl`, activeLogFile);
+}
+
+export function gameplaySessionRecordingPath(
+  projectRoot: string,
+  session: GameplaySessionRecord,
+): string | null {
+  const file = session.recording?.file;
+  if (!file || basename(file) !== file) return null;
+  return join(projectRoot, '.vgai', 'recordings', file);
+}

package/server/generation-jobs.ts

@@ -0,0 +1,201 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import {
+  type GenerationJob,
+  type GenerationJobDraft,
+  type GenerationJobsDocument,
+  GenerationJobsDocumentSchema,
+  type GenerationJobUpdate,
+  type GenerationToolContribution,
+} from '@volter/editor-sdk/generations';
+import { sanitizeRecordedValue } from './redact-secrets';
+
+export const PROJECT_GENERATIONS_PATH = '.vgai/generations.json';
+
+const projectQueues = new Map<string, Promise<unknown>>();
+function emptyDocument(): GenerationJobsDocument {
+  return { version: 1, jobs: [] };
+}
+
+export async function readGenerationJobs(projectRoot: string): Promise<GenerationJobsDocument> {
+  try {
+    const value: unknown = JSON.parse(
+      await readFile(resolve(projectRoot, PROJECT_GENERATIONS_PATH), 'utf8'),
+    );
+    return GenerationJobsDocumentSchema.parse(value);
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return emptyDocument();
+    }
+    throw error;
+  }
+}
+
+async function writeDocument(projectRoot: string, document: GenerationJobsDocument): Promise<void> {
+  const path = resolve(projectRoot, PROJECT_GENERATIONS_PATH);
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(
+    temporary,
+    `${JSON.stringify(GenerationJobsDocumentSchema.parse(document), null, 2)}\n`,
+  );
+  try {
+    await rename(temporary, path);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+function serialize<T>(projectRoot: string, work: () => Promise<T>): Promise<T> {
+  const prior = projectQueues.get(projectRoot) ?? Promise.resolve();
+  const next = prior.catch(() => undefined).then(work);
+  projectQueues.set(projectRoot, next);
+  const cleanup = () => {
+    if (projectQueues.get(projectRoot) === next) projectQueues.delete(projectRoot);
+  };
+  void next.then(cleanup, cleanup);
+  return next;
+}
+
+function findJob(document: GenerationJobsDocument, update: GenerationJobUpdate): GenerationJob {
+  const job = document.jobs.find(
+    (candidate) =>
+      candidate.provider === update.provider && candidate.externalId === update.externalId,
+  );
+  if (!job) {
+    throw new Error(
+      `Generation provider ${JSON.stringify(update.provider)} updated unknown job ${JSON.stringify(update.externalId)}.`,
+    );
+  }
+  return job;
+}
+
+function applyUpdate(job: GenerationJob, update: GenerationJobUpdate, now: string): GenerationJob {
+  const next = {
+    ...job,
+    updatedAt: now,
+    ...(update.status ? { status: update.status } : {}),
+    ...(update.progress !== undefined ? { progress: update.progress } : {}),
+    ...(update.providerStatus !== undefined ? { providerStatus: update.providerStatus } : {}),
+    ...(update.queuePosition !== undefined ? { queuePosition: update.queuePosition } : {}),
+    ...(update.message !== undefined ? { message: update.message } : {}),
+    ...(update.billing ? { billing: update.billing } : {}),
+    ...(update.cancel ? { cancel: update.cancel } : {}),
+    ...(update.accept ? { accept: update.accept } : {}),
+    ...(update.accepted
+      ? {
+          acceptedAt: now,
+          provenanceOperationId: update.accepted.provenanceOperationId,
+          outputPaths: update.accepted.outputPaths,
+        }
+      : {}),
+  };
+  delete next.pollError;
+  delete next.pollErrorAt;
+  delete next.pollFailureCount;
+  delete next.nextPollAt;
+  if (update.accept === null) delete next.accept;
+  return next;
+}
+
+export async function recordGenerationPollFailure(
+  projectRoot: string,
+  id: string,
+  failure: string | null,
+): Promise<void> {
+  await serialize(projectRoot, async () => {
+    const document = await readGenerationJobs(projectRoot);
+    const job = document.jobs.find((candidate) => candidate.id === id);
+    if (!job) return;
+    const now = new Date().toISOString();
+    document.jobs = document.jobs.map((candidate) => {
+      if (candidate.id !== id) return candidate;
+      if (failure === null) {
+        const next = { ...candidate, updatedAt: now };
+        delete next.pollError;
+        delete next.pollErrorAt;
+        delete next.pollFailureCount;
+        delete next.nextPollAt;
+        return next;
+      }
+      const failureCount = (candidate.pollFailureCount ?? 0) + 1;
+      const backoffSeconds = Math.min(60, 5 * 2 ** Math.min(4, failureCount - 1));
+      return {
+        ...candidate,
+        pollError: failure,
+        pollErrorAt: now,
+        pollFailureCount: failureCount,
+        nextPollAt: new Date(Date.now() + backoffSeconds * 1_000).toISOString(),
+      };
+    });
+    await writeDocument(projectRoot, document);
+  });
+}
+
+export async function applyGenerationContribution(
+  projectRoot: string,
+  contribution: GenerationToolContribution,
+  input: unknown,
+  result: unknown,
+): Promise<GenerationJob> {
+  return serialize(projectRoot, async () => {
+    const document = await readGenerationJobs(projectRoot);
+    const now = new Date().toISOString();
+    let job: GenerationJob;
+    if (contribution.role === 'submit') {
+      const draft: GenerationJobDraft = contribution.toJob(input, result);
+      if (draft.provider !== contribution.provider) {
+        throw new Error('Generation contribution returned a different provider id.');
+      }
+      const existing = document.jobs.find(
+        (candidate) =>
+          candidate.provider === draft.provider && candidate.externalId === draft.externalId,
+      );
+      job = GenerationJobsDocumentSchema.shape.jobs.element.parse(
+        sanitizeRecordedValue({
+          ...draft,
+          id: existing?.id ?? randomUUID(),
+          createdAt: existing?.createdAt ?? now,
+          updatedAt: now,
+        }),
+      );
+      document.jobs = [job, ...document.jobs.filter((candidate) => candidate.id !== job.id)];
+    } else {
+      const update = contribution.toUpdate(input, result);
+      if (update.provider !== contribution.provider) {
+        throw new Error('Generation contribution returned a different provider id.');
+      }
+      job = applyUpdate(findJob(document, update), update, now);
+      document.jobs = document.jobs.map((candidate) => (candidate.id === job.id ? job : candidate));
+    }
+    await writeDocument(projectRoot, document);
+    return job;
+  });
+}
+
+export async function forgetGenerationJob(projectRoot: string, id: string): Promise<boolean> {
+  return serialize(projectRoot, async () => {
+    const document = await readGenerationJobs(projectRoot);
+    const next = document.jobs.filter((job) => job.id !== id);
+    if (next.length === document.jobs.length) return false;
+    document.jobs = next;
+    await writeDocument(projectRoot, document);
+    return true;
+  });
+}
+
+export async function markGenerationJobRead(projectRoot: string, id: string): Promise<boolean> {
+  return serialize(projectRoot, async () => {
+    const document = await readGenerationJobs(projectRoot);
+    const job = document.jobs.find((candidate) => candidate.id === id);
+    if (!job || job.status === 'queued' || job.status === 'running') return false;
+    if (job.readAt && Date.parse(job.readAt) >= Date.parse(job.updatedAt)) return false;
+    const readAt = new Date().toISOString();
+    document.jobs = document.jobs.map((candidate) =>
+      candidate.id === id ? { ...candidate, readAt } : candidate,
+    );
+    await writeDocument(projectRoot, document);
+    return true;
+  });
+}

package/server/generation-reconciler.ts

@@ -0,0 +1,137 @@
+import type { GenerationJob } from '@volter/editor-sdk/generations';
+import type { EditorAccountService } from './account-service';
+import { readGenerationJobs, recordGenerationPollFailure } from './generation-jobs';
+import { reconcileAcceptedGenerationProvenance } from './project-output-writer';
+import {
+  executeProjectTool,
+  type ProjectModuleLoader,
+  type ProjectToolExecution,
+} from './project-tools';
+
+export interface GenerationReconcileReport {
+  attempted: number;
+  succeeded: number;
+  failed: Array<{ id: string; message: string }>;
+}
+
+function executionFailure(result: ProjectToolExecution): string | null {
+  return result.body.ok ? (result.body.generationWarning ?? null) : result.body.error.message;
+}
+
+async function reconcileJob(
+  projectRoot: string,
+  loadModule: ProjectModuleLoader | undefined,
+  job: GenerationJob,
+  account?: EditorAccountService,
+): Promise<string | null> {
+  try {
+    if (job.status === 'queued' || job.status === 'running') {
+      const result = await executeProjectTool({
+        account,
+        projectRoot,
+        loadModule,
+        name: job.poll.tool,
+        input: job.poll.input,
+        confirmed: false,
+      });
+      const failure = executionFailure(result);
+      if (failure) throw new Error(failure);
+    }
+    // Read again: polling or a concurrent explicit save may have completed it.
+    const current = (await readGenerationJobs(projectRoot)).jobs.find(
+      (entry) => entry.id === job.id,
+    );
+    if (current?.status === 'succeeded' && current.accept && !current.acceptedAt) {
+      const result = await executeProjectTool({
+        account,
+        projectRoot,
+        loadModule,
+        name: current.accept.tool,
+        input: current.accept.input,
+        confirmed: true,
+      });
+      const failure =
+        executionFailure(result) ??
+        (result.body.ok && !result.body.generation?.acceptedAt ? 'Output was not saved.' : null);
+      if (failure) throw new Error(`Saving output failed: ${failure}`);
+    }
+    await recordGenerationPollFailure(projectRoot, job.id, null);
+    return null;
+  } catch (error) {
+    const failure = error instanceof Error ? error.message : String(error);
+    await recordGenerationPollFailure(projectRoot, job.id, failure);
+    return failure;
+  }
+}
+
+/** Server-owned, bounded reconciliation. Browser tabs observe this state and
+ * never multiply provider polls merely because several editors are open. */
+async function reconcileProjectGenerationJobs(
+  projectRoot: string,
+  loadModule: ProjectModuleLoader | undefined,
+  concurrency = 3,
+  account?: EditorAccountService,
+): Promise<GenerationReconcileReport> {
+  const allJobs = (await readGenerationJobs(projectRoot)).jobs;
+  const failed: GenerationReconcileReport['failed'] = [];
+  await Promise.all(
+    allJobs
+      .filter((job) => job.acceptedAt && job.provenanceOperationId)
+      .map(async (job) => {
+        try {
+          await reconcileAcceptedGenerationProvenance(projectRoot, job);
+        } catch (error) {
+          failed.push({
+            id: job.id,
+            message: `Provenance settlement repair failed: ${error instanceof Error ? error.message : String(error)}`,
+          });
+        }
+      }),
+  );
+  const now = Date.now();
+  const jobs = allJobs.filter(
+    (job) =>
+      (job.status === 'queued' ||
+        job.status === 'running' ||
+        (job.status === 'succeeded' &&
+          job.accept &&
+          !job.acceptedAt &&
+          (job.pollFailureCount ?? 0) < 5)) &&
+      (!job.nextPollAt || Date.parse(job.nextPollAt) <= now),
+  );
+  let cursor = 0;
+  let succeeded = 0;
+  const worker = async () => {
+    while (cursor < jobs.length) {
+      const job = jobs[cursor++];
+      if (!job) continue;
+      const failure = await reconcileJob(projectRoot, loadModule, job, account);
+      if (failure) failed.push({ id: job.id, message: failure });
+      else succeeded++;
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(Math.max(1, concurrency), jobs.length) }, () => worker()),
+  );
+  return { attempted: jobs.length, succeeded, failed };
+}
+
+const inFlight = new Map<string, Promise<GenerationReconcileReport>>();
+
+/** The timer and explicit refresh share the same poll/save pass. */
+export function reconcileGenerationJobs(
+  projectRoot: string,
+  loadModule: ProjectModuleLoader | undefined,
+  concurrency = 3,
+  account?: EditorAccountService,
+): Promise<GenerationReconcileReport> {
+  const pending = inFlight.get(projectRoot);
+  if (pending) return pending;
+  const work = reconcileProjectGenerationJobs(projectRoot, loadModule, concurrency, account);
+  inFlight.set(projectRoot, work);
+  const cleanup = () => {
+    if (inFlight.get(projectRoot) === work) inFlight.delete(projectRoot);
+  };
+  void work.then(cleanup, cleanup);
+  return work;
+}

package/server/generative-execution-context.ts

@@ -0,0 +1,59 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { ProjectProviderExecution } from '@volter/editor-sdk/tools/types';
+
+export const GENERATIVE_EXECUTION_RECORDER = Symbol.for('vgai.generative-execution-recorder.v1');
+
+type ExecutionFacts = ProjectProviderExecution;
+
+interface ExecutionCapture {
+  pending: ExecutionFacts[];
+}
+
+const captures = new AsyncLocalStorage<ExecutionCapture>();
+
+function sameNativeExecution(left: ExecutionFacts, right: ExecutionFacts): boolean {
+  if (left.mode !== right.mode || left.provider !== right.provider) return false;
+  if (left.requestId && right.requestId) return left.requestId === right.requestId;
+  if (left.taskId && right.taskId) return left.taskId === right.taskId;
+  if (left.managedJobId && right.managedJobId) return left.managedJobId === right.managedJobId;
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function validFacts(value: unknown): value is ExecutionFacts {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Partial<ExecutionFacts>;
+  return (
+    (candidate.mode === 'mock' || candidate.mode === 'direct' || candidate.mode === 'managed') &&
+    typeof candidate.provider === 'string' &&
+    candidate.provider.length > 0
+  );
+}
+
+function installRecorder(): void {
+  const globals = globalThis as typeof globalThis & { [GENERATIVE_EXECUTION_RECORDER]?: unknown };
+  if (globals[GENERATIVE_EXECUTION_RECORDER] !== undefined) return;
+  globals[GENERATIVE_EXECUTION_RECORDER] = (facts: unknown) => {
+    if (!validFacts(facts)) return;
+    captures.getStore()?.pending.push({ ...facts });
+  };
+}
+
+installRecorder();
+
+/** Runs one project tool with provider execution capture isolated across async work. */
+export function runWithGenerativeExecutionCapture<T>(work: () => Promise<T>): Promise<T> {
+  return captures.run({ pending: [] }, work);
+}
+
+/** Consumes the ordered native provider execution chain associated with the next output commit. */
+export function consumeGenerativeExecutions(): ExecutionFacts[] {
+  const capture = captures.getStore();
+  if (!capture || capture.pending.length === 0) return [];
+  const executions: ExecutionFacts[] = [];
+  for (const facts of capture.pending.splice(0)) {
+    const index = executions.findIndex((candidate) => sameNativeExecution(candidate, facts));
+    if (index === -1) executions.push(facts);
+    else executions[index] = { ...facts, ...executions[index] };
+  }
+  return executions;
+}