@funnelsgrove/runtime 0.1.56 → 0.1.60

package/dist/validation/funnel-contract-validator.js

@@ -0,0 +1,1458 @@
+import { CURRENT_STEP_CONTRACT_HASH } from '../generated/step-contract-hash.js';
+import { validateFunnelStepMetadataParity } from '../runtime/funnel-step-metadata.validation.js';
+import { parseFunnelChoiceDescriptor } from '../steps/choice-contract.js';
+import { CURRENT_STEP_CONTRACT_VERSION, FUNNEL_RESERVED_STEP_CONTRACTS, FUNNEL_STEP_CONTRACTS, FUNNEL_STEP_TYPES, LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION, SUPPORTED_STEP_CONTRACT_VERSIONS, resolveReservedStepContract, resolveStepTypeContract, } from '../steps/step-contract.js';
+import { createFunnelContractDiagnostic, } from './funnel-contract-diagnostics.js';
+import { MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS, isPlainDataRecord, normalizeFunnelManifestInput, } from './funnel-manifest-input.normalization.js';
+const MANIFEST_FILE = 'src/config/funnel.manifest.ts';
+const AUTHORING_GUIDE = 'docs/product-specs/funnel-template-step-authoring.md';
+const FLOW_GUIDE = 'docs/product-specs/funnel-flow-routing.md';
+const KEBAB_CASE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const FUNNEL_STEP_KINDS = Object.freeze(Array.from(new Set(Object.values(FUNNEL_STEP_CONTRACTS).flatMap((contract) => contract.allowedKinds))));
+const FUNNEL_STEP_KIND_SET = new Set(FUNNEL_STEP_KINDS);
+const SUPPORTED_STEP_CONTRACT_VERSION_SET = new Set(SUPPORTED_STEP_CONTRACT_VERSIONS);
+const resolvedReservedContracts = (version) => (Object.keys(FUNNEL_RESERVED_STEP_CONTRACTS).flatMap((identity) => {
+    const contract = resolveReservedStepContract(version, identity);
+    return contract ? [contract] : [];
+}));
+const exactReservedContracts = (version) => resolvedReservedContracts(version).filter((contract) => contract.match === 'exact');
+const isExactReservedCandidate = (version, step) => {
+    return exactReservedContracts(version).some((contract) => {
+        return step.id === contract.id || step.name === contract.name;
+    });
+};
+const isNonEmptyString = (value) => {
+    return typeof value === 'string' && value.trim().length > 0;
+};
+const isKnownStepType = (version, value) => {
+    return typeof value === 'string' && resolveStepTypeContract(version, value) !== undefined;
+};
+const isKnownStepKind = (value) => {
+    return typeof value === 'string' && FUNNEL_STEP_KIND_SET.has(value);
+};
+const stepFile = (step) => {
+    return isNonEmptyString(step.filePath) ? step.filePath : MANIFEST_FILE;
+};
+const diagnostic = (input) => {
+    var _a;
+    return createFunnelContractDiagnostic({
+        code: input.code,
+        file: input.step ? stepFile(input.step) : MANIFEST_FILE,
+        stepId: input.step && isNonEmptyString(input.step.id) ? input.step.id : null,
+        expected: input.expected,
+        received: input.received,
+        reason: input.reason,
+        guide: (_a = input.guide) !== null && _a !== void 0 ? _a : AUTHORING_GUIDE,
+        repair: input.repair,
+    });
+};
+const boundaryDiagnostic = (input) => {
+    return diagnostic(Object.assign(Object.assign({}, input), { guide: input.code === 'FG-FLOW-002' ? FLOW_GUIDE : AUTHORING_GUIDE }));
+};
+const dedupeDiagnostics = (diagnostics) => {
+    const diagnosticByCanonicalValue = new Map();
+    for (const item of diagnostics) {
+        const key = JSON.stringify(item);
+        if (!diagnosticByCanonicalValue.has(key)) {
+            diagnosticByCanonicalValue.set(key, item);
+        }
+    }
+    return Array.from(diagnosticByCanonicalValue.values());
+};
+const validateVersion = (manifest, mode) => {
+    const version = manifest.stepContractVersion;
+    const received = version === undefined ? 'missing' : version;
+    if (mode === 'legacy-read') {
+        const readableVersion = version === undefined
+            ? LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION
+            : version;
+        if (typeof readableVersion === 'number'
+            && Number.isInteger(readableVersion)
+            && SUPPORTED_STEP_CONTRACT_VERSION_SET.has(readableVersion)) {
+            return [];
+        }
+        return [diagnostic({
+                code: 'FG-VERSION-001',
+                expected: SUPPORTED_STEP_CONTRACT_VERSIONS,
+                received,
+                reason: 'The manifest uses an unsupported step contract version.',
+                repair: 'Use a supported reader or migrate the manifest before reading it.',
+            })];
+    }
+    if (version === CURRENT_STEP_CONTRACT_VERSION) {
+        return [];
+    }
+    if (version === undefined
+        || (typeof version === 'number' && SUPPORTED_STEP_CONTRACT_VERSION_SET.has(version))) {
+        return [diagnostic({
+                code: 'FG-VERSION-002',
+                expected: CURRENT_STEP_CONTRACT_VERSION,
+                received,
+                reason: `${mode} requires the current step contract version.`,
+                repair: `Migrate the manifest to step contract version ${CURRENT_STEP_CONTRACT_VERSION} before ${mode}.`,
+            })];
+    }
+    return [diagnostic({
+            code: 'FG-VERSION-001',
+            expected: CURRENT_STEP_CONTRACT_VERSION,
+            received,
+            reason: `${mode} cannot use an unsupported or future step contract version.`,
+            repair: 'Use tooling that supports this version or migrate the manifest to the current version.',
+        })];
+};
+const validateChoiceDescriptor = (version, step) => {
+    if (!isKnownStepType(version, step.type)) {
+        return [];
+    }
+    const contract = resolveStepTypeContract(version, step.type);
+    const choice = step.choice;
+    if (!contract.choice) {
+        if (choice === undefined) {
+            return [];
+        }
+        return [diagnostic({
+                code: 'FG-CHOICE-001',
+                step,
+                expected: 'omitted',
+                received: choice,
+                reason: 'Non-choice step types must omit choice metadata.',
+                repair: 'Remove the choice descriptor or assign the correct canonical choice step type.',
+            })];
+    }
+    const parsedChoice = parseFunnelChoiceDescriptor(step.type, choice);
+    if (!parsedChoice.ok) {
+        return [diagnostic({
+                code: 'FG-CHOICE-001',
+                step,
+                expected: {
+                    answerKey: 'camelCase or snake_case safe identifier',
+                    allowEmpty: 'optional boolean',
+                },
+                received: choice,
+                reason: 'Choice steps require an exact, stable choice descriptor.',
+                repair: 'Declare exactly answerKey and, when supported, an optional boolean allowEmpty.',
+            })];
+    }
+    return [];
+};
+const validateStepMetadata = (version, step) => {
+    const diagnostics = [];
+    const reservedCandidate = isExactReservedCandidate(version, step);
+    if (!isNonEmptyString(step.name) || !KEBAB_CASE_PATTERN.test(step.name)) {
+        diagnostics.push(diagnostic({
+            code: 'FG-STEP-002',
+            step,
+            expected: 'lowercase-kebab-case',
+            received: step.name,
+            reason: 'Every step requires a stable lowercase kebab-case analytics name.',
+            repair: 'Set name to a stable lowercase kebab-case value and keep it unchanged.',
+        }));
+    }
+    if (!reservedCandidate && !isKnownStepType(version, step.type)) {
+        diagnostics.push(diagnostic({
+            code: 'FG-STEP-001',
+            step,
+            expected: FUNNEL_STEP_TYPES.filter((type) => resolveStepTypeContract(version, type)),
+            received: step.type,
+            reason: 'The step type is not part of the canonical taxonomy.',
+            repair: 'Replace type with the canonical type that matches the screen semantics.',
+        }));
+    }
+    const receivedKind = step.kind;
+    if (!reservedCandidate && receivedKind === 'default') {
+        diagnostics.push(diagnostic({
+            code: 'FG-STEP-002',
+            step,
+            expected: 'omitted',
+            received: receivedKind,
+            reason: 'The legacy default kind is forbidden; ordinary step kinds are omitted.',
+            repair: 'Remove the kind field.',
+        }));
+    }
+    else if (!reservedCandidate && receivedKind !== undefined && !isKnownStepKind(receivedKind)) {
+        diagnostics.push(diagnostic({
+            code: 'FG-STEP-001',
+            step,
+            expected: FUNNEL_STEP_KINDS,
+            received: receivedKind,
+            reason: 'The step kind is not part of the canonical taxonomy.',
+            repair: 'Use the canonical required kind for the step type, or omit it for ordinary types.',
+        }));
+    }
+    else if (!reservedCandidate && isKnownStepType(version, step.type)) {
+        const contract = resolveStepTypeContract(version, step.type);
+        if (contract.requiredKind !== undefined && receivedKind !== contract.requiredKind) {
+            diagnostics.push(diagnostic({
+                code: 'FG-STEP-002',
+                step,
+                expected: contract.requiredKind,
+                received: receivedKind,
+                reason: 'The step kind does not match the canonical type contract.',
+                repair: `Set kind to ${contract.requiredKind}.`,
+            }));
+        }
+        else if (contract.requiredKind === undefined && receivedKind !== undefined) {
+            diagnostics.push(diagnostic({
+                code: 'FG-STEP-002',
+                step,
+                expected: 'omitted',
+                received: receivedKind,
+                reason: 'Ordinary step types must omit kind.',
+                repair: 'Remove the kind field.',
+            }));
+        }
+    }
+    diagnostics.push(...validateChoiceDescriptor(version, step));
+    return diagnostics;
+};
+const isReservedIdentityValue = (version, value) => {
+    return typeof value === 'string' && exactReservedContracts(version).some((contract) => {
+        return value === contract.id || value === contract.name;
+    });
+};
+const validateUniqueStepFields = (version, steps) => {
+    const diagnostics = [];
+    const fields = ['id', 'name', 'path', 'filePath', 'componentKey'];
+    for (const field of fields) {
+        const firstStepByValue = new Map();
+        for (const step of steps) {
+            const value = step[field];
+            if (!isNonEmptyString(value)) {
+                diagnostics.push(diagnostic({
+                    code: 'FG-STEP-002',
+                    step,
+                    expected: `non-empty ${field}`,
+                    received: value,
+                    reason: `Every manifest step requires a non-empty ${field}.`,
+                    repair: `Set a stable, unique ${field}.`,
+                }));
+                continue;
+            }
+            if (!firstStepByValue.has(value)) {
+                firstStepByValue.set(value, step);
+                continue;
+            }
+            if ((field === 'id' || field === 'name') && isReservedIdentityValue(version, value)) {
+                continue;
+            }
+            diagnostics.push(diagnostic({
+                code: 'FG-STEP-002',
+                step,
+                expected: `unique step ${field}`,
+                received: value,
+                reason: `Manifest step ${field} values must be unique.`,
+                repair: `Assign a unique ${field} without changing another step's stable identity.`,
+            }));
+        }
+    }
+    return diagnostics;
+};
+const exactReservedShape = (contract) => ({
+    id: contract.id,
+    name: contract.name,
+    type: contract.type,
+    kind: contract.kind,
+});
+const receivedReservedShape = (step) => ({
+    id: step.id,
+    name: step.name,
+    type: step.type,
+    kind: step.kind,
+});
+const matchesExactReservedContract = (step, contract) => {
+    return step.id === contract.id
+        && step.name === contract.name
+        && step.type === contract.type
+        && step.kind === contract.kind;
+};
+const matchesPatternReservedContract = (step, contract) => {
+    return typeof step.id === 'string'
+        && typeof step.name === 'string'
+        && new RegExp(contract.idPattern).test(step.id)
+        && new RegExp(contract.namePattern).test(step.name)
+        && step.id === step.name
+        && step.type === contract.type
+        && step.kind === contract.kind;
+};
+const validateReservedSteps = (version, steps) => {
+    const diagnostics = [];
+    const exactContracts = exactReservedContracts(version);
+    const paywallVariantContract = resolveReservedStepContract(version, 'paywall-variant');
+    const primaryPaywallContract = resolveReservedStepContract(version, 'paywall');
+    const subscriptionTerminalContract = resolveReservedStepContract(version, 'subscription-started');
+    const subscriptionManagementContract = resolveReservedStepContract(version, 'manage-subscription');
+    for (const contract of exactContracts) {
+        const candidates = steps.filter((step) => step.id === contract.id || step.name === contract.name);
+        for (const step of candidates) {
+            if (matchesExactReservedContract(step, contract)) {
+                continue;
+            }
+            diagnostics.push(diagnostic({
+                code: 'FG-RESERVED-001',
+                step,
+                expected: exactReservedShape(contract),
+                received: receivedReservedShape(step),
+                reason: 'A reserved lifecycle identity must match its exact id, name, type, and kind contract.',
+                repair: 'Restore the complete reserved lifecycle step metadata pair.',
+            }));
+        }
+        if (contract.unique && candidates.length > 1 && !contract.primary) {
+            diagnostics.push(diagnostic({
+                code: 'FG-RESERVED-001',
+                step: candidates[1],
+                expected: `one ${contract.id} reserved identity`,
+                received: candidates.length,
+                reason: 'Reserved lifecycle identities must be unique.',
+                repair: `Keep exactly one ${contract.id} step and give other screens semantic identities.`,
+            }));
+        }
+    }
+    for (const step of steps) {
+        const isPaywallPrefixed = (typeof step.id === 'string' && step.id.startsWith('paywall-'))
+            || (typeof step.name === 'string' && step.name.startsWith('paywall-'));
+        if (isPaywallPrefixed && !matchesPatternReservedContract(step, paywallVariantContract)) {
+            diagnostics.push(diagnostic({
+                code: 'FG-RESERVED-001',
+                step,
+                expected: paywallVariantContract.idPattern,
+                received: step.id === step.name ? step.id : receivedReservedShape(step),
+                reason: 'Paywall variants require identical stable id/name slugs and the paywall type/kind pair.',
+                repair: 'Use an identical lowercase paywall-* id/name with type paywall_offer and kind paywall.',
+            }));
+        }
+        const isPrimaryIdentityCandidate = step.id === primaryPaywallContract.id
+            || step.name === primaryPaywallContract.name;
+        const isPaywallVariant = matchesPatternReservedContract(step, paywallVariantContract);
+        if (step.type === 'paywall_offer'
+            && !isPrimaryIdentityCandidate
+            && !isPaywallVariant
+            && !isPaywallPrefixed) {
+            const isScratchcard = step.id === 'step-4' || step.name === 'scratchpad-entry';
+            diagnostics.push(diagnostic({
+                code: isScratchcard ? 'FG-STEP-104' : 'FG-RESERVED-001',
+                step,
+                expected: isScratchcard
+                    ? 'progress_interstitial'
+                    : 'id/name paywall or matching paywall-*',
+                received: isScratchcard ? step.type : receivedReservedShape(step),
+                reason: isScratchcard
+                    ? 'The known non-purchasable scratchcard is classified as a paywall offer.'
+                    : 'A paywall offer must use a canonical reserved paywall identity.',
+                repair: isScratchcard
+                    ? 'Classify the scratchcard as progress_interstitial.'
+                    : 'Rename the real offer to paywall or a matching paywall-* identity.',
+            }));
+        }
+        if (step.type === subscriptionTerminalContract.type
+            && step.id !== subscriptionTerminalContract.id
+            && step.name !== subscriptionTerminalContract.name) {
+            diagnostics.push(diagnostic({
+                code: 'FG-RESERVED-001',
+                step,
+                expected: exactReservedShape(subscriptionTerminalContract),
+                received: receivedReservedShape(step),
+                reason: 'The completion terminal type requires the exact subscription-started identity.',
+                repair: 'Use the subscription-started reserved identity or choose a non-terminal handoff type.',
+            }));
+        }
+        if (step.type === 'subscription_management'
+            && step.id !== subscriptionManagementContract.id
+            && step.name !== subscriptionManagementContract.name) {
+            diagnostics.push(diagnostic({
+                code: 'FG-RESERVED-001',
+                step,
+                expected: exactReservedShape(subscriptionManagementContract),
+                received: receivedReservedShape(step),
+                reason: 'The subscription management type requires the exact manage-subscription identity.',
+                repair: 'Restore the manage-subscription reserved identity.',
+            }));
+        }
+    }
+    const paywallOfferCount = steps.filter((step) => step.type === 'paywall_offer').length;
+    if (paywallOfferCount > 0) {
+        const primaryCount = steps.filter((step) => {
+            return step.id === primaryPaywallContract.id
+                || step.name === primaryPaywallContract.name;
+        }).length;
+        if (primaryCount !== 1) {
+            diagnostics.push(diagnostic({
+                code: 'FG-RESERVED-002',
+                expected: 1,
+                received: primaryCount,
+                reason: 'Funnels with paywall offers require exactly one canonical primary paywall.',
+                repair: 'Keep exactly one id/name paywall step with type paywall_offer and kind paywall.',
+            }));
+        }
+    }
+    return diagnostics;
+};
+const isTerminalStep = (version, step) => {
+    var _a;
+    return Boolean(step && ((_a = resolveStepTypeContract(version, String(step.type))) === null || _a === void 0 ? void 0 : _a.terminal));
+};
+const validateFlow = (version, manifest, steps) => {
+    var _a;
+    const diagnostics = [];
+    const validStepIds = new Set(steps.map((step) => step.id));
+    const stepById = new Map(steps.map((step) => [step.id, step]));
+    const identityLabel = (value) => {
+        return isNonEmptyString(value) ? value : '<invalid>';
+    };
+    const reportMissingReference = (owner, received, step) => {
+        diagnostics.push(diagnostic({
+            code: 'FG-FLOW-002',
+            step,
+            expected: 'an existing manifest step id',
+            received,
+            reason: `${owner} references an unknown manifest step.`,
+            guide: FLOW_GUIDE,
+            repair: 'Point the reference at an existing step or add the missing step atomically.',
+        }));
+    };
+    const entryPointIds = new Set();
+    let defaultEntryPointCount = 0;
+    for (const entryPoint of manifest.entryPoints) {
+        const entryPointId = isNonEmptyString(entryPoint.id) ? entryPoint.id : null;
+        if (entryPointId === null || entryPointIds.has(entryPointId)) {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                expected: 'unique non-empty entry point id',
+                received: entryPoint.id,
+                reason: 'Entry point identities must be present and unique.',
+                guide: FLOW_GUIDE,
+                repair: 'Assign each entry point a unique stable id.',
+            }));
+        }
+        if (entryPointId !== null) {
+            entryPointIds.add(entryPointId);
+        }
+        if (entryPoint.isDefault !== undefined && typeof entryPoint.isDefault !== 'boolean') {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                expected: 'boolean or undefined',
+                received: entryPoint.isDefault,
+                reason: 'Entry point isDefault must be an explicit boolean when present.',
+                guide: FLOW_GUIDE,
+                repair: 'Set isDefault to true or false, or omit it.',
+            }));
+        }
+        defaultEntryPointCount += entryPoint.isDefault === true ? 1 : 0;
+        if (!validStepIds.has(entryPoint.stepId)) {
+            reportMissingReference(`Entry point ${identityLabel(entryPoint.id)}`, entryPoint.stepId);
+        }
+    }
+    if (defaultEntryPointCount > 1) {
+        diagnostics.push(diagnostic({
+            code: 'FG-FLOW-002',
+            expected: 'at most one default entry point',
+            received: defaultEntryPointCount,
+            reason: 'A manifest cannot declare multiple default entry points.',
+            guide: FLOW_GUIDE,
+            repair: 'Mark at most one entry point as default.',
+        }));
+    }
+    for (const { sourceStepId, edges } of manifest.edgeGroups) {
+        const sourceStep = stepById.get(sourceStepId);
+        if (!sourceStep) {
+            reportMissingReference(`Edge source ${sourceStepId}`, sourceStepId);
+        }
+        const declaredEdges = edges !== null && edges !== void 0 ? edges : [];
+        for (const edge of declaredEdges) {
+            if (!validStepIds.has(edge.toStepId)) {
+                reportMissingReference(`Edge from ${sourceStepId}`, edge.toStepId, sourceStep);
+            }
+        }
+        if (sourceStep
+            && ((_a = resolveStepTypeContract(version, String(sourceStep.type))) === null || _a === void 0 ? void 0 : _a.terminal)
+            && declaredEdges.length > 0) {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                step: sourceStep,
+                expected: 'no outbound edges',
+                received: declaredEdges,
+                reason: 'Terminal contract step types cannot have outbound edges.',
+                guide: FLOW_GUIDE,
+                repair: 'Remove all outbound edges from the terminal step.',
+            }));
+        }
+    }
+    const branchIds = new Set();
+    for (const branch of manifest.branches) {
+        const branchId = isNonEmptyString(branch.id) ? branch.id : null;
+        if (branchId === null || branchIds.has(branchId)) {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                expected: 'unique non-empty branch id',
+                received: branch.id,
+                reason: 'Branch identities must be present and unique.',
+                guide: FLOW_GUIDE,
+                repair: 'Assign each branch a unique stable id.',
+            }));
+        }
+        if (branchId !== null) {
+            branchIds.add(branchId);
+        }
+        if (!isNonEmptyString(branch.name)) {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                expected: 'non-empty branch name',
+                received: branch.name,
+                reason: 'Every branch requires a name.',
+                guide: FLOW_GUIDE,
+                repair: 'Set a descriptive branch name.',
+            }));
+        }
+        if (!validStepIds.has(branch.sourceStepId)) {
+            reportMissingReference(`Branch ${identityLabel(branch.id)} source`, branch.sourceStepId);
+        }
+        const branchSourceStep = stepById.get(branch.sourceStepId);
+        if (isTerminalStep(version, branchSourceStep)) {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                step: branchSourceStep,
+                expected: 'no outbound routing',
+                received: { branchId: branch.id },
+                reason: 'Terminal contract step types cannot be branch sources.',
+                guide: FLOW_GUIDE,
+                repair: 'Move the branch source before the terminal step.',
+            }));
+        }
+        if (branch.stepIds.length === 0) {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                expected: 'at least one branch-owned step',
+                received: branch.stepIds,
+                reason: 'Branches must own at least one step.',
+                guide: FLOW_GUIDE,
+                repair: 'Add an existing step to the branch or remove the empty branch.',
+            }));
+        }
+        for (const branchStepId of branch.stepIds) {
+            if (!validStepIds.has(branchStepId)) {
+                reportMissingReference(`Branch ${identityLabel(branch.id)}`, branchStepId);
+            }
+        }
+    }
+    const experimentIds = new Set();
+    for (const experiment of manifest.experiments) {
+        const experimentId = isNonEmptyString(experiment.experimentId)
+            ? experiment.experimentId
+            : null;
+        if (experimentId === null || experimentIds.has(experimentId)) {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                step: stepById.get(experiment.stepId),
+                expected: 'unique non-empty experiment id',
+                received: experiment.experimentId,
+                reason: 'Experiment identities must be present and unique.',
+                guide: FLOW_GUIDE,
+                repair: 'Assign each experiment a unique stable id.',
+            }));
+        }
+        if (experimentId !== null) {
+            experimentIds.add(experimentId);
+        }
+        if (!validStepIds.has(experiment.stepId)) {
+            reportMissingReference(`Experiment ${identityLabel(experiment.experimentId)}`, experiment.stepId);
+        }
+        const experimentSourceStep = stepById.get(experiment.stepId);
+        if (isTerminalStep(version, experimentSourceStep) && experiment.variants.length > 0) {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                step: experimentSourceStep,
+                expected: 'no outbound routing',
+                received: { experimentId: experiment.experimentId },
+                reason: 'Terminal contract step types cannot route through experiments.',
+                guide: FLOW_GUIDE,
+                repair: 'Move the experiment before the terminal step.',
+            }));
+        }
+        if (experiment.variants.length === 0) {
+            diagnostics.push(diagnostic({
+                code: 'FG-FLOW-002',
+                step: stepById.get(experiment.stepId),
+                expected: 'at least one experiment variant',
+                received: experiment.variants,
+                reason: 'Experiments must declare at least one route variant.',
+                guide: FLOW_GUIDE,
+                repair: 'Add a valid variant or remove the experiment.',
+            }));
+        }
+        const variantKeys = new Set();
+        for (const variant of experiment.variants) {
+            const variantKey = isNonEmptyString(variant.variantKey) ? variant.variantKey : null;
+            if (variantKey === null || variantKeys.has(variantKey)) {
+                diagnostics.push(diagnostic({
+                    code: 'FG-FLOW-002',
+                    step: stepById.get(experiment.stepId),
+                    expected: 'unique non-empty variant key within the experiment',
+                    received: variant.variantKey,
+                    reason: 'Experiment variant identities must be present and unique.',
+                    guide: FLOW_GUIDE,
+                    repair: 'Assign each variant a unique stable key.',
+                }));
+            }
+            if (variantKey !== null) {
+                variantKeys.add(variantKey);
+            }
+            if (!validStepIds.has(variant.routeToStepId)) {
+                reportMissingReference(`Experiment variant ${identityLabel(experiment.experimentId)}:${identityLabel(variant.variantKey)}`, variant.routeToStepId, stepById.get(experiment.stepId));
+            }
+        }
+    }
+    return diagnostics;
+};
+export const validateFunnelManifestContract = (input, options) => {
+    try {
+        const normalized = normalizeFunnelManifestInput(input, boundaryDiagnostic);
+        if (!normalized.manifest) {
+            return normalized.diagnostics;
+        }
+        const manifest = normalized.manifest;
+        const steps = manifest.steps;
+        const declaredVersion = manifest.stepContractVersion;
+        const contractVersion = typeof declaredVersion === 'number'
+            && SUPPORTED_STEP_CONTRACT_VERSION_SET.has(declaredVersion)
+            ? declaredVersion
+            : declaredVersion === undefined
+                ? LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION
+                : CURRENT_STEP_CONTRACT_VERSION;
+        const diagnostics = [
+            ...validateVersion(manifest, options.mode),
+            ...normalized.diagnostics,
+        ];
+        if (!Number.isInteger(manifest.templateArchitectureVersion)
+            || typeof manifest.templateArchitectureVersion !== 'number'
+            || manifest.templateArchitectureVersion < 1) {
+            diagnostics.push(diagnostic({
+                code: 'FG-STEP-002',
+                expected: 'positive integer templateArchitectureVersion',
+                received: manifest.templateArchitectureVersion,
+                reason: 'templateArchitectureVersion must be a positive integer.',
+                repair: 'Set templateArchitectureVersion to the supported positive architecture version.',
+            }));
+        }
+        if (manifest.declaredStepCount === 0) {
+            diagnostics.push(diagnostic({
+                code: 'FG-STEP-002',
+                expected: 'at least one manifest step',
+                received: steps,
+                reason: 'A funnel manifest must declare at least one step.',
+                repair: 'Add the first complete step before authoring or publishing.',
+            }));
+        }
+        for (const step of steps) {
+            diagnostics.push(...validateStepMetadata(contractVersion, step));
+        }
+        diagnostics.push(...validateUniqueStepFields(contractVersion, steps));
+        if (manifest.hasValidStepRecords) {
+            diagnostics.push(...validateReservedSteps(contractVersion, steps));
+            diagnostics.push(...validateFlow(contractVersion, manifest, steps));
+        }
+        return dedupeDiagnostics(diagnostics);
+    }
+    catch (_a) {
+        return [diagnostic({
+                code: 'FG-STEP-002',
+                expected: 'inspectable plain funnel manifest object',
+                received: 'uninspectable runtime input',
+                reason: 'The funnel manifest could not be inspected safely.',
+                repair: 'Provide a plain JSON-compatible funnel manifest without accessors or proxies.',
+            })];
+    }
+};
+const EXPERIMENTS_FILE = 'src/config/experiments.ts';
+const DOCS_MANIFEST_FILE = '.funnelsgrove-docs.json';
+const isObjectRecord = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const readOwnDataProperty = (value, key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor) {
+        return { status: 'missing', value: undefined };
+    }
+    if (!Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+        return { status: 'accessor', value: undefined };
+    }
+    return { status: 'data', value: descriptor.value };
+};
+const runtimeValueType = (value) => {
+    try {
+        if (value === null) {
+            return 'null';
+        }
+        return Array.isArray(value) ? 'array' : typeof value;
+    }
+    catch (_a) {
+        return 'uninspectable';
+    }
+};
+const readBoundedDenseDataArrayUnsafe = (value) => {
+    if (!Array.isArray(value)) {
+        return {
+            valid: false,
+            summary: { state: 'not-array', receivedType: runtimeValueType(value) },
+        };
+    }
+    const lengthProperty = readOwnDataProperty(value, 'length');
+    if (lengthProperty.status !== 'data'
+        || typeof lengthProperty.value !== 'number'
+        || !Number.isSafeInteger(lengthProperty.value)
+        || lengthProperty.value < 0) {
+        return { valid: false, summary: { state: 'invalid-length' } };
+    }
+    if (lengthProperty.value > MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS) {
+        return {
+            valid: false,
+            summary: { state: 'oversized', declaredLength: lengthProperty.value },
+        };
+    }
+    const values = [];
+    for (let index = 0; index < lengthProperty.value; index += 1) {
+        const item = readOwnDataProperty(value, String(index));
+        if (item.status === 'missing') {
+            return {
+                valid: false,
+                summary: { state: 'sparse', declaredLength: lengthProperty.value, index },
+            };
+        }
+        if (item.status === 'accessor') {
+            return {
+                valid: false,
+                summary: { state: 'accessor-index', declaredLength: lengthProperty.value, index },
+            };
+        }
+        values.push(item.value);
+    }
+    return { valid: true, values };
+};
+const readBoundedDenseDataArray = (value) => {
+    try {
+        return readBoundedDenseDataArrayUnsafe(value);
+    }
+    catch (_a) {
+        return { valid: false, summary: { state: 'uninspectable' } };
+    }
+};
+const MAX_FUNNEL_SNAPSHOT_RECORD_KEY_LENGTH = 256;
+const readBoundedOwnDataRecord = (value) => {
+    try {
+        if (!isPlainDataRecord(value)) {
+            return {
+                valid: false,
+                summary: { state: 'not-record', receivedType: runtimeValueType(value) },
+            };
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            return { valid: false, summary: { state: 'symbol-property' } };
+        }
+        const keys = Object.getOwnPropertyNames(value);
+        if (keys.length > MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS) {
+            return {
+                valid: false,
+                summary: { state: 'oversized', declaredKeyCount: keys.length },
+            };
+        }
+        const entries = new Map();
+        for (let keyIndex = 0; keyIndex < keys.length; keyIndex += 1) {
+            const key = keys[keyIndex];
+            if (key.length > MAX_FUNNEL_SNAPSHOT_RECORD_KEY_LENGTH) {
+                return {
+                    valid: false,
+                    summary: { state: 'key-too-long', keyIndex, keyLength: key.length },
+                };
+            }
+            const property = readOwnDataProperty(value, key);
+            if (property.status !== 'data') {
+                return {
+                    valid: false,
+                    summary: { state: 'accessor-property', keyIndex },
+                };
+            }
+            entries.set(key, property.value);
+        }
+        return { valid: true, entries };
+    }
+    catch (_a) {
+        return { valid: false, summary: { state: 'uninspectable' } };
+    }
+};
+const snapshotDiagnostic = (input) => {
+    var _a, _b, _c;
+    return createFunnelContractDiagnostic({
+        code: input.code,
+        file: (_a = input.file) !== null && _a !== void 0 ? _a : null,
+        stepId: (_b = input.stepId) !== null && _b !== void 0 ? _b : null,
+        expected: input.expected,
+        received: input.received,
+        reason: input.reason,
+        guide: (_c = input.guide) !== null && _c !== void 0 ? _c : AUTHORING_GUIDE,
+        repair: input.repair,
+    });
+};
+const validateSnapshotRegistry = (registeredComponentKeysInput, componentMetaByKeyInput, manifest) => {
+    var _a, _b, _c;
+    const diagnostics = [];
+    const registeredKeysRead = readBoundedDenseDataArray(registeredComponentKeysInput);
+    if (!registeredKeysRead.valid) {
+        return [snapshotDiagnostic({
+                code: 'FG-REGISTRY-001',
+                file: MANIFEST_FILE,
+                expected: 'a dense bounded array of nonblank component keys',
+                received: registeredKeysRead.summary,
+                reason: 'The registered component key collection is malformed.',
+                repair: 'Provide a dense bounded array containing only nonblank component key strings.',
+            })];
+    }
+    const invalidKeyIndex = registeredKeysRead.values.findIndex((key) => (!isNonEmptyString(key) || key.length > MAX_FUNNEL_SNAPSHOT_RECORD_KEY_LENGTH));
+    if (invalidKeyIndex !== -1) {
+        return [snapshotDiagnostic({
+                code: 'FG-REGISTRY-001',
+                file: MANIFEST_FILE,
+                expected: 'a dense bounded array of nonblank component keys',
+                received: Object.assign({ state: 'invalid-entry', index: invalidKeyIndex, receivedType: runtimeValueType(registeredKeysRead.values[invalidKeyIndex]) }, (typeof registeredKeysRead.values[invalidKeyIndex] === 'string'
+                    ? { keyLength: registeredKeysRead.values[invalidKeyIndex].length }
+                    : {})),
+                reason: 'Registered component keys must be nonblank strings.',
+                repair: 'Replace the invalid registry entry with the exact manifest component key.',
+            })];
+    }
+    const registeredComponentKeys = registeredKeysRead.values;
+    const componentMetaRead = readBoundedOwnDataRecord(componentMetaByKeyInput);
+    if (!componentMetaRead.valid) {
+        return [snapshotDiagnostic({
+                code: 'FG-REGISTRY-001',
+                file: MANIFEST_FILE,
+                expected: 'a bounded own-data component metadata map',
+                received: componentMetaRead.summary,
+                reason: 'The component metadata map is malformed or exceeds snapshot limits.',
+                repair: 'Provide a bounded plain component metadata map without accessors or symbols.',
+            })];
+    }
+    const componentMetaByKey = componentMetaRead.entries;
+    const registrationCountByKey = new Map();
+    for (const key of registeredComponentKeys) {
+        if (typeof key !== 'string') {
+            continue;
+        }
+        registrationCountByKey.set(key, ((_a = registrationCountByKey.get(key)) !== null && _a !== void 0 ? _a : 0) + 1);
+    }
+    const manifestComponentKeys = new Set();
+    const manifestSteps = Array.isArray(manifest.steps) ? manifest.steps : [];
+    for (const step of manifestSteps) {
+        const componentKey = step.componentKey;
+        manifestComponentKeys.add(componentKey);
+        const registrationCount = (_b = registrationCountByKey.get(componentKey)) !== null && _b !== void 0 ? _b : 0;
+        if (componentKey.length > MAX_FUNNEL_SNAPSHOT_RECORD_KEY_LENGTH) {
+            diagnostics.push(snapshotDiagnostic({
+                code: 'FG-REGISTRY-001',
+                file: step.filePath,
+                stepId: step.id,
+                expected: `component key with at most ${MAX_FUNNEL_SNAPSHOT_RECORD_KEY_LENGTH} characters`,
+                received: { state: 'key-too-long', keyLength: componentKey.length },
+                reason: 'The manifest component key exceeds the bounded registry key length.',
+                repair: 'Use a stable bounded component key in the manifest and registry.',
+            }));
+            continue;
+        }
+        const hasMetadata = componentMetaByKey.has(componentKey)
+            && isObjectRecord(componentMetaByKey.get(componentKey));
+        if (registrationCount === 1 && hasMetadata) {
+            continue;
+        }
+        diagnostics.push(snapshotDiagnostic({
+            code: 'FG-REGISTRY-001',
+            file: step.filePath,
+            stepId: step.id,
+            expected: { componentKey, registrationCount: 1, hasMetadata: true },
+            received: { componentKey, registrationCount, hasMetadata },
+            reason: 'Every manifest component key must have one registration and one metadata record.',
+            repair: 'Register the declared component exactly once and export its matching metadata.',
+        }));
+    }
+    const orphanKeys = new Set();
+    for (const key of registrationCountByKey.keys()) {
+        if (!manifestComponentKeys.has(key)) {
+            orphanKeys.add(key);
+        }
+    }
+    for (const key of componentMetaByKey.keys()) {
+        if (!manifestComponentKeys.has(key)) {
+            orphanKeys.add(key);
+        }
+    }
+    for (const componentKey of [...orphanKeys].sort()) {
+        diagnostics.push(snapshotDiagnostic({
+            code: 'FG-REGISTRY-001',
+            file: MANIFEST_FILE,
+            expected: { componentKey, declaredByManifest: true },
+            received: {
+                componentKey,
+                declaredByManifest: false,
+                registrationCount: (_c = registrationCountByKey.get(componentKey)) !== null && _c !== void 0 ? _c : 0,
+                hasMetadata: componentMetaByKey.has(componentKey),
+            },
+            reason: 'The component registry contains a key that no manifest step declares.',
+            repair: 'Remove the orphan registry entry or declare the complete manifest step atomically.',
+        }));
+    }
+    return diagnostics;
+};
+const validateSnapshotMetadataParity = (componentMetaByKeyInput, manifest) => {
+    const diagnostics = [];
+    const componentMetaRead = readBoundedOwnDataRecord(componentMetaByKeyInput);
+    if (!componentMetaRead.valid) {
+        return diagnostics;
+    }
+    const manifestSteps = Array.isArray(manifest.steps) ? manifest.steps : [];
+    for (const step of manifestSteps) {
+        const componentMeta = componentMetaRead.entries.get(step.componentKey);
+        if (!isObjectRecord(componentMeta)) {
+            continue;
+        }
+        diagnostics.push(...validateFunnelStepMetadataParity(step, componentMeta, { file: step.filePath }));
+    }
+    return diagnostics;
+};
+const choiceOptionSchema = (presentation) => {
+    return presentation === 'emoji'
+        ? { required: ['id', 'label', 'emoji'], allowed: ['id', 'label', 'emoji'] }
+        : { required: ['id', 'label'], allowed: ['id', 'label', 'imageSrc', 'iconKey'] };
+};
+const validateChoiceOptionUnsafe = (option, presentation) => {
+    if (!isPlainDataRecord(option)) {
+        return { valid: false, fields: [], id: typeof option };
+    }
+    const schema = choiceOptionSchema(presentation);
+    const fields = Object.getOwnPropertyNames(option).sort();
+    const valueByField = new Map();
+    const hasOnlyDataFields = fields.every((field) => {
+        const property = readOwnDataProperty(option, field);
+        if (property.status !== 'data') {
+            return false;
+        }
+        valueByField.set(field, property.value);
+        return true;
+    });
+    const hasExactFields = hasOnlyDataFields
+        && schema.required.every((field) => valueByField.has(field))
+        && fields.every((field) => schema.allowed.includes(field));
+    const id = valueByField.get('id');
+    const label = valueByField.get('label');
+    const imageSrc = valueByField.get('imageSrc');
+    const iconKey = valueByField.get('iconKey');
+    const emoji = valueByField.get('emoji');
+    const hasValidIdentity = isNonEmptyString(id) && isNonEmptyString(label);
+    const hasValidPresentation = presentation === 'emoji'
+        ? isNonEmptyString(emoji)
+        : (imageSrc === undefined || typeof imageSrc === 'string')
+            && (iconKey === undefined || typeof iconKey === 'string');
+    return {
+        valid: hasExactFields && hasValidIdentity && hasValidPresentation,
+        fields,
+        id: typeof id === 'string' ? id : typeof id,
+    };
+};
+const validateChoiceOption = (option, presentation) => {
+    try {
+        return validateChoiceOptionUnsafe(option, presentation);
+    }
+    catch (_a) {
+        return { valid: false, fields: [], id: 'uninspectable' };
+    }
+};
+const validateSnapshotChoiceContent = (contentOptionsByStepIdInput, manifest) => {
+    const diagnostics = [];
+    const contentOptionsRead = readBoundedOwnDataRecord(contentOptionsByStepIdInput);
+    if (!contentOptionsRead.valid) {
+        return [snapshotDiagnostic({
+                code: 'FG-CONTENT-001',
+                file: MANIFEST_FILE,
+                expected: 'a bounded own-data choice content map',
+                received: contentOptionsRead.summary,
+                reason: 'The choice content map is malformed or exceeds snapshot limits.',
+                repair: 'Provide a bounded plain choice content map without accessors or symbols.',
+            })];
+    }
+    const contentOptionsByStepId = contentOptionsRead.entries;
+    const expectedChoiceStepIds = new Set();
+    const manifestSteps = Array.isArray(manifest.steps) ? manifest.steps : [];
+    for (const step of manifestSteps) {
+        const contract = resolveStepTypeContract(manifest.stepContractVersion, step.type);
+        if (!(contract === null || contract === void 0 ? void 0 : contract.choice)) {
+            continue;
+        }
+        expectedChoiceStepIds.add(step.id);
+        const ownsOptions = contentOptionsByStepId.has(step.id);
+        const options = ownsOptions ? contentOptionsByStepId.get(step.id) : undefined;
+        const optionsRead = readBoundedDenseDataArray(options);
+        if (!ownsOptions || !optionsRead.valid || optionsRead.values.length === 0) {
+            const received = !ownsOptions
+                ? 'missing'
+                : !optionsRead.valid
+                    ? optionsRead.summary
+                    : 'empty';
+            diagnostics.push(snapshotDiagnostic({
+                code: 'FG-CONTENT-001',
+                file: step.filePath,
+                stepId: step.id,
+                expected: ownsOptions && !optionsRead.valid
+                    ? 'a dense bounded options array'
+                    : 'a non-empty options array owned by this choice step',
+                received,
+                reason: 'Choice steps require their own non-empty content option registry entry.',
+                repair: 'Add a non-empty canonical option array under this exact stable step id.',
+            }));
+            continue;
+        }
+        const seenIds = new Set();
+        optionsRead.values.forEach((option, optionIndex) => {
+            const result = validateChoiceOption(option, contract.choice.presentation);
+            if (!result.valid) {
+                diagnostics.push(snapshotDiagnostic({
+                    code: 'FG-CHOICE-002',
+                    file: step.filePath,
+                    stepId: step.id,
+                    expected: Object.assign({ optionIndex, presentation: contract.choice.presentation }, choiceOptionSchema(contract.choice.presentation)),
+                    received: { optionIndex, fields: result.fields, id: result.id },
+                    reason: 'The choice option does not match the exact presentation schema.',
+                    repair: contract.choice.presentation === 'emoji'
+                        ? 'Use exactly id, label, and a nonblank emoji string.'
+                        : 'Use exactly id, label, and optional imageSrc or iconKey strings.',
+                }));
+            }
+            if (isNonEmptyString(result.id)) {
+                if (seenIds.has(result.id)) {
+                    diagnostics.push(snapshotDiagnostic({
+                        code: 'FG-CHOICE-002',
+                        file: step.filePath,
+                        stepId: step.id,
+                        expected: { optionIndex, id: 'unique within step' },
+                        received: { optionIndex, id: result.id },
+                        reason: 'Choice option IDs must be unique within their step.',
+                        repair: 'Assign a stable unique ID without using the display label as persisted state.',
+                    }));
+                }
+                else {
+                    seenIds.add(result.id);
+                }
+            }
+        });
+    }
+    const orphanStepIds = [...contentOptionsByStepId.keys()]
+        .filter((stepId) => !expectedChoiceStepIds.has(stepId))
+        .sort();
+    for (const stepId of orphanStepIds) {
+        diagnostics.push(snapshotDiagnostic({
+            code: 'FG-CONTENT-001',
+            file: MANIFEST_FILE,
+            stepId,
+            expected: 'a manifest step with a canonical choice type',
+            received: 'orphan content options entry',
+            reason: 'Content options may only be registered for declared canonical choice steps.',
+            repair: 'Remove the orphan content entry or declare the complete choice step contract.',
+        }));
+    }
+    return diagnostics;
+};
+const compareCanonicalValues = (left, right, state) => {
+    if (Object.is(left, right)) {
+        return true;
+    }
+    state.remainingValues -= 1;
+    if (state.remainingValues < 0) {
+        return false;
+    }
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right)) {
+            return false;
+        }
+        const leftRead = readBoundedDenseDataArray(left);
+        const rightRead = readBoundedDenseDataArray(right);
+        if (!leftRead.valid
+            || !rightRead.valid
+            || leftRead.values.length !== rightRead.values.length) {
+            return false;
+        }
+        return leftRead.values.every((item, index) => (compareCanonicalValues(item, rightRead.values[index], state)));
+    }
+    if (!isPlainDataRecord(left) || !isPlainDataRecord(right)) {
+        return false;
+    }
+    const existingRightValues = state.comparedObjectPairs.get(left);
+    if (existingRightValues === null || existingRightValues === void 0 ? void 0 : existingRightValues.has(right)) {
+        return true;
+    }
+    const comparedRightValues = existingRightValues !== null && existingRightValues !== void 0 ? existingRightValues : new WeakSet();
+    comparedRightValues.add(right);
+    state.comparedObjectPairs.set(left, comparedRightValues);
+    const readComparableRecord = (record) => {
+        const recordRead = readBoundedOwnDataRecord(record);
+        if (!recordRead.valid) {
+            return null;
+        }
+        const values = new Map();
+        for (const [key, value] of recordRead.entries) {
+            if (value !== undefined) {
+                values.set(key, value);
+            }
+        }
+        return values;
+    };
+    const leftValues = readComparableRecord(left);
+    const rightValues = readComparableRecord(right);
+    if (!leftValues || !rightValues) {
+        return false;
+    }
+    const leftKeys = [...leftValues.keys()].sort();
+    const rightKeys = [...rightValues.keys()].sort();
+    if (leftKeys.length !== rightKeys.length
+        || leftKeys.some((key, index) => key !== rightKeys[index])) {
+        return false;
+    }
+    return leftKeys.every((key) => (compareCanonicalValues(leftValues.get(key), rightValues.get(key), state)));
+};
+const canonicalDeepEqual = (left, right) => {
+    return compareCanonicalValues(left, right, {
+        remainingValues: MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS,
+        comparedObjectPairs: new WeakMap(),
+    });
+};
+const summarizeFlowMismatchValue = (value, path) => {
+    try {
+        if (Array.isArray(value)) {
+            const length = readOwnDataProperty(value, 'length');
+            return Object.assign({ path, type: 'array' }, (length.status === 'data' && typeof length.value === 'number'
+                ? { count: length.value }
+                : {}));
+        }
+        if (isPlainDataRecord(value)) {
+            const recordRead = readBoundedOwnDataRecord(value);
+            return Object.assign({ path, type: recordRead.valid ? 'object' : recordRead.summary.state }, (recordRead.valid ? { count: recordRead.entries.size } : {}));
+        }
+        return { path, type: runtimeValueType(value) };
+    }
+    catch (_a) {
+        return { path, type: 'uninspectable' };
+    }
+};
+const validateSnapshotFlowParity = (edgesByStepIdInput, experimentsInput, manifest) => {
+    const diagnostics = [];
+    const manifestEdgesRead = readBoundedOwnDataRecord(manifest.edgesByStepId);
+    const snapshotEdgesRead = readBoundedOwnDataRecord(edgesByStepIdInput);
+    if (!manifestEdgesRead.valid || !snapshotEdgesRead.valid) {
+        diagnostics.push(snapshotDiagnostic({
+            code: 'FG-FLOW-001',
+            file: MANIFEST_FILE,
+            expected: manifestEdgesRead.valid
+                ? { path: 'edgesByStepId', type: 'object', count: manifestEdgesRead.entries.size }
+                : { path: 'edgesByStepId', type: manifestEdgesRead.summary.state },
+            received: snapshotEdgesRead.valid
+                ? { path: 'edgesByStepId', type: 'object', count: snapshotEdgesRead.entries.size }
+                : { path: 'edgesByStepId', type: snapshotEdgesRead.summary.state },
+            reason: 'The edge registry is malformed or exceeds bounded snapshot limits.',
+            guide: FLOW_GUIDE,
+            repair: 'Provide a bounded own-data edge registry that matches the manifest.',
+        }));
+    }
+    else {
+        const edgeKeys = new Set([
+            ...manifestEdgesRead.entries.keys(),
+            ...snapshotEdgesRead.entries.keys(),
+        ]);
+        for (const stepId of [...edgeKeys].sort()) {
+            const expected = manifestEdgesRead.entries.get(stepId);
+            const received = snapshotEdgesRead.entries.get(stepId);
+            if (canonicalDeepEqual(expected, received)) {
+                continue;
+            }
+            diagnostics.push(snapshotDiagnostic({
+                code: 'FG-FLOW-001',
+                file: MANIFEST_FILE,
+                stepId,
+                expected: summarizeFlowMismatchValue(expected, `edgesByStepId.${stepId}`),
+                received: summarizeFlowMismatchValue(received, `edgesByStepId.${stepId}`),
+                reason: 'Extracted edge metadata does not match the manifest edge array.',
+                guide: FLOW_GUIDE,
+                repair: 'Write the declared manifest and extracted edge registry as one candidate transaction.',
+            }));
+        }
+    }
+    if (!canonicalDeepEqual(manifest.experiments, experimentsInput)) {
+        diagnostics.push(snapshotDiagnostic({
+            code: 'FG-FLOW-001',
+            file: EXPERIMENTS_FILE,
+            expected: summarizeFlowMismatchValue(manifest.experiments, 'experiments'),
+            received: summarizeFlowMismatchValue(experimentsInput, 'experiments'),
+            reason: 'Extracted experiment metadata does not match the manifest experiments.',
+            guide: FLOW_GUIDE,
+            repair: 'Write the manifest and experiment configuration as one candidate transaction.',
+        }));
+    }
+    return diagnostics;
+};
+const validateSnapshotDocs = (docsInput) => {
+    const diagnostics = [];
+    const docsRead = readBoundedOwnDataRecord(docsInput);
+    if (!docsRead.valid) {
+        return [snapshotDiagnostic({
+                code: 'FG-DOC-001',
+                file: DOCS_MANIFEST_FILE,
+                expected: 'a bounded own-data managed documentation status map',
+                received: docsRead.summary,
+                reason: 'The managed documentation status map is malformed or exceeds snapshot limits.',
+                repair: 'Provide a bounded plain documentation status map without accessors or symbols.',
+            })];
+    }
+    const docsValue = (field) => {
+        return docsRead.entries.get(field);
+    };
+    const headers = [
+        {
+            field: 'schemaVersion',
+            expected: 1,
+            received: docsValue('schemaVersion'),
+            valid: docsValue('schemaVersion') === 1,
+        },
+        {
+            field: 'bundleVersion',
+            expected: 'nonblank bundle version',
+            received: docsValue('bundleVersion'),
+            // Exact bundle-version comparison belongs to the docs adapter because this
+            // project snapshot intentionally carries no expected bundle version.
+            valid: isNonEmptyString(docsValue('bundleVersion')),
+        },
+        {
+            field: 'stepContractVersion',
+            expected: CURRENT_STEP_CONTRACT_VERSION,
+            received: docsValue('stepContractVersion'),
+            valid: docsValue('stepContractVersion') === CURRENT_STEP_CONTRACT_VERSION,
+        },
+        {
+            field: 'contractHash',
+            expected: CURRENT_STEP_CONTRACT_HASH,
+            received: docsValue('contractHash'),
+            valid: docsValue('contractHash') === CURRENT_STEP_CONTRACT_HASH,
+        },
+    ];
+    for (const header of headers) {
+        if (header.valid) {
+            continue;
+        }
+        diagnostics.push(snapshotDiagnostic({
+            code: 'FG-DOC-001',
+            file: DOCS_MANIFEST_FILE,
+            expected: { field: header.field, value: header.expected },
+            received: header.received,
+            reason: `Managed documentation ${header.field} is stale or invalid.`,
+            repair: 'Sync the current managed documentation bundle before authoring or publishing.',
+        }));
+    }
+    const readManagedPaths = (field, code) => {
+        const pathsRead = readBoundedDenseDataArray(docsValue(field));
+        let invalidEntryIndex = -1;
+        if (pathsRead.valid) {
+            invalidEntryIndex = pathsRead.values.findIndex((path) => !isNonEmptyString(path));
+        }
+        if (!pathsRead.valid || invalidEntryIndex !== -1) {
+            const received = !pathsRead.valid
+                ? Object.assign({ field }, pathsRead.summary) : {
+                field,
+                state: 'invalid-entry',
+                index: invalidEntryIndex,
+                receivedType: runtimeValueType(pathsRead.values[invalidEntryIndex]),
+            };
+            diagnostics.push(snapshotDiagnostic({
+                code,
+                file: DOCS_MANIFEST_FILE,
+                expected: 'a dense bounded array of nonblank managed paths',
+                received,
+                reason: `Managed documentation ${field} must be a strict path array.`,
+                repair: `Replace ${field} with a dense bounded array containing only nonblank path strings.`,
+            }));
+            return new Set();
+        }
+        return new Set(pathsRead.values);
+    };
+    const conflicts = readManagedPaths('conflicts', 'FG-DOC-002');
+    const changed = new Set([...readManagedPaths('changed', 'FG-DOC-001')].filter((path) => !conflicts.has(path)));
+    const missing = new Set([...readManagedPaths('missing', 'FG-DOC-001')].filter((path) => (!conflicts.has(path) && !changed.has(path))));
+    const statuses = [
+        { code: 'FG-DOC-002', status: 'conflict', paths: [...conflicts].sort() },
+        { code: 'FG-DOC-001', status: 'changed', paths: [...changed].sort() },
+        { code: 'FG-DOC-001', status: 'missing', paths: [...missing].sort() },
+    ];
+    for (const status of statuses) {
+        for (const path of status.paths) {
+            diagnostics.push(snapshotDiagnostic({
+                code: status.code,
+                file: path,
+                expected: 'current managed documentation bytes',
+                received: status.status,
+                reason: status.status === 'conflict'
+                    ? 'The managed documentation path has an unresolved local conflict.'
+                    : `The managed documentation path is ${status.status}.`,
+                repair: status.status === 'conflict'
+                    ? 'Resolve the managed-document conflict explicitly, preserving project guidance separately.'
+                    : 'Sync the current managed documentation bundle.',
+            }));
+        }
+    }
+    return diagnostics;
+};
+const hasInspectableNormalizedManifest = (input) => {
+    try {
+        const normalized = normalizeFunnelManifestInput(input, boundaryDiagnostic);
+        return normalized.manifest !== null && normalized.diagnostics.length === 0;
+    }
+    catch (_a) {
+        return false;
+    }
+};
+const runSnapshotValidationPhase = (phase) => {
+    try {
+        return phase.validate();
+    }
+    catch (_a) {
+        return [snapshotDiagnostic({
+                code: phase.code,
+                expected: 'inspectable plain snapshot phase data',
+                received: 'uninspectable runtime input',
+                reason: phase.reason,
+                guide: phase.guide,
+                repair: phase.repair,
+            })];
+    }
+};
+const inaccessibleSnapshotManifestDiagnostic = () => {
+    return snapshotDiagnostic({
+        code: 'FG-STEP-002',
+        file: MANIFEST_FILE,
+        expected: 'inspectable plain funnel manifest object',
+        received: 'uninspectable runtime input',
+        reason: 'The snapshot manifest could not be accessed safely.',
+        repair: 'Provide a plain snapshot object with a plain manifest data property.',
+    });
+};
+const SNAPSHOT_ROOT_FIELDS = [
+    'manifest',
+    'registeredComponentKeys',
+    'componentMetaByKey',
+    'contentOptionsByStepId',
+    'edgesByStepId',
+    'experiments',
+    'docs',
+];
+const captureSnapshotRootData = (input) => {
+    try {
+        if (!isPlainDataRecord(input)) {
+            return null;
+        }
+        const values = new Map();
+        const invalidFields = new Set();
+        for (const field of SNAPSHOT_ROOT_FIELDS) {
+            const property = readOwnDataProperty(input, field);
+            if (property.status === 'data') {
+                values.set(field, property.value);
+            }
+            else {
+                invalidFields.add(field);
+            }
+        }
+        const manifest = values.get('manifest');
+        if (invalidFields.has('manifest') || !isPlainDataRecord(manifest)) {
+            return null;
+        }
+        return {
+            manifest: manifest,
+            values,
+            invalidFields,
+        };
+    }
+    catch (_a) {
+        return null;
+    }
+};
+export const validateFunnelStepContractSnapshot = (input, options) => {
+    const captured = captureSnapshotRootData(input);
+    if (captured === null) {
+        return [inaccessibleSnapshotManifestDiagnostic()];
+    }
+    const diagnostics = validateFunnelManifestContract(captured.manifest, options);
+    if (!hasInspectableNormalizedManifest(captured.manifest)) {
+        return diagnostics;
+    }
+    const hasInvalidField = (...fields) => (fields.some((field) => captured.invalidFields.has(field)));
+    const phases = [
+        {
+            code: 'FG-REGISTRY-001',
+            reason: 'The component registry snapshot could not be inspected safely.',
+            repair: 'Provide plain component registry arrays and metadata records.',
+            validate: () => hasInvalidField('registeredComponentKeys', 'componentMetaByKey')
+                ? [snapshotDiagnostic({
+                        code: 'FG-REGISTRY-001',
+                        expected: 'own data properties for registry snapshot fields',
+                        received: 'missing or accessor-backed root field',
+                        reason: 'The component registry root fields must be own data properties.',
+                        repair: 'Provide own plain data properties for registry keys and component metadata.',
+                    })]
+                : validateSnapshotRegistry(captured.values.get('registeredComponentKeys'), captured.values.get('componentMetaByKey'), captured.manifest),
+        },
+        {
+            code: 'FG-PARITY-001',
+            reason: 'The component metadata snapshot could not be inspected safely for parity.',
+            repair: 'Provide plain component metadata records that can be compared with the manifest.',
+            validate: () => hasInvalidField('componentMetaByKey')
+                ? []
+                : validateSnapshotMetadataParity(captured.values.get('componentMetaByKey'), captured.manifest),
+        },
+        {
+            code: 'FG-CONTENT-001',
+            reason: 'The choice content snapshot could not be inspected safely.',
+            repair: 'Provide plain choice content arrays and option records.',
+            validate: () => hasInvalidField('contentOptionsByStepId')
+                ? [snapshotDiagnostic({
+                        code: 'FG-CONTENT-001',
+                        expected: 'own data property for contentOptionsByStepId',
+                        received: 'missing or accessor-backed root field',
+                        reason: 'The choice content root field must be an own data property.',
+                        repair: 'Provide an own plain data property for choice content.',
+                    })]
+                : validateSnapshotChoiceContent(captured.values.get('contentOptionsByStepId'), captured.manifest),
+        },
+        {
+            code: 'FG-FLOW-001',
+            guide: FLOW_GUIDE,
+            reason: 'The extracted flow snapshot could not be inspected safely.',
+            repair: 'Provide plain edge and experiment collections that match the manifest.',
+            validate: () => hasInvalidField('edgesByStepId', 'experiments')
+                ? [snapshotDiagnostic({
+                        code: 'FG-FLOW-001',
+                        expected: 'own data properties for flow snapshot fields',
+                        received: 'missing or accessor-backed root field',
+                        reason: 'The flow root fields must be own data properties.',
+                        guide: FLOW_GUIDE,
+                        repair: 'Provide own plain data properties for edges and experiments.',
+                    })]
+                : validateSnapshotFlowParity(captured.values.get('edgesByStepId'), captured.values.get('experiments'), captured.manifest),
+        },
+        {
+            code: 'FG-DOC-001',
+            reason: 'The managed documentation snapshot could not be inspected safely.',
+            repair: 'Provide a plain managed documentation status object.',
+            validate: () => hasInvalidField('docs')
+                ? [snapshotDiagnostic({
+                        code: 'FG-DOC-001',
+                        expected: 'own data property for docs',
+                        received: 'missing or accessor-backed root field',
+                        reason: 'The docs root field must be an own data property.',
+                        repair: 'Provide an own plain data property for managed documentation status.',
+                    })]
+                : validateSnapshotDocs(captured.values.get('docs')),
+        },
+    ];
+    for (const phase of phases) {
+        diagnostics.push(...runSnapshotValidationPhase(phase));
+    }
+    return diagnostics;
+};