graphddb 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -1,8 +1,11 @@
-import { ak as SelectableOf, al as PrimaryKeyOf, e as ProjectionTransform, f as MaintainEvent, j as MembershipPredicate, h as MaintainConsistency, i as MaintainUpdateMode, am as MembershipPredicateOp, an as publishQuery, ao as publishCommand, D as DDBModel, ap as RetryPolicy, aq as Middleware } from './key-DR7_lpyk.js';
-export { ar as CdcModelRegistry, as as CdcSubscribeHandlers, at as Change, au as Column, av as ColumnMap, aw as CondSlot, ax as CtxBase, ay as CtxModel, az as FilterInput, aA as GsiDefinitionMarker, aB as GsiOptions, aC as InlineSnapshotSpec, aD as Item, aE as KeyDefinitionMarker, aF as KeySegment, aG as KeySlot, aH as KeyStructure, M as ModelStatic, aI as MutateAuthoringOptions, aJ as ParamDescriptor, aK as ParamStructure, aL as PartialQueryKeyOf, aM as PersistCtx, aN as PersistOrigin, aO as QueryKeyOf, aP as QueryResult, aQ as RawCondition, aR as ReadOpCtx, aS as ReadOpKind, aT as ReadParams, aU as ReadRequestCtx, aV as ReadRequestKind, aW as RelationBuilder, aX as RelationSelect, aY as RelationSpec, aZ as RequestContext, a_ as SegmentSpec, d as SegmentedKey, a$ as SelectBuilder, b0 as SelectOf, b1 as UniqueQueryKeyOf, b2 as Updatable, b3 as WriteCtx, b4 as WriteInput, b5 as WriteKind, b6 as WriteMiddleware, b7 as cond, b8 as entityWrites, b9 as getEntityWrites, ba as gsi, bb as identity, bc as k, bd as key, be as mutate, bf as preview, bg as when } from './key-DR7_lpyk.js';
+import { ak as SelectableOf, al as PrimaryKeyOf, e as ProjectionTransform, f as MaintainEvent, j as MembershipPredicate, h as MaintainConsistency, i as MaintainUpdateMode, am as MembershipPredicateOp, an as publishQuery, ao as publishCommand, D as DDBModel, ap as RetryPolicy, aq as Middleware } from './key-Dne-a20Q.js';
+export { ar as CdcModelRegistry, as as CdcSubscribeHandlers, at as Change, au as Column, av as ColumnMap, aw as CondSlot, ax as CtxBase, ay as CtxModel, az as FilterInput, aA as GsiDefinitionMarker, aB as GsiOptions, aC as InlineSnapshotSpec, aD as Item, aE as KeyDefinitionMarker, aF as KeySegment, aG as KeySlot, aH as KeyStructure, M as ModelStatic, aI as MutateAuthoringOptions, aJ as ParamDescriptor, aK as ParamStructure, aL as PartialQueryKeyOf, aM as PersistCtx, aN as PersistOrigin, aO as QueryKeyOf, aP as QueryResult, aQ as RawCondition, aR as ReadOpCtx, aS as ReadOpKind, aT as ReadParams, aU as ReadRequestCtx, aV as ReadRequestKind, aW as RelationBuilder, aX as RelationSelect, aY as RelationSpec, aZ as RequestContext, a_ as SegmentSpec, d as SegmentedKey, a$ as SelectBuilder, b0 as SelectOf, b1 as UniqueQueryKeyOf, b2 as Updatable, b3 as WriteCtx, b4 as WriteInput, b5 as WriteKind, b6 as WriteMiddleware, b7 as cond, b8 as entityWrites, b9 as getEntityWrites, ba as gsi, bb as identity, bc as k, bd as key, be as mutate, bf as preview, bg as when } from './key-Dne-a20Q.js';
 import * as _aws_sdk_client_dynamodb from '@aws-sdk/client-dynamodb';
