graphddb 0.5.2 → 0.6.0

package/dist/index.js

@@ -1,3 +1,6 @@
+import {
+  queryBoundaryRule
+} from "./chunk-MMVHOUM4.js";
 import {
   BatchGetResult,
   DDBModel,
@@ -36,7 +39,6 @@ import {
   deriveEdgeWriteItems,
   deriveEdgeWriteItemsFor,
   deriveModelEdgeWriteItems,
-  detectRelationFields,
   edgeWrites,
   encodeCursor,
   evaluateFilter,
@@ -50,7 +52,6 @@ import {
   executeQuery,
   from,
   getEdgeWrites,
-  getImplicitKeyFields,
   isCommandModelContract,
   isCommandPlan,
   isContractComposeNode,
@@ -77,7 +78,7 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-H5TUW2WR.js";
+} from "./chunk-N5NQM3SO.js";
 import {
   CdcEmulator,
   MAINT_OUTBOX_PK_PREFIX,
@@ -89,7 +90,7 @@ import {
   orderAndTrimCollection,
   pathField,
   projectFrom
-} from "./chunk-QBXLQNXY.js";
+} from "./chunk-5NXNEW43.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -99,11 +100,9 @@ import {
   DynamoExecutor,
   ENTITY_WRITES_MARKER,
   LIFECYCLE_CONTRACT_MARKER,
-  Linter,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
   RetryingExecutor,
-  TableMapping,
   TransactionContext,
   attachModelClass,
   buildConditionExpression,
@@ -118,7 +117,7 @@ import {
   collectViewDefinitions,
   commitTransaction,
   cond,
-  createDefaultLinter,
+  detectRelationFields,
   entityWrites,
   execItemKeySignature,
   executeDelete,
@@ -126,13 +125,11 @@ import {
   executeTransaction,
   executeUpdate,
   getEntityWrites,
+  getImplicitKeyFields,
   gsi,
-  gsiAmbiguityRule,
   hydrate,
   identity,
-  isColumn,
   isEntityWritesDefinition,
-  isKeySegment,
   isLifecycleContract,
   isMaintainTrigger,
   isParam,
@@ -140,24 +137,31 @@ import {
   isRetryableError,
   isRetryableTransactionCancellation,
   isSelectBuilder,
-  k,
-  key,
   lifecyclePhaseForIntent,
   maintainTrigger,
-  missingGsiRule,
-  noScanRule,
   param,
   parseChange,
   preview,
-  relationDepthRule,
-  requireLimitRule,
   resolveConditionTree,
-  resolveKey,
   resolveModelClass,
-  segmentFieldNames,
   serializeFieldValue
-} from "./chunk-W3GEJPPV.js";
-import "./chunk-MCKGQKYU.js";
+} from "./chunk-F2DI3GTI.js";
+import {
+  Linter,
+  TableMapping,
+  createDefaultLinter,
+  gsiAmbiguityRule,
+  isColumn,
+  isKeySegment,
+  k,
+  key,
+  missingGsiRule,
+  noScanRule,
+  relationDepthRule,
+  requireLimitRule,
+  resolveKey,
+  segmentFieldNames
+} from "./chunk-PDUVTYC5.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -508,6 +512,29 @@ function hasMany(targetFactory, keyBindingOrCallback, options) {
     });
   };
 }
