graphddb 0.6.0 → 0.7.1

package/dist/{registry-DbqmFyab.d.ts → registry-BndKbZbg.d.ts}

@@ -1,4 +1,4 @@
-import { m as EntityMetadata } from './maintenance-view-adapter-CFeasCKo.js';
+import { m as EntityMetadata } from './maintenance-view-adapter-NBTZbE8-.js';
 
 interface LintRule {
     id: string;

package/dist/{relation-depth-0TiWr5OW.d.ts → relation-depth-CCGHLTOv.d.ts}

@@ -1,4 +1,4 @@
-import { b as Linter, L as LintRule } from './registry-DbqmFyab.js';
+import { b as Linter, L as LintRule } from './registry-BndKbZbg.js';
 
 /**
  * Creates a Linter pre-loaded with rules safe for Entity registration.

package/dist/spec/index.d.ts

@@ -1,4 +1,4 @@
-export { $ as BridgeBundle, a1 as CommandContractMethodSpec, a2 as CommandResolutionTarget, L as CommandSpec, a3 as CompiledFragment, a4 as CompiledMutationPlan, a5 as ComposeSpec, a6 as CompositionPlanSpec, a0 as ConditionSpec, O as ContextSpec, a7 as ContractCardinality, a8 as ContractCommandResult, a9 as ContractInputArity, aa as ContractKeySpec, ab as ContractKind, ac as ContractResolution, J as ContractSpec, ad as DerivedConditionCheck, ae as DerivedEdgeWrite, af as DerivedIdempotencyGuard, ag as DerivedMaintainOutbox, ah as DerivedMaintainWrite, ai as DerivedOutboxEvent, aj as DerivedUniqueGuard, ak as DerivedUpdate, al as EntityRefResolver, am as ExecutionPlanSpec, an as FilterSpec, ao as MAX_TRANSACT_COMPOSE_ITEMS, _ as Manifest, ap as ManifestEntity, aq as ManifestField, ar as ManifestFieldType, as as ManifestGsi, at as ManifestKey, au as ManifestRelation, av as ManifestTable, aw as OperationSpec, Y as OperationsDocument, ax as ParamSpec, ay as QueryContractMethodSpec, K as QuerySpec, az as RangeConditionSpec, aA as ReadOperationType, aB as SPEC_VERSION, aC as TransactionItemSpec, aD as TransactionItemType, N as TransactionSpec, aE as WhenSpec, aF as WriteOperationType, aG as assertNoCrossFragmentMaintainCollision, aH as compileFragment, aI as compileMutationPlan, aJ as compileSingleFragmentPlan, aK as resetMaintenanceGraphCache, aL as resolveLifecycle, aM as resolveMaintainers } from '../maintenance-view-adapter-CFeasCKo.js';
-export { A as AnyModelContract, B as BuiltContracts, C as ContextOwnership, a as ContextOwnershipMap, b as ContractBoundaryViolation, c as ContractInputs, d as ContractMap, e as ContractN1Violation, o as assertBundleSerializable, p as assertContractBoundaries, q as assertContractN1Safe, r as assertJsonSerializable, s as assertSupportedCondition, t as buildBridgeBundle, u as buildContexts, v as buildContracts, w as buildManifest, x as buildOperations, y as buildQuerySpec, z as buildTransactionSpec, D as buildTransactions, E as collectContractBoundaryViolations, F as collectContractN1Violations } from '../index-CtJbTrfB.js';
-import '../registry-DbqmFyab.js';
+export { a2 as BridgeBundle, a4 as CommandContractMethodSpec, a5 as CommandResolutionTarget, H as CommandSpec, a6 as CompiledFragment, a7 as CompiledMutationPlan, a8 as ComposeSpec, a9 as CompositionPlanSpec, a3 as ConditionSpec, J as ContextSpec, aa as ContractCardinality, ab as ContractCommandResult, ac as ContractInputArity, ad as ContractKeySpec, ae as ContractKind, af as ContractResolution, A as ContractSpec, ag as DerivedConditionCheck, ah as DerivedEdgeWrite, ai as DerivedIdempotencyGuard, aj as DerivedMaintainOutbox, ak as DerivedMaintainWrite, al as DerivedOutboxEvent, am as DerivedUniqueGuard, an as DerivedUpdate, ao as EntityRefResolver, ap as ExecutionPlanSpec, aq as FilterSpec, ar as MAX_TRANSACT_COMPOSE_ITEMS, a1 as Manifest, as as ManifestEntity, at as ManifestField, au as ManifestFieldType, av as ManifestGsi, aw as ManifestKey, ax as ManifestRelation, ay as ManifestTable, az as OperationSpec, $ as OperationsDocument, L as ParamSpec, aA as QueryContractMethodSpec, G as QuerySpec, aB as RangeConditionSpec, aC as ReadOperationType, K as SPEC_VERSION, aD as TransactionItemSpec, aE as TransactionItemType, I as TransactionSpec, aF as WhenSpec, aG as WriteOperationType, aH as assertNoCrossFragmentMaintainCollision, aI as compileFragment, aJ as compileMutationPlan, aK as compileSingleFragmentPlan, aL as resetMaintenanceGraphCache, aM as resolveLifecycle, aN as resolveMaintainers } from '../maintenance-view-adapter-NBTZbE8-.js';
+export { A as AnyModelContract, B as BuiltContracts, C as ContextOwnership, b as ContextOwnershipMap, c as ContractBoundaryViolation, d as ContractInputs, e as ContractMap, f as ContractN1Violation, O as PREPARED_FORMAT_VERSION, Q as PreparedBindMap, g as PreparedBindSpec, a as PreparedPlanDocument, h as PreparedPlanSpec, i as PreparedReadRouteSpec, P as PreparedWriteOpSpec, s as assertBundleSerializable, t as assertContractBoundaries, u as assertContractN1Safe, v as assertJsonSerializable, w as assertSupportedCondition, x as buildBridgeBundle, y as buildContexts, z as buildContracts, D as buildManifest, E as buildOperations, R as buildPreparedPlanDocument, F as buildQuerySpec, G as buildTransactionSpec, H as buildTransactions, S as canonicalJson, I as collectContractBoundaryViolations, J as collectContractN1Violations, U as compilePreparedPlan, V as entityFingerprint, X as planFingerprint } from '../index-CvS9ATKB.js';
+import '../registry-BndKbZbg.js';
 import '@aws-sdk/client-dynamodb';

package/dist/spec/index.js

@@ -1,5 +1,6 @@
 import {
   MAX_TRANSACT_COMPOSE_ITEMS,
+  PREPARED_FORMAT_VERSION,
   SPEC_VERSION,
   assertBundleSerializable,
   assertContractBoundaries,
@@ -12,22 +13,28 @@ import {
   buildContracts,
   buildManifest,
   buildOperations,
+  buildPreparedPlanDocument,
   buildQuerySpec,
   buildTransactionSpec,
   buildTransactions,
+  canonicalJson,
   collectContractBoundaryViolations,
   collectContractN1Violations,
   compileFragment,
   compileMutationPlan,
+  compilePreparedPlan,
   compileSingleFragmentPlan,
+  entityFingerprint,
+  planFingerprint,
   resetMaintenanceGraphCache,
   resolveLifecycle,
   resolveMaintainers
-} from "../chunk-N5NQM3SO.js";
+} from "../chunk-C5Q2NMRW.js";
 import "../chunk-F2DI3GTI.js";
 import "../chunk-PDUVTYC5.js";
 export {
   MAX_TRANSACT_COMPOSE_ITEMS,
+  PREPARED_FORMAT_VERSION,
   SPEC_VERSION,
   assertBundleSerializable,
   assertContractBoundaries,
@@ -40,14 +47,19 @@ export {
   buildContracts,
   buildManifest,
   buildOperations,
+  buildPreparedPlanDocument,
   buildQuerySpec,
   buildTransactionSpec,
   buildTransactions,
+  canonicalJson,
   collectContractBoundaryViolations,
   collectContractN1Violations,
   compileFragment,
   compileMutationPlan,
+  compilePreparedPlan,
   compileSingleFragmentPlan,
+  entityFingerprint,
+  planFingerprint,
   resetMaintenanceGraphCache,
   resolveLifecycle,
   resolveMaintainers

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { n as Executor, D as DynamoDBOperation, o as ReadExecOptions, p as ExecutorResult, q as BatchGetExecInput, P as PutInput, W as WriteExecOptions, r as WriteResult, s as UpdateInput, t as DeleteInput, u as BatchWriteExecItem, v as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, w as DDBModel, c as ChangeEvent } from '../maintenance-view-adapter-CFeasCKo.js';
+import { n as Executor, D as DynamoDBOperation, o as ReadExecOptions, p as ExecutorResult, q as BatchGetExecInput, P as PutInput, W as WriteExecOptions, r as WriteResult, s as UpdateInput, t as DeleteInput, u as BatchWriteExecItem, v as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, w as DDBModel, c as ChangeEvent } from '../maintenance-view-adapter-NBTZbE8-.js';
 import '@aws-sdk/client-dynamodb';
 
 /**

package/dist/transform/index.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Compile-time hoist transform + no-runtime-capture build lint for
+ * `DDBModel.prepare` (issue #206, design #203 — phase 2 on top of the phase-1
+ * runtime in `src/runtime/prepared.ts`).
+ *
+ * ## What it does
+ *
+ * A **source-to-source** pass (TypeScript compiler API, purely syntactic — no
+ * type checker, no module loading) over user source files:
+ *
+ *  1. **Detect** every `DDBModel.prepare(fn)` call site (through import aliases,
+ *     namespace imports, module-const aliases, and same-file `extends DDBModel`
+ *     subclasses).
+ *  2. **Statically verify no-runtime-capture** — the design's key constraint
+ *     (#203): the body may reference only its own `$` parameter (per-call
+ *     values) and **module-static** bindings (imports, module-scope `const` /
+ *     `class` / `function` / `enum` — the `() => Model` refs). Any reference to
+ *     an enclosing function's binding (a parameter, an outer `let` / `const`,
+ *     `this`), any mutable module state (`let` / `var`), any call / `new` /
+ *     conditional / computed expression inside the body — including **indirect
+ *     capture via helper calls** — is a **loud build error**.
+ *  3. **Hoist** each verified inline call site: the call expression is wrapped
+ *     into a module-scope **lazy memoization slot** —
+ *
+ *     ```ts
+ *     let __gddbPrepared1;                       // module scope, after imports
+ *     // ... inside the hot function, the call site becomes:
+ *     (__gddbPrepared1 ??= DDBModel.prepare(($) => ({ ... }))).execute(params)
+ *     ```
+ *
+ *     so the body is evaluated and the plan compiled **exactly once** for the
+ *     module (first call), and every subsequent call is a single nullish check
+ *     straight into `.execute` — **zero per-op planning / compiling / structure
+ *     hashing**, identical to a hand-hoisted module-level handle.
+ *
+ * ## Why a lazy slot and not an eager module `const`
+ *
+ * `prepare()` resolves its `() => Model` thunks immediately. An eager
+ * `const __p = DDBModel.prepare(...)` hoisted above a `class User` declared
+ * later in the same file would hit the TDZ at module init; hoisted below it, a
+ * mid-file IIFE could still observe the TDZ. The lazy slot keeps the original
+ * expression **lexically in place** (every reference resolves exactly as
+ * before) and defers the one-time compile to the first call — the same moment
+ * the untransformed code would have compiled it. Evaluation ORDER and error
+ * timing are therefore identical to the untransformed build for the first
+ * call, and per-op cost is zero afterwards. Results are identical by
+ * construction: the transform never rewrites the body, only memoizes the
+ * handle (which the phase-1 runtime already guarantees is reusable — that is
+ * what its structural-memoization fallback relies on).
+ *
+ * ## The static lint: a declarative whitelist, transitively applied
+ *
+ * Rather than trying to enumerate the infinite ways a per-call value can leak
+ * into the body (blacklisting), the lint accepts only the **declarative
+ * grammar** the prepared runtime itself accepts — everything else is a loud
+ * error:
+ *
+ *  - object / array literals (non-computed keys), string / number / boolean /
+ *    bigint / `null` literals, no-substitution template literals, unary `+`/`-`
+ *    on numeric literals, `as` / `satisfies` / parenthesized wrappers;
+ *  - `$.<name>` — exactly one property level on the body's own parameter
+ *    (deeper access is rejected, mirroring the runtime proxy);
+ *  - identifiers / property chains that resolve to **module-static** bindings
+ *    (imports, module `const` / `class` / `function` / `enum`). A module-const
+ *    initializer referenced from a body (a shared select template, a
+ *    module-const alias) is **transitively linted** against the same
+ *    whitelist, so an indirect capture through a same-file "helper constant"
+ *    is caught;
+ *  - zero-parameter arrows / functions whose body is a single reference chain
+ *    to a module-static binding (the `() => Model` refs).
+ *
+ * Rejected (loud, with the precise source position): references that resolve
+ * to an **enclosing function scope** (direct capture — parameters, outer
+ * `let`/`const`/`var`); module-scope `let` / `var` (mutable module state — a
+ * hoisted body would freeze it, an inline body would not; results MUST match);
+ * **any call or `new` expression** (a helper call is an indirect-capture
+ * channel the pass cannot see through, and even a pure-looking global like
+ * `Date.now()` is a fresh per-call value); unresolved (global) identifiers;
+ * conditionals / binary operators / substitution templates / computed keys
+ * (per-call control flow); `this`; bodies that are not statically visible
+ * functions (a body passed through a variable of function scope, a call
+ * result).
+ *
+ * ### Known limits (documented, backstopped at runtime)
+ *
+ * The pass is per-file and syntactic. Two things it cannot prove:
+ *
+ *  - a binding **imported from another module** is accepted as module-static
+ *    (that is the design's allowance — `() => Model` refs are imports); a
+ *    pathological mutable re-exported `let`, or a cross-module template
+ *    object mutated elsewhere, is not visible per-file;
+ *  - mutation of a same-file module-const **object** between calls.
+ *
+ * Both are backstopped by the phase-1 **runtime** no-capture guard
+ * (`assertNoRuntimeCapture` — only `$`-refs and scalar static literals are
+ * bindable value leaves), so a per-call object smuggled through module state
+ * still rejects loudly at runtime; and by the fact that the transform never
+ * changes results — an unhoistable site left untransformed falls back to the
+ * phase-1 structural-memoization path (correct, merely warmer).
+ */
+/** Diagnostic codes emitted by the lint / transform pass. */
+type PreparedDiagnosticCode = 
+/** A reference to an enclosing function's binding (direct per-call capture). */
+'runtime-capture'
+/** A reference to module-scope `let` / `var` (mutable module state). */
+ | 'mutable-module-state'
+/** An unresolved (global / ambient) identifier — not `$`, not module-static. */
+ | 'non-static-reference'
+/** A call / `new` inside the body — the indirect-capture channel. */
+ | 'call-in-body'
+/** A non-declarative expression (conditional, binary op, template subst, …). */
+ | 'impure-expression'
+/** `$.<a>.<b>` — deeper than the single supported property level. */
+ | 'param-deep-access'
+/** The `prepare` argument is not a statically visible function body. */
+ | 'unverifiable-body'
+/** Informational: an inline call site the transform hoists (check mode). */
+ | 'hoistable'
+/** Informational (#208 --aot check mode): a `DDBModel.prepare` call site not
+ * yet rewritten to the static-plan loader (`--aot … --write` rewrites it). */
+ | 'aot-pending';
+/** One lint / transform diagnostic, positioned in the original source. */
+interface PreparedDiagnostic {
+    readonly code: PreparedDiagnosticCode;
+    readonly category: 'error' | 'note';
+    readonly message: string;
+    readonly file: string;
+    /** 1-based line in the ORIGINAL source text. */
+    readonly line: number;
+    /** 1-based column in the ORIGINAL source text. */
+    readonly column: number;
+}
+/** Result of {@link transformPreparedSource} on one source file. */
+interface PreparedTransformResult {
+    readonly fileName: string;
+    /** The transformed source (identical to the input when nothing changed). */
+    readonly text: string;
+    readonly changed: boolean;
+    /** Inline call sites normalized to a module lazy slot in THIS run. */
+    readonly hoistedCount: number;
+    /** Call sites already evaluated once per module load (left as-is). */
+    readonly moduleScopeCount: number;
+    /** Call sites already normalized by a previous run (idempotence). */
+    readonly alreadyHoistedCount: number;
+    readonly diagnostics: readonly PreparedDiagnostic[];
+    /** Count of `category: 'error'` diagnostics (a build gate: non-zero fails). */
+    readonly errorCount: number;
+}
+interface PreparedTransformOptions {
+    /**
+     * `transform` (default) verifies AND rewrites; `lint` only verifies (the
+     * build-lint gate) and reports inline call sites as `hoistable` notes.
+     */
+    readonly mode?: 'transform' | 'lint';
+}
+/** The identifier prefix used for generated module lazy slots. */
+declare const HOIST_SLOT_PREFIX = "__gddbPrepared";
+/**
+ * Lint (and, in `transform` mode, hoist-normalize) every `DDBModel.prepare`
+ * call site in one source file. See the module doc for the full contract.
+ */
+declare function transformPreparedSource(fileName: string, sourceText: string, options?: PreparedTransformOptions): PreparedTransformResult;
+/**
+ * The build-lint gate: verify no-runtime-capture on every `DDBModel.prepare`
+ * body in the file WITHOUT rewriting. Inline (hoistable) call sites are
+ * reported as `hoistable` notes so a build can surface silent-slow fallbacks.
+ */
+declare function lintPreparedSource(fileName: string, sourceText: string): readonly PreparedDiagnostic[];
+/** The local identifier the rewrite binds `loadPreparedPlan` to. */
+declare const AOT_LOADER_LOCAL = "__gddbLoadPreparedPlan";
+/** The local identifier the rewrite binds the artifact document to. */
+declare const AOT_PLANS_LOCAL = "__gddbPreparedPlans";
+/** The named export of an evaluation shim: `{ <siteIndex>: <bodyFn> }`. */
+declare const AOT_SHIM_EXPORT = "__gddbAotBodies";
+/** One discovered prepared call site (either form), verified and numbered. */
+interface PreparedAotSite {
+    /** 1-based document-order index within the file. */
+    readonly index: number;
+    /** The stable plan id: `<planIdPrefix>#<index>`. */
+    readonly planId: string;
+    /** `prepare` (original form) or `aot` (already rewritten). */
+    readonly form: 'prepare' | 'aot';
+}
+/** The per-file result of the AOT pass. */
+interface PreparedAotFileResult {
+    readonly fileName: string;
+    /** The rewritten source (identical to the input in check mode / no change). */
+    readonly text: string;
+    readonly changed: boolean;
+    readonly sites: readonly PreparedAotSite[];
+    /**
+     * The evaluation-shim module source (present when the file has ≥1 verified
+     * site and no violations). Importing it yields `{ [AOT_SHIM_EXPORT]:
+     * Record<siteIndex, PreparedBody> }`.
+     */
+    readonly shimSource?: string;
+    readonly diagnostics: readonly PreparedDiagnostic[];
+    readonly errorCount: number;
+}
+interface PreparedAotOptions {
+    /** `transform` rewrites call sites; `check` only discovers + lints (drift mode). */
+    readonly mode: 'transform' | 'check';
+    /** The plan-id prefix — the project-relative source path (POSIX separators). */
+    readonly planIdPrefix: string;
+    /** The module specifier the rewrite imports the artifact document from. */
+    readonly artifactImport: string;
+}
+/**
+ * The #208 AOT pass over one source file: discover + verify every prepared call
+ * site (both forms), assign stable plan ids, build the evaluation shim, and (in
+ * `transform` mode) rewrite `DDBModel.prepare` sites to the static-plan loader.
+ * See the section header above for the full contract.
+ */
+declare function transformPreparedSourceAot(fileName: string, sourceText: string, options: PreparedAotOptions): PreparedAotFileResult;
+
+export { AOT_LOADER_LOCAL, AOT_PLANS_LOCAL, AOT_SHIM_EXPORT, HOIST_SLOT_PREFIX, type PreparedAotFileResult, type PreparedAotOptions, type PreparedAotSite, type PreparedDiagnostic, type PreparedDiagnosticCode, type PreparedTransformOptions, type PreparedTransformResult, lintPreparedSource, transformPreparedSource, transformPreparedSourceAot };