@spottoai/types-package 1.0.2-beta.43 → 1.0.2-beta.430

package/dist/common/providerSyncProgress.d.ts

@@ -0,0 +1,91 @@
+import { ProviderName, ProviderScopeType } from './provider';
+import type { SyncProgressIssue, SyncProgressStatus, SyncProgressStepStatus, SyncProgressSubStepStatus } from './syncProgress';
+/** Sanitized failure information safe to return through a public API. */
+export interface ProviderSyncProgressFailure {
+    code?: string;
+    message: string;
+    retryable?: boolean;
+    remediation?: string;
+}
+/**
+ * Engine-owned sync identifiers and raw failure details must not cross the
+ * public provider-sync progress boundary.
+ */
+export interface ProviderSyncProgressForbiddenInternalFields {
+    requestId?: never;
+    targetKey?: never;
+    childRequestIds?: never;
+    completedChildRequestIds?: never;
+    failureReason?: never;
+}
+/** Public checkpoint or nested work item owned by one provider sync stage. */
+export interface ProviderSyncSubStepProgress extends ProviderSyncProgressForbiddenInternalFields {
+    id: string;
+    label?: string;
+    status: SyncProgressSubStepStatus;
+    attempts?: number;
+    lastUpdated?: string;
+    completedAt?: string;
+    note?: string;
+    issue?: SyncProgressIssue;
+    failure?: ProviderSyncProgressFailure;
+}
+/** Public progress for one provider-owned stage. */
+export interface ProviderSyncStageProgress extends ProviderSyncProgressForbiddenInternalFields {
+    id: string;
+    label: string;
+    order: number;
+    status: SyncProgressStepStatus;
+    statusLabel?: string;
+    attempts?: number;
+    active?: boolean;
+    note?: string;
+    expectedWorkItemCount?: number;
+    completedWorkItemCount?: number;
+    startedAt?: string;
+    updatedAt?: string;
+    completedAt?: string;
+    issue?: SyncProgressIssue;
+    failure?: ProviderSyncProgressFailure;
+    subSteps?: ProviderSyncSubStepProgress[];
+}
+/** Aggregate counts for the stages selected for one provider sync run. */
+export interface ProviderSyncProgressSummary {
+    totalStages: number;
+    completedStages: number;
+    failedStages: number;
+    activeStages: number;
+    issueStages?: number;
+}
+interface ProviderSyncProgressBase extends ProviderSyncProgressForbiddenInternalFields {
+    cloudAccountId: string;
+    runId?: string;
+    overallStatus: SyncProgressStatus;
+    statusLabel: string;
+    hasIssues?: boolean;
+    currentStageId?: string;
+    requestedAt?: string;
+    startedAt?: string;
+    updatedAt?: string;
+    completedAt?: string;
+    lastSuccessfulSyncAt?: string;
+    summary: ProviderSyncProgressSummary;
+    stages: ProviderSyncStageProgress[];
+    failure?: ProviderSyncProgressFailure;
+}
+/** Public sync progress for an Azure subscription provider scope. */
+export interface AzureProviderSyncProgress extends ProviderSyncProgressBase {
+    providerName: ProviderName.Azure;
+    providerScopeId: string;
+    scopeType: ProviderScopeType.Subscription;
+}
+/** Public sync progress for an AWS account provider scope. */
+export interface AwsProviderSyncProgress extends ProviderSyncProgressBase {
+    providerName: ProviderName.Aws;
+    providerScopeId: string;
+    scopeType: ProviderScopeType.Account;
+}
+/** Provider-neutral public sync progress returned by API provider strategies. */
+export type ProviderSyncProgress = AzureProviderSyncProgress | AwsProviderSyncProgress;
+export {};
+//# sourceMappingURL=providerSyncProgress.d.ts.map

package/dist/common/providerSyncProgress.d.ts.map

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

package/dist/common/providerSyncProgress.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=providerSyncProgress.js.map

