Report API

let plan: ReportPlan;
let input: ReportInput;
{
  await using record = await openRecordReader({ root });
  const sample = await projectExplicitRuns(record, { runIds });
  const scope = createReportScope(sample);
  plan = definition.plan(scope);
  input = await buildReportInput({ record, sample, plan });
}

const execution = executeReport({ definition, plan, input });

interface ReportScope {
  readonly provenance: AnalysisProjectionProvenance;
  readonly runs: readonly AnalysisRun[];
  readonly slots: readonly AnalysisSlot[];
}

type FactOwner = "run" | "attempt";

interface FactRequirement<Value> {
  readonly id: string;
  readonly owner: FactOwner;
  readonly name: string;
  readonly source: BuiltInFactSource | CustomJsonFactSource<Value>;
}

defineJsonFact({
  id,
  owner,
  name,
  parse(document) {
    return value;
  },
});

interface ReportPlan {
  readonly calculations: readonly Calculation<unknown>[];
  readonly pages: readonly ReportPage[];
  readonly downloads: readonly ReportDownload[];
}

interface ReportInput {
  readonly scope: ReportScope;
  readonly sample: AnalysisSample;
  // The internal fact matrix uses an unexported brand and cannot be indexed by user code.
}

interface ReportContext {
  readonly scope: ReportScope;
  readonly sample: ReportSample; // Explicitly excludes recordRoot
}

interface Calculation<Value> {
  readonly id: string;
  readonly inputs: readonly FactRequirement<ReportJsonValue>[];
  readonly completeness: "allowPartial" | "requireComplete";
  evaluate(input: CalculationInput): CalculationValue<Value>;
}

interface ReportPage {
  readonly id: string;
  readonly route: ReportRoute;
  readonly title: string;
  readonly inputs: readonly FactRequirement<ReportJsonValue>[];
  readonly calculations: readonly Calculation<unknown>[];
  render(input: ReportPageInput): ReportPageModel;
}

interface ReportPageModel {
  readonly title: string;
  readonly body: ReportJsonValue;
  readonly textAlternative: string;
}

interface ReportDownload {
  readonly id: string;
  readonly path: ReportDownloadPath;
  readonly mediaType: string;
  readonly inputs: readonly FactRequirement<ReportJsonValue>[];
  readonly calculations: readonly Calculation<unknown>[];
  build(input: ReportDownloadInput): Uint8Array;
}

interface ReportExecution {
  readonly plan: ReportPlan;
  readonly input: ReportInput;
  readonly calculations: readonly CalculationResult<unknown>[];
  readonly pages: readonly PageResult[];
  readonly downloads: readonly DownloadResult[];
}

interface StaticAssetManifest {
  readonly routes: readonly {
    readonly route: ReportRoute;
    readonly pagePath: StaticOutputPath;
    readonly hostDataPath: StaticOutputPath;
  }[];
  readonly entries: readonly StaticAsset[];
}