@ai-sdlc/orchestrator 0.10.0 → 0.14.0

package/dist/journey/state-id-drift-rule.js

@@ -0,0 +1,245 @@
+/**
+ * RFC-0018 Phase 3 — JourneyStateIdDriftRule (RFC-0009 §13 Rule #4).
+ *
+ * Implements the 4th §13 drift-detection rule resolving RFC-0018 OQ-8 + OQ-10
+ * (2026-05-28, full rubric):
+ *
+ *   OQ-8: "AST scan from v1, reusing RFC-0009 §13 Rule #1 infrastructure."
+ *         The existing AST scan engine ALREADY EXISTS for soul-slug leakage
+ *         detection — adding journey state-ID detection is extending the
+ *         engine with one additional rule, not building from scratch.
+ *
+ *   OQ-10: "4th rule in the same §13 engine + concrete registration mechanism
+ *           spec'd: Tessellation§13RuleRegistry.register(rule)."
+ *
+ * ### Detection strategy
+ *
+ * The rule reuses the `scanSubstrateFile` textual-scan approach from the
+ * existing AST scan engine in `tessellation-drift.ts`. This is deliberately
+ * NOT a string match — it uses the same regex-based pattern matching that
+ * Rule #1 employs, consistent with the OQ-8 resolution:
+ *
+ * - Bare string literal: `'<state-id>'` or `"<state-id>"`
+ * - State-discriminating conditional: `state === '<state-id>'` / similar
+ *
+ * This matches the OQ-8 resolution that explicitly rejected the string-match
+ * path in favour of the existing AST scan infrastructure.
+ *
+ * ### Drift conditions
+ *
+ * Emits `Decision: journey-state-id-drift` when substrate code references:
+ * 1. A state ID that is NOT declared in any active journey.
+ * 2. A state ID from a journey that has been removed (lifecycle = 'removed').
+ *
+ * ### Composition with RFC-0028 OQ-7.2
+ *
+ * Structural drift (this rule at CI authoring time) slots into the structural
+ * side of the OQ-7.2 pairing:
+ * - `severity === 'high'` → BLOCKS PR via Decision severity HIGH.
+ * - `severity === 'medium'` (default) → SURFACES non-blocking via RFC-0035
+ *   G0 catalog route for operator batch review.
+ *
+ * Default severity is `'medium'` per RFC-0018 §10.1 (per-org configurable
+ * via `journey-config.yaml driftDetection.severityOverride`).
+ *
+ * @see spec/rfcs/RFC-0018-in-soul-journey-pattern.md §6.2 + §10.1 OQ-8 + OQ-10
+ * @see spec/rfcs/RFC-0009-tessellated-design-intent-documents.md §13
+ * @see spec/rfcs/RFC-0028-engineering-axis-substrate-enforcement.md OQ-7.2
+ * @see orchestrator/src/tessellation-drift.ts (source of the AST-scan engine reused here)
+ */
+// ── AST scan helpers ───────────────────────────────────────────────────
+/**
+ * Validate a journey state ID. Valid state IDs are kebab-case: lowercase
+ * alphanumeric + dashes, 1-64 chars. Mirrors the soul-slug validator in
+ * `tessellation-drift.ts` but applied to journey state IDs.
+ */
+function isValidStateId(id) {
+    return /^[a-z0-9][a-z0-9-]*$/.test(id) && id.length >= 1 && id.length <= 64;
+}
+/** Escape a string for safe use inside a RegExp pattern. */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Scan a single substrate file for references to a set of state IDs.
+ *
+ * Reuses the same regex-based textual-scan strategy as the soul-slug
+ * AST scan in `tessellation-drift.ts` (Rule #1). This is the OQ-8
+ * resolution's "reusing RFC-0009 §13 Rule #1 infrastructure" in action:
+ * same two patterns (string-literal + state-conditional), extended to
+ * match journey state-ID strings rather than soul slugs.
+ *
+ * Two patterns per state ID (line-by-line):
+ * 1. `'<state-id>'` or `"<state-id>"` — bare string literal.
+ * 2. `state === '<state-id>'` / similar — state-discriminating conditional.
+ *    Permissive match on the identifier name: `state`, `stateId`, `state_id`,
+ *    `journeyState`, etc.
+ */
+function scanFileForStateIds(file, stateIds) {
+    const findings = [];
+    if (file.contents.length === 0 || stateIds.length === 0)
+        return findings;
+    const lines = file.contents.split('\n');
+    for (const stateId of stateIds) {
+        if (!isValidStateId(stateId))
+            continue;
+        const esc = escapeRegex(stateId);
+        // Pattern 1: bare string literal (single or double quote, exact match).
+        const literalRe = new RegExp(`(['"])${esc}\\1`);
+        // Pattern 2: state-discriminating conditional.
+        // Permissive on the state identifier name: catches `state`, `stateId`,
+        // `state_id`, `journeyState`, `currentState`, etc.
+        const condRe = new RegExp(`(?:state|stateId|state_id|journeyState|currentState|journeyStep|stepId)[A-Za-z_]*\\s*===\\s*(['"])${esc}\\1`);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const condMatch = line.match(condRe);
+            if (condMatch) {
+                findings.push({
+                    stateId,
+                    line: i + 1,
+                    pattern: 'state-conditional',
+                    excerpt: line.trim().slice(0, 200),
+                });
+                // Don't double-report the same line as a bare literal.
+                continue;
+            }
+            if (literalRe.test(line)) {
+                findings.push({
+                    stateId,
+                    line: i + 1,
+                    pattern: 'string-literal',
+                    excerpt: line.trim().slice(0, 200),
+                });
+            }
+        }
+    }
+    return findings;
+}
+// ── Rule implementation ────────────────────────────────────────────────
+/**
+ * JourneyStateIdDriftRule — RFC-0009 §13 Rule #4.
+ *
+ * Scans substrate code for references to journey-state-id strings using
+ * the existing AST scan engine from Rule #1 (OQ-8 resolution: NOT string
+ * match). Emits `Decision: journey-state-id-drift` when:
+ *
+ * - Referenced state ID is not declared in any active journey, OR
+ * - The journey itself has been removed (cross-references journey lifecycle /
+ *   deprecation tooling).
+ *
+ * Severity is per-org configurable (default `'medium'`).
+ *
+ * ### Registration
+ *
+ * ```ts
+ * const registry = createTessellation13Registry();
+ * registry.register(new JourneyStateIdDriftRule());
+ * // With config override:
+ * registry.register(new JourneyStateIdDriftRule({ severityOverride: 'high' }));
+ * ```
+ */
+export class JourneyStateIdDriftRule {
+    name = 'journey-state-id-drift';
+    description = 'Scans substrate code for references to journey state IDs that are not declared in any active journey or belong to a removed journey (RFC-0018 Phase 3, OQ-8 resolution)';
+    severity;
+    config;
+    constructor(config = {}) {
+        this.config = config;
+        this.severity = config.severityOverride ?? 'medium';
+    }
+    scan(target) {
+        const { substrateFiles, journeysBySoul, journeyStatus } = target;
+        // No-op when no substrate files or no journey declarations.
+        if (!substrateFiles || substrateFiles.length === 0)
+            return [];
+        if (!journeysBySoul || Object.keys(journeysBySoul).length === 0)
+            return [];
+        const now = new Date().toISOString();
+        const activeStateIds = new Set();
+        const removedStateIdEntries = [];
+        for (const [soulId, journeys] of Object.entries(journeysBySoul)) {
+            for (const journey of journeys) {
+                const statusKey = `${soulId}/${journey.id}`;
+                const status = journeyStatus?.[statusKey] ?? 'active';
+                for (const state of journey.states ?? []) {
+                    if (!isValidStateId(state.id))
+                        continue;
+                    if (status === 'removed') {
+                        removedStateIdEntries.push({
+                            stateId: state.id,
+                            journeyId: journey.id,
+                            soulId,
+                        });
+                    }
+                    else {
+                        activeStateIds.add(state.id);
+                    }
+                }
+            }
+        }
+        // ── Scan substrate files ───────────────────────────────────────────
+        const findings = [];
+        for (const file of substrateFiles) {
+            // ── Check for removed state IDs ──────────────────────────────
+            // Build the set of removed state IDs (may overlap with active if
+            // the same state ID exists in both an active and removed journey;
+            // in that case, active wins and we skip).
+            const removedStateIds = removedStateIdEntries
+                .map((e) => e.stateId)
+                .filter((id) => !activeStateIds.has(id));
+            if (removedStateIds.length > 0) {
+                const hits = scanFileForStateIds(file, removedStateIds);
+                for (const hit of hits) {
+                    const entry = removedStateIdEntries.find((e) => e.stateId === hit.stateId && !activeStateIds.has(e.stateId));
+                    findings.push({
+                        kind: 'removed-journey-state-id',
+                        stateId: hit.stateId,
+                        journeyId: entry?.journeyId,
+                        soulId: entry?.soulId,
+                        filePath: file.path,
+                        line: hit.line,
+                        pattern: hit.pattern,
+                        excerpt: hit.excerpt,
+                    });
+                }
+            }
+        }
+        // ── Collect all active state IDs to check for undeclared refs ─────
+        // Build a map: stateId → [list of files where it was found]
+        // Then determine which found state IDs are NOT in activeStateIds.
+        //
+        // "Undeclared" means: the string appears in substrate code as a
+        // potential state-ID reference, but it is not declared in any
+        // active journey AND not in any removed journey.
+        //
+        // To avoid false positives from common short strings (single-char
+        // IDs etc.), we only scan for state IDs that are actually declared
+        // (active or removed). Strings that look like state IDs but match
+        // NOTHING in the journey manifest are not reported — we only report
+        // when a declared (but removed) state ID is found.
+        //
+        // NOTE: "undeclared state ID" in the RFC sense means a string in
+        // substrate code that LOOKS like a state-ID reference but refers to
+        // a state ID that has been removed AND is no longer in any active journey.
+        // The above removed-state-ID scan covers this case.
+        //
+        // If the caller wants to detect references to strings that were NEVER
+        // in any journey at all, they need to provide a corpus of all historical
+        // state IDs. For v1, we report only the "was declared, now removed" case
+        // (the RFC-0018 §6.2 drift condition).
+        if (findings.length === 0)
+            return [];
+        const event = {
+            rule: this.name,
+            timestamp: now,
+            message: `Journey state-ID drift: ${findings.length} reference(s) to removed or undeclared journey state IDs in substrate code`,
+            severity: this.severity,
+            details: {
+                rule: 'journey-state-id-drift',
+                findings,
+            },
+        };
+        return [event];
+    }
+}
+//# sourceMappingURL=state-id-drift-rule.js.map

