@sequenceholdings/orm 0.1.1 → 0.1.3

package/dist/compiler.d.ts

@@ -0,0 +1,389 @@
+import { CanonicalEnum, CanonicalDefinition } from './canonical.js';
+import { ClaimKey, PredIr, RootIr, InputRefKind, TableMetaIr, CompiledOperation, CompiledArtifact, VariableIr, OrderIr, SelectionIr } from './ir.js';
+import { DocumentNode, OperationDefinitionNode, FragmentDefinitionNode, GraphQLSchema, ValueNode, SelectionSetNode } from 'graphql';
+export { DynamicInputIssue, DynamicInputResult, NormalizedBoolExp, NormalizedOnConflict, NormalizedOrderBy, NormalizedRow, ORDER_BY_DIRECTIONS, ScalarKind, allowedBoolExpOperators, allowedOps, validateAppendInput, validateBoolExpInput, validateInsertInput, validateOnConflictInput, validateOrderByInput, validateSelectColumns, validateSetInput } from './dynamic-input.js';
+export { CompilePolicyInput, CompilePredicateInput, POLICY_COMPARE_OPS, POLICY_MAX_LINK_DEPTH, ParsedPolicy, PolicyColumnInfo, PolicyCompareOp, PolicyCompileError, PolicyCompileErrorCode, PolicyLinkInfo, PolicyNode, PolicyOperand, PolicyParseError, PolicyResolver, PolicyTableInfo, assertClaimsOnlyWhen, compilePolicy, compilePredicateV2, parsePolicy, walkPolicy } from './predicate-v2.js';
+export { P as PLATFORM_USER_TYPENAME, c as camelCase, e as enumTypeName, p as pascalCase } from './naming-CTvWSRTf.js';
+import 'zod';
+
+type DiagnosticSeverity = 'error' | 'warning';
+interface CompilerDiagnostic {
+    severity: DiagnosticSeverity;
+    /** Stable machine code, e.g. 'unknown-column', 'unsupported-variable-type'. */
+    code: string;
+    message: string;
+    /** Source document path, when the diagnostic is document-scoped. */
+    document?: string;
+    /** Operation name, when known. */
+    operation?: string;
+    /** Table name, for canonical/policy-scoped diagnostics. */
+    table?: string;
+}
+/**
+ * Thrown internally while compiling one operation; artifact assembly catches
+ * it and records a diagnostic, so one broken document never hides the rest.
+ */
+declare class DocumentCompileError extends Error {
+    readonly code: string;
+    readonly candidates: readonly string[];
+    readonly name = "DocumentCompileError";
+    constructor(message: string, code: string, candidates?: readonly string[]);
+}
+/** Thrown by compileNamespace when any error-severity diagnostic was produced. */
+declare class NamespaceCompileError extends Error {
+    readonly diagnostics: CompilerDiagnostic[];
+    readonly name = "NamespaceCompileError";
+    constructor(diagnostics: CompilerDiagnostic[]);
+}
+
+/**
+ * Inject pass — bake policies into the lowered IR so the artifact is
+ * self-contained (plan §4 invariant: execution needs only IR + claims +
+ * variables):
+ *
+ *  - read policy AND-ed into every select/byPk/aggregate root `where`, every
+ *    relation subtree `where`, every aggregate `where`, and — via relation
+ *    subtrees — mutation `returning`;
+ *  - document-authored relationship predicates (exists/aggPredicate) get the
+ *    TARGET table's read policy injected too, so filtering through a link
+ *    can't become an existence oracle on rows the caller can't read;
+ *  - write policy AND-ed into update/delete row filters, and set as the
+ *    insert check for inserts (claims + inserted-values only in v2.0 — an
+ *    exists() write policy makes a table un-insertable, loudly);
+ *  - `col = claim(k)` AND-conjuncts of the write policy become pinned columns
+ *    merged into every inserted row (and excluded from insertable/settable).
+ */
+
+interface PinnedColumn {
+    column: string;
+    claim: ClaimKey;
+}
+/**
+ * Pins come from `col = claim(k)` comparisons the write policy fixes for EVERY
+ * caller, so the server can fill the column and drop it from the insert input.
+ *
+ *  - `and` contributes the UNION of its operands' pins: each conjunct must hold.
+ *  - `or` contributes their INTERSECTION on (column, claim): a policy with
+ *    variants is a permissive union (§4c), so only a pin present — and pinned
+ *    to the same claim — in every arm is fixed regardless of which arm admits
+ *    the caller. Pinning from one arm alone would silently narrow the others
+ *    (a `deals-admin` variant that only constrains `org` would lose the ability
+ *    to insert on another author's behalf).
+ *  - everything else (not/exists/capability/role/const/dynamic) pins nothing.
+ *
+ * A column left unpinned is not unprotected: it stays in the insert input and
+ * the same policy is enforced as the insert check, so a forged value is
+ * rejected with POLICY_CHECK_FAILED. Pinning is about removing the column from
+ * the client's reach, not about whether the rule is enforced.
+ */
+declare function collectPinnedColumns(writePolicy: PredIr): PinnedColumn[];
+declare function injectPolicies({ roots, ctx }: {
+    roots: RootIr[];
+    ctx: CompileContext;
+}): {
+    roots: RootIr[];
+    tableSet: string[];
+};
+
+/**
+ * Compiler-side naming — a thin adaptor over the CANONICAL naming authority,
+ * `src/sdl/naming.ts`. Every type/input/enum/scalar/root name the compiler
+ * resolves is derived from the same `tableNames`/`typeName` math the SDL
+ * generator emits (singularized PascalCase types, lowercase custom scalars),
+ * so the two surfaces can never skew. Pinned by
+ * `test/compiler/naming-parity.test.ts`.
+ */
+
+/**
+ * Artifact/link key for the built-in platform-users entity (plan §4b). This
+ * is the LOGICAL key (`artifact.tables['platformUsers']`, link targets) — the
+ * SQL identity of the backing relation is `platform.users_directory` (see
+ * `platformUserMeta` in context.ts).
+ */
+declare const PLATFORM_USER_TABLE = "platformUsers";
+
+/** GraphQL object type name for a table: `deal_comments` → `DealComment`. */
+declare function typeNameForTable(table: string): string;
+/** Query-root field names for a table — the SDL generator's own root names. */
+declare function queryRootNames(table: string): {
+    select: string;
+    byPk: string;
+    aggregate: string;
+};
+type MutationOp = 'insert' | 'insertOne' | 'update' | 'updateByPk' | 'delete' | 'deleteByPk';
+declare function mutationRootNames(table: string): Record<MutationOp, string>;
+/** Generated input type name for a table, e.g. ('deals', 'boolExp') → 'DealBoolExp'. */
+declare function inputTypeName(table: string, kind: InputRefKind): string;
+/**
+ * Map a GraphQL input/enum type name back to `{ input, table }` via the naming
+ * rules. Returns undefined when the name doesn't match a generated §4f type
+ * for any known table.
+ */
+declare function classifyInputType(name: string, tableByTypename: ReadonlyMap<string, string>): {
+    input: InputRefKind;
+    table: string;
+} | undefined;
+
+/**
+ * Compile context — everything derived from the canonical definition that the
+ * restrict/lower/inject passes need: per-table runtime metadata (TableMetaIr),
+ * the root-field and input-type name indexes, and the compiled read/write
+ * policies with their pinned columns.
+ */
+
+interface QueryRootInfo {
+    kind: 'select' | 'byPk' | 'aggregate';
+    table: string;
+}
+interface CrudMutationRootInfo {
+    op: MutationOp;
+    table: string;
+}
+/**
+ * A declared copy-on-write mutation root (canonical `cowMutations`). Carries
+ * everything lowering needs so the executor can generate the SQL — no
+ * authored statements anywhere in the pipeline.
+ */
+interface CowMutationRootInfo {
+    op: 'cowOverride' | 'cowRevert';
+    table: string;
+    /** Logical synced twin table (same namespace). */
+    synced: string;
+    /** Shared single-column primary-key property. */
+    pk: string;
+    /** Override: overlay properties written by the UPDATE. */
+    set: readonly string[];
+    /** Override: properties copied INSERT…SELECT from synced (pk included). */
+    copyColumns: readonly string[];
+}
+type MutationRootInfo = CrudMutationRootInfo | CowMutationRootInfo;
+interface CompileContext {
+    namespace: string;
+    tables: Record<string, TableMetaIr>;
+    /** GraphQL object type name → table name. */
+    tableByTypename: Map<string, string>;
+    queryRoots: Map<string, QueryRootInfo>;
+    mutationRoots: Map<string, MutationRootInfo>;
+    /** GraphQL enum type name → canonical enum (SelectColumn enums are NOT here). */
+    enumsByTypeName: Map<string, CanonicalEnum>;
+    readPolicies: Map<string, PredIr>;
+    /** Legacy combined write policy (mutation row filters when insert/update are absent). */
+    writePolicies: Map<string, PredIr>;
+    insertPolicies: Map<string, PredIr>;
+    updatePolicies: Map<string, PredIr>;
+    /** Per-table `col = claim(k)` insert-policy pins (insert-merged, non-insertable). */
+    pins: Map<string, PinnedColumn[]>;
+    /** Tables with both `insert` and `update` declared (no legacy `write`-only path). */
+    splitWritePolicyTables: ReadonlySet<string>;
+}
+/**
+ * §4b curated platform-users view — synthesized, never consumer-defined.
+ *
+ * The SQL identity (`schema`."`table`" — what the executor's tableFrag
+ * renders) is the hand-migrated view `platform.users_directory` (atlas
+ * migration 0481_platform_users_view.sql), NOT the logical artifact key
+ * `platformUsers` that links/tableSets/policies use. Must match
+ * atlas/src/server/services/orm/platform-users.ts EXACTLY — import-sharing is
+ * impossible across the package boundary, so the two are pinned by tests on
+ * both sides (test/compiler/compile-namespace.test.ts §4b and atlas
+ * platform-users.test.ts).
+ */
+declare function platformUserMeta(): TableMetaIr;
+interface BuildContextResult {
+    ctx: CompileContext;
+    diagnostics: CompilerDiagnostic[];
+}
+declare function buildCompileContext(rawCanonical: CanonicalDefinition): BuildContextResult;
+
+/**
+ * Parse pass — build the GraphQLSchema from SDL text and parse + validate the
+ * consumer's documents against it with graphql-js's spec rules. Validation
+ * failures become diagnostics (never thrown mid-pipeline) so every document
+ * reports at once.
+ */
+
+interface SourceDocument {
+    path: string;
+    contents: string;
+}
+interface ParsedDocument {
+    path: string;
+    document: DocumentNode;
+    operations: OperationDefinitionNode[];
+    /** Fragments are document-scoped — bios colocates them via TS interpolation. */
+    fragments: Map<string, FragmentDefinitionNode>;
+}
+declare function parseSdl(sdl: string): GraphQLSchema;
+interface ParseDocumentsResult {
+    documents: ParsedDocument[];
+    diagnostics: CompilerDiagnostic[];
+}
+declare function parseDocuments({ schema, documents, }: {
+    schema: GraphQLSchema;
+    documents: SourceDocument[];
+}): ParseDocumentsResult;
+
+/** Content hash of the canonical definition — the schema identity ops compile against. */
+declare function computeSchemaHash(canonical: CanonicalDefinition): string;
+interface ClientManifestOperation {
+    opHash: string;
+    kind: 'query' | 'mutation';
+    requires: CompiledOperation['requires'];
+}
+/** What codegen/the client transport needs: name → hash mapping + set identity. */
+interface ClientManifest {
+    namespace: string;
+    schemaHash: string;
+    opsHash: string;
+    operations: Record<string, ClientManifestOperation>;
+}
+interface CompileNamespaceInput {
+    canonical: CanonicalDefinition;
+    /** Generated SDL text (src/sdl once it lands; test-local SDL until then). */
+    sdl: string;
+    documents: SourceDocument[];
+}
+type CompileNamespaceResult = {
+    ok: true;
+    artifact: CompiledArtifact;
+    manifest: ClientManifest;
+    diagnostics: CompilerDiagnostic[];
+} | {
+    ok: false;
+    diagnostics: CompilerDiagnostic[];
+};
+declare function compileNamespace({ canonical, sdl, documents }: CompileNamespaceInput): CompileNamespaceResult;
+/** compileNamespace that throws on errors — for callers that want the v1-style hard failure. */
+declare function compileNamespaceOrThrow(input: CompileNamespaceInput): {
+    artifact: CompiledArtifact;
+    manifest: ClientManifest;
+    diagnostics: CompilerDiagnostic[];
+};
+/** Per-table `col = claim(k)` write-policy pins — exposed for SDL generation options. */
+declare function computePinnedColumnsByTable(canonical: CanonicalDefinition): Record<string, PinnedColumn[]>;
+
+/**
+ * Flatten pass — inline every fragment spread (and inline fragment) so the
+ * lowering pass sees one plain selection tree. The bios corpus uses flat,
+ * TS-interpolated fragments only; nested spreads still work here, but cycles
+ * and directives-on-spreads are rejected.
+ */
+
+declare function flattenOperation({ operation, fragments, }: {
+    operation: OperationDefinitionNode;
+    fragments: ReadonlyMap<string, FragmentDefinitionNode>;
+}): OperationDefinitionNode;
+
+/** Bump on any change to lowering semantics — invalidates every op hash. */
+declare const COMPILER_MAJOR = 1;
+/** Canonical print of one flattened operation (fragments already inlined). */
+declare function canonicalOperationText(definition: OperationDefinitionNode): string;
+declare function computeOpHash({ definition, schemaHash, }: {
+    definition: OperationDefinitionNode;
+    schemaHash: string;
+}): string;
+/** Order-independent set hash over the sorted op hashes. */
+declare function computeOpsHash(opHashes: readonly string[]): string;
+
+/**
+ * Restrict pass — the grammar gate that keeps operations inside the v2.0
+ * envelope BEFORE lowering:
+ *
+ *  - operations must be named (the op name keys the registry + manifest);
+ *  - no subscriptions (post-v1);
+ *  - every variable must be a scalar, a scalar list, a declared enum, OR one
+ *    of the §4f generated input types (BoolExp/OrderBy/SelectColumn/
+ *    InsertInput/SetInput/AppendInput/OnConflict) — mapped back to
+ *    `{ inputRef kind, table }` via the naming rules. Anything else gets a
+ *    targeted error naming what IS allowed.
+ *  - a declared default is validated here and persisted into the IR, so the
+ *    executor can apply it. A default the IR cannot carry faithfully is a
+ *    compile error rather than a value that silently becomes NULL.
+ */
+
+interface RestrictedOperation {
+    name: string;
+    kind: 'query' | 'mutation';
+    requires: CompiledOperation['requires'];
+    variables: VariableIr[];
+    definition: OperationDefinitionNode;
+}
+declare function restrictOperation({ operation, ctx, }: {
+    operation: OperationDefinitionNode;
+    ctx: CompileContext;
+}): RestrictedOperation;
+
+/**
+ * Lower pass — flattened GraphQL selection trees → IR. Document-authored
+ * argument literals lower to PredIr/OrderIr (variables allowed in leaf
+ * positions as ValueIr variables); whole-variable arguments become §4f
+ * dynamic slots keyed by the variable name. Policies are NOT injected here —
+ * see inject.ts (this pass emits document-only `where` shapes).
+ */
+
+declare const DEFAULT_LIMIT = 100;
+declare const MAX_LIMIT = 1000;
+declare class OperationLowerer {
+    private readonly ctx;
+    private readonly variables;
+    constructor(ctx: CompileContext, restricted: RestrictedOperation);
+    private meta;
+    private column;
+    private link;
+    private fieldCandidates;
+    /** Validate that a whole-variable argument is the declared §4f slot for this table. */
+    private slot;
+    private lowerValue;
+    lowerBoolExp(node: ValueNode, table: string): PredIr;
+    private lowerComparison;
+    /** Hasura aggregation predicate: `{ count: { predicate: { _gt: 2 }, filter: {…} } }`. */
+    private lowerAggPredicate;
+    lowerOrderBy(node: ValueNode, table: string): OrderIr[];
+    private lowerDirection;
+    lowerDistinctOn(node: ValueNode, table: string): string[] | {
+        slot: string;
+    };
+    private lowerLimit;
+    private lowerOffset;
+    lowerSelection(selectionSet: SelectionSetNode, table: string): SelectionIr;
+    /** The `{ aggregate { count sum {…} avg {…} } nodes {…} }` block shared by roots and relations. */
+    private lowerAggregateSelection;
+    lowerRoots(operation: OperationDefinitionNode, kind: 'query' | 'mutation'): RootIr[];
+    private parseRootDirectives;
+    private lowerQueryRoot;
+    /** byPk-style pk arguments: one argument per primary-key column, exactly. */
+    private lowerPkArgs;
+    private lowerMutationRoot;
+    /**
+     * Copy-on-write roots: flat args — the pk plus (override only) every
+     * declared set column. Overrides are full snapshots of the set columns, so
+     * every set argument must be supplied explicitly (pass null to clear a
+     * nullable column); the executor generates the copy/update/delete SQL from
+     * the structured fields, never from authored statements.
+     */
+    private lowerCowRoot;
+    private lowerMutationResponse;
+    private lowerInsertObjects;
+    private lowerInsertRow;
+    private lowerOnConflictArg;
+    private lowerWriteValues;
+    private lowerColumnEntries;
+    private lowerPkColumnsArg;
+}
+declare function lowerOperation({ restricted, ctx }: {
+    restricted: RestrictedOperation;
+    ctx: CompileContext;
+}): RootIr[];
+
+declare const CONST_TRUE: PredIr;
+/**
+ * AND predicates together, dropping `const(true)` operands so a policy-less
+ * table (or an absent document where) doesn't wrap everything in dead nodes.
+ */
+declare function andPred(...preds: Array<PredIr | undefined>): PredIr;
+declare function walkPred(pred: PredIr, visit: (node: PredIr) => void): void;
+declare function predContainsExists(pred: PredIr): boolean;
+/** Structural containment: does `haystack` carry `needle` as a subtree? */
+declare function predContains(haystack: PredIr, needle: PredIr): boolean;
+
+export { type BuildContextResult, COMPILER_MAJOR, CONST_TRUE, type ClientManifest, type ClientManifestOperation, type CompileContext, type CompileNamespaceInput, type CompileNamespaceResult, type CompilerDiagnostic, DEFAULT_LIMIT, type DiagnosticSeverity, DocumentCompileError, MAX_LIMIT, type MutationOp, type MutationRootInfo, NamespaceCompileError, OperationLowerer, PLATFORM_USER_TABLE, type ParseDocumentsResult, type ParsedDocument, type PinnedColumn, type QueryRootInfo, type RestrictedOperation, type SourceDocument, andPred, buildCompileContext, canonicalOperationText, classifyInputType, collectPinnedColumns, compileNamespace, compileNamespaceOrThrow, computeOpHash, computeOpsHash, computePinnedColumnsByTable, computeSchemaHash, flattenOperation, injectPolicies, inputTypeName, lowerOperation, mutationRootNames, parseDocuments, parseSdl, platformUserMeta, predContains, predContainsExists, queryRootNames, restrictOperation, typeNameForTable, walkPred };