@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/variant/internal-adopter/products.js

@@ -0,0 +1,366 @@
+/**
+ * RFC-0017 Phase 4 — InternalAdopter three-product reference implementation
+ * (AISDLC-437).
+ *
+ * Ships ProductA / ProductB / ProductC as canonical fixtures that demonstrate
+ * the In-Soul Variant Pattern against real-world adopter constraints. Each
+ * product is a distinct Soul on shared substrate; each declares three variants
+ * with audience-segment / form-factor / role-based specialization.
+ *
+ * **ProductD is INTENTIONALLY OMITTED** — per RFC-0017 §11 v0.4 (2026-05-26
+ * Design Authority editorial pass), ProductD's proposed variants
+ * (`annual-test`, `repair-event`, `regulatory-audit-mode`) are temporal-context-
+ * bound operational modes activated by *when* and *why* a user is in the
+ * system. Same user, different operational moment = Journey shape (RFC-0018),
+ * not Variant shape. ProductD's validation is deferred to RFC-0018 §11 as a
+ * Variant/Journey boundary validation case for the companion RFC.
+ *
+ * Variant constraints validated by `products.test.ts`:
+ *   - Every variant has ≤ 5 `designImperatives` strings (closed-enum discipline)
+ *   - Every variant's `designOverrides` uses only framework-owned enum fields
+ *     (`colorPaletteOverlay`, `densityProfile`, `typographyScale`,
+ *     `motionProfile`, `radiusProfile` per §6.1 OQ-5 2026-05-26 revisit)
+ *   - All variants of a given product share the same compliance + substrate
+ *     (substrate-shared check, AC #7)
+ *   - All variants pass `validateVariantDeclarations()` (no inheritance
+ *     violations, no nested variants, under the soft-warn / hard-limit caps)
+ *
+ * @see spec/rfcs/RFC-0017-in-soul-variant-pattern.md §11 (practitioner validation)
+ * @see ./products.test.ts — substrate-shared + closed-enum + inheritance checks
+ * @see ./admission-spotcheck.test.ts — variant-routed vs soul-aggregate scoring
+ * @see ./deprecation-lifecycle.test.ts — end-to-end lifecycle on ProductA variant
+ */
+/**
+ * Canonical shared substrate for the InternalAdopter product suite.
+ * Every ProductA/B/C variant inherits this identical block — substrate
+ * sharing is enforced at the fixture level (AC #7).
+ */
+export const INTERNAL_ADOPTER_SUBSTRATE = {
+    complianceRegimes: ['WCAG-2.1-AA'],
+    substrateInvariants: {
+        eventBus: 'internal-adopter-kafka-v1',
+        schemaRegistry: 'internal-adopter-schema-registry-v1',
+        tenantModel: 'multi-tenant-row-isolation',
+    },
+    performanceBudgets: {
+        initialLoadMs: 2500,
+        interactionResponseMs: 100,
+    },
+    observabilityRequirements: ['otel-traces', 'structured-logs', 'rum-vitals'],
+};
+// ── ProductA — small-utility / enterprise / county-regional ──────────────────
+//
+// Validates audience-segment specialization across the v0.4 visual-token
+// surface. The three variants serve dramatically different audience sizes
+// + cognitive-load profiles on a shared substrate.
+const PRODUCT_A = {
+    soulId: 'product-a',
+    description: 'Utility-operations management for water + electricity service providers. ' +
+        'Validates audience-segment specialization (small ↔ enterprise ↔ county).',
+    validationAxis: 'audience-segment specialization (RFC-0017 §11)',
+    substrate: INTERNAL_ADOPTER_SUBSTRATE,
+    soulDesignImperatives: ['compliance-first-information-architecture', 'audit-trail-visibility'],
+    variants: [
+        {
+            id: 'small-utility',
+            audienceCharacteristics: {
+                segments: ['municipal-small', 'water-district-small'],
+                sizeRange: { minStaff: 1, maxStaff: 50 },
+            },
+            designOverrides: {
+                colorPaletteOverlay: 'small-utility-warm',
+                densityProfile: 'comfortable',
+                typographyScale: 'large-print',
+                motionProfile: 'reduced',
+                radiusProfile: 'rounded',
+            },
+            designImperatives: [
+                'low-tech-fluency-tolerance',
+                'single-task-focus-per-screen',
+                'forgiving-error-recovery',
+                'minimal-jargon',
+            ],
+        },
+        {
+            id: 'enterprise',
+            audienceCharacteristics: {
+                segments: ['municipal-large', 'regional-utility'],
+                sizeRange: { minStaff: 51, maxStaff: 5000 },
+            },
+            designOverrides: {
+                colorPaletteOverlay: 'enterprise-cool',
+                densityProfile: 'compact',
+                typographyScale: 'default',
+                motionProfile: 'full',
+                radiusProfile: 'default',
+            },
+            designImperatives: [
+                'bulk-operation-efficiency',
+                'multi-tab-workflow-tolerance',
+                'keyboard-first-power-user-shortcuts',
+                'dashboard-density-tolerance',
+            ],
+        },
+        {
+            id: 'county-regional',
+            audienceCharacteristics: {
+                segments: ['county-government', 'regional-coordinator'],
+                sizeRange: { minStaff: 20, maxStaff: 200 },
+            },
+            designOverrides: {
+                colorPaletteOverlay: 'county-civic',
+                densityProfile: 'comfortable',
+                typographyScale: 'default',
+                motionProfile: 'reduced',
+                radiusProfile: 'sharp',
+            },
+            designImperatives: [
+                'cross-jurisdiction-reconciliation-clarity',
+                'inter-agency-handoff-explicit',
+                'official-record-defensibility',
+            ],
+        },
+    ],
+};
+// ── ProductB — field-tech-on-truck / field-tech-handheld / supervisor-tablet ─
+//
+// Validates density profile + form-factor specialization. Same role (field
+// operations) at different form-factors / contexts of use — density profile
+// + motion + radius differ sharply across the three.
+const PRODUCT_B = {
+    soulId: 'product-b',
+    description: 'Field-operations dispatch + workflow execution for utility field crews. ' +
+        'Validates density profile + form-factor specialization.',
+    validationAxis: 'density profile + form-factor specialization (RFC-0017 §11)',
+    substrate: INTERNAL_ADOPTER_SUBSTRATE,
+    soulDesignImperatives: ['offline-first-resilience', 'one-handed-operation-where-possible'],
+    variants: [
+        {
+            id: 'field-tech-on-truck',
+            audienceCharacteristics: {
+                segments: ['field-crew-mounted', 'service-truck-operator'],
+                sizeRange: { minStaff: 1, maxStaff: 4 },
+            },
+            designOverrides: {
+                colorPaletteOverlay: 'high-contrast-outdoor',
+                densityProfile: 'spacious',
+                typographyScale: 'large-print',
+                motionProfile: 'reduced',
+                radiusProfile: 'rounded',
+            },
+            designImperatives: [
+                'glanceable-from-driving-position',
+                'glove-friendly-tap-targets',
+                'sun-glare-readable-contrast',
+                'cellular-degraded-graceful',
+            ],
+        },
+        {
+            id: 'field-tech-handheld',
+            audienceCharacteristics: {
+                segments: ['field-crew-handheld', 'meter-reader'],
+                sizeRange: { minStaff: 1, maxStaff: 1 },
+            },
+            designOverrides: {
+                colorPaletteOverlay: 'high-contrast-outdoor',
+                densityProfile: 'comfortable',
+                typographyScale: 'large-print',
+                motionProfile: 'reduced',
+                radiusProfile: 'rounded',
+            },
+            designImperatives: [
+                'thumb-zone-reachability',
+                'single-hand-operation',
+                'rugged-conditions-tolerance',
+                'barcode-scan-prominent',
+            ],
+        },
+        {
+            id: 'supervisor-tablet',
+            audienceCharacteristics: {
+                segments: ['field-supervisor', 'crew-dispatch-coordinator'],
+                sizeRange: { minStaff: 1, maxStaff: 10 },
+            },
+            designOverrides: {
+                colorPaletteOverlay: 'supervisor-default',
+                densityProfile: 'compact',
+                typographyScale: 'data-dense',
+                motionProfile: 'full',
+                radiusProfile: 'default',
+            },
+            designImperatives: [
+                'multi-crew-overview-at-a-glance',
+                'rapid-reassignment-workflow',
+                'cross-crew-comparative-metrics',
+                'two-handed-tablet-grip-affordance',
+            ],
+        },
+    ],
+};
+// ── ProductC — billing-clerk / customer-portal / csr-dashboard ───────────────
+//
+// Validates role-based audience + workflow-density specialization. Same
+// domain (billing) but radically different roles (internal staff vs end
+// customer vs CSR) on shared substrate.
+const PRODUCT_C = {
+    soulId: 'product-c',
+    description: 'Billing + customer-account management spanning internal staff, end customers, ' +
+        'and customer-service representatives. Validates role-based audience + ' +
+        'workflow-density specialization.',
+    validationAxis: 'role-based audience + workflow-density specialization (RFC-0017 §11)',
+    substrate: INTERNAL_ADOPTER_SUBSTRATE,
+    soulDesignImperatives: ['financial-accuracy-first', 'data-provenance-traceable'],
+    variants: [
+        {
+            id: 'billing-clerk',
+            audienceCharacteristics: {
+                segments: ['billing-staff', 'accounts-receivable'],
+                sizeRange: { minStaff: 1, maxStaff: 20 },
+            },
+            designOverrides: {
+                colorPaletteOverlay: 'billing-staff-neutral',
+                densityProfile: 'compact',
+                typographyScale: 'data-dense',
+                motionProfile: 'reduced',
+                radiusProfile: 'sharp',
+            },
+            designImperatives: [
+                'bulk-edit-efficiency',
+                'keyboard-numpad-optimized',
+                'audit-log-always-visible',
+                'reconciliation-discrepancy-prominent',
+            ],
+        },
+        {
+            id: 'customer-portal',
+            audienceCharacteristics: {
+                segments: ['end-customer', 'self-service-billpayer'],
+                sizeRange: { minStaff: 1, maxStaff: 1 },
+            },
+            designOverrides: {
+                colorPaletteOverlay: 'customer-portal-friendly',
+                densityProfile: 'spacious',
+                typographyScale: 'default',
+                motionProfile: 'full',
+                radiusProfile: 'rounded',
+            },
+            designImperatives: [
+                'plain-language-no-jargon',
+                'self-service-task-completion-clarity',
+                'mobile-first-responsive',
+                'trust-signal-prominent',
+            ],
+        },
+        {
+            id: 'csr-dashboard',
+            audienceCharacteristics: {
+                segments: ['customer-service-representative', 'call-center-agent'],
+                sizeRange: { minStaff: 5, maxStaff: 500 },
+            },
+            designOverrides: {
+                colorPaletteOverlay: 'csr-action-oriented',
+                densityProfile: 'compact',
+                typographyScale: 'data-dense',
+                motionProfile: 'full',
+                radiusProfile: 'default',
+            },
+            designImperatives: [
+                'caller-context-instantly-loaded',
+                'quick-resolution-workflow',
+                'sentiment-aware-prompts',
+                'screen-pop-integration',
+            ],
+        },
+    ],
+};
+// ── Exports ──────────────────────────────────────────────────────────────────
+/**
+ * The three InternalAdopter products — ProductA / ProductB / ProductC.
+ * ProductD is intentionally omitted per RFC-0017 §11 v0.4 (deferred to
+ * RFC-0018 §11 — temporal-context-bound modes are Journey shape, not Variant).
+ */
+export const INTERNAL_ADOPTER_PRODUCTS = [
+    PRODUCT_A,
+    PRODUCT_B,
+    PRODUCT_C,
+];
+/** Individual product accessors for direct consumption by tests / tooling. */
+export const productA = PRODUCT_A;
+export const productB = PRODUCT_B;
+export const productC = PRODUCT_C;
+/**
+ * Build a `variantsBySoul` map suitable for `VariantContext`, derived from
+ * the three product declarations. Test helper + the canonical shape callers
+ * use to wire the reference impl into the admission composite.
+ */
+export function buildVariantsBySoul() {
+    const out = {};
+    for (const product of INTERNAL_ADOPTER_PRODUCTS) {
+        out[product.soulId] = product.variants.map((v) => ({ ...v }));
+    }
+    return out;
+}
+/**
+ * Build a representative `variantScores` map for spot-check admission scoring.
+ *
+ * Score shape: each variant gets `sa1` and `sa2` numbers in [0, 1].
+ * Per-variant scores are chosen to demonstrate that **variant-routed scoring
+ * differs from soul-aggregate scoring on a representative work item** (AC #6):
+ *
+ *   - The "well-aligned" variant for a given work item scores HIGH (sa1=0.92,
+ *     sa2=0.88).
+ *   - The "misaligned" variants score LOW (sa1=0.30-0.40, sa2=0.35-0.45).
+ *
+ * If the same work item were scored at soul-aggregate scope, the average of
+ * its variants would compress to a middling value (sa1≈0.54, sa2≈0.56) —
+ * the variant-routed score for the well-aligned variant is meaningfully
+ * different (≈ +70% on sa1, +57% on sa2). This is the failure mode RFC-0017
+ * §2 documents: soul-aggregate scoring underweights variant-specific intent.
+ *
+ * The spot-check test in `admission-spotcheck.test.ts` exercises this against
+ * a representative ProductA work item ("small-utility onboarding improvement").
+ */
+export function buildVariantScores() {
+    return {
+        'product-a': {
+            'small-utility': { sa1: 0.92, sa2: 0.88 },
+            enterprise: { sa1: 0.35, sa2: 0.4 },
+            'county-regional': { sa1: 0.4, sa2: 0.45 },
+        },
+        'product-b': {
+            'field-tech-on-truck': { sa1: 0.9, sa2: 0.85 },
+            'field-tech-handheld': { sa1: 0.6, sa2: 0.55 },
+            'supervisor-tablet': { sa1: 0.3, sa2: 0.35 },
+        },
+        'product-c': {
+            'billing-clerk': { sa1: 0.88, sa2: 0.82 },
+            'customer-portal': { sa1: 0.3, sa2: 0.35 },
+            'csr-dashboard': { sa1: 0.55, sa2: 0.6 },
+        },
+    };
+}
+/**
+ * Soul-aggregate Sα₁ / Sα₂ baseline for a given Soul, computed by averaging
+ * the per-variant scores from `buildVariantScores()`. Used by the spot-check
+ * test to demonstrate that variant-routed scoring meaningfully deviates from
+ * the soul-aggregate baseline (AC #6).
+ *
+ * The aggregation rule used here is `mean` — chosen because the failure mode
+ * documented in RFC-0017 §2 is the SMOOTHING/AVERAGING effect of soul-aggregate
+ * Sα₂ scoring across heterogeneous variants. Comparing variant-routed to mean
+ * is what shows the misallocation pattern. (The admission composite itself
+ * uses `min` per OQ-4, but that's a different question — we're showing that
+ * the per-variant view is structurally different from any soul-level aggregate.)
+ */
+export function computeSoulAggregateBaseline(soulId) {
+    const scores = buildVariantScores()[soulId];
+    if (!scores) {
+        throw new Error(`[internal-adopter] no variant scores for soul '${soulId}' — ` +
+            `known soulIds: ${INTERNAL_ADOPTER_PRODUCTS.map((p) => p.soulId).join(', ')}`);
+    }
+    const variants = Object.values(scores);
+    const sa1 = variants.reduce((s, v) => s + v.sa1, 0) / variants.length;
+    const sa2 = variants.reduce((s, v) => s + v.sa2, 0) / variants.length;
+    return { sa1, sa2 };
+}
+//# sourceMappingURL=products.js.map

package/dist/variant-admission.d.ts

@@ -0,0 +1,316 @@
+/**
+ * RFC-0017 Phase 2 — In-Soul Variant Pattern admission scorer composition.
+ *
+ * Implements the variant-scope routing algorithm described in RFC-0017 §5.4
+ * and §9 (Phase 2):
+ *
+ *   resolveTargetedVariants(w) = set of (soulId, variantId) pairs declared on
+ *     the work item via `targetedVariants[]` (URI shape `<soul-id>/<variant-id>`).
+ *
+ *   If no `targetedVariants` declared:
+ *     Scoring proceeds at soul-aggregate scope (backward-compatible — unchanged
+ *     from RFC-0009 baseline).
+ *
+ *   Else if |targeted| == 1 (single-variant):
+ *     Sα₁(w) = scoreSα₁(variant.audienceCharacteristics)
+ *     Sα₂(w) = scoreSα₂(variant.designOverrides ∪ variant.designImperatives)
+ *
+ *   Else (multi-variant):
+ *     Per-variant Sα₁ + Sα₂ are aggregated via the Soul's
+ *     `crossVariantAggregation` rule (per-Soul override; default `min` per
+ *     RFC-0017 OQ-4 / RFC-0009 §7.2 consistency).
+ *
+ * This module mirrors the surface shape of `tessellation-admission.ts` so the
+ * composite reader can compose the two layers cleanly: tessellation routing
+ * picks the Soul scope; variant routing refines that to a variant scope when
+ * the work item declares targeted variants of one of the affected souls.
+ *
+ * **Schema dependency note (Phase 1 not yet shipped):**
+ * Phase 1 (AISDLC-352) ships the JSON Schema additions for `variants[]` on
+ * Soul DID and `targetedVariants[]` on Work Item, plus the inheritance
+ * validator. Phase 2 (this file) defines the in-memory shapes the admission
+ * composite needs and the pure routing algorithm. Phase 1 loaders will
+ * populate `VariantContext` from on-disk Soul DIDs once they exist. The
+ * shapes here parallel the schema layout in RFC-0017 §6.1.
+ *
+ * @see spec/rfcs/RFC-0017-in-soul-variant-pattern.md §5.4 + §9 + §10
+ * @see orchestrator/src/tessellation-admission.ts — sibling Soul-scope router
+ */
+import type { Tessellation } from '@ai-sdlc/reference';
+/**
+ * Framework-owned `designOverrides` enum fields per RFC-0017 §6.1 + OQ-5 revisit (2026-05-26).
+ *
+ * Design Authority editorial pass (Mo, 2026-05-26): `voiceRegister` cut — 6/6 leading design
+ * systems (Tailwind, Radix, Material, Carbon, Spectrum, Atlassian) converge on color, spacing,
+ * typography, motion, and radii as the core theming surface; none include content register at
+ * the visual token layer. `typographyScale`, `motionProfile`, and `radiusProfile` added.
+ *
+ * These are the only framework-owned field names. Adopters extend via vendor-prefix
+ * (see `designOverridesExt` below).
+ */
+export interface VariantDesignOverridesFramework {
+    /** Variant-scoped color palette overlay (additive over soul palette). */
+    colorPaletteOverlay?: string;
+    /** Variant-scoped density profile. */
+    densityProfile?: 'compact' | 'comfortable' | 'spacious';
+    /** Variant-scoped typography scale. */
+    typographyScale?: 'default' | 'large-print' | 'data-dense';
+    /** Variant-scoped motion/animation profile. */
+    motionProfile?: 'full' | 'reduced' | 'none';
+    /** Variant-scoped corner-rounding character (shape, not border stroke weight). */
+    radiusProfile?: 'sharp' | 'default' | 'rounded';
+}
+/**
+ * Vendor-prefixed `designOverrides` extension map per RFC-0017 OQ-5.
+ * Keys MUST follow reverse-DNS prefix convention (e.g. `acme.com/accessibilityProfile`).
+ * Schema validation of the prefix is Phase 1's concern; Phase 2 simply consumes
+ * whatever keys are present and treats their truthy presence as a variant-scoped
+ * Sα₂ signal contribution.
+ */
+export type VariantDesignOverridesExt = Record<string, string | number | boolean>;
+/**
+ * In-memory representation of one variant declared on a Soul DID, parallel to
+ * the YAML/JSON schema fields in RFC-0017 §6.1. Phase 1 (AISDLC-352) ships the
+ * schema + loader; Phase 2 uses this shape as the contract between loader and
+ * the variant-scope router.
+ */
+export interface VariantOverlay {
+    /** Variant identifier (kebab-case, unique within the parent Soul). */
+    id: string;
+    /**
+     * Variant-scoped audience characteristics. Feeds Sα₁ Problem/Audience
+     * Resonance scoring when the work item targets this variant (RFC-0017
+     * §5.4 + §6.1 `targetAudience`).
+     */
+    audienceCharacteristics?: {
+        segments?: string[];
+        sizeRange?: {
+            minStaff?: number;
+            maxStaff?: number;
+        };
+        /** Free-form adopter-defined audience fields — preserved as-is for Sα₁. */
+        [k: string]: unknown;
+    };
+    /**
+     * Framework-owned design override fields (closed enum per OQ-5).
+     */
+    designOverrides?: VariantDesignOverridesFramework;
+    /**
+     * Vendor-prefixed adopter extensions (OQ-5). Schema validates the prefix;
+     * any present key contributes to the variant-scoped Sα₂ surface.
+     */
+    designOverridesExt?: VariantDesignOverridesExt;
+    /**
+     * Variant-scoped Sα₂ design imperatives (layered on top of soul-level
+     * imperatives, variant wins on conflict per RFC-0017 §5.4).
+     */
+    designImperatives?: string[];
+}
+/**
+ * Per-variant Sα₁ + Sα₂ scores. One entry per variant of one Soul.
+ *
+ * Phase 1's loader OR a Phase 2/3 scorer populates this — Phase 2's router
+ * is agnostic to how the per-variant scores are produced (could be BM25
+ * against `audienceCharacteristics.segments`, embedding similarity against
+ * `designImperatives`, etc.). The router only knows how to ROUTE among them.
+ */
+export interface VariantScores {
+    /** Variant-scoped Sα₁ Problem/Audience Resonance score, in [0, 1]. */
+    sa1: number;
+    /** Variant-scoped Sα₂ Vibe Coherence score, in [0, 1]. */
+    sa2: number;
+}
+/**
+ * Per-Soul `variantConfig` block, projected from the
+ * `.ai-sdlc/variant-config.yaml` (per-org defaults) + per-Soul overrides
+ * in `spec.variantConfig` (RFC-0017 §10.1).
+ *
+ * Currently surfaces only the OQ-4-resolved knob (cross-variant aggregation).
+ * Future Phase-1 phases add `limits`, `lifecycle`, etc.; this interface stays
+ * tightly scoped to what the admission router consumes.
+ */
+export interface VariantConfig {
+    /**
+     * OQ-4 — cross-variant aggregation rule. Default `min` (matches RFC-0009
+     * §7.2 cross-soul default per the OQ-4 resolution). Per-Soul override
+     * accommodates adopters needing `max` for experimental-variant promotion
+     * or `mean` for blended audience studies.
+     */
+    crossVariantAggregation?: VariantAggregationRule;
+}
+/**
+ * Supported cross-variant aggregation rules. Subset of `Tessellation['crossSoulScoringRule']`
+ * — we expose `min`/`max`/`mean` since those are the variant-scope-meaningful options
+ * (the `weighted-*` variants are platform-scope-only per RFC-0009 §5.2).
+ */
+export type VariantAggregationRule = 'min' | 'max' | 'mean';
+/**
+ * One work item's `targetedVariants[]` declaration. Entries are URI-shaped
+ * `<soul-id>/<variant-id>` per RFC-0017 §6.1 (the URI pattern enforced by
+ * the schema; we accept the trimmed slug form here because the DID prefix
+ * `did:platform-x:soul:` is platform-scoped, not router-scoped).
+ *
+ * The `did:platform-x:soul:engage/variant:small-utility` URI form from
+ * OQ-6 reduces to `engage/small-utility` after the schema's URI parser
+ * extracts the soul-id + variant-id segments.
+ */
+export interface WorkItemVariantTargeting {
+    /** Canonical work item ID (case-insensitive). E.g. "AISDLC-313". */
+    id: string;
+    /**
+     * Variant references in the schema-accepted form. Each entry MUST be the
+     * `<soul-id>/<variant-id>` slug pair (the schema's URI parser normalizes
+     * the full `did:...:variant:...` form down to this).
+     */
+    targetedVariants?: string[];
+}
+/**
+ * Variant-scope context for the admission composite — everything Phase 2's
+ * router needs to refine an already-soul-routed score into a variant-scope
+ * score. Built once per pipeline tick from:
+ *
+ *   - The Soul DIDs of every active soul (their `variants[]` declarations)
+ *   - Pre-computed per-variant Sα₁/Sα₂ scores (Phase 2/3 scorers populate)
+ *   - The active backlog's work-item targeting (one entry per work item)
+ *   - Per-Soul `variantConfig` overrides (resolved against per-org defaults)
+ *
+ * When `undefined` is passed to `computeVariantScopedScores`, the router
+ * preserves single-soul Sα₁/Sα₂ semantics unchanged (backward-compatible).
+ */
+export interface VariantContext {
+    /**
+     * Variant overlays keyed by soulId. Source of truth for which variant IDs
+     * are valid per Soul + their `audienceCharacteristics` / `designOverrides`.
+     */
+    variantsBySoul: Record<string, VariantOverlay[]>;
+    /**
+     * Pre-computed per-variant scores, keyed first by soulId then by variantId.
+     * Missing entries fall back to the work item's soul-aggregate Sα₁/Sα₂.
+     */
+    variantScores: Record<string, Record<string, VariantScores>>;
+    /**
+     * Work-item targeting entries — one per work item in the active backlog.
+     * Missing entries (or empty `targetedVariants`) → backward-compat soul-scope.
+     */
+    workItemTargeting?: WorkItemVariantTargeting[];
+    /**
+     * Per-Soul `variantConfig` overrides (defaults to `{ crossVariantAggregation: 'min' }`
+     * when absent). Keyed by soulId.
+     */
+    configBySoul?: Record<string, VariantConfig>;
+}
+/**
+ * One parsed targeted-variant reference. Internal use; surfaced via the router
+ * for auditability.
+ */
+export interface ParsedVariantRef {
+    soulId: string;
+    variantId: string;
+    /** The original schema-form string (for round-trip + error reporting). */
+    raw: string;
+}
+/**
+ * Parse a targeted-variant reference. Accepts both the schema's accepted forms:
+ *
+ *   1. Slug-pair: `engage/small-utility` (RFC-0017 §6.1 Work Item schema pattern)
+ *   2. Full DID: `did:platform-x:soul:engage/variant:small-utility` (OQ-6)
+ *
+ * Returns `undefined` for any malformed input — caller's responsibility to
+ * surface diagnostics. The schema-side validator is Phase 1's responsibility;
+ * the router treats any malformed entry as ignorable (silent skip + caller can
+ * count them via the returned `parsedTargets`/`malformedTargets` split if
+ * desired).
+ */
+export declare function parseTargetedVariantRef(raw: string): ParsedVariantRef | undefined;
+/**
+ * Resolve the set of targeted (soulId, variantId) pairs for a given work item.
+ *
+ * Algorithm:
+ * 1. Find the work item by case-insensitive ID match in `workItemTargeting`.
+ * 2. Parse each entry of `targetedVariants[]` via `parseTargetedVariantRef`.
+ * 3. Filter parsed refs against `variantsBySoul` — a (soulId, variantId) pair
+ *    only survives if the soul exists AND the variantId is declared on it.
+ * 4. Return the validated intersection (empty = backward-compat soul-scope).
+ *
+ * Returns an empty array (NOT undefined) in all "no variant routing" cases
+ * — the caller distinguishes single-variant / multi-variant / soul-scope
+ * paths by checking `.length`.
+ */
+export declare function resolveTargetedVariants(workItemId: string, variantCtx: VariantContext | undefined): ParsedVariantRef[];
+/**
+ * Apply a per-Soul `crossVariantAggregation` rule over per-variant scores.
+ * Mirrors `applyCrossSoulRule` in `tessellation-admission.ts` but restricted
+ * to the three variant-scope-meaningful aggregations (`min` / `max` / `mean`).
+ *
+ * @param values   - Per-variant score samples (one per targeted variant).
+ * @param rule     - The aggregation rule (defaults to `min` per OQ-4).
+ * @param fallback - Returned when `values` is empty.
+ */
+export declare function applyCrossVariantRule(values: number[], rule: VariantAggregationRule | undefined, fallback?: number): number;
+/**
+ * Result of variant-scope resolution. Composed with `TessellatedSaResult` by
+ * the admission composite — variant routing only takes effect when the work
+ * item declares `targetedVariants` AND the variant context is wired in.
+ */
+export interface VariantScopedSaResult {
+    /** Resolved Sα₁ value in [0, 1] (variant-scoped or fallback). */
+    sa1: number;
+    /** Resolved Sα₂ value in [0, 1] (variant-scoped or fallback). */
+    sa2: number;
+    /**
+     * Routing path taken (matches RFC-0017 §5.4 case labels).
+     *
+     * - `'no-variant-routing'`    — no context or no targeted variants declared;
+     *                                fallback Sα₁/Sα₂ preserved (backward-compat).
+     * - `'single-variant'`        — exactly one targeted variant; per-variant Sα₁/Sα₂ used.
+     * - `'multi-variant'`         — multiple targeted variants; crossVariantAggregation applied.
+     */
+    routingPath: 'no-variant-routing' | 'single-variant' | 'multi-variant';
+    /** Targeted variant references that contributed to the aggregation. */
+    targetedVariants: ParsedVariantRef[];
+    /**
+     * The aggregation rule used when `routingPath === 'multi-variant'`. Undefined
+     * for `single-variant` and `no-variant-routing` paths. Exposed for audit.
+     */
+    aggregationRule?: VariantAggregationRule;
+}
+/**
+ * Compute the variant-scope-refined Sα₁ + Sα₂ for a work item.
+ *
+ * This runs AFTER tessellation soul-resolution: the caller has already routed
+ * the work item to its target Soul(s) and obtained the soul-aggregate Sα₁ /
+ * Sα₂ (the `fallbackSa1` / `fallbackSa2` arguments). Variant routing refines
+ * those values when the work item declares `targetedVariants` of one of the
+ * affected Souls (RFC-0017 §5.4).
+ *
+ * **Cross-soul + cross-variant interaction** (RFC-0017 §6.2 last bullet):
+ * "When a work item targets variants in MULTIPLE souls, the cross-soul
+ * aggregation rule applies at the soul level FIRST, then the cross-variant
+ * rule applies within each soul." Phase 2 implements the per-Soul-scope
+ * variant aggregation; the per-Soul `crossVariantAggregation` config picks
+ * which rule applies inside each Soul. When variants span multiple souls,
+ * each soul's per-variant scores are aggregated by THAT soul's config; the
+ * resulting per-soul scores are then aggregated by the cross-soul rule
+ * (handled by `tessellation-admission.ts`). At the variant-scope layer we
+ * therefore aggregate per-Soul, then aggregate per-Soul-results by `min`
+ * (the safest cross-soul aggregation default — matches RFC-0009 §7.2).
+ *
+ * @param workItemId    - The canonical work item ID.
+ * @param fallbackSa1   - Soul-scope Sα₁ to use when no variant routing applies.
+ * @param fallbackSa2   - Soul-scope Sα₂ to use when no variant routing applies.
+ * @param variantCtx    - Variant-scope context; undefined → backward-compat passthrough.
+ */
+export declare function computeVariantScopedScores(workItemId: string, fallbackSa1: number, fallbackSa2: number, variantCtx: VariantContext | undefined): VariantScopedSaResult;
+/**
+ * Helper for callers that already hold a `Tessellation` (sibling SoulScope router)
+ * and want to lift Soul-scope tessellation aggregation rule into the
+ * variant-scope cross-Soul layer. Currently the variant-scope cross-Soul
+ * layer always uses `min` (RFC-0017 §6.2 + RFC-0009 §7.2 safety-critical
+ * default). This helper is reserved for a future per-Soul override of the
+ * cross-Soul cross-variant layer; today it returns `min` unconditionally.
+ *
+ * Exported for documentation + so callers can `import` the boundary rather
+ * than hardcode `'min'` in two places.
+ */
+export declare function defaultCrossSoulVariantRule(_tessellation?: Tessellation): VariantAggregationRule;
+//# sourceMappingURL=variant-admission.d.ts.map