@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/substrate/drift-composition.js

@@ -0,0 +1,306 @@
+/**
+ * RFC-0028 §7.2 — structural + statistical drift composition.
+ *
+ * Phase 3 of RFC-0028 §7.2 v0.2 resolution. Wires the canonical pairing of
+ * the two drift-detection layers with the explicit composition rules the
+ * operator resolved on 2026-05-27:
+ *
+ * 1. **Structural drift (CI authoring-time) REJECTS deployment.** The
+ *    type-registry CI gate (`scripts/check-substrate-contract.mjs`,
+ *    AISDLC-453) is the hard gate. When any of its 5 assertions fail it emits
+ *    `Decision: substrate-structural-drift-detected` (severity HIGH) and
+ *    blocks PR merge via a non-zero exit code. This module does NOT rebuild
+ *    that gate — it *represents* its outcome so the two layers can be
+ *    composed and correlated. {@link toStructuralDriftEvents} maps the gate's
+ *    result into the composition model.
+ *
+ * 2. **Statistical drift (runtime) SURFACES to operator (RFC-0035 G0
+ *    non-blocking).** PPA's `SoulDriftDetected` signal (rolling 30-day mean
+ *    < 0.4 or stddev > 0.15 sustained for 3 sprints) routes to
+ *    `Decision: soul-statistical-drift-detected` → operator batch review with
+ *    three reconciliation paths. The pipeline NEVER halts on statistical
+ *    drift. {@link evaluateStatisticalDrift} computes the signal;
+ *    {@link composeDrift} routes the firing signal to the catalog request.
+ *
+ * 3. **Both Decisions composable in the catalog.** Both classes carry a
+ *    `soulId` + a stable `driftClass` discriminant and share one catalog
+ *    scope ({@link DRIFT_DECISION_SCOPE}) so an operator can query
+ *    "show me all drift events for Soul X" and get structural (rejected at
+ *    CI) and statistical (caught at runtime) events side-by-side —
+ *    {@link correlateDriftBySoul}.
+ *
+ * 4. **Cold-start handling.** Statistical detection needs a rolling 30d
+ *    baseline. Pre-baseline (< 30d of signal), the detector returns a
+ *    `calibrating` status and emits NO statistical Decisions — structural
+ *    detection is the sole defense during the calibration window. The
+ *    cold-start shape mirrors RFC-0030 §13 OQ-13.5's z-score flooding
+ *    detector (calibrating until the rolling window fills, then active).
+ *
+ * **AC-8 — no parallel event emitter.** This module does NOT import or write
+ * to the catalog event log directly. Mirroring the Phase 1 `identity-class.ts`
+ * audit and the Phase 2 `check-substrate-contract.mjs` gate, it produces
+ * `DriftDecisionRequest` payloads (summary + scope + source + options) that
+ * the *caller* forwards to the existing RFC-0035 substrate via
+ * `node pipeline-cli/bin/cli-decisions.mjs add` (or `makeDecisionOpenedEvent`
+ * + `appendDecisionEvent` in-process). The request shape is byte-compatible
+ * with `cli-decisions add --summary … --scope … --option id:desc`. This keeps
+ * the orchestrator package free of a build-time dependency on
+ * `@ai-sdlc/pipeline-cli`'s dist output and avoids a second emitter.
+ *
+ * @see spec/rfcs/RFC-0028-engineering-axis-substrate-enforcement.md §7.2
+ * @see spec/rfcs/RFC-0035-decision-catalog-operator-routing.md (G0 routing)
+ * @see scripts/check-substrate-contract.mjs (the structural layer, AISDLC-453)
+ * @module substrate/drift-composition
+ */
+/**
+ * The RFC-0035 Decision scope used for every drift Decision. Both classes
+ * share one scope so `cli-decisions list --scope substrate-drift` returns
+ * the composed view (AC-3 / AC-5).
+ */
+export const DRIFT_DECISION_SCOPE = 'substrate-drift';
+/** Decision summary slug for structural drift (matches AISDLC-453 gate). */
+export const STRUCTURAL_DECISION_SLUG = 'substrate-structural-drift-detected';
+/** Decision summary slug for statistical drift (RFC-0028 §7.2 rule 2). */
+export const STATISTICAL_DECISION_SLUG = 'soul-statistical-drift-detected';
+/**
+ * Statistical-drift detection thresholds, frozen from RFC-0028 §7.2 / PPA's
+ * `SoulDriftDetected` definition. A drift fires when the rolling 30-day mean
+ * drops below {@link MEAN_FLOOR} OR the rolling stddev exceeds
+ * {@link STDDEV_CEILING}, sustained for {@link SUSTAINED_SPRINTS} sprints.
+ */
+export const MEAN_FLOOR = 0.4;
+export const STDDEV_CEILING = 0.15;
+export const SUSTAINED_SPRINTS = 3;
+/** Rolling baseline window in days (RFC-0028 §7.2 cold-start: 30d). */
+export const BASELINE_WINDOW_DAYS = 30;
+// ── Reconciliation paths (RFC-0028 §7.2 — exactly three) ──────────────────
+/**
+ * The three (and only three) operator reconciliation paths for a
+ * `soul-statistical-drift-detected` Decision, per RFC-0028 §7.2:
+ *
+ * (a) confirm drift as legitimate evolution → emit DID amendment
+ * (b) confirm drift as substrate violation → file fix task
+ * (c) defer for the next operator review window
+ */
+export const STATISTICAL_RECONCILIATION_OPTIONS = Object.freeze([
+    {
+        id: 'confirm-as-evolution',
+        description: 'Confirm drift as legitimate evolution — emit a DID amendment to ratify the new baseline.',
+        consequences: ['DID amendment authored', 'New baseline ratified as intended state'],
+    },
+    {
+        id: 'confirm-as-violation',
+        description: 'Confirm drift as a substrate violation — file a fix task to restore the contracted baseline.',
+        consequences: ['Fix task filed', 'Substrate restored to contracted intent'],
+    },
+    {
+        id: 'defer',
+        description: 'Defer for the next operator review window — re-surface unchanged at the next batch review.',
+        consequences: ['Decision re-surfaces next review window', 'No state change'],
+    },
+]);
+/** Structural-drift reconciliation options mirror the AISDLC-453 CI gate. */
+export const STRUCTURAL_RECONCILIATION_OPTIONS = Object.freeze([
+    { id: 'fix', description: 'Correct the contract field causing the assertion failure.' },
+    { id: 'exempt', description: 'Document an RFC-approved exemption for this soul.' },
+]);
+/**
+ * Project the structural CI gate's result into composition `DriftEvent`s.
+ *
+ * One `DriftEvent` per gate failure. Always `blocking: true` / severity
+ * `high` — structural drift is the hard gate (RFC-0028 §7.2 rule 1). Returns
+ * `[]` when the gate passed or was a cold-start no-op (no contracts).
+ */
+export function toStructuralDriftEvents(result) {
+    if (result.passed || result.coldStart)
+        return [];
+    return result.failures.map((f) => ({
+        driftClass: 'structural',
+        soulId: f.soulId,
+        severity: 'high',
+        blocking: true,
+        summary: f.decisionSummary ?? `${STRUCTURAL_DECISION_SLUG}: Soul "${f.soulId}" — ${f.message}`,
+        detail: f.message,
+    }));
+}
+function mean(values) {
+    return values.reduce((a, b) => a + b, 0) / values.length;
+}
+function populationStdDev(values, mu) {
+    const variance = values.reduce((acc, v) => acc + (v - mu) ** 2, 0) / values.length;
+    return Math.sqrt(variance);
+}
+/** Count the length of the trailing run of `true` values. */
+function trailingTrueRun(flags) {
+    let run = 0;
+    for (let i = flags.length - 1; i >= 0; i--) {
+        if (flags[i])
+            run += 1;
+        else
+            break;
+    }
+    return run;
+}
+/**
+ * Evaluate statistical drift for one Soul DID over its metric history.
+ *
+ * Cold-start (AC-4): if the span between the earliest sample and `now` is
+ * shorter than {@link BASELINE_WINDOW_DAYS}, the detector is still
+ * `calibrating` — it returns `drifted: false` with null statistics and the
+ * caller emits no Decision. Structural detection (AISDLC-453) is the sole
+ * defense during this window.
+ *
+ * Once the window is filled the detector is `active`: drift fires when the
+ * rolling mean < {@link MEAN_FLOOR} OR the rolling stddev >
+ * {@link STDDEV_CEILING}, AND that condition has held for at least
+ * {@link SUSTAINED_SPRINTS} consecutive sprint buckets.
+ *
+ * The cold-start shape mirrors RFC-0030 §13 OQ-13.5's z-score flooding
+ * detector (calibrating until the window accumulates, then active).
+ *
+ * @param samples Metric history (any order). Empty → calibrating.
+ * @param sprintFlags Per-sprint booleans (most-recent last) indicating
+ *   whether the drift condition held in each sprint; used to enforce the
+ *   "3 sustained sprints" rule independent of raw sample cadence. When
+ *   omitted, sustained-sprint accounting falls back to whether the current
+ *   window meets the condition (counts as 1 sprint, so a single-window
+ *   breach is reported but does not satisfy the 3-sprint rule).
+ * @param now Clock override for deterministic tests.
+ */
+export function evaluateStatisticalDrift(samples, sprintFlags, now = new Date()) {
+    if (samples.length === 0) {
+        return {
+            status: 'calibrating',
+            drifted: false,
+            rollingMean: null,
+            rollingStdDev: null,
+            sustainedSprints: 0,
+            reason: 'No signal yet — calibrating (cold-start).',
+        };
+    }
+    const sorted = [...samples].sort((a, b) => new Date(a.at).getTime() - new Date(b.at).getTime());
+    const earliest = new Date(sorted[0].at).getTime();
+    const spanDays = (now.getTime() - earliest) / (1000 * 60 * 60 * 24);
+    if (spanDays < BASELINE_WINDOW_DAYS) {
+        return {
+            status: 'calibrating',
+            drifted: false,
+            rollingMean: null,
+            rollingStdDev: null,
+            sustainedSprints: 0,
+            reason: `Baseline incomplete (${spanDays.toFixed(1)}d / ${BASELINE_WINDOW_DAYS}d) — calibrating; structural detection is sole defense.`,
+        };
+    }
+    // Active: compute rolling stats over the trailing 30d window.
+    const cutoff = now.getTime() - BASELINE_WINDOW_DAYS * 24 * 60 * 60 * 1000;
+    const windowValues = sorted.filter((s) => new Date(s.at).getTime() >= cutoff).map((s) => s.value);
+    // Fall back to the whole series if the trailing window is empty (sparse cadence).
+    const values = windowValues.length > 0 ? windowValues : sorted.map((s) => s.value);
+    const mu = mean(values);
+    const sigma = populationStdDev(values, mu);
+    const meanBreach = mu < MEAN_FLOOR;
+    const stdDevBreach = sigma > STDDEV_CEILING;
+    const conditionMet = meanBreach || stdDevBreach;
+    const sustainedSprints = sprintFlags ? trailingTrueRun(sprintFlags) : conditionMet ? 1 : 0;
+    const drifted = conditionMet && sustainedSprints >= SUSTAINED_SPRINTS;
+    const reasons = [];
+    if (meanBreach)
+        reasons.push(`rolling 30d mean ${mu.toFixed(3)} < ${MEAN_FLOOR}`);
+    if (stdDevBreach)
+        reasons.push(`rolling 30d stddev ${sigma.toFixed(3)} > ${STDDEV_CEILING}`);
+    const reason = drifted
+        ? `${reasons.join(' and ')} sustained for ${sustainedSprints} sprint(s).`
+        : conditionMet
+            ? `${reasons.join(' and ')} but only ${sustainedSprints}/${SUSTAINED_SPRINTS} sustained sprints — not yet drifted.`
+            : `Within bounds (mean ${mu.toFixed(3)}, stddev ${sigma.toFixed(3)}).`;
+    return {
+        status: 'active',
+        drifted,
+        rollingMean: mu,
+        rollingStdDev: sigma,
+        sustainedSprints,
+        reason,
+    };
+}
+/**
+ * Project an `active` + `drifted` statistical result into a composition
+ * `DriftEvent`. Returns `null` while calibrating or not drifted — there is
+ * nothing to surface to the operator (AC-4: no statistical Decisions during
+ * cold-start).
+ */
+export function toStatisticalDriftEvent(soulId, result) {
+    if (result.status !== 'active' || !result.drifted)
+        return null;
+    return {
+        driftClass: 'statistical',
+        soulId,
+        severity: 'advisory',
+        blocking: false,
+        summary: `${STATISTICAL_DECISION_SLUG}: Soul "${soulId}" — ${result.reason}`,
+        detail: result.reason,
+    };
+}
+/** Build the catalog request for one composed drift event. */
+export function toDecisionRequest(event) {
+    const isStructural = event.driftClass === 'structural';
+    return {
+        // Structural failures are emergent CI findings; statistical drift is a
+        // framework-calibration signal. Both are valid catalog sources.
+        source: isStructural ? 'emergent-finding' : 'framework-calibration',
+        scope: DRIFT_DECISION_SCOPE,
+        summary: event.summary,
+        ...(event.detail !== undefined ? { body: event.detail } : {}),
+        // Statistical drift is reversible/non-blocking (G0); structural is a hard
+        // gate the operator must clear.
+        reversible: !isStructural,
+        options: [
+            ...(isStructural ? STRUCTURAL_RECONCILIATION_OPTIONS : STATISTICAL_RECONCILIATION_OPTIONS),
+        ],
+    };
+}
+/**
+ * Compose the structural gate outcome with a set of statistical results.
+ *
+ * - Structural events → `substrate-structural-drift-detected` (HIGH,
+ *   blocking). Represented from the CI gate result; the gate itself already
+ *   emits + blocks at CI time (AISDLC-453), so the catalog request here is the
+ *   composition/audit projection (so structural + statistical sit
+ *   side-by-side in one scope).
+ * - Statistical drifted events → `soul-statistical-drift-detected`
+ *   (advisory, non-blocking, G0) with the three reconciliation options.
+ * - Calibrating / non-drifted statistical results emit NO request (AC-4).
+ *
+ * The pipeline never halts here: `blocked` reports the structural hard-gate
+ * state for the CI caller to act on, but statistical drift never sets it.
+ */
+export function composeDrift(structural, statistical) {
+    const structuralEvents = toStructuralDriftEvents(structural);
+    const statisticalEvents = [];
+    for (const { soulId, result } of statistical) {
+        const evt = toStatisticalDriftEvent(soulId, result);
+        if (evt)
+            statisticalEvents.push(evt);
+    }
+    const events = [...structuralEvents, ...statisticalEvents];
+    return {
+        events,
+        requests: events.map(toDecisionRequest),
+        blocked: structuralEvents.length > 0,
+    };
+}
+// ── Catalog correlation (AC-3 / AC-5) ─────────────────────────────────────
+/**
+ * Group composed drift events by Soul DID so an operator can query
+ * "show me all drift events for Soul X" and get both classes side-by-side.
+ * Returns a map keyed by `soulId` whose values preserve event order.
+ */
+export function correlateDriftBySoul(events) {
+    const bySoul = new Map();
+    for (const evt of events) {
+        const list = bySoul.get(evt.soulId) ?? [];
+        list.push(evt);
+        bySoul.set(evt.soulId, list);
+    }
+    return bySoul;
+}
+//# sourceMappingURL=drift-composition.js.map

