graphddb 0.7.9 → 0.8.0

package/dist/linter/index.d.ts

@@ -1,8 +1,41 @@
-import { L as LintRule } from '../registry-CXhP4TaE.js';
-export { a as LintResult, b as Linter } from '../registry-CXhP4TaE.js';
-export { c as createDefaultLinter, g as gsiAmbiguityRule, m as missingGsiRule, n as noScanRule, q as queryBoundaryRule, r as relationDepthRule, a as requireLimitRule } from '../relation-depth-Dg3yhl7S.js';
-import '../maintenance-view-adapter-BATUh_I8.js';
-import '@aws-sdk/client-dynamodb';
+import { L as Linter, a as LintRule } from '../linter-C-vypgut.js';
+export { b as LintResult } from '../linter-C-vypgut.js';
+import '../types-BXLzIcQD.js';
+import '../key-DR7_lpyk.js';
+import '../types-2PMXEn5x.js';
+
+/**
+ * Creates a Linter pre-loaded with rules safe for Entity registration.
+ *
+ * Rules included: no-scan, require-limit, gsi-ambiguity, missing-gsi,
+ * relation-depth, same-partition-preset, plus the Epic #118 Phase 1 maintenance
+ * validators (issue #126): missing-context, 400kb, hot-partition, fan-out,
+ * multi-maintainer-same-row. The maintenance validators are no-ops for any
+ * relation that does not declare `write.maintainedOn`, so unannotated models are
+ * unaffected. query-boundary is excluded because it flags non-unique GSIs which
+ * are valid for list() operations; boundary enforcement is handled at runtime by
+ * the planner's boundary-check.
+ *
+ * Also includes cfn-schema-consistency (issue #169): a whole-table validator
+ * that rejects entities sharing a physical table with an ambiguous base
+ * KeySchema, inconsistently-shared GSI index names, or more than 20 unioned
+ * GSIs — the CFn deploy-consistency user-error class, caught statically at
+ * finalize. It is additive: a single entity on its own table with ≤ 20 GSIs is
+ * never affected.
+ */
+declare function createDefaultLinter(): Linter;
+
+declare const noScanRule: LintRule;
+
+declare const requireLimitRule: LintRule;
+
+declare const queryBoundaryRule: LintRule;
+
+declare const gsiAmbiguityRule: LintRule;
+
+declare const missingGsiRule: LintRule;
+
+declare const relationDepthRule: LintRule;
 
 /**
  * `samePartition` preset validator (Epic #118 child issue H).
@@ -123,4 +156,4 @@ declare const multiMaintainerSameRowRule: LintRule;
 
 declare const cfnSchemaConsistencyRule: LintRule;
 
-export { LintRule, cfnSchemaConsistencyRule, embeddedSnapshotSizeRule, fanOutRule, hotPartitionRule, missingContextRule, multiMaintainerSameRowRule, samePartitionPresetRule };
+export { LintRule, Linter, cfnSchemaConsistencyRule, createDefaultLinter, embeddedSnapshotSizeRule, fanOutRule, gsiAmbiguityRule, hotPartitionRule, missingContextRule, missingGsiRule, multiMaintainerSameRowRule, noScanRule, queryBoundaryRule, relationDepthRule, requireLimitRule, samePartitionPresetRule };

package/dist/linter/index.js

@@ -1,6 +1,3 @@
-import {
-  queryBoundaryRule
-} from "../chunk-MMVHOUM4.js";
 import {
   Linter,
   cfnSchemaConsistencyRule,
@@ -16,7 +13,28 @@ import {
   relationDepthRule,
   requireLimitRule,
   samePartitionPresetRule
-} from "../chunk-PDUVTYC5.js";
+} from "../chunk-XTWXMOHD.js";
+
+// src/linter/rules/query-boundary.ts
+var queryBoundaryRule = {
+  id: "query-boundary",
+  severity: "error",
+  check(metadata) {
+    const results = [];
+    for (const gsi of metadata.gsiDefinitions) {
+      if (!gsi.unique) {
+        results.push({
+          ruleId: "query-boundary",
+          severity: "error",
+          message: `GSI '${gsi.indexName}' on entity '${metadata.prefix}' is not marked as unique. Using query() on a non-unique GSI may return multiple items. Use list() instead, or mark the GSI as unique if it guarantees single results.`,
+          entity: metadata.prefix,
+          field: gsi.indexName
+        });
+      }
+    }
+    return results;
+  }
+};
 export {
   Linter,
   cfnSchemaConsistencyRule,

package/dist/{registry-CXhP4TaE.d.ts → linter-C-vypgut.d.ts}

@@ -1,24 +1,4 @@
-import { m as EntityMetadata } from './maintenance-view-adapter-BATUh_I8.js';
-
-interface LintRule {
-    id: string;
-    severity: 'error' | 'warning';
-    check(metadata: EntityMetadata, registry: typeof MetadataRegistry): LintResult[];
-}
-interface LintResult {
-    ruleId: string;
-    severity: 'error' | 'warning';
-    message: string;
-    entity: string;
-    field?: string;
-}
-
-declare class Linter {
-    private rules;
-    addRule(rule: LintRule): void;
-    run(metadata: EntityMetadata, registry: typeof MetadataRegistry): LintResult[];
-    runAll(registry: typeof MetadataRegistry): LintResult[];
-}
+import { E as EntityMetadata } from './types-BXLzIcQD.js';
 
 declare class MetadataRegistry {
     private static store;
@@ -73,4 +53,24 @@ declare class MetadataRegistry {
     private static handleLintResults;
 }
 
-export { type LintRule as L, MetadataRegistry as M, type LintResult as a, Linter as b };
+interface LintRule {
+    id: string;
+    severity: 'error' | 'warning';
+    check(metadata: EntityMetadata, registry: typeof MetadataRegistry): LintResult[];
+}
+interface LintResult {
+    ruleId: string;
+    severity: 'error' | 'warning';
+    message: string;
+    entity: string;
+    field?: string;
+}
+
+declare class Linter {
+    private rules;
+    addRule(rule: LintRule): void;
+    run(metadata: EntityMetadata, registry: typeof MetadataRegistry): LintResult[];
+    runAll(registry: typeof MetadataRegistry): LintResult[];
+}
+
+export { Linter as L, MetadataRegistry as M, type LintRule as a, type LintResult as b };

package/dist/prepared-artifact-BpPgkXEo.d.ts

@@ -0,0 +1,281 @@
+import { E as EntityMetadata } from './types-BXLzIcQD.js';
+import { C as ContractSpec, Q as QuerySpec, a as CommandSpec, T as TransactionSpec, b as ContextSpec, S as SPEC_VERSION, P as ParamSpec } from './types-2PMXEn5x.js';
+import { Q as QueryModelContract, k as QueryMethodSpec, l as CommandModelContract, m as CommandMethodSpec } from './key-DR7_lpyk.js';
+
+/**
+ * Contract-layer serialization (issue #59, CQRS Contract layer, Epic #57;
+ * spec `docs/cqrs-contract.md`, "SSoT Schema").
+ *
+ * The Contract IR (#58, `src/define/contract.ts`) holds, per contract method, a
+ * resolved declarative {@link ContractMethodOp} plus the **decided facts** the
+ * planner derived (`resolution` / `inputArity` / `result`). This module
+ * **serializes** those facts into the JSON SSoT — it does **not** re-derive them:
+ *
+ * - The `contracts` map (contract name → {@link ContractSpec}) is layered **on
+ *   top of** the existing `queries` / `commands` / `transactions`. Each method
+ *   references one of them by name (`ContractName__methodName`), so the existing
+ *   operation-spec shapes are unchanged and the current runtime keeps working.
+ * - The referenced operation spec is produced by **reusing** the proven
+ *   {@link buildQuerySpec} / {@link buildCommandSpec} planners: a
+ *   {@link ContractMethodOp} is translated back into the {@link AnyOperationDefinition}
+ *   shape those planners consume (the contract's sentinel references become the
+ *   `Param` placeholders the planner already understands), so the symbolic key
+ *   evaluation, projection, relation chaining, and condition handling are shared
+ *   — never re-implemented, never drifting.
+ *
+ * Everything emitted is **JSON-serializable** by construction (only strings /
+ * numbers / booleans / arrays / plain objects). A contract-free input emits no
+ * `contracts` / `contexts` keys, so the pre-#59 operations document is reproduced
+ * byte-for-byte (backward compatibility).
+ *
+ * ## What this issue serializes vs. defers
+ *
+ * The #58 IR captures a single declarative op per method with a boolean `select`
+ * projection; it does **not** model External Query / Query Composition (no
+ * `query(Contract.method, { from(...) })` primitive exists yet). So no #58
+ * contract produces a `compose`. The serializer nonetheless **supports** it: when
+ * a method op carries composition (a forward-compatible {@link ContractMethodOp}
+ * extension), it is emitted per the proposal's `compose` shape. The N+1 checker
+ * (#60), boundary lint (#61), and runtime execution (#62) are out of scope here —
+ * this is serialization + generator only.
+ */
+
+/**
+ * A contract as accepted by the serializer: either a resolved
+ * {@link QueryModelContract} or a {@link CommandModelContract} (the #58 factory
+ * output). The Key type is erased — the serializer reads the key **fields** off
+ * the resolved op / model metadata, not the phantom type.
+ */
+type AnyModelContract = QueryModelContract<unknown, Record<string, QueryMethodSpec<unknown, unknown, unknown>>> | CommandModelContract<unknown, Record<string, CommandMethodSpec<unknown, unknown, unknown>>>;
+/** A map of contract name → resolved contract IR (as passed to the generator). */
+type ContractMap = Record<string, AnyModelContract>;
+/**
+ * A context-ownership declaration as authored by the producer: context name →
+ * the Model (entity) and Contract names that belong to it. The serializer sorts
+ * the member lists deterministically; see {@link ContextSpec}.
+ */
+interface ContextOwnership {
+    readonly models?: readonly string[];
+    readonly contracts?: readonly string[];
+}
+/** A map of context name → its membership (as passed to the generator). */
+type ContextOwnershipMap = Record<string, ContextOwnership>;
+/**
+ * The output of {@link buildContracts}: the `contracts` map and the
+ * **synthesized** operation specs each method references. The caller merges the
+ * synthesized `queries` / `commands` / `transactions` into the document's
+ * existing maps (a contract method's referenced op lives alongside hand-written
+ * definitions, addressed by name).
+ */
+interface BuiltContracts {
+    readonly contracts: Record<string, ContractSpec>;
+    /** Synthesized read ops referenced by query contract methods. */
+    readonly queries: Record<string, QuerySpec>;
+    /** Synthesized write ops referenced by command contract methods (single form). */
+    readonly commands: Record<string, CommandSpec>;
+    /**
+     * Synthesized transactions referenced by command contract methods whose array
+     * form resolves to a `'transact'` batched write (issue #64). One transaction per
+     * such method, named `<Contract>__<method>__batch`: a single `forEach`-over-keys
+     * write item that the runtime expands once per key (≤25, atomic), reusing the
+     * proven declarative-transaction machinery (#46). Empty when no command method
+     * declares a `'transact'` batch.
+     */
+    readonly transactions: Record<string, TransactionSpec>;
+}
+/**
+ * The derived-effect family of one serialized prepared-write transaction item
+ * (issue #208). Index-aligned to `TransactionSpec.items`; the AOT loader groups
+ * rendered items by category ACROSS the plan's ops so the composed
+ * `TransactWriteItems` matches the in-process execution core's order
+ * (writes, then all edges, then all derived updates, …) byte-for-byte.
+ */
+type PreparedWriteItemCategory = 'base' | 'edge' | 'derive' | 'unique' | 'outbox' | 'idempotency' | 'maintain' | 'maintainOutbox' | 'check';
+/**
+ * Serialize a map of resolved contracts into the `contracts` SSoT map plus the
+ * synthesized operation specs each method references. Deterministic: contracts
+ * and methods are emitted in sorted-key order.
+ *
+ * @param contracts Contract name → resolved {@link QueryModelContract} /
+ *   {@link CommandModelContract} (the #58 factory output). Empty → empty output.
+ * @throws if a contract method op cannot be serialized (a non-boolean projection
+ *   slot, an unsupported write condition); or if a contract violates an N+1
+ *   safety rule (#60, {@link assertContractN1Safe}) — an array into a `range`
+ *   method, a "list under a list", or a `range` composed child.
+ */
+declare function buildContracts(contracts?: ContractMap): BuiltContracts;
+/**
+ * Serialize the context-ownership declarations into the SSoT `contexts` map.
+ * Member lists are sorted for determinism. An empty input yields an empty map
+ * (the caller then omits the key for backward compatibility).
+ */
+declare function buildContexts(contexts?: ContextOwnershipMap): Record<string, ContextSpec>;
+
+/**
+ * Static prepared-plan artifact — the SHARED, dependency-minimal half of the
+ * AOT pipeline (issue #208; layering fixed by #223).
+ *
+ * This module carries everything BOTH sides of the pipeline need:
+ *
+ * - the artifact shapes ({@link PreparedPlanDocument} and friends),
+ * - the format version ({@link PREPARED_FORMAT_VERSION}),
+ * - canonical JSON ({@link canonicalJson}) and the drift-detection
+ *   fingerprints ({@link entityFingerprint} / {@link planFingerprint}).
+ *
+ * ## Layering (#223)
+ *
+ * The dependency direction is strictly one-way:
+ *
+ * ```
+ * emitter (src/spec/prepared.ts, build-time)  ──▶  THIS MODULE
+ * loader  (src/runtime/prepared-loader.ts)    ──▶  THIS MODULE
+ * ```
+ *
+ * The loader must NEVER import the emitter: the emitter drags the whole
+ * build-time spec machinery into the runtime bundle (`dist/index.js`), which
+ * is exactly the leak the size-limit CI gate caught in #223. This module's
+ * only value-level dependencies are ones the loader already carries
+ * (`buildManifestEntity` / spec types).
+ *
+ * ## Fingerprints are checksums, not cryptography
+ *
+ * The fingerprint exists to detect DRIFT (model declarations changed since
+ * the artifact was generated). It is not a security boundary, so it uses a
+ * pure-TypeScript FNV-1a 64-bit hash — no `node:crypto`, no platform builtin,
+ * bundles everywhere. Switching the algorithm (sha-256 → FNV-1a) is what
+ * bumped {@link PREPARED_FORMAT_VERSION} '1' → '2': a format-'1' artifact's
+ * fingerprints can never match, so the loader rejects the version loudly
+ * instead of failing the comparison confusingly.
+ */
+
+/**
+ * The prepared-plan artifact format version (independent of {@link SPEC_VERSION}).
+ *
+ * '2' (#223): fingerprints are FNV-1a 64-bit over canonical JSON (16 hex
+ * chars). '1' (#208, graphddb ≤ 0.7.2) used sha-256 via `node:crypto`; the
+ * loader rejects '1' artifacts with a regeneration instruction.
+ */
+declare const PREPARED_FORMAT_VERSION: "2";
+/**
+ * One serialized value bind: a `$`-param slot (bound from the caller's
+ * `execute(params)` by name) or a static literal recorded at build time. `Date`
+ * and `bigint` literals — which JSON cannot carry natively — are encoded
+ * explicitly and revived by the loader, so the bound value is the SAME typed
+ * value the runtime `prepare` would have captured.
+ */
+type PreparedBindSpec = {
+    readonly param: string;
+} | {
+    readonly literal: string | number | boolean | null;
+} | {
+    readonly literalDate: string;
+} | {
+    readonly literalBigInt: string;
+};
+/** A `{ field: bind }` map (a serialized slot map). */
+type PreparedBindMap = Readonly<Record<string, PreparedBindSpec>>;
+/** One serialized read route of a prepared READ plan. */
+interface PreparedReadRouteSpec {
+    readonly alias: string;
+    readonly op: 'query' | 'list';
+    /** The target entity name (re-bound via the registry at load). */
+    readonly entity: string;
+    /** The static, params-independent select template (JSON-safe by the #206 lint). */
+    readonly select: Record<string, unknown>;
+    /** Key-field binds (`{ field: { param | literal } }`). */
+    readonly key: PreparedBindMap;
+    /** Static option literals decided at build time. */
+    readonly maxDepth?: number;
+    readonly order?: 'ASC' | 'DESC';
+    readonly filter?: Record<string, unknown>;
+    /** Dynamic option binds (a `$` param or a literal, decided per call). */
+    readonly consistentRead?: PreparedBindSpec;
+    readonly limit?: PreparedBindSpec;
+    readonly after?: PreparedBindSpec;
+    /**
+     * The spec-IR read plan (`operations.json` vocabulary: physical ops, templated
+     * `{<field>}` key conditions, relation fan-outs, execution plan) derived from
+     * this route at build time. Key-condition tokens are the entity's key FIELD
+     * names; the per-call param→field mapping is {@link key}. Deriving it at build
+     * time surfaces a broken route as a BUILD failure and freezes the physical
+     * plan for drift comparison.
+     */
+    readonly query: QuerySpec;
+}
+/** One serialized write op of a prepared WRITE plan. */
+interface PreparedWriteOpSpec {
+    readonly alias: string;
+    readonly entity: string;
+    readonly intent: 'create' | 'update' | 'remove' | 'upsert';
+    /** The target model's primary-key input fields (W1 key/changes split + read-back key). */
+    readonly keyFields: readonly string[];
+    /** Key-field binds. */
+    readonly key: PreparedBindMap;
+    /** Input-field binds. */
+    readonly input: PreparedBindMap;
+    /** In-process write-gate binds (flat equality / existence template), if declared. */
+    readonly condition?: PreparedBindMap;
+    /** The read-back projection + options, verbatim (JSON-safe by the #206 lint). */
+    readonly result?: {
+        readonly select?: Record<string, unknown>;
+        readonly options?: {
+            readonly consistentRead?: boolean;
+            readonly maxDepth?: number;
+        };
+    };
+    /**
+     * The consistent read-back's spec-IR plan (derived from `result.select` at
+     * build time — a broken read-back projection fails the BUILD). Present iff
+     * {@link result} declares a non-empty select.
+     */
+    readonly readback?: QuerySpec;
+    /**
+     * The op's full declarative {@link TransactionSpec}: `items[0]` is the base
+     * write, followed by every derived effect the mutation compiler resolved at
+     * build time. Templates bind `{<field>}` tokens — the op's key/input FIELD
+     * names — which the loader renders from the per-call bound field values.
+     */
+    readonly transaction: TransactionSpec;
+    /** Per-item derived-effect categories, index-aligned to `transaction.items`. */
+    readonly categories: readonly PreparedWriteItemCategory[];
+}
+/** One compiled prepared plan (all routes of one `DDBModel.prepare` body). */
+interface PreparedPlanSpec {
+    readonly kind: 'read' | 'write';
+    /**
+     * The `$` params the plan binds (union across routes), with kinds recovered
+     * from the bound entity fields where determinable.
+     */
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    /**
+     * Entity name → fingerprint of its canonical manifest entry at build time.
+     * The loader recomputes these from the live registry and LOUDLY rejects a
+     * mismatch (stale plan / model drift).
+     */
+    readonly entities: Readonly<Record<string, string>>;
+    /** Read routes, in body declaration order (read plans only). */
+    readonly reads?: readonly PreparedReadRouteSpec[];
+    /** Write ops, in body declaration order (write plans only). */
+    readonly writes?: readonly PreparedWriteOpSpec[];
+}
+/** The full static prepared-plan artifact. */
+interface PreparedPlanDocument {
+    readonly formatVersion: typeof PREPARED_FORMAT_VERSION;
+    /** The shared operation-IR version the plans were compiled against. */
+    readonly specVersion: typeof SPEC_VERSION;
+    /** Plan id (the transform's stable call-site id) → compiled plan. */
+    readonly plans: Readonly<Record<string, PreparedPlanSpec>>;
+}
+/** Deterministic JSON: object keys sorted at every level (arrays keep order). */
+declare function canonicalJson(value: unknown): string;
+/**
+ * The fingerprint of one entity's canonical manifest entry — every plan-relevant
+ * declaration fact (table, physical name, prefix, fields + formats, key / GSI
+ * templates, relations incl. `refs` bindings, TTL). Computed identically at
+ * build (emit) and at load (live registry), so any drift is caught.
+ */
+declare function entityFingerprint(metadata: EntityMetadata): string;
+/** Stable content hash of a compiled plan (drift-check convenience). */
+declare function planFingerprint(plan: PreparedPlanSpec): string;
+
+export { type AnyModelContract as A, type BuiltContracts as B, type ContractMap as C, type PreparedWriteOpSpec as P, type PreparedPlanDocument as a, type PreparedBindSpec as b, type PreparedPlanSpec as c, type PreparedReadRouteSpec as d, type ContextOwnershipMap as e, type ContextOwnership as f, PREPARED_FORMAT_VERSION as g, type PreparedBindMap as h, buildContexts as i, buildContracts as j, canonicalJson as k, entityFingerprint as l, planFingerprint as p };