graphddb 0.8.0 → 0.9.0

package/docs/python-bridge.md

@@ -276,63 +276,46 @@ Every operation carries a `params` map of `ParamSpec`:
 
 #### Queries
 
-A `QuerySpec` has `params`, an ordered `operations` array, and a `cardinality`
-(`"one"` or `"many"`). Each `OperationSpec`:
+A `QuerySpec` has `params`, an `operations` array carrying exactly **one**
+entry — the root physical op — and a `cardinality` (`"one"` or `"many"`).
+Since SCP IR Phase 3 (#290 P3-5) relation fan-out is NOT part of `queries`:
+it lives exclusively in the universal `components[]` graph (below). The root
+`OperationSpec`:
 
 ```jsonc
 {
   "type": "Query",                // "Query" | "GetItem" | "BatchGetItem"
   "tableName": "UserPermissions",
   "indexName": "GSI1",            // omitted for base-table access
-  "keyCondition": { "GSI1PK": "EMAIL#{email}", "GSI1SK": "PROFILE" },
-  "rangeCondition": { "operator": "begins_with", "key": "SK", "value": "USER#" },
   "projection": ["email", "name", "status", "userId"],
+  "keyExpr": { "GSI1PK": { "concat": ["EMAIL#", { "ref": ["input", "email"] }] },
+               "GSI1SK": "PROFILE" },
+  "rangeCondition": { "operator": "begins_with", "key": "SK", "valueExpr": "USER#" },
   "limit": 20,
-  "filter": { /* declarative FilterExpression */ },
-  "resultPath": "$",              // "$" or e.g. "$.groups.items"
-  "sourceField": "userId"         // present on relation child operations
+  "filter": { /* declarative FilterExpression */ }
 }
 ```
 
 The operation type is chosen by the planner from the key shape: a full PK+SK is
 a `GetItem`; a partial key with a contiguous sort-key prefix is a `Query` with a
 `begins_with` `rangeCondition`; a partition-key-only access is a `Query`. The
-`projection` is the set of scalar fields selected `true`.
-
-#### Template placeholders
-
-Key, item, and change templates use two placeholder forms plus literals:
-
-- `{paramName}` — bound from caller-supplied parameters.
-- `{result.sourceField}` — bound from a prior operation's result item(s), used to
-  chain relation operations.
-- Literal text (e.g. `PROFILE`, `USER#`) is emitted verbatim.
-
-The planner derives every template by **symbolic evaluation** of the model's key
-mapping (it evaluates the key function over symbolic field markers rather than
-concrete values), producing `USER#{userId}`-style templates directly from the
-metadata.
-
-#### Relation chaining and execution plan
-
-A relation traversal is expressed as additional `OperationSpec` nodes in the same
-query's `operations` array. Each child references its parent through
-`{result.sourceField}` in its `keyCondition`, and its `resultPath` nests the
-result under the parent (`$.groups.items` for a `hasMany`, `$.account` for a
-`belongsTo` / `hasOne`). `belongsTo` / `hasOne` children are emitted as
-`BatchGetItem`; `hasMany` children as `Query`.
-
-A query may carry an `executionPlan`:
-
-```jsonc
-{ "groups": [[1, 2], [3]], "concurrency": 16 }
-```
-
-`groups` is an ordered list of stages of operation indices (the root, index 0,
-is implicit and runs first). Operations within a stage are mutually independent
-and may run concurrently; later stages may read `{result.*}` produced by earlier
-ones. The same `deriveExecutionPlan` routine is used by the generator and by the
-TypeScript runtime, so the staging cannot drift between them.
+`projection` is the set of scalar fields selected `true`. The key wiring is
+portable Expression IR (`keyExpr` / `valueExpr`, #289), derived by **symbolic
+evaluation** of the model's key mapping. The runtime executes the root op via
+its `components[]` entry; the emitted root op remains the validation /
+`explain` / contract point-batch surface.
+
+#### Relation chaining and staging (`components[]`)
+
+A relation traversal is expressed as the query's entry in the top-level
+`components[]` — the universal SCP component graph (behavior-contracts
+`Component`): the root op becomes a `componentRef` body node, each relation a
+`componentRef` / `map` node whose id is the dotted result path
+(`groups.items`, `groups.items.group`), wired to its producer via `parent`
+and executed by `run_behavior` with the DynamoDB catalog handlers. A
+multi-node component carries a `plan` (`{ "groups": [[0], [1, 2]],
+"concurrency": 16 }`) staging mutually-independent nodes; the shared executor
+honors it.
 
 #### Commands
 
@@ -581,8 +564,9 @@ resuming with a cursor for the wrong key is rejected.
 
 ### 7.6 Relations, Batch, and Concurrency
 
-Relation children are resolved against the parents produced by earlier
-operations and merged into the result at their `resultPath`:
+Relation nodes of the query's `components[]` entry are resolved against the
+parents produced by earlier nodes and folded into the result at their node id
+path:
 
 - **`belongsTo` / `hasOne`** — source values from all parents are deduplicated
   and fetched in a single `BatchGetItem`, then matched back to each parent (a
@@ -592,10 +576,10 @@ operations and merged into the result at their `resultPath`:
 
 `BatchGetItem` requests are chunked at 100 keys, deduplicated, and retried on
 `UnprocessedKeys` with capped exponential backoff (up to 10 attempts).
-`BatchWriteItem` is chunked at 25 with the same `UnprocessedItems` retry. Stages
-of mutually independent operations (from `executionPlan`) run concurrently on a
-bounded thread pool (default 16 in flight); boto3 releases the GIL during
-network I/O, so the overlap is real. Result order is preserved.
+`BatchWriteItem` is chunked at 25 with the same `UnprocessedItems` retry. Node
+staging follows the component's `plan` inside the shared `run_behavior`
+executor (deterministic in-order reference semantics). Result order is
+preserved.
 
 ### 7.7 Transactions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",
@@ -54,6 +54,9 @@
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "gen:py:fixtures": "tsx src/cli.ts generate python --entry python/tests/fixtures/models.ts --transactions python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out python/tests/fixtures/generated",
     "gen:py:fixtures:multi": "tsx src/cli.ts generate python --entry python/tests/fixtures/models.ts --contracts python/tests/fixtures/definitions_multi.ts --out python/tests/fixtures/generated_multi",
+    "gen:py:behaviors:fixture": "tsx src/cli.ts generate behaviors --lang python --entry python/tests/fixtures/models.ts --transactions python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out python/tests/fixtures/generated_behaviors",
+    "gen:rust:behaviors:fixture": "tsx src/cli.ts generate behaviors --lang rust --entry python/tests/fixtures/models.ts --transactions python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out rust/graphddb_runtime/tests/generated_behaviors",
+    "gen:php:behaviors:fixture": "tsx src/cli.ts generate behaviors --lang php --entry python/tests/fixtures/models.ts --transactions python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out php/tests/fixtures/generated_behaviors",
     "test:py": "python3 -m pytest python/tests -m \"not integration\"",
     "test:py:integration": "python3 -m pytest python/tests -m integration",
     "test:conformance": "tsx conformance/run.ts",
@@ -71,7 +74,9 @@
     "embedoc:build": "embedoc build",
     "embedoc:watch": "embedoc watch",
     "embedoc:generate": "embedoc generate --all",
+    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
     "embedoc:check": "node scripts/embedoc-drift-check.mjs",
+    "deps:check": "node scripts/check-no-local-deps.mjs",
     "vendor:bc-php": "node scripts/vendor-behavior-contracts-php.mjs",
     "vendor:bc-php:check": "node scripts/vendor-behavior-contracts-php.mjs --check",
     "vendor:bc-vectors": "node scripts/vendor-behavior-contracts-vectors.mjs",
@@ -80,6 +85,9 @@
     "bench:crosslang:integration": "tsx benchmark/crosslang/integration.ts",
     "bench:crosslang:test": "vitest run benchmark/crosslang/__tests__"
   },
+  "size-limit-notes": {
+    "graphddb/spec (build-time)": "#290 transitional loop CLOSED at the final sub-pass (P3-5): the components[] emitter is now the PERMANENT (and only) portable carrier of relation fan-out + transaction write plans, so the sub-pass-1 dual-emit bump does not fully revert — the old operation/transaction builders remain as the emitter INTERNAL lowering input (they also feed the TS declarative executor and the AOT prepared plan); only their serialization into operations.json was removed, replaced by the small portable projection. Measured 22.38->22.51 KB across the flip (all first-party src/spec, zero new dependencies, all runtime bundles flat); budget stays 23 KB as the steady-state ceiling. Any future growth must be traced per the size-limit-gate discipline, never blanket-raised. #297 SP1+SP2 traced growth: 22.51->25.02 KB (+2.51 brotli), two traced components — (1) first-party src/spec/catalog.ts: the bc-typed GRAPHDDB_CATALOG + the SP1c emitter validation + the SP2 CQRS effect-derivation invariant, both wired into buildOperations so a catalog/effect mismatch is a BUILD error (load-bearing by design, must ship in this bundle); (2) behavior-contracts/dist/authoring.js partial inclusion, 5.66 KB minified (esbuild metafile-traced): the SP2-mandated classifyBehaviorEffect/referencedComponents live in bc's authoring module, whose top-level `export const add = binOp('add')`-style const-initializer calls esbuild cannot prove pure — bc 0.1.6 ships no sideEffects:false / __PURE__ annotations, so the two tiny helpers drag the authoring-DSL scaffolding along. NOT a new dependency (behavior-contracts already supplied this bundle's contract types); an upstream bc annotation fix reclaims (2), and the ceiling must be re-tightened when it lands. New ceiling 25.5 KB keeps the same ~0.5 KB headroom discipline as the previous 23 KB ceiling. #297 SP3+SP4 traced growth: 25.04->25.26 KB (+0.22 brotli), all first-party src/spec — the SP4 inversion (deriveComponentEffects + assertPublishSplitMatchesDerived with method-naming errors, replacing the SP2 symmetric assertion) plus the additive contractInputs.behaviors registration loop in buildOperations (rename + collision check + re-validation); the publishBehaviors authoring machinery itself is type-only from this bundle (src/define/behaviors.ts never enters dist/spec). Runtime-core bucket flat (39.08->39.07: the eager graphddb.publishBehaviors member tree-shakes out of a { DDBModel }-only consumer — bc 0.1.7 ships sideEffects:false); import-* bucket 47.8->55.4 (+7.6: bc compileBehaviors recorder/scanner + src/define/behaviors.ts + src/executor/behavior-exec.ts, all reachable only via publishBehaviors / behaviorComponents / behavior-exec). #297 SP5 traced growth: 25.26->28.84 KB (+3.58 brotli), one traced component — behavior-contracts/dist/builder.js (11.69 KB minified) + its guard.js dependency (3.51 KB minified), esbuild metafile-traced: SP5 moved components[] IR assembly/validation/canonicalization OUT of src/spec/components.ts and INTO bc's data-registration builder (buildComponentDefinition, bc#26 — the owner-decided split: extraction stays graphddb, IR shape is bc's), and the builder internally applies assertPortableComponentGraph (guard.js) as its fail-closed self-check, so both are load-bearing in the spec build path BY DESIGN (this is the seam the sub-pass exists to create, not a dependency leak). First-party src/spec shrank slightly (the hand-assembled Component return + inline plan emission were replaced by the registration call). New ceiling 29.3 KB keeps the same ~0.5 KB headroom discipline."
+  },
   "size-limit": [
     {
       "name": "runtime core (DDBModel + authoring)",
@@ -102,7 +110,7 @@
       "name": "graphddb/spec (build-time)",
       "path": "dist/spec/index.js",
       "import": "{ buildBridgeBundle }",
-      "limit": "20 KB"
+      "limit": "29.3 KB"
     },
     {
       "name": "graphddb/internal (AOT prepared-plan loader)",
@@ -150,7 +158,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "behavior-contracts": "0.1.3",
+    "behavior-contracts": "0.2.0",
     "commander": "^15.0.0",
     "handlebars": "^4.7.9"
   },