@ai-sdlc/orchestrator 0.5.0 → 0.9.0

package/dist/scheduling/calibration.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-stage rolling token-estimate calibration per RFC §14.6 (Q11). Tracks the last 20
+ * invocations per stage with exponentially-weighted average; emits EstimateBootstrapped
+ * after first run replaces the cold-start default; emits EstimateVariance when observed
+ * deviates from estimated by > 50%.
+ */
+import { type LedgerEvent, type TokenEstimate } from './types.js';
+export declare const COLD_START_DEFAULT: TokenEstimate;
+export interface CalibrationStoreDeps {
+    io?: {
+        read: (path: string) => Promise<string | null>;
+        write: (path: string, content: string) => Promise<void>;
+    };
+}
+export declare class CalibrationStore {
+    private state;
+    private readonly path;
+    private readonly io;
+    constructor(artifactsDir: string, deps?: CalibrationStoreDeps);
+    load(): Promise<void>;
+    /**
+     * Resolve the effective estimate for a stage at dispatch time. Frozen declarations
+     * pin the operator value; otherwise rolling supersedes; otherwise declared; otherwise
+     * cold-start default (with a MissingEstimate event for the caller to surface).
+     */
+    resolveEstimate(stage: string, declared: TokenEstimate | undefined): {
+        estimate: TokenEstimate;
+        events: LedgerEvent[];
+    };
+    /**
+     * Record actual consumption after a stage completes. Updates the rolling estimate;
+     * emits EstimateBootstrapped on first replacement of cold-start; emits EstimateVariance
+     * when actuals diverge from the previous declared estimate by > threshold.
+     */
+    record(stage: string, actual: {
+        input: number;
+        output: number;
+    }, declared: TokenEstimate | undefined): Promise<LedgerEvent[]>;
+    getRollingEstimate(stage: string): TokenEstimate | undefined;
+    private persist;
+}
+//# sourceMappingURL=calibration.d.ts.map

package/dist/scheduling/calibration.js

