graphddb 0.5.1 → 0.5.3

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

@@ -1,103 +1,13 @@
-// src/select/column.ts
-var COLUMN_REF = /* @__PURE__ */ Symbol.for("graphddb.columnRef");
-function isColumn(value) {
-  return typeof value === "object" && value !== null && value[COLUMN_REF] === true;
-}
-function createColumnMap() {
-  const cache = /* @__PURE__ */ new Map();
-  return new Proxy(
-    {},
-    {
-      get(_target, prop) {
-        if (typeof prop !== "string") return void 0;
-        let col = cache.get(prop);
-        if (!col) {
-          col = { [COLUMN_REF]: true, name: prop };
-          cache.set(prop, col);
-        }
-        return col;
-      }
-    }
-  );
-}
-
-// src/decorators/key.ts
-var KEY_MARKER = /* @__PURE__ */ Symbol("graphddb:key");
-var KEY_SEGMENT = /* @__PURE__ */ Symbol("graphddb:keySegment");
-function isKeySegment(value) {
-  return typeof value === "object" && value !== null && value[KEY_SEGMENT] === true;
-}
-function k(literals, ...columns) {
-  for (let i = 0; i < columns.length; i++) {
-    if (!isColumn(columns[i])) {
-      throw new Error(
-        `k\`...\`: interpolation #${i} must be a typed column reference (e.g. \`c.userId\`), not ${typeof columns[i]}. Key segments name fields via column references so they stay type-safe.`
-      );
-    }
-  }
-  return {
-    [KEY_SEGMENT]: true,
-    literals: [...literals],
-    columns
-  };
-}
-function isKeyDefinition(value) {
-  return typeof value === "object" && value !== null && KEY_MARKER in value;
-}
-function normalizeSegments(spec) {
-  if (spec === void 0) return [];
-  const list = Array.isArray(spec) ? spec : [spec];
-  for (const seg of list) {
-    if (!isKeySegment(seg)) {
-      throw new Error(
-        "key()/gsi(): pk and sk must be built with the `k` tagged template (e.g. k`USER#${c.userId}`) or an array of them."
-      );
-    }
-  }
-  return list;
-}
-function segmentFieldNames(segments) {
-  const seen = /* @__PURE__ */ new Set();
-  const out = [];
-  for (const seg of segments) {
-    for (const col of seg.columns) {
-      if (!seen.has(col.name)) {
-        seen.add(col.name);
-        out.push(col.name);
-      }
-    }
-  }
-  return out;
-}
-function buildSegmentedKey(structure) {
-  const pkSegments = normalizeSegments(structure.pk);
-  const skSegments = normalizeSegments(structure.sk);
-  if (pkSegments.length === 0) {
-    throw new Error("key()/gsi(): pk must define at least one segment.");
-  }
-  const seen = /* @__PURE__ */ new Set();
-  const inputFieldNames = [];
-  for (const name of [
-    ...segmentFieldNames(pkSegments),
-    ...segmentFieldNames(skSegments)
-  ]) {
-    if (!seen.has(name)) {
-      seen.add(name);
-      inputFieldNames.push(name);
-    }
-  }
-  return { segmented: { pkSegments, skSegments }, inputFieldNames };
-}
-function key(builder) {
-  const accessor = createColumnMap();
-  const structure = builder(accessor);
-  const { segmented, inputFieldNames } = buildSegmentedKey(structure);
-  return {
-    [KEY_MARKER]: true,
-    segmented,
-    inputFieldNames
-  };
-}
+import {
+  TableMapping,
+  buildSegmentedKey,
+  createColumnMap,
+  createDefaultLinter,
+  isColumn,
+  isKeyDefinition,
+  resolveKey,
+  segmentFieldNames
+} from "./chunk-PDUVTYC5.js";
 
 // src/decorators/gsi.ts
 var GSI_MARKER = /* @__PURE__ */ Symbol("graphddb:gsi");
@@ -113,879 +23,20 @@ function gsi(indexName, builder, options) {
     indexName,
     segmented,
     inputFieldNames,
-    unique: options?.unique ?? false
-  };
-}
-
-// src/linter/linter.ts
-var Linter = class {
-  rules = [];
-  addRule(rule) {
-    this.rules.push(rule);
-  }
-  run(metadata, registry) {
-    const results = [];
-    for (const rule of this.rules) {
-      results.push(...rule.check(metadata, registry));
-    }
-    return results;
-  }
-  runAll(registry) {
-    const results = [];
-    const all = registry.getAll();
-    for (const [, metadata] of all) {
-      results.push(...this.run(metadata, registry));
-    }
-    return results;
-  }
-};
-
-// src/linter/rules/no-scan.ts
-var noScanRule = {
-  id: "no-scan",
-  severity: "error",
-  check(metadata) {
-    if (metadata.primaryKey === null && metadata.gsiDefinitions.length === 0) {
-      return [
-        {
-          ruleId: "no-scan",
-          severity: "error",
-          message: `Entity '${metadata.prefix}' has no primaryKey or GSI defined. All reads would require a full table scan.`,
-          entity: metadata.prefix
-        }
-      ];
-    }
-    return [];
-  }
-};
-
-// src/linter/rules/require-limit.ts
-var requireLimitRule = {
-  id: "require-limit",
-  severity: "warning",
-  check(metadata) {
-    const results = [];
-    for (const relation of metadata.relations) {
-      if (relation.type !== "hasMany") continue;
-      if (relation.options?.versioned) continue;
-      const limit = relation.options?.limit;
-      if (!limit || limit.default === void 0 || limit.max === void 0) {
-        const kb = Object.keys(relation.keyBinding).join(", ");
-        results.push({
-          ruleId: "require-limit",
-          severity: "warning",
-          message: `hasMany relation (keyBinding: [${kb}]) on entity '${metadata.prefix}' is missing limit.default or limit.max. Unbounded queries may consume excessive RCU.`,
-          entity: metadata.prefix
-        });
-      }
-    }
-    return results;
-  }
-};
-
-// src/linter/rules/gsi-ambiguity.ts
-function isSubsetOf(a, b) {
-  const setB = new Set(b);
-  return a.length > 0 && a.every((f) => setB.has(f));
-}
-var gsiAmbiguityRule = {
-  id: "gsi-ambiguity",
-  severity: "error",
-  check(metadata) {
-    const results = [];
-    const patterns = [];
-    if (metadata.primaryKey) {
-      patterns.push({
-        label: "primaryKey",
-        fieldNames: metadata.primaryKey.inputFieldNames
-      });
-    }
-    for (const gsi2 of metadata.gsiDefinitions) {
-      patterns.push({ label: gsi2.indexName, fieldNames: gsi2.inputFieldNames });
-    }
-    for (let i = 0; i < patterns.length; i++) {
-      for (let j = i + 1; j < patterns.length; j++) {
-        const a = patterns[i];
-        const b = patterns[j];
-        if (isSubsetOf(a.fieldNames, b.fieldNames) || isSubsetOf(b.fieldNames, a.fieldNames)) {
-          const smaller = a.fieldNames.length <= b.fieldNames.length ? a : b;
-          results.push({
-            ruleId: "gsi-ambiguity",
-            severity: "error",
-            message: `Ambiguous GSI resolution: field set [${smaller.fieldNames.join(", ")}] matches both '${a.label}' and '${b.label}'. Each access pattern must have a unique field combination.`,
-            entity: metadata.prefix,
-            field: smaller.fieldNames.join(", ")
-          });
-        }
-      }
-    }
-    return results;
-  }
-};
-
-// src/planner/key-resolver.ts
-function fieldSetsEqual(a, b) {
-  if (a.length !== b.length) return false;
-  const sorted = [...b].sort();
-  return [...a].sort().every((v, i) => v === sorted[i]);
-}
-function classifySegmentMatch(segmented, queryFields) {
-  const pkFields = segmentFieldNames(segmented.pkSegments);
-  const present = new Set(queryFields);
-  const allFields = /* @__PURE__ */ new Set([
-    ...pkFields,
-    ...segmentFieldNames(segmented.skSegments)
-  ]);
-  for (const f of queryFields) {
-    if (!allFields.has(f)) return null;
-  }
-  for (const f of pkFields) {
-    if (!present.has(f)) return null;
-  }
-  const sk = segmented.skSegments;
-  let consumed = 0;
-  let truncated = false;
-  for (let i = 0; i < sk.length; i++) {
-    const fields = sk[i].columns.map((c) => c.name);
-    const all = fields.every((f) => present.has(f));
-    const any = fields.some((f) => present.has(f));
-    if (all && fields.length > 0) {
-      if (truncated) return null;
-      consumed = i + 1;
-      continue;
-    }
-    if (fields.length === 0) {
-      if (!truncated) consumed = i + 1;
-      continue;
-    }
-    if (any) return null;
-    truncated = true;
-  }
-  const skFieldCount = segmentFieldNames(sk).length;
-  const allSkPresent = segmentFieldNames(sk).every((f) => present.has(f));
-  if (skFieldCount === 0 || allSkPresent && consumed === sk.length) {
-    return "full";
-  }
-  return "partial";
-}
-function resolveKey(queryFields, metadata) {
-  if (metadata.primaryKey && fieldSetsEqual(queryFields, metadata.primaryKey.inputFieldNames)) {
-    return {
-      type: "pk",
-      partial: false,
-      inputFieldNames: metadata.primaryKey.inputFieldNames
-    };
-  }
-  for (const gsi2 of metadata.gsiDefinitions) {
-    if (fieldSetsEqual(queryFields, gsi2.inputFieldNames)) {
-      return {
-        type: "gsi",
-        indexName: gsi2.indexName,
-        unique: gsi2.unique,
-        partial: false,
-        inputFieldNames: gsi2.inputFieldNames
-      };
-    }
-  }
-  if (metadata.primaryKey) {
-    const match = classifySegmentMatch(metadata.primaryKey.segmented, queryFields);
-    if (match === "partial") {
-      return { type: "pk", partial: true, inputFieldNames: queryFields };
-    }
-    if (match === "full") {
-      return { type: "pk", partial: false, inputFieldNames: queryFields };
-    }
-  }
-  for (const gsi2 of metadata.gsiDefinitions) {
-    const match = classifySegmentMatch(gsi2.segmented, queryFields);
-    if (match === "partial") {
-      return {
-        type: "gsi",
-        indexName: gsi2.indexName,
-        unique: false,
-        partial: true,
-        inputFieldNames: queryFields
-      };
-    }
-    if (match === "full") {
-      return {
-        type: "gsi",
-        indexName: gsi2.indexName,
-        unique: gsi2.unique,
-        partial: false,
-        inputFieldNames: queryFields
-      };
-    }
-  }
-  throw new Error(
-    `No access pattern found for fields [${queryFields.join(", ")}]. Available: primaryKey([${metadata.primaryKey?.inputFieldNames.join(", ") ?? ""}])` + metadata.gsiDefinitions.map((g) => `, ${g.indexName}([${g.inputFieldNames.join(", ")}])`).join("")
-  );
-}
-
-// src/linter/rules/missing-gsi.ts
-var missingGsiRule = {
-  id: "missing-gsi",
-  severity: "error",
-  check(metadata, registry) {
-    const results = [];
-    for (const relation of metadata.relations) {
-      const targetFields = Object.keys(relation.keyBinding);
-      if (targetFields.length === 0) {
-        continue;
-      }
-      let targetMeta;
-      try {
-        const targetClass = relation.targetFactory();
-        targetMeta = registry.get(targetClass);
-      } catch {
-        results.push({
-          ruleId: "missing-gsi",
-          severity: "error",
-          message: `Relation '${relation.propertyName}' on entity '${metadata.prefix}' targets an entity that is not registered in MetadataRegistry.`,
-          entity: metadata.prefix,
-          field: relation.propertyName
-        });
-        continue;
-      }
-      try {
-        resolveKey(targetFields, targetMeta);
-      } catch {
-        results.push({
-          ruleId: "missing-gsi",
-          severity: "error",
-          message: `Relation '${relation.propertyName}' on entity '${metadata.prefix}' requires access pattern [${targetFields.join(", ")}] on target entity '${targetMeta.prefix}', but no matching primary key or GSI is defined.`,
-          entity: metadata.prefix,
-          field: relation.propertyName
-        });
-      }
-    }
-    return results;
-  }
-};
-
-// src/linter/rules/relation-depth.ts
-var DEFAULT_MAX_DEPTH = 1;
-function computeRelationDepth(metadata, registry, visited = /* @__PURE__ */ new Set()) {
-  if (metadata.relations.length === 0) {
-    return 0;
-  }
-  let maxDepth = 0;
-  for (const relation of metadata.relations) {
-    let targetClass;
-    try {
-      targetClass = relation.targetFactory();
-    } catch {
-      continue;
-    }
-    if (visited.has(targetClass)) {
-      continue;
-    }
-    let targetMeta;
-    try {
-      targetMeta = registry.get(targetClass);
-    } catch {
-      continue;
-    }
-    const nextVisited = new Set(visited);
-    nextVisited.add(targetClass);
-    const childDepth = 1 + computeRelationDepth(targetMeta, registry, nextVisited);
-    maxDepth = Math.max(maxDepth, childDepth);
-  }
-  return maxDepth;
-}
-var relationDepthRule = {
-  id: "relation-depth",
-  severity: "warning",
-  check(metadata, registry) {
-    const depth = computeRelationDepth(metadata, registry);
-    if (depth <= DEFAULT_MAX_DEPTH) {
-      return [];
-    }
-    return [
-      {
-        ruleId: "relation-depth",
-        severity: "warning",
-        message: `Entity '${metadata.prefix}' has relation paths exceeding default maxDepth ${DEFAULT_MAX_DEPTH} (detected depth: ${depth}). Deep traversal requires explicit maxDepth at runtime.`,
-        entity: metadata.prefix
-      }
-    ];
-  }
-};
-
-// src/client/TableMapping.ts
-var TableMapping = class {
-  static mapping = {};
-  static set(mapping) {
-    this.mapping = { ...mapping };
-  }
-  static resolve(declaredName) {
-    return this.mapping[declaredName] ?? declaredName;
-  }
-  /** @internal — for testing only */
-  static reset() {
-    this.mapping = {};
-  }
-};
-
-// src/linter/rules/same-partition-preset.ts
-var samePartitionPresetRule = {
-  id: "same-partition-preset",
-  severity: "error",
-  check(metadata, registry) {
-    const results = [];
-    for (const relation of metadata.relations) {
-      if (relation.options?.pattern !== "samePartition") continue;
-      results.push(...checkRelation(metadata, relation, registry));
-    }
-    return results;
-  }
-};
-function err(metadata, relation, message) {
-  return {
-    ruleId: "same-partition-preset",
-    severity: "error",
-    message: `Relation '${relation.propertyName}' on entity '${metadata.prefix}' declares pattern 'samePartition' but ${message}`,
-    entity: metadata.prefix,
-    field: relation.propertyName
-  };
-}
-function checkRelation(metadata, relation, registry) {
-  if (relation.type !== "hasMany") {
-    return [
-      err(
-        metadata,
-        relation,
-        `is a '${relation.type}'. 'samePartition' lowers a parent\u2192children collection read (begins_with on a segmented sort key) and is only valid on @hasMany.`
-      )
-    ];
-  }
-  const results = [];
-  const maintenanceOptions = ["read", "write", "projection"].filter(
-    (k2) => relation.options?.[k2] !== void 0
-  );
-  if (maintenanceOptions.length > 0) {
-    results.push(
-      err(
-        metadata,
-        relation,
-        `also sets [${maintenanceOptions.join(", ")}]. 'samePartition' has no maintained materialisation \u2014 children are read live by begins_with, so it carries no read/write/projection effect. Drop these options (or use a maintained preset such as 'embeddedSnapshot').`
-      )
-    );
-  }
-  const targetFields = Object.keys(relation.keyBinding);
-  if (targetFields.length === 0) {
-    results.push(
-      err(metadata, relation, `has an empty keyBinding; nothing to lower.`)
-    );
-    return results;
-  }
-  let targetMeta;
-  try {
-    const targetClass = relation.targetFactory();
-    targetMeta = registry.get(targetClass);
-  } catch {
-    results.push(
-      err(
-        metadata,
-        relation,
-        `targets an entity that is not registered in MetadataRegistry.`
-      )
-    );
-    return results;
-  }
-  let resolved;
-  try {
-    resolved = resolveKey(targetFields, targetMeta);
-  } catch {
-    results.push(
-      err(
-        metadata,
-        relation,
-        `binds [${targetFields.join(", ")}] on target '${targetMeta.prefix}', which matches no access pattern. A same-partition relation must bind a contiguous prefix of the target's primary key.`
-      )
-    );
-    return results;
-  }
-  if (resolved.type !== "pk") {
-    results.push(
-      err(
-        metadata,
-        relation,
-        `binds [${targetFields.join(", ")}] to a ${resolved.type.toUpperCase()} on target '${targetMeta.prefix}'. A GSI is a different partition; 'samePartition' requires the binding to resolve on the target's primary key (same PK, segmented-SK begins_with).`
-      )
-    );
-    return results;
-  }
-  if (!resolved.partial) {
-    results.push(
-      err(
-        metadata,
-        relation,
-        `binds the target's full primary key on '${targetMeta.prefix}', which is a point read of a single item, not a child collection. 'samePartition' requires a partial key \u2014 the parent fields fully supply the PK and a proper prefix of the segmented SK, leaving a begins_with boundary for the children.`
-      )
-    );
-  }
-  return results;
-}
-
-// src/linter/rules/maintenance-shared.ts
-function isMaintainedRelation(relation) {
-  const triggers = relation.options?.write?.maintainedOn;
-  return Array.isArray(triggers) && triggers.length > 0;
-}
-function maintainedRelations(metadata) {
-  return metadata.relations.filter(isMaintainedRelation);
-}
-function logicalName(metadata) {
-  return metadata.prefix.endsWith("#") ? metadata.prefix.slice(0, -1) : metadata.prefix;
-}
-function payloadAttributes(meta) {
-  const attrs = /* @__PURE__ */ new Set();
-  for (const f of meta.fields) attrs.add(f.propertyName);
-  if (meta.primaryKey) {
-    for (const f of segmentFieldNames(meta.primaryKey.segmented.pkSegments)) {
-      attrs.add(f);
-    }
-    for (const f of segmentFieldNames(meta.primaryKey.segmented.skSegments)) {
-      attrs.add(f);
-    }
-  }
-  for (const gsi2 of meta.gsiDefinitions) {
-    for (const f of segmentFieldNames(gsi2.segmented.pkSegments)) attrs.add(f);
-    for (const f of segmentFieldNames(gsi2.segmented.skSegments)) attrs.add(f);
-  }
-  return attrs;
-}
-function isPayloadRooted(value) {
-  return value.startsWith("$.input.") || value.startsWith("$.entity.");
-}
-function projectionSourceAttribute(value) {
-  const path = typeof value === "string" ? value : value.path;
-  if (typeof value === "string") {
-    if (!isPayloadRooted(path)) return path;
-  } else if (!isPayloadRooted(path)) {
-    return null;
-  }
-  const stripped = path.replace(/^\$\.(input|entity)\./, "");
-  return stripped.split(".")[0] ?? stripped;
-}
-function projectionEntries(projection) {
-  return projection ? Object.entries(projection) : [];
-}
-
-// src/linter/rules/missing-context.ts
-var missingContextRule = {
-  id: "missing-context",
-  severity: "error",
-  check(metadata, registry) {
-    const results = [];
-    for (const relation of maintainedRelations(metadata)) {
-      results.push(...checkRelation2(metadata, relation, registry));
-    }
-    return results;
-  }
-};
-function err2(metadata, relation, message) {
-  return {
-    ruleId: "missing-context",
-    severity: "error",
-    message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' ${message}`,
-    entity: metadata.prefix,
-    field: relation.propertyName
+    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 } : {}
   };
 }
-function checkRelation2(metadata, relation, registry) {
-  let sourceMeta;
-  try {
-    sourceMeta = registry.get(relation.targetFactory());
-  } catch {
-    return [];
-  }
-  const sourceName = logicalName(sourceMeta);
-  const payload = payloadAttributes(sourceMeta);
-  const available = `available: ${[...payload].sort().map((f) => `'${f}'`).join(", ")}`;
-  const results = [];
-  for (const sourceField of Object.keys(relation.keyBinding)) {
-    if (!payload.has(sourceField)) {
-      results.push(
-        err2(
-          metadata,
-          relation,
-          `resolves its destination row from source field '${sourceField}', but the source entity '${sourceName}' carries no such attribute on its write payload (${available}). Phase 1 maintenance is payload \u540C\u68B1 only (no write-time fetch) \u2014 include '${sourceField}' on '${sourceName}' or bind a key field it does carry.`
-        )
-      );
-    }
-  }
-  for (const [attr, value] of projectionEntries(relation.options?.projection)) {
-    const path = typeof value === "string" ? value : value.path;
-    const srcAttr = projectionSourceAttribute(value);
-    if (srcAttr === null || typeof value !== "string" && !isPayloadRooted(path)) {
-      results.push(
-        err2(
-          metadata,
-          relation,
-          `projects '${attr}' from '${path}', which is not a payload-rooted source path (\`$.input.*\` / \`$.entity.*\`). Phase 1 maintenance projects only from the source payload (payload \u540C\u68B1); there is no fetch / re-projection.`
-        )
-      );
-      continue;
-    }
-    if (!payload.has(srcAttr)) {
-      results.push(
-        err2(
-          metadata,
-          relation,
-          `projects '${attr}' from source attribute '${srcAttr}', but the source entity '${sourceName}' carries no such attribute on its write payload (${available}). Phase 1 maintenance is payload \u540C\u68B1 only (no write-time fetch / re-projection) \u2014 an attribute the source row does not carry cannot be projected.`
-        )
-      );
-    }
-  }
-  return results;
-}
-
-// src/linter/rules/embedded-snapshot-size.ts
-var ITEM_LIMIT_BYTES = 400 * 1024;
-var SOFT_BUDGET_BYTES = ITEM_LIMIT_BYTES / 2;
-var DEFAULT_STRING_BYTES = 256;
-var ATTR_NAME_OVERHEAD_BYTES = 16;
-var embeddedSnapshotSizeRule = {
-  id: "400kb",
-  severity: "warning",
-  check(metadata, _registry) {
-    const results = [];
-    for (const relation of maintainedRelations(metadata)) {
-      const result = checkRelation3(metadata, relation);
-      if (result) results.push(result);
-    }
-    return results;
-  }
-};
-function estimateItemBytes(relation) {
-  let bytes = 0;
-  for (const [attr, value] of projectionEntries(relation.options?.projection)) {
-    bytes += ATTR_NAME_OVERHEAD_BYTES + attr.length;
-    bytes += attributeValueBytes(value);
-  }
-  return bytes;
-}
-function attributeValueBytes(value) {
-  if (typeof value !== "string" && value.op === "preview") {
-    const [n] = value.args;
-    if (typeof n === "number" && Number.isFinite(n)) return n;
-  }
-  return DEFAULT_STRING_BYTES;
-}
-function checkRelation3(metadata, relation) {
-  const itemBytes = estimateItemBytes(relation);
-  if (itemBytes === 0) return null;
-  const isCollection = relation.type === "hasMany";
-  const maxItems = relation.options?.read?.maxItems;
-  if (isCollection && maxItems === void 0) return null;
-  const count = isCollection ? maxItems : 1;
-  const estimate = itemBytes * count;
-  const shape = isCollection ? `${count} item(s) \xD7 ~${itemBytes} B` : `~${itemBytes} B snapshot`;
-  if (estimate >= ITEM_LIMIT_BYTES) {
-    return {
-      ruleId: "400kb",
-      severity: "error",
-      message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' materializes ${shape} \u2248 ${estimate} B onto the owner row, which meets or exceeds DynamoDB's 400 KB item limit (${ITEM_LIMIT_BYTES} B). The maintenance write would fail once the collection fills \u2014 reduce \`read.maxItems\` or the projected attributes (e.g. tighter \`preview(n)\` bounds).`,
-      entity: metadata.prefix,
-      field: relation.propertyName
-    };
-  }
-  if (estimate >= SOFT_BUDGET_BYTES) {
-    return {
-      ruleId: "400kb",
-      severity: "warning",
-      message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' materializes ${shape} \u2248 ${estimate} B onto the owner row, over half of DynamoDB's 400 KB item limit (${ITEM_LIMIT_BYTES} B). Little headroom remains for the rest of the item \u2014 consider a tighter \`read.maxItems\` / projection.`,
-      entity: metadata.prefix,
-      field: relation.propertyName
-    };
-  }
-  return null;
-}
-
-// src/linter/rules/hot-partition.ts
-var HOT_TRIGGER_FANIN = 2;
-var hotPartitionRule = {
-  id: "hot-partition",
-  severity: "warning",
-  check(metadata, _registry) {
-    const results = [];
-    const maintained = maintainedRelations(metadata);
-    for (const relation of maintained) {
-      if (relation.type !== "hasMany") continue;
-      if (relation.options?.read?.maxItems === void 0) {
-        results.push(unboundedWarning(metadata, relation));
-      }
-    }
-    const byTrigger = /* @__PURE__ */ new Map();
-    for (const relation of maintained) {
-      for (const trigger of relation.options?.write?.maintainedOn ?? []) {
-        const bucket = byTrigger.get(trigger);
-        if (bucket) bucket.push(relation.propertyName);
-        else byTrigger.set(trigger, [relation.propertyName]);
-      }
-    }
-    for (const [trigger, props] of byTrigger) {
-      if (props.length > HOT_TRIGGER_FANIN) {
-        results.push(fanInWarning(metadata, trigger, props));
-      }
-    }
-    return results;
-  }
-};
-function unboundedWarning(metadata, relation) {
-  return {
-    ruleId: "hot-partition",
-    severity: "warning",
-    message: `Maintained collection '${relation.propertyName}' on '${logicalName(metadata)}' has no \`read.maxItems\` bound: every maintained source row appends to the same owner ("root") item, so that single partition takes unbounded write traffic and the item trends toward the 400 KB limit. Declare a \`read.maxItems\` window (e.g. latest-N) or read the children from their own partition (\`samePartition\`) instead of inlining a snapshot.`,
-    entity: metadata.prefix,
-    field: relation.propertyName
-  };
-}
-function fanInWarning(metadata, trigger, props) {
-  return {
-    ruleId: "hot-partition",
-    severity: "warning",
-    message: `${props.length} maintained relations on '${logicalName(metadata)}' ([${props.map((p) => `'${p}'`).join(", ")}]) all fire on trigger '${trigger}', concentrating that many maintenance writes onto the single owner ("root") row in one mutation. This amplifies per-source-row write cost on one partition \u2014 consider splitting the maintained shapes across rows / partitions.`,
-    entity: metadata.prefix
-  };
-}
-
-// src/linter/rules/fan-out.ts
-var MAX_MAINTENANCE_HOPS = 1;
-var fanOutRule = {
-  id: "fan-out",
-  severity: "warning",
-  check(metadata, registry) {
-    const results = [];
-    for (const relation of maintainedRelations(metadata)) {
-      const point = checkDestinationFanOut(metadata, relation);
-      if (point) results.push(point);
-    }
-    const chain = maintenanceChain(metadata, registry, /* @__PURE__ */ new Set([modelKey(metadata)]));
-    if (chain.hops > MAX_MAINTENANCE_HOPS) {
-      results.push({
-        ruleId: "fan-out",
-        severity: "warning",
-        message: `Entity '${chain.root}' is the root of a maintenance chain ${chain.hops} hops deep, terminating at '${logicalName(metadata)}': a single '${chain.root}' lifecycle event cascades through ${chain.hops} maintenance writes \u2014 each maintained row is itself the trigger source of the next hop \u2014 until it reaches '${logicalName(metadata)}'. A multi-step maintenance fan-out amplifies one write into many; flatten the chain or move downstream hops to a stream (\`updateMode: 'stream'\`).`,
-        entity: metadata.prefix
-      });
-    }
-    return results;
-  }
-};
-function checkDestinationFanOut(metadata, relation) {
-  const ownerKeyFields = Object.values(relation.keyBinding);
-  if (ownerKeyFields.length === 0) return null;
-  let resolved;
-  try {
-    resolved = resolveKey(ownerKeyFields, metadata);
-  } catch {
-    return null;
-  }
-  const isPoint = !resolved.partial && (resolved.type === "pk" || resolved.type === "gsi" && resolved.unique);
-  if (isPoint) return null;
-  const shape = resolved.partial ? `a partial ${resolved.type.toUpperCase()} (a begins_with range of rows)` : `a non-unique ${resolved.type.toUpperCase()} (many matching rows)`;
-  return {
-    ruleId: "fan-out",
-    severity: "warning",
-    message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' binds its destination row by [${ownerKeyFields.map((f) => `'${f}'`).join(", ")}], which resolves to ${shape} on '${logicalName(metadata)}'. A single source event then fans its maintenance write out across every matching destination row in one mutation (unbounded fan-out). Bind the destination's full primary key (or a unique GSI) so each source event maintains exactly one row.`,
-    entity: metadata.prefix,
-    field: relation.propertyName
-  };
-}
-function modelKey(metadata) {
-  return logicalName(metadata);
-}
-function maintenanceChain(metadata, registry, visited) {
-  const maintained = maintainedRelations(metadata);
-  if (maintained.length === 0) return { hops: 0, root: logicalName(metadata) };
-  let best = { hops: 0, root: logicalName(metadata) };
-  for (const relation of maintained) {
-    let targetMeta;
-    try {
-      targetMeta = registry.get(relation.targetFactory());
-    } catch {
-      continue;
-    }
-    const key2 = modelKey(targetMeta);
-    if (visited.has(key2)) continue;
-    const next = new Set(visited);
-    next.add(key2);
-    const upstream = maintenanceChain(targetMeta, registry, next);
-    if (1 + upstream.hops > best.hops) {
-      best = { hops: 1 + upstream.hops, root: upstream.root };
-    }
-  }
-  return best;
-}
-
-// src/linter/rules/multi-maintainer-same-row.ts
-var multiMaintainerSameRowRule = {
-  id: "multi-maintainer-same-row",
-  severity: "error",
-  check(metadata, _registry) {
-    const maintained = maintainedRelations(metadata);
-    if (maintained.length < 2) return [];
-    const owner = logicalName(metadata);
-    const groups = /* @__PURE__ */ new Map();
-    for (const relation of maintained) {
-      const rowKey = destinationRowKey(owner, relation);
-      for (const trigger of relation.options?.write?.maintainedOn ?? []) {
-        const groupKey = `${trigger} ${rowKey}`;
-        const group = groups.get(groupKey);
-        if (group) group.props.push(relation.propertyName);
-        else groups.set(groupKey, { trigger, props: [relation.propertyName] });
-      }
-    }
-    const results = [];
-    for (const { trigger, props } of groups.values()) {
-      if (props.length < 2) continue;
-      results.push({
-        ruleId: "multi-maintainer-same-row",
-        severity: "error",
-        message: `Maintained relations [${props.map((p) => `'${p}'`).join(", ")}] on '${owner}' all fire on trigger '${trigger}' and write the SAME destination row. Phase 1 maintenance is "1 mutation \xD7 1 target row = 1 effect" (\u8AD6\u70B92 = b): a single mutation cannot touch one row with ${props.length} maintain effects \u2014 DynamoDB rejects two writes to the same key in one TransactWriteItems (cf. #96). Merge the projections into one maintained relation, or split them onto distinct destination rows / triggers.`,
-        entity: metadata.prefix,
-        field: props[0]
-      });
-    }
-    return results;
-  }
-};
-function destinationRowKey(owner, relation) {
-  const parts = Object.entries(relation.keyBinding).map(([sourceField, ownerField]) => `${ownerField}=$.entity.${sourceField}`).sort();
-  return `${owner}#${parts.join("&")}`;
-}
-
-// src/linter/rules/cfn-schema-consistency.ts
-var MAX_GSIS_PER_TABLE = 20;
-function gsiShape(gsi2) {
-  const hasSk = gsi2.segmented.skSegments.length > 0;
-  return { indexName: gsi2.indexName, hasSk };
-}
-function err3(entity, message) {
-  return {
-    ruleId: "cfn-schema-consistency",
-    severity: "error",
-    message,
-    entity
-  };
-}
-var cfnSchemaConsistencyRule = {
-  id: "cfn-schema-consistency",
-  severity: "error",
-  check(metadata, registry) {
-    return checkAllTables(metadata, registry);
-  }
-};
-function checkAllTables(current, registry) {
-  const seenMeta = /* @__PURE__ */ new Set();
-  const byPhysical = /* @__PURE__ */ new Map();
-  const add = (meta) => {
-    if (seenMeta.has(meta)) return;
-    seenMeta.add(meta);
-    const physical = TableMapping.resolve(meta.tableName);
-    const list = byPhysical.get(physical) ?? [];
-    list.push(meta);
-    byPhysical.set(physical, list);
-  };
-  add(current);
-  for (const [, meta] of registry.getFinalized()) add(meta);
-  const currentPhysical = TableMapping.resolve(current.tableName);
-  const entities = byPhysical.get(currentPhysical);
-  if (!entities) return [];
-  return checkTable(currentPhysical, entities);
-}
-function checkTable(physical, entities) {
-  const ordered = [...entities].sort((a, b) => a.prefix.localeCompare(b.prefix));
-  const results = [];
-  results.push(...checkBaseKeySchema(physical, ordered));
-  results.push(...checkGsiUnion(physical, ordered));
-  return results;
-}
-function checkBaseKeySchema(physical, entities) {
-  const withSk = [];
-  const withoutSk = [];
-  for (const meta of entities) {
-    if (!meta.primaryKey) continue;
-    const hasSk = meta.primaryKey.segmented.skSegments.length > 0;
-    (hasSk ? withSk : withoutSk).push(meta.prefix);
-  }
-  if (withSk.length > 0 && withoutSk.length > 0) {
-    const offender = [...withSk, ...withoutSk].sort()[0];
-    return [
-      err3(
-        offender,
-        `CloudFormation schema consistency: physical table '${physical}' has an ambiguous base KeySchema \u2014 some entities declare a sort key and some do not (with SK: [${withSk.join(", ")}]; without SK: [${withoutSk.join(", ")}]). A single DynamoDB table has exactly one KeySchema; every entity sharing a table must agree on whether the base key has an SK.`
-      )
-    ];
-  }
-  return [];
-}
-function checkGsiUnion(physical, entities) {
-  const results = [];
-  const seen = /* @__PURE__ */ new Map();
-  for (const meta of entities) {
-    for (const gsi2 of meta.gsiDefinitions) {
-      const shape = gsiShape(gsi2);
-      const existing = seen.get(shape.indexName);
-      if (!existing) {
-        seen.set(shape.indexName, { shape, entity: meta.prefix });
-        continue;
-      }
-      const conflict = describeConflict(existing.shape, shape);
-      if (conflict) {
-        results.push(
-          err3(
-            meta.prefix,
-            `CloudFormation schema consistency: GSI '${shape.indexName}' on physical table '${physical}' is declared inconsistently across entities that share it \u2014 ${conflict} (first declared by '${existing.entity}', conflicting declaration on '${meta.prefix}'). A single DynamoDB table has exactly one GSI per index name; entities may share an index name (projecting different logical fields into the shared physical key), but only when its physical key structure (sort-key presence) is identical.`
-          )
-        );
-      }
-    }
-  }
-  if (seen.size > MAX_GSIS_PER_TABLE) {
-    const names = [...seen.keys()].sort();
-    const offender = [...entities].map((e) => e.prefix).sort()[0];
-    results.push(
-      err3(
-        offender,
-        `CloudFormation schema consistency: physical table '${physical}' would have ${seen.size} global secondary indexes after unioning across entities, exceeding the DynamoDB limit of ${MAX_GSIS_PER_TABLE}. Distinct index names: [${names.join(", ")}]. Reduce the number of distinct GSIs on this table.`
-      )
-    );
-  }
-  return results;
-}
-function describeConflict(a, b) {
-  if (a.hasSk !== b.hasSk) {
-    return `one declaration has a sort key and the other does not (${a.hasSk ? "with" : "without"} SK vs. ${b.hasSk ? "with" : "without"} SK)`;
-  }
-  return null;
-}
-
-// src/linter/default-linter.ts
-function createDefaultLinter() {
-  const linter = new Linter();
-  linter.addRule(noScanRule);
-  linter.addRule(requireLimitRule);
-  linter.addRule(gsiAmbiguityRule);
-  linter.addRule(missingGsiRule);
-  linter.addRule(relationDepthRule);
-  linter.addRule(samePartitionPresetRule);
-  linter.addRule(missingContextRule);
-  linter.addRule(embeddedSnapshotSizeRule);
-  linter.addRule(hotPartitionRule);
-  linter.addRule(fanOutRule);
-  linter.addRule(multiMaintainerSameRowRule);
-  linter.addRule(cfnSchemaConsistencyRule);
-  return linter;
-}
 
 // src/metadata/registry.ts
+function defaultLinterForEnv() {
+  return process.env.NODE_ENV === "production" ? null : createDefaultLinter();
+}
 var MetadataRegistry = class {
   static store = /* @__PURE__ */ new Map();
-  static _linter = createDefaultLinter();
+  static _linter = defaultLinterForEnv();
   /**
    * A monotonically-increasing counter bumped on every change to the set of
    * registered models ({@link register} / {@link clear}). It lets a consumer that
@@ -1056,14 +107,21 @@ var MetadataRegistry = class {
   static set linter(linter) {
     this._linter = linter;
   }
-  /** Resets linter to the default built-in rule set. */
+  /** Resets linter to the environment default (built-in rule set outside production). */
   static resetLinter() {
-    this._linter = createDefaultLinter();
+    this._linter = defaultLinterForEnv();
   }
-  /** @internal — for testing only */
+  /**
+   * @internal — for testing only. Resets to a no-op linter (no rules): matches
+   * the pre-#189 `new Linter()` behaviour where a cleared registry does not lint
+   * on re-registration. `null` is finalize-equivalent to an empty linter (the
+   * `finalize` guard skips a null linter), and nothing reads the linter getter
+   * to invoke it, so this preserves existing test semantics without importing
+   * the `Linter` class as a value (keeping it out of a production bundle).
+   */
   static clear() {
     this.store.clear();
-    this._linter = new Linter();
+    this._linter = null;
     this._generation++;
   }
   static finalize(target, meta) {
@@ -1084,12 +142,17 @@ 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 } : {}
         });
       }
     }
-    const results = this._linter.run(meta, this);
-    this.handleLintResults(results);
+    if (this._linter) {
+      const results = this._linter.run(meta, this);
+      this.handleLintResults(results);
+    }
     meta._finalized = true;
   }
   static handleLintResults(results) {
@@ -1953,7 +1016,7 @@ function isOperatorObject(value) {
   }
   const keys = Object.keys(value);
   if (keys.length === 0) return false;
-  return keys.every((k2) => OPERATOR_KEYS.has(k2));
+  return keys.every((k) => OPERATOR_KEYS.has(k));
 }
 function joinAnd(clauses) {
   if (clauses.length === 1) return clauses[0];
@@ -2053,25 +1116,25 @@ function compileNode(ctx, node) {
     return compileRaw(ctx, node);
   }
   const clauses = [];
-  for (const [key2, value] of Object.entries(node)) {
+  for (const [key, value] of Object.entries(node)) {
     if (value === void 0) continue;
-    if (key2 === "and" || key2 === "or") {
+    if (key === "and" || key === "or") {
       const parts = value.map((sub) => compileNode(ctx, sub)).filter((s) => s.length > 0);
       if (parts.length === 0) continue;
       if (parts.length === 1) {
         clauses.push(parts[0]);
       } else {
-        const sep = key2 === "and" ? " AND " : " OR ";
+        const sep = key === "and" ? " AND " : " OR ";
         clauses.push(`(${parts.map((p) => wrap(p)).join(sep)})`);
       }
       continue;
     }
-    if (key2 === "not") {
+    if (key === "not") {
       const inner = compileNode(ctx, value);
       if (inner.length > 0) clauses.push(`NOT ${wrap(inner)}`);
       continue;
     }
-    const clause = compileField(ctx, key2, value);
+    const clause = compileField(ctx, key, value);
     if (clause.length > 0) clauses.push(clause);
   }
   return joinAnd(clauses);
@@ -2089,11 +1152,11 @@ function resolveLeaf(value, resolveParam) {
 function resolveNode(node, resolveParam) {
   const obj = node;
   const out = {};
-  for (const [key2, value] of Object.entries(obj)) {
-    if (key2 === "and" || key2 === "or") {
-      out[key2] = value.map((s) => resolveNode(s, resolveParam));
-    } else if (key2 === "not") {
-      out[key2] = resolveNode(value, resolveParam);
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "and" || key === "or") {
+      out[key] = value.map((s) => resolveNode(s, resolveParam));
+    } else if (key === "not") {
+      out[key] = resolveNode(value, resolveParam);
     } else {
       const ops = value;
       const rendered = {};
@@ -2114,7 +1177,7 @@ function resolveNode(node, resolveParam) {
           rendered[op] = resolveLeaf(opVal, resolveParam);
         }
       }
-      out[key2] = rendered;
+      out[key] = rendered;
     }
   }
   return out;
@@ -2533,14 +1596,14 @@ var MiddlewareRuntime = class {
    * is the host's responsibility — a hook recovering a `query` should return an
    * item / `null`, one recovering a `list` a `{ items, cursor }`.
    */
-  async runRequestError(ctx, err4) {
+  async runRequestError(ctx, err) {
     for (let i = this.chain.length - 1; i >= 0; i--) {
       const onError = this.chain[i].read?.onError;
       if (!onError) continue;
-      const recovered = await onError(ctx, err4);
+      const recovered = await onError(ctx, err);
       if (recovered !== void 0) return recovered;
     }
-    throw err4;
+    throw err;
   }
   /**
    * Drive ONE physical op (root read or any fan-out fetch) through R2 → send →
@@ -2580,14 +1643,14 @@ var MiddlewareRuntime = class {
         if (afterFetch) items = await afterFetch(ctx, items);
       }
       return items;
-    } catch (err4) {
+    } catch (err) {
       for (let i = this.chain.length - 1; i >= 0; i--) {
         const onError = this.chain[i].read?.op?.onError;
         if (!onError) continue;
-        const recovered = await onError(ctx, err4);
+        const recovered = await onError(ctx, err);
         if (recovered !== void 0) return recovered;
       }
-      throw err4;
+      throw err;
     }
   }
 };
@@ -2651,14 +1714,14 @@ var WriteRuntime = class {
    * short-circuits the chain); the value becomes the write's resolved value.
    * Otherwise the original error rethrows (symmetric with the read `onError`).
    */
-  async runWriteError(ctx, err4) {
+  async runWriteError(ctx, err) {
     for (let i = this.chain.length - 1; i >= 0; i--) {
       const onError = this.chain[i].write?.onError;
       if (!onError) continue;
-      const recovered = await onError(ctx, err4);
+      const recovered = await onError(ctx, err);
       if (recovered !== void 0) return recovered;
     }
-    throw err4;
+    throw err;
   }
   /** Build a W3/W4/W5 persist context (pure — no hooks run). */
   persistCtx(items, origins, transaction) {
@@ -2687,20 +1750,20 @@ var WriteRuntime = class {
         if (before) await before(ctx);
       }
       results = await send(ctx.items);
-    } catch (err4) {
+    } catch (err) {
       let recovered;
       let didRecover = false;
       for (let i = this.chain.length - 1; i >= 0; i--) {
         const onError = this.chain[i].write?.persist?.onError;
         if (!onError) continue;
-        const r = await onError(ctx, err4);
+        const r = await onError(ctx, err);
         if (r !== void 0) {
           recovered = r;
           didRecover = true;
           break;
         }
       }
-      if (!didRecover) throw err4;
+      if (!didRecover) throw err;
       results = recovered;
     }
     for (let i = this.chain.length - 1; i >= 0; i--) {
@@ -2921,8 +1984,8 @@ async function executeSingleWriteWithHooks(req, mw) {
     await mw.runWriteBefore(ctx);
     const change2 = await persistRewrittenWrite(req.modelClass, ctx, mw);
     await mw.runWriteAfter(ctx, change2);
-  } catch (err4) {
-    await mw.runWriteError(ctx, err4);
+  } catch (err) {
+    await mw.runWriteError(ctx, err);
   }
 }
 async function persistRewrittenWrite(modelClass, ctx, mw) {
@@ -3500,12 +2563,12 @@ var TransactionContext = class {
       keys: { pk: String(updateInput.Key.PK), sk: String(updateInput.Key.SK ?? "") }
     });
   }
-  delete(model, key2, options) {
+  delete(model, key, options) {
     this.assertWithinLimit();
     const modelClass = resolveModelClass(model);
-    const deleteInput = buildDeleteInput(modelClass, key2, options);
+    const deleteInput = buildDeleteInput(modelClass, key, options);
     this.items.push({ Delete: deleteInput });
-    this.logicalOps.push({ kind: "delete", modelClass, key: key2, options });
+    this.logicalOps.push({ kind: "delete", modelClass, key, options });
     this.captureMeta.push({
       modelName: modelClass.name,
       op: "delete",
@@ -3525,7 +2588,7 @@ var TransactionContext = class {
    * @throws if `options.condition` is missing — a ConditionCheck without an
    *   assertion is meaningless.
    */
-  conditionCheck(model, key2, options) {
+  conditionCheck(model, key, options) {
     if (!options || !options.condition) {
       throw new Error(
         "TransactionContext.conditionCheck requires a `condition` (the read-only assertion it makes); e.g. `{ condition: { attributeExists: 'PK' } }`."
@@ -3533,7 +2596,7 @@ var TransactionContext = class {
     }
     this.assertWithinLimit();
     const modelClass = resolveModelClass(model);
-    const { TableName, Key } = buildDeleteInput(modelClass, key2);
+    const { TableName, Key } = buildDeleteInput(modelClass, key);
     const cond2 = buildConditionExpression(options.condition);
     const check = {
       TableName,
@@ -3677,19 +2740,19 @@ function hydrateItem(raw, select, metadata, updatable = false) {
 }
 function hydrateEmbedded(raw, select, _metadata, _fieldName) {
   const result = {};
-  for (const [key2, selectValue] of Object.entries(select)) {
+  for (const [key, selectValue] of Object.entries(select)) {
     if (selectValue === true) {
-      if (raw[key2] !== void 0) {
-        result[key2] = raw[key2];
+      if (raw[key] !== void 0) {
+        result[key] = raw[key];
       }
     } else if (typeof selectValue === "object" && selectValue !== null && !("select" in selectValue)) {
-      const nested = raw[key2];
+      const nested = raw[key];
       if (nested && typeof nested === "object") {
-        result[key2] = hydrateEmbedded(
+        result[key] = hydrateEmbedded(
           nested,
           selectValue,
           _metadata,
-          key2
+          key
         );
       }
     }
@@ -4640,22 +3703,7 @@ function buildSubscribeHandler(handlers) {
 }
 
 export {
-  isColumn,
-  createColumnMap,
-  isKeySegment,
-  k,
-  segmentFieldNames,
-  key,
   gsi,
-  Linter,
-  noScanRule,
-  requireLimitRule,
-  gsiAmbiguityRule,
-  resolveKey,
-  missingGsiRule,
-  relationDepthRule,
-  TableMapping,
-  createDefaultLinter,
   MetadataRegistry,
   pkTemplate,
   skTemplate,