@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/variant/inheritance-validator.d.ts

@@ -0,0 +1,165 @@
+/**
+ * RFC-0017 Phase 1 — Variant Inheritance Validator.
+ *
+ * Implements RFC-0017 §5.3 bounded-inheritance enforcement. A variant MUST NOT
+ * attempt to override fields that are inherited from (and locked to) the parent
+ * Soul DID. When a violation is detected the validator emits a
+ * `VariantInheritanceViolation` event (RFC-0008 §C5 Engineering vertex error).
+ *
+ * Additionally implements the OQ-1 variant count constraints:
+ *   - Soft warn (non-blocking) at `softWarnAt` variants (default 5).
+ *   - Hard reject at `hardLimit` variants (default 20).
+ *
+ * And the OQ-2 nested-variants rejection: schema-enforced flat means a variant
+ * declaration MUST NOT contain a nested `variants[]` field.
+ *
+ * @see spec/rfcs/RFC-0017-in-soul-variant-pattern.md §5.3 + §10.1
+ * @see orchestrator/src/variant-admission.ts — Phase 2 admission composite
+ */
+/**
+ * Fields that are INHERITED from the parent Soul DID and cannot be overridden
+ * by any variant declaration. Attempting to declare these fields on a variant
+ * triggers a `VariantInheritanceViolation`.
+ *
+ * Corresponds to the left column of the §5.3 inheritance table.
+ */
+export declare const INHERITED_LOCKED_FIELDS: readonly ["complianceRegimes", "substrateInvariants", "tenantQuotaShare", "performanceBudgets", "observabilityRequirements"];
+export type InheritedLockedField = (typeof INHERITED_LOCKED_FIELDS)[number];
+/**
+ * Discriminated event kind for variant-level events emitted to events.jsonl.
+ */
+export type VariantEventKind = 'VariantInheritanceViolation' | 'VariantCountSoftWarning' | 'VariantCountHardLimitExceeded' | 'NestedVariantRejected';
+/**
+ * Emitted when a variant attempts to override an inherited locked field per
+ * RFC-0017 §5.3. This is an Engineering vertex error (RFC-0008 §C5).
+ *
+ * The result is `blocking: true` — the declaring Soul DID is invalid until
+ * the offending override is removed.
+ */
+export interface VariantInheritanceViolation {
+    readonly kind: 'VariantInheritanceViolation';
+    /** Identifier of the Soul DID that contains the offending variant. */
+    readonly soulId: string;
+    /** The variant's `id` field value. */
+    readonly variantId: string;
+    /** The field name the variant attempted to override. */
+    readonly field: InheritedLockedField;
+    /** Human-readable description of the violation. */
+    readonly message: string;
+    /** Always true — inheritance violations are blocking errors. */
+    readonly blocking: true;
+    readonly timestamp: string;
+}
+/**
+ * Non-blocking warning emitted when a Soul DID's variant count reaches the
+ * soft-warn threshold (default 5 per OQ-1). Routes through Decision Catalog
+ * as `Decision: variant-count-soft-warning` for operator batch review.
+ */
+export interface VariantCountSoftWarning {
+    readonly kind: 'VariantCountSoftWarning';
+    readonly soulId: string;
+    readonly variantCount: number;
+    readonly threshold: number;
+    readonly message: string;
+    readonly blocking: false;
+    readonly timestamp: string;
+}
+/**
+ * Hard-blocking rejection emitted when a Soul DID's variant count reaches the
+ * hard limit (default 20 per OQ-1). The Soul DID declaration is rejected.
+ * Routes through Decision Catalog as `Decision: variant-count-hard-limit-exceeded`
+ * plus a clarification task recommending multi-soul re-architecture.
+ */
+export interface VariantCountHardLimitExceeded {
+    readonly kind: 'VariantCountHardLimitExceeded';
+    readonly soulId: string;
+    readonly variantCount: number;
+    readonly limit: number;
+    readonly message: string;
+    readonly blocking: true;
+    readonly timestamp: string;
+}
+/**
+ * Emitted when a nested `variants[]` field is detected inside a variant
+ * declaration. Schema-enforced flat per RFC-0017 OQ-2. Blocking.
+ */
+export interface NestedVariantRejected {
+    readonly kind: 'NestedVariantRejected';
+    readonly soulId: string;
+    readonly variantId: string;
+    readonly message: string;
+    readonly blocking: true;
+    readonly timestamp: string;
+}
+export type VariantEvent = VariantInheritanceViolation | VariantCountSoftWarning | VariantCountHardLimitExceeded | NestedVariantRejected;
+/**
+ * Minimal representation of one variant declaration as loaded from a Soul DID.
+ * Mirrors the JSON Schema shape at `spec/schemas/design-intent-document.schema.json`
+ * `$defs.variantDeclaration`.
+ */
+export interface VariantDeclarationInput {
+    /** Kebab-case variant id. */
+    id: string;
+    /**
+     * Any additional fields present in the raw declaration — used to detect
+     * attempts to override locked inherited fields.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Per-org variant count configuration. Loaded from
+ * `.ai-sdlc/variant-config.yaml` (`variant.limits`) with the defaults below.
+ */
+export interface VariantLimitsConfig {
+    /** Non-blocking soft warn threshold. Default: 5. */
+    softWarnAt?: number;
+    /** Hard-blocking rejection limit. Default: 20. */
+    hardLimit?: number;
+}
+/**
+ * Options for `validateVariantDeclarations`.
+ */
+export interface ValidateVariantDeclarationsOptions {
+    /** Identifier of the Soul DID being validated (for event attribution). */
+    soulId: string;
+    /** Raw variant declarations from the Soul DID's `spec.variants[]`. */
+    variants: VariantDeclarationInput[];
+    /** Per-org or per-Soul limit overrides. Defaults apply when absent. */
+    limits?: VariantLimitsConfig;
+    /** ISO 8601 timestamp to stamp on emitted events. Defaults to now. */
+    now?: string;
+}
+/** OQ-1 default: soft warn at 5 variants (Miller 7±2 cognitive-load threshold). */
+export declare const DEFAULT_SOFT_WARN_AT = 5;
+/** OQ-1 default: hard limit at 20 variants (re-architect-as-multi-soul threshold). */
+export declare const DEFAULT_HARD_LIMIT = 20;
+/**
+ * Validate a Soul DID's `variants[]` declarations against RFC-0017 §5.3 rules.
+ *
+ * Returns all emitted events. Callers check `event.blocking` to determine
+ * whether the Soul DID should be rejected. Caller's responsibility to write
+ * events to events.jsonl via the artifact layer.
+ *
+ * Validation rules (in order):
+ *
+ *   1. **Hard-limit check (OQ-1)** — if `variants.length >= hardLimit`, emit
+ *      `VariantCountHardLimitExceeded` (blocking). Continue to check individual
+ *      variants for completeness of the error report.
+ *
+ *   2. **Soft-warn check (OQ-1)** — if `variants.length >= softWarnAt` AND
+ *      below hard limit, emit `VariantCountSoftWarning` (non-blocking).
+ *
+ *   3. **Per-variant inheritance check (§5.3)** — for each variant, verify it
+ *      does not declare any field from `INHERITED_LOCKED_FIELDS`. Each violation
+ *      emits `VariantInheritanceViolation` (blocking).
+ *
+ *   4. **Nested-variants rejection (OQ-2)** — for each variant, verify it does
+ *      not contain a `variants` key. Emits `NestedVariantRejected` (blocking).
+ */
+export declare function validateVariantDeclarations(options: ValidateVariantDeclarationsOptions): VariantEvent[];
+/**
+ * Convenience predicate: returns true when any event in the list is blocking.
+ * Use to decide whether to reject the Soul DID declaration.
+ */
+export declare function hasBlockingViolations(events: VariantEvent[]): boolean;
+//# sourceMappingURL=inheritance-validator.d.ts.map

package/dist/variant/inheritance-validator.js

@@ -0,0 +1,139 @@
+/**
+ * RFC-0017 Phase 1 — Variant Inheritance Validator.
+ *
+ * Implements RFC-0017 §5.3 bounded-inheritance enforcement. A variant MUST NOT
+ * attempt to override fields that are inherited from (and locked to) the parent
+ * Soul DID. When a violation is detected the validator emits a
+ * `VariantInheritanceViolation` event (RFC-0008 §C5 Engineering vertex error).
+ *
+ * Additionally implements the OQ-1 variant count constraints:
+ *   - Soft warn (non-blocking) at `softWarnAt` variants (default 5).
+ *   - Hard reject at `hardLimit` variants (default 20).
+ *
+ * And the OQ-2 nested-variants rejection: schema-enforced flat means a variant
+ * declaration MUST NOT contain a nested `variants[]` field.
+ *
+ * @see spec/rfcs/RFC-0017-in-soul-variant-pattern.md §5.3 + §10.1
+ * @see orchestrator/src/variant-admission.ts — Phase 2 admission composite
+ */
+// ── Inherited (locked) field names per RFC-0017 §5.3 ────────────────────────
+/**
+ * Fields that are INHERITED from the parent Soul DID and cannot be overridden
+ * by any variant declaration. Attempting to declare these fields on a variant
+ * triggers a `VariantInheritanceViolation`.
+ *
+ * Corresponds to the left column of the §5.3 inheritance table.
+ */
+export const INHERITED_LOCKED_FIELDS = [
+    'complianceRegimes',
+    'substrateInvariants',
+    'tenantQuotaShare',
+    'performanceBudgets',
+    'observabilityRequirements',
+];
+// ── Default constants ────────────────────────────────────────────────────────
+/** OQ-1 default: soft warn at 5 variants (Miller 7±2 cognitive-load threshold). */
+export const DEFAULT_SOFT_WARN_AT = 5;
+/** OQ-1 default: hard limit at 20 variants (re-architect-as-multi-soul threshold). */
+export const DEFAULT_HARD_LIMIT = 20;
+// ── Validator ────────────────────────────────────────────────────────────────
+/**
+ * Validate a Soul DID's `variants[]` declarations against RFC-0017 §5.3 rules.
+ *
+ * Returns all emitted events. Callers check `event.blocking` to determine
+ * whether the Soul DID should be rejected. Caller's responsibility to write
+ * events to events.jsonl via the artifact layer.
+ *
+ * Validation rules (in order):
+ *
+ *   1. **Hard-limit check (OQ-1)** — if `variants.length >= hardLimit`, emit
+ *      `VariantCountHardLimitExceeded` (blocking). Continue to check individual
+ *      variants for completeness of the error report.
+ *
+ *   2. **Soft-warn check (OQ-1)** — if `variants.length >= softWarnAt` AND
+ *      below hard limit, emit `VariantCountSoftWarning` (non-blocking).
+ *
+ *   3. **Per-variant inheritance check (§5.3)** — for each variant, verify it
+ *      does not declare any field from `INHERITED_LOCKED_FIELDS`. Each violation
+ *      emits `VariantInheritanceViolation` (blocking).
+ *
+ *   4. **Nested-variants rejection (OQ-2)** — for each variant, verify it does
+ *      not contain a `variants` key. Emits `NestedVariantRejected` (blocking).
+ */
+export function validateVariantDeclarations(options) {
+    const { soulId, variants, limits, now } = options;
+    const timestamp = now ?? new Date().toISOString();
+    const softWarnAt = limits?.softWarnAt ?? DEFAULT_SOFT_WARN_AT;
+    const hardLimit = limits?.hardLimit ?? DEFAULT_HARD_LIMIT;
+    const events = [];
+    const count = variants.length;
+    // Rule 1 — Hard limit (OQ-1)
+    if (count >= hardLimit) {
+        events.push({
+            kind: 'VariantCountHardLimitExceeded',
+            soulId,
+            variantCount: count,
+            limit: hardLimit,
+            message: `Soul '${soulId}' declares ${count} variant(s), reaching or exceeding the hard limit of ` +
+                `${hardLimit}. Declaration rejected. Consider re-architecting as multiple Soul DIDs ` +
+                `(RFC-0017 §5.5 boundary guidance). Decision: variant-count-hard-limit-exceeded.`,
+            blocking: true,
+            timestamp,
+        });
+    }
+    else if (count >= softWarnAt) {
+        // Rule 2 — Soft warn (OQ-1, non-blocking)
+        events.push({
+            kind: 'VariantCountSoftWarning',
+            soulId,
+            variantCount: count,
+            threshold: softWarnAt,
+            message: `Soul '${soulId}' declares ${count} variant(s), at or above the soft-warn threshold of ` +
+                `${softWarnAt}. Non-blocking review recommended. Decision: variant-count-soft-warning.`,
+            blocking: false,
+            timestamp,
+        });
+    }
+    // Rules 3 + 4 — Per-variant checks
+    for (const variant of variants) {
+        const variantId = String(variant.id ?? '<unknown>');
+        // Rule 3 — Inheritance violation check (§5.3)
+        for (const field of INHERITED_LOCKED_FIELDS) {
+            if (Object.prototype.hasOwnProperty.call(variant, field)) {
+                events.push({
+                    kind: 'VariantInheritanceViolation',
+                    soulId,
+                    variantId,
+                    field,
+                    message: `Variant '${variantId}' on soul '${soulId}' attempts to override '${field}', ` +
+                        `which is inherited-and-locked from the parent Soul DID (RFC-0017 §5.3 bounded ` +
+                        `inheritance table). Remove '${field}' from the variant declaration.`,
+                    blocking: true,
+                    timestamp,
+                });
+            }
+        }
+        // Rule 4 — Nested variants rejection (OQ-2)
+        if (Object.prototype.hasOwnProperty.call(variant, 'variants')) {
+            events.push({
+                kind: 'NestedVariantRejected',
+                soulId,
+                variantId,
+                message: `Variant '${variantId}' on soul '${soulId}' declares a nested 'variants[]' field. ` +
+                    `RFC-0017 OQ-2 resolution mandates schema-enforced flat: variants cannot contain ` +
+                    `sub-variants in v1. Remove the nested 'variants' field.`,
+                blocking: true,
+                timestamp,
+            });
+        }
+    }
+    return events;
+}
+/**
+ * Convenience predicate: returns true when any event in the list is blocking.
+ * Use to decide whether to reject the Soul DID declaration.
+ */
+export function hasBlockingViolations(events) {
+    return events.some((e) => e.blocking);
+}
+//# sourceMappingURL=inheritance-validator.js.map

package/dist/variant/internal-adopter/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * RFC-0017 Phase 4 — InternalAdopter three-product reference impl barrel.
+ *
+ * Re-exports the canonical product fixtures + helpers. ProductD is
+ * intentionally absent — deferred to RFC-0018 per RFC-0017 §11 v0.4.
+ *
+ * @see ./products.ts
+ */
+export { INTERNAL_ADOPTER_SUBSTRATE, INTERNAL_ADOPTER_PRODUCTS, productA, productB, productC, buildVariantsBySoul, buildVariantScores, computeSoulAggregateBaseline, } from './products.js';
+export type { InternalAdopterSubstrate, InternalAdopterProduct } from './products.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,10 @@
+/**
+ * RFC-0017 Phase 4 — InternalAdopter three-product reference impl barrel.
+ *
+ * Re-exports the canonical product fixtures + helpers. ProductD is
+ * intentionally absent — deferred to RFC-0018 per RFC-0017 §11 v0.4.
+ *
+ * @see ./products.ts
+ */
+export { INTERNAL_ADOPTER_SUBSTRATE, INTERNAL_ADOPTER_PRODUCTS, productA, productB, productC, buildVariantsBySoul, buildVariantScores, computeSoulAggregateBaseline, } from './products.js';
+//# sourceMappingURL=index.js.map

package/dist/variant/internal-adopter/products.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 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
+ */
+import type { VariantOverlay, VariantScores } from '../../variant-admission.js';
+/**
+ * The shared substrate every InternalAdopter product Soul inherits.
+ *
+ * Per RFC-0017 §5.3 bounded-inheritance table: substrate fields are
+ * INHERITED-AND-LOCKED — variants cannot override these. Capturing them here
+ * in a single shared constant proves AC #7 (substrate shared across variants
+ * of every product) at the type/declaration level rather than via runtime
+ * spot-check alone.
+ *
+ * `complianceRegimes: ['WCAG-2.1-AA']` is the field-tech-deployed baseline
+ * documented in RFC-0017 §1: "all sharing the soul's WCAG 2.1 AA compliance
+ * floor and shared design system tokens."
+ */
+export interface InternalAdopterSubstrate {
+    /** Compliance regimes inherited by every variant on every product. */
+    readonly complianceRegimes: readonly string[];
+    /**
+     * Substrate invariants — event bus, schema, tenant model. Captured as an
+     * opaque string identifier here; the reconciler is what proves substrate
+     * sharing at runtime (per RFC-0017 §5.3 footnote).
+     */
+    readonly substrateInvariants: {
+        readonly eventBus: string;
+        readonly schemaRegistry: string;
+        readonly tenantModel: string;
+    };
+    /** Engineering performance budgets shared across all variants. */
+    readonly performanceBudgets: {
+        readonly initialLoadMs: number;
+        readonly interactionResponseMs: number;
+    };
+    /** Engineering observability requirements shared across all variants. */
+    readonly observabilityRequirements: readonly string[];
+}
+/**
+ * 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 declare const INTERNAL_ADOPTER_SUBSTRATE: InternalAdopterSubstrate;
+/**
+ * A reference-impl Soul descriptor. Captures the inherited-locked substrate
+ * separately from the variant overlays so AC #7 (substrate shared across
+ * variants) is provable by structural inspection.
+ *
+ * This is NOT the full Soul DID schema (`reference/src/core/types.ts` carries
+ * that). It's the minimum surface needed for the variant-pattern reference
+ * impl — `soulId` + shared substrate + variant overlays.
+ */
+export interface InternalAdopterProduct {
+    /** Soul identifier in kebab-case. */
+    readonly soulId: string;
+    /** Human-readable product description. */
+    readonly description: string;
+    /** What variant axis this product is validating per RFC-0017 §11. */
+    readonly validationAxis: string;
+    /** Shared substrate — identical reference across all three products (AC #7). */
+    readonly substrate: InternalAdopterSubstrate;
+    /** Variant overlays declared on this Soul (exactly 3 per RFC-0017 §11). */
+    readonly variants: readonly VariantOverlay[];
+    /**
+     * Soul-level `designImperatives` — apply to all variants of this Soul
+     * unless a variant overrides the same design dimension (variant-wins per
+     * RFC-0017 §5.4). Captured here so the admission-spotcheck test can
+     * compose soul-aggregate vs variant-routed scoring.
+     */
+    readonly soulDesignImperatives: readonly string[];
+}
+/**
+ * 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 declare const INTERNAL_ADOPTER_PRODUCTS: readonly InternalAdopterProduct[];
+/** Individual product accessors for direct consumption by tests / tooling. */
+export declare const productA: InternalAdopterProduct;
+export declare const productB: InternalAdopterProduct;
+export declare const productC: InternalAdopterProduct;
+/**
+ * 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 declare function buildVariantsBySoul(): Record<string, VariantOverlay[]>;
+/**
+ * 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 declare function buildVariantScores(): Record<string, Record<string, VariantScores>>;
+/**
+ * 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 declare function computeSoulAggregateBaseline(soulId: string): {
+    sa1: number;
+    sa2: number;
+};
+//# sourceMappingURL=products.d.ts.map