@@ -0,0 +1,150 @@
+/**
+ * Per-stage rolling token-estimate calibration per RFC §14.6 (Q11). Tracks the last 20
+ * invocations per stage with exponentially-weighted average; emits EstimateBootstrapped
+ * after first run replaces the cold-start default; emits EstimateVariance when observed
+ * deviates from estimated by > 50%.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { COLD_START_DEFAULT_INPUT, COLD_START_DEFAULT_OUTPUT, ESTIMATE_VARIANCE_THRESHOLD, ROLLING_WINDOW_SIZE, } from './types.js';
+export const COLD_START_DEFAULT = {
+    input: COLD_START_DEFAULT_INPUT,
+    output: COLD_START_DEFAULT_OUTPUT,
+};
+export class CalibrationStore {
+    state = { version: 1, stages: {} };
+    path;
+    io;
+    constructor(artifactsDir, deps = {}) {
+        this.path = join(artifactsDir, '_ledger', 'stage-estimates.json');
+        this.io = deps.io ?? {
+            read: async (p) => {
+                try {
+                    return await readFile(p, 'utf8');
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT')
+                        return null;
+                    throw err;
+                }
+            },
+            write: async (p, c) => {
+                await mkdir(dirname(p), { recursive: true });
+                await writeFile(p, c, 'utf8');
+            },
+        };
+    }
+    async load() {
+        const raw = await this.io.read(this.path);
+        if (!raw)
+            return;
+        try {
+            this.state = JSON.parse(raw);
+        }
+        catch {
+            // Malformed; reset.
+            this.state = { version: 1, stages: {} };
+        }
+    }
+    /**
+     * Resolve the effective estimate for a stage at dispatch time. Frozen declarations
+     * pin the operator value; otherwise rolling supersedes; otherwise declared; otherwise
+     * cold-start default (with a MissingEstimate event for the caller to surface).
+     */
+    resolveEstimate(stage, declared) {
+        const events = [];
+        if (declared?.frozen) {
+            return { estimate: declared, events };
+        }
+        const history = this.state.stages[stage];
+        if (history?.rollingEstimate) {
+            return { estimate: history.rollingEstimate, events };
+        }
+        if (declared) {
+            return { estimate: declared, events };
+        }
+        events.push({ type: 'MissingEstimate', stage });
+        return { estimate: COLD_START_DEFAULT, events };
+    }
+    /**
+     * Record actual consumption after a stage completes. Updates the rolling estimate;
+     * emits EstimateBootstrapped on first replacement of cold-start; emits EstimateVariance
+     * when actuals diverge from the previous declared estimate by > threshold.
+     */
+    async record(stage, actual, declared) {
+        const events = [];
+        let history = this.state.stages[stage];
+        const isFirstRun = !history || history.samples.length === 0;
+        if (!history) {
+            history = { stage, samples: [] };
+            this.state.stages[stage] = history;
+        }
+        history.samples.push({ ...actual, at: new Date().toISOString() });
+        if (history.samples.length > ROLLING_WINDOW_SIZE) {
+            history.samples.shift();
+        }
+        const newRolling = exponentiallyWeightedAverage(history.samples);
+        const previousRolling = history.rollingEstimate;
+        history.rollingEstimate = newRolling;
+        if (isFirstRun && !declared) {
+            history.bootstrappedAt = new Date().toISOString();
+            events.push({
+                type: 'EstimateBootstrapped',
+                stage,
+                coldStartDefault: COLD_START_DEFAULT,
+                firstRunActual: { input: actual.input, output: actual.output },
+                newRollingEstimate: newRolling,
+            });
+        }
+        if (declared && !declared.frozen) {
+            const declaredTotal = declared.input + declared.output;
+            const actualTotal = actual.input + actual.output;
+            if (declaredTotal > 0) {
+                const ratio = actualTotal / declaredTotal;
+                if (Math.abs(ratio - 1) > ESTIMATE_VARIANCE_THRESHOLD) {
+                    events.push({
+                        type: 'EstimateVariance',
+                        stage,
+                        declared,
+                        observed: { input: actual.input, output: actual.output },
+                        ratio,
+                    });
+                }
+            }
+        }
+        void previousRolling; // reserved for future delta event.
+        await this.persist();
+        return events;
+    }
+    getRollingEstimate(stage) {
+        return this.state.stages[stage]?.rollingEstimate;
+    }
+    async persist() {
+        await this.io.write(this.path, JSON.stringify(this.state));
+    }
+}
+/**
+ * Exponentially-weighted average over the last N samples (newest weighted most).
+ * Decay 0.85 — gentle preference for recent observations without ignoring history.
+ */
+function exponentiallyWeightedAverage(samples) {
+    if (samples.length === 0)
+        return COLD_START_DEFAULT;
+    const decay = 0.85;
+    let sumW = 0;
+    let sumI = 0;
+    let sumO = 0;
+    // Newest sample (last in array) gets weight 1.0; older samples get progressively less.
+    for (let i = samples.length - 1; i >= 0; i--) {
+        const age = samples.length - 1 - i;
+        const w = Math.pow(decay, age);
+        sumW += w;
+        sumI += samples[i].input * w;
+        sumO += samples[i].output * w;
+    }
+    return {
+        input: Math.round(sumI / sumW),
+        output: Math.round(sumO / sumW),
+    };
+}
+//# sourceMappingURL=calibration.js.map

package/dist/scheduling/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export { isOffPeakAt, nextOffPeakStart, ageInDays, freshnessLevel, type FreshnessLevel, } from './off-peak.js';
+export { SubscriptionLedger, validateTenantShares, type LedgerDeps } from './ledger.js';
+export { evaluateSchedule, type ScheduleDecision, type ScheduleEvaluationContext, } from './schedule-decision.js';
+export { CalibrationStore, COLD_START_DEFAULT, type CalibrationStoreDeps } from './calibration.js';
+export { buildBurnDownReport, type BurnDownInput } from './burn-down.js';
+export { analyzeTier, PLAN_COSTS_USD, type Confidence, type ContentionEvent, type TierAnalysisInput, type TierAnalysisResult, } from './tier-analysis.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/scheduling/index.js

