Files
quixos-protocol/src/query/types.ts
T

171 lines
5.6 KiB
TypeScript

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<QueryBudgets> = Object.freeze({
rows: 100,
depth: 8,
resultBytes: 1048576,
candidates: 100,
rpcCalls: 200,
concurrency: 8,
deadlineMs: 10000,
});
export type QueryRoot<Interface = InterfaceRevisionId> =
| { 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<string, string>;
}[];
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<QueryDeclaration, "root" | "views" | "allowances">;
parameters: TypeParameter[];
root: QueryRoot<InterfaceApplicationExpression>;
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<string, NonNullable<QuerySelection["fragmentSpread"]>>;
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<string, QueryArgument>;
sourceFiles: string[];
}
export type QueryArgument =
| { kind: "variable"; name: string }
| { kind: "literal"; value: string | number | boolean | null }
| { kind: "list"; values: QueryArgument[] }
| { kind: "object"; fields: Record<string, QueryArgument> };
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<string, string>;
};
name: string;
key: string;
interfaceRevisionId?: InterfaceRevisionId;
memberId?: MemberId;
targetInterfaceRevisionId?: InterfaceRevisionId;
conditions: { include: boolean; value: QueryArgument }[];
arguments: Record<string, QueryArgument>;
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;
}