package/dist/substrate/drift-tui-surface.d.ts

@@ -0,0 +1,61 @@
+/**
+ * RFC-0028 §7.2 — drift composition TUI surface (AC-5).
+ *
+ * Renders structural + statistical drift events side-by-side for the operator
+ * batch-review panel. Composes with the RFC-0023 operator TUI: this module
+ * produces a plain-text section (a `DriftPanel` string + a structured
+ * `DriftPanelModel`) that the TUI host embeds in its pipeline-visibility view.
+ * Keeping the render pure (string in / string out, no terminal control codes)
+ * lets the RFC-0023 surface own layout, paging, and color while this module
+ * owns the drift-specific content.
+ *
+ * Side-by-side requirement (RFC-0028 §7.2 rule 3): events are grouped by Soul
+ * DID via {@link correlateDriftBySoul} so each soul shows its structural
+ * (rejected-at-CI, HIGH) and statistical (caught-at-runtime, advisory) drift
+ * together — closing the "drift caught early vs drift that escaped" loop.
+ *
+ * @see spec/rfcs/RFC-0023-operator-tui.md (the host surface)
+ * @see spec/rfcs/RFC-0028-engineering-axis-substrate-enforcement.md §7.2
+ * @module substrate/drift-tui-surface
+ */
+import { type DriftClass, type DriftEvent } from './drift-composition.js';
+/** A single rendered row in the drift panel. */
+export interface DriftPanelRow {
+    soulId: string;
+    driftClass: DriftClass;
+    /** `BLOCKS` for structural, `surface` for statistical. */
+    disposition: 'BLOCKS' | 'surface';
+    severity: DriftEvent['severity'];
+    summary: string;
+}
+/** Per-soul grouping for the side-by-side panel model. */
+export interface DriftPanelSoulGroup {
+    soulId: string;
+    structural: DriftPanelRow[];
+    statistical: DriftPanelRow[];
+}
+/** The structured model a TUI host can render however it likes (AC-5). */
+export interface DriftPanelModel {
+    /** Souls in stable (insertion) order, each with both drift classes. */
+    groups: DriftPanelSoulGroup[];
+    structuralCount: number;
+    statisticalCount: number;
+    /** True if any structural (blocking) drift is present. */
+    hasBlocking: boolean;
+}
+/**
+ * Build the structured panel model from composed drift events. Souls appear
+ * in first-seen order; within each soul, structural rows precede statistical
+ * rows (hard gate first, then advisory).
+ */
+export declare function buildDriftPanelModel(events: DriftEvent[]): DriftPanelModel;
+/**
+ * Render the drift panel as a plain-text section for the RFC-0023 TUI.
+ *
+ * Produces a per-soul block with structural drift (rejected at CI, hard gate)
+ * and statistical drift (surfaced for operator review, non-blocking) shown
+ * side-by-side under each Soul DID. Empty input renders a single "no drift"
+ * line so the panel never collapses to nothing.
+ */
+export declare function renderDriftPanel(events: DriftEvent[]): string;
+//# sourceMappingURL=drift-tui-surface.d.ts.map