@@ -0,0 +1,8 @@
+export * from './types.js';
+export { isOffPeakAt, nextOffPeakStart, ageInDays, freshnessLevel, } from './off-peak.js';
+export { SubscriptionLedger, validateTenantShares } from './ledger.js';
+export { evaluateSchedule, } from './schedule-decision.js';
+export { CalibrationStore, COLD_START_DEFAULT } from './calibration.js';
+export { buildBurnDownReport } from './burn-down.js';
+export { analyzeTier, PLAN_COSTS_USD, } from './tier-analysis.js';
+//# sourceMappingURL=index.js.map

package/dist/scheduling/ledger.d.ts

@@ -0,0 +1,59 @@
+/**
+ * SubscriptionLedger per RFC §14.2 / §14.12. Tracks per-(harness, accountId, tenant)
+ * window state derived from observed token consumption. Persists per-key state to
+ * $ARTIFACTS_DIR/_ledger/<harness>-<accountIdShort>-<tenant>.json so it survives
+ * orchestrator restarts within a window.
+ */
+import { type AdmissionDecision, type LedgerKey, type SubscriptionPlan, type TokenEstimate, type WindowState } from './types.js';
+export interface LedgerDeps {
+    now?: () => Date;
+    /** Override file IO for tests. */
+    io?: {
+        read: (path: string) => Promise<string | null>;
+        write: (path: string, content: string) => Promise<void>;
+    };
+}
+export declare class SubscriptionLedger {
+    private readonly state;
+    private readonly now;
+    private readonly io;
+    private readonly artifactsDir;
+    constructor(artifactsDir: string, deps?: LedgerDeps);
+    static keyToString(key: LedgerKey): string;
+    static keyToFilename(key: LedgerKey): string;
+    private filePathFor;
+    /** Load persisted state for a key (or initialize a fresh window). */
+    load(key: LedgerKey, plan: SubscriptionPlan): Promise<void>;
+    windowState(key: LedgerKey, plan: SubscriptionPlan): WindowState;
+    /**
+     * Decide whether a stage with the given estimated token cost may admit. Off-peak
+     * multiplier reduces the effective cost (2x off-peak → 0.5x quota consumption).
+     */
+    admit(key: LedgerKey, plan: SubscriptionPlan, estimate: TokenEstimate): AdmissionDecision;
+    record(key: LedgerKey, plan: SubscriptionPlan, actualTokens: {
+        input: number;
+        output: number;
+    }): Promise<void>;
+    isOffPeak(plan: SubscriptionPlan, when?: Date): boolean;
+    /** Reset the ledger for a key (used by tests + the LedgerReconciliation flow). */
+    reset(key: LedgerKey): void;
+    private persist;
+}
+/**
+ * Tenant-share validation per RFC §14.12. Returns null if valid; otherwise the failed
+ * (harness, accountId) groups with their share sums. The orchestrator emits
+ * TenantShareInvalid for each failure and refuses to start.
+ */
+export declare function validateTenantShares(pipelines: ReadonlyArray<{
+    name: string;
+    harness: string;
+    accountId: string;
+    tenant?: string;
+    tenantQuotaShare?: number;
+}>, tolerance?: number): Array<{
+    harness: string;
+    accountId: string;
+    sumOfShares: number;
+    pipelines: string[];
+}>;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/scheduling/ledger.js

