graphddb 0.5.1 → 0.5.2

package/README.md

@@ -21,6 +21,7 @@ TypeScript types.
 - ✅ **CDC emulator** —— drive and test change events equivalent to DynamoDB Streams locally.
 - ✅ **CDC projection** —— `@cdcProjected()` + `fromChange` / `subscribe` parse CDC change events into typed records (sink delivery / idempotency stay with the consumer).
 - ✅ **Maintained access paths** —— keep embedded snapshots / aggregate counters synchronized atomically.
+- ✅ **CloudFormation generation** —— emit a CloudFormation template for the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / TableClass / SSE / PROVISIONED / Auto Scaling).
 
 ## 🤔 Philosophy
 
@@ -262,6 +263,7 @@ flowchart LR
     M["TS Model (SSoT)"] --> RT["Runtime (TS)"]
     M --> PY["Python client + runtime"]
     M --> CQ["CQRS Contract"]
+    M --> CFN["CloudFormation template"]
 ```
 
 ## 📄 License

package/dist/{chunk-FI63YKK5.js → chunk-H5TUW2WR.js}

@@ -50,7 +50,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-B3GWIWT6.js";
+} from "./chunk-W3GEJPPV.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -99,7 +99,10 @@ function buildGsis(metadata) {
       unique: gsi.unique,
       inputFields: [...gsi.inputFieldNames],
       pkTemplate: pk,
-      skTemplate: sk ?? null
+      skTemplate: sk ?? null,
+      // Purely-documentary GSI description (issue #166); emitted only when declared
+      // so an undescribed index is byte-identical to the pre-#166 manifest.
+      ...gsi.description !== void 0 ? { description: gsi.description } : {}
     };
   });
 }
@@ -110,7 +113,10 @@ function buildRelations(metadata) {
     relations[rel.propertyName] = {
       type: rel.type,
       target: targetClass.name,
-      keyBinding: { ...rel.keyBinding }
+      keyBinding: { ...rel.keyBinding },
+      // Purely-documentary relation description (issue #166); emitted only when
+      // declared so an undescribed relation is byte-identical to the pre-#166 manifest.
+      ...rel.options?.description !== void 0 ? { description: rel.options.description } : {}
     };
   }
   return sortedRecord(relations);

package/dist/chunk-MCKGQKYU.js

@@ -0,0 +1,15 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+export {
+  __require,
+  __commonJS
+};

package/dist/{chunk-EMJHTUA4.js → chunk-QBXLQNXY.js}

@@ -7,7 +7,7 @@ import {
   buildMaintenanceGraph,
   buildPutInput,
   resolveModelClass
-} from "./chunk-B3GWIWT6.js";
+} from "./chunk-W3GEJPPV.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {

package/dist/{chunk-B3GWIWT6.js → chunk-W3GEJPPV.js}

@@ -113,7 +113,10 @@ function gsi(indexName, builder, options) {
     indexName,
     segmented,
     inputFieldNames,
-    unique: options?.unique ?? false
+    unique: options?.unique ?? false,
+    // Purely-documentary description (issue #166); emitted only when declared so an
+    // undescribed index carries no `description` key (byte-identical to pre-#166).
+    ...options?.description !== void 0 ? { description: options.description } : {}
   };
 }
 
@@ -1084,7 +1087,10 @@ var MetadataRegistry = class {
           indexName: value.indexName,
           segmented: value.segmented,
           inputFieldNames: value.inputFieldNames,
-          unique: value.unique
+          unique: value.unique,
+          // Purely-documentary GSI description (issue #166); copied only when declared
+          // so an undescribed index is byte-identical to the pre-#166 metadata.
+          ...value.description !== void 0 ? { description: value.description } : {}
         });
       }
     }

package/dist/cli.js

@@ -2,11 +2,12 @@
 import {
   buildBridgeBundle,
   buildManifest
-} from "./chunk-FI63YKK5.js";
+} from "./chunk-H5TUW2WR.js";
 import {
   MetadataRegistry,
   normalizeSelectSpec
-} from "./chunk-B3GWIWT6.js";
+} from "./chunk-W3GEJPPV.js";
+import "./chunk-MCKGQKYU.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -659,6 +660,9 @@ function collectResultTypes(manifest, entity, select, typeName, out, seen) {
       } else {
         fields.push([field, `${itemTypeName} | None`]);
       }
+      if (relation.description !== void 0) {
+        fieldDescriptions[field] = relation.description;
+      }
       continue;
     }
     if (value === true) {
@@ -790,7 +794,15 @@ function methodParams(def) {
   }
   return out;
 }
-function collectRepositories(queries, commands) {
+function gsiDescriptionForQuery(name, entity, manifest, querySpecs) {
+  if (!manifest || !querySpecs) return void 0;
+  const spec = querySpecs[name];
+  const indexName = spec?.operations[0]?.indexName;
+  if (indexName === void 0) return void 0;
+  const gsi = manifest.entities[entity]?.gsis.find((g) => g.indexName === indexName);
+  return gsi?.description;
+}
+function collectRepositories(queries, commands, manifest, querySpecs) {
   const byEntity = /* @__PURE__ */ new Map();
   const ensure = (entity) => {
     const cls = `${entityBaseName(entity)}Repository`;
@@ -803,13 +815,14 @@ function collectRepositories(queries, commands) {
   };
   for (const name of Object.keys(queries).sort()) {
     const def = queries[name];
+    const description = def.description ?? gsiDescriptionForQuery(name, def.entity.name, manifest, querySpecs);
     ensure(def.entity.name).push({
       methodName: toSnakeCase(name),
       params: methodParams(def),
       returnType: `${queryResultTypeName(name)} | None`,
       kind: "query",
       operationId: name,
-      ...def.description !== void 0 ? { description: def.description } : {}
+      ...description !== void 0 ? { description } : {}
     });
   }
   for (const name of Object.keys(commands).sort()) {
@@ -914,8 +927,8 @@ function renderTransactionsClass(methods) {
     body.join("\n\n")
   ].join("\n");
 }
-function generateRepositories(queries, commands, transactions = {}) {
-  const classes = collectRepositories(queries, commands);
+function generateRepositories(queries, commands, transactions = {}, manifest, querySpecs) {
+  const classes = collectRepositories(queries, commands, manifest, querySpecs);
   const txMethods = collectTransactionMethods(transactions);
   const resultTypes = /* @__PURE__ */ new Set();
   for (const name of Object.keys(queries)) {
@@ -1471,11 +1484,243 @@ function renderBundle(queries = {}, commands = {}, registry = MetadataRegistry,
     "manifest.json": JSON.stringify(bundle.manifest, null, 2) + "\n",
     "operations.json": JSON.stringify(bundle.operations, null, 2) + "\n",
     "types.py": generateTypes(bundle.manifest, queries, txSpecs, options),
-    "repositories.py": generateRepositories(queries, commands, txSpecs),
+    "repositories.py": generateRepositories(
+      queries,
+      commands,
+      txSpecs,
+      bundle.manifest,
+      bundle.operations.queries
+    ),
     "__init__.py": generateInit(queries, commands, txSpecs)
   };
 }
 
+// src/codegen/jsdoc.ts
+async function loadTypescript() {
+  try {
+    const mod = await import("./typescript-ZUQEBJRV.js");
+    return mod.default ?? mod;
+  } catch {
+    return void 0;
+  }
+}
+var warnedTypescriptMissing = false;
+var TYPESCRIPT_MISSING_WARNING = "warning: JSDoc description extraction skipped \u2014 'typescript' is not installed. Install typescript to enable it, or use explicit `description` fields.\n";
+function docCommentFor(ts, node) {
+  const jsDoc = node.jsDoc;
+  if (!jsDoc || jsDoc.length === 0) return void 0;
+  const last = jsDoc[jsDoc.length - 1];
+  const comment = last.comment;
+  if (typeof comment === "string") {
+    const t = comment.trim();
+    return t === "" ? void 0 : t;
+  }
+  if (Array.isArray(comment)) {
+    const joined = ts.getTextOfJSDocComment(comment);
+    if (joined) {
+      const t = joined.trim();
+      return t === "" ? void 0 : t;
+    }
+  }
+  return void 0;
+}
+function hasModelDecorator(ts, node) {
+  const decorators = ts.getDecorators?.(node) ?? [];
+  for (const dec of decorators) {
+    const expr = dec.expression;
+    const callee = ts.isCallExpression(expr) ? expr.expression : expr;
+    if (ts.isIdentifier(callee) && callee.text === "model") return true;
+  }
+  return false;
+}
+function gsiIndexNameOf(ts, init) {
+  if (!init || !ts.isCallExpression(init)) return void 0;
+  const callee = init.expression;
+  if (!ts.isIdentifier(callee) || callee.text !== "gsi") return void 0;
+  const first = init.arguments[0];
+  if (first && ts.isStringLiteralLike(first)) return first.text;
+  return void 0;
+}
+function collectClassDoc(ts, node) {
+  const members = /* @__PURE__ */ new Map();
+  const gsis = /* @__PURE__ */ new Map();
+  for (const member of node.members) {
+    if (ts.isPropertyDeclaration(member) && member.name) {
+      const doc = docCommentFor(ts, member);
+      if (doc === void 0) continue;
+      const gsiName = gsiIndexNameOf(ts, member.initializer);
+      if (gsiName !== void 0) {
+        gsis.set(gsiName, doc);
+      } else if (ts.isIdentifier(member.name) || ts.isStringLiteralLike(member.name)) {
+        members.set(member.name.text, doc);
+      }
+    }
+  }
+  return { own: docCommentFor(ts, node), members, gsis };
+}
+function collectDefinitionDocs(ts, obj, into, ambiguous) {
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    if (!ts.isIdentifier(prop.name) && !ts.isStringLiteralLike(prop.name)) continue;
+    const key = prop.name.text;
+    if (into.has(key) || ambiguous.has(key)) {
+      into.delete(key);
+      ambiguous.add(key);
+      continue;
+    }
+    const params = /* @__PURE__ */ new Map();
+    collectParamDocs(ts, prop.initializer, params);
+    into.set(key, { own: docCommentFor(ts, prop), params });
+  }
+}
+function collectParamDocs(ts, node, into) {
+  const visit = (n) => {
+    if (ts.isPropertyAssignment(n)) {
+      const isParamCall = ts.isCallExpression(n.initializer) && ts.isPropertyAccessExpression(n.initializer.expression) && ts.isIdentifier(n.initializer.expression.expression) && n.initializer.expression.expression.text === "param";
+      if (isParamCall && (ts.isIdentifier(n.name) || ts.isStringLiteralLike(n.name))) {
+        const doc = docCommentFor(ts, n);
+        if (doc !== void 0) into.set(n.name.text, doc);
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(node, visit);
+}
+function extract(ts, files) {
+  const program = ts.createProgram(files, {
+    // Parse-only, permissive options: we never emit and never type-check the
+    // world — we only walk the AST of the requested files. `allowJs` lets a `.js`
+    // definition module (pre-compiled input) be parsed too.
+    allowJs: true,
+    noResolve: true,
+    noLib: true,
+    skipLibCheck: true,
+    types: [],
+    // The definition modules use TC39 standard decorators (repo tsconfig has
+    // `experimentalDecorators: false`); parsing is decorator-flavour agnostic for
+    // AST purposes, but keep it aligned.
+    experimentalDecorators: false
+  });
+  const classes = /* @__PURE__ */ new Map();
+  const ambiguousClassNames = /* @__PURE__ */ new Set();
+  const definitions = /* @__PURE__ */ new Map();
+  const ambiguousDefinitionKeys = /* @__PURE__ */ new Set();
+  const fileSet = new Set(files.map((f) => normalize(f)));
+  for (const sf of program.getSourceFiles()) {
+    if (!fileSet.has(normalize(sf.fileName))) continue;
+    const visit = (node) => {
+      if (ts.isClassDeclaration(node) && node.name && hasModelDecorator(ts, node)) {
+        const name = node.name.text;
+        if (classes.has(name) || ambiguousClassNames.has(name)) {
+          classes.delete(name);
+          ambiguousClassNames.add(name);
+        } else {
+          classes.set(name, collectClassDoc(ts, node));
+        }
+      }
+      if (ts.isCallExpression(node)) {
+        const callee = node.expression;
+        if (ts.isIdentifier(callee) && (callee.text === "defineQueries" || callee.text === "defineCommands")) {
+          const arg = node.arguments[0];
+          if (arg && ts.isObjectLiteralExpression(arg)) {
+            collectDefinitionDocs(ts, arg, definitions, ambiguousDefinitionKeys);
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sf);
+  }
+  return {
+    classes,
+    ambiguousClassNames,
+    definitions,
+    ambiguousDefinitionKeys
+  };
+}
+function normalize(p) {
+  return p.replace(/\\/g, "/");
+}
+function mergeIntoRegistry(extracted, registry) {
+  const countByName = /* @__PURE__ */ new Map();
+  for (const [cls] of registry.getAll()) {
+    countByName.set(cls.name, (countByName.get(cls.name) ?? 0) + 1);
+  }
+  for (const [cls, meta] of registry.getAll()) {
+    const name = cls.name;
+    if (extracted.ambiguousClassNames.has(name)) continue;
+    if ((countByName.get(name) ?? 0) !== 1) continue;
+    const classDoc = extracted.classes.get(name);
+    if (!classDoc) continue;
+    applyClassDoc(classDoc, meta);
+  }
+}
+function applyClassDoc(classDoc, meta) {
+  if (meta.description === void 0 && classDoc.own !== void 0) {
+    meta.description = classDoc.own;
+  }
+  for (const field of meta.fields) {
+    const doc = classDoc.members.get(field.propertyName);
+    if (doc === void 0) continue;
+    if (field.options?.description !== void 0) continue;
+    field.options = { ...field.options ?? {}, description: doc };
+  }
+  for (const rel of meta.relations) {
+    const doc = classDoc.members.get(rel.propertyName);
+    if (doc === void 0) continue;
+    if (rel.options?.description !== void 0) continue;
+    rel.options = { ...rel.options ?? {}, description: doc };
+  }
+  for (const gsi of meta.gsiDefinitions) {
+    const doc = classDoc.gsis.get(gsi.indexName);
+    if (doc === void 0) continue;
+    if (gsi.description !== void 0) continue;
+    gsi.description = doc;
+  }
+}
+function mergeIntoDefinitions(extracted, map) {
+  for (const [key, def] of Object.entries(map)) {
+    if (extracted.ambiguousDefinitionKeys.has(key)) continue;
+    const defDoc = extracted.definitions.get(key);
+    if (!defDoc) continue;
+    if (def.description === void 0 && defDoc.own !== void 0) {
+      def.description = defDoc.own;
+    }
+    for (const [paramName, descriptor] of Object.entries(def.params)) {
+      const doc = defDoc.params.get(paramName);
+      if (doc === void 0) continue;
+      if (descriptor.description !== void 0) continue;
+      descriptor.description = doc;
+    }
+  }
+}
+async function applyJsDocDescriptions(sources, queries, commands, registry = MetadataRegistry, opts = {}) {
+  const ts = await (opts.loadTs ?? loadTypescript)();
+  if (!ts) {
+    if (!warnedTypescriptMissing) {
+      warnedTypescriptMissing = true;
+      (opts.warn ?? ((m) => void process.stderr.write(m)))(
+        TYPESCRIPT_MISSING_WARNING
+      );
+    }
+    return false;
+  }
+  try {
+    const files = [
+      sources.entry,
+      ...sources.queries ? [sources.queries] : [],
+      ...sources.commands ? [sources.commands] : []
+    ].filter((f, i, a) => a.indexOf(f) === i);
+    const extracted = extract(ts, files);
+    mergeIntoRegistry(extracted, registry);
+    mergeIntoDefinitions(extracted, queries);
+    mergeIntoDefinitions(extracted, commands);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/cli/handlers.ts
 function fail(code, message, exitCode) {
   process.stderr.write(JSON.stringify({ code, message }) + "\n");
@@ -1552,6 +1797,16 @@ var handlers = {
         contextsPath ?? contractsPath ?? entry,
         "contexts"
       );
+      const abs = (p) => isAbsolute(p) ? p : resolve(process.cwd(), p);
+      await applyJsDocDescriptions(
+        {
+          entry: abs(entry),
+          queries: abs(queriesPath ?? entry),
+          commands: abs(commandsPath ?? entry)
+        },
+        queries,
+        commands
+      );
       const files = renderBundle(queries, commands, void 0, transactions, {
         dataclass: Boolean(dataclass),
         contracts: { contracts, contexts }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SelectableOf, g as PrimaryKeyOf, h as RequestContext, i as Middleware, j as ReadRequestKind, k as CtxModel, l as ReadParams, m as ReadRequestCtx, D as DynamoDBOperation, I as Item, E as Executor, n as RetryPolicy, o as ExecutionPlanSpec, p as EntityMetadata, K as KeyDefinition, G as GsiDefinition, q as ModelKind, F as FieldOptions, r as DynamoType, s as ProjectionTransform, t as MaintainEvent, u as MembershipPredicate, v as MaintainConsistency, w as MaintainUpdateMode, x as MembershipPredicateOp, y as RelationOptions, A as AggregateOptions, z as AggregateValue, H as SelectBuilderSpec, J as RawCondition, L as TransactionSpec, N as Manifest, O as RetryOverride, Q as ExecutionPlan, V as FieldMetadata, X as ResolvedKey, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, Y as CdcEmulatorOptions, Z as ChangeHandler, _ as Unsubscribe, $ as FaultSpec, a0 as ConcurrentRecomputeRef, C as ChangeEvent, a1 as EventLog, a2 as ReplayOptions, a3 as ShardId, a4 as ViewDefinition, a5 as RelationMetadata, a6 as TransactionItemSpec, a7 as MaintainEffect, M as ModelStatic, f as DDBModel, a8 as Param, a9 as ParamDescriptor, aa as DefinitionMap, ab as OperationDefinition, ac as WriteDefinitionOptions, ad as PartialQueryKeyOf, ae as StrictSelectSpec, af as ReadDefinitionOptions, ag as EntityInput, ah as UniqueQueryKeyOf, ai as EntityRef, aj as ConditionInput, ak as QueryModelContract, al as QueryMethodSpec, am as CommandModelContract, an as CommandMethodSpec, ao as ContractSpec, ap as QuerySpec, aq as CommandSpec, ar as ContextSpec, as as OperationsDocument, at as AnyOperationDefinition, au as BridgeBundle, av as ConditionSpec } from './types-B9rJ1z3H.js';
-export { aw as AggregateMetadata, ax as BatchDeleteRequest, ay as BatchGetOptions, az as BatchGetRequest, aA as BatchGetResult, aB as BatchPutRequest, aC as BatchResult, aD as BatchWriteRequest, aE as CONTRACT_RANGE_FANOUT_CONCURRENCY, aF as CdcMode, aG as CdcModelRegistry, aH as CdcSubscribeHandlers, aI as Change, aJ as ChangeBatch, aK as ChangeEventName, aL as ClockMode, aM as CollectionEffect, aN as CollectionOptions, aO as Column, aP as ColumnMap, aQ as CommandContractMethodSpec, aR as CommandInputShape, aS as CommandMethod, aT as CommandPlan, aU as CommandResolutionTarget, aV as CommandResultKind, aW as CommandSelectShape, aX as CompiledFragment, aY as ComposeSpec, aZ as CondSlot, a_ as ConditionCheckInput, a$ as Connection, b0 as ContractCallSignature, b1 as ContractCardinality, b2 as ContractCommandParams, b3 as ContractCommandResult, b4 as ContractComposeNode, b5 as ContractFromRef, b6 as ContractInputArity, b7 as ContractItem, b8 as ContractKeyFieldRef, b9 as ContractKeyInput, ba as ContractKeyRef, bb as ContractKeySpec, bc as ContractKind, bd as ContractMethodOp, be as ContractParamRef, bf as ContractQueryParams, bg as ContractResolution, bh as CounterAggregate, bi as CounterEffect, bj as CtxBase, bk as DEFAULT_MAX_ATTEMPTS, bl as DEFAULT_RETRY_POLICY, bm as DeleteOptions, bn as DeriveEffect, bo as DerivedEdgeWrite, bp as DerivedUpdate, bq as DescriptorBinding, br as ENTITY_WRITES_MARKER, bs as EdgeEffect, bt as EffectPath, bu as EmbeddedMetadata, bv as EmitEffect, bw as EntityWritesDefinition, bx as EntityWritesShape, by as ExecutableCommandContract, bz as ExecutableQueryContract, bA as FilterInput, bB as FilterSpec, bC as FragmentInput, bD as GsiDefinitionMarker, bE as GsiOptions, bF as IdempotencyEffect, bG as InProcessWriteDescriptor, bH as InputArity, bI as KeyDefinitionMarker, bJ as KeySegment, bK as KeySlot, bL as KeyStructure, bM as KeyedResult, bN as LIFECYCLE_CONTRACT_MARKER, bO as LifecycleContract, bP as LifecycleEffects, bQ as LiteralParam, bR as MaintainItem, bS as MaintainTrigger, bT as MaintenanceGraph, bU as ManifestEntity, bV as ManifestField, bW as ManifestFieldType, bX as ManifestGsi, bY as ManifestKey, bZ as ManifestRelation, b_ as ManifestTable, b$ as MembershipEffect, c0 as ModelRef, c1 as MutateMode, c2 as MutateOptions, c3 as MutateParallelResult, c4 as MutateTransactionResult, c5 as MutationBody, c6 as MutationDescriptorMap, c7 as MutationFragment, c8 as MutationInputProxy, c9 as MutationInputRef, ca as MutationIntent, cb as NumberParam, cc as OperationKind, cd as OperationSpec, ce as ParallelOpResult, cf as ParamKind, cg as ParamSpec, ch as ParamStructure, ci as PersistCtx, cj as PersistOrigin, ck as PlannedCommandMethod, cl as ProjectionMap, cm as ProjectionTransformOp, cn as PutOptions, co as QueryContractMethodSpec, cp as QueryEnvelopeResult, cq as QueryKeyOf, cr as QueryMethod, cs as QueryResult, ct as RangeConditionSpec, cu as ReadEnvelope, cv as ReadOpCtx, cw as ReadOpKind, cx as ReadOperationType, cy as ReadRouteDescriptor, cz as ReadRouteOptions, cA as ReadRouteResult, cB as RecordedCompose, cC as RelationBuilder, cD as RelationConsistency, cE as RelationLimitOptions, cF as RelationPattern, cG as RelationProjection, cH as RelationReadOptions, cI as RelationSelect, cJ as RelationSpec, cK as RelationUpdateMode, cL as RelationWriteOptions, cM as RequiresEffect, cN as Resolution, cO as RetryInfo, cP as RetryOperationKind, cQ as SPEC_VERSION, cR as SegmentSpec, cS as SegmentedKey, cT as SelectBuilder, cU as SelectOf, cV as SnapshotEffect, cW as StartingPosition, cX as StreamViewType, cY as StringParam, cZ as SubscribeHandler, c_ as SubscribeHandlers, c$ as TransactionContext, d0 as TransactionItemType, d1 as UniqueEffect, d2 as Updatable, d3 as UpdateOptions, d4 as ViewSourceSlice, d5 as WhenSpec, d6 as WriteCtx, d7 as WriteDescriptor, d8 as WriteEnvelope, d9 as WriteInput, da as WriteKind, db as WriteLifecyclePhase, dc as WriteMiddleware, dd as WriteOperationType, de as WriteRecorder, df as WriteResultProjection, dg as attachModelClass, dh as buildDeleteInput, di as buildMaintenanceGraph, dj as buildPutInput, dk as buildSubscribeHandler, dl as buildUpdateInput, dm as collectViewDefinitions, dn as compileFragment, dp as compileMutationPlan, dq as compileSingleFragmentPlan, dr as cond, ds as contractOfMethodSpec, dt as definePlan, du as entityWrites, dv as executeBatchGet, dw as executeBatchWrite, dx as executeCommandMethod, dy as executeDelete, dz as executeKeyedBatchGet, dA as executePut, dB as executeQueryMethod, dC as executeRangeFanout, dD as executeTransaction, dE as executeUpdate, dF as from, dG as getEntityWrites, dH as gsi, dI as identity, dJ as isColumn, dK as isCommandModelContract, dL as isCommandPlan, dM as isContractComposeNode, dN as isContractFromRef, dO as isContractKeyFieldRef, dP as isContractKeyRef, dQ as isContractParamRef, dR as isEntityWritesDefinition, dS as isKeySegment, dT as isLifecycleContract, dU as isMaintainTrigger, dV as isMutationFragment, dW as isMutationInputRef, dX as isParam, dY as isPlannedCommandMethod, dZ as isQueryModelContract, d_ as isRetryableError, d$ as isRetryableTransactionCancellation, e0 as k, e1 as key, e2 as lifecyclePhaseForIntent, e3 as maintainTrigger, e4 as mintContractKeyFieldRef, e5 as mintContractParamRef, e6 as mutation, e7 as param, e8 as preview, e9 as publicCommandModel, ea as publicQueryModel, eb as query, ec as resolveLifecycle, ed as wholeKeysSentinel } from './types-B9rJ1z3H.js';
+import { S as SelectableOf, g as PrimaryKeyOf, h as RequestContext, i as Middleware, j as ReadRequestKind, k as CtxModel, l as ReadParams, m as ReadRequestCtx, D as DynamoDBOperation, I as Item, E as Executor, n as RetryPolicy, o as ExecutionPlanSpec, p as EntityMetadata, K as KeyDefinition, G as GsiDefinition, q as ModelKind, F as FieldOptions, r as DynamoType, s as ProjectionTransform, t as MaintainEvent, u as MembershipPredicate, v as MaintainConsistency, w as MaintainUpdateMode, x as MembershipPredicateOp, y as RelationOptions, A as AggregateOptions, z as AggregateValue, H as SelectBuilderSpec, J as RawCondition, L as TransactionSpec, N as Manifest, O as RetryOverride, Q as ExecutionPlan, V as FieldMetadata, X as ResolvedKey, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, Y as CdcEmulatorOptions, Z as ChangeHandler, _ as Unsubscribe, $ as FaultSpec, a0 as ConcurrentRecomputeRef, C as ChangeEvent, a1 as EventLog, a2 as ReplayOptions, a3 as ShardId, a4 as ViewDefinition, a5 as RelationMetadata, a6 as TransactionItemSpec, a7 as MaintainEffect, M as ModelStatic, f as DDBModel, a8 as Param, a9 as ParamDescriptor, aa as DefinitionMap, ab as OperationDefinition, ac as WriteDefinitionOptions, ad as PartialQueryKeyOf, ae as StrictSelectSpec, af as ReadDefinitionOptions, ag as EntityInput, ah as UniqueQueryKeyOf, ai as EntityRef, aj as ConditionInput, ak as QueryModelContract, al as QueryMethodSpec, am as CommandModelContract, an as CommandMethodSpec, ao as ContractSpec, ap as QuerySpec, aq as CommandSpec, ar as ContextSpec, as as OperationsDocument, at as AnyOperationDefinition, au as BridgeBundle, av as ConditionSpec } from './types-m1Ect6hG.js';
+export { aw as AggregateMetadata, ax as BatchDeleteRequest, ay as BatchGetOptions, az as BatchGetRequest, aA as BatchGetResult, aB as BatchPutRequest, aC as BatchResult, aD as BatchWriteRequest, aE as CONTRACT_RANGE_FANOUT_CONCURRENCY, aF as CdcMode, aG as CdcModelRegistry, aH as CdcSubscribeHandlers, aI as Change, aJ as ChangeBatch, aK as ChangeEventName, aL as ClockMode, aM as CollectionEffect, aN as CollectionOptions, aO as Column, aP as ColumnMap, aQ as CommandContractMethodSpec, aR as CommandInputShape, aS as CommandMethod, aT as CommandPlan, aU as CommandResolutionTarget, aV as CommandResultKind, aW as CommandSelectShape, aX as CompiledFragment, aY as ComposeSpec, aZ as CondSlot, a_ as ConditionCheckInput, a$ as Connection, b0 as ContractCallSignature, b1 as ContractCardinality, b2 as ContractCommandParams, b3 as ContractCommandResult, b4 as ContractComposeNode, b5 as ContractFromRef, b6 as ContractInputArity, b7 as ContractItem, b8 as ContractKeyFieldRef, b9 as ContractKeyInput, ba as ContractKeyRef, bb as ContractKeySpec, bc as ContractKind, bd as ContractMethodOp, be as ContractParamRef, bf as ContractQueryParams, bg as ContractResolution, bh as CounterAggregate, bi as CounterEffect, bj as CtxBase, bk as DEFAULT_MAX_ATTEMPTS, bl as DEFAULT_RETRY_POLICY, bm as DeleteOptions, bn as DeriveEffect, bo as DerivedEdgeWrite, bp as DerivedUpdate, bq as DescriptorBinding, br as ENTITY_WRITES_MARKER, bs as EdgeEffect, bt as EffectPath, bu as EmbeddedMetadata, bv as EmitEffect, bw as EntityWritesDefinition, bx as EntityWritesShape, by as ExecutableCommandContract, bz as ExecutableQueryContract, bA as FilterInput, bB as FilterSpec, bC as FragmentInput, bD as GsiDefinitionMarker, bE as GsiOptions, bF as IdempotencyEffect, bG as InProcessWriteDescriptor, bH as InputArity, bI as KeyDefinitionMarker, bJ as KeySegment, bK as KeySlot, bL as KeyStructure, bM as KeyedResult, bN as LIFECYCLE_CONTRACT_MARKER, bO as LifecycleContract, bP as LifecycleEffects, bQ as LiteralParam, bR as MaintainItem, bS as MaintainTrigger, bT as MaintenanceGraph, bU as ManifestEntity, bV as ManifestField, bW as ManifestFieldType, bX as ManifestGsi, bY as ManifestKey, bZ as ManifestRelation, b_ as ManifestTable, b$ as MembershipEffect, c0 as ModelRef, c1 as MutateMode, c2 as MutateOptions, c3 as MutateParallelResult, c4 as MutateTransactionResult, c5 as MutationBody, c6 as MutationDescriptorMap, c7 as MutationFragment, c8 as MutationInputProxy, c9 as MutationInputRef, ca as MutationIntent, cb as NumberParam, cc as OperationKind, cd as OperationSpec, ce as ParallelOpResult, cf as ParamKind, cg as ParamSpec, ch as ParamStructure, ci as PersistCtx, cj as PersistOrigin, ck as PlannedCommandMethod, cl as ProjectionMap, cm as ProjectionTransformOp, cn as PutOptions, co as QueryContractMethodSpec, cp as QueryEnvelopeResult, cq as QueryKeyOf, cr as QueryMethod, cs as QueryResult, ct as RangeConditionSpec, cu as ReadEnvelope, cv as ReadOpCtx, cw as ReadOpKind, cx as ReadOperationType, cy as ReadRouteDescriptor, cz as ReadRouteOptions, cA as ReadRouteResult, cB as RecordedCompose, cC as RelationBuilder, cD as RelationConsistency, cE as RelationLimitOptions, cF as RelationPattern, cG as RelationProjection, cH as RelationReadOptions, cI as RelationSelect, cJ as RelationSpec, cK as RelationUpdateMode, cL as RelationWriteOptions, cM as RequiresEffect, cN as Resolution, cO as RetryInfo, cP as RetryOperationKind, cQ as SPEC_VERSION, cR as SegmentSpec, cS as SegmentedKey, cT as SelectBuilder, cU as SelectOf, cV as SnapshotEffect, cW as StartingPosition, cX as StreamViewType, cY as StringParam, cZ as SubscribeHandler, c_ as SubscribeHandlers, c$ as TransactionContext, d0 as TransactionItemType, d1 as UniqueEffect, d2 as Updatable, d3 as UpdateOptions, d4 as ViewSourceSlice, d5 as WhenSpec, d6 as WriteCtx, d7 as WriteDescriptor, d8 as WriteEnvelope, d9 as WriteInput, da as WriteKind, db as WriteLifecyclePhase, dc as WriteMiddleware, dd as WriteOperationType, de as WriteRecorder, df as WriteResultProjection, dg as attachModelClass, dh as buildDeleteInput, di as buildMaintenanceGraph, dj as buildPutInput, dk as buildSubscribeHandler, dl as buildUpdateInput, dm as collectViewDefinitions, dn as compileFragment, dp as compileMutationPlan, dq as compileSingleFragmentPlan, dr as cond, ds as contractOfMethodSpec, dt as definePlan, du as entityWrites, dv as executeBatchGet, dw as executeBatchWrite, dx as executeCommandMethod, dy as executeDelete, dz as executeKeyedBatchGet, dA as executePut, dB as executeQueryMethod, dC as executeRangeFanout, dD as executeTransaction, dE as executeUpdate, dF as from, dG as getEntityWrites, dH as gsi, dI as identity, dJ as isColumn, dK as isCommandModelContract, dL as isCommandPlan, dM as isContractComposeNode, dN as isContractFromRef, dO as isContractKeyFieldRef, dP as isContractKeyRef, dQ as isContractParamRef, dR as isEntityWritesDefinition, dS as isKeySegment, dT as isLifecycleContract, dU as isMaintainTrigger, dV as isMutationFragment, dW as isMutationInputRef, dX as isParam, dY as isPlannedCommandMethod, dZ as isQueryModelContract, d_ as isRetryableError, d$ as isRetryableTransactionCancellation, e0 as k, e1 as key, e2 as lifecyclePhaseForIntent, e3 as maintainTrigger, e4 as mintContractKeyFieldRef, e5 as mintContractParamRef, e6 as mutation, e7 as param, e8 as preview, e9 as publicCommandModel, ea as publicQueryModel, eb as query, ec as resolveLifecycle, ed as wholeKeysSentinel } from './types-m1Ect6hG.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 
@@ -735,6 +735,16 @@ interface MaintainedFromOptions<Self = unknown> {
     readonly when?: MembershipPredicate;
     readonly consistency?: MaintainConsistency;
     readonly updateMode?: MaintainUpdateMode;
+    /**
+     * Optional human-readable description of this maintained-from source slice (issue
+     * #166, follow-up of #154). Pure documentation metadata — it does NOT affect the
+     * maintenance IR or any runtime behaviour. Captured onto
+     * {@link MaintainedFromMetadata.description}. The maintenance IR is deliberately
+     * kept off `manifest.json` / `operations.json` and the generated Python (see the
+     * note on {@link MaintainedFromMetadata.description}), so this is a metadata-layer
+     * capture only. Omit for byte-identical metadata.
+     */
+    readonly description?: string;
 }
 /** The `(self, source) =>` symbolic callback evaluated at decoration time. */
 type MaintainedFromCallback<Self, Source> = (self: SelfProxy<Self>, source: SourceProxy<Source>) => MaintainedFromOptions<Self>;
@@ -837,7 +847,7 @@ type HasManyVersionedCallback<Self, Source> = (self: SelfProxy<Self>, source: So
 declare function hasMany(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (value: undefined, context: ClassFieldDecoratorContext) => void;
 declare function hasMany<Self = unknown, Source = unknown>(targetFactory: () => new (...args: unknown[]) => unknown, callback: HasManyVersionedCallback<Self, Source>): (value: undefined, context: ClassFieldDecoratorContext) => void;
 declare function belongsTo(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (_value: undefined, context: ClassFieldDecoratorContext) => void;
-declare function hasOne(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>): (value: undefined, context: ClassFieldDecoratorContext) => void;
+declare function hasOne(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (value: undefined, context: ClassFieldDecoratorContext) => void;
 declare function hasOne<Self = unknown, Source = unknown>(targetFactory: () => new (...args: unknown[]) => unknown, callback: HasOneVersionedCallback<Self, Source>): (value: undefined, context: ClassFieldDecoratorContext) => void;
 
 /**

package/dist/index.js

@@ -77,7 +77,7 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-FI63YKK5.js";
+} from "./chunk-H5TUW2WR.js";
 import {
   CdcEmulator,
   MAINT_OUTBOX_PK_PREFIX,
@@ -89,7 +89,7 @@ import {
   orderAndTrimCollection,
   pathField,
   projectFrom
-} from "./chunk-EMJHTUA4.js";
+} from "./chunk-QBXLQNXY.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -156,7 +156,8 @@ import {
   resolveModelClass,
   segmentFieldNames,
   serializeFieldValue
-} from "./chunk-B3GWIWT6.js";
+} from "./chunk-W3GEJPPV.js";
+import "./chunk-MCKGQKYU.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -520,7 +521,7 @@ function belongsTo(targetFactory, keyBinding, options) {
     });
   };
 }
-function hasOne(targetFactory, keyBindingOrCallback) {
+function hasOne(targetFactory, keyBindingOrCallback, options) {
   return function(_value, context) {
     const propertyName = String(context.name);
     assertRelationPropertyNameAllowed(propertyName);
@@ -547,7 +548,12 @@ function hasOne(targetFactory, keyBindingOrCallback) {
       type: "hasOne",
       propertyName,
       targetFactory,
-      keyBinding: keyBindingOrCallback
+      keyBinding: keyBindingOrCallback,
+      // Legacy navigation `@hasOne` now accepts a (purely-documentary, issue #166)
+      // `RelationOptions` third argument, symmetric with `@hasMany`/`@belongsTo`.
+      // Included ONLY when supplied so an option-less `@hasOne` records metadata with
+      // no `options` key — byte-identical to the pre-#166 collected metadata.
+      ...options !== void 0 ? { options } : {}
     });
   };
 }
@@ -681,7 +687,10 @@ function maintainedFrom(source, callback) {
       ...collection ? { collection } : {},
       ...opts.when ? { when: opts.when } : {},
       ...opts.consistency !== void 0 ? { consistency: opts.consistency } : {},
-      ...opts.updateMode !== void 0 ? { updateMode: opts.updateMode } : {}
+      ...opts.updateMode !== void 0 ? { updateMode: opts.updateMode } : {},
+      // Purely-documentary description (issue #166); recorded only when declared so an
+      // undescribed `@maintainedFrom` is byte-identical to the pre-#166 metadata.
+      ...opts.description !== void 0 ? { description: opts.description } : {}
     };
     collectMaintainedFrom(metadata);
   };

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types-B9rJ1z3H.js';
+import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types-m1Ect6hG.js';
 import '@aws-sdk/client-dynamodb';
 
 /**

package/dist/testing/index.js

@@ -1,12 +1,13 @@
 import {
   createCdcEmulator
-} from "../chunk-EMJHTUA4.js";
+} from "../chunk-QBXLQNXY.js";
 import {
   ClientManager,
   MetadataRegistry,
   TableMapping,
   resolveModelClass
-} from "../chunk-B3GWIWT6.js";
+} from "../chunk-W3GEJPPV.js";
+import "../chunk-MCKGQKYU.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {