instar 1.3.1647 → 1.3.1649

package/dist/monitoring/MaturationLadder.d.ts

@@ -0,0 +1,214 @@
+/**
+ * MaturationLadder — the pure core of the measured path to default-on.
+ *
+ * Spec: docs/specs/feature-maturation-ladder.md (Justin, topic 136110, 2026-11-03).
+ *
+ * This module parses the registry (src/data/feature-ladders.json), derives each
+ * feature's rung from what the code actually ships, turns the next rung into a
+ * D7 contract, and reduces D7's rows to one plain state. It reads no files,
+ * calls nothing and decides nothing: D7 stays the only thing that says `ready`,
+ * and the review job's model stays the only thing that decides a move.
+ */
+import type { MaturationEvaluationContract } from '../core/InitiativeTracker.js';
+export declare const LADDERS_SCHEMA = "feature-ladders/1";
+export declare const LADDER_RESPONSE_SCHEMA = "maturation-ladder/1";
+/** Observed rungs. `dark` is "nobody runs it"; no test-agent role exists to observe yet. */
+export declare const OBSERVED_RUNGS: readonly ['dark', 'dry-run', 'dev-agent-live', 'fleet'];
+export type ObservedRung = typeof OBSERVED_RUNGS[number];
+/** Rungs a feature can be asked to earn. */
+export type TargetRung = 'dev-agent-live' | 'fleet';
+export type MetricRole = 'ran' | 'quality' | 'harm';
+export type MetricSource = 'jsonl-log' | 'feature-metrics' | 'guard-posture' | 'feature-summary';
+export type MetricDirection = 'at-least' | 'at-most';
+export interface JsonlLogRef {
+    file: string;
+    where?: Record<string, string | number | boolean>;
+    of?: Record<string, string | number | boolean>;
+    value: 'count' | 'ratio';
+    timeField?: string;
+    /** Keep only the last row per this field's value, so a re-graded event counts once. */
+    dedupe?: string;
+}
+export interface FeatureMetricsRef {
+    feature: string;
+    field: 'errorRate' | 'fireRate' | 'realLlmCalls';
+}
+export interface GuardPostureRef {
+    key: string;
+}
+export interface FeatureSummaryRef {
+    ref: string;
+}
+export interface LadderMetric {
+    id: string;
+    role: MetricRole;
+    source: MetricSource;
+    ref: JsonlLogRef | FeatureMetricsRef | GuardPostureRef | FeatureSummaryRef;
+    direction: MetricDirection;
+    threshold: number;
+    minSamples: number;
+    windowDays: number;
+}
+export type RungAdvance = {
+    kind: 'config';
+    set: Record<string, string | number | boolean>;
+} | {
+    kind: 'owner-driver';
+    driver: string;
+} | {
+    kind: 'code';
+};
+export interface LadderRung {
+    soakDays: number;
+    advance: RungAdvance;
+    metrics: LadderMetric[];
+}
+export interface LadderPreference {
+    decidedBy: string;
+    reason: string;
+    decidedAt: string;
+    ref: string;
+}
+export interface LadderEntry {
+    id: string;
+    title: string;
+    aliases: string[];
+    /** D7 feature id. The spec-born initiative's id when one exists; else derived from `id`. */
+    subject: string;
+    /**
+     * `on`: the value meaning fully live, default `enabled: true`.
+     * `dryRunPath`: where its dry-run lives when not `<path>.dryRun`.
+     * `dryRunDefault`: the code treats an absent dry-run as on, with no shipped key to read.
+     */
+    flag: {
+        path: string;
+        on?: string | boolean;
+        dryRunPath?: string;
+        dryRunDefault?: boolean;
+    } | null;
+    disposition: 'ladder' | 'composed' | 'retire';
+    composedInto?: string;
+    retire?: {
+        reason: string;
+        ref: string;
+    };
+    final: 'default-on' | 'default-off-by-preference';
+    preference?: LadderPreference;
+    risk: 'standard' | 'sensitive';
+    /** Fires only on incidents, so idle is healthy: `no-opportunity`, not `no-data`. */
+    rare?: boolean;
+    /** How to start it safely when nothing runs it yet: a setting under its flag, normally a dry-run. */
+    start?: {
+        set: Record<string, string | number | boolean>;
+    };
+    /** The setting is read at boot, so a move needs a restart to take effect. */
+    restartNeeded?: boolean;
+    tracking: {
+        state: 'measured' | 'needed';
+        plan: string;
+    };
+    rungs: Partial<Record<TargetRung, LadderRung>>;
+}
+export interface LadderRegistry {
+    schema: typeof LADDERS_SCHEMA;
+    entries: LadderEntry[];
+}
+export type LadderParseResult = {
+    ok: true;
+    registry: LadderRegistry;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Evidence files may only live in an agent's log or state folders, and only as
+ * JSONL. Registry entries are reviewed code, so this is a second lock rather
+ * than the first: a typo must not reach a credential file.
+ */
+export declare const EVIDENCE_FILE_RE: RegExp;
+export declare function isEvidenceFileAllowed(file: string): boolean;
+/** D7 only accepts kebab ids, and flag paths are dotted. */
+export declare function subjectFromId(id: string): string;
+/** Validate the registry. A bad file is refused whole, naming the failing field. */
+export declare function parseLadderRegistry(text: string): LadderParseResult;
+/**
+ * The rung comes from what is shipped and what runs here, never from a label.
+ * The shipped default alone decides `fleet`; a shipped dry-run is not fleet.
+ */
+export declare function deriveLadderRung(entry: LadderEntry, liveConfig: unknown, shippedDefaults: unknown): {
+    rung: ObservedRung;
+    flagMissing: boolean;
+};
+export declare function nextRung(entry: LadderEntry, rung: ObservedRung): TargetRung | null;
+/** The rung just below `target`, whose bar a feature already crossed. */
+export declare function crossedRung(entry: LadderEntry, rung: ObservedRung): LadderRung | null;
+/** D7's contract for the rung this feature is working toward. Same scorer, more subjects. */
+export declare function contractForRung(rung: LadderRung): MaturationEvaluationContract;
+/** Stable D7 source ref for a ladder metric. `feature-summary` keeps its own ref. */
+export declare function projectionRef(m: LadderMetric): string;
+export type LadderState = 'retire-pending' | 'composed' | 'held' | 'harmed' | 'at-final' | 'not-started' | 'no-opportunity' | 'no-data' | 'hold' | 'collecting' | 'soaking' | 'ready-to-advance';
+export interface MetricReading {
+    metric: LadderMetric;
+    value: number | null;
+    samples: number;
+    /** Newest matching row, when known. */
+    newestAt: number | null;
+    /** Days of the window the log actually covers, when rotation may have cut it. */
+    coverageDays?: number;
+    /** Why no number exists (a read failed, the file is too big, or the data was cut). */
+    reason?: string;
+}
+export interface EvaluationRow {
+    status: string;
+    dueSlotMs: number;
+    contractHash: string;
+}
+export interface LadderStateInput {
+    entry: LadderEntry;
+    rung: ObservedRung;
+    target: TargetRung | null;
+    /** Readings for the next rung's metrics. */
+    readings: MetricReading[];
+    /** Readings for the crossed rung's `harm` and `ran` metrics, windowed from the move. */
+    afterMove: MetricReading[];
+    /** D7 rows for this subject, any order. */
+    evaluations: EvaluationRow[];
+    contractHash: string | null;
+    now: number;
+    /** When a move for this feature was last applied here, if any. */
+    lastMoveAt: number | null;
+    /** This agent's operator holds it, with a reason. */
+    heldReason: string | null;
+}
+export interface MetricView {
+    id: string;
+    role: MetricRole;
+    direction: MetricDirection;
+    threshold: number;
+    minSamples: number;
+    value: number | null;
+    samples: number;
+    pass: boolean | null;
+    coverageDays?: number;
+    reason?: string;
+}
+export interface LadderStateResult {
+    state: LadderState;
+    /** Why, in a word or two, when the state alone does not say. */
+    because?: string;
+    soak: {
+        days: number;
+        needed: number;
+    };
+    metrics: MetricView[];
+    passing: number;
+    total: number;
+}
+export declare function raiseDue(state: LadderState, lastRaisedAt: number | undefined, now: number): boolean;
+export declare const HARM_WATCH_DAYS = 14;
+export declare const SILENT_AFTER_MOVE_DAYS = 3;
+export declare function metricPasses(direction: MetricDirection, value: number, threshold: number): boolean;
+/** Whole days of unbroken D7 `ready` under this contract. Any other row restarts it. */
+export declare function soakDays(evaluations: EvaluationRow[], contractHash: string | null, now: number): number;
+export declare function computeLadderState(input: LadderStateInput): LadderStateResult;
+//# sourceMappingURL=MaturationLadder.d.ts.map

package/dist/monitoring/MaturationLadder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaturationLadder.d.ts","sourceRoot":"","sources":["../../src/monitoring/MaturationLadder.ts"],"names":[],"mappings":"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"}