@@ -0,0 +1,216 @@
+/**
+ * SubscriptionLedger per RFC §14.2 / §14.12. Tracks per-(harness, accountId, tenant)
+ * window state derived from observed token consumption. Persists per-key state to
+ * $ARTIFACTS_DIR/_ledger/<harness>-<accountIdShort>-<tenant>.json so it survives
+ * orchestrator restarts within a window.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { isOffPeakAt } from './off-peak.js';
+import { DEFAULT_TENANT, } from './types.js';
+export class SubscriptionLedger {
+    state = new Map();
+    now;
+    io;
+    artifactsDir;
+    constructor(artifactsDir, deps = {}) {
+        this.artifactsDir = artifactsDir;
+        this.now = deps.now ?? (() => new Date());
+        this.io = deps.io ?? {
+            read: async (p) => {
+                try {
+                    return await readFile(p, 'utf8');
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT')
+                        return null;
+                    throw err;
+                }
+            },
+            write: async (p, c) => {
+                await mkdir(dirname(p), { recursive: true });
+                await writeFile(p, c, 'utf8');
+            },
+        };
+    }
+    static keyToString(key) {
+        return `${key.harness}|${key.accountId}|${key.tenant ?? DEFAULT_TENANT}`;
+    }
+    static keyToFilename(key) {
+        const accountIdShort = key.accountId.slice(0, 8);
+        const tenant = key.tenant ?? DEFAULT_TENANT;
+        return `${key.harness}-${accountIdShort}-${tenant}.json`;
+    }
+    filePathFor(key) {
+        return join(this.artifactsDir, '_ledger', SubscriptionLedger.keyToFilename(key));
+    }
+    /** Load persisted state for a key (or initialize a fresh window). */
+    async load(key, plan) {
+        const path = this.filePathFor(key);
+        const raw = await this.io.read(path);
+        if (raw) {
+            try {
+                const parsed = JSON.parse(raw);
+                const now = this.now();
+                const windowStart = new Date(parsed.windowStart);
+                const windowEnd = computeWindowEnd(windowStart, plan);
+                if (now.getTime() < windowEnd.getTime()) {
+                    this.state.set(SubscriptionLedger.keyToString(key), parsed);
+                    return;
+                }
+                // Window has expired; reset.
+            }
+            catch {
+                // Malformed; reset.
+            }
+        }
+        this.state.set(SubscriptionLedger.keyToString(key), {
+            windowStart: this.now().toISOString(),
+            consumedTokens: 0,
+        });
+        await this.persist(key);
+    }
+    windowState(key, plan) {
+        const persisted = this.state.get(SubscriptionLedger.keyToString(key));
+        if (!persisted)
+            throw new Error(`Ledger not loaded for key: ${SubscriptionLedger.keyToString(key)}`);
+        const windowStart = new Date(persisted.windowStart);
+        const windowEnd = computeWindowEnd(windowStart, plan);
+        const multiplier = plan.offPeak && isOffPeakAt(plan.offPeak, this.now()) ? plan.offPeak.multiplier : 1.0;
+        const quotaTokens = plan.windowQuotaTokens ?? Number.POSITIVE_INFINITY;
+        return {
+            windowStart,
+            windowEnd,
+            consumedTokens: persisted.consumedTokens,
+            quotaTokens,
+            multiplier,
+            utilizationFraction: quotaTokens === Number.POSITIVE_INFINITY ? 0 : persisted.consumedTokens / quotaTokens,
+            pacingTarget: plan.pacingTarget,
+            hardCap: plan.hardCap,
+        };
+    }
+    /**
+     * Decide whether a stage with the given estimated token cost may admit. Off-peak
+     * multiplier reduces the effective cost (2x off-peak → 0.5x quota consumption).
+     */
+    admit(key, plan, estimate) {
+        const ws = this.windowState(key, plan);
+        if (plan.billingMode === 'pay-per-token' || ws.quotaTokens === Number.POSITIVE_INFINITY) {
+            return { kind: 'yes', reason: 'pay-per-token plan; no quota' };
+        }
+        const totalEstimate = (estimate.input + estimate.output) / ws.multiplier;
+        const wouldConsume = ws.consumedTokens + totalEstimate;
+        const projectedFraction = wouldConsume / ws.quotaTokens;
+        if (projectedFraction <= plan.hardCap) {
+            return {
+                kind: 'yes',
+                reason: `under hardCap (${projectedFraction.toFixed(3)} ≤ ${plan.hardCap})`,
+            };
+        }
+        return {
+            kind: 'no',
+            reason: `would exceed hardCap (${projectedFraction.toFixed(3)} > ${plan.hardCap})`,
+            blockedBy: 'hardCap',
+        };
+    }
+    async record(key, plan, actualTokens) {
+        const persisted = this.state.get(SubscriptionLedger.keyToString(key));
+        if (!persisted)
+            throw new Error(`Ledger not loaded for key: ${SubscriptionLedger.keyToString(key)}`);
+        const multiplier = plan.offPeak && isOffPeakAt(plan.offPeak, this.now()) ? plan.offPeak.multiplier : 1.0;
+        persisted.consumedTokens += (actualTokens.input + actualTokens.output) / multiplier;
+        await this.persist(key);
+    }
+    isOffPeak(plan, when) {
+        if (!plan.offPeak)
+            return false;
+        return isOffPeakAt(plan.offPeak, when ?? this.now());
+    }
+    /** Reset the ledger for a key (used by tests + the LedgerReconciliation flow). */
+    reset(key) {
+        this.state.set(SubscriptionLedger.keyToString(key), {
+            windowStart: this.now().toISOString(),
+            consumedTokens: 0,
+        });
+    }
+    async persist(key) {
+        const persisted = this.state.get(SubscriptionLedger.keyToString(key));
+        if (!persisted)
+            return;
+        await this.io.write(this.filePathFor(key), JSON.stringify(persisted));
+    }
+}
+function computeWindowEnd(windowStart, plan) {
+    if (plan.billingMode === 'monthly-cap') {
+        // Roll at month boundary.
+        const next = new Date(windowStart);
+        next.setMonth(next.getMonth() + 1);
+        return next;
+    }
+    if (plan.billingMode === 'session-window' && plan.windowDuration) {
+        return new Date(windowStart.getTime() + parseIso8601DurationMs(plan.windowDuration));
+    }
+    // pay-per-token: no window.
+    return new Date(windowStart.getTime() + 365 * 24 * 60 * 60 * 1000);
+}
+/** Minimal ISO 8601 duration parser supporting PT<N>H / PT<N>M / P<N>D combinations. */
+function parseIso8601DurationMs(duration) {
+    const m = duration.match(/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?)?$/);
+    if (!m)
+        throw new Error(`Unsupported ISO 8601 duration: ${duration}`);
+    const days = Number.parseInt(m[1] ?? '0', 10);
+    const hours = Number.parseInt(m[2] ?? '0', 10);
+    const minutes = Number.parseInt(m[3] ?? '0', 10);
+    return ((days * 24 + hours) * 60 + minutes) * 60 * 1000;
+}
+/**
+ * Tenant-share validation per RFC §14.12. Returns null if valid; otherwise the failed
+ * (harness, accountId) groups with their share sums. The orchestrator emits
+ * TenantShareInvalid for each failure and refuses to start.
+ */
+export function validateTenantShares(pipelines, tolerance = 0.001) {
+    const groups = new Map();
+    for (const p of pipelines) {
+        const key = `${p.harness}|${p.accountId}`;
+        let group = groups.get(key);
+        if (!group) {
+            group = {
+                harness: p.harness,
+                accountId: p.accountId,
+                pipelines: [],
+                shares: [],
+                tenants: new Set(),
+            };
+            groups.set(key, group);
+        }
+        group.pipelines.push(p.name);
+        group.shares.push(p.tenantQuotaShare);
+        if (p.tenant)
+            group.tenants.add(p.tenant);
+    }
+    const failures = [];
+    for (const group of groups.values()) {
+        if (group.tenants.size === 0)
+            continue; // all untenanted; no validation needed
+        if (group.shares.some((s) => s === undefined)) {
+            failures.push({
+                harness: group.harness,
+                accountId: group.accountId,
+                sumOfShares: NaN,
+                pipelines: group.pipelines,
+            });
+            continue;
+        }
+        const sum = group.shares.reduce((a, b) => a + b, 0);
+        if (Math.abs(sum - 1.0) > tolerance) {
+            failures.push({
+                harness: group.harness,
+                accountId: group.accountId,
+                sumOfShares: sum,
+                pipelines: group.pipelines,
+            });
+        }
+    }
+    return failures;
+}
+//# sourceMappingURL=ledger.js.map

package/dist/scheduling/off-peak.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Off-peak window evaluation per RFC §14.5. Operator-declared schedules with hour ranges
+ * (possibly wrapping midnight) and optional day-of-week filters, evaluated against an
+ * IANA timezone.
+ */
+import type { OffPeakSchedule } from './types.js';
+/**
+ * Returns true when the given instant falls inside any of the schedule's windows.
+ * Each window's `hours` is a range like '22-06' (which wraps midnight) or '0-7'.
+ */
+export declare function isOffPeakAt(schedule: OffPeakSchedule, when: Date): boolean;
+/**
+ * Returns the next off-peak window start strictly after `from`. Iterates by hour up to
+ * a 7-day horizon — bounded scan since schedules are weekly-periodic.
+ */
+export declare function nextOffPeakStart(schedule: OffPeakSchedule, from: Date): Date | null;
+/**
+ * Days since `lastVerified`. Returns Infinity if the date is missing/unparseable.
+ */
+export declare function ageInDays(lastVerified: string | undefined, now?: Date): number;
+export type FreshnessLevel = 'fresh' | 'advisory' | 'error';
+/**
+ * Returns the freshness severity per RFC §14.5: fresh ≤ 30 days, advisory 30–90 days,
+ * error > 90 days (or missing). Operators see this in cli-status --subscriptions.
+ */
+export declare function freshnessLevel(lastVerified: string | undefined, now?: Date): FreshnessLevel;
+//# sourceMappingURL=off-peak.d.ts.map

