graphddb 0.4.0 → 0.4.2

package/dist/{chunk-GWFZVNAV.js → chunk-BROCT574.js}

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

package/dist/{chunk-72VZYOSG.js → chunk-CPTV3H2U.js}

@@ -984,30 +984,46 @@ var TableMapping = class {
 };
 
 // src/define/param.ts
-function makeParam(kind, literals) {
-  return literals === void 0 ? { kind } : { kind, literals };
+function isParamOptions(value) {
+  return typeof value === "object" && value !== null;
+}
+function makeParam(kind, literals, description) {
+  const param2 = { kind };
+  if (literals !== void 0) param2.literals = literals;
+  if (description !== void 0) param2.description = description;
+  return param2;
 }
 var param = {
   /** A placeholder for a `string` value. */
-  string() {
-    return makeParam("string");
+  string(options) {
+    return makeParam("string", void 0, options?.description);
   },
   /** A placeholder for a `number` value. */
-  number() {
-    return makeParam("number");
+  number(options) {
+    return makeParam("number", void 0, options?.description);
   },
   /**
    * A placeholder constrained to one of the given literal values. The value
    * type of the resulting {@link Param} is the **union of the literals**, so it
-   * is preserved precisely in the IR and the inferred definition types.
+   * is preserved precisely in the IR and the inferred definition types. A final
+   * plain-object argument is read as {@link ParamOptions} (a `description`),
+   * distinguished from the `string` / `number` literal values.
    *
    * @example
    * ```ts
    * param.literal('active', 'disabled'); // Param<'active' | 'disabled'>
+   * param.literal('active', 'disabled', { description: 'Account state.' });
    * ```
    */
-  literal(...values) {
-    return makeParam("literal", values);
+  literal(...valuesAndOptions) {
+    const args = [...valuesAndOptions];
+    const last = args[args.length - 1];
+    const options = isParamOptions(last) ? args.pop() : void 0;
+    return makeParam(
+      "literal",
+      args,
+      options?.description
+    );
   },
   /**
    * A placeholder for an **array** parameter whose elements have the given field
@@ -1020,8 +1036,10 @@ var param = {
    * // Param<{ userId: string; role: string }[]>
    * ```
    */
-  array(element) {
-    return { kind: "array", element };
+  array(element, options) {
+    const param2 = { kind: "array", element };
+    if (options?.description !== void 0) param2.description = options.description;
+    return param2;
   }
 };
 function isParam(value) {

package/dist/{chunk-PC54CW5P.js → chunk-G5RWWBAL.js}

@@ -42,7 +42,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-72VZYOSG.js";
+} from "./chunk-CPTV3H2U.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -111,7 +111,12 @@ function buildFields(metadata) {
   const fields = {};
   for (const field of metadata.fields) {
     const format = field.options?.format;
-    fields[field.propertyName] = format ? { type: DYNAMO_TYPE_TO_FIELD_TYPE[field.dynamoType], format } : { type: DYNAMO_TYPE_TO_FIELD_TYPE[field.dynamoType] };
+    const description = field.options?.description;
+    fields[field.propertyName] = {
+      type: DYNAMO_TYPE_TO_FIELD_TYPE[field.dynamoType],
+      ...format ? { format } : {},
+      ...description !== void 0 ? { description } : {}
+    };
   }
   return sortedRecord(fields);
 }
@@ -123,7 +128,8 @@ function buildEntity(metadata) {
     fields: buildFields(metadata),
     key: buildKey(metadata.primaryKey),
     gsis: buildGsis(metadata),
-    relations: buildRelations(metadata)
+    relations: buildRelations(metadata),
+    ...metadata.description !== void 0 ? { description: metadata.description } : {}
   };
 }
 function buildManifest(registry = MetadataRegistry) {
@@ -3572,7 +3578,8 @@ function buildQueryContract(methods) {
       op,
       resolution,
       inputArity,
-      __methodName: name
+      __methodName: name,
+      ...op.description !== void 0 ? { description: op.description } : {}
     };
   }
   const contract = { __isContract: true, kind: "query", methods: resolved };
@@ -3586,8 +3593,8 @@ function buildCommandContract(methods) {
   const resolved = {};
   for (const [name, body] of Object.entries(methods)) {
     if (isPublicWriteDescriptor(body)) {
-      const { plan: plan2, select, condition, mode } = writeDescriptorToPlan(name, body);
-      resolved[name] = finalizeDescriptorCommand(name, plan2, select, condition, mode);
+      const { plan: plan2, select, condition, mode, description } = writeDescriptorToPlan(name, body);
+      resolved[name] = finalizeDescriptorCommand(name, plan2, select, condition, mode, description);
       continue;
     }
     if (isPublicComposeDescriptor(body)) {
@@ -3597,7 +3604,8 @@ function buildCommandContract(methods) {
         body.command,
         select,
         void 0,
-        body.mode ?? "transaction"
+        body.mode ?? "transaction",
+        body.description
       );
       continue;
     }
@@ -3662,7 +3670,7 @@ function buildPlannedCommandMethod(name, planned) {
     ...returnSelection !== void 0 ? { returnSelection } : {}
   };
 }
-function finalizeDescriptorCommand(name, plan2, select, condition, mode) {
+function finalizeDescriptorCommand(name, plan2, select, condition, mode, description) {
   const planned = {
     [PLANNED_COMMAND_BRAND]: true,
     plan: plan2,
@@ -3674,7 +3682,8 @@ function finalizeDescriptorCommand(name, plan2, select, condition, mode) {
   return {
     ...built,
     op,
-    mode
+    mode,
+    ...description !== void 0 ? { description } : {}
   };
 }
 function normalizeReturnSelection(select) {
@@ -3760,7 +3769,8 @@ function readDescriptorToOp(name, d) {
     keys,
     ...isQuery ? { keyFields: keyFieldNames2 } : {},
     ...select !== void 0 ? { select } : {},
-    ...compose.length > 0 ? { compose } : {}
+    ...compose.length > 0 ? { compose } : {},
+    ...d.description !== void 0 ? { description: d.description } : {}
   };
 }
 function writeDescriptorToPlan(name, d) {
@@ -3794,7 +3804,7 @@ function writeDescriptorToPlan(name, d) {
   });
   const select = d.result !== void 0 && d.result.select !== void 0 ? d.result.select : void 0;
   const condition = d.condition !== void 0 ? descriptorConditionRecord(d.condition, name) : void 0;
-  return { plan: plan2, select, condition, mode: d.mode ?? "transaction" };
+  return { plan: plan2, select, condition, mode: d.mode ?? "transaction", description: d.description };
 }
 
 // src/spec/mutation-command.ts
@@ -5697,10 +5707,12 @@ function paramSpecs(params) {
   const out = {};
   for (const name of Object.keys(params).sort()) {
     const d = params[name];
-    out[name] = d.literals === void 0 ? { type: d.kind, required: d.required } : {
+    out[name] = {
       type: d.kind,
       required: d.required,
-      literals: d.literals
+      ...d.literals !== void 0 ? { literals: d.literals } : {},
+      // Pure-documentation description (issue #154); absent → byte-identical spec.
+      ...d.description !== void 0 ? { description: d.description } : {}
     };
   }
   return out;
@@ -5929,6 +5941,7 @@ function buildCommandSpec(def) {
   const params = paramSpecs(def.params);
   const entity = def.entity.name;
   const condition = extractCondition(def);
+  const description = def.description !== void 0 ? { description: def.description } : {};
   if (def.operation === "put") {
     const item = templateRecord3(def.key);
     return {
@@ -5937,7 +5950,8 @@ function buildCommandSpec(def) {
       entity,
       params,
       item,
-      ...condition ? { condition } : {}
+      ...condition ? { condition } : {},
+      ...description
     };
   }
   if (def.operation === "delete") {
@@ -5947,7 +5961,8 @@ function buildCommandSpec(def) {
       entity,
       params,
       keyCondition: writeKeyCondition(metadata, def.key, entity),
-      ...condition ? { condition } : {}
+      ...condition ? { condition } : {},
+      ...description
     };
   }
   return {
@@ -5957,7 +5972,8 @@ function buildCommandSpec(def) {
     params,
     keyCondition: writeKeyCondition(metadata, def.key, entity),
     changes: templateRecord3(def.changes),
-    ...condition ? { condition } : {}
+    ...condition ? { condition } : {},
+    ...description
   };
 }
 function writeKeyCondition(metadata, key, entity) {
@@ -6024,7 +6040,9 @@ function buildQuerySpec(def) {
     operations,
     // `defineQuery` → a single entity object; `defineList` → a connection.
     cardinality: def.operation === "query" ? "one" : "many",
-    ...executionPlan !== void 0 ? { executionPlan } : {}
+    ...executionPlan !== void 0 ? { executionPlan } : {},
+    // Pure-documentation description (issue #154); absent → byte-identical spec.
+    ...def.description !== void 0 ? { description: def.description } : {}
   };
 }
 function mergeSpecs(base, synthesized, kind) {
@@ -6788,7 +6806,9 @@ function serializeQueryContract(contractName, contract, querySpecs, contracts) {
       cardinality: method.resolution === "point" ? "one" : "many",
       operation: opName,
       ...compose.length > 0 ? { compose } : {},
-      ...compositionPlan !== void 0 ? { compositionPlan } : {}
+      ...compositionPlan !== void 0 ? { compositionPlan } : {},
+      // Pure-documentation description (issue #154); absent → byte-identical spec.
+      ...method.description !== void 0 ? { description: method.description } : {}
     };
   }
   return {
@@ -6876,7 +6896,9 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
       result: method.result,
       single,
       ...batch !== void 0 ? { batch } : {},
-      ...returnSelection !== void 0 && Object.keys(returnSelection).length > 0 ? { returnSelection: sortedReturnSelection(returnSelection) } : {}
+      ...returnSelection !== void 0 && Object.keys(returnSelection).length > 0 ? { returnSelection: sortedReturnSelection(returnSelection) } : {},
+      // Pure-documentation description (issue #154); absent → byte-identical spec.
+      ...method.description !== void 0 ? { description: method.description } : {}
     };
   }
   return {

package/dist/cli.js

@@ -2,10 +2,10 @@
 import {
   buildBridgeBundle,
   normalizeSelectSpec
-} from "./chunk-PC54CW5P.js";
+} from "./chunk-G5RWWBAL.js";
 import {
   MetadataRegistry
-} from "./chunk-72VZYOSG.js";
+} from "./chunk-CPTV3H2U.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -467,9 +467,16 @@ function pyTransactionParamType(txName, paramName, spec) {
   }
   return pyParamType(spec);
 }
+function pyDocLine(text) {
+  return text.replace(/\\/g, "\\\\").replace(/"""/g, '\\"\\"\\"').replace(/\r?\n/g, " ").trim();
+}
+function pyCommentLine(text) {
+  return text.replace(/\r?\n/g, " ").trim();
+}
 function collectResultTypes(manifest, entity, select, typeName, out, seen) {
   const meta = manifest.entities[entity];
   const fields = [];
+  const fieldDescriptions = {};
   for (const field of Object.keys(select).sort()) {
     const value = select[field];
     const relation = meta?.relations[field];
@@ -504,13 +511,23 @@ function collectResultTypes(manifest, entity, select, typeName, out, seen) {
       continue;
     }
     if (value === true) {
-      const fieldType = meta?.fields[field]?.type ?? "string";
+      const manifestField = meta?.fields[field];
+      const fieldType = manifestField?.type ?? "string";
       fields.push([field, pyScalarType(fieldType)]);
+      if (manifestField?.description !== void 0) {
+        fieldDescriptions[field] = manifestField.description;
+      }
     }
   }
   if (!seen.has(typeName)) {
     seen.add(typeName);
-    out.push({ name: typeName, fields });
+    out.push({
+      name: typeName,
+      fields,
+      ...Object.keys(fieldDescriptions).length > 0 ? { fieldDescriptions } : {},
+      // The entity's own description (issue #154) becomes the result class docstring.
+      ...meta?.description !== void 0 ? { docstring: meta.description } : {}
+    });
   }
 }
 function selectOf(def) {
@@ -519,29 +536,44 @@ function selectOf(def) {
 function queryResultTypeName(queryName) {
   return `${toPascalCase(queryName)}Result`;
 }
+function classDocstringLines(cls) {
+  return cls.docstring !== void 0 ? [`    """${pyDocLine(cls.docstring)}"""`] : [];
+}
+function withFieldComment(cls, name, line) {
+  const desc = cls.fieldDescriptions?.[name];
+  return desc !== void 0 ? `${line}  # ${pyCommentLine(desc)}` : line;
+}
 function renderTypedDict(cls) {
+  const doc = classDocstringLines(cls);
   if (cls.fields.length === 0) {
-    return `class ${cls.name}(TypedDict):
+    return doc.length > 0 ? `class ${cls.name}(TypedDict):
+${doc.join("\n")}` : `class ${cls.name}(TypedDict):
     pass`;
   }
-  const lines = cls.fields.map(([name, type]) => `    ${name}: ${type}`);
+  const lines = cls.fields.map(
+    ([name, type]) => withFieldComment(cls, name, `    ${name}: ${type}`)
+  );
   return `class ${cls.name}(TypedDict):
-${lines.join("\n")}`;
+${[...doc, ...lines].join("\n")}`;
 }
 function renderDataclass(cls) {
+  const doc = classDocstringLines(cls);
   if (cls.fields.length === 0) {
-    return `@dataclass
+    return doc.length > 0 ? `@dataclass
+class ${cls.name}:
+${doc.join("\n")}` : `@dataclass
 class ${cls.name}:
     pass`;
   }
   const lines = cls.fields.map(
-    ([name, type]) => type.endsWith("| None") ? `    ${name}: ${type} = None` : `    ${name}: ${type}`
+    ([name, type]) => type.endsWith("| None") ? withFieldComment(cls, name, `    ${name}: ${type} = None`) : withFieldComment(cls, name, `    ${name}: ${type}`)
   );
-  const required = lines.filter((l) => !l.endsWith("= None"));
-  const optional = lines.filter((l) => l.endsWith("= None"));
+  const isOptional = (l) => /:\s.*\| None\s*=\sNone(\s+#.*)?$/.test(l);
+  const required = lines.filter((l) => !isOptional(l));
+  const optional = lines.filter(isOptional);
   return `@dataclass
 class ${cls.name}:
-${[...required, ...optional].join("\n")}`;
+${[...doc, ...required, ...optional].join("\n")}`;
 }
 function collectTransactionElementTypes(transactions, out, seen) {
   for (const txName of Object.keys(transactions).sort()) {
@@ -625,7 +657,8 @@ function collectRepositories(queries, commands) {
       params: methodParams(def),
       returnType: `${queryResultTypeName(name)} | None`,
       kind: "query",
-      operationId: name
+      operationId: name,
+      ...def.description !== void 0 ? { description: def.description } : {}
     });
   }
   for (const name of Object.keys(commands).sort()) {
@@ -635,7 +668,8 @@ function collectRepositories(queries, commands) {
       params: methodParams(def),
       returnType: "None",
       kind: "command",
-      operationId: name
+      operationId: name,
+      ...def.description !== void 0 ? { description: def.description } : {}
     });
   }
   return [...byEntity.keys()].sort().map((className) => ({
@@ -646,11 +680,13 @@ function collectRepositories(queries, commands) {
 function renderMethod(m) {
   const sig = m.params.map((p) => `${p.argName}: ${p.pyType}`).join(", ");
   const head = `    def ${m.methodName}(self${sig ? ", " + sig : ""}) -> ${m.returnType}:`;
+  const doc = m.description !== void 0 ? [`        """${pyDocLine(m.description)}"""`] : [];
   const paramsDict = m.params.map((p) => `"${p.originalName}": ${p.argName}`).join(", ");
   const paramsArg = paramsDict ? `{${paramsDict}}` : "{}";
   if (m.kind === "query") {
     return [
       head,
+      ...doc,
       `        return self._runtime.execute_query(`,
       `            query_id="${m.operationId}",`,
       `            params=${paramsArg},`,
@@ -659,6 +695,7 @@ function renderMethod(m) {
   }
   return [
     head,
+    ...doc,
     `        self._runtime.execute_command(`,
     `            command_id="${m.operationId}",`,
     `            params=${paramsArg},`,

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 EntityInput, ag as UniqueQueryKeyOf, ah as EntityRef, ai as ConditionInput, aj as QueryModelContract, ak as QueryMethodSpec, al as CommandModelContract, am as CommandMethodSpec, an as ContractSpec, ao as QuerySpec, ap as CommandSpec, aq as ContextSpec, ar as OperationsDocument, as as AnyOperationDefinition, at as BridgeBundle, au as ConditionSpec } from './types-CpCo8yHP.js';
-export { av as AggregateMetadata, aw as BatchDeleteRequest, ax as BatchGetOptions, ay as BatchGetRequest, az as BatchGetResult, aA as BatchPutRequest, aB as BatchResult, aC as BatchWriteRequest, aD as CONTRACT_RANGE_FANOUT_CONCURRENCY, aE as CdcMode, aF as Change, aG as ChangeBatch, aH as ChangeEventName, aI as ClockMode, aJ as CollectionEffect, aK as CollectionOptions, aL as Column, aM as ColumnMap, aN as CommandContractMethodSpec, aO as CommandInputShape, aP as CommandMethod, aQ as CommandPlan, aR as CommandResolutionTarget, aS as CommandResultKind, aT as CommandSelectShape, aU as CompiledFragment, aV as ComposeSpec, aW as CondSlot, aX as ConditionCheckInput, aY as Connection, aZ as ContractCallSignature, a_ as ContractCardinality, a$ as ContractCommandParams, b0 as ContractCommandResult, b1 as ContractComposeNode, b2 as ContractFromRef, b3 as ContractInputArity, b4 as ContractItem, b5 as ContractKeyFieldRef, b6 as ContractKeyInput, b7 as ContractKeyRef, b8 as ContractKeySpec, b9 as ContractKind, ba as ContractMethodOp, bb as ContractParamRef, bc as ContractQueryParams, bd as ContractResolution, be as CounterAggregate, bf as CounterEffect, bg as CtxBase, bh as DEFAULT_MAX_ATTEMPTS, bi as DEFAULT_RETRY_POLICY, bj as DeleteOptions, bk as DeriveEffect, bl as DerivedEdgeWrite, bm as DerivedUpdate, bn as DescriptorBinding, bo as ENTITY_WRITES_MARKER, bp as EdgeEffect, bq as EffectPath, br as EmbeddedMetadata, bs as EmitEffect, bt as EntityWritesDefinition, bu as EntityWritesShape, bv as ExecutableCommandContract, bw as ExecutableQueryContract, bx as FilterInput, by as FilterSpec, bz as FragmentInput, bA as GsiDefinitionMarker, bB as GsiOptions, bC as IdempotencyEffect, bD as InProcessWriteDescriptor, bE as InputArity, bF as KeyDefinitionMarker, bG as KeySegment, bH as KeySlot, bI as KeyStructure, bJ as KeyedResult, bK as LIFECYCLE_CONTRACT_MARKER, bL as LifecycleContract, bM as LifecycleEffects, bN as LiteralParam, bO as MaintainItem, bP as MaintainTrigger, bQ as MaintenanceGraph, bR as ManifestEntity, bS as ManifestField, bT as ManifestFieldType, bU as ManifestGsi, bV as ManifestKey, bW as ManifestRelation, bX as ManifestTable, bY as MembershipEffect, bZ as ModelRef, b_ as MutateMode, b$ as MutateOptions, c0 as MutateParallelResult, c1 as MutateTransactionResult, c2 as MutationBody, c3 as MutationDescriptorMap, c4 as MutationFragment, c5 as MutationInputProxy, c6 as MutationInputRef, c7 as MutationIntent, c8 as NumberParam, c9 as OperationKind, ca as OperationSpec, cb as ParallelOpResult, cc as ParamKind, cd as ParamSpec, ce as ParamStructure, cf as PersistCtx, cg as PersistOrigin, ch as PlannedCommandMethod, ci as ProjectionMap, cj as ProjectionTransformOp, ck as PutOptions, cl as QueryContractMethodSpec, cm as QueryEnvelopeResult, cn as QueryKeyOf, co as QueryMethod, cp as QueryResult, cq as RangeConditionSpec, cr as ReadEnvelope, cs as ReadOpCtx, ct as ReadOpKind, cu as ReadOperationType, cv as ReadRouteDescriptor, cw as ReadRouteOptions, cx as ReadRouteResult, cy as RecordedCompose, cz as RelationBuilder, cA as RelationConsistency, cB as RelationLimitOptions, cC as RelationPattern, cD as RelationProjection, cE as RelationReadOptions, cF as RelationSelect, cG as RelationSpec, cH as RelationUpdateMode, cI as RelationWriteOptions, cJ as RequiresEffect, cK as Resolution, cL as RetryInfo, cM as RetryOperationKind, cN as SPEC_VERSION, cO as SegmentSpec, cP as SegmentedKey, cQ as SelectBuilder, cR as SelectOf, cS as SnapshotEffect, cT as StartingPosition, cU as StreamViewType, cV as StringParam, cW as TransactionContext, cX as TransactionItemType, cY as UniqueEffect, cZ as Updatable, c_ as UpdateOptions, c$ as ViewSourceSlice, d0 as WhenSpec, d1 as WriteCtx, d2 as WriteDescriptor, d3 as WriteEnvelope, d4 as WriteInput, d5 as WriteKind, d6 as WriteLifecyclePhase, d7 as WriteMiddleware, d8 as WriteOperationType, d9 as WriteRecorder, da as WriteResultProjection, db as attachModelClass, dc as buildDeleteInput, dd as buildMaintenanceGraph, de as buildPutInput, df as buildUpdateInput, dg as collectViewDefinitions, dh as compileFragment, di as compileMutationPlan, dj as compileSingleFragmentPlan, dk as cond, dl as contractOfMethodSpec, dm as definePlan, dn as entityWrites, dp as executeBatchGet, dq as executeBatchWrite, dr as executeCommandMethod, ds as executeDelete, dt as executeKeyedBatchGet, du as executePut, dv as executeQueryMethod, dw as executeRangeFanout, dx as executeTransaction, dy as executeUpdate, dz as from, dA as getEntityWrites, dB as gsi, dC as identity, dD as isColumn, dE as isCommandModelContract, dF as isCommandPlan, dG as isContractComposeNode, dH as isContractFromRef, dI as isContractKeyFieldRef, dJ as isContractKeyRef, dK as isContractParamRef, dL as isEntityWritesDefinition, dM as isKeySegment, dN as isLifecycleContract, dO as isMaintainTrigger, dP as isMutationFragment, dQ as isMutationInputRef, dR as isParam, dS as isPlannedCommandMethod, dT as isQueryModelContract, dU as isRetryableError, dV as isRetryableTransactionCancellation, dW as k, dX as key, dY as lifecyclePhaseForIntent, dZ as maintainTrigger, d_ as mintContractKeyFieldRef, d$ as mintContractParamRef, e0 as mutation, e1 as param, e2 as preview, e3 as publicCommandModel, e4 as publicQueryModel, e5 as query, e6 as resolveLifecycle, e7 as wholeKeysSentinel } from './types-CpCo8yHP.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-BWOrWcbd.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 Change, aH as ChangeBatch, aI as ChangeEventName, aJ as ClockMode, aK as CollectionEffect, aL as CollectionOptions, aM as Column, aN as ColumnMap, aO as CommandContractMethodSpec, aP as CommandInputShape, aQ as CommandMethod, aR as CommandPlan, aS as CommandResolutionTarget, aT as CommandResultKind, aU as CommandSelectShape, aV as CompiledFragment, aW as ComposeSpec, aX as CondSlot, aY as ConditionCheckInput, aZ as Connection, a_ as ContractCallSignature, a$ as ContractCardinality, b0 as ContractCommandParams, b1 as ContractCommandResult, b2 as ContractComposeNode, b3 as ContractFromRef, b4 as ContractInputArity, b5 as ContractItem, b6 as ContractKeyFieldRef, b7 as ContractKeyInput, b8 as ContractKeyRef, b9 as ContractKeySpec, ba as ContractKind, bb as ContractMethodOp, bc as ContractParamRef, bd as ContractQueryParams, be as ContractResolution, bf as CounterAggregate, bg as CounterEffect, bh as CtxBase, bi as DEFAULT_MAX_ATTEMPTS, bj as DEFAULT_RETRY_POLICY, bk as DeleteOptions, bl as DeriveEffect, bm as DerivedEdgeWrite, bn as DerivedUpdate, bo as DescriptorBinding, bp as ENTITY_WRITES_MARKER, bq as EdgeEffect, br as EffectPath, bs as EmbeddedMetadata, bt as EmitEffect, bu as EntityWritesDefinition, bv as EntityWritesShape, bw as ExecutableCommandContract, bx as ExecutableQueryContract, by as FilterInput, bz as FilterSpec, bA as FragmentInput, bB as GsiDefinitionMarker, bC as GsiOptions, bD as IdempotencyEffect, bE as InProcessWriteDescriptor, bF as InputArity, bG as KeyDefinitionMarker, bH as KeySegment, bI as KeySlot, bJ as KeyStructure, bK as KeyedResult, bL as LIFECYCLE_CONTRACT_MARKER, bM as LifecycleContract, bN as LifecycleEffects, bO as LiteralParam, bP as MaintainItem, bQ as MaintainTrigger, bR as MaintenanceGraph, bS as ManifestEntity, bT as ManifestField, bU as ManifestFieldType, bV as ManifestGsi, bW as ManifestKey, bX as ManifestRelation, bY as ManifestTable, bZ as MembershipEffect, b_ as ModelRef, b$ as MutateMode, c0 as MutateOptions, c1 as MutateParallelResult, c2 as MutateTransactionResult, c3 as MutationBody, c4 as MutationDescriptorMap, c5 as MutationFragment, c6 as MutationInputProxy, c7 as MutationInputRef, c8 as MutationIntent, c9 as NumberParam, ca as OperationKind, cb as OperationSpec, cc as ParallelOpResult, cd as ParamKind, ce as ParamSpec, cf as ParamStructure, cg as PersistCtx, ch as PersistOrigin, ci as PlannedCommandMethod, cj as ProjectionMap, ck as ProjectionTransformOp, cl as PutOptions, cm as QueryContractMethodSpec, cn as QueryEnvelopeResult, co as QueryKeyOf, cp as QueryMethod, cq as QueryResult, cr as RangeConditionSpec, cs as ReadEnvelope, ct as ReadOpCtx, cu as ReadOpKind, cv as ReadOperationType, cw as ReadRouteDescriptor, cx as ReadRouteOptions, cy as ReadRouteResult, cz as RecordedCompose, cA as RelationBuilder, cB as RelationConsistency, cC as RelationLimitOptions, cD as RelationPattern, cE as RelationProjection, cF as RelationReadOptions, cG as RelationSelect, cH as RelationSpec, cI as RelationUpdateMode, cJ as RelationWriteOptions, cK as RequiresEffect, cL as Resolution, cM as RetryInfo, cN as RetryOperationKind, cO as SPEC_VERSION, cP as SegmentSpec, cQ as SegmentedKey, cR as SelectBuilder, cS as SelectOf, cT as SnapshotEffect, cU as StartingPosition, cV as StreamViewType, cW as StringParam, cX as TransactionContext, cY as TransactionItemType, cZ as UniqueEffect, c_ as Updatable, c$ as UpdateOptions, d0 as ViewSourceSlice, d1 as WhenSpec, d2 as WriteCtx, d3 as WriteDescriptor, d4 as WriteEnvelope, d5 as WriteInput, d6 as WriteKind, d7 as WriteLifecyclePhase, d8 as WriteMiddleware, d9 as WriteOperationType, da as WriteRecorder, db as WriteResultProjection, dc as attachModelClass, dd as buildDeleteInput, de as buildMaintenanceGraph, df as buildPutInput, dg as buildUpdateInput, dh as collectViewDefinitions, di as compileFragment, dj as compileMutationPlan, dk as compileSingleFragmentPlan, dl as cond, dm as contractOfMethodSpec, dn as definePlan, dp as entityWrites, dq as executeBatchGet, dr as executeBatchWrite, ds as executeCommandMethod, dt as executeDelete, du as executeKeyedBatchGet, dv as executePut, dw as executeQueryMethod, dx as executeRangeFanout, dy as executeTransaction, dz as executeUpdate, dA as from, dB as getEntityWrites, dC as gsi, dD as identity, dE as isColumn, dF as isCommandModelContract, dG as isCommandPlan, dH as isContractComposeNode, dI as isContractFromRef, dJ as isContractKeyFieldRef, dK as isContractKeyRef, dL as isContractParamRef, dM as isEntityWritesDefinition, dN as isKeySegment, dO as isLifecycleContract, dP as isMaintainTrigger, dQ as isMutationFragment, dR as isMutationInputRef, dS as isParam, dT as isPlannedCommandMethod, dU as isQueryModelContract, dV as isRetryableError, dW as isRetryableTransactionCancellation, dX as k, dY as key, dZ as lifecyclePhaseForIntent, d_ as maintainTrigger, d$ as mintContractKeyFieldRef, e0 as mintContractParamRef, e1 as mutation, e2 as param, e3 as preview, e4 as publicCommandModel, e5 as publicQueryModel, e6 as query, e7 as resolveLifecycle, e8 as wholeKeysSentinel } from './types-BWOrWcbd.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 
@@ -386,6 +386,13 @@ interface ModelOptions {
      * adapter validates this).
      */
     kind?: ModelKind;
+    /**
+     * Optional human-readable description of the entity (issue #154). Pure
+     * documentation metadata — recorded into {@link EntityMetadata.description} and
+     * propagated to `manifest.json` + the generated Python class docstring. It does
+     * NOT affect storage, keys, or any runtime behaviour. Omit for unchanged output.
+     */
+    description?: string;
 }
 declare function model(options: ModelOptions): (target: Function, context: ClassDecoratorContext) => void;
 
@@ -2262,13 +2269,13 @@ type EntityOf<M> = M extends ModelStatic<infer T, infer _C> ? T : never;
  * the model's unique-key boundary (`UniqueQueryKeyOf`); `select` is the strict
  * projection (#37) typed against the entity.
  */
-declare function defineQuery<M extends ModelStatic<DDBModel, AnyModelClass>, const K extends Parameterize<UniqueQueryKeyOf<ClassOf<M>>>, const S extends SelectableOf<EntityOf<M>>>(model: M, key: K & ExactParam<UniqueQueryKeyOf<ClassOf<M>>, K>, select: S & StrictSelectSpec<EntityOf<M>, S>): OperationDefinition<EntityOf<M>, 'query', K, S, undefined, CollectParams<K>>;
+declare function defineQuery<M extends ModelStatic<DDBModel, AnyModelClass>, const K extends Parameterize<UniqueQueryKeyOf<ClassOf<M>>>, const S extends SelectableOf<EntityOf<M>>>(model: M, key: K & ExactParam<UniqueQueryKeyOf<ClassOf<M>>, K>, select: S & StrictSelectSpec<EntityOf<M>, S>, options?: ReadDefinitionOptions): OperationDefinition<EntityOf<M>, 'query', K, S, undefined, CollectParams<K>>;
 /**
  * Define a parameterized **partition read** (`list`). The `key` accepts a
  * partial (partition-key) input with {@link Param} placeholders; `select` is
  * the strict projection typed against the entity.
  */
-declare function defineList<M extends ModelStatic<DDBModel, AnyModelClass>, const K extends Parameterize<PartialQueryKeyOf<ClassOf<M>>>, const S extends SelectableOf<EntityOf<M>>>(model: M, key: K & ExactParam<PartialQueryKeyOf<ClassOf<M>>, K>, select: S & StrictSelectSpec<EntityOf<M>, S>): OperationDefinition<EntityOf<M>, 'list', K, S, undefined, CollectParams<K>>;
+declare function defineList<M extends ModelStatic<DDBModel, AnyModelClass>, const K extends Parameterize<PartialQueryKeyOf<ClassOf<M>>>, const S extends SelectableOf<EntityOf<M>>>(model: M, key: K & ExactParam<PartialQueryKeyOf<ClassOf<M>>, K>, select: S & StrictSelectSpec<EntityOf<M>, S>, options?: ReadDefinitionOptions): OperationDefinition<EntityOf<M>, 'list', K, S, undefined, CollectParams<K>>;
 /**
  * Define a parameterized **put** (`put`). The `item` accepts {@link Param}
  * placeholders at scalar leaves and is otherwise checked against `EntityInput`

package/dist/index.js

@@ -79,7 +79,7 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-PC54CW5P.js";
+} from "./chunk-G5RWWBAL.js";
 import {
   CdcEmulator,
   MAINT_OUTBOX_PK_PREFIX,
@@ -91,7 +91,7 @@ import {
   orderAndTrimCollection,
   pathField,
   projectFrom
-} from "./chunk-GWFZVNAV.js";
+} from "./chunk-BROCT574.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -154,7 +154,7 @@ import {
   resolveModelClass,
   segmentFieldNames,
   serializeFieldValue
-} from "./chunk-72VZYOSG.js";
+} from "./chunk-CPTV3H2U.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -277,6 +277,7 @@ function model(options) {
       aggregates,
       embeddedFields,
       kind,
+      ...options.description !== void 0 ? { description: options.description } : {},
       maintainedFrom: maintainedFrom2
     });
   };
@@ -1596,7 +1597,15 @@ function collectParams(structure, out = {}) {
   return out;
 }
 function descriptorFromParam(name, value, existing) {
-  const descriptor = value.literals === void 0 ? { kind: value.kind, required: true } : { kind: value.kind, literals: value.literals, required: true };
+  const descriptor = {
+    kind: value.kind,
+    ...value.literals !== void 0 ? { literals: value.literals } : {},
+    // Pure-documentation description (issue #154); carried through verbatim. Does
+    // not participate in the conflicting-kind check below (it is not part of the
+    // execution-relevant descriptor identity).
+    ...value.description !== void 0 ? { description: value.description } : {},
+    required: true
+  };
   if (existing !== void 0 && existing.kind !== descriptor.kind) {
     throw new Error(
       `Parameter '${name}' is declared with conflicting types ('${existing.kind}' and '${descriptor.kind}'). A parameter name must have a single type across a definition.`
@@ -1693,7 +1702,7 @@ function collectConditionTreeParams(obj, out) {
     }
   }
 }
-function makeDefinition(model2, operation, key2, select, changes, condition) {
+function makeDefinition(model2, operation, key2, select, changes, condition, description) {
   const params = collectParams(key2);
   if (changes !== void 0) collectParams(changes, params);
   collectConditionParams(condition, params);
@@ -1705,25 +1714,30 @@ function makeDefinition(model2, operation, key2, select, changes, condition) {
     select,
     changes,
     ...condition !== void 0 ? { condition } : {},
+    ...description !== void 0 ? { description } : {},
     params
   };
 }
-function defineQuery(model2, key2, select) {
+function defineQuery(model2, key2, select, options) {
   return makeDefinition(
     model2,
     "query",
     key2,
     select,
-    void 0
+    void 0,
+    void 0,
+    options?.description
   );
 }
-function defineList(model2, key2, select) {
+function defineList(model2, key2, select, options) {
   return makeDefinition(
     model2,
     "list",
     key2,
     select,
-    void 0
+    void 0,
+    void 0,
+    options?.description
   );
 }
 function definePut(model2, item, options) {
@@ -1733,7 +1747,8 @@ function definePut(model2, item, options) {
     item,
     void 0,
     void 0,
-    options?.condition
+    options?.condition,
+    options?.description
   );
 }
 function defineUpdate(model2, key2, changes, options) {
@@ -1743,7 +1758,8 @@ function defineUpdate(model2, key2, changes, options) {
     key2,
     void 0,
     changes,
-    options?.condition
+    options?.condition,
+    options?.description
   );
 }
 function defineDelete(model2, key2, options) {
@@ -1753,7 +1769,8 @@ function defineDelete(model2, key2, options) {
     key2,
     void 0,
     void 0,
-    options?.condition
+    options?.condition,
+    options?.description
   );
 }
 function defineQueries(definitions) {

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-CpCo8yHP.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-BWOrWcbd.js';
 import '@aws-sdk/client-dynamodb';
 
 /**

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-GWFZVNAV.js";
+} from "../chunk-BROCT574.js";
 import {
   ClientManager,
   MetadataRegistry,
   TableMapping,
   resolveModelClass
-} from "../chunk-72VZYOSG.js";
+} from "../chunk-CPTV3H2U.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {