import type { AtomId, InterfaceRevisionId, MemberId, ValueType } from "../capability-model/types.js"; import type { TypeParameter, InterfaceApplicationExpression, ObjectTypeExpression, ClosedTypeArgument, } from "../capability-model/generics.js"; export type QueryUse = "select" | "predicate" | "order" | "aggregate" | "group" | "distinct"; export interface QueryAllowance { interfaceRevisionId: InterfaceRevisionId; memberId: MemberId; uses: QueryUse[]; reason: string; } export interface QueryBudgets { rows: number; depth: number; resultBytes: number; candidates: number; rpcCalls: number; concurrency: number; deadlineMs: number; } export const defaultQueryBudgets: Readonly = Object.freeze({ rows: 100, depth: 8, resultBytes: 1048576, candidates: 100, rpcCalls: 200, concurrency: 8, deadlineMs: 10000, }); export type QueryRoot = | { kind: "object"; interface: Interface } | { kind: "workspace-interface"; interface: Interface }; export interface QueryDeclaration { /** Exported local projection; compilation also creates its direct admission. */ fragment?: { name: string; operation?: string; admission?: boolean }; importedFragments?: { /** Bind an independently observed fragment without including its fields in * this projection. Its acquisition is still an explicit replica source. */ mode?: "reference"; packageRevisionId: string; packageAlias?: string; fragmentId: string; variables: Record; }[]; placement?: { kind: "replica" } | { kind: "local"; sourceQueryId: string }; id: string; displayName: string; root: QueryRoot; document: string; operation: string; fragments: string[]; views: { atomId: AtomId; interfaceRevisionId: InterfaceRevisionId }[]; allowances: QueryAllowance[]; budgets: QueryBudgets; watch: boolean; polling?: { intervalMs: number; reason: string }; application?: { templateId: string; arguments: ClosedTypeArgument[] }; argumentRequirements?: { target: import("../capability-model/types.js").ObjectExpectation; required: InterfaceRevisionId; }[]; } /** Source-only template; neither parameters nor synthetic bound witnesses are installed. */ export interface QueryTemplate { declaration: Omit; parameters: TypeParameter[]; root: QueryRoot; views: { target: ObjectTypeExpression; interface: InterfaceApplicationExpression }[]; allowances: { interface: InterfaceApplicationExpression; memberName: string; uses: QueryUse[]; reason: string }[]; } export interface QueryFieldEffect { interfaceRevisionId: InterfaceRevisionId; memberId: MemberId; uses: QueryUse[]; execution: "native" | "rpc-permitted" | "portable"; } export interface QuerySourceLocation { file: string; line: number; column: number; } export class QueryCompileError extends Error { constructor( readonly code: string, message: string, readonly location?: QuerySourceLocation, ) { super(`${code}${location ? ` ${location.file}:${location.line}:${location.column}` : ""}: ${message}`); this.name = "QueryCompileError"; } } export interface CheckedQuery { /** Checked decomposition; handles belong to a Client Session, never graph values. */ tree?: QueryTreePlan; treeProjection?: { tree: string; projection: string; role: "replica" | "local" }; fragmentContracts?: Record>; declaration: QueryDeclaration; definitionDigest: string; /** Fixed, validated document. Execution always uses checked IR; public runtime * documents pass through this same checker before they are executed. */ document: string; schema: string; variables: ValueType; output: ValueType; effects: QueryFieldEffect[]; selection: QuerySelection[]; variableDefaults: Record; sourceFiles: string[]; } export type QueryArgument = | { kind: "variable"; name: string } | { kind: "literal"; value: string | number | boolean | null } | { kind: "list"; values: QueryArgument[] } | { kind: "object"; fields: Record }; export interface QuerySelection { boundary?: { name: string; root: InterfaceRevisionId; output: ValueType; location?: QuerySourceLocation; }; /** A checked occurrence marker, not an output field or storage capability. */ fragmentSpread?: { mode?: "reference"; package: string; fragment: string; digest: string; root: InterfaceRevisionId; variables: Record; }; name: string; key: string; interfaceRevisionId?: InterfaceRevisionId; memberId?: MemberId; targetInterfaceRevisionId?: InterfaceRevisionId; conditions: { include: boolean; value: QueryArgument }[]; arguments: Record; selection: QuerySelection[]; relational?: import("./relational.js").QueryRelationalPlan; predicate?: import("./relational.js").QueryPredicate; } export interface QueryTreeProjection { id: string; root: QueryRoot; selection: QuerySelection[]; output: ValueType; } export interface QueryTreeNode { id: string; projection: string; boundaries: { name: string; conditions: QuerySelection["conditions"]; node: string }[]; bindings: { name: string; projection: string; /** [] denotes an occurrence in a bounded list; its entry key owns identity. */ targets: { path: string[]; node: string }[]; }[]; } export interface QueryTreePlan { root: string; nodes: QueryTreeNode[]; projections: QueryTreeProjection[]; maxOccurrences: number; }