@ai-sdlc/orchestrator 0.6.0 → 0.10.0

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

package/dist/scheduling/schedule-decision.js

@@ -0,0 +1,89 @@
+/**
+ * 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 { isOffPeakAt, nextOffPeakStart } from './off-peak.js';
+const DEFAULT_OFF_PEAK_MAX_WAIT_MS = 8 * 60 * 60 * 1000; // PT8H
+export function evaluateSchedule(schedule, ctx) {
+    const now = ctx.now ?? (() => new Date());
+    const admission = ctx.ledger.admit(ctx.ledgerKey, ctx.plan, ctx.estimate);
+    switch (schedule) {
+        case 'now':
+            return interpretNow(admission);
+        case 'off-peak':
+            return interpretOffPeak(admission, ctx, now());
+        case 'quota-permitting':
+            return interpretQuotaPermitting(admission);
+        case 'defer-if-low-priority':
+            return interpretDeferIfLowPriority(admission, ctx, now());
+        default:
+            throw new Error(`Unknown schedule mode: ${String(schedule)}`);
+    }
+}
+function interpretNow(admission) {
+    if (admission.kind === 'yes')
+        return { kind: 'dispatch-now', reason: admission.reason };
+    if (admission.kind === 'wait-until')
+        return { kind: 'wait-until', until: admission.until, reason: admission.reason };
+    return { kind: 'denied', reason: admission.reason, blockedBy: admission.blockedBy };
+}
+function interpretOffPeak(admission, ctx, now) {
+    if (!ctx.plan.offPeak || !ctx.plan.offPeak.enabled) {
+        // No off-peak configured; behave as 'now'.
+        return interpretNow(admission);
+    }
+    if (isOffPeakAt(ctx.plan.offPeak, now)) {
+        return interpretNow(admission);
+    }
+    const next = nextOffPeakStart(ctx.plan.offPeak, now);
+    if (!next)
+        return interpretNow(admission);
+    const maxWaitMs = parseDurationMs(ctx.offPeakMaxWait) ?? DEFAULT_OFF_PEAK_MAX_WAIT_MS;
+    if (next.getTime() - now.getTime() <= maxWaitMs) {
+        return {
+            kind: 'wait-until',
+            until: next,
+            reason: 'next off-peak window within offPeakMaxWait',
+        };
+    }
+    // Off-peak too far in the future; fall through to dispatch-on-peak with a warning.
+    return { kind: 'dispatch-now', reason: 'OffPeakDeferralExceeded — dispatching on-peak' };
+}
+function interpretQuotaPermitting(admission) {
+    if (admission.kind === 'yes')
+        return { kind: 'dispatch-now', reason: admission.reason };
+    return { kind: 'requeue', reason: admission.reason };
+}
+function interpretDeferIfLowPriority(admission, ctx, now) {
+    // Top quartile of queue → dispatch immediately.
+    const isTopQuartile = ctx.ppaScore !== undefined && ctx.queueScores && isInTopQuartile(ctx.ppaScore, ctx.queueScores);
+    if (isTopQuartile)
+        return interpretNow(admission);
+    // >30% window headroom → dispatch immediately.
+    const ws = ctx.ledger.windowState(ctx.ledgerKey, ctx.plan);
+    const headroomFraction = 1 - ws.utilizationFraction;
+    if (headroomFraction > 0.3)
+        return interpretNow(admission);
+    // Otherwise behave as 'off-peak'.
+    return interpretOffPeak(admission, ctx, now);
+}
+function isInTopQuartile(score, queueScores) {
+    if (queueScores.length === 0)
+        return true;
+    const sorted = [...queueScores].sort((a, b) => b - a);
+    const cutoff = sorted[Math.floor(sorted.length / 4)] ?? sorted[0];
+    return score >= cutoff;
+}
+function parseDurationMs(duration) {
+    if (!duration)
+        return null;
+    const m = duration.match(/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?)?$/);
+    if (!m)
+        return null;
+    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;
+}
+//# sourceMappingURL=schedule-decision.js.map

package/dist/scheduling/tier-analysis.d.ts

@@ -0,0 +1,47 @@
+/**
+ * TierAnalysis aggregator per RFC §14.13. Aggregates QuotaContention events per
+ * billing window and produces upgrade/downgrade recommendations consumed by the
+ * Slack daily digest and cli-tier-recommendation.
+ */
+import type { LedgerKey, SubscriptionPlan } from './types.js';
+export type Confidence = 'low' | 'medium' | 'high';
+export interface ContentionEvent {
+    timestamp: string;
+    /** Cumulative duration the high-PPA stage waited on hardCap. */
+    contentionDurationMs: number;
+}
+export interface TierAnalysisInput {
+    billingPeriod: string;
+    ledgerKey: LedgerKey;
+    currentPlan: SubscriptionPlan;
+    contentionEvents: ContentionEvent[];
+    issuesDeferredOffPeak: number;
+    issuesBlockedOnHardCap: number;
+    /** Candidate plans (typically: registered SubscriptionPlan resources). */
+    candidates: SubscriptionPlan[];
+}
+export interface TierAnalysisResult {
+    billingPeriod: string;
+    ledgerKey: LedgerKey;
+    currentPlan: string;
+    currentPlanCostUsd: number;
+    contentionEvents: number;
+    cumulativeContentionDurationMs: number;
+    issuesDeferredOffPeak: number;
+    issuesBlockedOnHardCap: number;
+    recommendedPlan: string;
+    recommendedPlanCostUsd: number;
+    projectedTimeSavedMs: number;
+    projectedAdditionalIssuesProcessed: number;
+    projectedSpilloverSavingsUsd: number;
+    confidence: Confidence;
+    reasoning: string;
+}
+/**
+ * Reference plan-cost table — the orchestrator typically has these populated from the
+ * SubscriptionPlan resources, but ships with sensible defaults so cli-tier-recommendation
+ * can produce useful output even on a fresh deployment.
+ */
+export declare const PLAN_COSTS_USD: Record<string, number>;
+export declare function analyzeTier(input: TierAnalysisInput): TierAnalysisResult;
+//# sourceMappingURL=tier-analysis.d.ts.map

