@funnelsgrove/cli 0.1.19 → 0.1.24

package/dist/experimentCreate.js

@@ -0,0 +1,887 @@
+import { Buffer } from 'node:buffer';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, readFile, readdir, realpath, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { SYNC_MANIFEST_FILE, assertSafeRootFileWriteTarget, assertSafeSyncPath, readSyncManifest, readSafeRootFile, writeSafeRootFile, writeSourceFiles, writeSyncManifest, } from './localSync.js';
+export const EXPERIMENT_GENERATED_PATHS = [
+    'src/config/experiments.generated.ts',
+    'src/config/experiments.ts',
+];
+const EXPERIMENT_GENERATED_CONTENT_TYPE = 'text/typescript';
+const LOWERCASE_SHA256 = /^[a-f0-9]{64}$/;
+const EXPERIMENT_METRICS = [
+    'step_completion',
+    'next_step_reached',
+    'checkout_opened',
+    'funnel_completed',
+    'paying_customer',
+];
+export class ExperimentCreateContractError extends Error {
+    constructor(fieldPath, reason) {
+        super(`${fieldPath}: ${reason}`);
+        this.name = 'ExperimentCreateContractError';
+    }
+}
+function fail(fieldPath, reason) {
+    throw new ExperimentCreateContractError(fieldPath, reason);
+}
+const isRecord = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value));
+const requireRecord = (value, fieldPath) => {
+    if (!isRecord(value)) {
+        fail(fieldPath, 'must be an object');
+    }
+    return value;
+};
+const assertExactKeys = (value, allowedKeys, fieldPath) => {
+    const allowed = new Set(allowedKeys);
+    const unknownKey = Object.keys(value).find((key) => !allowed.has(key));
+    if (unknownKey !== undefined) {
+        fail(fieldPath ? `${fieldPath}.${unknownKey}` : unknownKey, 'unknown field');
+    }
+};
+const requireString = (value, fieldPath, maxLength) => {
+    if (typeof value !== 'string') {
+        fail(fieldPath, 'must be a string');
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        fail(fieldPath, 'must not be empty');
+    }
+    if (maxLength !== undefined && trimmed.length > maxLength) {
+        fail(fieldPath, `must contain at most ${maxLength} characters`);
+    }
+    return trimmed;
+};
+const requireBoolean = (value, fieldPath) => {
+    if (typeof value !== 'boolean') {
+        fail(fieldPath, 'must be a boolean');
+    }
+    return value;
+};
+const requireInteger = (value, fieldPath, minimum, maximum) => {
+    if (typeof value !== 'number'
+        || !Number.isInteger(value)
+        || value < minimum
+        || value > maximum) {
+        fail(fieldPath, `must be an integer from ${minimum} to ${maximum}`);
+    }
+    return value;
+};
+const requireMetric = (value, fieldPath) => {
+    if (!EXPERIMENT_METRICS.includes(value)) {
+        fail(fieldPath, `must be one of ${EXPERIMENT_METRICS.join(', ')}`);
+    }
+    return value;
+};
+const compareExperimentVariants = (left, right) => {
+    if (left.isControl !== right.isControl) {
+        return left.isControl ? -1 : 1;
+    }
+    const leftIsLiteralControl = left.variantKey === 'control';
+    const rightIsLiteralControl = right.variantKey === 'control';
+    if (leftIsLiteralControl !== rightIsLiteralControl) {
+        return leftIsLiteralControl ? -1 : 1;
+    }
+    return Buffer.compare(Buffer.from(left.variantKey), Buffer.from(right.variantKey));
+};
+const parseVariant = (value, index, type) => {
+    const fieldPath = `variants[${index}]`;
+    const record = requireRecord(value, fieldPath);
+    const keys = [
+        'variantKey',
+        'label',
+        'routeToStepId',
+        'trafficPercent',
+        'isControl',
+        ...(type === 'pricing' ? ['offerSetKey'] : []),
+    ];
+    assertExactKeys(record, keys, fieldPath);
+    const shared = {
+        variantKey: requireString(record.variantKey, `${fieldPath}.variantKey`, 120),
+        label: requireString(record.label, `${fieldPath}.label`, 200),
+        routeToStepId: requireString(record.routeToStepId, `${fieldPath}.routeToStepId`, 200),
+        trafficPercent: requireInteger(record.trafficPercent, `${fieldPath}.trafficPercent`, 0, 100),
+        isControl: requireBoolean(record.isControl, `${fieldPath}.isControl`),
+    };
+    if (type !== 'pricing') {
+        return shared;
+    }
+    return {
+        ...shared,
+        offerSetKey: requireString(record.offerSetKey, `${fieldPath}.offerSetKey`, 200),
+    };
+};
+export function parseAgentExperimentSpec(value) {
+    const record = requireRecord(value, 'spec');
+    assertExactKeys(record, [
+        'id',
+        'name',
+        'type',
+        'stepId',
+        'primaryMetric',
+        'trackedMetrics',
+        'variants',
+    ], '');
+    if (record.type !== 'step' && record.type !== 'paywall' && record.type !== 'pricing') {
+        fail('type', 'must be one of step, paywall, pricing');
+    }
+    const type = record.type;
+    const id = requireString(record.id, 'id', 200);
+    const name = requireString(record.name, 'name', 200);
+    const stepId = requireString(record.stepId, 'stepId', 200);
+    const primaryMetric = requireMetric(record.primaryMetric, 'primaryMetric');
+    if (!Array.isArray(record.trackedMetrics) || record.trackedMetrics.length < 1) {
+        fail('trackedMetrics', 'must contain at least one metric');
+    }
+    const trackedMetrics = record.trackedMetrics.map((metric, index) => (requireMetric(metric, `trackedMetrics[${index}]`)));
+    if (new Set(trackedMetrics).size !== trackedMetrics.length) {
+        fail('trackedMetrics', 'must contain unique metrics');
+    }
+    if (!trackedMetrics.includes(primaryMetric)) {
+        fail('primaryMetric', 'must be included in trackedMetrics');
+    }
+    if (!Array.isArray(record.variants) || record.variants.length < 2 || record.variants.length > 5) {
+        fail('variants', 'must contain two to five variants');
+    }
+    const variants = record.variants.map((variant, index) => parseVariant(variant, index, type));
+    const keys = variants.map((variant) => variant.variantKey);
+    if (new Set(keys).size !== keys.length) {
+        fail('variants', 'variant keys must be unique');
+    }
+    if (variants.filter((variant) => variant.isControl).length !== 1) {
+        fail('variants', 'must include exactly one control');
+    }
+    if (variants.reduce((total, variant) => total + variant.trafficPercent, 0) !== 100) {
+        fail('variants', 'trafficPercent values must total 100');
+    }
+    if (type === 'pricing') {
+        variants.forEach((variant, index) => {
+            if (variant.routeToStepId !== stepId) {
+                fail(`variants[${index}].routeToStepId`, 'must match stepId for pricing experiments');
+            }
+        });
+    }
+    const canonicalVariants = [...variants].sort(compareExperimentVariants);
+    const shared = { id, name, stepId, primaryMetric, trackedMetrics };
+    if (type === 'pricing') {
+        return {
+            ...shared,
+            type,
+            variants: canonicalVariants,
+        };
+    }
+    return {
+        ...shared,
+        type,
+        variants: canonicalVariants,
+    };
+}
+export async function readAgentExperimentSpec(filePath) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(filePath, 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            fail(filePath, 'invalid JSON');
+        }
+        throw error;
+    }
+    return parseAgentExperimentSpec(value);
+}
+const parseGeneratedExperimentFiles = (value) => {
+    if (!Array.isArray(value) || value.length !== EXPERIMENT_GENERATED_PATHS.length) {
+        fail('generatedFiles', 'must contain exactly the two generated experiment files');
+    }
+    const files = value.map((entry, index) => {
+        const fieldPath = `generatedFiles[${index}]`;
+        const record = requireRecord(entry, fieldPath);
+        assertExactKeys(record, ['path', 'content', 'contentType'], fieldPath);
+        const expectedPath = EXPERIMENT_GENERATED_PATHS[index];
+        if (record.path !== expectedPath) {
+            fail(`${fieldPath}.path`, `must equal ${expectedPath}`);
+        }
+        if (record.contentType !== EXPERIMENT_GENERATED_CONTENT_TYPE) {
+            fail(`${fieldPath}.contentType`, `must equal ${EXPERIMENT_GENERATED_CONTENT_TYPE}`);
+        }
+        if (typeof record.content !== 'string') {
+            fail(`${fieldPath}.content`, 'must be a string');
+        }
+        return {
+            path: expectedPath,
+            content: record.content,
+            contentType: EXPERIMENT_GENERATED_CONTENT_TYPE,
+        };
+    });
+    return [files[0], files[1]];
+};
+const EXPERIMENT_ROW_KEYS = [
+    'conversion_config',
+    'created_at',
+    'ended_at',
+    'funnel_id',
+    'id',
+    'name',
+    'paused_at',
+    'posthog_flag_id',
+    'posthog_flag_key',
+    'primary_metric',
+    'project_id',
+    'started_at',
+    'status',
+    'step_id',
+    'tracked_metrics',
+    'updated_at',
+];
+const VARIANT_ROW_KEYS = [
+    'created_at',
+    'experiment_id',
+    'id',
+    'is_control',
+    'label',
+    'route_to_step_id',
+    'traffic_percent',
+    'updated_at',
+    'variant_key',
+];
+const requireNull = (value, fieldPath) => {
+    if (value !== null) {
+        fail(fieldPath, 'must be null for a draft experiment');
+    }
+    return null;
+};
+const expectedConversionConfig = (spec) => (spec.type === 'pricing'
+    ? {
+        source: 'agent',
+        type: 'pricing',
+        paywallStepId: spec.stepId,
+        offerSetKeys: spec.variants.map((variant) => variant.offerSetKey),
+    }
+    : {
+        source: 'agent',
+        type: spec.type,
+        stepId: spec.stepId,
+        variantStepIds: spec.variants.map((variant) => variant.routeToStepId),
+    });
+export function parseExperimentCreateResponse(value, requestedSpec, expectedFunnelIdValue) {
+    const spec = parseAgentExperimentSpec(requestedSpec);
+    const expectedFunnelId = requireString(expectedFunnelIdValue, 'expectedFunnelId');
+    const response = requireRecord(value, 'response');
+    assertExactKeys(response, [
+        'experiment',
+        'variants',
+        'draftVersionId',
+        'generatedFiles',
+        'githubConnected',
+    ], '');
+    const experiment = requireRecord(response.experiment, 'experiment');
+    assertExactKeys(experiment, EXPERIMENT_ROW_KEYS, 'experiment');
+    const experimentId = requireString(experiment.id, 'experiment.id');
+    requireString(experiment.project_id, 'experiment.project_id');
+    const experimentFunnelId = requireString(experiment.funnel_id, 'experiment.funnel_id');
+    if (experimentFunnelId !== expectedFunnelId) {
+        fail('experiment.funnel_id', 'does not match the requested funnel');
+    }
+    if (experiment.status !== 'draft')
+        fail('experiment.status', 'must equal draft');
+    if (experiment.posthog_flag_key !== spec.id) {
+        fail('experiment.posthog_flag_key', `must equal requested experiment id ${spec.id}`);
+    }
+    if (experiment.step_id !== spec.stepId)
+        fail('experiment.step_id', 'does not match requested spec');
+    if (experiment.name !== spec.name)
+        fail('experiment.name', 'does not match requested spec');
+    if (experiment.primary_metric !== spec.primaryMetric) {
+        fail('experiment.primary_metric', 'does not match requested spec');
+    }
+    if (!isDeepStrictEqual(experiment.tracked_metrics, spec.trackedMetrics)) {
+        fail('experiment.tracked_metrics', 'does not match requested spec');
+    }
+    if (!isDeepStrictEqual(experiment.conversion_config, expectedConversionConfig(spec))) {
+        fail('experiment.conversion_config', 'does not match requested spec');
+    }
+    requireNull(experiment.posthog_flag_id, 'experiment.posthog_flag_id');
+    requireNull(experiment.started_at, 'experiment.started_at');
+    requireNull(experiment.paused_at, 'experiment.paused_at');
+    requireNull(experiment.ended_at, 'experiment.ended_at');
+    requireString(experiment.created_at, 'experiment.created_at');
+    requireString(experiment.updated_at, 'experiment.updated_at');
+    if (!Array.isArray(response.variants) || response.variants.length !== spec.variants.length) {
+        fail('variants', 'must match the requested canonical variants');
+    }
+    const variants = response.variants.map((value, index) => {
+        const fieldPath = `variants[${index}]`;
+        const variant = requireRecord(value, fieldPath);
+        assertExactKeys(variant, VARIANT_ROW_KEYS, fieldPath);
+        const expected = spec.variants[index];
+        requireString(variant.id, `${fieldPath}.id`);
+        if (variant.experiment_id !== experimentId) {
+            fail(`${fieldPath}.experiment_id`, 'must equal experiment.id');
+        }
+        if (variant.variant_key !== expected.variantKey) {
+            fail('variants', 'must use canonical experiment variant ordering');
+        }
+        if (variant.label !== expected.label)
+            fail(`${fieldPath}.label`, 'does not match requested spec');
+        if (variant.route_to_step_id !== expected.routeToStepId) {
+            fail(`${fieldPath}.route_to_step_id`, 'does not match requested spec');
+        }
+        if (variant.traffic_percent !== expected.trafficPercent) {
+            fail(`${fieldPath}.traffic_percent`, 'does not match requested spec');
+        }
+        if (variant.is_control !== expected.isControl) {
+            fail(`${fieldPath}.is_control`, 'does not match requested spec');
+        }
+        requireString(variant.created_at, `${fieldPath}.created_at`);
+        requireString(variant.updated_at, `${fieldPath}.updated_at`);
+        return variant;
+    });
+    const variantIds = variants.map((variant) => variant.id);
+    if (new Set(variantIds).size !== variantIds.length) {
+        fail('variants', 'must contain unique persisted variant ids');
+    }
+    const draftVersionId = requireString(response.draftVersionId, 'draftVersionId');
+    const generatedFiles = parseGeneratedExperimentFiles(response.generatedFiles);
+    const githubConnected = requireBoolean(response.githubConnected, 'githubConnected');
+    return {
+        experiment: experiment,
+        variants,
+        draftVersionId,
+        generatedFiles,
+        githubConnected,
+    };
+}
+const validateManifest = (value) => {
+    const manifest = requireRecord(value, 'manifest');
+    assertExactKeys(manifest, ['version', 'workspaceId', 'funnelId', 'draftVersionId', 'files'], 'manifest');
+    if (manifest.version !== 1)
+        fail('manifest.version', 'must equal 1');
+    const workspaceId = requireString(manifest.workspaceId, 'manifest.workspaceId');
+    const funnelId = requireString(manifest.funnelId, 'manifest.funnelId');
+    const draftVersionId = requireString(manifest.draftVersionId, 'manifest.draftVersionId');
+    if (!Array.isArray(manifest.files))
+        fail('manifest.files', 'must be an array');
+    const seenPaths = new Set();
+    const generatedPathByFoldedPath = new Map(EXPERIMENT_GENERATED_PATHS.map((generatedPath) => [generatedPath.toLowerCase(), generatedPath]));
+    const files = manifest.files.map((value, index) => {
+        const fieldPath = `manifest.files[${index}]`;
+        const entry = requireRecord(value, fieldPath);
+        assertExactKeys(entry, ['path', 'hash'], fieldPath);
+        const rawPath = entry.path;
+        const filePath = requireString(rawPath, `${fieldPath}.path`);
+        try {
+            assertSafeSyncPath(rawPath);
+        }
+        catch {
+            fail(`${fieldPath}.path`, 'must be a safe canonical relative POSIX path');
+        }
+        if (typeof entry.hash !== 'string' || !LOWERCASE_SHA256.test(entry.hash)) {
+            fail(`${fieldPath}.hash`, 'must be a lowercase SHA-256 hash');
+        }
+        if (seenPaths.has(filePath)) {
+            fail('manifest.files', `contains duplicate path ${filePath}`);
+        }
+        const foldedPath = filePath.toLowerCase();
+        const generatedPath = generatedPathByFoldedPath.get(foldedPath);
+        if (generatedPath !== undefined && filePath !== generatedPath) {
+            fail('manifest.files', `contains a non-canonical case variant ${filePath}`);
+        }
+        seenPaths.add(filePath);
+        return { path: filePath, hash: entry.hash };
+    });
+    return { version: 1, workspaceId, funnelId, draftVersionId, files };
+};
+const isErrno = (error, code) => (error instanceof Error && 'code' in error && error.code === code);
+export async function assertGeneratedExperimentFilesUnchanged(root, manifestValue) {
+    const manifest = validateManifest(manifestValue);
+    const baselineByPath = new Map(manifest.files.map((file) => [file.path, file.hash]));
+    for (const generatedPath of EXPERIMENT_GENERATED_PATHS) {
+        const baselineHash = baselineByPath.get(generatedPath);
+        let currentBytes;
+        try {
+            currentBytes = await readSafeRootFile(root, generatedPath);
+        }
+        catch (error) {
+            if (!isErrno(error, 'ENOENT'))
+                throw error;
+            if (baselineHash !== undefined) {
+                fail(generatedPath, 'was locally modified or deleted');
+            }
+            continue;
+        }
+        if (baselineHash === undefined) {
+            fail(generatedPath, 'exists without a trustworthy manifest baseline');
+        }
+        const currentHash = createHash('sha256').update(currentBytes).digest('hex');
+        if (currentHash !== baselineHash) {
+            fail(generatedPath, 'was locally modified');
+        }
+    }
+}
+export function buildExperimentCreateManifest(manifestValue, draftVersionIdValue, filesValue) {
+    const manifest = validateManifest(manifestValue);
+    const draftVersionId = requireString(draftVersionIdValue, 'draftVersionId');
+    const files = parseGeneratedExperimentFiles(filesValue);
+    const nextHashByPath = new Map(files.map((file) => [
+        file.path,
+        createHash('sha256').update(file.content).digest('hex'),
+    ]));
+    const replacedPaths = new Set();
+    const nextFiles = manifest.files.map((file) => {
+        const nextHash = nextHashByPath.get(file.path);
+        if (nextHash === undefined)
+            return { ...file };
+        replacedPaths.add(file.path);
+        return { path: file.path, hash: nextHash };
+    });
+    for (const generatedPath of EXPERIMENT_GENERATED_PATHS) {
+        if (!replacedPaths.has(generatedPath)) {
+            nextFiles.push({ path: generatedPath, hash: nextHashByPath.get(generatedPath) });
+        }
+    }
+    return {
+        ...manifest,
+        draftVersionId,
+        files: nextFiles,
+    };
+}
+const EXPERIMENT_CREATE_TRANSACTION_PARENT = '.funnelsgrove/transactions';
+const EXPERIMENT_CREATE_READY_DIRECTORY = `${EXPERIMENT_CREATE_TRANSACTION_PARENT}/experiment-create`;
+const EXPERIMENT_CREATE_PREPARING_PREFIX = `${EXPERIMENT_CREATE_TRANSACTION_PARENT}/experiment-create-preparing-`;
+const EXPERIMENT_CREATE_STAGED_PATHS = [
+    'experiments.generated.ts',
+    'experiments.ts',
+];
+const EXPERIMENT_CREATE_MANIFEST_STAGED_PATH = 'manifest.json';
+const EXPERIMENT_CREATE_JOURNAL_PATH = 'journal.json';
+const EXPERIMENT_CREATE_MANIFEST_CONTENT_TYPE = 'application/json';
+const experimentCreateTransactionError = (reason) => (new Error(`Invalid experiment-create transaction: ${reason}`));
+const sha256Buffer = (content) => createHash('sha256')
+    .update(content)
+    .digest('hex');
+const serializedManifest = (manifest) => Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+const transactionRelativePath = (directory, filePath) => (`${directory}/${filePath}`);
+const syncDirectory = async (directoryPath) => {
+    const handle = await open(directoryPath, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const readManifestBytes = async (root) => {
+    const bytes = await readSafeRootFile(root, SYNC_MANIFEST_FILE);
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw experimentCreateTransactionError('sync manifest is not valid JSON');
+    }
+    try {
+        return { manifest: validateManifest(value), bytes };
+    }
+    catch {
+        throw experimentCreateTransactionError('sync manifest is invalid');
+    }
+};
+const assertTransactionArtifactEntries = async (root) => {
+    const readyPath = path.join(root, ...EXPERIMENT_CREATE_READY_DIRECTORY.split('/'));
+    const entries = await readdir(readyPath, { withFileTypes: true });
+    const expected = [
+        ...EXPERIMENT_CREATE_STAGED_PATHS,
+        EXPERIMENT_CREATE_MANIFEST_STAGED_PATH,
+        EXPERIMENT_CREATE_JOURNAL_PATH,
+    ].sort();
+    if (entries.some((entry) => !entry.isFile() || entry.isSymbolicLink())
+        || !isDeepStrictEqual(entries.map((entry) => entry.name).sort(), expected)) {
+        throw experimentCreateTransactionError('artifact set or type is invalid');
+    }
+};
+const requireTransactionString = (value, fieldPath) => {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw experimentCreateTransactionError(`${fieldPath} must be a non-empty string`);
+    }
+    return value;
+};
+const requireTransactionHash = (value, fieldPath) => {
+    if (typeof value !== 'string' || !LOWERCASE_SHA256.test(value)) {
+        throw experimentCreateTransactionError(`${fieldPath} must be a lowercase SHA-256 hash`);
+    }
+    return value;
+};
+const requireTransactionBytes = (value, fieldPath) => {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw experimentCreateTransactionError(`${fieldPath} must be a non-negative byte count`);
+    }
+    return value;
+};
+const requireExactTransactionKeys = (value, keys, fieldPath) => {
+    if (Object.keys(value).length !== keys.length
+        || keys.some((key) => !Object.hasOwn(value, key))) {
+        throw experimentCreateTransactionError(`${fieldPath} has an invalid shape`);
+    }
+};
+const parseExperimentCreateJournal = (value) => {
+    if (!isRecord(value))
+        throw experimentCreateTransactionError('journal must be an object');
+    requireExactTransactionKeys(value, [
+        'version',
+        'workspaceId',
+        'funnelId',
+        'baseDraftVersionId',
+        'draftVersionId',
+        'baseManifestSha256',
+        'files',
+        'manifest',
+    ], 'journal');
+    if (value.version !== 1)
+        throw experimentCreateTransactionError('journal version is unsupported');
+    if (!Array.isArray(value.files) || value.files.length !== 2) {
+        throw experimentCreateTransactionError('journal files must contain exactly two entries');
+    }
+    const files = value.files.map((file, index) => {
+        if (!isRecord(file))
+            throw experimentCreateTransactionError(`journal.files[${index}] must be an object`);
+        requireExactTransactionKeys(file, ['path', 'stagedPath', 'contentType', 'sha256', 'bytes'], `journal.files[${index}]`);
+        if (file.path !== EXPERIMENT_GENERATED_PATHS[index]
+            || file.stagedPath !== EXPERIMENT_CREATE_STAGED_PATHS[index]
+            || file.contentType !== EXPERIMENT_GENERATED_CONTENT_TYPE) {
+            throw experimentCreateTransactionError(`journal.files[${index}] does not use the fixed file contract`);
+        }
+        return {
+            path: EXPERIMENT_GENERATED_PATHS[index],
+            stagedPath: EXPERIMENT_CREATE_STAGED_PATHS[index],
+            contentType: EXPERIMENT_GENERATED_CONTENT_TYPE,
+            sha256: requireTransactionHash(file.sha256, `journal.files[${index}].sha256`),
+            bytes: requireTransactionBytes(file.bytes, `journal.files[${index}].bytes`),
+        };
+    });
+    if (!isRecord(value.manifest)) {
+        throw experimentCreateTransactionError('journal.manifest must be an object');
+    }
+    requireExactTransactionKeys(value.manifest, ['path', 'stagedPath', 'contentType', 'sha256', 'bytes'], 'journal.manifest');
+    if (value.manifest.path !== SYNC_MANIFEST_FILE
+        || value.manifest.stagedPath !== EXPERIMENT_CREATE_MANIFEST_STAGED_PATH
+        || value.manifest.contentType !== EXPERIMENT_CREATE_MANIFEST_CONTENT_TYPE) {
+        throw experimentCreateTransactionError('journal.manifest does not use the fixed manifest contract');
+    }
+    return {
+        version: 1,
+        workspaceId: requireTransactionString(value.workspaceId, 'journal.workspaceId'),
+        funnelId: requireTransactionString(value.funnelId, 'journal.funnelId'),
+        baseDraftVersionId: requireTransactionString(value.baseDraftVersionId, 'journal.baseDraftVersionId'),
+        draftVersionId: requireTransactionString(value.draftVersionId, 'journal.draftVersionId'),
+        baseManifestSha256: requireTransactionHash(value.baseManifestSha256, 'journal.baseManifestSha256'),
+        files: [files[0], files[1]],
+        manifest: {
+            path: SYNC_MANIFEST_FILE,
+            stagedPath: EXPERIMENT_CREATE_MANIFEST_STAGED_PATH,
+            contentType: EXPERIMENT_CREATE_MANIFEST_CONTENT_TYPE,
+            sha256: requireTransactionHash(value.manifest.sha256, 'journal.manifest.sha256'),
+            bytes: requireTransactionBytes(value.manifest.bytes, 'journal.manifest.bytes'),
+        },
+    };
+};
+const assertStagedBytes = (content, receipt, fieldPath) => {
+    if (content.byteLength !== receipt.bytes || sha256Buffer(content) !== receipt.sha256) {
+        throw experimentCreateTransactionError(`${fieldPath} bytes or hash do not match the journal`);
+    }
+};
+const loadPreparedExperimentCreateTransaction = async (root) => {
+    await assertTransactionArtifactEntries(root);
+    let journalValue;
+    try {
+        journalValue = JSON.parse((await readSafeRootFile(root, transactionRelativePath(EXPERIMENT_CREATE_READY_DIRECTORY, EXPERIMENT_CREATE_JOURNAL_PATH))).toString('utf8'));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw experimentCreateTransactionError('journal is not valid JSON');
+        }
+        throw error;
+    }
+    const journal = parseExperimentCreateJournal(journalValue);
+    const stagedBuffers = await Promise.all(journal.files.map(async (file) => {
+        const content = await readSafeRootFile(root, transactionRelativePath(EXPERIMENT_CREATE_READY_DIRECTORY, file.stagedPath));
+        assertStagedBytes(content, file, file.stagedPath);
+        return content;
+    }));
+    const manifestBytes = await readSafeRootFile(root, transactionRelativePath(EXPERIMENT_CREATE_READY_DIRECTORY, EXPERIMENT_CREATE_MANIFEST_STAGED_PATH));
+    assertStagedBytes(manifestBytes, journal.manifest, 'manifest.json');
+    let manifestValue;
+    try {
+        manifestValue = JSON.parse(manifestBytes.toString('utf8'));
+    }
+    catch {
+        throw experimentCreateTransactionError('manifest.json is not valid JSON');
+    }
+    let manifest;
+    try {
+        manifest = validateManifest(manifestValue);
+    }
+    catch {
+        throw experimentCreateTransactionError('manifest.json is invalid');
+    }
+    if (manifest.workspaceId !== journal.workspaceId
+        || manifest.funnelId !== journal.funnelId
+        || manifest.draftVersionId !== journal.draftVersionId) {
+        throw experimentCreateTransactionError('manifest identity does not match the journal');
+    }
+    const manifestHashByPath = new Map(manifest.files.map((file) => [file.path, file.hash]));
+    journal.files.forEach((file) => {
+        if (manifestHashByPath.get(file.path) !== file.sha256) {
+            throw experimentCreateTransactionError(`manifest hash does not match ${file.path}`);
+        }
+    });
+    const stagedContents = stagedBuffers.map((content, index) => {
+        const decoded = content.toString('utf8');
+        if (!Buffer.from(decoded, 'utf8').equals(content)) {
+            throw experimentCreateTransactionError(`${journal.files[index].stagedPath} is not canonical UTF-8 text`);
+        }
+        return decoded;
+    });
+    return {
+        journal,
+        generatedFiles: journal.files.map((file, index) => ({
+            path: file.path,
+            content: stagedContents[index],
+            contentType: file.contentType,
+        })),
+        manifest,
+        manifestBytes,
+    };
+};
+const removeReadyExperimentCreateTransaction = async (root) => {
+    const resolvedRoot = await realpath(root);
+    const readyPath = path.join(resolvedRoot, ...EXPERIMENT_CREATE_READY_DIRECTORY.split('/'));
+    const parentPath = path.dirname(readyPath);
+    await rm(readyPath, { recursive: true });
+    await syncDirectory(parentPath);
+};
+const assertGeneratedTargetsRecoverable = async (root, baseManifest, journal) => {
+    const baseHashByPath = new Map(baseManifest.files.map((file) => [file.path, file.hash]));
+    for (const file of journal.files) {
+        let currentHash;
+        try {
+            currentHash = sha256Buffer(await readSafeRootFile(root, file.path));
+        }
+        catch (error) {
+            if (!isErrno(error, 'ENOENT'))
+                throw error;
+            currentHash = null;
+        }
+        const baseHash = baseHashByPath.get(file.path);
+        const matchesAllowedState = currentHash === file.sha256
+            || (baseHash === undefined ? currentHash === null : currentHash === baseHash);
+        if (!matchesAllowedState) {
+            throw experimentCreateTransactionError(`${file.path} contains a local edit made after experiment creation started`);
+        }
+    }
+};
+const applyPreparedExperimentCreateTransaction = async (root, prepared, hooks = {}) => {
+    const current = await readManifestBytes(root);
+    const currentHash = sha256Buffer(current.bytes);
+    if (current.bytes.equals(prepared.manifestBytes)) {
+        await removeReadyExperimentCreateTransaction(root);
+        return;
+    }
+    if (currentHash !== prepared.journal.baseManifestSha256
+        || current.manifest.workspaceId !== prepared.journal.workspaceId
+        || current.manifest.funnelId !== prepared.journal.funnelId
+        || current.manifest.draftVersionId !== prepared.journal.baseDraftVersionId) {
+        throw experimentCreateTransactionError('checkout sync manifest changed before recovery');
+    }
+    const expectedManifestBytes = serializedManifest(buildExperimentCreateManifest(current.manifest, prepared.journal.draftVersionId, prepared.generatedFiles));
+    if (!expectedManifestBytes.equals(prepared.manifestBytes)) {
+        throw experimentCreateTransactionError('staged manifest is not the canonical rebase of the checkout sync manifest');
+    }
+    for (const targetPath of [...EXPERIMENT_GENERATED_PATHS, SYNC_MANIFEST_FILE]) {
+        await assertSafeRootFileWriteTarget(root, targetPath);
+    }
+    await assertGeneratedTargetsRecoverable(root, current.manifest, prepared.journal);
+    for (const file of prepared.generatedFiles) {
+        await writeSourceFiles(root, [file]);
+        await hooks.afterPhase?.(`generated:${file.path}`);
+    }
+    await hooks.afterPhase?.('before-manifest');
+    await writeSyncManifest(root, prepared.manifest);
+    await hooks.afterPhase?.('manifest');
+    await removeReadyExperimentCreateTransaction(root);
+};
+const assertNoReadyExperimentCreateTransaction = async (root) => {
+    const readyPath = path.join(root, ...EXPERIMENT_CREATE_READY_DIRECTORY.split('/'));
+    try {
+        await lstat(readyPath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return;
+        throw error;
+    }
+    throw experimentCreateTransactionError('an unfinished experiment-create transaction already exists; recover it before continuing');
+};
+export async function recoverExperimentCreateTransaction(root) {
+    const readyPath = path.join(root, ...EXPERIMENT_CREATE_READY_DIRECTORY.split('/'));
+    let metadata;
+    try {
+        metadata = await lstat(readyPath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return false;
+        throw error;
+    }
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+        throw experimentCreateTransactionError('ready path must be a real directory');
+    }
+    try {
+        await applyPreparedExperimentCreateTransaction(root, await loadPreparedExperimentCreateTransaction(root));
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('experiment-create transaction')) {
+            throw error;
+        }
+        throw experimentCreateTransactionError(error instanceof Error ? error.message : 'recovery failed');
+    }
+}
+export async function installExperimentCreateTransaction(root, input, hooks = {}) {
+    await assertNoReadyExperimentCreateTransaction(root);
+    const generatedFiles = parseGeneratedExperimentFiles(input.generatedFiles);
+    const manifest = validateManifest(input.manifest);
+    const current = await readManifestBytes(root);
+    if (current.manifest.workspaceId !== manifest.workspaceId
+        || current.manifest.funnelId !== manifest.funnelId) {
+        throw experimentCreateTransactionError('next manifest does not match the checkout identity');
+    }
+    const manifestHashByPath = new Map(manifest.files.map((file) => [file.path, file.hash]));
+    generatedFiles.forEach((file) => {
+        if (manifestHashByPath.get(file.path) !== sha256Buffer(file.content)) {
+            throw experimentCreateTransactionError(`next manifest hash does not match ${file.path}`);
+        }
+    });
+    const manifestBytes = serializedManifest(manifest);
+    const expectedManifestBytes = serializedManifest(buildExperimentCreateManifest(current.manifest, manifest.draftVersionId, generatedFiles));
+    if (!manifestBytes.equals(expectedManifestBytes)) {
+        throw experimentCreateTransactionError('next manifest is not the canonical rebase of the checkout sync manifest');
+    }
+    const preparingDirectory = `${EXPERIMENT_CREATE_PREPARING_PREFIX}${randomUUID()}`;
+    const resolvedRoot = await realpath(root);
+    const preparingPath = path.join(resolvedRoot, ...preparingDirectory.split('/'));
+    const readyPath = path.join(resolvedRoot, ...EXPERIMENT_CREATE_READY_DIRECTORY.split('/'));
+    const parentPath = path.dirname(readyPath);
+    let published = false;
+    try {
+        for (const [index, file] of generatedFiles.entries()) {
+            await writeSafeRootFile(root, transactionRelativePath(preparingDirectory, EXPERIMENT_CREATE_STAGED_PATHS[index]), file.content);
+        }
+        await writeSafeRootFile(root, transactionRelativePath(preparingDirectory, EXPERIMENT_CREATE_MANIFEST_STAGED_PATH), manifestBytes);
+        const journal = {
+            version: 1,
+            workspaceId: manifest.workspaceId,
+            funnelId: manifest.funnelId,
+            baseDraftVersionId: current.manifest.draftVersionId,
+            draftVersionId: manifest.draftVersionId,
+            baseManifestSha256: sha256Buffer(current.bytes),
+            files: generatedFiles.map((file, index) => ({
+                path: file.path,
+                stagedPath: EXPERIMENT_CREATE_STAGED_PATHS[index],
+                contentType: file.contentType,
+                sha256: sha256Buffer(file.content),
+                bytes: Buffer.byteLength(file.content, 'utf8'),
+            })),
+            manifest: {
+                path: SYNC_MANIFEST_FILE,
+                stagedPath: EXPERIMENT_CREATE_MANIFEST_STAGED_PATH,
+                contentType: EXPERIMENT_CREATE_MANIFEST_CONTENT_TYPE,
+                sha256: sha256Buffer(manifestBytes),
+                bytes: manifestBytes.byteLength,
+            },
+        };
+        await writeSafeRootFile(root, transactionRelativePath(preparingDirectory, EXPERIMENT_CREATE_JOURNAL_PATH), `${JSON.stringify(journal, null, 2)}\n`);
+        await syncDirectory(preparingPath);
+        await hooks.afterPhase?.('prepared');
+        await assertNoReadyExperimentCreateTransaction(root);
+        try {
+            await rename(preparingPath, readyPath);
+        }
+        catch (error) {
+            if (isErrno(error, 'EEXIST') || isErrno(error, 'ENOTEMPTY')) {
+                throw experimentCreateTransactionError('an unfinished experiment-create transaction already exists; recover it before continuing');
+            }
+            throw error;
+        }
+        published = true;
+        await syncDirectory(parentPath);
+        await hooks.afterPhase?.('ready');
+        await applyPreparedExperimentCreateTransaction(root, await loadPreparedExperimentCreateTransaction(root), hooks);
+    }
+    finally {
+        if (!published) {
+            await rm(preparingPath, { recursive: true, force: true }).catch(() => undefined);
+            await syncDirectory(parentPath).catch(() => undefined);
+        }
+    }
+}
+const executeExperimentCreateDependencies = {
+    recover: recoverExperimentCreateTransaction,
+    readManifest: readSyncManifest,
+    readSpec: readAgentExperimentSpec,
+    assertGeneratedFilesUnchanged: assertGeneratedExperimentFilesUnchanged,
+    parseResponse: parseExperimentCreateResponse,
+    install: installExperimentCreateTransaction,
+};
+export async function executeExperimentCreate(input, dependencyOverrides = {}) {
+    const dependencies = { ...executeExperimentCreateDependencies, ...dependencyOverrides };
+    await dependencies.recover(input.sourceDir);
+    const manifest = await dependencies.readManifest(input.sourceDir);
+    if (!manifest) {
+        throw new Error(`No ${SYNC_MANIFEST_FILE} found. Run \`fgrove sync down --dir ${input.sourceDir}\` first.`);
+    }
+    const spec = await dependencies.readSpec(input.specPath);
+    await dependencies.assertGeneratedFilesUnchanged(input.sourceDir, manifest);
+    const rawResponse = await input.createFromSpec({
+        workspaceId: manifest.workspaceId,
+        funnelId: manifest.funnelId,
+        expectedDraftVersionId: manifest.draftVersionId,
+        spec,
+    });
+    const response = dependencies.parseResponse(rawResponse, spec, manifest.funnelId);
+    await dependencies.assertGeneratedFilesUnchanged(input.sourceDir, manifest);
+    const nextManifest = buildExperimentCreateManifest(manifest, response.draftVersionId, response.generatedFiles);
+    await dependencies.install(input.sourceDir, {
+        generatedFiles: response.generatedFiles,
+        manifest: nextManifest,
+    });
+    return {
+        experimentId: response.experiment.id,
+        experimentKey: response.experiment.posthog_flag_key,
+        draftVersionId: response.draftVersionId,
+        writtenPaths: [...EXPERIMENT_GENERATED_PATHS],
+        githubConnected: response.githubConnected,
+    };
+}
+export function formatExperimentCreateSuccess(result, json) {
+    const machineOutput = {
+        experimentId: result.experimentId,
+        experimentKey: result.experimentKey,
+        draftVersionId: result.draftVersionId,
+        writtenPaths: result.writtenPaths,
+    };
+    if (json) {
+        return `${JSON.stringify(machineOutput, null, 2)}\n`;
+    }
+    const guidance = result.githubConnected
+        ? 'For this GitHub-connected funnel, commit and push the generated source files with your other source changes, then run `fgrove github pull`.'
+        : 'Run `fgrove sync up` to deliver the local funnel changes.';
+    return [
+        `Created experiment ${result.experimentId} (${result.experimentKey})`,
+        `Draft version ${result.draftVersionId}`,
+        `Wrote ${result.writtenPaths.join(', ')}`,
+        guidance,
+        '',
+    ].join('\n');
+}