graphddb 0.7.9 → 0.8.0

package/dist/types-BXLzIcQD.d.ts

@@ -0,0 +1,450 @@
+import { d as SegmentedKey, e as ProjectionTransform, f as MaintainEvent, g as ProjectionMap, h as MaintainConsistency, i as MaintainUpdateMode, E as EffectPath, j as MembershipPredicate } from './key-DR7_lpyk.js';
+
+type DynamoType = 'S' | 'N' | 'BOOL' | 'B' | 'SS' | 'NS' | 'L' | 'M';
+interface FieldOptions {
+    format?: 'datetime' | 'date';
+    readonly?: boolean;
+    serialize?: (value: unknown) => unknown;
+    deserialize?: (value: unknown) => unknown;
+    /**
+     * Optional human-readable description of the field (issue #154). Pure
+     * documentation metadata — it does NOT affect storage, hydration, key handling,
+     * or any runtime behaviour. When present it is propagated to the field entry in
+     * `manifest.json` ({@link ManifestField.description}) and surfaces as a field
+     * comment in the generated Python `types.py`. Absent → byte-for-byte unchanged
+     * output (backward compatible).
+     */
+    description?: string;
+}
+interface FieldMetadata {
+    propertyName: string;
+    dynamoType: DynamoType;
+    options?: FieldOptions;
+    /**
+     * For a `@literal(...)` field — a `string`-stored field whose value is one of a
+     * known, finite set — the allowed literal values, in declaration order (issue
+     * #75). Recorded purely as model metadata so a Contract param bound into the
+     * field can recover the precise `literal` param-kind from its bind position
+     * (`src/spec/contracts.ts`), serializing as `{ type: 'literal', literals: [...] }`
+     * instead of the imprecise `'string'`. JSON-safe by construction (a non-empty
+     * array of strings). `undefined` for every other field decorator (`@string`,
+     * `@number`, …), so plain fields are byte-for-byte unchanged (backward compat).
+     */
+    literals?: readonly string[];
+    /**
+     * For an `@ttl` field (issue #172, Epic #167 — CFn generator C4) — marks this
+     * field as the model's **DynamoDB Time-To-Live** attribute. `@ttl` is a
+     * standalone semantic decorator pinned to `number` (it records `dynamoType: 'N'`
+     * itself, so `@ttl expiresAt!: string` is a compile error), because DynamoDB TTL
+     * requires a Number attribute holding **epoch seconds**. It is a **physical
+     * schema** fact (unlike the maintenance signals kept off the manifest): the flag
+     * flows through {@link EntityMetadata} into `manifest.json`
+     * ({@link ManifestEntity.ttlAttribute}), which the CloudFormation emitter consumes
+     * to render `TimeToLiveSpecification`. DynamoDB allows exactly one TTL attribute
+     * per table, enforced loudly at model registration (`@model`). `undefined` for
+     * every other field decorator, so non-TTL fields are byte-for-byte unchanged.
+     */
+    ttl?: boolean;
+}
+
+/**
+ * The maintenance kind of a model (issue #152). `'entity'` (the default) is a plain
+ * stored entity. `'materializedView'` / `'sparseView'` mark a model as a maintained
+ * **view** row whose `@maintainedFrom` declarations feed the maintenance graph (the
+ * adapter that replaces the old `defineView` / `ViewRegistry` path). A `sparseView`
+ * requires every `@maintainedFrom` to carry a `when` membership predicate.
+ */
+type ModelKind = 'entity' | 'materializedView' | 'sparseView';
+/**
+ * One lowered `@maintainedFrom(source, (self, source) => options)` declaration on a
+ * view model (issue #152). It is the decorator-declarative replacement for one
+ * `defineView` source slice: the symbolic `(self, source) =>` callback has already
+ * been evaluated into the SAME payload-rooted IR (`keyBind` → `$.entity.*` key
+ * binding, `project` → {@link ProjectionMap}), so the adapter
+ * (`src/relation/maintenance-view-adapter.ts`) reconstructs a byte-identical
+ * `ViewSourceSlice` from it.
+ *
+ * `collection` and `when` are mutually exclusive (a row either holds a maintained
+ * list or appears/disappears as a whole — the same rule the old builder enforced).
+ */
+interface MaintainedFromMetadata {
+    /** Resolves the source entity whose lifecycle events maintain the view row. */
+    sourceFactory: () => new (...args: unknown[]) => unknown;
+    /** The lifecycle events that maintain the view row (`created`/`updated`/`removed`). */
+    on: readonly MaintainEvent[];
+    /** The view-row key binding (view-row key field → payload-rooted source value). */
+    keyBind: Readonly<Record<string, EffectPath>>;
+    /** The projection of the source payload into the view row (target attr → transform). */
+    project: ProjectionMap;
+    /** Bounded/ordered collection options when this declaration maintains a list. */
+    collection?: {
+        /** The view-row attribute that holds the maintained list (a `self.<field>`). */
+        field: string;
+        maxItems?: number;
+        order?: 'ASC' | 'DESC';
+        /** The source value the collection orders by / trims on (`$.entity.<field>`). */
+        orderBy?: EffectPath;
+    };
+    /** Sparse-view membership predicate (mutually exclusive with `collection`). */
+    when?: MembershipPredicate;
+    consistency?: MaintainConsistency;
+    updateMode?: MaintainUpdateMode;
+    /**
+     * Optional human-readable description of this maintained-from source slice (issue
+     * #166, follow-up of #154), supplied via
+     * `@maintainedFrom(() => Source, (self, source) => ({ description, ... }))`. Pure
+     * documentation metadata — it does NOT affect the maintenance IR (`keyBind` /
+     * `project` / `on` / `collection` / `when`) or any runtime behaviour.
+     *
+     * NOTE (representation): the maintenance IR is deliberately kept OFF the
+     * serializable `manifest.json` / `operations.json` — the {@link Manifest} carries
+     * only the physical shape (table / keys / GSIs / relation navigation), NOT the
+     * maintenance graph (see `detectStreamMaintenance` in `src/codegen/cloudformation.ts`).
+     * There is therefore no manifest / operations / generated-Python site for a
+     * maintained-from source; this description is captured at the metadata layer only
+     * (mirroring where #154 captured its descriptions before propagation), available to
+     * any future consumer that DOES surface `@maintainedFrom` (e.g. the CDC-projection
+     * typed-consumer path, #153). Absent → byte-for-byte unchanged metadata.
+     */
+    description?: string;
+}
+interface KeyDefinition {
+    /** The canonical structured key (PK/SK segment lists). */
+    segmented: SegmentedKey;
+    inputFieldNames: string[];
+}
+interface GsiDefinition {
+    indexName: string;
+    /** The canonical structured key (PK/SK segment lists). */
+    segmented: SegmentedKey;
+    inputFieldNames: string[];
+    unique: boolean;
+    /**
+     * Optional human-readable description of the GSI (issue #166, follow-up of #154),
+     * supplied via `gsi(name, key, { description })`. Pure documentation metadata — it
+     * does NOT affect the index key, projection, or any runtime behaviour. When present
+     * it is propagated to the index entry in `manifest.json`
+     * ({@link ManifestGsi.description}) and surfaces as the docstring of any generated
+     * Python query method that reads through this index (a query carrying the GSI's
+     * `indexName`, when the query itself declares no description). Absent →
+     * byte-for-byte unchanged output (backward compatible).
+     */
+    description?: string;
+}
+interface RelationLimitOptions {
+    default: number;
+    max: number;
+}
+/**
+ * The named maintenance pattern a relation participates in (Epic #118 §5.1).
+ *
+ * `pattern` is the *preset* selector: omitting it leaves the relation a plain
+ * read-only navigation (the historical `hasMany`/`belongsTo`/`hasOne`
+ * behaviour), exactly backward compatible. When present it names the AWS
+ * design pattern the relation lowers to — the lowering itself (maintenance
+ * graph / compile injection) is out of scope for issue #121 and lands in
+ * #124/#125; here the value is recorded purely as declaration metadata.
+ *
+ * Typed as a `string` union of the known presets but kept open-ended via the
+ * `(string & {})` tail so a future preset can be authored before this union is
+ * widened, without a breaking change to callers.
+ *
+ * The union lists only the presets that are actually *reachable* as a recorded
+ * `RelationOptions.pattern` / `AggregateOptions.pattern` value: `samePartition`,
+ * `counter`, `embeddedSnapshot`, and the two versioned discriminators
+ * `versionedLatest` / `versionedHistory` (issue #152). `materializedView` /
+ * `sparseView` migrated to the model-level `@model({ kind })` selector (they are
+ * a {@link ModelKind}, not a relation preset); the placeholder `edge` /
+ * `dualEdge` / `versioned` / `externalProjection` names are not authored anywhere
+ * and were removed. A future preset can still be written against the `(string & {})`
+ * tail before it is added to this union.
+ */
+type RelationPattern = 'samePartition' | 'counter' | 'embeddedSnapshot' | 'versionedLatest' | 'versionedHistory' | (string & {});
+/**
+ * Consistency boundary a maintained write is declared against (Epic #118 §4.A.7):
+ * `transactional` = same `TransactWriteItems`; `eventual` = asynchronous catch-up.
+ */
+type RelationConsistency = 'transactional' | 'eventual';
+/**
+ * How a maintained write is applied (Epic #118 §4.A.7):
+ * `mutation` = composed into the same mutation; `stream` = driven asynchronously
+ * off a stream / outbox.
+ */
+type RelationUpdateMode = 'mutation' | 'stream';
+/**
+ * Read-strategy hints for a maintained relation (Epic #118 §5.1 `read`).
+ *
+ * All fields optional — present only when a `pattern` declares a read shape
+ * (e.g. an `embeddedSnapshot` keeping the latest N items). A bare relation
+ * carries no `read` block.
+ */
+interface RelationReadOptions {
+    /** Cap on materialised items kept inline (e.g. "latest 3 posts"). */
+    maxItems?: number;
+    /** Ordering of the maintained collection. */
+    order?: 'ASC' | 'DESC';
+}
+/**
+ * Write-maintenance declaration for a relation (Epic #118 §5.1 `write`).
+ *
+ * `maintainedOn` is the cross-entity trigger list (`"<Entity>.<event>"`, e.g.
+ * `"Post.created"`) that the maintenance graph (#124/#125) will key off. Recorded
+ * here as declaration metadata only.
+ */
+interface RelationWriteOptions {
+    /**
+     * Cross-entity triggers, e.g. `['Post.created', 'Post.removed']`. The event
+     * segment is the confirmed shared lifecycle vocabulary (epic #118 A/B
+     * reconciliation): `created` / `updated` / `removed`.
+     */
+    maintainedOn?: string[];
+    consistency?: RelationConsistency;
+    updateMode?: RelationUpdateMode;
+}
+/**
+ * Snapshot / projection capture map for a maintained relation
+ * (Epic #118 §5.1 / §5.2 `projection`).
+ *
+ * Maps each captured field name on the maintaining side to **how** the source
+ * value is projected. The confirmed shared vocabulary (epic #118 A/B
+ * reconciliation) is the **function-form IR** — the same {@link
+ * ProjectionTransform} node A (#120) defines on `src/define/entity-writes.ts`,
+ * re-used here (NOT re-defined) so the two surfaces never re-diverge. Each value
+ * is either:
+ *
+ * - a {@link ProjectionTransform} (built with the standalone authoring helpers,
+ *   e.g. `preview('body', 120)` — RFC §5.2 `textPreview: preview('body', 120)`),
+ *   or
+ * - a bare `string` — the **identity shorthand**: project that source path
+ *   through unchanged (e.g. `{ postId: 'postId' }`).
+ *
+ * `Readonly` so the recorded declaration metadata is not mutated downstream.
+ * Issue #121 scopes this to the declaration shape; the maintenance graph /
+ * compile injection that consumes the IR is #124/#125.
+ *
+ * @example `{ postId: 'postId', textPreview: preview('body', 120) }`
+ */
+type RelationProjection = Readonly<Record<string, ProjectionTransform | string>>;
+interface RelationOptions {
+    limit?: RelationLimitOptions;
+    order?: 'ASC' | 'DESC';
+    /**
+     * Optional human-readable description of the relation (issue #166, follow-up of
+     * #154), supplied via `@hasMany/@belongsTo/@hasOne(() => T, keyBind, { description })`.
+     * Pure documentation metadata — it does NOT affect navigation, key binding, or any
+     * runtime behaviour. When present it is propagated to the relation entry in
+     * `manifest.json` ({@link ManifestRelation.description}) and surfaces as a trailing
+     * `# …` comment on the relation's field in the generated Python result TypedDict /
+     * dataclass. Absent → byte-for-byte unchanged output (backward compatible).
+     */
+    description?: string;
+    /**
+     * Named maintenance preset (Epic #118). Omitted = plain read-only navigation,
+     * fully backward compatible with the historical relation decorators.
+     */
+    pattern?: RelationPattern;
+    read?: RelationReadOptions;
+    write?: RelationWriteOptions;
+    projection?: RelationProjection;
+    /**
+     * Lowered versioned-pattern declaration (issue #152, section B). Present only when
+     * the relation declares `pattern: 'versionedLatest' | 'versionedHistory'` via the
+     * `@hasOne/@hasMany(() => Target, (self, source) => ({...}))` callback form. The
+     * declaring model is the SOURCE (a revision); the relation target is the
+     * DESTINATION view row. The adapter
+     * (`src/relation/maintenance-view-adapter.ts`) lowers this to the SAME `defineView`
+     * snapshot IR the old `defineVersioned` produced (latest = overwrite, history =
+     * append). `on` are the lifecycle events; `project` is the lowered projection map.
+     */
+    versioned?: {
+        readonly mode: 'latest' | 'history';
+        readonly on: readonly MaintainEvent[];
+        readonly project: ProjectionMap;
+        readonly consistency?: MaintainConsistency;
+        readonly updateMode?: MaintainUpdateMode;
+    };
+}
+/**
+ * Descriptor for a `refs` relation (issue #197, Pattern 2 Embedded Refs read
+ * side). A `refs` relation resolves an **inline id-list** held on the parent row
+ * — e.g. `PPost.tagRefs: { tagId: string }[]` — into the referenced child
+ * bodies, in ONE deduped `BatchGetItem` (never per-ref `GetItem`).
+ *
+ * Unlike `hasMany`/`belongsTo`/`hasOne`, whose key is bound from a parent
+ * **scalar** field ({@link RelationMetadata.keyBinding} — `target key ← parent
+ * scalar`), a `refs` key is bound from EACH ELEMENT of a parent LIST attribute:
+ * the traversal reads `parent[from]` (a list), pulls `.key` off every element,
+ * and fans those out into a single BatchGet against the target. This descriptor
+ * captures exactly that list-valued source shape, which the scalar `keyBinding`
+ * `Record<string,string>` cannot express.
+ *
+ * `keyBinding` on a `refs` relation still records the **target child key field ←
+ * element key name** mapping (e.g. `{ tagId: 'tagId' }`), so key building /
+ * projection reuse the existing scalar machinery per resolved element; `refs`
+ * only adds *where the scalar values come from* (the parent list), not a new key
+ * grammar. That keeps `refs` byte-compatible with every scalar-keyBinding
+ * consumer (manifest, planner, dedupe) — an unknown-to-them relation kind is
+ * simply carried through with a valid scalar `keyBinding`.
+ */
+interface RefsBinding {
+    /** The parent LIST attribute holding the inline reference elements (e.g. `'tagRefs'`). */
+    from: string;
+    /** The key field to read off EACH list element (e.g. `'tagId'`). */
+    key: string;
+}
+interface RelationMetadata {
+    type: 'hasMany' | 'hasOne' | 'belongsTo' | 'refs';
+    propertyName: string;
+    targetFactory: () => new (...args: unknown[]) => unknown;
+    keyBinding: Record<string, string>;
+    /**
+     * List-valued source descriptor for a `refs` relation (issue #197). Present
+     * IFF `type === 'refs'`; the traversal reads the parent list `refs.from`, pulls
+     * `refs.key` off each element, and resolves the referenced child bodies in one
+     * deduped BatchGet. Absent for every scalar-keyed relation (byte-compatible).
+     */
+    refs?: RefsBinding;
+    options?: RelationOptions;
+}
+/**
+ * The scalar-aggregate value an `@aggregate` field derives from its source entity
+ * (Epic #118 §5.2 counter / latest preset; issue #122). It is the function-form
+ * IR built by the {@link count} / {@link max} value helpers — the aggregation an
+ * `@aggregate(() => Source, keyBinding, { pattern, value })` field maintains:
+ *
+ * - `count` — the cardinality of source rows matched by the key binding (no
+ *   source field; e.g. `postCount!: number` ← `count()`).
+ * - `max` — the maximum value of a named source `field` (e.g. `lastPostAt!:
+ *   string` ← `max('createdAt')`).
+ *
+ * Recorded purely as declaration metadata (issue #122 scope = declaration
+ * surface): the maintenance graph (#124) / compile injection (#125) consume it;
+ * the effect itself is out of scope here. Kept open-ended via the discriminated
+ * `op` so a future aggregation (`min`, `sum`, …) extends the union without a
+ * breaking change.
+ *
+ * @example `count()` → `{ op: 'count' }`
+ * @example `max('createdAt')` → `{ op: 'max', field: 'createdAt' }`
+ */
+type AggregateValue = {
+    readonly op: 'count';
+} | {
+    readonly op: 'max';
+    readonly field: string;
+};
+/**
+ * Options for an `@aggregate` field (Epic #118 §5.2 counter / latest preset;
+ * issue #122). Mirrors the maintenance vocabulary a relation declares so the two
+ * authoring surfaces stay in lockstep:
+ *
+ * - `pattern` reuses {@link RelationPattern} (e.g. `'counter'`) — the named
+ *   maintenance preset, NOT re-defined here.
+ * - `value` is the {@link AggregateValue} the field maintains (`count()` /
+ *   `max('createdAt')`).
+ * - `write` reuses {@link RelationWriteOptions} verbatim — `maintainedOn`
+ *   triggers (`Post.created` / `Post.removed`, the confirmed shared
+ *   `created|updated|removed` event vocabulary) plus `consistency`
+ *   (`transactional|eventual`) / `updateMode` (`mutation|stream`). These are NOT
+ *   re-defined; they are the same shared types B (#121) added.
+ */
+interface AggregateOptions {
+    /** Named maintenance preset (typically `'counter'`); reuses {@link RelationPattern}. */
+    pattern?: RelationPattern;
+    /** The scalar aggregation this field maintains (`count()` / `max('createdAt')`). */
+    value: AggregateValue;
+    /** Cross-entity maintenance triggers / consistency / update-mode (reused from B). */
+    write?: RelationWriteOptions;
+}
+/**
+ * Declaration metadata recorded by an `@aggregate` field decorator (issue #122).
+ *
+ * An `@aggregate` is a **scalar** field (`postCount!: number`,
+ * `lastPostAt!: string`) whose value is derived — by aggregating rows of a source
+ * entity resolved by {@link targetFactory} + {@link keyBinding} — rather than
+ * stored directly. It is therefore recorded in its **own** metadata array
+ * (`EntityMetadata.aggregates`), distinct from both {@link FieldMetadata} (a
+ * plain stored attribute) and {@link RelationMetadata} (a navigation yielding
+ * model instances): an aggregate carries a source binding like a relation, but
+ * surfaces a scalar value like a field. The collector path mirrors relations
+ * (decorator pushes, `@model` drains).
+ *
+ * Issue #122 scope is the declaration surface + metadata pass-through only; the
+ * aggregation effect's compile / runtime (#124/#125/#127) is out of scope.
+ */
+interface AggregateMetadata {
+    /** The scalar field the aggregate value is written to. */
+    propertyName: string;
+    /** Resolves the source entity whose rows are aggregated. */
+    targetFactory: () => new (...args: unknown[]) => unknown;
+    /** The key binding selecting the source rows (target key field → source field). */
+    keyBinding: Record<string, string>;
+    /** The aggregate preset / value / maintenance-write declaration. */
+    options: AggregateOptions;
+}
+interface EmbeddedMetadata {
+    propertyName: string;
+    modelFactory: () => new (...args: unknown[]) => unknown;
+}
+interface EntityMetadata {
+    tableName: string;
+    prefix: string;
+    fields: FieldMetadata[];
+    primaryKey: KeyDefinition | null;
+    gsiDefinitions: GsiDefinition[];
+    relations: RelationMetadata[];
+    /** Scalar `@aggregate` fields (Epic #118 §5.2 counter / latest; issue #122). */
+    aggregates: AggregateMetadata[];
+    embeddedFields: EmbeddedMetadata[];
+    /**
+     * The model's maintenance kind (issue #152). `'entity'` (default; also assumed
+     * when absent, for hand-built metadata in tests) is a plain stored entity;
+     * `'materializedView'` / `'sparseView'` mark it a maintained view row fed by
+     * {@link maintainedFrom}.
+     */
+    kind?: ModelKind;
+    /**
+     * Optional human-readable description of the entity (issue #154), supplied via
+     * `@model({ description })`. Pure documentation metadata — it does NOT affect
+     * storage, keys, or any runtime behaviour. When present it is propagated to the
+     * entity entry in `manifest.json` ({@link ManifestEntity.description}) and
+     * surfaces as the class docstring in the generated Python `types.py`. Absent →
+     * byte-for-byte unchanged output (backward compatible).
+     */
+    description?: string;
+    /**
+     * Class-level `@maintainedFrom(...)` declarations (issue #152). Non-empty only on
+     * a `materializedView` / `sparseView` model; each is one source slice the view
+     * row is maintained from. The adapter lowers these to the maintenance graph's
+     * `ViewDefinition` IR (replacing the old `defineView` / `ViewRegistry` path).
+     * Absent / empty for a plain entity.
+     */
+    maintainedFrom?: MaintainedFromMetadata[];
+    /**
+     * Whether the model is flagged **CDC-parseable** by `@cdcProjected()` (issue
+     * #153). It carries NO runtime side effect — it is purely a compile-/registration-
+     * time capability marker: `Model.fromChange(event)` (and, transitively,
+     * `DDBModel.subscribe` routing to this model) is gated on it, and it is the SSoT
+     * the codegen reads to emit the `CdcModelRegistry` module augmentation that types
+     * `subscribe`'s handlers by model name. `true` only on a model carrying the
+     * decorator; absent (⇒ falsy) for every plain entity, so a non-`@cdcProjected`
+     * model is byte-for-byte unchanged (backward compatible). Deliberately kept OFF
+     * the manifest / bridge (it is a host-runtime + TS-typing concern, like the
+     * maintenance signals — not a physical-schema fact like {@link ttlAttribute}).
+     */
+    cdcProjected?: boolean;
+    /**
+     * The physical attribute name of the model's `@ttl` field, when one is declared
+     * (issue #172, Epic #167 — CFn generator C4). DynamoDB TTL requires a single
+     * Number attribute holding epoch seconds; `@model` derives this from the (unique)
+     * field carrying {@link FieldMetadata.ttl} and throws if more than one field on the
+     * SAME model is `@ttl` (the cross-entity, same-physical-table single-TTL rule is
+     * enforced downstream, at manifest build, where all entities on a table are known).
+     * A non-key field's physical attribute name is its property name, so this is the
+     * `@ttl` field's property name. Propagated to the manifest
+     * ({@link ManifestEntity.ttlAttribute}) — the SSoT the CloudFormation emitter reads
+     * to render `TimeToLiveSpecification`. Absent when the model declares no `@ttl`.
+     */
+    ttlAttribute?: string;
+}
+
+export type { AggregateOptions as A, DynamoType as D, EntityMetadata as E, FieldOptions as F, ModelKind as M, RelationOptions as R, AggregateValue as a };