-import { M as ModelKind, F as FieldOptions, D as DynamoType, R as RelationOptions, A as AggregateOptions, a as AggregateValue } from './types-BXLzIcQD.js';
-export { $ as LiteralParam, a0 as NumberParam, a1 as Param, a2 as ParamKind, a3 as StringParam, a4 as param } from './types-2PMXEn5x.js';
+import { p as publishBehaviors } from './behaviors-DDltNivc.js';
+export { b as BehaviorComponentFns, a as BehaviorMethodSpec, B as BehaviorModelContract, P as PublishBehaviorsOptions, c as behaviorComponents, i as isBehaviorModelContract } from './behaviors-DDltNivc.js';
+import { M as ModelKind, F as FieldOptions, D as DynamoType, R as RelationOptions, A as AggregateOptions, a as AggregateValue } from './types-BnFsTZwl.js';
+export { a0 as LiteralParam, a1 as MapParam, a2 as NumberParam, a3 as Param, a4 as ParamKind, a5 as StringParam, a6 as param } from './types-CfxzTEFL.js';
+import 'behavior-contracts';
 
 /**
  * Query options with conditional `consistentRead` availability.
@@ -196,6 +199,128 @@ declare const map: FieldDecorator<Record<string, unknown>>;
 
 declare function embedded(modelFactory: () => new (...args: unknown[]) => unknown): (_value: undefined, context: ClassFieldDecoratorContext) => void;
 
+/**
+ * Field groups — reusable, composable field sets for models (issue #295, part B).
+ *
+ * ## Why composition, not inheritance
+ *
+ * The metadata pipeline is drain-based: TC39 field decorators push
+ * {@link FieldMetadata} into a module-level pending collector, and the topmost
+ * `@model` class decorator drains it (`collector.ts`). A **decorated shared base
+ * class** breaks that contract — the base's field decorators fire ONCE (at base
+ * class definition) and sit pending until the NEXT `@model` drains them, so the
+ * first subclass absorbs the base's fields and every later subclass silently
+ * loses them (drain-order dependence; the issue-#295 report). Real inheritance
+ * support would require re-architecting the collector around prototype-chain
+ * walks. A **field group** achieves the reuse the issue wants ("generic meta
+ * columns shared by every domain model") with the SAME mechanism the codebase
+ * already uses for stacked class-level declarations (`@maintainedFrom`,
+ * `@cdcProjected`): a class decorator that pushes into the pending collector
+ * BEFORE `@model` drains — per-class, so no drain-order hazard exists.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * // Shared, generic meta columns — defined ONCE, reused by every domain model.
+ * export const TreeMeta = defineFieldGroup(($) => ({
+ *   part: $.string(),
+ *   child: $.string(),
+ *   scope: $.string(),
+ *   computeVersion: $.number(),
+ *   computedAt: $.number(),
+ *   minPendingAt: $.number(),
+ * }));
+ *
+ * // A domain model composes the group with its own typed map value (issue #295):
+ * @model({ table: TABLE })
+ * @withFields(TreeMeta)
+ * export class AvgTreeNodeModel extends DDBModel {
+ *   static readonly keys = key<{ part: string; child: string }>((c) => ({
+ *     pk: k`TREE#${c.part}`,
+ *     sk: k`${c.child}`,
+ *   }));
+ *   @map value!: AvgValue; // the domain-specific value class, one M attribute
+ * }
+ * // TypeScript-side property typing via declaration merging (one line):
+ * export interface AvgTreeNodeModel extends FieldsOf<typeof TreeMeta> {}
+ * ```
+ *
+ * Group fields are ordinary {@link FieldMetadata}: they participate in keys
+ * (`key<{part, child}>` references them by name), GSIs, params-kind recovery
+ * (a `param` bound into a group `$.number()` field serializes as `'number'`),
+ * hydration, and codegen exactly as body-declared fields do.
+ */
+
+/** Brand tag carrying the TS value type a group field represents. */
+declare const GROUP_FIELD_BRAND: unique symbol;
+/**
+ * One field definition inside a {@link FieldGroup}: the same storage facts a
+ * semantic field decorator records (`dynamoType` + optional `options` /
+ * `literals`), plus — purely at the type level — the represented value type `T`
+ * (surfaced through {@link FieldsOf}).
+ */
+interface GroupFieldDef<out T> {
+    /** @internal Type brand carrying the represented value type. */
+    readonly [GROUP_FIELD_BRAND]: T;
+    readonly dynamoType: DynamoType;
+    readonly options?: FieldOptions;
+    readonly literals?: readonly string[];
+}
+/** The field-shape record a {@link defineFieldGroup} builder returns. */
+type FieldGroupShape = Record<string, GroupFieldDef<unknown>>;
+/** A reusable, named set of field definitions (issue #295 part B). */
+interface FieldGroup<S extends FieldGroupShape = FieldGroupShape> {
+    readonly __isFieldGroup: true;
+    readonly fields: S;
+}
+/**
+ * The TypeScript property types a {@link FieldGroup} contributes — merge them
+ * into the model class with one declaration-merging line:
+ * `export interface MyModel extends FieldsOf<typeof MyGroup> {}`.
+ */
+type FieldsOf<G extends FieldGroup> = {
+    [K in keyof G['fields']]: G['fields'][K] extends GroupFieldDef<infer T> ? T : never;
+};
+/**
+ * The field factories a {@link defineFieldGroup} builder receives — one per
+ * semantic field decorator, recording the same storage facts (`@string` → `'S'`,
+ * `@datetime` → `'S'` + `format`, `@literal` → `'S'` + the literal set, …).
+ */
+interface GroupFieldFactories {
+    string(options?: FieldOptions): GroupFieldDef<string>;
+    number(options?: FieldOptions): GroupFieldDef<number>;
+    boolean(options?: FieldOptions): GroupFieldDef<boolean>;
+    datetime(options?: FieldOptions): GroupFieldDef<Date>;
+    binary(options?: FieldOptions): GroupFieldDef<Uint8Array>;
+    stringSet(options?: FieldOptions): GroupFieldDef<Set<string>>;
+    numberSet(options?: FieldOptions): GroupFieldDef<Set<number>>;
+    list(options?: FieldOptions): GroupFieldDef<unknown[]>;
+    /** A free-form map field (one DynamoDB `M` attribute). `T` types the TS surface. */
+    map<T extends Record<string, unknown> = Record<string, unknown>>(options?: FieldOptions): GroupFieldDef<T>;
+    /** A closed string-literal-union field (the `@literal(...)` counterpart). */
+    literal<const L extends string>(...values: readonly [L, ...L[]]): GroupFieldDef<L>;
+}
+/**
+ * Define a reusable field group. The builder receives the field factories and
+ * returns the `{ fieldName: $.<type>() }` shape; the group is a plain immutable
+ * value (no collector interaction happens here — fields are contributed to a
+ * model only when `@withFields(group)` runs on that class).
+ */
+declare function defineFieldGroup<const S extends FieldGroupShape>(build: (f: GroupFieldFactories) => S): FieldGroup<S>;
+/**
+ * `@withFields(...groups)` — contribute each group's fields to the decorated
+ * model class. Stacked BELOW `@model` (which must stay topmost): TC39 class
+ * decorators apply bottom-up, so `@withFields` pushes into the pending collector
+ * and the `@model` drain picks the group fields up together with the class's own
+ * decorated fields — the exact `@maintainedFrom` / `@cdcProjected` mechanism.
+ *
+ * Duplicate field names are rejected LOUDLY: a group field colliding with a
+ * body-declared field (already pending at this point — field decorators run
+ * before any class decorator) or with an earlier group would register two
+ * metadata entries for one property and silently shadow one of them.
+ */
+declare function withFields(...groups: readonly FieldGroup[]): (_target: Function, context: ClassDecoratorContext) => void;
+
 /**
  * Symbolic `(self, source) =>` evaluation for the `@maintainedFrom` view authoring
  * and the versioned relation `pattern` union (issue #152).
@@ -668,6 +793,7 @@ declare function cdcProjected(): (_target: Function, _context: ClassDecoratorCon
 declare const graphddb: {
     readonly publishQuery: typeof publishQuery;
     readonly publishCommand: typeof publishCommand;
+    readonly publishBehaviors: typeof publishBehaviors;
     readonly query: typeof DDBModel.query;
     readonly mutate: typeof DDBModel.mutate;
     readonly prepare: typeof DDBModel.prepare;
@@ -682,4 +808,4 @@ declare const graphddb: {
     };
 };
 
-export { DDBModel, type HasManyVersionedCallback, type HasManyVersionedOptions, type HasOneVersionedCallback, type HasOneVersionedOptions, type ListOptions, type MaintainedFromCallback, type MaintainedFromOptions, Middleware, type ModelOptions, PrimaryKeyOf, type ProjectionValue, type QueryOptions, type RefsOptions, SelectableOf, type SelfProxy, type SelfRef, type SourceProxy, type SourceRef, type VersionedHistoryOptions, type VersionedLatestOptions, aggregate, belongsTo, binary, boolean, cdcProjected, count, datetime, embedded, field, graphddb, hasMany, hasOne, list, literal, maintainedFrom, map, max, model, number, numberSet, refs, string, stringSet, ttl, whenMember };
+export { DDBModel, type FieldGroup, type FieldGroupShape, type FieldsOf, type GroupFieldDef, type GroupFieldFactories, type HasManyVersionedCallback, type HasManyVersionedOptions, type HasOneVersionedCallback, type HasOneVersionedOptions, type ListOptions, type MaintainedFromCallback, type MaintainedFromOptions, Middleware, type ModelOptions, PrimaryKeyOf, type ProjectionValue, type QueryOptions, type RefsOptions, SelectableOf, type SelfProxy, type SelfRef, type SourceProxy, type SourceRef, type VersionedHistoryOptions, type VersionedLatestOptions, aggregate, belongsTo, binary, boolean, cdcProjected, count, datetime, defineFieldGroup, embedded, field, graphddb, hasMany, hasOne, list, literal, maintainedFrom, map, max, model, number, numberSet, refs, string, stringSet, ttl, whenMember, withFields };

package/dist/index.js

@@ -3,29 +3,70 @@ import {
   mutate,
   publishCommand,
   publishQuery
-} from "./chunk-I4LEJ4TF.js";
+} from "./chunk-XZTA4VJH.js";
 import {
   entityWrites,
   getEntityWrites,
   identity,
   preview
-} from "./chunk-HNY2EJPV.js";
+} from "./chunk-KOIJ4SNO.js";
 import {
   when
-} from "./chunk-L4QRCHRQ.js";
+} from "./chunk-WOFRHRXY.js";
 import {
   ClientManager,
+  GRAPHDDB_CATALOG,
   MetadataRegistry,
+  assertComponentsInCatalog,
   cond,
+  deriveContractEffect,
   gsi,
   param
-} from "./chunk-L2NEDS7U.js";
+} from "./chunk-ZNU7OI5I.js";
 import {
   TableMapping,
   k,
   key
 } from "./chunk-XTWXMOHD.js";
 
+// src/define/behaviors.ts
+import {
+  catalogComponents,
+  compileBehaviors
+} from "behavior-contracts";
+var boundComponents;
+function behaviorComponents() {
+  if (boundComponents === void 0) {
+    boundComponents = catalogComponents(GRAPHDDB_CATALOG);
+  }
+  return boundComponents;
+}
+function publishBehaviors(cls, options = {}) {
+  const ir = compileBehaviors(cls, {
+    ...options.inputPorts !== void 0 ? { inputPorts: options.inputPorts } : {},
+    ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {}
+  });
+  assertComponentsInCatalog(ir.components);
+  const methods = {};
+  for (const component of ir.components) {
+    methods[component.name] = {
+      name: component.name,
+      effect: deriveContractEffect(component),
+      component
+    };
+  }
+  return Object.freeze({
+    kind: "behaviors",
+    className: cls.name ?? "<anonymous>",
+    ir,
+    components: ir.components,
+    methods: Object.freeze(methods)
+  });
+}
+function isBehaviorModelContract(value) {
+  return typeof value === "object" && value !== null && value.kind === "behaviors" && Array.isArray(value.components);
+}
+
 // src/config/index.ts
 var config = {
   /**
@@ -123,6 +164,9 @@ function drainFields() {
   pendingFields = [];
   return result;
 }
+function peekPendingFieldNames() {
+  return pendingFields.map((f) => f.propertyName);
+}
 function drainEmbedded() {
   const result = pendingEmbedded;
   pendingEmbedded = [];
@@ -267,6 +311,71 @@ function embedded(modelFactory) {
   };
 }
 
+// src/decorators/field-group.ts
+function def(dynamoType, options, literals) {
+  const d = { dynamoType };
+  if (options !== void 0 && Object.keys(options).length > 0) d.options = options;
+  if (literals !== void 0) d.literals = literals;
+  return d;
+}
+var factories = {
+  string: (options) => def("S", options),
+  number: (options) => def("N", options),
+  boolean: (options) => def("BOOL", options),
+  datetime: (options) => def("S", { format: "datetime", ...options }),
+  binary: (options) => def("B", options),
+  stringSet: (options) => def("SS", options),
+  numberSet: (options) => def("NS", options),
+  list: (options) => def("L", options),
+  map: (options) => def("M", options),
+  literal: (...values) => {
+    if (values.length === 0) {
+      throw new Error(
+        "defineFieldGroup: $.literal(...) requires at least one allowed value."
+      );
+    }
+    return def("S", void 0, [...values]);
+  }
+};
+function defineFieldGroup(build) {
+  const fields = build(factories);
+  if (Object.keys(fields).length === 0) {
+    throw new Error("defineFieldGroup: a field group must declare at least one field.");
+  }
+  return { __isFieldGroup: true, fields };
+}
+function withFields(...groups) {
+  if (groups.length === 0) {
+    throw new Error("@withFields requires at least one field group.");
+  }
+  for (const g of groups) {
+    if (g === null || typeof g !== "object" || g.__isFieldGroup !== true) {
+      throw new Error(
+        "@withFields: every argument must be a `defineFieldGroup(...)` result."
+      );
+    }
+  }
+  return function(_target, context) {
+    const seen = new Set(peekPendingFieldNames());
+    for (const group of groups) {
+      for (const [propertyName, d] of Object.entries(group.fields)) {
+        if (seen.has(propertyName)) {
+          throw new Error(
+            `@withFields on '${String(context.name)}': field '${propertyName}' is declared more than once (a group field collides with a body-declared field or another group). Each property may be declared exactly once.`
+          );
+        }
+        seen.add(propertyName);
+        collectField({
+          propertyName,
+          dynamoType: d.dynamoType,
+          ...d.options !== void 0 ? { options: d.options } : {},
+          ...d.literals !== void 0 ? { literals: d.literals } : {}
+        });
+      }
+    }
+  };
+}
+
 // src/decorators/maintained-symbolic.ts
 var SOURCE_REF = /* @__PURE__ */ Symbol("graphddb:maintainedSourceRef");
 var SELF_REF = /* @__PURE__ */ Symbol("graphddb:maintainedSelfRef");