package/dist/scheduling/off-peak.js

@@ -0,0 +1,112 @@
+/**
+ * Off-peak window evaluation per RFC §14.5. Operator-declared schedules with hour ranges
+ * (possibly wrapping midnight) and optional day-of-week filters, evaluated against an
+ * IANA timezone.
+ */
+const DAY_NAMES = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+/**
+ * Returns true when the given instant falls inside any of the schedule's windows.
+ * Each window's `hours` is a range like '22-06' (which wraps midnight) or '0-7'.
+ */
+export function isOffPeakAt(schedule, when) {
+    if (!schedule.enabled || schedule.schedule.length === 0)
+        return false;
+    for (const window of schedule.schedule) {
+        if (windowMatches(window, when))
+            return true;
+    }
+    return false;
+}
+function windowMatches(window, when) {
+    const hourMatch = window.hours.match(/^(\d{1,2})-(\d{1,2})$/);
+    if (!hourMatch)
+        return false;
+    const startHour = Number.parseInt(hourMatch[1], 10);
+    const endHour = Number.parseInt(hourMatch[2], 10);
+    // Get the local hour + day-of-week in the window's timezone.
+    const local = getLocalTimeInTimezone(when, window.tz);
+    if (!local)
+        return false;
+    // Day filter (optional).
+    if (window.daysOfWeek) {
+        const allowedDays = new Set(window.daysOfWeek.split(',').map((d) => d.trim()));
+        if (!allowedDays.has(DAY_NAMES[local.dayOfWeek]))
+            return false;
+    }
+    // Hour range; wraps midnight when start > end.
+    if (startHour <= endHour) {
+        return local.hour >= startHour && local.hour < endHour;
+    }
+    // Wrapping case: e.g., 22-06 means [22, 24) ∪ [0, 6).
+    return local.hour >= startHour || local.hour < endHour;
+}
+function getLocalTimeInTimezone(when, tz) {
+    try {
+        const fmt = new Intl.DateTimeFormat('en-US', {
+            timeZone: tz,
+            hour: 'numeric',
+            hourCycle: 'h23',
+            weekday: 'short',
+        });
+        const parts = fmt.formatToParts(when);
+        let hour = null;
+        let weekday = null;
+        for (const p of parts) {
+            if (p.type === 'hour')
+                hour = Number.parseInt(p.value, 10);
+            else if (p.type === 'weekday')
+                weekday = p.value;
+        }
+        if (hour === null || weekday === null)
+            return null;
+        const dayIndex = DAY_NAMES.indexOf(weekday);
+        if (dayIndex < 0)
+            return null;
+        return { hour, dayOfWeek: dayIndex };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns the next off-peak window start strictly after `from`. Iterates by hour up to
+ * a 7-day horizon — bounded scan since schedules are weekly-periodic.
+ */
+export function nextOffPeakStart(schedule, from) {
+    if (!schedule.enabled || schedule.schedule.length === 0)
+        return null;
+    const HORIZON_HOURS = 24 * 7;
+    for (let h = 1; h <= HORIZON_HOURS; h++) {
+        const candidate = new Date(from.getTime() + h * 60 * 60 * 1000);
+        const candidateMinusHour = new Date(candidate.getTime() - 60 * 60 * 1000);
+        // Find a transition from off → on.
+        if (isOffPeakAt(schedule, candidate) && !isOffPeakAt(schedule, candidateMinusHour)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Days since `lastVerified`. Returns Infinity if the date is missing/unparseable.
+ */
+export function ageInDays(lastVerified, now = new Date()) {
+    if (!lastVerified)
+        return Infinity;
+    const parsed = new Date(lastVerified);
+    if (Number.isNaN(parsed.getTime()))
+        return Infinity;
+    return Math.floor((now.getTime() - parsed.getTime()) / (24 * 60 * 60 * 1000));
+}
+/**
+ * Returns the freshness severity per RFC §14.5: fresh ≤ 30 days, advisory 30–90 days,
+ * error > 90 days (or missing). Operators see this in cli-status --subscriptions.
+ */
+export function freshnessLevel(lastVerified, now = new Date()) {
+    const age = ageInDays(lastVerified, now);
+    if (age <= 30)
+        return 'fresh';
+    if (age <= 90)
+        return 'advisory';
+    return 'error';
+}
+//# sourceMappingURL=off-peak.js.map

package/dist/scheduling/schedule-decision.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Schedule-aware dispatch decision per RFC §14.3. Implements the four schedule modes
+ * (now, off-peak, quota-permitting, defer-if-low-priority) on top of the
+ * SubscriptionLedger admission decision.
+ */
+import type { SubscriptionLedger } from './ledger.js';
+import type { LedgerKey, Schedule, SubscriptionPlan, TokenEstimate } from './types.js';
+export type ScheduleDecision = {
+    kind: 'dispatch-now';
+    reason: string;
+} | {
+    kind: 'wait-until';
+    until: Date;
+    reason: string;
+} | {
+    kind: 'requeue';
+    reason: string;
+} | {
+    kind: 'denied';
+    reason: string;
+    blockedBy: string;
+};
+export interface ScheduleEvaluationContext {
+    ledger: SubscriptionLedger;
+    ledgerKey: LedgerKey;
+    plan: SubscriptionPlan;
+    estimate: TokenEstimate;
+    /**
+     * PPA score in [0,1]. Used by 'defer-if-low-priority' to decide whether to
+     * dispatch immediately (top quartile or > 30% headroom in the window).
+     */
+    ppaScore?: number;
+    queueScores?: number[];
+    /** Maximum time to wait for the next off-peak window. ISO 8601 duration. */
+    offPeakMaxWait?: string;
+    now?: () => Date;
+}
+export declare function evaluateSchedule(schedule: Schedule, ctx: ScheduleEvaluationContext): ScheduleDecision;
+//# sourceMappingURL=schedule-decision.d.ts.map