package/docs/cdc-projection.md

@@ -80,7 +80,7 @@ A valid event for this model always has at least one non-null side, so `[null, n
 is an unambiguous "this event is not for this model" signal. You don't need a separate
 guard — `fromChange` does routing **and** parse in one call.
 
-### 3. `DDBModel.subscribe(handlers)` — declarative, batch
+### 3. `graphddb.subscribe(handlers)` — declarative, batch
 
 The third sibling of `query` / `mutate` (GraphQL's query / mutation / **subscription**).
 It takes a handler map keyed by model name. Unlike `query` / `mutate`, which hit
@@ -89,7 +89,7 @@ DynamoDB, **`subscribe` does not subscribe**: it *returns* a `ChangeHandler`
 
 ```ts
 // graphddb side: build a batch handler that parses + routes + dispatches (no sink, no dedup)
-const handler = DDBModel.subscribe({
+const handler = graphddb.subscribe({
   OrderModel: (old, neu) => {        // old, neu: OrderModel | null (typed via the generated registry)
     if (!neu) return opensearch.delete({ id: old!.orderId });
     return opensearch.index({ id: neu.orderId, body: { status: neu.status } });
@@ -138,9 +138,9 @@ inferred from the key.
 
 | GraphQL | DDBModel | Executed by | Returns |
 | --- | --- | --- | --- |
-| query | `DDBModel.query(envelope)` | graphddb (hits DynamoDB) | result object |
-| mutation | `DDBModel.mutate(envelope)` | graphddb (hits DynamoDB) | result object |
-| subscription | `DDBModel.subscribe(handlers)` | **you** (mount it) | `ChangeHandler` |
+| query | `graphddb.query(envelope)` | graphddb (hits DynamoDB) | result object |
+| mutation | `graphddb.mutate(envelope)` | graphddb (hits DynamoDB) | result object |
+| subscription | `graphddb.subscribe(handlers)` | **you** (mount it) | `ChangeHandler` |
 
 Only subscription is "executed by you, returns a handler rather than a result" —
 because CDC delivery lives outside the boundary.

package/docs/class-hydration.md

@@ -267,7 +267,7 @@ serialized query/`OperationSpec`, or `operations.json`. This is the same rule
 `#50` (middleware) and `updatable` / `consistentRead` already follow.
 
 - **The declarative layer is "what to fetch."** `operations.json` is generated
-  from *contract definitions* (`publicQueryModel`, etc.) — key, select, filter,
+  from *contract definitions* (`publishQuery`, etc.) — key, select, filter,
   projection, result paths, cardinality, execution plan. It is the serializable,
   language-neutral plan the Python runtime (`#48`) replays. It already contains
   **none** of the host-runtime call options: a `grep` of

package/docs/cqrs-contract.md

@@ -83,7 +83,9 @@ field list argument. The access pattern — primary key or GSI — is resolved f
 the `Model` plus the `key` fields named in the descriptor:
 
 ```ts
-const UserByEmail = publicQueryModel({
+import { graphddb, param } from 'graphddb';
+
+const UserByEmail = graphddb.publishQuery({
   get: { query: User, key: { email: param.string() }, select: { userId: true, email: true } },
 });
 ```
@@ -95,7 +97,7 @@ key, select, options? }`, with exactly one of `query` / `list`. `select` and
 `options` are separate keys (no `select` nested inside `options`).
 
 ```ts
-export const ArticleById = publicQueryModel({
+export const ArticleById = graphddb.publishQuery({
   get: { query: Article, key: { articleId: param.string() },
          select: { articleId: true, title: true, body: true },
          options: { consistentRead: false } },
@@ -193,7 +195,7 @@ write-use-case Methods. A command method is a single declarative write
 result?, mode? }`, with exactly one of `create` / `update` / `remove`.
 
 ```ts
-export const UserCommands = publicCommandModel({
+export const UserCommands = graphddb.publishCommand({
   disable: { update: User, key: { userId: param.string() },
              input: { status: 'disabled', disableReason: param.string() },
              result: { select: { userId: true, status: true } } },
@@ -214,7 +216,7 @@ export const UserCommands = publicCommandModel({
   **or** a raw `cond\`…\`` fragment whose value slots may be `param.*` bindings:
 
   ```ts
-  export const UserCommands = publicCommandModel({
+  export const UserCommands = graphddb.publishCommand({
     // declarative operators in a write condition
     promote: { update: User, key: { userId: param.string() },
                input: { role: 'admin' },
@@ -276,7 +278,7 @@ read dependency, declared with the `query($ => ({...}))` builder; a cross-
 fragment reference uses `$.alias.field`:
 
 ```ts
-export const AccountAccess = publicQueryModel({
+export const AccountAccess = graphddb.publishQuery({
   get: query($ => ({
     account: { query: Account, key: { accountId: param.string() },
                select: { accountId: true } },
@@ -361,7 +363,8 @@ single-model lint framework.
 
 A method body is evaluated at definition time with throwing sentinels in place
 of `keys` / `params`, recorded through a model recorder, and subjected to the
-same hardening `defineTransaction` applies:
+same no-runtime-capture build-time hardening the prepared-statement compiler
+applies:
 
 1. **Throwing sentinel Proxy** — any property / method access other than the
    internal brand reads or primitive coercion throws at the access site.
@@ -489,31 +492,36 @@ input produces a byte-identical pre-contract document).
 
 ## Public API surface
 
-Definition DSL (`src/define/contract.ts`):
+Definition DSL (`src/define/contract.ts`) — import the `graphddb` namespace
+(`import { graphddb } from 'graphddb'`); `graphddb.publishQuery` /
+`graphddb.publishCommand` are the sole read/write authoring surface:
 
 ```ts
-publicQueryModel({ alias: { query | list: Model, key, select, options? } })
-publicCommandModel({ alias: { create | update | remove: Model, key, input, condition?, result?, mode? } })
-query($ => ({ alias: descriptor, ... }))           // composite read; cross-fragment refs $.alias.field
-mutation($ => ({ alias: descriptor, ... }))         // composite write; cross-fragment refs $.alias.field
+graphddb.publishQuery({ alias: { query | list: Model, key, select, options? } })
+graphddb.publishCommand({ alias: { create | update | remove: Model, key, input, condition?, result?, use?, mode? } })
 param.string() / param.number() / ...               // descriptor key/input parameters
 ```
 
-Runtime (`src/runtime/*`):
+A query method may compose another query contract's method (cross-fragment refs
+via `$.alias.field`); a command descriptor composes its derived write ops and
+maintenance writes into one plan. These are declared inside the
+`publishQuery` / `publishCommand` map — there is no separate public `query()` /
+`mutation()` composite verb (removed in 0.8.0).
 
-```ts
-executeQueryMethod(contract, methodName, key | keys[], params?)    // contract-runtime
-executeCommandMethod(contract, methodName, key | keys[], params?)  // command-runtime
-encodePerKeyCursor / decodePerKeyCursor / serializeContractKey     // per-key-cursor
-```
+Execution is the two `graphddb.*` verbs (`graphddb.query` / `graphddb.mutate`) —
+they route contract methods through the in-process runtime.
 
-Build / static analysis (`src/spec/*`):
+The contract runtime (`executeQueryMethod` / `executeCommandMethod` /
+per-key-cursor helpers, `src/runtime/*`) is **internal** machinery behind those
+verbs — not a public export.
+
+Build / static analysis is the advanced `graphddb/spec` subpath:
 
 ```ts
+import { buildContracts, buildContexts } from 'graphddb/spec';
+
 buildContracts(contracts)                  // → { contracts, queries, commands, transactions }
 buildContexts(contexts)                    // → context-ownership specs
-assertContractN1Safe(name, spec, isGsiPoint?)
-assertContractBoundaries(...)              // context-boundary lint
 ```
 
 ## Query vs Command

package/docs/design-patterns.md

@@ -542,11 +542,11 @@ GSI). *Dual-edge form* — declare `w.dualEdge(forward, inverse)` on the forward
 keep a **two-row** bidirectional edge in sync without an inverse GSI. The dual edge can
 be recorded in either of two write vocabularies carrying the SAME `w.dualEdge`:
 
-- **`entityWrites` (recommended when driving through the command / mutation IF, #195)** —
+- **`entityWrites` (recommended when driving through the command IF, #195)** —
   place `w.dualEdge(...)` in a lifecycle's `edges` array. The dual edge is then derived by
-  `executeCommandMethod` / `DDBModel.mutate`, so a `mutation` over the edge maintains BOTH
-  rows in the SAME atomic transaction with no low-level handwork. Use this form if the edge
-  is created / removed through a command.
+  the command runtime behind `graphddb.publishCommand` / `graphddb.mutate`, so a write over
+  the edge maintains BOTH rows in the SAME atomic transaction with no low-level handwork. Use
+  this form if the edge is created / removed through a command.
 - **`edgeWrites` (the low-level edge-only primitive)** — the historical adjacency-only
   `writes` member. Same two-row synchronization, but driven through the low-level edge-write
   path rather than the command IF.
@@ -626,7 +626,7 @@ actual sink write happens inside the consumer's CDC infrastructure, outside grap
 That runtime was **removed in 0.4.0** (issue #152). External projection is now a
 **typed-consumer-IF contract** (issue #153): mark the source model with
 `@cdcProjected()`, then parse a CDC change event into typed instances — `Model.fromChange(event)`
-returns `[oldRecord, newRecord]`, and `DDBModel.subscribe(handlers)` (the GraphQL-style
+returns `[oldRecord, newRecord]`, and `graphddb.subscribe(handlers)` (the GraphQL-style
 sibling of `query` / `mutate`) returns a `ChangeHandler` the consumer mounts on its own
 stream. graphddb owns the *parse → typed record* contract; subscription, sink delivery,
 and idempotency stay with the consumer. See [`cdc-projection.md`](./cdc-projection.md)

package/docs/docs-generation.md

@@ -40,15 +40,15 @@ graphddb generate docs --entry models.ts --out doc.md
   `<dir>/index.md` (backward compatible). Either way the command prints a JSON
   result (`{"status":"ok","outDir":…,"files":[…]}`) to stdout, where `files`
   reports the written path(s).
-- **`--queries`** (optional) points at the module exporting your `queries` /
-  `commands` (the `defineQueries` / `defineCommands` maps). It powers the Access
-  Patterns and Mutation Contracts sections; omit it and those sections are empty.
-  Defaults to the entry module.
+- **`--contracts`** (optional) points at the module exporting your `contracts`
+  map (the `graphddb.publishQuery` / `graphddb.publishCommand` results). It powers
+  the Access Patterns and Mutation Contracts sections; omit it and those sections
+  are empty. Defaults to the entry module.
 
 To also document your access patterns and mutations:
 
 ```bash
-graphddb generate docs --entry models.ts --queries definitions.ts --out docs/
+graphddb generate docs --entry models.ts --contracts contracts.ts --out docs/
 ```
 
 ## Output sections
@@ -78,7 +78,7 @@ flag (PITR, table class, encryption) render as `as configured at deployment`.
 | --- | --- | --- |
 | `--entry <file>` | (required) | Entry module registering the entity models. |
 | `--out <path>` | (required) | Output path. A `*.md` file is written verbatim at that path; any other value is a directory and `index.md` is written inside it. |
-| `--queries <file>` | entry module | Module exporting `queries` / `commands` for Access Patterns / Mutation Contracts. |
+| `--contracts <file>` | entry module | Module exporting the `contracts` map for Access Patterns / Mutation Contracts. |
 | `--format <format>` | `markdown` | Output format (only `markdown` today). |
 | `--split <mode>` | `none` | `none` emits a single `index.md`. `entity` is reserved for a future per-entity split. |
 | `--template-dir <dir>` | — | Directory of override `<partial>.hbs` templates. |