package/dist/scheduling/tier-analysis.js

@@ -0,0 +1,81 @@
+/**
+ * TierAnalysis aggregator per RFC §14.13. Aggregates QuotaContention events per
+ * billing window and produces upgrade/downgrade recommendations consumed by the
+ * Slack daily digest and cli-tier-recommendation.
+ */
+/**
+ * Reference plan-cost table — the orchestrator typically has these populated from the
+ * SubscriptionPlan resources, but ships with sensible defaults so cli-tier-recommendation
+ * can produce useful output even on a fresh deployment.
+ */
+export const PLAN_COSTS_USD = {
+    'claude-code-pro': 20,
+    'claude-code-max-5x': 100,
+    'claude-code-max-20x': 200,
+    'codex-plus': 20,
+    'codex-pro': 200,
+    'pay-per-token': 0,
+};
+const HIGH_CONTENTION_THRESHOLD = 20;
+const MEDIUM_CONTENTION_THRESHOLD = 5;
+export function analyzeTier(input) {
+    const cumulative = input.contentionEvents.reduce((a, e) => a + e.contentionDurationMs, 0);
+    const confidence = confidenceFor(input.contentionEvents.length);
+    const currentPlanCost = PLAN_COSTS_USD[input.currentPlan.name] ?? 0;
+    // Find the candidate that minimizes expected contention, conservative for downgrades.
+    let recommended = input.currentPlan;
+    let recommendedCost = currentPlanCost;
+    if (input.contentionEvents.length > 0) {
+        // Upgrade direction: pick the next plan up.
+        const upgrade = nextPlanUp(input.currentPlan, input.candidates);
+        if (upgrade) {
+            recommended = upgrade;
+            recommendedCost = PLAN_COSTS_USD[upgrade.name] ?? currentPlanCost;
+        }
+    }
+    else if (confidence === 'high') {
+        // Possibly recommend downgrade if utilization is consistently low — we don't have
+        // utilization in this aggregation; defer to caller to set issuesBlockedOnHardCap=0
+        // and contentionEvents=0 explicitly. For now keep currentPlan as the recommendation.
+    }
+    const reasoning = buildReasoning(input, cumulative, recommended);
+    return {
+        billingPeriod: input.billingPeriod,
+        ledgerKey: input.ledgerKey,
+        currentPlan: input.currentPlan.name,
+        currentPlanCostUsd: currentPlanCost,
+        contentionEvents: input.contentionEvents.length,
+        cumulativeContentionDurationMs: cumulative,
+        issuesDeferredOffPeak: input.issuesDeferredOffPeak,
+        issuesBlockedOnHardCap: input.issuesBlockedOnHardCap,
+        recommendedPlan: recommended.name,
+        recommendedPlanCostUsd: recommendedCost,
+        projectedTimeSavedMs: cumulative * 0.75, // heuristic: upgrade reclaims ~75% of contention
+        projectedAdditionalIssuesProcessed: Math.floor(cumulative / (60 * 60 * 1000)), // 1 issue per hour saved
+        projectedSpilloverSavingsUsd: input.issuesBlockedOnHardCap * 1.5,
+        confidence,
+        reasoning,
+    };
+}
+function nextPlanUp(current, candidates) {
+    const sameHarness = candidates.filter((c) => c.harness === current.harness);
+    const ordered = sameHarness.sort((a, b) => (PLAN_COSTS_USD[a.name] ?? 0) - (PLAN_COSTS_USD[b.name] ?? 0));
+    const idx = ordered.findIndex((p) => p.name === current.name);
+    if (idx < 0 || idx === ordered.length - 1)
+        return null;
+    return ordered[idx + 1];
+}
+function confidenceFor(count) {
+    if (count > HIGH_CONTENTION_THRESHOLD)
+        return 'high';
+    if (count >= MEDIUM_CONTENTION_THRESHOLD)
+        return 'medium';
+    return 'low';
+}
+function buildReasoning(input, cumulativeMs, recommended) {
+    if (recommended.name === input.currentPlan.name) {
+        return `Current plan ${input.currentPlan.name} appears appropriately sized for observed contention (${input.contentionEvents.length} events, ${(cumulativeMs / 1000 / 60 / 60).toFixed(1)}h cumulative).`;
+    }
+    return `${input.currentPlan.name} hit hardCap on ${input.issuesBlockedOnHardCap} issues this period, totaling ${(cumulativeMs / 1000 / 60 / 60).toFixed(1)}h of cumulative wait. ${recommended.name} would project to keep utilization below pacingTarget at current dispatch rate.`;
+}
+//# sourceMappingURL=tier-analysis.js.map