171 lines
5.6 KiB
TypeScript
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;
|
|
}
|