@@ -620,6 +729,9 @@ function cdcProjected() {
 var graphddb = {
   publishQuery,
   publishCommand,
+  // #297 SP3: the shared-authoring verb (SemanticBehavior class → behavior
+  // contract; effect derived from the graph, components registered additively).
+  publishBehaviors,
   get query() {
     return DDBModel.query;
   },
@@ -647,6 +759,7 @@ var graphddb = {
 export {
   DDBModel,
   aggregate,
+  behaviorComponents,
   belongsTo,
   binary,
   boolean,
@@ -654,6 +767,7 @@ export {
   cond,
   count,
   datetime,
+  defineFieldGroup,
   embedded,
   entityWrites,
   field,
@@ -663,6 +777,7 @@ export {
   hasMany,
   hasOne,
   identity,
+  isBehaviorModelContract,
   k,
   key,
   list,
@@ -681,5 +796,6 @@ export {
   stringSet,
   ttl,
   when,
-  whenMember
+  whenMember,
+  withFields
 };

package/dist/internal/index.d.ts

@@ -1,8 +1,9 @@
-import { P as PreparedWriteOpSpec, a as PreparedPlanDocument } from '../prepared-artifact-BpPgkXEo.js';
-export { b as PreparedBindSpec, c as PreparedPlanSpec, d as PreparedReadRouteSpec } from '../prepared-artifact-BpPgkXEo.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-DR7_lpyk.js';
-import '../types-BXLzIcQD.js';
+import { P as PreparedWriteOpSpec, a as PreparedPlanDocument } from '../prepared-artifact-BXkARxwO.js';
+export { b as PreparedBindSpec, c as PreparedPlanSpec, d as PreparedReadRouteSpec } from '../prepared-artifact-BXkARxwO.js';
+import { M as Manifest } from '../types-CfxzTEFL.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-Dne-a20Q.js';
+import '../types-BnFsTZwl.js';
+import 'behavior-contracts';
 
 /**
  * Static prepared-plan LOADER (issue #208) — the runtime half of the AOT

package/dist/internal/index.js

@@ -2,26 +2,26 @@ import {
   PREPARED_FORMAT_VERSION,
   buildManifestEntity,
   entityFingerprint
-} from "../chunk-LGHSZIEE.js";
+} from "../chunk-NWTEUWJD.js";
 import {
   LOGICAL_EFFECT_CATEGORIES,
   PreparedReadStatement,
   executeLogicalParallelWrites,
   executeLogicalWriteOps,
   serializeEffectParams
-} from "../chunk-I4LEJ4TF.js";
-import "../chunk-HNY2EJPV.js";
+} from "../chunk-XZTA4VJH.js";
+import "../chunk-KOIJ4SNO.js";
 import {
   MARKER_ROW_ENTITY,
-  SPEC_VERSION,
+  SPEC_VERSION_KEY_EXPR,
   SPEC_VERSION_SUPPORTED
-} from "../chunk-L4QRCHRQ.js";
+} from "../chunk-WOFRHRXY.js";
 import {
   MetadataRegistry,
   buildConditionExpression,
   execItemKeySignature,
   resolveConditionTree
-} from "../chunk-L2NEDS7U.js";
+} from "../chunk-ZNU7OI5I.js";
 import {
   TableMapping
 } from "../chunk-XTWXMOHD.js";
@@ -489,7 +489,7 @@ function bindEntities(plan, planId) {
     entities[name] = entity;
     tables[metadata.tableName] = { physicalName: TableMapping.resolve(metadata.tableName) };
   }
-  return { classes, manifest: { version: SPEC_VERSION, tables, entities } };
+  return { classes, manifest: { version: SPEC_VERSION_KEY_EXPR, tables, entities } };
 }
 function renderSpecItem(transaction, index, manifest, params) {
   const single = {