@open-agent-toolkit/cli 0.3.21 → 0.3.22

package/dist/commands/project/archive/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAIL,KAAK,qCAAqC,EAC3C,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,iCAAiC,EACvC,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,kBAAkB,EAClB,iCAAiC,GAClC,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qCAAqC,GACtC,MAAM,eAAe,CAAC;AAEvB,KAAK,0BAA0B,GAAG,iCAAiC,GACjE,qCAAqC,CAAC;AAKxC,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAiFT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAIL,KAAK,qCAAqC,EAC3C,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,iCAAiC,EACvC,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,kBAAkB,EAClB,iCAAiC,GAClC,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qCAAqC,GACtC,MAAM,eAAe,CAAC;AAEvB,KAAK,0BAA0B,GAAG,iCAAiC,GACjE,qCAAqC,CAAC;AAKxC,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAqFT"}

package/dist/commands/project/archive/index.js

@@ -15,6 +15,7 @@ export function createProjectArchiveCommand(overrides = {}) {
         .option('--dry-run', 'Preview archive without moving files or syncing S3')
         .option('--no-commit', 'Manual/library use only: omit the synced lifecycle commit receipt')
         .option('--project-recap-run <path>', 'Export the selected project-relative recap run before archiving')
+        .option('--new-generation <reason>', 'Archive reopened work as the next generation of an archived shared or local project (requires exactly one predecessor)')
         .addHelpText('afterAll', '\nPull archived project data with `oat repo archive sync [project-name]`; `oat project archive sync` is deprecated.')
         .action(async (projectPath, options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));

package/dist/commands/project/archive/push-runner.d.ts

@@ -1,11 +1,13 @@
 import { buildCommandContext, type CommandContext } from '../../../app/command-context.js';
 import { readSyncedRecord } from '../../project/sync/record.js';
 import { type OatConfig, type OatLocalConfig } from '../../../config/oat-config.js';
-import { assertExactArchiveProjectRoot, resolveArchiveProjectTarget, resolvePrimaryRepoRoot, verifySelectedProjectRecapForArchive, type ArchiveProjectOnCompletionOptions, type ArchiveProjectOnCompletionResult } from './archive-utils.js';
+import { assertExactArchiveProjectRoot, resolveArchiveProjectTarget, resolvePrimaryRepoRoot, verifySelectedProjectRecapForArchive, type RecordlessSyncedArchiveIdentity, type ArchiveProjectOnCompletionOptions, type ArchiveProjectOnCompletionResult } from './archive-utils.js';
 export interface ArchivePushOptions {
     dryRun?: boolean;
     projectRecapRun?: string;
     commit?: boolean;
+    /** `--new-generation <reason>`. */
+    newGeneration?: string;
 }
 export interface ProjectArchivePushCommandDependencies {
     buildCommandContext: (options: Parameters<typeof buildCommandContext>[0]) => CommandContext;
@@ -21,6 +23,12 @@ export interface ProjectArchivePushCommandDependencies {
     assertExactArchiveProjectRoot: typeof assertExactArchiveProjectRoot;
     processEnv: NodeJS.ProcessEnv;
     timestamp: () => string;
+    /** Recordless synced identity through the completed ref; defaults to the shared resolver. */
+    resolveRecordlessSyncedArchiveIdentity?: (options: {
+        repoRoot: string;
+        projectsRoot: string;
+        projectName: string;
+    }) => Promise<RecordlessSyncedArchiveIdentity>;
 }
 export declare function defaultProjectArchivePushCommandDependencies(): ProjectArchivePushCommandDependencies;
 export declare function runArchivePushCommand(dependencies: ProjectArchivePushCommandDependencies, projectPathArg: string | undefined, options: ArchivePushOptions, context: CommandContext): Promise<void>;

package/dist/commands/project/archive/push-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"push-runner.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/push-runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAOjE,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAEL,6BAA6B,EAI7B,2BAA2B,EAC3B,sBAAsB,EACtB,oCAAoC,EAEpC,KAAK,iCAAiC,EACtC,KAAK,gCAAgC,EAEtC,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,qCAAqC;IACpD,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;IAChE,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;IAC1C,oCAAoC,EAAE,OAAO,oCAAoC,CAAC;IAClF,0BAA0B,EAAE,CAC1B,OAAO,EAAE,iCAAiC,KACvC,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC/C,6BAA6B,EAAE,OAAO,6BAA6B,CAAC;IACpE,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,SAAS,EAAE,MAAM,MAAM,CAAC;CACzB;AA0BD,wBAAgB,4CAA4C,IAAI,qCAAqC,CAgBpG;AA8JD,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,qCAAqC,EACnD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAmHf"}
+{"version":3,"file":"push-runner.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/push-runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAQjE,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAGL,6BAA6B,EAK7B,2BAA2B,EAE3B,sBAAsB,EACtB,oCAAoC,EAEpC,KAAK,+BAA+B,EACpC,KAAK,iCAAiC,EACtC,KAAK,gCAAgC,EAEtC,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qCAAqC;IACpD,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;IAChE,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;IAC1C,oCAAoC,EAAE,OAAO,oCAAoC,CAAC;IAClF,0BAA0B,EAAE,CAC1B,OAAO,EAAE,iCAAiC,KACvC,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC/C,6BAA6B,EAAE,OAAO,6BAA6B,CAAC;IACpE,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,6FAA6F;IAC7F,sCAAsC,CAAC,EAAE,CAAC,OAAO,EAAE;QACjD,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC,+BAA+B,CAAC,CAAC;CAChD;AA4BD,wBAAgB,4CAA4C,IAAI,qCAAqC,CAgBpG;AAiLD,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,qCAAqC,EACnD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAoJf"}

package/dist/commands/project/archive/push-runner.js

@@ -1,12 +1,14 @@
 import { basename, isAbsolute, join } from 'node:path';
 import { buildCommandContext } from '../../../app/command-context.js';
+import { defaultGitRunner } from '../../project/sync/git.js';
 import { readSyncedRecord } from '../../project/sync/record.js';
+import { buildSyncTarget } from '../../project/sync/ref-sync.js';
 import { resolveProjectsRoot } from '../../shared/oat-paths.js';
 import { resolveScopeRoot, syncedRecordPath, } from '../../shared/project-scope.js';
 import { readOatConfig, readOatLocalConfig, } from '../../../config/oat-config.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
-import { archiveProjectOnCompletion, assertExactArchiveProjectRoot, assertDurableArchiveProjectTarget, buildArchiveSnapshotName, buildProjectArchiveS3Uri, resolveArchiveProjectTarget, resolvePrimaryRepoRoot, verifySelectedProjectRecapForArchive, } from './archive-utils.js';
+import { ArchiveIdentityError, archiveProjectOnCompletion, assertExactArchiveProjectRoot, assertDurableArchiveProjectTarget, buildProjectArchiveS3Uri, evaluateArchiveRetryIdentity, newGenerationReplayWarning, resolveArchiveProjectTarget, resolveRecordlessSyncedArchiveIdentity, resolvePrimaryRepoRoot, verifySelectedProjectRecapForArchive, } from './archive-utils.js';
 export function defaultProjectArchivePushCommandDependencies() {
     return {
         buildCommandContext,
@@ -58,9 +60,16 @@ function buildArchiveOptions(repoRoot, config, projectsRoot, target, options) {
         awsProfile: config.archive?.awsProfile,
         awsRegion: config.archive?.awsRegion,
         ...(options.commit === false ? { commit: false } : {}),
+        ...(options.newGeneration !== undefined
+            ? { newGenerationReason: options.newGeneration }
+            : {}),
     };
 }
-async function buildDryRunReport(dependencies, repoRoot, config, target, archiveTarget, snapshotName, projectScope) {
+async function buildDryRunReport(dependencies, repoRoot, config, target, identity, projectScope, newGenerationReason) {
+    // Every reported destination comes from the shared retry-identity
+    // evaluator, so an identical retry previews the persisted snapshot it would
+    // reuse rather than a new identity derived from today's date.
+    const snapshotName = identity.snapshotName;
     const remoteRepoRoot = await dependencies.resolvePrimaryRepoRoot(repoRoot);
     const s3Path = config.archive?.s3Uri && config.archive.s3SyncOnComplete === true
         ? buildProjectArchiveS3Uri(config.archive.s3Uri, remoteRepoRoot, snapshotName)
@@ -73,19 +82,21 @@ async function buildDryRunReport(dependencies, repoRoot, config, target, archive
         mode: 'dry-run',
         projectName: target.projectName,
         projectPath: target.projectPath,
-        archivePath: archiveTarget.archivePath,
+        archivePath: identity.archivePath,
         s3Path,
         summaryExportFile,
-        warnings: [],
+        warnings: [
+            newGenerationReplayWarning(identity, newGenerationReason),
+        ].filter((warning) => warning !== null),
         lifecycleCommit: null,
         recapExportPaths: [],
-        snapshotId: projectScope === 'synced'
-            ? snapshotName
-            : basename(archiveTarget.archivePath),
+        snapshotId: projectScope === 'synced' ? snapshotName : basename(identity.archivePath),
         completedRef: null,
         verifiedSourceSha: null,
         activeAliasDisposition: null,
         recordRetired: false,
+        generation: identity.generation,
+        predecessorSnapshot: identity.predecessor,
     };
 }
 function emitArchivePushText(report, summaryExportPath, logger) {
@@ -94,6 +105,9 @@ function emitArchivePushText(report, summaryExportPath, logger) {
     }
     if (report.mode === 'dry-run') {
         logger.info(`Dry-run: would archive project \`${report.projectName}\` from \`${report.projectPath}\` to \`${report.archivePath}\`.`);
+        if (report.predecessorSnapshot) {
+            logger.info(`Generation ${report.generation} after \`${report.predecessorSnapshot}\`.`);
+        }
         if (report.s3Path) {
             logger.info(`S3 archive: ${report.s3Path}`);
         }
@@ -103,6 +117,9 @@ function emitArchivePushText(report, summaryExportPath, logger) {
         return;
     }
     logger.info(`Archived project \`${report.projectName}\` to \`${report.archivePath}\`.`);
+    if (report.predecessorSnapshot) {
+        logger.info(`Generation ${report.generation} after \`${report.predecessorSnapshot}\`.`);
+    }
     if (report.s3Path) {
         logger.info(`S3 archive: ${report.s3Path}`);
     }
@@ -133,33 +150,44 @@ export async function runArchivePushCommand(dependencies, projectPathArg, option
             projectName: target.projectName,
             projectsRoot,
         });
-        const defaultSnapshotName = buildArchiveSnapshotName(target.projectName, dependencies.timestamp());
         const syncedRecord = projectScope === 'synced'
             ? await dependencies.readSyncedRecord(syncedRecordPath(resolveScopeRoot(repoRoot, projectsRoot, 'synced'), target.projectName))
             : null;
-        const snapshotName = syncedRecord?.archiveSnapshot ?? defaultSnapshotName;
-        const archiveTarget = await dependencies.resolveArchiveProjectTarget({
+        // A recordless synced project binds its snapshot through the completed
+        // ref, in dry-run exactly as in apply.
+        const recordless = projectScope === 'synced' && syncedRecord === null
+            ? await (dependencies.resolveRecordlessSyncedArchiveIdentity ??
+                ((resolverOptions) => resolveRecordlessSyncedArchiveIdentity(resolverOptions, buildSyncTarget(resolverOptions.repoRoot, resolverOptions.projectsRoot, resolverOptions.projectName), defaultGitRunner, { env: dependencies.processEnv })))({ repoRoot, projectsRoot, projectName: target.projectName })
+            : null;
+        const persistedSnapshot = syncedRecord?.archiveSnapshot ?? recordless?.metadata.snapshotName;
+        const persistedSourceRefSha = syncedRecord?.archiveSourceRefSha ?? recordless?.metadata.sourceRefSha;
+        const identity = await evaluateArchiveRetryIdentity({
             repoRoot,
             projectsRoot,
             projectName: target.projectName,
-            ...(syncedRecord?.archiveSnapshot
-                ? {
-                    archiveSnapshot: syncedRecord.archiveSnapshot,
-                    archiveScope: projectScope ?? undefined,
-                }
+            projectPath: target.projectPath,
+            scope: projectScope,
+            timestamp: dependencies.timestamp(),
+            ...(persistedSnapshot ? { persistedSnapshot } : {}),
+            ...(persistedSourceRefSha
+                ? { sourceRefSha: persistedSourceRefSha }
+                : {}),
+            ...(options.newGeneration !== undefined
+                ? { newGeneration: { reason: options.newGeneration } }
                 : {}),
         }, {
+            resolveArchiveProjectTarget: dependencies.resolveArchiveProjectTarget,
             env: dependencies.processEnv,
             timestamp: dependencies.timestamp,
         });
-        assertDurableArchiveProjectTarget(archiveTarget);
+        assertDurableArchiveProjectTarget(identity.target);
         const dryRun = options.dryRun === true || context.dryRun;
         const recordlessSyncedApply = projectScope === 'synced' && syncedRecord === null && !dryRun;
         if (options.projectRecapRun?.trim() && !recordlessSyncedApply) {
             await dependencies.verifySelectedProjectRecapForArchive(target.projectPath, options.projectRecapRun.trim());
         }
         if (dryRun) {
-            const report = await buildDryRunReport(dependencies, repoRoot, config, target, archiveTarget, snapshotName, projectScope);
+            const report = await buildDryRunReport(dependencies, repoRoot, config, target, identity, projectScope, options.newGeneration);
             emitArchivePushReport(report, config.archive?.summaryExportPath, context);
             process.exitCode = 0;
             return;
@@ -188,6 +216,12 @@ export async function runArchivePushCommand(dependencies, projectPathArg, option
                     : 'removed'
                 : null,
             recordRetired: result.recordRetired,
+            ...(result.generation !== undefined
+                ? {
+                    generation: result.generation,
+                    predecessorSnapshot: result.predecessorSnapshot ?? null,
+                }
+                : {}),
         };
         emitArchivePushReport(report, config.archive?.summaryExportPath, context);
         process.exitCode = 0;
@@ -195,7 +229,11 @@ export async function runArchivePushCommand(dependencies, projectPathArg, option
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         if (context.json) {
-            context.logger.json({ status: 'error', message });
+            context.logger.json({
+                status: 'error',
+                ...(error instanceof ArchiveIdentityError ? { code: error.code } : {}),
+                message,
+            });
         }
         else {
             context.logger.error(message);

package/dist/commands/project/archive/sync-runner.d.ts

@@ -1,5 +1,6 @@
 import { rm } from 'node:fs/promises';
 import { buildCommandContext, type CommandContext } from '../../../app/command-context.js';
+import type { ProjectScope } from '../../shared/project-scope.js';
 import { type OatConfig } from '../../../config/oat-config.js';
 import { buildProjectArchiveS3Uri, buildRepoArchiveS3Uri, ensureS3ArchiveAccess, type ExecFileLike, resolveLocalArchiveProjectPath, resolvePrimaryRepoRoot } from './archive-utils.js';
 export interface ArchiveSyncOptions {
@@ -33,14 +34,41 @@ export declare function buildArchiveSyncArgs(source: string, target: string, opt
 export declare function runArchiveSync(repoRoot: string, source: string, target: string, options: ArchiveSyncOptions, awsEnv: NodeJS.ProcessEnv, dependencies: ProjectArchiveCommandDependencies): Promise<void>;
 export interface ArchiveSnapshotEntry {
     dateStamp: string | null;
+    /** Base project name, without a `-gN` generation suffix. */
     projectName: string;
+    /** Full local archive name the snapshot hydrates to (`<project>-gN`). */
+    localName: string;
+    /** Generation family: the base name plus its scope qualifier, if any. */
+    familyName: string;
+    /** Scope qualifier carried by the snapshot name, or null. */
+    scope: ProjectScope | null;
+    /** Archive generation; 1 when the snapshot name carries no suffix. */
+    generation: number;
     snapshotName: string;
     source: string;
     target: string;
 }
 export declare function listArchiveSnapshots(repoRoot: string, projectsRoot: string, s3Uri: string, awsEnv: NodeJS.ProcessEnv, dependencies: ProjectArchiveCommandDependencies): Promise<ArchiveSnapshotEntry[]>;
+/**
+ * Orders snapshots oldest to latest: a later generation is later regardless
+ * of date, then a later date, then the snapshot name.
+ */
 export declare function compareSnapshotEntries(left: ArchiveSnapshotEntry, right: ArchiveSnapshotEntry): number;
+/**
+ * The latest snapshot for each local archive: every generation keeps its own
+ * local directory, so each one is hydrated from its own latest snapshot.
+ */
 export declare function selectLatestSnapshots(snapshots: ArchiveSnapshotEntry[]): ArchiveSnapshotEntry[];
+/**
+ * The snapshots a by-name sync restores, in precedence order: an exact
+ * snapshot name; else a full generation name such as `demo-g2` or
+ * `demo-g2-local` (which also keeps a project literally named `demo-g2`
+ * reachable); else every generation family the name identifies, either as a
+ * family (`demo-local`: the local-scope `demo` archives) or as the base
+ * project (`demo`: `demo` and its scope-qualified families). Each family
+ * restores its latest generation, then its latest date.
+ */
+export declare function selectNamedSnapshotCandidates(snapshots: ArchiveSnapshotEntry[], name: string): ArchiveSnapshotEntry[];
 export declare function readLocalSnapshotName(repoRoot: string, target: string): Promise<string | null>;
 export declare function syncArchiveSnapshot(repoRoot: string, snapshot: ArchiveSnapshotEntry, options: ArchiveSyncOptions, awsEnv: NodeJS.ProcessEnv, dependencies: ProjectArchiveCommandDependencies): Promise<boolean>;
 export declare function runArchiveSyncCommand(dependencies: ProjectArchiveCommandDependencies, projectName: string | undefined, options: ArchiveSyncOptions, context: CommandContext, commandLabel?: string): Promise<void>;

package/dist/commands/project/archive/sync-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-runner.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/sync-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync-runner.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/sync-runner.ts"],"names":[],"mappings":"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"}

package/dist/commands/project/archive/sync-runner.js

@@ -80,11 +80,18 @@ export async function listArchiveSnapshots(repoRoot, projectsRoot, s3Uri, awsEnv
         return {
             ...parsed,
             source: dependencies.buildProjectArchiveS3Uri(s3Uri, remoteRepoRoot, snapshotName),
-            target: dependencies.resolveLocalArchiveProjectPath(projectsRoot, parsed.projectName),
+            target: dependencies.resolveLocalArchiveProjectPath(projectsRoot, parsed.localName),
         };
     });
 }
+/**
+ * Orders snapshots oldest to latest: a later generation is later regardless
+ * of date, then a later date, then the snapshot name.
+ */
 export function compareSnapshotEntries(left, right) {
+    if (left.generation !== right.generation) {
+        return left.generation - right.generation;
+    }
     if (left.dateStamp && right.dateStamp && left.dateStamp !== right.dateStamp) {
         return left.dateStamp.localeCompare(right.dateStamp);
     }
@@ -96,15 +103,45 @@ export function compareSnapshotEntries(left, right) {
     }
     return left.snapshotName.localeCompare(right.snapshotName);
 }
+/**
+ * The latest snapshot for each local archive: every generation keeps its own
+ * local directory, so each one is hydrated from its own latest snapshot.
+ */
 export function selectLatestSnapshots(snapshots) {
-    const latestByProject = new Map();
+    const latestByLocalName = new Map();
     for (const snapshot of snapshots) {
-        const current = latestByProject.get(snapshot.projectName);
+        const current = latestByLocalName.get(snapshot.localName);
+        if (!current || compareSnapshotEntries(snapshot, current) > 0) {
+            latestByLocalName.set(snapshot.localName, snapshot);
+        }
+    }
+    return [...latestByLocalName.values()];
+}
+/**
+ * The snapshots a by-name sync restores, in precedence order: an exact
+ * snapshot name; else a full generation name such as `demo-g2` or
+ * `demo-g2-local` (which also keeps a project literally named `demo-g2`
+ * reachable); else every generation family the name identifies, either as a
+ * family (`demo-local`: the local-scope `demo` archives) or as the base
+ * project (`demo`: `demo` and its scope-qualified families). Each family
+ * restores its latest generation, then its latest date.
+ */
+export function selectNamedSnapshotCandidates(snapshots, name) {
+    const exactSnapshot = snapshots.filter((snapshot) => snapshot.snapshotName === name);
+    const fullName = snapshots.filter((snapshot) => snapshot.localName === name && snapshot.generation > 1);
+    const pool = exactSnapshot.length > 0
+        ? exactSnapshot
+        : fullName.length > 0
+            ? fullName
+            : snapshots.filter((snapshot) => snapshot.familyName === name || snapshot.projectName === name);
+    const latestByFamily = new Map();
+    for (const snapshot of pool) {
+        const current = latestByFamily.get(snapshot.familyName);
         if (!current || compareSnapshotEntries(snapshot, current) > 0) {
-            latestByProject.set(snapshot.projectName, snapshot);
+            latestByFamily.set(snapshot.familyName, snapshot);
         }
     }
-    return [...latestByProject.values()];
+    return [...latestByFamily.values()];
 }
 export async function readLocalSnapshotName(repoRoot, target) {
     try {
@@ -152,27 +189,12 @@ export async function runArchiveSyncCommand(dependencies, projectName, options,
         const projectsRoot = await dependencies.resolveProjectsRoot(repoRoot, dependencies.processEnv);
         const snapshots = await listArchiveSnapshots(repoRoot, projectsRoot, s3Uri, awsEnv, dependencies);
         const targets = projectName
-            ? snapshots.filter((snapshot) => snapshot.projectName === projectName ||
-                snapshot.snapshotName === projectName)
+            ? selectNamedSnapshotCandidates(snapshots, projectName)
             : selectLatestSnapshots(snapshots);
         if (projectName && targets.length === 0) {
             throw new CliError(`No archived snapshot found in S3 for project \`${projectName}\`.`);
         }
-        const latestTarget = projectName
-            ? targets.reduce((latest, snapshot) => {
-                if (!latest) {
-                    return snapshot;
-                }
-                return compareSnapshotEntries(snapshot, latest) > 0
-                    ? snapshot
-                    : latest;
-            }, null)
-            : null;
-        const snapshotsToSync = projectName
-            ? latestTarget
-                ? [latestTarget]
-                : []
-            : targets;
+        const snapshotsToSync = targets;
         const appliedTargets = [];
         const appliedSources = [];
         for (const snapshot of snapshotsToSync) {

package/dist/commands/project/complete-state/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/complete-state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,IAAI,eAAe,EAC3B,SAAS,IAAI,gBAAgB,EAC9B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAIL,KAAK,yBAAyB,EAC/B,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,UAAU,gCAAiC,SAAQ,yBAAyB;IAC1E,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,EAAE,OAAO,eAAe,CAAC;IACjC,SAAS,EAAE,OAAO,gBAAgB,CAAC;IACnC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAkFD,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,gCAAgC,CAAM,GACxD,OAAO,CA+BT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/complete-state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,IAAI,eAAe,EAC3B,SAAS,IAAI,gBAAgB,EAC9B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAIL,KAAK,yBAAyB,EAC/B,MAAM,wCAAwC,CAAC;AAMhD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,UAAU,gCAAiC,SAAQ,yBAAyB;IAC1E,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,EAAE,OAAO,eAAe,CAAC;IACjC,SAAS,EAAE,OAAO,gBAAgB,CAAC;IACnC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAiID,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,gCAAgC,CAAM,GACxD,OAAO,CA+BT"}

package/dist/commands/project/complete-state/index.js

@@ -1,6 +1,9 @@
 import { readFile as defaultReadFile, writeFile as defaultWriteFile, } from 'node:fs/promises';
+import { join } from 'node:path';
 import { buildCommandContext } from '../../../app/command-context.js';
+import { readStateWorkflowMode } from '../../project/closeout-check/closeout-invariant.js';
 import { checkProjectCloseout, DEFAULT_CLOSEOUT_CHECK_DEPENDENCIES, formatCloseoutRefusal, } from '../../project/closeout-check/index.js';
+import { evaluateJournal, formatJournalRefusal, } from '../../project/journal-check/index.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { resolveEffectiveConfig } from '../../../config/resolve.js';
 import { CliError } from '../../../errors/cli-error.js';
@@ -35,6 +38,48 @@ async function runProjectCompleteState(projectPath, options, context, dependenci
         if (result.status === 'incomplete') {
             throw new CliError(formatCloseoutRefusal(projectPath, result), 1);
         }
+        // Immediately before the write, the final journal evaluator: a project
+        // that has a journal completes only when that journal holds its terminal
+        // shape. Both guards refuse before any write; no override bypasses the
+        // closeout invariant above.
+        const journalPath = join(targetProjectPath, 'implementation.md');
+        const planPath = join(targetProjectPath, 'plan.md');
+        const hasJournal = await dependencies.fileExists(journalPath);
+        if (!hasJournal && (await dependencies.fileExists(planPath))) {
+            // A planned project completes only through its journal: a missing
+            // journal must never silently turn the final evaluator off.
+            throw new CliError(formatJournalRefusal(projectPath, {
+                status: 'refused',
+                boundary: 'completion',
+                workflowMode: readStateWorkflowMode(content) ?? 'spec-driven',
+                scope: null,
+                reasons: [
+                    {
+                        code: 'journal-missing',
+                        path: 'implementation.md',
+                        line: null,
+                        owner: 'oat-project-implement',
+                        message: 'plan.md exists but implementation.md is missing; a planned project completes only with its journal.',
+                    },
+                ],
+                warnings: [],
+                overrides: [],
+            }), 1);
+        }
+        if (hasJournal) {
+            const journal = evaluateJournal({
+                boundary: 'completion',
+                scope: null,
+                planContent: (await dependencies.fileExists(planPath))
+                    ? await dependencies.readFile(planPath, 'utf8')
+                    : '',
+                journalContent: await dependencies.readFile(journalPath, 'utf8'),
+                stateContent: content,
+            });
+            if (journal.status === 'refused') {
+                throw new CliError(formatJournalRefusal(projectPath, journal), 1);
+            }
+        }
         const now = dependencies.now();
         const updatedContent = renderCompletedProjectState(content, {
             archived: options.archived ?? false,

package/dist/commands/project/dispatch/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,MAAM,WAAW,kCAAkC;IACjD,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC;AAiHD,wBAAgB,4BAA4B,CAC1C,SAAS,GAAE,OAAO,CAAC,kCAAkC,CAAM,GAC1D,OAAO,CA0BT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC,MAAM,WAAW,kCAAkC;IACjD,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC;AAsID,wBAAgB,4BAA4B,CAC1C,SAAS,GAAE,OAAO,CAAC,kCAAkC,CAAM,GAC1D,OAAO,CAkCT"}

package/dist/commands/project/dispatch/index.js

@@ -4,7 +4,8 @@ import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
 import { Command } from 'commander';
 import { createCanonicalRoleCommand } from './canonical-role.js';
-import { recordProjectDispatch, redactDispatchMessage, } from './record.js';
+import { assertFormalDispatchStamp, projectDispatchRunLine, recordProjectDispatch, redactDispatchMessage, } from './record.js';
+const RECORD_FORMATS = ['text', 'line'];
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveProjectRoot,
@@ -54,6 +55,10 @@ function runtimeIdentityLines(identity) {
 async function runRecordCommand(options, context, dependencies) {
     let repoRoot = null;
     try {
+        const format = options.format ?? 'text';
+        if (!RECORD_FORMATS.includes(format)) {
+            throw new Error(`Unknown --format ${format}; expected one of ${RECORD_FORMATS.join(', ')}.`);
+        }
         repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const content = options.eventFile === '-'
             ? await dependencies.readStdin()
@@ -77,8 +82,23 @@ async function runRecordCommand(options, context, dependencies) {
                     }),
             },
         };
+        // The stamp is caller-supplied text, so it passes the same redaction
+        // boundary before it can reach the projection.
+        const dispatchStamp = options.dispatchStamp === undefined
+            ? null
+            : redactDispatchMessage(options.dispatchStamp, {
+                repo: repoRoot,
+                home: context.home,
+            });
+        if (dispatchStamp !== null) {
+            assertFormalDispatchStamp(dispatchStamp);
+        }
+        const runLine = projectDispatchRunLine(result, { dispatchStamp });
         if (context.json) {
-            context.logger.json(result);
+            context.logger.json({ ...result, runLine });
+        }
+        else if (format === 'line') {
+            context.logger.info(runLine.line);
         }
         else {
             context.logger.info('Dispatch evidence is valid; nothing was written.');
@@ -107,6 +127,8 @@ export function createProjectDispatchCommand(overrides = {}) {
         .addCommand(new Command('record')
         .description('Validate one generic dispatch plus namespaced OAT evidence (writes nothing)')
         .requiredOption('--event-file <json-file-or-dash>', 'Complete record and event JSON file, or - for standard input')
+        .option('--format <format>', 'Text output: text (default) or line (one journal run line, run/v1)')
+        .option('--dispatch-stamp <line>', 'Formal "Dispatch:" stamp copied verbatim from the resolver into the run line')
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         await runRecordCommand(options, context, dependencies);

package/dist/commands/project/dispatch/record.d.ts

@@ -1,4 +1,4 @@
-import { type GenericDispatchRecord } from '../../../providers/identity/generic-dispatch-record.js';
+import { type DispatchTerminalClassification, type GenericDispatchRecord } from '../../../providers/identity/generic-dispatch-record.js';
 import { type OatDispatchEvidenceEvent, type PersistedOatDispatchRecordV1 } from '../../../providers/identity/oat-dispatch-record.js';
 /**
  * Hard redaction boundary. Producers redact their own messages, but this is the
@@ -67,6 +67,59 @@ export type ProjectDispatchRecordResult = {
     record: PersistedOatDispatchRecordV1;
     runtimeIdentity: DispatchRecordRuntimeIdentity;
 };
+/**
+ * One-line journal run record, projection v1.
+ *
+ * An additive rendering of the same validated, redacted record and event: one
+ * line per request id, written by the owning skill under
+ * `## Orchestration Runs` and updated in place with the terminal outcome. The
+ * renderer writes nothing.
+ *
+ * Grammar: `run/v1` followed by named `key=value` fields in the fixed order of
+ * `DISPATCH_RUN_LINE_FIELDS`, joined by ` · `. Inside a value, `\\`, `\·`,
+ * `\~`, `\n` and `\r` escape a backslash, the delimiter, a literal tilde, a
+ * newline and a carriage return; a bare `~` value is null. The configured
+ * identity (`target`, `model`, `effort`) and the observed identity are
+ * separate fields: an observation never replaces the configured invocation.
+ */
+export declare const DISPATCH_RUN_LINE_PREFIX = "run/v1";
+export declare const DISPATCH_RUN_LINE_DELIMITER = " \u00B7 ";
+export declare const DISPATCH_RUN_LINE_FIELDS: readonly ['request', 'scope', 'action', 'role', 'target', 'model', 'effort', 'stamp', 'launch', 'outcome', 'terminal', 'class', 'continuation', 'observed', 'match'];
+export type DispatchRunLineField = (typeof DISPATCH_RUN_LINE_FIELDS)[number];
+export type DispatchRunLineFields = Record<DispatchRunLineField, string | null>;
+export interface DispatchRunLineProjection {
+    version: 1;
+    line: string;
+    fields: DispatchRunLineFields;
+    classification: DispatchTerminalClassification;
+    terminal: boolean;
+}
+export declare function renderDispatchRunLine(fields: DispatchRunLineFields): string;
+export type ParsedDispatchRunLine = {
+    ok: true;
+    fields: DispatchRunLineFields;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Parse one journal run line (optionally written as a `- ` list item). Every
+ * field must be present exactly once, in order; anything else is malformed.
+ * Callers derive terminality from `launch` and `outcome` with
+ * `classifyDispatchOutcome`, never from the recorded `terminal` text alone.
+ */
+export declare function parseDispatchRunLine(text: string): ParsedDispatchRunLine;
+/**
+ * Validate a caller-supplied formal `Dispatch:` stamp: one line with the
+ * canonical prefix that parses as a modern stamp. The stamp comes from the
+ * resolver's `dispatchStamp` field; the projection carries it verbatim and
+ * never assembles one.
+ */
+export declare function assertFormalDispatchStamp(stamp: string): void;
+/** Project a validated record result onto the one-line run record. */
+export declare function projectDispatchRunLine(result: ProjectDispatchRecordResult, options?: {
+    dispatchStamp?: string | null;
+}): DispatchRunLineProjection;
 export declare function parseDispatchRecordInput(value: unknown): DispatchRecordInput;
 /**
  * Validate one dispatch record and event and return the augmented record. Parse

package/dist/commands/project/dispatch/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch/record.ts"],"names":[],"mappings":"AAYA,OAAO,EAKL,KAAK,qBAAqB,EAC3B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAOL,KAAK,wBAAwB,EAE7B,KAAK,4BAA4B,EAElC,MAAM,yCAAyC,CAAC;AASjD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,GAAE;IACL,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjB,GACL,MAAM,CAgBR;AAeD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,KAAK,EAAE,wBAAwB,CAAC;IAChC,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;IACF,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,GAAG,IAAI,CAAC;IACT,KAAK,EAAE,UAAU,GAAG,aAAa,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC5D;;;OAGG;IACH,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,4BAA4B,CAAC;IACrC,eAAe,EAAE,6BAA6B,CAAC;CAChD,CAAC;AA8NF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA6G5E;AAoCD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE;IACjD,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAWvC"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch/record.ts"],"names":[],"mappings":"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"}