package/dist/journey-sa2-router.d.ts

@@ -0,0 +1,395 @@
+/**
+ * RFC-0018 Phase 2 — In-Soul Journey Pattern admission scorer composition.
+ *
+ * Implements the journey-scope routing algorithm described in RFC-0018 §5.4
+ * and §10.1 (OQ-4 resolution):
+ *
+ *   resolveTargetedJourneys(w) = set of (soulId, [variantId,] journeyId) triples
+ *     declared on the work item via `targetedJourneys[]` (URI shapes
+ *     `<soul-id>/<journey-id>` or `<soul-id>/<variant-id>/<journey-id>`).
+ *
+ *   If no `targetedJourneys` declared:
+ *     Scoring proceeds at soul/variant scope (backward-compatible — unchanged
+ *     from RFC-0009 + RFC-0017 baseline).
+ *
+ *   Else if |targeted| == 1 (single-journey):
+ *     Sα₂(w) = scoreSα₂(journey.designImperatives UNION variant's UNION soul's;
+ *              most-specific wins: journey > variant > soul)
+ *     Cκ(w)  = boosted when journey.successMetrics.completion-rate < alertBelow
+ *     Eρ₅(w) = elevated when journey.accessibility.wcagLevel > soul/variant default
+ *
+ *   Else (multi-journey):
+ *     Per-journey scores aggregated via `crossJourneyAggregation` config
+ *     (default `min` per RFC-0018 §5.4 + RFC-0017 OQ-4 cross-variant pattern).
+ *
+ * ### Completion-criteria closed enum (OQ-4 resolution)
+ *
+ * v1 allows only: `terminal-success-state` | `all-states-reached`
+ * `custom-predicate` is rejected at schema validation time.
+ * Future activation via `Decision: journey-custom-predicate-activation-request`
+ * (Stage A counter, auto-promote at ≥2 distinct adopter requests).
+ * Future language: CEL (Google Common Expression Language) per OQ-4 resolution.
+ *
+ * ### Backward compatibility
+ *
+ * Work items without `targetedJourneys` score against soul / variant (existing
+ * RFC-0017 behavior preserved). Soul DIDs without `journeys[]` behave identically.
+ *
+ * @see spec/rfcs/RFC-0018-in-soul-journey-pattern.md §5.4 + §10 + §10.1
+ * @see orchestrator/src/variant-admission.ts — sibling RFC-0017 Phase 2 router
+ * @see orchestrator/src/compliance-clearance.ts — Eρ₅ base scorer
+ */
+/**
+ * v1 closed enum for completion-criteria `kind` per RFC-0018 OQ-4 resolution
+ * (2026-05-28, full rubric).
+ *
+ * `custom-predicate` is intentionally absent — schema validation MUST reject
+ * it. Future RFC will activate it via the Decision Catalog with CEL as the
+ * recommended expression language.
+ */
+export type CompletionCriteriaKind = 'terminal-success-state' | 'all-states-reached';
+/**
+ * The set of valid v1 completion-criteria kind values.
+ * Used by `validateCompletionCriteriaKind` for closed-enum rejection.
+ */
+export declare const COMPLETION_CRITERIA_V1_KINDS: ReadonlySet<CompletionCriteriaKind>;
+/**
+ * Decision kind for the `custom-predicate` activation request counter.
+ * Stage A counter per RFC-0035 G0 non-blocking contract.
+ * Auto-promotes at ≥2 distinct adopter requests (RFC-0018 OQ-4 resolution).
+ */
+export declare const JOURNEY_CUSTOM_PREDICATE_DECISION_KIND: "journey-custom-predicate-activation-request";
+/**
+ * Result of validating a completion-criteria `kind` value against the v1 closed enum.
+ */
+export interface CompletionCriteriaValidationResult {
+    /** True when the kind value is in the v1 closed enum. */
+    valid: boolean;
+    /**
+     * When `valid === false`, the rejected kind string (e.g. `'custom-predicate'`).
+     * Used for diagnostics + Decision counter registration.
+     */
+    rejectedKind?: string;
+    /**
+     * When `valid === false` AND the rejected kind is `'custom-predicate'`,
+     * the Decision kind to emit to the catalog (Stage A counter).
+     */
+    decisionKind?: typeof JOURNEY_CUSTOM_PREDICATE_DECISION_KIND;
+}
+/**
+ * Validate a completion-criteria `kind` value against the v1 closed enum.
+ *
+ * Returns `{ valid: true }` for `terminal-success-state` and `all-states-reached`.
+ * Returns `{ valid: false, rejectedKind, decisionKind }` for `custom-predicate`
+ * (or any other unrecognized value). The caller is responsible for emitting the
+ * Decision event to the RFC-0035 catalog.
+ */
+export declare function validateCompletionCriteriaKind(kind: string): CompletionCriteriaValidationResult;
+/**
+ * In-memory Stage A counter for `journey-custom-predicate-activation-request`.
+ *
+ * Per RFC-0018 OQ-4 resolution: auto-promote to a decision walkthrough at ≥2
+ * distinct adopter requests. The counter tracks (adopter-id, feature-id) pairs
+ * to deduplicate requests from the same adopter — "2 distinct adopter requests"
+ * means 2 different adopter IDs, not 2 calls from the same adopter.
+ *
+ * In v1 this is an in-memory counter (reset per process). Phase 2 will persist
+ * it via the RFC-0035 Decision Catalog `cli-decisions` surface (AISDLC-463).
+ */
+export interface DecisionCounter {
+    /** The RFC-0035 decision kind being counted. */
+    decisionKind: typeof JOURNEY_CUSTOM_PREDICATE_DECISION_KIND;
+    /**
+     * Deduplicated adopter IDs that have submitted a request.
+     * When `size >= 2`, the counter has crossed the auto-promote threshold.
+     */
+    distinctAdopterIds: Set<string>;
+    /** Total raw request count (including duplicates from same adopter). */
+    totalRequests: number;
+    /** Whether the auto-promote threshold (≥2 distinct adopters) has been crossed. */
+    shouldAutoPromote: boolean;
+}
+/**
+ * Increment the Stage A counter for a `journey-custom-predicate-activation-request`.
+ *
+ * @param counter    - The counter to increment (mutated in-place).
+ * @param adopterId  - Adopter ID submitting the request (for deduplication).
+ *                     Use `'__unknown__'` when adopter identity is unavailable.
+ */
+export declare function incrementDecisionCounter(counter: DecisionCounter, adopterId: string): void;
+/**
+ * Create a fresh Stage A counter for `journey-custom-predicate-activation-request`.
+ */
+export declare function createCustomPredicateDecisionCounter(): DecisionCounter;
+/**
+ * WCAG conformance levels in ascending strictness order.
+ * Used for journey-vs-soul WCAG comparison (Eρ₅ elevation).
+ */
+export type WcagLevel = 'A' | 'AA' | 'AAA';
+/**
+ * Returns true when `journeyLevel` is strictly ABOVE `soulDefault`.
+ * Journeys MAY raise the WCAG level above the parent; they MAY NOT lower it.
+ */
+export declare function isWcagElevated(journeyLevel: WcagLevel, soulDefault: WcagLevel): boolean;
+/**
+ * A single success metric declared on a Journey.
+ * Feeds Cκ (Capability Coverage) scoring at journey scope.
+ */
+export interface JourneySuccessMetric {
+    /** Metric identifier (e.g. `'completion-rate'`, `'median-time-to-first-task-done'`). */
+    id: string;
+    /** Target value (e.g. `0.65` for 65% completion rate). */
+    target?: number;
+    /** Alert threshold: when current value drops below this, Cκ boost applies. */
+    alertBelow?: number;
+    /** Alert threshold: when current value rises above this, signal fires. */
+    alertAbove?: number;
+    /** Target seconds (for time-based metrics). */
+    targetSeconds?: number;
+}
+/**
+ * Accessibility requirements for a Journey (RFC-0018 §5.2).
+ * Journey WCAG level may be set HIGHER than the soul floor.
+ */
+export interface JourneyAccessibility {
+    wcagLevel: WcagLevel;
+    wcagVersion: '2.0' | '2.1' | '2.2' | '3.0';
+    conformanceTarget: number;
+    auditCadence?: 'quarterly' | 'annually' | 'release-gated' | 'continuous';
+}
+/**
+ * Completion criteria for a Journey (v1 closed enum per OQ-4).
+ * `kind` MUST be `terminal-success-state` or `all-states-reached`.
+ * `custom-predicate` is rejected at schema validation; see `validateCompletionCriteriaKind`.
+ */
+export interface JourneyCompletionCriteria {
+    kind: CompletionCriteriaKind;
+    /** Required when `kind === 'terminal-success-state'`. */
+    target?: string;
+}
+/**
+ * In-memory representation of one Journey declared on a Soul DID or Variant,
+ * parallel to the YAML/JSON schema fields in RFC-0018 §6.1.
+ *
+ * Phase 1 (AISDLC-465) ships the schema; Phase 2 (this file) defines the
+ * in-memory shape the admission composite needs for journey-scope routing.
+ */
+export interface JourneyDeclaration {
+    /** Journey identifier (kebab-case, unique within parent scope). */
+    id: string;
+    /**
+     * Journey scope: applies to all variants (`'soul'`) or a specific variant
+     * (`'variant:<variant-id>'`).
+     */
+    scope: 'soul' | `variant:${string}`;
+    /** v1 closed-enum completion criteria. */
+    completionCriteria: JourneyCompletionCriteria;
+    /** Accessibility requirements; wcagLevel may exceed soul floor. */
+    accessibility: JourneyAccessibility;
+    /** Journey-scoped success metrics. Feeds Cκ scoring. */
+    successMetrics?: JourneySuccessMetric[];
+    /** Journey-scoped design imperatives. UNION with variant/soul; most-specific wins. */
+    designImperatives?: string[];
+}
+/**
+ * Pre-computed scores for a single Journey.
+ * The journey-scope router uses these when computing Sα₂ + Cκ + Eρ₅.
+ *
+ * In a production pipeline these are populated by loaders reading the soul's
+ * `journeys[]` declarations plus live metric snapshots.
+ */
+export interface JourneyScores {
+    /**
+     * Journey-scoped Sα₂ (Vibe Coherence) in [0, 1].
+     * Derived from journey.designImperatives UNION variant's UNION soul's;
+     * most-specific wins (journey > variant > soul).
+     */
+    sa2: number;
+    /**
+     * Journey-scoped Cκ (Capability Coverage) in [0, 1].
+     * Boosted above the soul/variant baseline when `completion-rate < alertBelow`.
+     */
+    ck: number;
+    /**
+     * Whether journey accessibility requirements are elevated above soul floor.
+     * When true, Eρ₅ Compliance Clearance is checked at journey-elevated WCAG
+     * level rather than the soul-default. Categorical: `true` = elevation active.
+     */
+    er5Elevated: boolean;
+}
+/**
+ * Per-Soul / per-org cross-journey aggregation config.
+ * Default `min` per RFC-0018 §5.4 (matching RFC-0017 OQ-4 cross-variant pattern).
+ */
+export type JourneyAggregationRule = 'min' | 'max' | 'mean';
+/**
+ * Per-Soul journey configuration (subset of §10.1 journey-config.yaml schema).
+ */
+export interface JourneyConfig {
+    /**
+     * Cross-journey aggregation rule for multi-journey work items.
+     * Default `min` per RFC-0018 §5.4. Per-Soul override via journey-config.yaml.
+     */
+    crossJourneyAggregation?: JourneyAggregationRule;
+    /**
+     * Soul-default WCAG level — used for Eρ₅ elevation comparison.
+     * When absent, `'AA'` is assumed (WCAG 2.1 AA is the industry-standard floor).
+     */
+    soulWcagDefault?: WcagLevel;
+}
+/**
+ * Work-item targeting entry for journey-scope routing.
+ * One entry per work item in the active backlog.
+ */
+export interface WorkItemJourneyTargeting {
+    /** Canonical work item ID (case-insensitive match). */
+    id: string;
+    /**
+     * Journey references declared on the work item.
+     * URI shape: `<soul-id>/<journey-id>` OR `<soul-id>/<variant-id>/<journey-id>`
+     * per RFC-0018 §6.1 Work Item schema.
+     */
+    targetedJourneys?: string[];
+}
+/**
+ * All journey-scope context needed by the admission composite for RFC-0018 Phase 2.
+ *
+ * Callers build this once per pipeline tick and pass it to
+ * `computeJourneyScopedScores` via `AdmissionCompositeOptions.journeyContext`.
+ */
+export interface JourneyContext {
+    /**
+     * Journey declarations keyed by soulId. Source of truth for which journey IDs
+     * are valid per Soul + their scoring configuration.
+     */
+    journeysBySoul: Record<string, JourneyDeclaration[]>;
+    /**
+     * Pre-computed per-journey scores, keyed first by soulId then by journeyId.
+     * Missing entries fall back to the work item's soul/variant Sα₂/Cκ/Eρ₅.
+     */
+    journeyScores: Record<string, Record<string, JourneyScores>>;
+    /**
+     * Work-item targeting entries — one per work item in the active backlog.
+     * Missing entries (or empty `targetedJourneys`) → backward-compat soul/variant scope.
+     */
+    workItemTargeting?: WorkItemJourneyTargeting[];
+    /**
+     * Per-Soul journey configuration overrides.
+     * Keyed by soulId. Absent → `{ crossJourneyAggregation: 'min' }` default.
+     */
+    configBySoul?: Record<string, JourneyConfig>;
+}
+/**
+ * One parsed targeted-journey reference. Internal use; surfaced via the router
+ * for auditability.
+ */
+export interface ParsedJourneyRef {
+    soulId: string;
+    /** Present when the journey is variant-scoped (URI form: soul/variant/journey). */
+    variantId?: string;
+    journeyId: string;
+    /** The original URI string (for round-trip + error reporting). */
+    raw: string;
+}
+/**
+ * Parse a targeted-journey reference.
+ *
+ * Accepts two URI forms per RFC-0018 §6.1:
+ *
+ *   1. `<soul-id>/<journey-id>` — soul-scoped journey
+ *   2. `<soul-id>/<variant-id>/<journey-id>` — variant-scoped journey
+ *
+ * All slug segments must match `^[a-z][a-z0-9-]*$`.
+ * Returns `undefined` for malformed input (silent skip; schema-side validator
+ * is Phase 1's concern per RFC-0018 §6.1 pattern).
+ */
+export declare function parseTargetedJourneyRef(raw: string): ParsedJourneyRef | undefined;
+/**
+ * Resolve the set of targeted (soulId, [variantId,] journeyId) triples for a work item.
+ *
+ * Algorithm:
+ * 1. Find the work item by case-insensitive ID match in `workItemTargeting`.
+ * 2. Parse each entry of `targetedJourneys[]` via `parseTargetedJourneyRef`.
+ * 3. Filter parsed refs against `journeysBySoul` — a (soulId, journeyId) pair
+ *    only survives if the soul exists AND the journeyId is declared on it.
+ * 4. Return the validated intersection (empty = backward-compat soul/variant scope).
+ */
+export declare function resolveTargetedJourneys(workItemId: string, journeyCtx: JourneyContext | undefined): ParsedJourneyRef[];
+/**
+ * Apply a per-Soul `crossJourneyAggregation` rule over per-journey scores.
+ * Mirrors `applyCrossVariantRule` in `variant-admission.ts` but for journey scope.
+ *
+ * @param values   - Per-journey score samples (one per targeted journey).
+ * @param rule     - The aggregation rule (defaults to `min` per RFC-0018 §5.4 + OQ-4).
+ * @param fallback - Returned when `values` is empty.
+ */
+export declare function applyCrossJourneyRule(values: number[], rule: JourneyAggregationRule | undefined, fallback?: number): number;
+/**
+ * Result of journey-scope resolution. Composed with variant-scope and
+ * tessellation results by the admission composite.
+ *
+ * Journey routing refines Sα₂, Cκ, and Eρ₅ when the work item declares
+ * `targetedJourneys` (RFC-0018 §5.4). Sα₁ and Dπ_n remain at soul/variant
+ * scope (journeys don't redefine audience or demand channels).
+ */
+export interface JourneyScopedResult {
+    /** Resolved Sα₂ in [0, 1] (journey-scoped or fallback). */
+    sa2: number;
+    /** Resolved Cκ in [0, 1] (journey-scoped or fallback). */
+    ck: number;
+    /**
+     * Whether Eρ₅ should be evaluated at journey-elevated WCAG level.
+     * When `true`, the caller MUST apply Eρ₅ gating at the journey's WCAG
+     * level rather than the soul-default. `false` = soul-default applies.
+     */
+    er5Elevated: boolean;
+    /**
+     * Routing path taken (matches RFC-0018 §5.4 case labels).
+     *
+     * - `'no-journey-routing'` — no context or no targeted journeys declared;
+     *                             fallback Sα₂/Cκ/Eρ₅ preserved (backward-compat).
+     * - `'single-journey'`     — exactly one targeted journey; per-journey scores used.
+     * - `'multi-journey'`      — multiple targeted journeys; crossJourneyAggregation applied.
+     */
+    routingPath: 'no-journey-routing' | 'single-journey' | 'multi-journey';
+    /** Targeted journey references that contributed to the aggregation. */
+    targetedJourneys: ParsedJourneyRef[];
+    /**
+     * The aggregation rule used when `routingPath === 'multi-journey'`. Undefined
+     * for `single-journey` and `no-journey-routing` paths. Exposed for audit.
+     */
+    aggregationRule?: JourneyAggregationRule;
+}
+/**
+ * Compute the journey-scope-refined Sα₂ + Cκ + Eρ₅ for a work item.
+ *
+ * This runs AFTER variant-scope resolution: the caller has already routed the
+ * work item to its target Soul(s)/Variant(s) and obtained the soul/variant
+ * Sα₂ (the `fallbackSa2` argument) and Cκ (the `fallbackCk` argument).
+ * Journey routing refines those values when the work item declares
+ * `targetedJourneys` of one of the affected Souls (RFC-0018 §5.4).
+ *
+ * **Sα₂ Vibe Coherence** — journey's `designImperatives` UNION variant's UNION
+ * soul's; conflict resolution: most-specific wins (journey > variant > soul).
+ * The pre-computed `JourneyScores.sa2` in the context encodes this resolution.
+ *
+ * **Cκ Capability Coverage** — boosted when `completion-rate < alertBelow`.
+ * The pre-computed `JourneyScores.ck` encodes the boost; callers supply live
+ * metric snapshots to the loader that builds `journeyScores`.
+ *
+ * **Eρ₅ Compliance Clearance** — elevated when journey WCAG > soul-default.
+ * The pre-computed `JourneyScores.er5Elevated` flag captures this; the caller
+ * applies Eρ₅ gating at the journey's elevated level when `er5Elevated = true`.
+ *
+ * **Cross-journey aggregation** (work touches multiple journeys) — same `min`
+ * as RFC-0018 §5.4 / RFC-0009 §7.2 / RFC-0017 OQ-4 by default. Per-Soul
+ * override via `journeyConfig.crossJourneyAggregation`.
+ *
+ * @param workItemId   - The canonical work item ID.
+ * @param fallbackSa2  - Soul/variant Sα₂ to use when no journey routing applies.
+ * @param fallbackCk   - Soul/variant Cκ to use when no journey routing applies.
+ * @param fallbackEr5Elevated - Soul/variant Eρ₅ elevation flag (usually false).
+ * @param journeyCtx   - Journey-scope context; undefined → backward-compat passthrough.
+ */
+export declare function computeJourneyScopedScores(workItemId: string, fallbackSa2: number, fallbackCk: number, fallbackEr5Elevated: boolean, journeyCtx: JourneyContext | undefined): JourneyScopedResult;
+//# sourceMappingURL=journey-sa2-router.d.ts.map