package/dist/substrate/drift-tui-surface.js

@@ -0,0 +1,102 @@
+/**
+ * RFC-0028 §7.2 — drift composition TUI surface (AC-5).
+ *
+ * Renders structural + statistical drift events side-by-side for the operator
+ * batch-review panel. Composes with the RFC-0023 operator TUI: this module
+ * produces a plain-text section (a `DriftPanel` string + a structured
+ * `DriftPanelModel`) that the TUI host embeds in its pipeline-visibility view.
+ * Keeping the render pure (string in / string out, no terminal control codes)
+ * lets the RFC-0023 surface own layout, paging, and color while this module
+ * owns the drift-specific content.
+ *
+ * Side-by-side requirement (RFC-0028 §7.2 rule 3): events are grouped by Soul
+ * DID via {@link correlateDriftBySoul} so each soul shows its structural
+ * (rejected-at-CI, HIGH) and statistical (caught-at-runtime, advisory) drift
+ * together — closing the "drift caught early vs drift that escaped" loop.
+ *
+ * @see spec/rfcs/RFC-0023-operator-tui.md (the host surface)
+ * @see spec/rfcs/RFC-0028-engineering-axis-substrate-enforcement.md §7.2
+ * @module substrate/drift-tui-surface
+ */
+import { correlateDriftBySoul } from './drift-composition.js';
+function toRow(event) {
+    return {
+        soulId: event.soulId,
+        driftClass: event.driftClass,
+        disposition: event.driftClass === 'structural' ? 'BLOCKS' : 'surface',
+        severity: event.severity,
+        summary: event.summary,
+    };
+}
+/**
+ * Build the structured panel model from composed drift events. Souls appear
+ * in first-seen order; within each soul, structural rows precede statistical
+ * rows (hard gate first, then advisory).
+ */
+export function buildDriftPanelModel(events) {
+    const bySoul = correlateDriftBySoul(events);
+    const groups = [];
+    let structuralCount = 0;
+    let statisticalCount = 0;
+    let hasBlocking = false;
+    for (const [soulId, soulEvents] of bySoul) {
+        const structural = [];
+        const statistical = [];
+        for (const evt of soulEvents) {
+            const row = toRow(evt);
+            if (evt.driftClass === 'structural') {
+                structural.push(row);
+                structuralCount += 1;
+                hasBlocking = true;
+            }
+            else {
+                statistical.push(row);
+                statisticalCount += 1;
+            }
+        }
+        groups.push({ soulId, structural, statistical });
+    }
+    return { groups, structuralCount, statisticalCount, hasBlocking };
+}
+/**
+ * Render the drift panel as a plain-text section for the RFC-0023 TUI.
+ *
+ * Produces a per-soul block with structural drift (rejected at CI, hard gate)
+ * and statistical drift (surfaced for operator review, non-blocking) shown
+ * side-by-side under each Soul DID. Empty input renders a single "no drift"
+ * line so the panel never collapses to nothing.
+ */
+export function renderDriftPanel(events) {
+    const model = buildDriftPanelModel(events);
+    const lines = [];
+    lines.push('Substrate Drift — structural (CI hard gate) + statistical (runtime, G0)');
+    lines.push(`  ${model.structuralCount} structural (blocking) · ${model.statisticalCount} statistical (advisory)`);
+    if (model.groups.length === 0) {
+        lines.push('  (no drift events)');
+        return lines.join('\n');
+    }
+    for (const group of model.groups) {
+        lines.push('');
+        lines.push(`Soul: ${group.soulId}`);
+        lines.push('  Structural (REJECTS deployment):');
+        if (group.structural.length === 0) {
+            lines.push('    (none)');
+        }
+        else {
+            for (const row of group.structural) {
+                lines.push(`    [BLOCKS · ${row.severity}] ${row.summary}`);
+            }
+        }
+        lines.push('  Statistical (surfaces to operator — non-blocking):');
+        if (group.statistical.length === 0) {
+            lines.push('    (none)');
+        }
+        else {
+            for (const row of group.statistical) {
+                lines.push(`    [surface · ${row.severity}] ${row.summary}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=drift-tui-surface.js.map

package/dist/substrate/identity-class.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Canonical `identityClass` taxonomy for Substrate Contract fields.
+ *
+ * Phase 1 of RFC-0028 §7.1 v0.2 resolution. Defines the framework-level
+ * taxonomy `core | evolving` together with bucket assignments, a novel-field
+ * default helper (conservative `core`), and the type-level tightening-only
+ * primitives used by Substrate Contract authors.
+ *
+ * Harmonizes with the already-shipped `'core' | 'evolving'` discriminant in
+ * `orchestrator/src/sa-scoring/layer1-deterministic.ts` — see
+ * {@link auditLayer1DeterministicClassifications} for the cross-check and
+ * {@link IdentityClassDiscrepancy} for the discrepancy shape filed against the
+ * Decision Catalog.
+ *
+ * @see spec/rfcs/RFC-0028-engineering-axis-substrate-enforcement.md §6, §7.1
+ */
+/**
+ * The canonical two-bucket taxonomy. Soul-DID-level identity vs operational
+ * tuning surface. Wider RFC-0028 §7.1 rationale: `core` changes are Soul
+ * pivots (full re-scoring fires); `evolving` changes are normal evolution
+ * (admission-queue re-scoring only).
+ */
+export type IdentityClass = 'core' | 'evolving';
+/** Runtime-enumerable list of every taxonomy bucket. */
+export declare const IDENTITY_CLASSES: readonly IdentityClass[];
+/**
+ * Substrate Contract field names that are CANONICAL `core` per RFC-0028 §7.1.
+ *
+ * Child Soul DIDs CANNOT loosen any value declared on these fields. A pivot
+ * rescoring fires whenever any of these fields change.
+ */
+export declare const CORE_BUCKET: {
+    /** Categorical compliance locks — `boolean` locks typed as `true` literal when locked. */
+    readonly categoricalComplianceLocks: readonly ["requiresTenantPhysicalIsolation", "requiresVulnerableAudienceLockout"];
+    /** Compliance regime declarations — categorical, tightening-only. */
+    readonly complianceRegimeDeclarations: readonly ["HIPAA", "PCI-DSS", "SOC2", "FedRAMP", "GDPR"];
+    /** Director / orchestrator agent identifier — changing the director IS a Soul-level event. */
+    readonly directorIdentifiers: readonly ["director", "orchestratorAgentId"];
+    /** §6 tightening-only `complianceFloor: inherit` lock. */
+    readonly complianceFloorLock: readonly ["complianceFloor"];
+};
+/**
+ * Substrate Contract field names that are CANONICAL `evolving` per RFC-0028 §7.1.
+ *
+ * Free movement within tightening-only bounds (a `cadence` may shorten but
+ * not lengthen past the parent; a similarity threshold may tighten but not
+ * loosen). Admission-queue rescoring only — no Soul pivot.
+ */
+export declare const EVOLVING_BUCKET: {
+    /** Operational cadence — observer cooldown / cadence minimum interval. */
+    readonly operationalCadence: readonly ["observerCooldownMs", "cadenceMinIntervalDays"];
+    /** Scoring tuning weights — bid diversity weight, recency half-life. */
+    readonly scoringTuningWeights: readonly ["bidDiversityWeight", "recencyHalfLife"];
+    /** Similarity thresholds — `clustering.similarityThreshold`. */
+    readonly similarityThresholds: readonly ["clustering.similarityThreshold"];
+    /** Quota quantities — `tenantQuotaShare`. */
+    readonly quotaQuantities: readonly ["tenantQuotaShare"];
+};
+/**
+ * Reverse-lookup table: field name → canonical `IdentityClass`.
+ * Built from {@link CORE_BUCKET} + {@link EVOLVING_BUCKET}. Fields not listed
+ * here are NOVEL and resolve via {@link defaultIdentityClassForNovelField}.
+ */
+export declare const CANONICAL_FIELD_CLASSIFICATIONS: Readonly<Record<string, IdentityClass>>;
+/** Optional warning hook invoked when {@link defaultIdentityClassForNovelField} fires. */
+export type NovelFieldWarningHook = (fieldName: string, defaultedTo: IdentityClass) => void;
+/**
+ * Resolve the canonical `IdentityClass` for a Substrate Contract field.
+ *
+ * - Listed in {@link CANONICAL_FIELD_CLASSIFICATIONS} → returns that bucket.
+ * - Otherwise NOVEL → returns `'core'` (per RFC-0028 §7.1 v0.2 conservative
+ *   default; promotion to `evolving` needs an RFC amendment with Design +
+ *   Engineering sign-off — burden-of-proof is "argue why operational").
+ *
+ * When defaulting fires AND a `warn` hook is supplied, the hook is invoked
+ * synchronously so contract authors get a visible signal that a field has
+ * not yet been classified canonically.
+ */
+export declare function defaultIdentityClassForNovelField(fieldName: string, options?: {
+    warn?: NovelFieldWarningHook;
+}): IdentityClass;
+/**
+ * A boolean compliance lock that is LOCKED. Typed as the `true` literal so
+ * any attempt to assign `false` (loosening) fails at compile time.
+ *
+ * @example
+ * ```ts
+ * const lock: LockedBoolean = true; // ok
+ * const lock: LockedBoolean = false; // type error
+ * ```
+ */
+export type LockedBoolean = true;
+/**
+ * A numeric cap that may only DECREASE. The discriminant `kind` field
+ * narrows the union; consumers may attempt to inherit + tighten by passing a
+ * smaller `max` value. The child-tightens-parent constraint is enforced via
+ * the {@link assertTightenedCap} helper at authoring time.
+ *
+ * Implementation note: TypeScript's structural type system cannot enforce
+ * "must be ≤ parent" at the type-level for arbitrary numeric values (that
+ * requires dependent types). The bounded discriminated union ensures
+ * authors must DECLARE intent (`tightened` vs `inherited`); the assertion
+ * helper catches loosening at runtime/authoring time.
+ */
+export type BoundedNumericCap = {
+    kind: 'inherited';
+    max: number;
+} | {
+    kind: 'tightened';
+    max: number;
+    previousMax: number;
+};
+/** Run-time assertion that a {@link BoundedNumericCap} tightening is valid. */
+export declare function assertTightenedCap(cap: BoundedNumericCap): void;
+/**
+ * Categorical inheritance via TypeScript template-literal types. The child
+ * Soul DID's value MUST be a string that is provably a subset of the parent
+ * (encoded as a literal-string union). At the type system level, any value
+ * outside that union fails compile-time inference.
+ *
+ * @example
+ * ```ts
+ * type ParentRegime = 'HIPAA' | 'PCI-DSS' | 'SOC2' | 'FedRAMP' | 'GDPR';
+ * type ChildRegime = TightenedCategorical<ParentRegime, 'HIPAA' | 'SOC2'>;
+ * // ChildRegime = 'HIPAA' | 'SOC2' — strictly tightened subset
+ * ```
+ */
+export type TightenedCategorical<Parent extends string, Child extends Parent> = Child;
+/**
+ * A single shipped-code identityClass usage that disagrees with the
+ * canonical taxonomy. Surfaced via {@link auditLayer1DeterministicClassifications}.
+ */
+export interface IdentityClassDiscrepancy {
+    /** Source file (repo-relative path). */
+    file: string;
+    /** Symbol or call-site label (e.g. function or interface name + line context). */
+    symbol: string;
+    /** Field / discriminant the classification applies to. */
+    field: string;
+    /** Value observed in the shipped code. */
+    observed: IdentityClass;
+    /** Value the canonical taxonomy prescribes. */
+    canonical: IdentityClass;
+    /** Operator-facing rationale describing why this is flagged. */
+    rationale: string;
+}
+/**
+ * Audit the shipped `orchestrator/src/sa-scoring/layer1-deterministic.ts`
+ * (and its compiler `did-compiler.ts`) identityClass classifications against
+ * the canonical RFC-0028 §7.1 taxonomy.
+ *
+ * RFC-0028 §7.1 canonical taxonomy classifies *Substrate Contract* fields.
+ * `layer1-deterministic.ts` applies the same `'core' | 'evolving'`
+ * discriminant to *DID scoring entries* (scope-gate terms, constraint rules,
+ * anti-patterns, measurable signals). The discriminant is reused across two
+ * layers; the taxonomy was only formally defined for the substrate layer.
+ *
+ * The defensible cross-layer discrepancy is the **default fallback**: the
+ * shipped `ic()` helper in `did-compiler.ts` returns `'evolving'` for fields
+ * with no explicit classification, but the canonical taxonomy says novel
+ * fields default to `'core'`. This is filed as a Decision rather than
+ * inline-resolved because the DID-scoring domain may legitimately prefer
+ * a different default than the substrate-contract domain — operator
+ * routing required.
+ *
+ * Returns the list of discrepancies (may be empty). Callers are responsible
+ * for piping each into `cli-decisions add --scope ... --option ...`.
+ */
+export declare function auditLayer1DeterministicClassifications(options?: {
+    readFile?: (path: string) => string;
+}): IdentityClassDiscrepancy[];
+/** Thrown by {@link assertTightenedCap} when a child loosens a numeric cap. */
+export declare class IdentityClassError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=identity-class.d.ts.map