package/dist/common/providerSyncProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providerSyncProgress.js","sourceRoot":"","sources":["../../src/common/providerSyncProgress.ts"],"names":[],"mappings":""}

package/dist/common/relationships.d.ts

@@ -0,0 +1,8 @@
+import type { AwsPortalRelationshipArtifact } from '../aws/portalRelationshipPublicArtifacts';
+import type { RelationshipSnapshot } from '../azure/relationships';
+import type { ProviderScope } from './provider';
+/** Canonical provider scope used to select a provider-specific relationship artifact. */
+export type PublicRelationshipProviderScope = ProviderScope;
+/** Public relationship bodies accepted by provider-aware API and UI consumers. */
+export type PublicRelationshipArtifact = RelationshipSnapshot | AwsPortalRelationshipArtifact;
+//# sourceMappingURL=relationships.d.ts.map

package/dist/common/relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/common/relationships.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,0CAA0C,CAAC;AAC9F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,yFAAyF;AACzF,MAAM,MAAM,+BAA+B,GAAG,aAAa,CAAC;AAE5D,kFAAkF;AAClF,MAAM,MAAM,0BAA0B,GAAG,oBAAoB,GAAG,6BAA6B,CAAC"}

package/dist/common/relationships.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=relationships.js.map

package/dist/common/relationships.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.js","sourceRoot":"","sources":["../../src/common/relationships.ts"],"names":[],"mappings":""}

package/dist/common/syncProgress.d.ts

@@ -0,0 +1,27 @@
+/** Public lifecycle states shared by provider sync progress responses. */
+export type SyncProgressStatus = 'idle' | 'processing' | 'completed' | 'error';
+/** Public lifecycle states shared by provider sync progress stages. */
+export type SyncProgressStepStatus = 'idle' | 'pending' | 'queued' | 'inProgress' | 'completed' | 'error';
+/** Public lifecycle states shared by nested provider sync progress stages. */
+export type SyncProgressSubStepStatus = SyncProgressStepStatus | 'skipped';
+export type SyncProgressIssueType = 'capabilityMissing' | 'billingExport' | 'partialData';
+export type SyncProgressIssueScope = 'cloudAccount' | 'subscription' | 'component';
+export type SyncProgressIssueMetadataValue = string | number | boolean | undefined;
+/** Structured non-fatal issue shared by Azure and AWS sync progress. */
+export interface SyncProgressIssue {
+    type: SyncProgressIssueType;
+    scope: SyncProgressIssueScope;
+    capabilityKey?: string;
+    capabilityDisplayName?: string;
+    capabilityDescription?: string;
+    requiredRoles?: string[];
+    message: string;
+    code?: string;
+    title?: string;
+    remediation?: string;
+    sourceSelected?: 'export' | 'query';
+    fallbackUsed?: boolean;
+    degraded?: boolean;
+    metadata?: Record<string, SyncProgressIssueMetadataValue>;
+}
+//# sourceMappingURL=syncProgress.d.ts.map

package/dist/common/syncProgress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncProgress.d.ts","sourceRoot":"","sources":["../../src/common/syncProgress.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAE/E,uEAAuE;AACvE,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAE1G,8EAA8E;AAC9E,MAAM,MAAM,yBAAyB,GAAG,sBAAsB,GAAG,SAAS,CAAC;AAE3E,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,GAAG,eAAe,GAAG,aAAa,CAAC;AAC1F,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG,cAAc,GAAG,WAAW,CAAC;AACnF,MAAM,MAAM,8BAA8B,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEnF,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,KAAK,EAAE,sBAAsB,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IACpC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,8BAA8B,CAAC,CAAC;CAC3D"}

package/dist/common/syncProgress.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=syncProgress.js.map

package/dist/common/syncProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncProgress.js","sourceRoot":"","sources":["../../src/common/syncProgress.ts"],"names":[],"mappings":""}

package/dist/common/utilizationStories.d.ts