+function refs(targetFactory, options) {
+  return function(_value, context) {
+    const propertyName = String(context.name);
+    assertRelationPropertyNameAllowed(propertyName);
+    if (!options || typeof options.from !== "string" || typeof options.key !== "string") {
+      throw new Error(
+        `@refs relation '${propertyName}': options must supply \`from\` (the parent list attribute, e.g. 'tagRefs') and \`key\` (the ref field on each element, e.g. 'tagId').`
+      );
+    }
+    const { from: from2, key: key2, to, ...relationOptions } = options;
+    const targetKeyField = to ?? key2;
+    collectRelation({
+      type: "refs",
+      propertyName,
+      targetFactory,
+      // Scalar keyBinding: target child key field ← element key name. Per resolved
+      // element the existing scalar key-building machinery reuses this unchanged.
+      keyBinding: { [targetKeyField]: key2 },
+      refs: { from: from2, key: key2 },
+      ...Object.keys(relationOptions).length > 0 ? { options: relationOptions } : {}
+    });
+  };
+}
 function belongsTo(targetFactory, keyBinding, options) {
   return function(_value, context) {
     const propertyName = String(context.name);
@@ -1250,27 +1277,6 @@ async function executeRangeFanout(op, keys, params = {}) {
   return out;
 }
 
-// src/linter/rules/query-boundary.ts
-var queryBoundaryRule = {
-  id: "query-boundary",
-  severity: "error",
-  check(metadata) {
-    const results = [];
-    for (const gsi2 of metadata.gsiDefinitions) {
-      if (!gsi2.unique) {
-        results.push({
-          ruleId: "query-boundary",
-          severity: "error",
-          message: `GSI '${gsi2.indexName}' on entity '${metadata.prefix}' is not marked as unique. Using query() on a non-unique GSI may return multiple items. Use list() instead, or mark the GSI as unique if it guarantees single results.`,
-          entity: metadata.prefix,
-          field: gsi2.indexName
-        });
-      }
-    }
-    return results;
-  }
-};
-
 // src/relation/maintenance-rebuild.ts
 function toClass(m) {
   try {
@@ -2011,6 +2017,7 @@ export {
   publicQueryModel,
   query,
   queryBoundaryRule,
+  refs,
   relationDepthRule,
   requireLimitRule,
   resolveKey,

package/dist/linter/index.d.ts

@@ -0,0 +1,126 @@
+import { L as LintRule } from '../registry-DbqmFyab.js';
+export { a as LintResult, b as Linter } from '../registry-DbqmFyab.js';
+export { c as createDefaultLinter, g as gsiAmbiguityRule, m as missingGsiRule, n as noScanRule, q as queryBoundaryRule, r as relationDepthRule, a as requireLimitRule } from '../relation-depth-0TiWr5OW.js';
+import '../maintenance-view-adapter-CFeasCKo.js';
+import '@aws-sdk/client-dynamodb';
+
+/**
+ * `samePartition` preset validator (Epic #118 child issue H).
+ *
+ * The `samePartition` preset is pure **lowering sugar**: a
+ * `@hasMany(..., { pattern: 'samePartition' })` declares that the children live
+ * in the **same partition** as the parent and are reached by a `begins_with`
+ * range read on a **segmented sort key** (RFC #118: `TestCaseModel` children of
+ * `SuiteModel`, same `PROJECT#{projectId}` PK, child SK
+ * `SUITE#{suiteId}#CASE#…`). There is **no maintained materialisation** — the
+ * preset carries no new write effect; it simply names an access shape the
+ * existing segmented-key + hasMany planner already produces.
+ *
+ * Because the preset desugars onto the *exact same* metadata path as the escape
+ * hatch (a bare `@hasMany` whose `keyBinding` is a contiguous prefix of the
+ * target's primary key), this rule's role is to verify the declaration really
+ * does lower that way — so that the preset form and the escape-hatch form are
+ * guaranteed to plan identically. It rejects declarations that name the preset
+ * but cannot lower to it (wrong key shape, GSI hop, maintenance options),
+ * turning a silent mis-lowering into a build-time error.
+ *
+ * ## Integrity rules enforced
+ *
+ * 1. **hasMany only** — `samePartition` is a parent→children collection read;
+ *    `belongsTo` / `hasOne` are single-target lookups and cannot lower to a
+ *    same-partition `begins_with`.
+ * 2. **Same partition, SK-prefix read** — the `keyBinding` must resolve against
+ *    the target's **primary key** as a `partial` match (every PK field bound,
+ *    the SK a proper segment prefix → `begins_with`). A GSI hop is a *different*
+ *    partition, and a `full` PK match is a point read of a single item, not a
+ *    child collection: both contradict the preset.
+ * 3. **No maintenance effect** — `read` / `write` / `projection` belong to the
+ *    maintained presets (`embeddedSnapshot` etc., #124/#125). `samePartition`
+ *    has no maintained materialisation, so these options on it are a declaration
+ *    error rather than a silently ignored field.
+ */
+declare const samePartitionPresetRule: LintRule;
+
+/**
+ * `missing-context` validator (Epic #118 issue #126, child G; AC: payload 非同梱
+ * 属性で error — 論点4 = payload 同梱のみ).
+ *
+ * A maintained relation (`embeddedSnapshot` etc.) projects attributes of its
+ * **source** entity (the relation target, whose lifecycle fires the maintenance)
+ * into the maintained snapshot / collection on the owner row. Phase 1 allows
+ * **payload 同梱 only** (論点4): the projection may read only attributes the
+ * source row actually carries on its write payload — there is no write-time fetch
+ * or re-projection (that is Phase 2 / stream). This rule rejects, as an `error`,
+ * any projection (or key-binding) source attribute that is absent from the source
+ * entity's payload.
+ *
+ * ## Role split vs D (#124 maintenance graph round-trip)
+ *
+ * D's `buildMaintenanceGraph` (`src/relation/maintenance-graph.ts`,
+ * `assertMaintenanceRoundTrips`) **already throws** on this exact condition when
+ * the graph is built. The overlap is deliberate and complementary, NOT redundant:
+ *
+ * - **Layer / timing.** D's reject fires only when someone *builds the graph*
+ *   (compile / explicit `buildMaintenanceGraph()`); it is the build-time final
+ *   defence. This rule runs inside `MetadataRegistry.finalize` (the moment a model
+ *   is first resolved), so a payload-非同梱 projection is surfaced **eagerly**, as
+ *   a structured per-entity `LintResult` with `entity` + `field`, alongside every
+ *   other lint finding — before any graph build.
+ * - **No re-derivation.** The rule does NOT call `buildMaintenanceGraph` (that
+ *   would re-derive the whole graph and, inside `finalize`, recurse through the
+ *   registry). It reads the same declaration metadata (`options.projection` +
+ *   `keyBinding`) and computes the same payload surface (`payloadAttributes`,
+ *   mirroring D's `sourcePayloadAttributes`) directly. D remains the SSoT for the
+ *   *build-time* reject; this is the user-facing linter diagnostic for the same
+ *   invariant.
+ *
+ * Source-payload resolution needs the **source** (relation target) metadata, so
+ * the rule resolves it via the registry (like `relation-depth`); if the target is
+ * unregistered it is skipped here (D / other rules surface that).
+ */
+declare const missingContextRule: LintRule;
+
+declare const embeddedSnapshotSizeRule: LintRule;
+
+declare const hotPartitionRule: LintRule;
+
+declare const fanOutRule: LintRule;
+
+/**
+ * `multi-maintainer-same-row` validator (Epic #118 issue #126, child G; AC: 同一
+ * 行への複数 maintain 効果で error — 論点2 = (b)).
+ *
+ * 論点2 was decided **(b)**: Phase 1 constrains maintenance to "**1 mutation × 1
+ * target row = 1 maintain effect**". If two or more maintained relations would,
+ * under the **same** trigger, write the **same** destination (owner) row, a single
+ * mutation would touch that one row twice — the same one-row-twice collision
+ * DynamoDB rejects in a `TransactWriteItems`, and the case #96 made a loud reject.
+ * This rule flags that configuration as an **error**.
+ *
+ * ## Consuming D's `multiMaintainerTargets` (#124) — and why this rule recomputes
+ *    the same grouping locally
+ *
+ * D's `buildMaintenanceGraph` exposes exactly this collision material as
+ * `MaintenanceGraph.multiMaintainerTargets` (grouped by `"<trigger>
+ * <destinationRowKey>"`, only groups of size > 1). By design D **surfaces** the
+ * collision without rejecting (its header: "#124 surfaces it, #125/#126 decide the
+ * reject") — and `destinationRowKey` is built as
+ * `"<ownerEntity>#<sorted ownerField=$.entity.sourceField>"`, so a collision is
+ * **always among one owner entity's own relations** (the owner name is part of the
+ * key, so two different entities can never share a destination row — confirmed by
+ * D's test "different owner entities → no collision").
+ *
+ * That fact is what lets this linter rule run **per-entity** inside
+ * `MetadataRegistry.finalize`: it recomputes D's `(trigger, destinationRowKey)`
+ * grouping over **this entity's own** maintained relations — the identical
+ * collision predicate, restricted to the only scope a collision can occur in — so
+ * it never needs to build the global graph (which, inside `finalize`, would
+ * re-enter the registry). The role split mirrors `missing-context`: D is the
+ * build-time material / final-defence, G is the eager user-facing linter
+ * diagnostic. The complementary compile-time reject is E (#125, NOT touched here).
+ */
+declare const multiMaintainerSameRowRule: LintRule;
+
+declare const cfnSchemaConsistencyRule: LintRule;
+
+export { LintRule, cfnSchemaConsistencyRule, embeddedSnapshotSizeRule, fanOutRule, hotPartitionRule, missingContextRule, multiMaintainerSameRowRule, samePartitionPresetRule };

package/dist/linter/index.js

@@ -0,0 +1,36 @@
+import {
+  queryBoundaryRule
+} from "../chunk-MMVHOUM4.js";
+import {
+  Linter,
+  cfnSchemaConsistencyRule,
+  createDefaultLinter,
+  embeddedSnapshotSizeRule,
+  fanOutRule,
+  gsiAmbiguityRule,
+  hotPartitionRule,
+  missingContextRule,
+  missingGsiRule,
+  multiMaintainerSameRowRule,
+  noScanRule,
+  relationDepthRule,
+  requireLimitRule,
+  samePartitionPresetRule
+} from "../chunk-PDUVTYC5.js";
+export {
+  Linter,
+  cfnSchemaConsistencyRule,
+  createDefaultLinter,
+  embeddedSnapshotSizeRule,
+  fanOutRule,
+  gsiAmbiguityRule,
+  hotPartitionRule,
+  missingContextRule,
+  missingGsiRule,
+  multiMaintainerSameRowRule,
+  noScanRule,
+  queryBoundaryRule,
+  relationDepthRule,
+  requireLimitRule,
+  samePartitionPresetRule
+};