@untangle-code/search 0.0.0-stage → 0.1.1

package/dist/product-complexity.js

@@ -0,0 +1,1367 @@
+/**
+ * Task-basierte Search Journeys und Dynamic Product Complexity.
+ *
+ * Dieser Reducer ist I/O-agnostisch. Er speichert ausschliesslich ueber den
+ * Domain-Port, liest Zeit/Zufall ueber Ports und berechnet jede Kennzahl aus
+ * den persistierten Beobachtungen neu. Damit kann derselbe Ablauf lokal, im
+ * MCP-Server und in Tests identisch laufen.
+ */
+import { DYNAMIC_SEARCH_COMPLEXITY_ALGORITHM_ID, INDEX_CONTEXT_INCOMPLETE_WARNING_CODE, MAX_SEARCH_JOURNEY_ATTEMPTS as DOMAIN_MAX_SEARCH_JOURNEY_ATTEMPTS, MAX_SEARCH_JOURNEY_EXECUTION_CONTEXT_LENGTH, MAX_SEARCH_JOURNEY_FEATURE_ID_LENGTH as DOMAIN_MAX_SEARCH_JOURNEY_FEATURE_ID_LENGTH, MAX_SEARCH_JOURNEY_LOCATOR_LENGTH, MAX_SEARCH_JOURNEY_NAVIGATION_EVENTS as DOMAIN_MAX_SEARCH_JOURNEY_NAVIGATION_EVENTS, MAX_SEARCH_JOURNEY_REASON_LENGTH, MAX_SEARCH_JOURNEY_TEXT_LENGTH, MAX_SEARCH_JOURNEY_TOOL_NAME_LENGTH, MINIMUM_PRODUCT_COMPLEXITY_SESSIONS as DOMAIN_MINIMUM_PRODUCT_COMPLEXITY_SESSIONS, RANKER_VERSION, SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS, SEARCH_JOURNEY_STATUSES, canonicalJson, compareCodepoints, hmacSha256Hex, isUntangleError, searchJourneyValidationIssue, sha256Hex, UntangleError, } from "@untangle-code/domain";
+export const MINIMUM_PRODUCT_COMPLEXITY_SESSIONS = DOMAIN_MINIMUM_PRODUCT_COMPLEXITY_SESSIONS;
+export const MAX_SEARCH_JOURNEY_ATTEMPTS = DOMAIN_MAX_SEARCH_JOURNEY_ATTEMPTS;
+export const MAX_SEARCH_JOURNEY_FEATURE_ID_LENGTH = DOMAIN_MAX_SEARCH_JOURNEY_FEATURE_ID_LENGTH;
+export const MAX_SEARCH_JOURNEY_NAVIGATION_EVENTS = DOMAIN_MAX_SEARCH_JOURNEY_NAVIGATION_EVENTS;
+function assertNonEmpty(value, field) {
+    const normalized = value.trim();
+    if (normalized === "")
+        throw new Error(`${field} must not be empty`);
+    return normalized;
+}
+function assertBoundedNonEmpty(value, field, maximum) {
+    const normalized = assertNonEmpty(value, field);
+    if (normalized.length > maximum) {
+        throw new Error(`${field} must contain at most ${String(maximum)} UTF-16 code units`);
+    }
+    return normalized;
+}
+function assertBoundedText(value, field, maximum) {
+    if (value.length > maximum) {
+        throw new Error(`${field} must contain at most ${String(maximum)} UTF-16 code units`);
+    }
+    return value;
+}
+function normalizedTarget(target) {
+    const normalized = {
+        ...(target.repoId === undefined
+            ? {}
+            : {
+                repoId: assertBoundedNonEmpty(target.repoId, "search journey target repoId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+            }),
+        ...(target.refId === undefined
+            ? {}
+            : {
+                refId: assertBoundedNonEmpty(target.refId, "search journey target refId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+            }),
+        ...(target.filePath === undefined
+            ? {}
+            : {
+                filePath: assertBoundedNonEmpty(target.filePath, "search journey target filePath", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+            }),
+        ...(target.chunkId === undefined
+            ? {}
+            : {
+                chunkId: assertBoundedNonEmpty(target.chunkId, "search journey target chunkId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+            }),
+        ...(target.symbolId === undefined
+            ? {}
+            : {
+                symbolId: assertBoundedNonEmpty(target.symbolId, "search journey target symbolId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+            }),
+        ...(target.embeddingProfileId === undefined
+            ? {}
+            : {
+                embeddingProfileId: assertBoundedNonEmpty(target.embeddingProfileId, "search journey target embeddingProfileId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+            }),
+        ...(target.indexGeneration === undefined
+            ? {}
+            : {
+                indexGeneration: assertBoundedNonEmpty(target.indexGeneration, "search journey target indexGeneration", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+            }),
+    };
+    const identity = [normalized.chunkId, normalized.symbolId, normalized.filePath].some((value) => typeof value === "string" && value.trim() !== "");
+    if (!identity) {
+        throw new Error("search journey target requires chunkId, symbolId or filePath");
+    }
+    return normalized;
+}
+function profilesOfProjection(projection) {
+    return projection.groups.map((group) => ({
+        embeddingProfileId: group.embeddingProfileId,
+        indexGenerations: group.indexGenerations === null
+            ? [...new Set(group.hits.map((hit) => hit.indexGeneration))].sort(compareCodepoints)
+            : [...new Set(group.indexGenerations)].sort(compareCodepoints),
+        ...(group.corpusRevisionFingerprint === null
+            ? {}
+            : { corpusRevisionFingerprint: group.corpusRevisionFingerprint }),
+        retrievalPerformed: group.notSearchedReason === undefined,
+        ...(group.notSearchedReason === undefined
+            ? {}
+            : { notSearchedReason: group.notSearchedReason }),
+        ...(group.retrieval === undefined ? {} : { retrieval: group.retrieval }),
+        candidates: group.hits.map((hit) => ({
+            repoId: hit.repoId,
+            refId: hit.refId,
+            filePath: hit.filePath,
+            chunkId: hit.chunkId,
+            ...(hit.symbolId === undefined ? {} : { symbolId: hit.symbolId }),
+            ...(hit.symbolFqn === undefined ? {} : { symbolFqn: hit.symbolFqn }),
+            embeddingProfileId: hit.embeddingProfileId,
+            indexGeneration: hit.indexGeneration,
+            rank: hit.rank,
+            score: hit.score,
+            ...(hit.complexity === null ? {} : { complexity: hit.complexity }),
+            incompletePayloadFields: [...hit.incompletePayloadFields],
+        })),
+    }));
+}
+function assertValidObservationProjection(projection) {
+    const probe = {
+        schemaVersion: 1,
+        revision: 0,
+        sessionId: "projection-validation",
+        workspaceId: "projection-validation",
+        status: "active",
+        recordingConsent: "explicit",
+        retainText: false,
+        goal: { fingerprint: "0".repeat(64) },
+        createdAt: "1970-01-01T00:00:00.000Z",
+        updatedAt: "1970-01-01T00:00:00.000Z",
+        attempts: [
+            {
+                attemptId: "projection-attempt",
+                sequence: 1,
+                measurementContextVersion: 2,
+                ...(projection.abstention === null ? {} : { abstention: projection.abstention }),
+                observationFingerprint: "0".repeat(64),
+                queryFingerprint: "0".repeat(64),
+                rankerVersion: projection.rankerVersion,
+                ...(projection.rankingContextFingerprint === null
+                    ? {}
+                    : { rankingContextFingerprint: projection.rankingContextFingerprint }),
+                resultLimit: projection.resultLimit,
+                candidateLimit: projection.candidateLimit,
+                observedAt: "1970-01-01T00:00:00.000Z",
+                status: "succeeded",
+                warningCodes: [...projection.warningCodes],
+                retrievalHealthy: projection.retrievalHealthy,
+                profiles: profilesOfProjection(projection),
+            },
+        ],
+        navigation: [],
+    };
+    assertValidSessionState(probe);
+}
+function projectComplexitySummary(complexity) {
+    return {
+        metricsScope: complexity.metricsScope,
+        metricsScopeId: assertBoundedNonEmpty(complexity.metricsScopeId, "search hit metricsScopeId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+        metricsVersion: assertBoundedNonEmpty(complexity.metricsVersion, "search hit metricsVersion", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+        ...(complexity.cyclomaticClassic === undefined
+            ? {}
+            : { cyclomaticClassic: complexity.cyclomaticClassic }),
+        ...(complexity.cyclomaticExtended === undefined
+            ? {}
+            : { cyclomaticExtended: complexity.cyclomaticExtended }),
+        ...(complexity.cognitive === undefined ? {} : { cognitive: complexity.cognitive }),
+        ...(complexity.maxNesting === undefined ? {} : { maxNesting: complexity.maxNesting }),
+        ...(complexity.sloc === undefined ? {} : { sloc: complexity.sloc }),
+        ...(complexity.halsteadVolume === undefined
+            ? {}
+            : { halsteadVolume: complexity.halsteadVolume }),
+        ...(complexity.maintainabilityIndex === undefined
+            ? {}
+            : { maintainabilityIndex: complexity.maintainabilityIndex }),
+        ...(complexity.riskScore === undefined ? {} : { riskScore: complexity.riskScore }),
+    };
+}
+function projectRetrievalDiagnostics(retrieval) {
+    return {
+        branchCandidateCounts: {
+            dense: retrieval.branchCandidateCounts.dense,
+            sparse: retrieval.branchCandidateCounts.sparse,
+            symbol: retrieval.branchCandidateCounts.symbol,
+        },
+        uniqueRetrievedCandidateCount: retrieval.uniqueRetrievedCandidateCount,
+        eligibleCandidateCount: retrieval.eligibleCandidateCount,
+        rankedCandidateCount: retrieval.rankedCandidateCount,
+        deduplicatedCandidateCount: retrieval.deduplicatedCandidateCount,
+        qualifiedHitCount: retrieval.qualifiedHitCount,
+        returnedHitCount: retrieval.returnedHitCount,
+        uniqueEligibleFileCount: retrieval.uniqueEligibleFileCount,
+        uniqueEligibleSymbolCount: retrieval.uniqueEligibleSymbolCount,
+        eligibleFileDispersion: retrieval.eligibleFileDispersion,
+        topScoreGap: retrieval.topScoreGap,
+        candidateLimitReached: retrieval.candidateLimitReached,
+    };
+}
+function projectSearchObservation(result, queryText) {
+    const queryFingerprint = assertBoundedNonEmpty(result.queryFingerprint, "search result queryFingerprint", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH);
+    const rankerVersion = assertBoundedNonEmpty(result.query.rankerVersion, "search result rankerVersion", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH);
+    const rankingContextFingerprint = result.rankingContextFingerprint === undefined
+        ? null
+        : assertBoundedNonEmpty(result.rankingContextFingerprint, "search result rankingContextFingerprint", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH);
+    const warningCodes = result.warnings
+        .map((warning) => assertBoundedNonEmpty(warning.code, "search result warning code", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH))
+        .sort(compareCodepoints);
+    const groups = result.groups.map((group) => {
+        const embeddingProfileId = assertBoundedNonEmpty(group.embeddingProfileId, "search result embeddingProfileId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH);
+        const indexGenerations = group.indexGenerations === undefined
+            ? null
+            : group.indexGenerations.map((generation) => assertBoundedNonEmpty(generation, "search result indexGeneration", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH));
+        const corpusRevisionFingerprint = group.corpusRevisionFingerprint === undefined
+            ? null
+            : assertBoundedNonEmpty(group.corpusRevisionFingerprint, "search result corpusRevisionFingerprint", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH);
+        const notSearchedReason = group.notSearchedReason === undefined
+            ? undefined
+            : assertBoundedText(group.notSearchedReason, "search result notSearchedReason", MAX_SEARCH_JOURNEY_REASON_LENGTH);
+        if (group.hits.length > result.query.limit) {
+            throw new Error("search result group contains more hits than its result limit");
+        }
+        const hits = group.hits.map((hit) => {
+            const complexity = hit.complexity === undefined ? null : projectComplexitySummary(hit.complexity);
+            return {
+                repoId: assertBoundedNonEmpty(hit.repoId, "search hit repoId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+                refId: assertBoundedNonEmpty(hit.refId, "search hit refId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+                filePath: assertBoundedText(hit.filePath, "search hit filePath", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+                chunkId: assertBoundedNonEmpty(hit.chunkId, "search hit chunkId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+                ...(hit.symbolId === undefined
+                    ? {}
+                    : {
+                        symbolId: assertBoundedNonEmpty(hit.symbolId, "search hit symbolId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+                    }),
+                ...(hit.symbolFqn === undefined
+                    ? {}
+                    : {
+                        symbolFqn: assertBoundedText(hit.symbolFqn, "search hit symbolFqn", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+                    }),
+                embeddingProfileId: assertBoundedNonEmpty(hit.embeddingProfileId, "search hit embeddingProfileId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+                indexGeneration: assertBoundedNonEmpty(hit.indexGeneration, "search hit indexGeneration", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH),
+                rank: hit.rank,
+                score: hit.score.final,
+                complexity,
+                incompletePayloadFields: (hit.incompletePayloadFields ?? []).map((field) => assertBoundedNonEmpty(field, "search hit incomplete payload field", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH)),
+            };
+        });
+        return {
+            embeddingProfileId,
+            indexGenerations,
+            corpusRevisionFingerprint,
+            ...(notSearchedReason === undefined ? {} : { notSearchedReason }),
+            ...(group.retrieval === undefined
+                ? {}
+                : { retrieval: projectRetrievalDiagnostics(group.retrieval) }),
+            hits,
+        };
+    });
+    const projection = {
+        queryFingerprint,
+        queryText,
+        rankerVersion,
+        rankingContextFingerprint,
+        resultLimit: result.query.limit,
+        candidateLimit: result.query.candidateLimit,
+        retrievalHealthy: retrievalHealthyOfResult(result),
+        groups,
+        warningCodes,
+        abstention: result.groups.find((group) => group.relevanceDecision !== undefined)?.relevanceDecision
+            ?.abstention ?? null,
+    };
+    assertValidObservationProjection(projection);
+    return projection;
+}
+function assertValidSessionState(session) {
+    const issue = searchJourneyValidationIssue(session);
+    if (issue !== null) {
+        throw new UntangleError("SEARCH_SESSION_INVALID_STATE", `search journey service produced an invalid state: ${issue}`, {
+            operation: "search_journey_service",
+            context: { sessionId: session.sessionId, validationIssue: issue },
+        });
+    }
+}
+function targetMatches(candidate, target) {
+    const fields = [
+        "repoId",
+        "refId",
+        "filePath",
+        "chunkId",
+        "symbolId",
+        "embeddingProfileId",
+        "indexGeneration",
+    ];
+    return fields.every((field) => target[field] === undefined || candidate[field] === target[field]);
+}
+function candidateKey(candidate) {
+    return canonicalJson([
+        candidate.embeddingProfileId,
+        candidate.indexGeneration,
+        candidate.repoId,
+        candidate.refId,
+        candidate.chunkId,
+    ]);
+}
+function candidateCodeEvidence(candidate) {
+    return canonicalJson({
+        complexity: candidate.complexity ?? null,
+        incompletePayloadFields: candidate.incompletePayloadFields ?? null,
+    });
+}
+function cloneSession(session) {
+    return structuredClone(session);
+}
+function journeyFingerprint(fingerprintKey, workspaceId, purpose, value) {
+    return hmacSha256Hex(fingerprintKey, canonicalJson({
+        schemaVersion: 1,
+        namespace: "untangle-search-journey",
+        workspaceId,
+        purpose,
+        value,
+    }));
+}
+function normalizeExecutionContext(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("executionContext must be an object of explicit caller labels");
+    }
+    if (Object.keys(value).some((key) => !SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS.some((dimension) => dimension === key))) {
+        throw new Error("executionContext contains an unknown dimension");
+    }
+    const normalized = {};
+    for (const dimension of SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS) {
+        const label = value[dimension];
+        if (label === undefined && (dimension === "taskMix" || dimension === "priorContext"))
+            continue;
+        if (typeof label !== "string") {
+            throw new Error(`executionContext.${dimension} must be a non-empty string`);
+        }
+        normalized[dimension] = assertBoundedNonEmpty(label, `executionContext.${dimension}`, MAX_SEARCH_JOURNEY_EXECUTION_CONTEXT_LENGTH);
+    }
+    return normalized;
+}
+function persistExecutionContext(input, fingerprintKey, workspaceId, retainText) {
+    const fields = Object.fromEntries(SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS.flatMap((dimension) => {
+        const label = input[dimension];
+        return label === undefined
+            ? []
+            : [
+                [
+                    dimension,
+                    {
+                        fingerprint: journeyFingerprint(fingerprintKey, workspaceId, "execution-context", {
+                            dimension,
+                            label,
+                        }),
+                        ...(retainText ? { text: label } : {}),
+                    },
+                ],
+            ];
+    }));
+    return {
+        schemaVersion: 1,
+        source: "caller-declared",
+        ...fields,
+    };
+}
+function executionContextEvidence(session) {
+    const context = session.executionContext;
+    if (context === undefined) {
+        return {
+            status: "not-recorded",
+            uncontrolledDimensions: [...SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS],
+        };
+    }
+    // Caller fingerprints are grouping evidence only after the persisted shape and retention contract pass.
+    assertValidSessionState(session);
+    const dimensions = SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS.map((dimension) => [
+        dimension,
+        context[dimension]?.fingerprint ?? null,
+    ]);
+    return {
+        status: "caller-declared",
+        fingerprint: sha256Hex(canonicalJson({ schemaVersion: 1, dimensions })),
+        uncontrolledDimensions: SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS.filter((dimension) => context[dimension] === undefined),
+    };
+}
+function reportContextId(session, retrievalContextId) {
+    const execution = executionContextEvidence(session);
+    return execution.status === "not-recorded"
+        ? retrievalContextId
+        : sha256Hex(canonicalJson({
+            schemaVersion: 1,
+            retrievalContextId,
+            executionContext: execution.fingerprint,
+        }));
+}
+function journeyQueryFingerprint(fingerprintKey, workspaceId, query) {
+    return journeyFingerprint(fingerprintKey, workspaceId, "query", query.trim());
+}
+function assertClientStep(step) {
+    if (step !== undefined &&
+        (!Number.isSafeInteger(step) || step < 1 || step > MAX_SEARCH_JOURNEY_ATTEMPTS)) {
+        throw new Error(`search journey step must be an integer in [1, ${String(MAX_SEARCH_JOURNEY_ATTEMPTS)}]`);
+    }
+}
+function assertConsistentStepMode(attempts, step, sessionId) {
+    if (attempts.length === 0)
+        return;
+    const numbered = attempts.filter((attempt) => attempt.clientStep !== undefined).length;
+    if (numbered !== 0 && numbered !== attempts.length) {
+        throw new UntangleError("SEARCH_SESSION_INVALID_STATE", `search journey "${sessionId}" contains mixed numbered and unnumbered attempts`, { operation: "search_journey_record", context: { sessionId } });
+    }
+    const expectsStep = numbered === attempts.length;
+    if (expectsStep !== (step !== undefined)) {
+        throw new UntangleError("SEARCH_SESSION_INVALID_STATE", `search journey "${sessionId}" cannot mix numbered and unnumbered attempts`, { operation: "search_journey_record", context: { sessionId } });
+    }
+}
+function sortAttempts(attempts) {
+    attempts.sort((left, right) => {
+        return ((left.clientStep ?? left.sequence) - (right.clientStep ?? right.sequence) ||
+            compareCodepoints(left.observedAt, right.observedAt) ||
+            compareCodepoints(left.attemptId, right.attemptId));
+    });
+    attempts.forEach((attempt, index) => {
+        attempt.sequence = index + 1;
+    });
+}
+function retrievalHealthyOfResult(result) {
+    return (result.groups.length > 0 &&
+        result.groups.every((group) => group.notSearchedReason === undefined) &&
+        !result.warnings.some((warning) => warning.code === INDEX_CONTEXT_INCOMPLETE_WARNING_CODE ||
+            warning.code === "SEARCH_BRANCH_UNAVAILABLE" ||
+            warning.code === "INCOMPLETE_PAYLOAD") &&
+        !result.skipped.some((entry) => entry.subjectKind === "search_candidate" &&
+            (entry.reason === "provider_unavailable" || entry.reason === "missing_index_entry")));
+}
+function observationFingerprintOfProjection(fingerprintKey, workspaceId, projection, includeCodeEvidence = true) {
+    return journeyFingerprint(fingerprintKey, workspaceId, "successful-observation", {
+        queryFingerprint: projection.queryFingerprint,
+        queryText: projection.queryText,
+        rankerVersion: projection.rankerVersion,
+        rankingContextFingerprint: projection.rankingContextFingerprint,
+        resultLimit: projection.resultLimit,
+        candidateLimit: projection.candidateLimit,
+        retrievalHealthy: projection.retrievalHealthy,
+        groups: projection.groups.map((group) => ({
+            embeddingProfileId: group.embeddingProfileId,
+            indexGenerations: group.indexGenerations,
+            ...(includeCodeEvidence
+                ? { corpusRevisionFingerprint: group.corpusRevisionFingerprint }
+                : {}),
+            notSearchedReason: group.notSearchedReason,
+            retrieval: group.retrieval,
+            hits: group.hits.map((hit) => ({
+                repoId: hit.repoId,
+                refId: hit.refId,
+                filePath: hit.filePath,
+                chunkId: hit.chunkId,
+                symbolId: hit.symbolId,
+                symbolFqn: hit.symbolFqn,
+                indexGeneration: hit.indexGeneration,
+                rank: hit.rank,
+                score: hit.score,
+                ...(includeCodeEvidence
+                    ? {
+                        complexity: hit.complexity,
+                        incompletePayloadFields: hit.incompletePayloadFields,
+                    }
+                    : {}),
+            })),
+        })),
+        warningCodes: projection.warningCodes,
+    });
+}
+function compareCandidates(left, right) {
+    return (left.rank - right.rank ||
+        compareCodepoints(left.embeddingProfileId, right.embeddingProfileId) ||
+        compareCodepoints(left.indexGeneration, right.indexGeneration) ||
+        compareCodepoints(left.repoId, right.repoId) ||
+        compareCodepoints(left.refId, right.refId) ||
+        compareCodepoints(left.filePath, right.filePath) ||
+        compareCodepoints(left.chunkId, right.chunkId));
+}
+function targetCodeComplexityEvidence(acceptedCandidates, accepted) {
+    if (acceptedCandidates.length === 0) {
+        return { status: "unavailable", reason: "target-not-returned" };
+    }
+    if (accepted === null ||
+        new Set(acceptedCandidates.map((candidate) => candidateKey(candidate))).size !== 1 ||
+        new Set(acceptedCandidates.map((candidate) => candidateCodeEvidence(candidate))).size !== 1) {
+        return { status: "unavailable", reason: "target-context-ambiguous" };
+    }
+    // New observations always carry this field, including the empty array.
+    // Its absence therefore means that an older persisted candidate cannot
+    // prove whether substituted payload values were involved.
+    if (accepted.incompletePayloadFields === undefined) {
+        return { status: "unavailable", reason: "legacy-observation" };
+    }
+    if (accepted.complexity === undefined) {
+        return { status: "unavailable", reason: "complexity-not-indexed" };
+    }
+    const incompletePayloadFields = [...new Set(accepted.incompletePayloadFields)].sort(compareCodepoints);
+    return {
+        status: "observed",
+        source: "indexed-search-hit",
+        candidate: {
+            repoId: accepted.repoId,
+            refId: accepted.refId,
+            filePath: accepted.filePath,
+            chunkId: accepted.chunkId,
+            ...(accepted.symbolId === undefined ? {} : { symbolId: accepted.symbolId }),
+            ...(accepted.symbolFqn === undefined ? {} : { symbolFqn: accepted.symbolFqn }),
+            embeddingProfileId: accepted.embeddingProfileId,
+            indexGeneration: accepted.indexGeneration,
+        },
+        complexity: structuredClone(accepted.complexity),
+        payloadComplete: incompletePayloadFields.length === 0,
+        incompletePayloadFields,
+    };
+}
+function attemptContextKey(attempt) {
+    const profiles = attempt.profiles
+        .map((profile) => ({
+        embeddingProfileId: profile.embeddingProfileId,
+        indexGenerations: profile.indexGenerations.length === 0
+            ? ["unknown"]
+            : [...profile.indexGenerations].sort(compareCodepoints),
+        corpusRevisionFingerprint: profile.corpusRevisionFingerprint ?? "unknown",
+    }))
+        .sort((left, right) => compareCodepoints(canonicalJson(left), canonicalJson(right)));
+    return canonicalJson({
+        rankerVersion: attempt.rankerVersion,
+        rankingContextFingerprint: attempt.rankingContextFingerprint ?? "unknown",
+        resultLimit: attempt.resultLimit ?? "unknown",
+        candidateLimit: attempt.candidateLimit ?? "unknown",
+        profiles,
+    });
+}
+function legacyContextId(attempts) {
+    const rankers = [...new Set(attempts.map((attempt) => attempt.rankerVersion))].sort(compareCodepoints);
+    const profiles = [
+        ...new Set(attempts.flatMap((attempt) => attempt.profiles.flatMap((profile) => profile.indexGenerations.length === 0
+            ? [`${profile.embeddingProfileId}\u001funknown`]
+            : profile.indexGenerations.map((generation) => `${profile.embeddingProfileId}\u001f${generation}`)))),
+    ].sort(compareCodepoints);
+    const rankingContexts = [
+        ...new Set(attempts.map((attempt) => attempt.rankingContextFingerprint ?? "unknown")),
+    ].sort(compareCodepoints);
+    const limits = [
+        ...new Set(attempts.map((attempt) => `${String(attempt.resultLimit ?? "unknown")}\u001f${String(attempt.candidateLimit ?? "unknown")}`)),
+    ].sort(compareCodepoints);
+    return sha256Hex(canonicalJson({ rankers, profiles, rankingContexts, limits }));
+}
+function contextId(attempts) {
+    const contextualAttempts = attempts.some((attempt) => attempt.status === "succeeded")
+        ? attempts.filter((attempt) => attempt.status === "succeeded")
+        : attempts;
+    if (contextualAttempts.every((attempt) => attempt.measurementContextVersion === undefined)) {
+        return legacyContextId(contextualAttempts);
+    }
+    const attemptContexts = [...new Set(contextualAttempts.map(attemptContextKey))].sort(compareCodepoints);
+    return sha256Hex(canonicalJson({ schemaVersion: 2, attemptContexts }));
+}
+function measurementContextComplete(attempts) {
+    const versioned = attempts.some((attempt) => attempt.measurementContextVersion !== undefined);
+    return (attempts.length > 0 &&
+        attempts.every((attempt) => (!versioned || attempt.measurementContextVersion === 2) &&
+            attempt.status === "succeeded" &&
+            attempt.retrievalHealthy &&
+            attempt.rankingContextFingerprint !== undefined &&
+            attempt.resultLimit !== undefined &&
+            attempt.candidateLimit !== undefined &&
+            attempt.profiles.length > 0 &&
+            attempt.profiles.every((profile) => (!versioned || profile.corpusRevisionFingerprint !== undefined) &&
+                profile.retrieval !== undefined &&
+                profile.indexGenerations.length > 0 &&
+                profile.indexGenerations.every((generation) => generation !== "unknown"))) &&
+        new Set(attempts.map(attemptContextKey)).size === 1);
+}
+function attemptHasRetrieval(attempt) {
+    return (attempt.status === "succeeded" && attempt.profiles.some((profile) => profile.retrievalPerformed));
+}
+function jaccardDistance(left, right) {
+    const union = new Set([...left, ...right]);
+    if (union.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const value of left)
+        if (right.has(value))
+            intersection++;
+    return 1 - intersection / union.size;
+}
+/** Berechnet die erklaerbaren Komponenten einer abgeschlossenen Journey. */
+export function assessSearchJourney(session, input) {
+    const target = normalizedTarget(input.target);
+    if (session.attempts.length === 0) {
+        throw new Error("search journey cannot be completed before at least one search attempt");
+    }
+    const numberedSteps = session.attempts.flatMap((attempt) => attempt.clientStep === undefined ? [] : [attempt.clientStep]);
+    if (numberedSteps.length > 0) {
+        const maximum = Math.max(...numberedSteps);
+        const present = new Set(numberedSteps);
+        const missing = Array.from({ length: maximum }, (_, index) => index + 1).filter((step) => !present.has(step));
+        if (missing.length > 0) {
+            throw new Error(`search journey cannot be completed with missing client step(s): ${missing.join(", ")}`);
+        }
+    }
+    const requestedAttempt = input.acceptedAttemptId === undefined
+        ? undefined
+        : session.attempts.find((attempt) => attempt.attemptId === input.acceptedAttemptId);
+    if (input.acceptedAttemptId !== undefined && requestedAttempt === undefined) {
+        throw new Error(`search journey has no attempt "${input.acceptedAttemptId}"`);
+    }
+    const attemptsWithTarget = session.attempts.filter((attempt) => attempt.profiles.some((profile) => profile.candidates.some((candidate) => targetMatches(candidate, target))));
+    if (requestedAttempt !== undefined &&
+        !attemptsWithTarget.some((attempt) => attempt.attemptId === requestedAttempt.attemptId)) {
+        throw new Error(`accepted attempt "${requestedAttempt.attemptId}" does not contain the confirmed target`);
+    }
+    // Der letzte passende Versuch entspricht ohne explizite Auswahl am ehesten
+    // dem Treffer, den der Agent gerade akzeptiert hat. Bei expliziter Auswahl
+    // zaehlen nur Versuche bis zu diesem Schritt: spaeter/out-of-order
+    // eingetroffene Beobachtungen duerfen die Suche bis zum Ziel nicht aufblasen.
+    const acceptedAttempt = requestedAttempt ?? attemptsWithTarget[attemptsWithTarget.length - 1] ?? null;
+    const attemptsToTarget = requestedAttempt === undefined
+        ? session.attempts
+        : session.attempts.filter((attempt) => attempt.sequence <= requestedAttempt.sequence);
+    const acceptedCandidates = acceptedAttempt === null
+        ? []
+        : acceptedAttempt.profiles
+            .flatMap((profile) => profile.candidates)
+            .filter((candidate) => targetMatches(candidate, target))
+            .sort(compareCandidates);
+    const acceptedContexts = new Set(acceptedCandidates.map((candidate) => `${candidate.embeddingProfileId}\u001f${candidate.indexGeneration}`));
+    const targetWasReturned = acceptedCandidates.length > 0;
+    const accepted = acceptedContexts.size <= 1 ? (acceptedCandidates[0] ?? null) : null;
+    const acceptedTargetCodeComplexity = targetCodeComplexityEvidence(acceptedCandidates, accepted);
+    const firstReturnedAttempt = attemptsWithTarget.find((attempt) => acceptedAttempt === null || attempt.sequence <= acceptedAttempt.sequence) ?? null;
+    const distinctQueries = new Set(attemptsToTarget.map((attempt) => attempt.queryFingerprint));
+    const allCandidates = attemptsToTarget.flatMap((attempt) => attempt.profiles.flatMap((profile) => profile.candidates));
+    const uniqueCandidates = new Map(allCandidates.map((candidate) => [candidateKey(candidate), candidate]));
+    const uniqueFiles = new Set(allCandidates.map((candidate) => `${candidate.repoId}\u001f${candidate.refId}\u001f${candidate.filePath}`));
+    const retrievals = attemptsToTarget.flatMap((attempt) => attempt.profiles.flatMap((profile) => profile.retrieval === undefined ? [] : [profile.retrieval]));
+    const eligibleCandidatesExamined = retrievals.reduce((sum, retrieval) => sum + retrieval.eligibleCandidateCount, 0);
+    const dispersionWeight = retrievals.reduce((sum, retrieval) => sum + retrieval.eligibleCandidateCount, 0);
+    const meanCandidateFileDispersion = dispersionWeight === 0
+        ? null
+        : retrievals.reduce((sum, retrieval) => sum + retrieval.eligibleFileDispersion * retrieval.eligibleCandidateCount, 0) / dispersionWeight;
+    const retrievedAttempts = attemptsToTarget.filter(attemptHasRetrieval);
+    const candidateLimitHitRate = retrievedAttempts.length === 0
+        ? 0
+        : retrievedAttempts.filter((attempt) => attempt.profiles.some((profile) => profile.retrieval?.candidateLimitReached === true)).length / retrievedAttempts.length;
+    const successfulCandidateSets = attemptsToTarget.flatMap((attempt) => !attemptHasRetrieval(attempt)
+        ? []
+        : [
+            new Set(attempt.profiles.flatMap((profile) => profile.candidates.map((candidate) => candidateKey(candidate)))),
+        ]);
+    const churnPairs = successfulCandidateSets
+        .slice(1)
+        .map((current, index) => jaccardDistance(successfulCandidateSets[index], current));
+    const meanCandidateChurn = churnPairs.length === 0 ? null : mean(churnPairs);
+    const successfulSearchesToTarget = attemptsToTarget.filter((attempt) => attempt.status === "succeeded").length;
+    const failedSearchesToTarget = attemptsToTarget.length - successfulSearchesToTarget;
+    const healthyRetrievalRate = attemptsToTarget.length === 0
+        ? 0
+        : attemptsToTarget.filter((attempt) => attempt.retrievalHealthy).length /
+            attemptsToTarget.length;
+    let acceptedTargetScoreMargin = null;
+    if (accepted !== null && acceptedAttempt !== null) {
+        const profile = acceptedAttempt.profiles.find((entry) => entry.embeddingProfileId === accepted.embeddingProfileId);
+        const sameProfile = (profile?.candidates ?? []).filter((candidate) => candidate.indexGeneration === accepted.indexGeneration);
+        const competitor = sameProfile
+            .filter((candidate) => candidateKey(candidate) !== candidateKey(accepted))
+            .sort((left, right) => right.score - left.score || compareCandidates(left, right))[0];
+        if (competitor !== undefined)
+            acceptedTargetScoreMargin = accepted.score - competitor.score;
+    }
+    const caveats = [
+        "This is a heuristic observation of one task, not cognitive complexity.",
+        "A confirmed target labels one accepted result; it does not label every candidate, so precision is not claimed.",
+        "Observed target code complexity is a separate static evidence axis; it is not combined with retrieval effort into a score or a causal claim.",
+        session.executionContext === undefined
+            ? "Agent model, harness, prior context and search strategy are not captured for this session; compare observations only under externally controlled caller conditions."
+            : "Execution context was explicitly caller-declared at journey start; report cohorts segment those fingerprints without independently verifying the declarations or asserting causation.",
+    ];
+    if (!targetWasReturned) {
+        caveats.push("The confirmed target was not present in a returned result; rank, reciprocal rank and score margin are unavailable.");
+    }
+    if (session.navigation.length === 0) {
+        caveats.push("No navigation events were reported; observedToolAndFileHops contains search calls only.");
+    }
+    if (retrievals.length === 0) {
+        caveats.push("No retrieval diagnostics were available; eligible-candidate and dispersion indicators are incomplete.");
+    }
+    if (attemptsToTarget.some((attempt) => attempt.status === "failed")) {
+        caveats.push("At least one search attempt failed; failures remain counted as search effort and their effective retrieval limits are unavailable.");
+    }
+    if (acceptedContexts.size > 1) {
+        caveats.push("The confirmed target appeared in multiple embedding-profile or generation contexts; rank, reciprocal rank and score margin remain unavailable until the target locator selects one context.");
+    }
+    if (acceptedTargetCodeComplexity.status === "unavailable") {
+        caveats.push(`Static code complexity for the confirmed target is unavailable (${acceptedTargetCodeComplexity.reason}); no value was inferred.`);
+    }
+    else if (!acceptedTargetCodeComplexity.payloadComplete) {
+        caveats.push("The confirmed target carries static code metrics, but its search payload used documented substitutes; inspect incompletePayloadFields before comparison.");
+    }
+    if (requestedAttempt !== undefined && requestedAttempt.sequence < session.attempts.length) {
+        caveats.push("Search metrics stop at the explicitly accepted attempt; independently ordered navigation events still include every event reported before completion.");
+    }
+    if (requestedAttempt === undefined && acceptedAttempt !== null) {
+        caveats.push("No acceptedAttemptId was supplied; every search through completion remains counted, while target rank and score margin use the last matching attempt.");
+    }
+    const contextComplete = measurementContextComplete(attemptsToTarget);
+    if (!contextComplete) {
+        caveats.push("The effective ranking policy, limits, embedding profiles, index generations or retrieval diagnostics are incomplete or changed across counted attempts; this observation cannot contribute sufficient product-level cohort evidence.");
+    }
+    return {
+        schemaVersion: 1,
+        algorithm: DYNAMIC_SEARCH_COMPLEXITY_ALGORITHM_ID,
+        isHeuristic: true,
+        searchesToTarget: attemptsToTarget.length,
+        successfulSearchesToTarget,
+        failedSearchesToTarget,
+        distinctQueryCount: distinctQueries.size,
+        queryReformulations: Math.max(0, distinctQueries.size - 1),
+        acceptedTargetRank: accepted?.rank ?? null,
+        reciprocalRank: accepted === null ? null : 1 / accepted.rank,
+        targetWasReturned,
+        targetFirstReturnedAtSearch: firstReturnedAttempt?.sequence ?? null,
+        targetAcceptedAtSearch: acceptedAttempt?.sequence ?? null,
+        selectionLagSearches: acceptedAttempt === null || firstReturnedAttempt === null
+            ? null
+            : acceptedAttempt.sequence - firstReturnedAttempt.sequence,
+        directHit: attemptsToTarget.length === 1 && acceptedAttempt?.sequence === 1 && accepted?.rank === 1,
+        eligibleCandidatesExamined,
+        uniqueCandidatesExposed: uniqueCandidates.size,
+        uniqueFilesExposed: uniqueFiles.size,
+        navigationEventsToTarget: session.navigation.length,
+        observedToolAndFileHops: attemptsToTarget.length + session.navigation.length,
+        meanCandidateFileDispersion,
+        meanCandidateChurn,
+        candidateLimitHitRate,
+        healthyRetrievalRate,
+        acceptedTargetScoreMargin,
+        acceptedTargetCodeComplexity,
+        measurementContextId: contextId(attemptsToTarget),
+        measurementContextComplete: contextComplete,
+        caveats,
+    };
+}
+function quantile(values, fraction) {
+    if (values.length === 0)
+        throw new Error("quantile needs at least one value");
+    const ordered = [...values].sort((left, right) => left - right);
+    const index = Math.max(0, Math.ceil(fraction * ordered.length) - 1);
+    return ordered[index];
+}
+function median(values) {
+    const ordered = [...values].sort((left, right) => left - right);
+    const middle = Math.floor(ordered.length / 2);
+    if (ordered.length % 2 === 1)
+        return ordered[middle];
+    return (ordered[middle - 1] + ordered[middle]) / 2;
+}
+function mean(values) {
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function buildCohort(measurementContextId, assessments, executionContext) {
+    const ranks = assessments.flatMap((assessment) => assessment.acceptedTargetRank === null ? [] : [assessment.acceptedTargetRank]);
+    const reciprocalRanks = assessments.flatMap((assessment) => assessment.reciprocalRank === null ? [] : [assessment.reciprocalRank]);
+    const dispersions = assessments.flatMap((assessment) => assessment.meanCandidateFileDispersion === null ? [] : [assessment.meanCandidateFileDispersion]);
+    const churn = assessments.flatMap((assessment) => assessment.meanCandidateChurn === null ? [] : [assessment.meanCandidateChurn]);
+    const contextComplete = assessments.every((assessment) => assessment.measurementContextComplete);
+    const sufficientEvidence = contextComplete && assessments.length >= MINIMUM_PRODUCT_COMPLEXITY_SESSIONS;
+    return {
+        measurementContextId,
+        completedSessionCount: assessments.length,
+        measurementContextComplete: contextComplete,
+        sufficientEvidence,
+        minimumCompletedSessions: MINIMUM_PRODUCT_COMPLEXITY_SESSIONS,
+        executionContext,
+        callerConditionsControlled: executionContext.uncontrolledDimensions.length === 0,
+        medianSearchesToTarget: median(assessments.map((assessment) => assessment.searchesToTarget)),
+        p90SearchesToTarget: quantile(assessments.map((assessment) => assessment.searchesToTarget), 0.9),
+        medianQueryReformulations: median(assessments.map((assessment) => assessment.queryReformulations)),
+        medianAcceptedTargetRank: ranks.length === 0 ? null : median(ranks),
+        meanReciprocalRank: reciprocalRanks.length === 0 ? null : mean(reciprocalRanks),
+        targetReturnedRate: assessments.filter((assessment) => assessment.targetWasReturned).length / assessments.length,
+        directHitRate: assessments.filter((assessment) => assessment.directHit).length / assessments.length,
+        healthyRetrievalRate: mean(assessments.map((assessment) => assessment.healthyRetrievalRate)),
+        medianEligibleCandidatesExamined: median(assessments.map((assessment) => assessment.eligibleCandidatesExamined)),
+        medianUniqueFilesExposed: median(assessments.map((assessment) => assessment.uniqueFilesExposed)),
+        meanCandidateFileDispersion: dispersions.length === 0 ? null : mean(dispersions),
+        meanCandidateChurn: churn.length === 0 ? null : mean(churn),
+        candidateLimitHitRate: mean(assessments.map((assessment) => assessment.candidateLimitHitRate)),
+        caveats: [
+            ...(!contextComplete
+                ? [
+                    "At least one observation has an incomplete effective retrieval context; this cohort cannot be treated as sufficient product-level evidence.",
+                ]
+                : sufficientEvidence
+                    ? [
+                        "This is a heuristic cohort signal segmented by ranker, embedding profile and index generation; it is neither a temporal trend nor a static code metric.",
+                    ]
+                    : [
+                        `Only ${String(assessments.length)} completed session(s) are available; at least ${String(MINIMUM_PRODUCT_COMPLEXITY_SESSIONS)} are required before treating this cohort as sufficient product-level evidence.`,
+                    ]),
+            executionContext.status === "not-recorded"
+                ? "Caller execution conditions were not recorded; retrieval sufficiency does not establish comparable agent behavior."
+                : "Execution conditions are caller-declared, not independently verified; equal labels do not establish a causal product effect.",
+            ...(executionContext.uncontrolledDimensions.length === 0
+                ? []
+                : [
+                    `Uncontrolled execution dimensions: ${executionContext.uncontrolledDimensions.join(", ")}.`,
+                ]),
+        ],
+    };
+}
+function reportAssessment(session) {
+    if (session.outcome?.kind !== "completed") {
+        throw new Error("report assessment requires a completed search journey");
+    }
+    const assessment = session.outcome.assessment;
+    const contextualAssessment = {
+        ...assessment,
+        measurementContextId: reportContextId(session, assessment.measurementContextId),
+    };
+    if (session.attempts.every((attempt) => attempt.measurementContextVersion === 2)) {
+        return contextualAssessment;
+    }
+    return {
+        ...contextualAssessment,
+        measurementContextComplete: false,
+        caveats: [
+            ...assessment.caveats,
+            "This legacy observation predates immutable corpus-revision fingerprints; it remains visible but cannot contribute sufficient product-level evidence.",
+        ],
+    };
+}
+function buildFeatureMapping(featureFingerprint, measurementContextId, observations) {
+    const targetGroups = new Map();
+    for (const observation of observations) {
+        const key = canonicalJson(observation.target);
+        const group = targetGroups.get(key) ?? [];
+        group.push(observation);
+        targetGroups.set(key, group);
+    }
+    const targets = [...targetGroups.entries()]
+        .sort(([left], [right]) => compareCodepoints(left, right))
+        .map(([, targetObservations]) => {
+        const first = targetObservations[0];
+        if (first === undefined)
+            throw new Error("feature target group must not be empty");
+        const variants = new Map();
+        for (const observation of targetObservations) {
+            const evidence = observation.assessment.acceptedTargetCodeComplexity ?? {
+                status: "unavailable",
+                reason: "legacy-observation",
+            };
+            const key = canonicalJson(evidence);
+            const existing = variants.get(key);
+            if (existing === undefined) {
+                variants.set(key, { evidence: structuredClone(evidence), completedSessionCount: 1 });
+            }
+            else {
+                existing.completedSessionCount += 1;
+            }
+        }
+        return {
+            target: structuredClone(first.target),
+            completedSessionCount: targetObservations.length,
+            complexityVariants: [...variants.entries()]
+                .sort(([left], [right]) => compareCodepoints(left, right))
+                .map(([, variant]) => variant),
+        };
+    });
+    const evidence = observations.map((observation) => observation.assessment.acceptedTargetCodeComplexity ?? {
+        status: "unavailable",
+        reason: "legacy-observation",
+    });
+    const observedComplexitySessionCount = evidence.filter((entry) => entry.status === "observed").length;
+    const incompletePayloadCount = evidence.filter((entry) => entry.status === "observed" && !entry.payloadComplete).length;
+    const unavailableComplexitySessionCount = evidence.length - observedComplexitySessionCount;
+    const distinctGoalCount = new Set(observations.map((entry) => entry.goalFingerprint)).size;
+    const caveats = [
+        "Search effort and static target-code complexity are separate evidence axes; no combined score or causal relationship is asserted.",
+        "Different target-locator precision can represent the same physical code as multiple confirmed targets; compare locators before interpreting target counts.",
+    ];
+    if (distinctGoalCount > 1) {
+        caveats.push("This feature mapping contains multiple task goals; search medians describe the observed feature workload, not repeated identical prompts.");
+    }
+    if (unavailableComplexitySessionCount > 0) {
+        caveats.push(`${String(unavailableComplexitySessionCount)} completed session(s) have no attributable static target-code complexity; missing values remain explicit and are never treated as zero.`);
+    }
+    if (incompletePayloadCount > 0) {
+        caveats.push(`${String(incompletePayloadCount)} observed static complexity value(s) came from search hits with incomplete payload provenance.`);
+    }
+    return {
+        featureFingerprint,
+        measurementContextId,
+        distinctGoalCount,
+        search: buildCohort(measurementContextId, observations.map((observation) => observation.assessment), observations[0]?.executionContext ?? {
+            status: "not-recorded",
+            uncontrolledDimensions: [...SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS],
+        }),
+        code: {
+            confirmedTargetCount: targets.length,
+            observedComplexitySessionCount,
+            unavailableComplexitySessionCount,
+            targets,
+        },
+        caveats,
+    };
+}
+function buildOutcomeCohorts(sessions) {
+    const grouped = new Map();
+    for (const session of sessions) {
+        const retrievalContextId = contextId(session.attempts);
+        const measurementContextId = reportContextId(session, retrievalContextId);
+        const key = canonicalJson([measurementContextId, session.feature?.fingerprint ?? null]);
+        const group = grouped.get(key) ?? {
+            measurementContextId,
+            retrievalContextId,
+            executionContext: executionContextEvidence(session),
+            ...(session.feature === undefined ? {} : { featureFingerprint: session.feature.fingerprint }),
+            sessions: [],
+        };
+        group.sessions.push(session);
+        grouped.set(key, group);
+    }
+    return [...grouped.entries()]
+        .sort(([left], [right]) => compareCodepoints(left, right))
+        .map(([, group]) => {
+        const completed = group.sessions.filter((session) => session.status === "completed").length;
+        const abandoned = group.sessions.filter((session) => session.status === "abandoned").length;
+        const terminal = completed + abandoned;
+        const reasons = new Map();
+        for (const session of group.sessions) {
+            if (session.outcome?.kind !== "abandoned")
+                continue;
+            const reasonCode = session.outcome.reasonCode ?? "not-recorded";
+            reasons.set(reasonCode, (reasons.get(reasonCode) ?? 0) + 1);
+        }
+        const { sessions: observations, ...context } = group;
+        return {
+            ...context,
+            distinctGoalCount: new Set(observations.map((session) => session.goal.fingerprint)).size,
+            sessionCounts: {
+                total: observations.length,
+                active: observations.length - terminal,
+                completed,
+                abandoned,
+                terminal,
+            },
+            terminalCompletionRate: terminal === 0 ? null : completed / terminal,
+            retrievalContextComplete: observations.every((session) => session.attempts.every((attempt) => attempt.measurementContextVersion === 2) &&
+                measurementContextComplete(session.attempts)),
+            statusEffort: SEARCH_JOURNEY_STATUSES.map((status) => {
+                const matching = observations.filter((session) => session.status === status);
+                const searches = matching.map((session) => session.attempts.length);
+                const totalSearches = searches.reduce((sum, count) => sum + count, 0);
+                const totalNavigationEvents = matching.reduce((sum, session) => sum + session.navigation.length, 0);
+                return {
+                    status,
+                    sessionCount: matching.length,
+                    sessionsWithSearches: searches.filter((count) => count > 0).length,
+                    totalSearches,
+                    failedSearches: matching.reduce((sum, session) => sum + session.attempts.filter((attempt) => attempt.status === "failed").length, 0),
+                    totalNavigationEvents,
+                    totalObservedHops: totalSearches + totalNavigationEvents,
+                    medianSearches: searches.length === 0 ? null : median(searches),
+                };
+            }),
+            abandonmentReasons: [...reasons.entries()]
+                .sort(([left], [right]) => compareCodepoints(left, right))
+                .map(([reasonCode, count]) => ({ reasonCode, count })),
+            caveats: [
+                "Outcome cohorts retain every observed search and navigation event, including failed searches, zero-search sessions and searches after an explicitly accepted earlier attempt; these are not completed-to-target metrics.",
+                "The completion-rate denominator is completed plus abandoned sessions in this cohort; active sessions are reported separately, and the rate describes recorded tasks rather than benchmark accuracy.",
+                "Unknown or incompatible retrieval/execution contexts remain separate, including retrieval-unavailable tasks with no known profile; inspect all cohorts before interpreting successful-task effort.",
+                "Task mix, sampling and declaration accuracy are not independently verified or normalized; there is no temporal trend, causal quality claim or ROI estimate.",
+            ],
+        };
+    });
+}
+/** Aggregiert ausschliesslich kompatible Messkontexte in getrennten Kohorten. */
+export function buildDynamicProductComplexityReport(workspaceId, sessions, generatedAt) {
+    const scoped = sessions.filter((session) => session.workspaceId === workspaceId);
+    const completed = scoped.filter((session) => session.status === "completed" && session.outcome?.kind === "completed");
+    const grouped = new Map();
+    for (const session of completed) {
+        if (session.outcome?.kind !== "completed")
+            continue;
+        const assessment = reportAssessment(session);
+        const cohort = grouped.get(assessment.measurementContextId) ?? {
+            assessments: [],
+            executionContext: executionContextEvidence(session),
+        };
+        cohort.assessments.push(assessment);
+        grouped.set(assessment.measurementContextId, cohort);
+    }
+    const cohorts = [...grouped.entries()]
+        .sort(([left], [right]) => compareCodepoints(left, right))
+        .map(([measurementContextId, cohort]) => buildCohort(measurementContextId, cohort.assessments, cohort.executionContext));
+    const featureGroups = new Map();
+    for (const session of completed) {
+        if (session.feature === undefined || session.outcome?.kind !== "completed")
+            continue;
+        const { target } = session.outcome;
+        const assessment = reportAssessment(session);
+        const key = canonicalJson([session.feature.fingerprint, assessment.measurementContextId]);
+        const group = featureGroups.get(key) ?? {
+            featureFingerprint: session.feature.fingerprint,
+            measurementContextId: assessment.measurementContextId,
+            observations: [],
+        };
+        group.observations.push({
+            goalFingerprint: session.goal.fingerprint,
+            target,
+            assessment,
+            executionContext: executionContextEvidence(session),
+        });
+        featureGroups.set(key, group);
+    }
+    const featureMappings = [...featureGroups.values()]
+        .sort((left, right) => compareCodepoints(left.featureFingerprint, right.featureFingerprint) ||
+        compareCodepoints(left.measurementContextId, right.measurementContextId))
+        .map((group) => buildFeatureMapping(group.featureFingerprint, group.measurementContextId, group.observations));
+    return {
+        schemaVersion: 1,
+        algorithm: DYNAMIC_SEARCH_COMPLEXITY_ALGORITHM_ID,
+        isHeuristic: true,
+        workspaceId,
+        generatedAt,
+        sessionCounts: {
+            total: scoped.length,
+            active: scoped.filter((session) => session.status === "active").length,
+            completed: completed.length,
+            featureTaggedCompleted: completed.filter((session) => session.feature !== undefined).length,
+            abandoned: scoped.filter((session) => session.status === "abandoned").length,
+        },
+        cohorts,
+        featureMappings,
+        outcomeCohorts: buildOutcomeCohorts(scoped),
+        caveats: [
+            "Completed-to-target cohort metrics exclude active and abandoned sessions; separate outcome cohorts expose all statuses, denominators and observed effort.",
+            "Incompatible ranker/profile/generation contexts are never merged.",
+            "Execution context is optional and caller-declared; absent context remains visibly uncontrolled and is never inferred from historical sessions. Equal declared conditions do not independently verify comparability or causation.",
+            "Task mix and sampling policy are not normalized in v1; each cohort describes the workload that was actually observed.",
+            "The report describes observed retrieval effort; it does not replace cognitive complexity and does not claim unlabeled precision.",
+            "Feature mappings include only journeys started with an explicit stable feature ID and keep search effort separate from static target-code complexity.",
+        ],
+    };
+}
+export class SearchJourneyService {
+    deps;
+    pendingMutations = new Map();
+    fingerprintKey;
+    constructor(deps) {
+        this.deps = deps;
+        assertBoundedNonEmpty(deps.workspaceId, "workspaceId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH);
+        if (deps.fingerprintKey !== undefined) {
+            this.fingerprintKey = this.validatedFingerprintKey(deps.fingerprintKey);
+        }
+    }
+    async start(input, options) {
+        options?.signal?.throwIfAborted();
+        const goal = assertBoundedNonEmpty(input.goal, "goal", MAX_SEARCH_JOURNEY_TEXT_LENGTH);
+        const featureId = input.featureId === undefined ? undefined : assertNonEmpty(input.featureId, "featureId");
+        if (featureId !== undefined && featureId.length > MAX_SEARCH_JOURNEY_FEATURE_ID_LENGTH) {
+            throw new Error(`featureId must contain at most ${String(MAX_SEARCH_JOURNEY_FEATURE_ID_LENGTH)} UTF-16 code units`);
+        }
+        const executionContext = normalizeExecutionContext(input.executionContext);
+        const fingerprintKey = await this.getFingerprintKey(options);
+        const now = this.deps.clock.nowIso();
+        const session = {
+            schemaVersion: 1,
+            revision: 0,
+            sessionId: this.deps.random.uuid(),
+            workspaceId: this.deps.workspaceId,
+            status: "active",
+            recordingConsent: "explicit",
+            retainText: input.retainText ?? false,
+            goal: {
+                fingerprint: journeyFingerprint(fingerprintKey, this.deps.workspaceId, "goal", goal),
+                ...(input.retainText === true ? { text: goal } : {}),
+            },
+            ...(featureId === undefined
+                ? {}
+                : {
+                    feature: {
+                        fingerprint: journeyFingerprint(fingerprintKey, this.deps.workspaceId, "feature", featureId),
+                        ...(input.retainText === true ? { text: featureId } : {}),
+                    },
+                }),
+            ...(executionContext === undefined
+                ? {}
+                : {
+                    executionContext: persistExecutionContext(executionContext, fingerprintKey, this.deps.workspaceId, input.retainText === true),
+                }),
+            createdAt: now,
+            updatedAt: now,
+            attempts: [],
+            navigation: [],
+        };
+        assertValidSessionState(session);
+        await this.deps.store.put(session, {
+            ...options,
+            expectedRevision: null,
+        });
+        return cloneSession(session);
+    }
+    async get(sessionId, options) {
+        const id = assertNonEmpty(sessionId, "sessionId");
+        const session = await this.deps.store.get(id, options);
+        if (session === null || session.workspaceId !== this.deps.workspaceId) {
+            throw new UntangleError("SEARCH_SESSION_NOT_FOUND", `search journey "${id}" was not found in this workspace`, { operation: "search_journey_get", context: { sessionId: id } });
+        }
+        return cloneSession(session);
+    }
+    async recordSearch(sessionId, result, link = {}, options) {
+        assertClientStep(link.step);
+        const queryText = assertBoundedNonEmpty(result.query.text, "query", MAX_SEARCH_JOURNEY_TEXT_LENGTH);
+        if (result.query.workspaceId !== this.deps.workspaceId) {
+            throw new Error(`search result belongs to workspace "${result.query.workspaceId}", not "${this.deps.workspaceId}"`);
+        }
+        const profileIds = result.groups.map((group) => group.embeddingProfileId);
+        if (new Set(profileIds).size !== profileIds.length) {
+            throw new UntangleError("SEARCH_SESSION_INVALID_STATE", "search result contains duplicate embedding-profile groups", { operation: "search_journey_record", context: { sessionId } });
+        }
+        const projection = projectSearchObservation(result, queryText);
+        const fingerprintKey = await this.getFingerprintKey(options);
+        const observationFingerprint = observationFingerprintOfProjection(fingerprintKey, this.deps.workspaceId, projection);
+        const legacyObservationFingerprint = observationFingerprintOfProjection(fingerprintKey, this.deps.workspaceId, projection, false);
+        return this.mutate(sessionId, (session) => {
+            assertConsistentStepMode(session.attempts, link.step, sessionId);
+            const existing = session.attempts.find((attempt) => link.step !== undefined && attempt.clientStep === link.step);
+            if (existing !== undefined) {
+                const legacyReplay = existing.profiles.every((profile) => profile.candidates.every((candidate) => candidate.complexity === undefined &&
+                    candidate.incompletePayloadFields === undefined)) && existing.observationFingerprint === legacyObservationFingerprint;
+                if (existing.observationFingerprint !== observationFingerprint && !legacyReplay) {
+                    throw new UntangleError("SEARCH_SESSION_CONFLICT", `search journey step ${String(link.step)} already records a different observation`, {
+                        operation: "search_journey_record",
+                        context: { sessionId, step: link.step },
+                    });
+                }
+                return { session, value: existing, changed: false };
+            }
+            if (session.attempts.length >= MAX_SEARCH_JOURNEY_ATTEMPTS) {
+                throw new UntangleError("SEARCH_SESSION_INVALID_STATE", `search journey reached its limit of ${String(MAX_SEARCH_JOURNEY_ATTEMPTS)} attempts`, { operation: "search_journey_record", context: { sessionId } });
+            }
+            const attempt = {
+                attemptId: this.deps.random.uuid(),
+                sequence: session.attempts.length + 1,
+                measurementContextVersion: 2,
+                // Aus dem Verdikt abgeleitet, nie aus einer leeren Kandidatenliste.
+                ...(projection.abstention === null ? {} : { abstention: projection.abstention }),
+                ...(link.step === undefined ? {} : { clientStep: link.step }),
+                observationFingerprint,
+                queryFingerprint: journeyQueryFingerprint(fingerprintKey, this.deps.workspaceId, queryText),
+                ...(session.retainText ? { queryText } : {}),
+                rankerVersion: projection.rankerVersion,
+                ...(projection.rankingContextFingerprint === null
+                    ? {}
+                    : { rankingContextFingerprint: projection.rankingContextFingerprint }),
+                resultLimit: projection.resultLimit,
+                candidateLimit: projection.candidateLimit,
+                observedAt: this.deps.clock.nowIso(),
+                status: "succeeded",
+                warningCodes: [...projection.warningCodes],
+                retrievalHealthy: projection.retrievalHealthy,
+                profiles: profilesOfProjection(projection),
+            };
+            session.attempts.push(attempt);
+            sortAttempts(session.attempts);
+            session.updatedAt = attempt.observedAt;
+            return { session, value: attempt };
+        }, options, { allowTerminalIdempotentReplay: link.step !== undefined }).then(({ session, value }) => ({ session, attempt: value }));
+    }
+    async recordFailedSearch(sessionId, input, link = {}, options) {
+        assertClientStep(link.step);
+        const query = assertBoundedNonEmpty(input.query, "query", MAX_SEARCH_JOURNEY_TEXT_LENGTH);
+        const failureCode = assertBoundedNonEmpty(input.failureCode, "failureCode", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH);
+        const failureReason = assertBoundedNonEmpty(input.failureReason, "failureReason", MAX_SEARCH_JOURNEY_REASON_LENGTH);
+        const fingerprintKey = await this.getFingerprintKey(options);
+        const observationFingerprint = journeyFingerprint(fingerprintKey, this.deps.workspaceId, "failed-observation", {
+            query,
+            failureCode,
+            failureReason,
+            rankerVersion: RANKER_VERSION,
+        });
+        return this.mutate(sessionId, (session) => {
+            assertConsistentStepMode(session.attempts, link.step, sessionId);
+            const existing = session.attempts.find((attempt) => link.step !== undefined && attempt.clientStep === link.step);
+            if (existing !== undefined) {
+                if (existing.observationFingerprint !== observationFingerprint) {
+                    throw new UntangleError("SEARCH_SESSION_CONFLICT", `search journey step ${String(link.step)} already records a different observation`, {
+                        operation: "search_journey_record_failure",
+                        context: { sessionId, step: link.step },
+                    });
+                }
+                return { session, value: existing, changed: false };
+            }
+            if (session.attempts.length >= MAX_SEARCH_JOURNEY_ATTEMPTS) {
+                throw new UntangleError("SEARCH_SESSION_INVALID_STATE", `search journey reached its limit of ${String(MAX_SEARCH_JOURNEY_ATTEMPTS)} attempts`, { operation: "search_journey_record", context: { sessionId } });
+            }
+            const observedAt = this.deps.clock.nowIso();
+            const attempt = {
+                attemptId: this.deps.random.uuid(),
+                sequence: session.attempts.length + 1,
+                measurementContextVersion: 2,
+                // Ein fehlgeschlagener Versuch hat kein Ergebnis und damit kein
+                // Verdikt. Hier `strict` einzutragen waere geraten, nicht beobachtet.
+                ...(link.step === undefined ? {} : { clientStep: link.step }),
+                observationFingerprint,
+                queryFingerprint: journeyQueryFingerprint(fingerprintKey, this.deps.workspaceId, query),
+                ...(session.retainText ? { queryText: query } : {}),
+                rankerVersion: RANKER_VERSION,
+                observedAt,
+                status: "failed",
+                failureCode,
+                ...(session.retainText ? { failureReason } : {}),
+                warningCodes: [],
+                retrievalHealthy: false,
+                profiles: [],
+            };
+            session.attempts.push(attempt);
+            sortAttempts(session.attempts);
+            session.updatedAt = observedAt;
+            return { session, value: attempt };
+        }, options, { allowTerminalIdempotentReplay: link.step !== undefined }).then(({ session, value }) => ({ session, attempt: value }));
+    }
+    async observeNavigation(sessionId, input, options) {
+        const target = input.target === undefined ? undefined : normalizedTarget(input.target);
+        const toolName = input.toolName === undefined
+            ? undefined
+            : assertBoundedNonEmpty(input.toolName, "toolName", MAX_SEARCH_JOURNEY_TOOL_NAME_LENGTH);
+        return this.mutate(sessionId, (session) => {
+            if (session.navigation.length >= MAX_SEARCH_JOURNEY_NAVIGATION_EVENTS) {
+                throw new UntangleError("SEARCH_SESSION_INVALID_STATE", `search journey reached its limit of ${String(MAX_SEARCH_JOURNEY_NAVIGATION_EVENTS)} navigation events`, { operation: "search_journey_observe", context: { sessionId } });
+            }
+            const observedAt = this.deps.clock.nowIso();
+            const event = {
+                eventId: this.deps.random.uuid(),
+                sequence: session.navigation.length + 1,
+                kind: input.kind,
+                observedAt,
+                ...(toolName === undefined ? {} : { toolName }),
+                ...(target === undefined ? {} : { target }),
+            };
+            session.navigation.push(event);
+            session.updatedAt = observedAt;
+            return { session, value: undefined };
+        }, options).then(({ session }) => session);
+    }
+    async complete(sessionId, input, options) {
+        const target = normalizedTarget(input.target);
+        const acceptedAttemptId = input.acceptedAttemptId === undefined
+            ? undefined
+            : assertBoundedNonEmpty(input.acceptedAttemptId, "acceptedAttemptId", MAX_SEARCH_JOURNEY_LOCATOR_LENGTH);
+        return this.mutate(sessionId, (session) => {
+            const completedAt = this.deps.clock.nowIso();
+            const assessment = assessSearchJourney(session, {
+                target,
+                ...(acceptedAttemptId === undefined ? {} : { acceptedAttemptId }),
+            });
+            session.status = "completed";
+            session.updatedAt = completedAt;
+            session.outcome = {
+                kind: "completed",
+                completedAt,
+                target,
+                ...(acceptedAttemptId === undefined ? {} : { acceptedAttemptId }),
+                assessment,
+            };
+            return { session, value: undefined };
+        }, options).then(({ session }) => session);
+    }
+    async abandon(sessionId, input = {}, options) {
+        const reason = input.reason === undefined
+            ? undefined
+            : assertBoundedNonEmpty(input.reason, "reason", MAX_SEARCH_JOURNEY_REASON_LENGTH);
+        return this.mutate(sessionId, (session) => {
+            const abandonedAt = this.deps.clock.nowIso();
+            session.status = "abandoned";
+            session.updatedAt = abandonedAt;
+            session.outcome = {
+                kind: "abandoned",
+                abandonedAt,
+                ...(input.reasonCode === undefined ? {} : { reasonCode: input.reasonCode }),
+                ...(session.retainText && reason !== undefined ? { reason } : {}),
+            };
+            return { session, value: undefined };
+        }, options).then(({ session }) => session);
+    }
+    async report(options) {
+        const sessions = await this.deps.store.list(this.deps.workspaceId, options);
+        return buildDynamicProductComplexityReport(this.deps.workspaceId, sessions, this.deps.clock.nowIso());
+    }
+    validatedFingerprintKey(key) {
+        if (key.byteLength < 32) {
+            throw new Error("search journey fingerprint key must contain at least 32 bytes");
+        }
+        return key.slice();
+    }
+    async getFingerprintKey(options) {
+        if (this.fingerprintKey !== undefined)
+            return this.fingerprintKey;
+        const provider = this.deps.fingerprintKeyProvider;
+        if (provider === undefined)
+            throw new Error("search journey fingerprint key is unavailable");
+        const loaded = this.validatedFingerprintKey(await provider(options));
+        this.fingerprintKey = loaded;
+        return loaded;
+    }
+    async mutate(sessionId, reducer, options, mutationOptions = {}) {
+        const id = assertNonEmpty(sessionId, "sessionId");
+        let resolved;
+        const previous = this.pendingMutations.get(id) ?? Promise.resolve();
+        // Ein fehlgeschlagener parallel vorausgehender Mutator darf die lokale
+        // Serialisierung nicht dauerhaft vergiften. Jeder Aufruf liest seinen
+        // eigenen frischen CAS-Stand und gibt seinen eigenen Fehler weiter.
+        const current = previous
+            .catch(() => undefined)
+            .then(async () => {
+            for (let attempt = 1; attempt <= 3; attempt++) {
+                options?.signal?.throwIfAborted();
+                const loaded = await this.deps.store.get(id, options);
+                if (loaded === null || loaded.workspaceId !== this.deps.workspaceId) {
+                    throw new UntangleError("SEARCH_SESSION_NOT_FOUND", `search journey "${id}" was not found in this workspace`, { operation: "search_journey_mutate", context: { sessionId: id } });
+                }
+                if (loaded.status !== "active" &&
+                    mutationOptions.allowTerminalIdempotentReplay !== true) {
+                    throw new UntangleError("SEARCH_SESSION_INVALID_STATE", `search journey "${id}" is ${loaded.status} and cannot be changed`, {
+                        operation: "search_journey_mutate",
+                        context: { sessionId: id, status: loaded.status },
+                    });
+                }
+                const next = reducer(cloneSession(loaded));
+                if (next.changed === false) {
+                    resolved = { session: cloneSession(loaded), value: next.value };
+                    return;
+                }
+                if (loaded.status !== "active") {
+                    throw new UntangleError("SEARCH_SESSION_INVALID_STATE", `search journey "${id}" is ${loaded.status} and cannot be changed`, {
+                        operation: "search_journey_mutate",
+                        context: { sessionId: id, status: loaded.status },
+                    });
+                }
+                next.session.revision = loaded.revision + 1;
+                assertValidSessionState(next.session);
+                try {
+                    await this.deps.store.put(next.session, {
+                        ...options,
+                        expectedRevision: loaded.revision,
+                    });
+                    resolved = { session: cloneSession(next.session), value: next.value };
+                    return;
+                }
+                catch (error) {
+                    if (!isUntangleError(error) ||
+                        error.code !== "SEARCH_SESSION_CONFLICT" ||
+                        attempt === 3) {
+                        throw error;
+                    }
+                }
+            }
+        });
+        this.pendingMutations.set(id, current);
+        try {
+            await current;
+            return resolved;
+        }
+        finally {
+            if (this.pendingMutations.get(id) === current)
+                this.pendingMutations.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=product-complexity.js.map