@@ -0,0 +1,516 @@
+/**
+ * Utilization stories: shared contracts for per-resource utilization profiles, the compact
+ * `utilizationSignal` carried on portal resource rows, the per-subscription story artifacts
+ * (`azure-portal/subscriptions/{id}/stories/{storyKey}.json`), the bounded story samples embedded
+ * in the subscription report evidence pack, and the cloud-engine config schemas that drive them.
+ *
+ * Provider-neutral (`provider` on every profile); depends only on other `common/` modules.
+ * Spec: `Specs/reporting/utilization-stories-types-package.md` (parent: core `specs/reporting/utilization-stories.md`).
+ *
+ * Producer: cloud-engine (`UtilizationProfileBuilder`, `StoryAccumulator`). Consumers: api (story routes), ui
+ * (story pages, report sections), report evidence pack (`reporting.stories`).
+ *
+ * All contracts are additive: consumers must tolerate unknown fields, and every optional field may be absent on
+ * artifacts produced by older engine versions.
+ */
+import type { MetricStats } from './metricStats';
+import type { ReportBoundedRows } from './boundedRows';
+export type Provider = 'azure' | 'aws';
+export type MetricRole = 'primary' | 'secondary' | 'context';
+export type DimensionPolicy = 'average' | 'sum' | 'max' | 'split';
+export type MetricVisual = 'sparkline' | 'trend' | 'capacity-bar' | 'mix-bar' | 'event-strip';
+export type BilledOn = 'allocated' | 'used' | 'included';
+/** One daily-bucketed metric series over the evidence window, ready for a sparkline or trend visual. */
+export interface MetricSparkline {
+    /** Generic profile key: "cpu", "memory", "dtu", "ru", "capacity", "usedCapacity", "transactions", ... */
+    key: string;
+    /** Provider metric name behind the key. */
+    metricName: string;
+    role: MetricRole;
+    visual: MetricVisual;
+    unit: string;
+    /** Resolved at build time; null when no sensible axis maximum exists. */
+    axisMax: number | null;
+    axisMaxSource?: 'config' | 'capacity' | 'observed';
+    /** Capacity metrics only. */
+    billedOn?: BilledOn;
+    dimensions?: {
+        policy: DimensionPolicy;
+        name?: string;
+        value?: string;
+        seriesCount: number;
+    };
+    /** ISO date (UTC) of bucket 0. */
+    start: string;
+    bucket: 'P1D';
+    /** `windowDays` entries; null = no samples that day. */
+    avg: (number | null)[];
+    p95: (number | null)[];
+    max: (number | null)[];
+    stats: MetricStats;
+    sourcePoints: number;
+}
+export interface CapacityDescriptor {
+    sku: string | null;
+    tier: string | null;
+    units: number | null;
+    /** "vCPU" | "vCore" | "DTU" | "instances" | "RU/s" | "units" | "nodes" | ... */
+    unitName: string;
+    memoryGB?: number | null;
+    scaleMode: 'fixed' | 'autoscale' | 'serverless';
+    /** Display label, e.g. "4 vCPU · 32 GB RAM". */
+    label: string;
+}
+export type RunMode = 'stop-start' | 'auto-pause' | 'scale-to-zero' | 'always-on';
+export type SizingVerdict = 'oversized' | 'undersized' | 'busy' | 'rebalance' | 'mostly-off' | 'idle' | 'no-telemetry' | 'fits' | 'unknown';
+export type ScheduleFit = 'good' | 'fair' | 'low' | 'done' | 'insufficient-data' | 'not-applicable';
+export type ScheduleAction = 'stop' | 'pause' | 'scale';
+export type TelemetryStatus = 'collected' | 'partial' | 'no-series' | 'unavailable';
+/**
+ * How the running/stopped signal was derived. `metric-presence` alone cannot distinguish a stopped resource from a
+ * collection gap, so it must be corroborated (see `RunningProfile.corroboration`) before it may drive a schedule fit
+ * or a `mostly-off` verdict.
+ */
+export type RunningBasis = 'power-state' | 'billing-hours' | 'metric-presence';
+export interface RunningProfile {
+    signalMetric: string;
+    basis: RunningBasis;
+    /**
+     * Independent sources (never the basis itself) whose daily running hours agree with `daily` within the engine's
+     * tolerance. Empty when none. Guard rule: `scheduleFit` in good|fair|low and `verdict` = mostly-off require
+     * `basis !== 'metric-presence'` or a corroboration entry other than `metric-presence`, plus
+     * `evidenceWindow.telemetry === 'collected'`; otherwise the engine emits `insufficient-data` / `unknown`.
+     */
+    corroboration: RunningBasis[];
+    /** Share of each day's expected samples that carried a value (or, for power-state/billing bases, the running share). */
+    daily: (number | null)[];
+    share: number | null;
+    weekly?: {
+        timezone: string;
+        /** 7 x 24 */
+        running: (number | null)[][];
+        /** 7 x 24, mean of the primary metric while running. */
+        usage: (number | null)[][];
+        businessHours: {
+            runningShare: number | null;
+            usageMean: number | null;
+        };
+        offHours: {
+            runningShare: number | null;
+            usageMean: number | null;
+        };
+    };
+}
+export interface CommitmentCoverage {
+    coveragePercent: number | null;
+    benefitTypes: ('reservation' | 'savings-plan')[];
+    benefitNames: string[];
+    coveredCost: number | null;
+    uncoveredCost: number | null;
+    windowStart: string;
+    windowEnd: string;
+}
+export interface EvidenceWindow {
+    windowStart: string;
+    windowEnd: string;
+    days: number;
+    sampleCount: number;
+    telemetry: TelemetryStatus;
+    confidence: 'high' | 'medium' | 'low';
+}
+export interface VerdictReason {
+    rule: string;
+    values: Record<string, number | null>;
+}
+export interface UtilizationProfile {
+    provider: Provider;
+    /** "compute" | "database" | "storage" | "networking" | "integration" | "analytics" | ... */
+    family: string;
+    capacity: CapacityDescriptor;
+    runMode: RunMode;
+    metrics: MetricSparkline[];
+    running?: RunningProfile;
+    verdict: SizingVerdict;
+    verdictReasons: VerdictReason[];
+    /** Corroborating stable keys, e.g. "cpu-low", "advisor-rightsize". */
+    evidence: string[];
+    scheduleFit: ScheduleFit;
+    scheduleAction?: ScheduleAction;
+    coverage?: CommitmentCoverage;
+    /** Derived from billing config (pool, plan, scale set, cluster). */
+    ownerResourceId?: string;
+    evidenceWindow: EvidenceWindow;
+    /** `${resourceId}|${verdict}` */
+    fingerprint: string;
+}
+/** Compact form carried on portal `resources.json` rows and used by list views. */
+export interface UtilizationSignal {
+    verdict: SizingVerdict;
+    scheduleFit: ScheduleFit;
+    primary: {
+        key: string;
+        p95: number | null;
+        sparkline: (number | null)[];
+    };
+    secondary?: {
+        key: string;
+        p95: number | null;
+        sparkline: (number | null)[];
+    };
+    coverage?: Pick<CommitmentCoverage, 'coveragePercent' | 'benefitTypes'>;
+    betterSku?: SkuOptionSummary;
+    telemetry: TelemetryStatus;
+}
+export type SkuOptionKind = 'same-shape' | 'fits-usage' | 'trade-off' | 'cross-platform';
+export interface SkuOption {
+    kind: SkuOptionKind;
+    /** e.g. "Standard_E8as_v4" */
+    sku: string;
+    /** e.g. "E8as v4" */
+    label: string;
+    capacity?: {
+        units: number | null;
+        memoryGB?: number | null;
+    };
+    monthlyCost: number | null;
+    currency: string;
+    savingsPercent: number | null;
+    savingsMonthly: number | null;
+    /** Provider capability keys, e.g. "maxDataDiskCount". */
+    lostCapabilities: string[];
+    confidence?: 'high' | 'medium' | 'low';
+}
+export interface SkuOptionSummary {
+    kind: SkuOptionKind;
+    label: string;
+    savingsPercent: number | null;
+}
+export type CapabilityState = 'enabled' | 'disabled' | 'partial' | 'unknown' | 'not-applicable';
+export interface ProtectionCapability {
+    /**
+     * "backup" | "replication" | "placement" | "disk-redundancy" | "patching" | "snapshots" | "geo-replication" |
+     * "pitr-retention" | "long-term-retention" | "zone-redundancy" | "backup-storage-redundancy" | "redundancy" |
+     * "soft-delete" | "versioning" | "point-in-time-restore" | "immutability" | "multi-region" | "continuous-backup" |
+     * "purge-protection" | ...
+     */
+    key: string;
+    state: CapabilityState;
+    required: boolean;
+    label: string;
+    details?: Record<string, string | number | boolean | null>;
+    costIfEnabled?: number | null;
+    evidence: {
+        source: string;
+        observedAt?: string | null;
+    };
+}
+export interface ProtectionProfile {
+    provider: Provider;
+    capabilities: ProtectionCapability[];
+    missingRequired: string[];
+    slaPercent?: number | null;
+}
+export type StoryKey = 'oversized-resources' | 'right-sku' | 'schedule-candidates' | 'resilience-recovery' | 'hybrid-benefit' | 'commitments';
+export declare const STORY_KEYS: readonly StoryKey[];
+export type StoryCellKind = 'text' | 'number' | 'money' | 'percent' | 'mark' | 'dot' | 'sparkline' | 'dual' | 'capacity-bar' | 'mix-bar' | 'event-strip' | 'weekly-grid';
+export type SeriesRole = 'primary' | 'secondary';
+export type StatusTone = 'good' | 'warn' | 'bad' | 'neutral' | 'muted';
+export interface TextCell {
+    kind: 'text';
+    value: string | null;
+    /** Optional second line, e.g. "4 vCPU · 32 GB RAM" under a SKU. */
+    detail?: string | null;
+}
+export interface NumberCell {
+    kind: 'number';
+    value: number | null;
+    unit?: string;
+    decimals?: number;
+}
+export interface MoneyCell {
+    kind: 'money';
+    value: number | null;
+    currency: string;
+}
+export interface PercentCell {
+    kind: 'percent';
+    value: number | null;
+}
+/** One-word verdict / rating with an icon and tone; `state` is the stable enum value behind the label. */
+export interface MarkCell {
+    kind: 'mark';
+    state: string;
+    label: string;
+    tone: StatusTone;
+    icon?: string;
+    hint?: string;
+}
+/** A single indicator dot, e.g. "better SKU available". */
+export interface DotCell {
+    kind: 'dot';
+    present: boolean;
+    tone: StatusTone;
+    label?: string;
+    hint?: string;
+}
+export interface SparklineCell {
+    kind: 'sparkline';
+    role: SeriesRole;
+    /** Daily values for the window; null = no samples that day. */
+    values: (number | null)[];
+    axisMax: number | null;
+    unit: string;
+    p95: number | null;
+    label: string;
+}
+/** Primary and secondary series merged into one column at narrow layouts. */
+export interface DualCell {
+    kind: 'dual';
+    primary: SparklineCell;
+    secondary: SparklineCell | null;
+}
+export interface CapacityBarCell {
+    kind: 'capacity-bar';
+    used: number | null;
+    total: number | null;
+    unit: string;
+    label: string;
+}
+export interface MixBarCell {
+    kind: 'mix-bar';
+    parts: {
+        key: string;
+        label: string;
+        value: number;
+    }[];
+    unit: string;
+    total: number;
+}
+export interface EventStripCell {
+    kind: 'event-strip';
+    events: ('ok' | 'failed' | null)[];
+    /** ISO date (UTC) of event 0. */
+    start: string;
+    label?: string;
+}
+export interface WeeklyGridCell {
+    kind: 'weekly-grid';
+    timezone: string;
+    /** 7 x 24 running share. */
+    running: (number | null)[][];
+    businessHoursShare: number | null;
+    offHoursShare: number | null;
+}
+export type StoryCell = TextCell | NumberCell | MoneyCell | PercentCell | MarkCell | DotCell | SparklineCell | DualCell | CapacityBarCell | MixBarCell | EventStripCell | WeeklyGridCell;
+export interface StoryRowBase {
+    resourceId: string;
+    name: string;
+    type: string;
+    location: string;
+    subscriptionId: string;
+    tenantId: string;
+    companyId: string;
+    currency: string;
+    spend30d: number | null;
+    savingsMax: number | null;
+    ownerResourceId?: string;
+    fingerprint: string;
+    /** One entry per column key of the owning section; kinds match `StoryColumn.cell`. */
+    cells: Record<string, StoryCell>;
+}
+export interface OversizedResourceRow extends StoryRowBase {
+    profile: UtilizationProfile;
+    betterSku?: SkuOptionSummary;
+}
+export interface RightSkuRow extends StoryRowBase {
+    current: SkuOption;
+    options: SkuOption[];
+    verdict: 'modernise' | 'downsize' | 'consider' | 'keep';
+    usage: {
+        primaryP95: number | null;
+        secondaryP95: number | null;
+        telemetry: TelemetryStatus;
+    };
+}
+export interface ScheduleCandidateRow extends StoryRowBase {
+    /** `profile.running.weekly` is always present on schedule candidates. */
+    profile: UtilizationProfile;
+    action: ScheduleAction;
+}
+export interface ResilienceRow extends StoryRowBase {
+    protection: ProtectionProfile;
+    backupRuns?: ('ok' | 'failed' | null)[];
+    lastRecoveryPointAt?: string | null;
+    uptimeDays?: number | null;
+    activeHealthEvents?: number;
+}
+export interface HybridBenefitRow extends StoryRowBase {
+    productFamily: string;
+    serviceModel: string;
+    edition: string | null;
+    vCpuCount: number | null;
+    configurationStatus: string;
+    technicalEligibilityStatus: string;
+    coverageStatus: string;
+    entitlementStatus: string;
+    decision: {
+        status: string;
+        headline: string;
+        paybackMonths: number | null;
+        confidence: string;
+    };
+    reasonCodes: string[];
+    licenceObservedStableDays: number | null;
+}
+export interface CommitmentRow extends StoryRowBase {
+    coverage: CommitmentCoverage;
+    utilization?: {
+        primaryKey: string;
+        p95: number | null;
+    };
+}
+export interface StoryRowByKey {
+    'oversized-resources': OversizedResourceRow;
+    'right-sku': RightSkuRow;
+    'schedule-candidates': ScheduleCandidateRow;
+    'resilience-recovery': ResilienceRow;
+    'hybrid-benefit': HybridBenefitRow;
+    commitments: CommitmentRow;
+}
+export declare const STORY_LIMITS: {
+    readonly sectionRows: 1000;
+    readonly sampleRows: 50;
+    readonly windowDays: 30;
+    readonly weeklyGridDays: 7;
+    readonly weeklyGridHours: 24;
+    /** Story fingerprints retained per monthly history period (all stories together). */
+    readonly historyFingerprints: 2000;
+};
+/** Reuses ReportBoundedRows<T> (totalCount / rows / omittedCount) from reportEvidence.ts. */
+export interface StorySection<TRow> extends ReportBoundedRows<TRow> {
+    resourceType: string;
+    family: string;
+    columns: StoryColumn[];
+}
+/**
+ * Column definition for the generic story table. `cell` names the renderer; `priority` drives the responsive
+ * tiers (1 always shown ... 5 first to drop); `roleClass` drives layout width and the primary/secondary merge:
+ * a section that has a `sec` column also carries a `dual` column, shown instead of `prim` + `sec` at narrow tiers.
+ */
+export interface StoryColumn {
+    key: string;
+    label: string;
+    cell: StoryCellKind;
+    priority: 1 | 2 | 3 | 4 | 5;
+    roleClass?: 'res' | 'prim' | 'sec' | 'nums' | 'cap' | 'read' | 'cost' | 'save' | 'dual';
+    hint?: string;
+}
+export interface StorySummary {
+    counts: Record<string, number>;
+    spend: Record<string, number>;
+    currency: string;
+    note?: string;
+}
+export interface StoryArtifact<TRow = unknown> {
+    storyKey: StoryKey;
+    scope: {
+        companyId: string;
+        tenantId: string;
+        subscriptionId: string;
+        displayName: string;
+        currency: string;
+    };
+    generation: {
+        sourceRunId: string;
+        generatedAt: string;
+    };
+    window: {
+        start: string;
+        end: string;
+        days: number;
+        timezone: string;
+    };
+    summary: StorySummary;
+    sections: StorySection<TRow>[];
+}
+/**
+ * Compact identity of one published story row, retained per monthly history period so a later report can say
+ * whether a row was previously reported (`previouslyReported`) and how its saving moved. Selected across all six
+ * stories by `savingsMax` desc, `storyKey` asc, `resourceId` asc and bounded by `STORY_LIMITS.historyFingerprints`.
+ */
+export interface StoryFingerprint {
+    storyKey: StoryKey;
+    resourceId: string;
+    /** The row's `fingerprint` (`${resourceId}|${verdict}` and story-specific variants). */
+    fingerprint: string;
+    savingsMax: number | null;
+}
+export interface StorySample<TRow = unknown> {
+    summary: StorySummary;
+    /** At most STORY_LIMITS.sampleRows rows per section. */
+    sections: StorySection<TRow>[];
+}
+export type ReportingStories = Partial<Record<StoryKey, StorySample>>;
+export interface UtilizationProfileConfig {
+    version: 1;
+    defaults: {
+        windowDays: number;
+        bucket: 'P1D';
+        weeklyProfile: boolean;
+        verdictRules: Record<string, string>;
+    };
+    /** Keyed by lowercase resource type. */
+    profiles: Record<string, UtilizationProfileEntry>;
+}
+export interface UtilizationProfileEntry {
+    family: string;
+    producer?: 'parser' | 'strategy';
+    /** jsonata over the resource */
+    capacityLabel?: string;
+    runMode: RunMode;
+    /** metric key */
+    runningSignal?: string | null;
+    scheduleFit?: boolean | ScheduleAction;
+    variants?: {
+        when: string;
+        metrics: UtilizationMetricEntry[];
+        verdictRules?: Record<string, string>;
+    }[];
+    metrics?: UtilizationMetricEntry[];
+    verdictRules?: Record<string, string>;
+    skuAlternatives?: {
+        source: string;
+        capabilityKeys?: string[];
+    };
+}
+export interface UtilizationMetricEntry {
+    key: string;
+    metricName: string;
+    collection?: string;
+    role: MetricRole;
+    visual?: MetricVisual;
+    unit?: string;
+    axisMax?: number;
+    axisMaxExpression?: string;
+    billedOn?: BilledOn;
+    transform?: string;
+    requires?: string;
+    when?: string;
+    dimensions?: {
+        policy: DimensionPolicy;
+        name?: string;
+    };
+    priority?: 1 | 2 | 3 | 4 | 5;
+}
+export interface ResilienceProfileConfig {
+    version: 1;
+    profiles: Record<string, {
+        capabilities: {
+            key: string;
+            required: boolean;
+            source: string;
+            sla?: string;
+        }[];
+    }>;
+}
+//# sourceMappingURL=utilizationStories.d.ts.map