instar 1.3.1647 → 1.3.1649

package/dist/monitoring/MaturationLadderService.d.ts

@@ -0,0 +1,189 @@
+/**
+ * MaturationLadderService — measures every ladder and raises what is worth a
+ * decision. It holds no authority to move a feature: the recurring review's
+ * model decides, and POST /maturation/moves only enforces floors in front of
+ * that decision. Spec: docs/specs/feature-maturation-ladder.md §6-§8.
+ */
+import type { Initiative } from '../core/InitiativeTracker.js';
+import { contractForRung, type LadderEntry, type LadderState, type MetricView, type ObservedRung, type TargetRung } from './MaturationLadder.js';
+/** The shipped registry, beside this module's package root. */
+export declare function readShippedRegistry(): string;
+export declare const LADDER_AUDIT_FILE = "logs/maturation-advances.jsonl";
+export declare const MAX_RAISES_PER_PASS = 5;
+export interface MetricsSummaryRow {
+    feature: string;
+    realLlmCalls?: number;
+    errorRate?: number | null;
+    fireRate?: number | null;
+}
+export interface MaturationLadderDeps {
+    projectDir: string;
+    machine: string;
+    now?: () => number;
+    /** The registry text; a test seam. Defaults to the shipped file. */
+    readRegistry: () => string;
+    /** The agent's config, re-read from disk. Null when it cannot be read. */
+    readLiveConfig: () => Record<string, unknown> | null;
+    shippedDefaults: () => unknown;
+    d7: {
+        registerMaturationProjection(ref: string, read: () => {
+            value: number;
+            samples: number;
+        } | null): void;
+        readMaturationProjection(ref: string): {
+            value: number;
+            samples: number;
+        } | null;
+        maturationContractHash(contract: ReturnType<typeof contractForRung>): string;
+        evaluations(sinceMs: number): Array<{
+            featureId: string;
+            status: string;
+            dueSlotMs: number;
+            contractHash: string;
+        }>;
+    } | null;
+    /** Feature-metrics rollups for a window. */
+    featureMetrics: ((sinceHours: number) => MetricsSummaryRow[]) | null;
+    /** Each guard's effective posture. */
+    guardEffective: (() => Map<string, string>) | null;
+    commitments: {
+        record(input: Record<string, unknown>): {
+            id: string;
+        };
+        getActive(): Array<{
+            externalKey?: string;
+            id: string;
+        }>;
+    } | null;
+    /** True on the machine that speaks for this agent (always true when alone). */
+    holdsLease: () => boolean;
+    /** Set only where a review reads what gets raised. */
+    reviewTopic: () => number | null;
+    /** Flags that must match across machines. */
+    isCoherenceCritical: (configPath: string) => boolean;
+    /** Writes one setting. Must persist or fail observably. */
+    setConfig: (dotPath: string, value: unknown) => void;
+    isDevelopmentAgent: () => boolean;
+}
+export interface LadderFeatureView {
+    id: string;
+    subject: string;
+    title: string;
+    aliases: string[];
+    flagPath: string | null;
+    rung: ObservedRung;
+    flagMissing: boolean;
+    next: TargetRung | null;
+    state: LadderState;
+    because?: string;
+    final: LadderEntry['final'];
+    risk: LadderEntry['risk'];
+    rare: boolean;
+    tracking: LadderEntry['tracking'];
+    composedInto?: string;
+    soak: {
+        days: number;
+        needed: number;
+    };
+    metrics: MetricView[];
+    passing: number;
+    total: number;
+    /** What a config move would write, and what is there now. */
+    move: null | {
+        kind: string;
+        set?: Record<string, unknown>;
+        from?: Record<string, unknown>;
+        restartNeeded?: boolean;
+    };
+    lastMove: {
+        moveId: string;
+        at: string;
+        action: string;
+    } | null;
+    stuckDays: number | null;
+    stuck: 'stuck-ready' | 'stuck-blind' | 'stuck-rare' | null;
+}
+export interface LadderCounts {
+    total: number;
+    byState: Record<string, number>;
+    byRung: Record<string, number>;
+    withThresholds: number;
+    trackingNeeded: number;
+    preferenceOff: number;
+    stuckReady: number;
+    stuckBlind: number;
+    stuckRare: number;
+}
+export type MoveRefusal = 'unknown-feature' | 'not-ready' | 'not-a-config-move' | 'sensitive' | 'held' | 'not-a-development-agent' | 'changed-since-read' | 'write-not-verified' | 'not-found' | 'changed-since-move' | 'not-applied';
+export type MoveResult = {
+    ok: true;
+    moveId: string;
+    state: 'applied';
+    old: Record<string, unknown>;
+    set: Record<string, unknown>;
+    restartNeeded?: boolean;
+} | {
+    ok: false;
+    refused: MoveRefusal;
+    detail?: string;
+    moveId?: string;
+};
+interface AuditRow {
+    at: string;
+    action: 'raise' | 'rung-observed' | 'move-intent' | 'move-applied' | 'move-failed' | 'revert-applied' | 'revert-refused';
+    id: string;
+    moveId?: string;
+    [k: string]: unknown;
+}
+export declare class MaturationLadderService {
+    private readonly deps;
+    private registry;
+    private registryError;
+    private readings;
+    private afterMoveReadings;
+    private readonly lastRaisedAt;
+    private readonly lastObservedRung;
+    private readonly lastRungChangeAt;
+    private readonly lastMoves;
+    private viewCache;
+    private lastRefreshAt;
+    private configReadable;
+    private readonly now;
+    private readonly auditPath;
+    constructor(deps: MaturationLadderDeps);
+    private loadRegistry;
+    get error(): string | null;
+    get entries(): LadderEntry[];
+    private loadAudit;
+    private applyAuditRow;
+    private audit;
+    private registerProjections;
+    private rungsOf;
+    /** When this feature's post-move watch began: its last applied move or observed rung change. */
+    private watchStart;
+    /** Read every metric a pass needs. Async and off the event loop; call before D7 scores. */
+    refresh(): Promise<void>;
+    private readInto;
+    /** The scorer's input: its own initiatives, with ladder contracts and in-memory subjects added. */
+    subjects(initiatives: Initiative[]): Initiative[];
+    private heldReason;
+    features(): LadderFeatureView[];
+    counts(features?: LadderFeatureView[]): LadderCounts;
+    response(id?: string): Record<string, unknown>;
+    /** Record what is worth a decision. A record, not a message; the review reads it. */
+    raise(): string[];
+    private readConfigFresh;
+    /** Apply a decision the review's model already made. Every floor here can only refuse. */
+    applyMove(input: {
+        id: string;
+        target: TargetRung;
+        reason: string;
+        from: Record<string, unknown>;
+        opinions: unknown[];
+    }): MoveResult;
+    /** Undo a move, only if what it wrote is still there. A revert also holds the feature, so nothing repeats. */
+    revertMove(moveId: string, reason: string): MoveResult;
+    auditRows(limit: number): AuditRow[];
+}
+export {};
+//# sourceMappingURL=MaturationLadderService.d.ts.map

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

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