Add queryable capability contracts and checked GraphQL artifacts

2026-09-17 14:55:10 -07:00
parent e3501772c5
commit 61a410f98f
27 changed files with 4798 additions and 2333 deletions
@@ -0,0 +1,90 @@
+import type { AtomId, InterfaceRevisionId, MemberId, ValueType } from "../capability-model/types.js";
+
+export type QueryUse = "select" | "predicate" | "order";
+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 interface QueryDeclaration {
+  id: string;
+  displayName: string;
+  root: InterfaceRevisionId;
+  document: string;
+  operation: string;
+  fragments: string[];
+  views: { atomId: AtomId; interfaceRevisionId: InterfaceRevisionId }[];
+  allowances: QueryAllowance[];
+  budgets: QueryBudgets;
+  watch: boolean;
+  polling?: { intervalMs: number; reason: string };
+}
+export interface QueryFieldEffect {
+  interfaceRevisionId: InterfaceRevisionId;
+  memberId: MemberId;
+  uses: QueryUse[];
+  execution: "native" | "rpc-permitted";
+}
+export interface QuerySourceLocation {
+  file: string;
+  line: number;
+  column: number;
+}
+export class QueryCompileError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly location?: QuerySourceLocation,
+  ) {
+    super(message);
+    this.name = "QueryCompileError";
+  }
+}
+export interface CheckedQuery {
+  declaration: QueryDeclaration;
+  definitionDigest: string;
+  /** Fixed, validated document: never supplied by runtime callers. */
+  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 {
+  name: string;
+  key: string;
+  interfaceRevisionId?: InterfaceRevisionId;
+  memberId?: MemberId;
+  targetInterfaceRevisionId?: InterfaceRevisionId;
+  conditions: { include: boolean; value: QueryArgument }[];
+  arguments: Record<string, QueryArgument>;
+  selection: QuerySelection[];
+}