@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/sa-scoring/revision-proposal.d.ts

@@ -0,0 +1,285 @@
+/**
+ * DIDRevisionProposal mechanism (RFC-0031).
+ *
+ * Implements the calibration-driven proposal mechanism that fires when the
+ * PPA flywheel accumulates sufficient evidence that a DID field has drifted
+ * from observed reality.
+ *
+ * What ships here:
+ *   - DIDRevisionProposal event shape + classification logic (§3, §5)
+ *   - SoulHealthDiagnostic event for unhealthy-drift path (§7)
+ *   - Approval routing by identityClass (§8)
+ *   - 14-day expiry + DIDRevisionProposalExpired event (§9)
+ *   - lockNoProposal opt-out per field from calibration config (OQ-12.3)
+ *   - Rejection learnings flowing back into the calibration log (OQ-12.5)
+ *   - Multi-field bundling explicitly deferred to v2 (OQ-12.2)
+ *   - Confidence derived from sample size + classification clarity + identityClass (OQ-12.1)
+ *   - PPA generates proposal regardless of pillar; pillar lead approves (OQ-12.4)
+ *
+ * Trigger entry point: `evaluateRevisionProposal()` — called after drift
+ * is detected (i.e., a `SoulDriftDetected` event fires). One call per
+ * field; bundling is v2.
+ *
+ * Scope: Shard-DID only. Platform-level DID changes are human-initiated.
+ */
+import { type ResolvedRevisionProposalCalibrationConfig } from './revision-proposal-config.js';
+export type { ResolvedRevisionProposalCalibrationConfig };
+export { type RevisionProposalCalibrationConfig, type ConfidenceThresholdsConfig, type RejectionPrecedentConfig, type RejectionPrecedentWeightsConfig, type ConfigValidationResult, type ConfigValidationError, DEFAULT_CONFIDENCE_HIGH_SAMPLE_SIZE, DEFAULT_CONFIDENCE_LOW_SAMPLE_SIZE, DEFAULT_REJECTION_WEIGHT_HIGH, DEFAULT_REJECTION_WEIGHT_MEDIUM, DEFAULT_REJECTION_WEIGHT_LOW, DEFAULT_CONFIDENCE_PENALTY_FLOOR, DEFAULT_RESOLVED_CALIBRATION_CONFIG, validateRevisionProposalCalibrationConfig, resolveRevisionProposalCalibrationConfig, parseRevisionProposalCalibrationYaml, } from './revision-proposal-config.js';
+/** Default trigger thresholds (§6). Configurable per deployment. */
+export declare const DEFAULT_DISMISS_THRESHOLD = 10;
+export declare const DEFAULT_DEMAND_MISALIGNMENT_THRESHOLD = 0.3;
+export declare const DEFAULT_DRIFT_EVENTS_THRESHOLD = 3;
+export declare const DEFAULT_TRIGGER_WINDOW_DAYS = 60;
+export declare const DEFAULT_PROPOSAL_EXPIRY_DAYS = 14;
+/** Classification thresholds per §7. */
+export declare const HEALTHY_ICP_MATCH_MIN = 0.6;
+export declare const UNHEALTHY_ICP_MATCH_MAX = 0.3;
+export type DriftClassification = 'healthy' | 'unhealthy' | 'ambiguous';
+export type IdentityClass = 'core' | 'evolving';
+export type ApprovalPath = 'triad' | 'pillarLead';
+export type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+export type ProposalConfidence = 'high' | 'medium' | 'low';
+export interface ClassificationEvidence {
+    /** [0,1]; high = healthy signal source (ICP-matched demand clusters). */
+    demandClusterICPMatchRate: number;
+    /** [0,1]; high = validated loss signal (churn-correlated demand). */
+    demandClusterChurnCorrelation: number;
+    /** High dismiss + low escalate = DID is stale (healthy evolution). */
+    dismissToEscalateRatio: number;
+    /** True = core identity field affected; more caution warranted. */
+    coreDIDFieldsAffected: boolean;
+}
+export interface TriggerEvidence {
+    /** Dismiss-signal count over the trigger window. */
+    dismissSignals: number;
+    escalateSignals: number;
+    /** SA gap between demand clusters and DID field (0=aligned, 1=fully misaligned). */
+    demandMisalignment: number;
+    /** SoulDriftDetected events attributable to this field. */
+    driftEvents: number;
+    /** ISO-8601 duration string for the evaluation window, e.g. "P60D". */
+    triggerWindow: string;
+}
+export interface DIDRevisionProposalEvent {
+    type: 'DIDRevisionProposal';
+    proposalId: string;
+    /** MUST be 'shard' — platform proposals are not generated. */
+    scope: 'shard';
+    shardId: string;
+    field: string;
+    currentValue: unknown;
+    proposedValue: unknown;
+    identityClass: IdentityClass | undefined;
+    classification: DriftClassification;
+    classificationEvidence: ClassificationEvidence;
+    triggerEvidence: TriggerEvidence;
+    confidence: ProposalConfidence;
+    approvalPath: ApprovalPath;
+    expiresAt: string;
+    createdAt: string;
+    /** Current lifecycle status. */
+    status: ProposalStatus;
+}
+/** Emitted on unhealthy drift (§7) instead of a DIDRevisionProposalEvent. */
+export interface SoulHealthDiagnosticEvent {
+    type: 'SoulHealthDiagnostic';
+    proposalId: string;
+    shardId: string;
+    field: string;
+    classification: 'unhealthy';
+    classificationEvidence: ClassificationEvidence;
+    triggerEvidence: TriggerEvidence;
+    /** Recommendation for unhealthy drift — tighten admission or review demand source. */
+    recommendation: 'tighten-admission-threshold' | 'review-demand-source';
+    createdAt: string;
+}
+/** Emitted by `archiveExpiredProposals()` for each expired proposal. */
+export interface DIDRevisionProposalExpiredEvent {
+    type: 'DIDRevisionProposalExpired';
+    proposalId: string;
+    shardId: string;
+    field: string;
+    classification: DriftClassification;
+    createdAt: string;
+    expiredAt: string;
+}
+/** Emitted when a proposal is rejected; flows back into the calibration log. */
+export interface ProposalRejectionRecord {
+    proposalId: string;
+    shardId: string;
+    field: string;
+    rejectedBy: string;
+    rationale: string;
+    rejectedAt: string;
+    classification: DriftClassification;
+    /** Confidence weight carried forward into future trigger evaluations. */
+    rejectionPrecedentWeight: number;
+}
+/**
+ * Classify drift as healthy / unhealthy / ambiguous per RFC-0031 §7.
+ *
+ * ```
+ * healthy:    icpMatchRate > 0.6  AND NOT coreDIDFieldsAffected
+ * unhealthy:  icpMatchRate < 0.3  OR (coreDIDFieldsAffected AND dismissToEscalateRatio < 1.0)
+ * ambiguous:  everything else
+ * ```
+ */
+export declare function classifyDrift(evidence: ClassificationEvidence): DriftClassification;
+/**
+ * Derive approval path from identityClass per RFC-0031 §8.
+ *
+ * - `core` → `triad` (all three pillar leads required)
+ * - `evolving` → `pillarLead` (owning lead + one other)
+ * - `undefined` → `triad` (default-tighten when class is undeclared)
+ * - ambiguous classification always → `triad` (§7 override)
+ */
+export declare function deriveApprovalPath(identityClass: IdentityClass | undefined, classification: DriftClassification): ApprovalPath;
+/**
+ * Compute proposal confidence from trigger evidence + classification clarity
+ * + identityClass (OQ-12.1 resolved position: confidence = f(sample size,
+ * classification clarity, identityClass)).
+ *
+ * Thresholds are per-org configurable via `.ai-sdlc/calibration.yaml`
+ * (Refit AISDLC-310). Defaults match the shipped AISDLC-271 values:
+ *
+ * - high:   sampleSize ≥ highSampleSize (default 20) AND classification != 'ambiguous' AND identityClass = 'evolving'
+ * - low:    sampleSize < lowSampleSize  (default 5)  OR classification = 'ambiguous'   OR identityClass = 'core'
+ * - medium: everything else
+ *
+ * @param calibrationConfig Optional resolved config from `parseRevisionProposalCalibrationYaml()`.
+ *   When omitted, shipped defaults (20 / 5) are used.
+ */
+export declare function computeConfidence(triggerEvidence: TriggerEvidence, classification: DriftClassification, identityClass: IdentityClass | undefined, calibrationConfig?: ResolvedRevisionProposalCalibrationConfig): ProposalConfidence;
+export interface TriggerConditions {
+    /** Dismiss-signal count over the last `triggerWindowDays`. */
+    dismissSignals: number;
+    escalateSignals: number;
+    /** SA gap between demand clusters and DID field — sustained over 3 sprints. */
+    demandMisalignment: number;
+    /** SoulDriftDetected events attributable to this field (indefinite window). */
+    driftEvents: number;
+}
+export interface TriggerConfig {
+    dismissThreshold?: number;
+    demandMisalignmentThreshold?: number;
+    driftEventsThreshold?: number;
+    triggerWindowDays?: number;
+}
+/**
+ * Returns true if ANY trigger condition fires per RFC-0031 §6.
+ */
+export declare function triggerConditionMet(conditions: TriggerConditions, config?: TriggerConfig): boolean;
+export interface CalibrationLockConfig {
+    /** List of JSON-path field identifiers that should never receive auto-proposals. */
+    lockNoProposal?: string[];
+}
+/**
+ * Returns true if the given field is locked from auto-proposals per OQ-12.3.
+ *
+ * Proposal generation SKIPS locked fields. Operators remove entries from
+ * `lockNoProposal` to opt back in.
+ */
+export declare function isFieldLocked(field: string, lockConfig: CalibrationLockConfig): boolean;
+export interface EvaluateRevisionProposalInput {
+    shardId: string;
+    /** JSON path for the DID field being evaluated, e.g. "soulPurpose.mission". */
+    field: string;
+    currentValue: unknown;
+    /** PPA's best inferred proposed value based on flywheel evidence. */
+    proposedValue: unknown;
+    identityClass: IdentityClass | undefined;
+    triggerConditions: TriggerConditions;
+    classificationEvidence: ClassificationEvidence;
+    lockConfig?: CalibrationLockConfig;
+    config?: TriggerConfig & {
+        expiryDays?: number;
+    };
+    /**
+     * Per-org calibration config loaded from `.ai-sdlc/calibration.yaml`.
+     * When omitted, shipped AISDLC-271 defaults are used for confidence
+     * thresholds (Refit AISDLC-310 / RFC-0031 §12.6).
+     */
+    calibrationConfig?: ResolvedRevisionProposalCalibrationConfig;
+    /** Clock injection for tests. */
+    now?: () => number;
+}
+export type EvaluateRevisionProposalResult = {
+    kind: 'proposal';
+    event: DIDRevisionProposalEvent;
+} | {
+    kind: 'diagnostic';
+    event: SoulHealthDiagnosticEvent;
+} | {
+    kind: 'ambiguous';
+    proposal: DIDRevisionProposalEvent;
+    diagnostic: SoulHealthDiagnosticEvent;
+} | {
+    kind: 'skipped';
+    reason: 'locked' | 'no-trigger';
+};
+/**
+ * Evaluate whether a DIDRevisionProposal should be generated for a given
+ * DID field. Entry point called once per field (one-field-per-proposal in
+ * v1 per OQ-12.2).
+ *
+ * Returns a discriminated union describing what was produced:
+ * - `proposal`   — healthy drift; one DIDRevisionProposalEvent
+ * - `diagnostic` — unhealthy drift; one SoulHealthDiagnosticEvent
+ * - `ambiguous`  — both events produced, both flagged for triad review
+ * - `skipped`    — field is locked or trigger conditions not met
+ */
+export declare function evaluateRevisionProposal(input: EvaluateRevisionProposalInput): EvaluateRevisionProposalResult;
+/**
+ * Check whether a proposal has passed its `expiresAt` timestamp.
+ *
+ * AISDLC-271 PR #476 round-2: validates expiresAt is parseable. Pre-fix
+ * a malformed (or attacker-mutated) expiresAt would silently NEVER
+ * expire because Date.parse returns NaN and `NaN <= now` is always false.
+ */
+export declare function isProposalExpired(proposal: DIDRevisionProposalEvent, nowMs?: number): boolean;
+/**
+ * Archive expired proposals and emit `DIDRevisionProposalExpired` events.
+ * Returns the list of expiry events for caller to process (persist / alert).
+ *
+ * Per §9: expiry without resolution emits the event — operator alert, not
+ * silent dismissal. Auto-archives by setting status to 'expired'.
+ */
+export declare function archiveExpiredProposals(proposals: DIDRevisionProposalEvent[], nowMs?: number): {
+    expired: DIDRevisionProposalExpiredEvent[];
+    remaining: DIDRevisionProposalEvent[];
+};
+/**
+ * Record a proposal rejection and compute the `rejectionPrecedentWeight`
+ * to feed back into future trigger evaluations (OQ-12.5 resolved position:
+ * rejection rationale captured in calibration log; future trigger evaluations
+ * weight rejection-precedent into confidence).
+ *
+ * Weight formula (defaults from AISDLC-271, per-org configurable via
+ * `calibration.yaml` — Refit AISDLC-310 / RFC-0031 §12.6):
+ *   - high-confidence proposals that were rejected → 0.8 (default)
+ *   - medium-confidence → 0.5 (default)
+ *   - low-confidence → 0.2 default (expected noise level, lower weight)
+ *
+ * Callers persist this record to their calibration log; the next trigger
+ * evaluation should factor it in by reducing effective confidence.
+ *
+ * @param calibrationConfig Optional resolved config from `parseRevisionProposalCalibrationYaml()`.
+ *   When omitted, shipped AISDLC-271 weights (0.8 / 0.5 / 0.2) are used.
+ */
+export declare function recordRejection(proposal: DIDRevisionProposalEvent, rejectedBy: string, rationale: string, now?: () => number, calibrationConfig?: ResolvedRevisionProposalCalibrationConfig): ProposalRejectionRecord;
+/**
+ * Apply rejection precedent to reduce effective trigger confidence.
+ * When a field has prior rejection records, the aggregated precedent
+ * weight penalises future proposals for the same field.
+ *
+ * Formula (RFC-0031 §12.6): `factor = max(floor, 1.0 - avgWeight × 0.5)`
+ * where `floor` is `confidencePenaltyFloor` from calibration config
+ * (default 0.2 — at most 80% suppression).
+ *
+ * Returns a factor in `[floor, 1.0]`. Callers decide how to interpret.
+ *
+ * @param calibrationConfig Optional resolved config from `parseRevisionProposalCalibrationYaml()`.
+ *   When omitted, shipped AISDLC-271 floor (0.2) is used.
+ */
+export declare function computeRejectionPrecedentFactor(field: string, rejections: readonly ProposalRejectionRecord[], calibrationConfig?: ResolvedRevisionProposalCalibrationConfig): number;
+//# sourceMappingURL=revision-proposal.d.ts.map