graphddb 0.5.2 → 0.6.0

package/dist/chunk-PDUVTYC5.js

@@ -0,0 +1,992 @@
+// 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
+  };
+}
+
+// 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 gsi of metadata.gsiDefinitions) {
+      patterns.push({ label: gsi.indexName, fieldNames: gsi.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 gsi of metadata.gsiDefinitions) {
+    if (fieldSetsEqual(queryFields, gsi.inputFieldNames)) {
+      return {
+        type: "gsi",
+        indexName: gsi.indexName,
+        unique: gsi.unique,
+        partial: false,
+        inputFieldNames: gsi.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 gsi of metadata.gsiDefinitions) {
+    const match = classifySegmentMatch(gsi.segmented, queryFields);
+    if (match === "partial") {
+      return {
+        type: "gsi",
+        indexName: gsi.indexName,
+        unique: false,
+        partial: true,
+        inputFieldNames: queryFields
+      };
+    }
+    if (match === "full") {
+      return {
+        type: "gsi",
+        indexName: gsi.indexName,
+        unique: gsi.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/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 gsi of meta.gsiDefinitions) {
+    for (const f of segmentFieldNames(gsi.segmented.pkSegments)) attrs.add(f);
+    for (const f of segmentFieldNames(gsi.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
+  };
+}
+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/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/cfn-schema-consistency.ts
+var MAX_GSIS_PER_TABLE = 20;
+function gsiShape(gsi) {
+  const hasSk = gsi.segmented.skSegments.length > 0;
+  return { indexName: gsi.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 gsi of meta.gsiDefinitions) {
+      const shape = gsiShape(gsi);
+      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;
+}
+
+export {
+  isColumn,
+  createColumnMap,
+  isKeySegment,
+  k,
+  isKeyDefinition,
+  segmentFieldNames,
+  buildSegmentedKey,
+  key,
+  Linter,
+  noScanRule,
+  requireLimitRule,
+  gsiAmbiguityRule,
+  resolveKey,
+  missingGsiRule,
+  relationDepthRule,
+  samePartitionPresetRule,
+  missingContextRule,
+  embeddedSnapshotSizeRule,
+  hotPartitionRule,
+  fanOutRule,
+  multiMaintainerSameRowRule,
+  TableMapping,
+  cfnSchemaConsistencyRule,
+  createDefaultLinter
+};