graphddb 0.7.10 → 0.8.1

package/dist/internal/index.d.ts

@@ -0,0 +1,84 @@
+import { P as PreparedWriteOpSpec, a as PreparedPlanDocument } from '../prepared-artifact-HFealr1q.js';
+export { b as PreparedBindSpec, c as PreparedPlanSpec, d as PreparedReadRouteSpec } from '../prepared-artifact-HFealr1q.js';
+import { M as Manifest } from '../types-2PMXEn5x.js';
+import { M as ModelStatic, D as DDBModel, S as Slot, P as PreparedWriteExecOptions, C as CommandReturn, a as ParallelOpResult, b as PreparedBody, c as PreparedStatement } from '../key-DZtjAQDh.js';
+import '../types-DW__-Icc.js';
+
+/**
+ * Static prepared-plan LOADER (issue #208) — the runtime half of the AOT
+ * pipeline. `graphddb transform prepared --aot` compiles every verified
+ * `DDBModel.prepare` body at BUILD time into a {@link PreparedPlanDocument}
+ * (`src/spec/prepared.ts`) and rewrites the call site to
+ *
+ * ```ts
+ * (__gddbPrepared1 ??= loadPreparedPlan(__gddbPreparedPlans, '<id>', ($) => ({…})))
+ * ```
+ *
+ * This module loads that artifact: it re-binds each plan's entity NAMES against
+ * the live {@link MetadataRegistry}, verifies the plan is not stale, and returns
+ * a handle whose `execute` runs the very same execution cores the runtime
+ * `prepare` uses — with **zero plan construction / compilation per op, including
+ * the first call**:
+ *
+ * - a **read** plan binds into the SAME {@link PreparedReadStatement} the
+ *   runtime `prepare` returns (identical semantics by construction — reads never
+ *   had an expensive compile; what `prepare` computes once, the artifact
+ *   carries);
+ * - a **write** plan's mutation compile (lifecycle resolution + derived-effect
+ *   derivation — the expensive half) happened at BUILD time; `execute` renders
+ *   the serialized templates and runs {@link executeLogicalWriteOps} /
+ *   {@link executeLogicalParallelWrites} — the same W1–W5 / fast-path / atomic
+ *   commit / read-back pipeline as the compiled core, so effects are identical.
+ *
+ * ## Stale plans are a LOUD reject
+ *
+ * Each plan records a fingerprint of every entity's canonical manifest entry at
+ * build time. On first use the loader recomputes the fingerprints from the live
+ * registry: a mismatch (the model declarations — key/GSI templates, fields,
+ * relations, table mapping — changed since the artifact was generated) throws
+ * with a regeneration hint. A stale static plan NEVER executes. Version-skewed
+ * artifacts (format / spec IR version) reject the same way.
+ *
+ * ## Laziness
+ *
+ * Binding is deferred to the FIRST `execute` (not the `loadPreparedPlan` call):
+ * a module-scope `const p = loadPreparedPlan(…)` must not touch the registry at
+ * module-init time (the target models may be declared later in the same module —
+ * the same TDZ hazard the #206 lazy slot solves). Binding is memoized per
+ * `(document, planId)`; it performs registry lookups + fingerprint hashing only,
+ * never plan compilation.
+ */
+
+interface BoundWriteOp {
+    readonly alias: string;
+    readonly spec: PreparedWriteOpSpec;
+    readonly modelClass: Function;
+    readonly modelStatic: ModelStatic<DDBModel>;
+    readonly keySlots: Readonly<Record<string, Slot>>;
+    readonly inputSlots: Readonly<Record<string, Slot>>;
+    readonly conditionSlots?: Readonly<Record<string, Slot>>;
+    readonly manifest: Manifest;
+}
+/** A prepared WRITE handle bound from a static plan (#208). `execute(params)`
+ * mirrors {@link import('./prepared.js').PreparedWriteStatement.execute}. */
+declare class AotPreparedWriteStatement {
+    private readonly ops;
+    /** @internal */
+    constructor(ops: readonly BoundWriteOp[]);
+    execute(params?: Record<string, unknown>, options?: PreparedWriteExecOptions): Promise<Record<string, CommandReturn | undefined> | Record<string, ParallelOpResult | ParallelOpResult[]>>;
+}
+/**
+ * Load one statically-compiled prepared plan (issue #208). The rewritten call
+ * site passes the artifact document, the stable plan id, and the ORIGINAL
+ * prepare body — the body is retained in source as the plan's compile source
+ * (drift regeneration + type inference + the untransformed-build fallback) and
+ * is NEVER evaluated here: execution consumes the static artifact only.
+ *
+ * Per-op plan construction / compilation is ZERO, including the first call —
+ * the first `execute` performs registry binding + stale-fingerprint
+ * verification only (memoized per `(document, planId)`), then every call binds
+ * params into the frozen plan and runs the shared execution cores.
+ */
+declare function loadPreparedPlan(doc: PreparedPlanDocument, planId: string, body?: PreparedBody): PreparedStatement;
+
+export { AotPreparedWriteStatement, PreparedPlanDocument, PreparedWriteOpSpec, loadPreparedPlan };