graphddb 0.7.10 → 0.8.0

package/dist/{types-BQLzTEqh.d.ts → types-2PMXEn5x.d.ts}

@@ -8,7 +8,7 @@
  *
  * - the **TypeScript value type** `T` it represents (`string`, `number`, or a
  *   string-literal union), preserved through the IR and the inferred return
- *   types of `defineQueries` / `defineCommands`; and
+ *   types of the contract layer (`publishQuery` / `publishCommand`); and
  * - a **runtime descriptor** (`kind` + optional `literals`) that the static
  *   planner (#42) and the code generator read to emit `operations.json`.
  *
@@ -132,8 +132,6 @@ declare const param: {
      */
     readonly array: <const E extends ArrayElementShape>(element: E, options?: ParamOptions) => ArrayParam<E>;
 };
-/** Runtime type guard: is `value` a parameter placeholder? */
-declare function isParam(value: unknown): value is Param<unknown>;
 
 /**
  * Serializable static operation specs and manifest (issue #42, Python-bridge
@@ -463,8 +461,8 @@ interface QuerySpec {
     readonly operations: readonly OperationSpec[];
     /**
      * Result cardinality of the **root** (`$`) operation, derived from the
-     * definition kind: `'one'` for `defineQuery` (a single entity object, with any
-     * relations attached directly), `'many'` for `defineList` (a `{ items, cursor }`
+     * operation kind: `'one'` for a `query` (a single entity object, with any
+     * relations attached directly), `'many'` for a `list` (a `{ items, cursor }`
      * connection). The relation runtime (#45) uses this to shape the root result:
      * a `'one'` Query root takes the first matched item rather than returning a
      * connection. Absent in specs produced before #45; consumers should treat an
@@ -481,8 +479,8 @@ interface QuerySpec {
      */
     readonly executionPlan?: ExecutionPlanSpec;
     /**
-     * Optional human-readable description of the query (issue #154), from
-     * `defineQuery(..., { description })`. Pure documentation — absent unless
+     * Optional human-readable description of the query (issue #154), from a
+     * contract method's `description` field. Pure documentation — absent unless
      * declared, so a query with no description serializes byte-identically to the
      * pre-#154 spec. Surfaces as the generated Python repository-method docstring.
      */
@@ -656,8 +654,8 @@ interface CommandSpec {
     /** Optional write condition (subset). */
     readonly condition?: ConditionSpec;
     /**
-     * Optional human-readable description of the command (issue #154), from
-     * `definePut`/`defineUpdate`/`defineDelete(..., { description })`. Pure
+     * Optional human-readable description of the command (issue #154), from a
+     * contract method's `description` field. Pure
      * documentation — absent unless declared, so a command with no description
      * serializes byte-identically to the pre-#154 spec. Surfaces as the generated
      * Python repository-method docstring.
@@ -1204,4 +1202,4 @@ interface BridgeBundle {
     readonly operations: OperationsDocument;
 }
 
-export { type WriteOperationType as $, type ExpressionScalar as A, type BridgeBundle as B, type ContractSpec as C, type ManifestEntity as D, type ExpressionSpec as E, type FilterSpec as F, type ManifestField as G, type ManifestFieldType as H, type ManifestGsi as I, type ManifestKey as J, type ManifestRelation as K, type ManifestTable as L, type Manifest as M, type OperationSpec as N, type OperationsDocument as O, type ParamSpec as P, type QuerySpec as Q, type QueryContractMethodSpec as R, SPEC_VERSION as S, type TransactionSpec as T, type RangeConditionSpec as U, type ReadOperationType as V, SPEC_VERSION_SCP as W, SPEC_VERSION_SUPPORTED as X, type TransactionItemSpec as Y, type TransactionItemType as Z, type WhenSpec as _, type CommandSpec as a, type ParamKind as a0, type LiteralParam as a1, type NumberParam as a2, type StringParam as a3, isParam as a4, param as a5, type ContextSpec as b, type Param as c, type ConditionSpec as d, type SpecVersion as e, type CommandContractMethodSpec as f, type CommandResolutionTarget as g, type ComposeSpec as h, type CompositionPlanSpec as i, type ContractCardinality as j, type ContractCommandResult as k, type ContractInputArity as l, type ContractKeySpec as m, type ContractKind as n, type ContractResolution as o, EXPR_VERSION as p, type ExecutionPlanSpec as q, type ExpressionArrNode as r, type ExpressionFloatNode as s, type ExpressionIntNode as t, type ExpressionNode as u, type ExpressionObjNode as v, type ExpressionOpNode as w, type ExpressionOperator as x, type ExpressionRefNode as y, type ExpressionRefOptNode as z };
+export { type LiteralParam as $, type ManifestEntity as A, type BridgeBundle as B, type ContractSpec as C, type ManifestField as D, type ExpressionSpec as E, type FilterSpec as F, type ManifestFieldType as G, type ManifestGsi as H, type ManifestKey as I, type ManifestRelation as J, type ManifestTable as K, type OperationSpec as L, type Manifest as M, type QueryContractMethodSpec as N, type OperationsDocument as O, type ParamSpec as P, type QuerySpec as Q, type RangeConditionSpec as R, SPEC_VERSION as S, type TransactionSpec as T, type ReadOperationType as U, SPEC_VERSION_SCP as V, SPEC_VERSION_SUPPORTED as W, type TransactionItemSpec as X, type TransactionItemType as Y, type WhenSpec as Z, type WriteOperationType as _, type CommandSpec as a, type NumberParam as a0, type Param as a1, type ParamKind as a2, type StringParam as a3, param as a4, type ContextSpec as b, type ConditionSpec as c, type SpecVersion as d, type CommandContractMethodSpec as e, type CommandResolutionTarget as f, type ComposeSpec as g, type CompositionPlanSpec as h, type ContractCardinality as i, type ContractCommandResult as j, type ContractInputArity as k, type ContractKeySpec as l, type ContractKind as m, type ContractResolution as n, EXPR_VERSION as o, type ExecutionPlanSpec as p, type ExpressionArrNode as q, type ExpressionFloatNode as r, type ExpressionIntNode as s, type ExpressionNode as t, type ExpressionObjNode as u, type ExpressionOpNode as v, type ExpressionOperator as w, type ExpressionRefNode as x, type ExpressionRefOptNode as y, type ExpressionScalar as z };

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