graphddb 0.8.0 → 0.9.0

package/dist/behaviors-DDltNivc.d.ts

@@ -0,0 +1,217 @@
+import { Recorded, Component, ComponentGraphIR, PortSchema, BehaviorClass } from 'behavior-contracts';
+
+/**
+ * GraphDDB's first-class SCP catalog — issue #297 SP1 (SCP authoring adoption),
+ * promoting the Phase-1 executor catalog (#288, `src/executor/catalog.ts`) into
+ * THE behavior-contracts–typed catalog the spec emitter is validated against.
+ *
+ * ## Source of truth (SP1 decision)
+ *
+ * ONE catalog lives here, in the spec layer — the layer that emits `components[]`
+ * (`src/spec/components.ts`) — and `src/executor/catalog.ts` re-exports it
+ * unchanged (the C4 handler registry keeps resolving against the same object).
+ * The Phase-1 module described itself as the C2 "the only per-DSL difference is
+ * the catalog" surface but its Port schemas mirrored the OLD-path executor
+ * inputs (`DynamoDBOperation` / `PutInput`), written before the Phase-3 emitter
+ * existed. Since #290 P3-5 the portable IR's actual wiring is the emitted
+ * component-graph ports, so promoting the catalog to LOAD-BEARING means the
+ * schemas here describe the EMITTED Port contract (what `readPorts` /
+ * `transactionItemPorts` in `components.ts` actually wire, and what a
+ * `runBehavior` handler actually receives) — the two latent Phase-1↔Phase-3
+ * inconsistencies are fixed loudly, not papered over:
+ *
+ * 1. **`ConditionCheck` was missing.** The emitter has emitted `ConditionCheck`
+ *    componentRefs since Phase 3 (`buildTransactionComponent`), but the Phase-1
+ *    catalog declared only 7 entries without it — so the "catalog" did not cover
+ *    the emitted vocabulary. It is now a first-class entry.
+ * 2. **`TransactWrite` is not portable.** No portable document references
+ *    `TransactWrite` (a transaction is emitted as a Component whose body
+ *    references the per-item write primitives; the atomic TransactWriteItems
+ *    envelope is the TS runtime's execution concern) — so its Phase-1
+ *    `portableToIR: true` claim was false since P3-5. It stays a catalog entry
+ *    (the executor-side atomic envelope, and a member of the write set) but is
+ *    now honestly `portableToIR: false`.
+ *
+ * ## Port schema conventions
+ *
+ * A `CatalogEntry.inputPorts` names the STATIC ports of the emitted wiring. Two
+ * port families are dynamic by construction and are validated by
+ * {@link assertComponentsInCatalog} against documented patterns instead:
+ *
+ * - **Read key-attribute ports**: one port per `keyExpr` attribute, named by the
+ *   physical key attribute — graphddb's fixed single-table convention
+ *   `PK` / `SK` / `<index>PK` / `<index>SK` ({@link KEY_ATTR_PORT}).
+ * - **Write record ports**: a transaction item's `item` / `key` / `changes` /
+ *   `add` records and the `condition.equals` / `condition.params` /
+ *   `condition.values` slots are flattened one-port-per-field under a
+ *   `<group>.<field>` key ({@link WRITE_PORT_FAMILIES}).
+ *
+ * ## Dynamic-port opt-in (`additionalPorts`, SP3)
+ *
+ * The seven read/write-item entries carry `additionalPorts: true` (bc#26): their
+ * dynamic port families above are BY DESIGN not statically enumerable, so bc's
+ * shared port check (`checkPortNames` — used by both the `catalogComponents`
+ * authoring recorder and `buildComponentDefinition`) must not reject them. This
+ * is an honest declaration, not a loosening: the dynamic families are still
+ * validated fail-closed by {@link assertComponentsInCatalog} (emit/registration
+ * time), and every DECLARED port keeps bc's required/type checks regardless of
+ * the opt-in. It is exactly this opt-in that makes `GRAPHDDB_CATALOG` directly
+ * consumable by the shared authoring surface (`catalogComponents(GRAPHDDB_CATALOG)`,
+ * bc#24 / #297 SP3) — the C2 contract that the catalog IS the whole per-DSL
+ * difference. `TransactWrite` stays fail-closed (its one port is static).
+ *
+ * ## Write set (SP1b) — and where `ConditionCheck` sits
+ *
+ * {@link WRITE_CATALOG_NAMES} is the CQRS write catalog: `PutItem` /
+ * `UpdateItem` / `DeleteItem` / `TransactWrite` / `ConditionCheck`.
+ * `ConditionCheck` mutates nothing — but it is classified WRITE deliberately:
+ * it exists only inside `TransactWriteItems` (DynamoDB accepts it in no read
+ * API), it acquires the item's transactional lock, and its failure aborts the
+ * sibling writes. A component referencing it therefore can only ever execute on
+ * the command path — for effect ROUTING (which is all the write set decides,
+ * bc#24) it is command-side infrastructure, not a read. The read set is exactly
+ * `GetItem` / `Query` / `BatchGetItem`; every catalog name is in exactly one set.
+ */
+
+/**
+ * The catalog-name literal union — one entry per DynamoDB primitive GraphDDB
+ * declares: the `ReadOperationType` (`GetItem` / `Query` / `BatchGetItem`) and
+ * `WriteOperationType` (`PutItem` / `UpdateItem` / `DeleteItem`) enum members
+ * from `src/spec/types.ts`, the transaction-item assertion primitive
+ * (`ConditionCheck`), and the atomic envelope (`TransactWrite`).
+ */
+type CatalogName = 'GetItem' | 'Query' | 'BatchGetItem' | 'PutItem' | 'UpdateItem' | 'DeleteItem' | 'ConditionCheck' | 'TransactWrite';
+/** GraphDDB's CQRS effect vocabulary, mapped 1:1 from bc's `BehaviorEffect`. */
+type ContractEffect = 'query' | 'command';
+
+/**
+ * `publishBehaviors` — the shared-SCP authoring entry (issue #297 SP3; pairs
+ * graphddb with behavior-contracts bc#24 and connects to #296 P4-1).
+ *
+ * A user authors a **`SemanticBehavior` class** on behavior-contracts' SHARED
+ * authoring surface — `$` input wiring, `when` / `.map` structured control, the
+ * expression builders (`eq` / `concat` / `coalesce` / …), and the leaf
+ * components minted from graphddb's catalog via
+ * `catalogComponents(GRAPHDDB_CATALOG)` ({@link behaviorComponents}) — and
+ * publishes it here:
+ *
+ * ```ts
+ * import { graphddb, behaviorComponents } from 'graphddb';
+ * import { SemanticBehavior, concat, type In } from 'behavior-contracts';
+ *
+ * const G = behaviorComponents();
+ * class ArticleBehaviors extends SemanticBehavior {
+ *   getArticleWithTags($: In<{ articleId: string }>) {
+ *     const a = G.GetItem({ table: 'Articles', PK: concat('ARTICLE#', $.articleId), SK: 'META',
+ *                           projection: ['articleId', 'title', 'tagRefs'] });
+ *     const tags = a.tagRefs.map(($t: Recorded) =>
+ *       G.BatchGetItem({ table: 'Articles', PK: concat('TAG#', $t.tagId), SK: 'META',
+ *                        projection: ['tagId', 'label'] }), { batched: true });
+ *     return { article: a, tags };
+ *   }
+ * }
+ * const Articles = graphddb.publishBehaviors(ArticleBehaviors);
+ * ```
+ *
+ * ## Responsibility split (C2 — "the difference is the catalog only")
+ *
+ * - **behavior-contracts does ALL composition and lowering**: `compileBehaviors`
+ *   evaluates each public method once (throwing-sentinel recording + native
+ *   control-syntax source scan), lowers `$` references, component calls, `when`
+ *   and `.map` into the portable component-graph IR, derives the plan, and
+ *   self-checks the result with `assertPortableComponentGraph`. graphddb adds
+ *   **no generic lowering of its own**.
+ * - **graphddb supplies only the catalog and the effects**: the leaf vocabulary
+ *   is `GRAPHDDB_CATALOG` (#297 SP1 — the same load-bearing catalog the spec
+ *   emitter is validated against), the dynamic port families are validated by
+ *   the same {@link assertComponentsInCatalog}, and the Query/Command
+ *   classification is DERIVED from the lowered graph per SP2/SP4
+ *   ({@link deriveContractEffect}) — the author never declares an effect
+ *   (authoring is effect-agnostic; a method that references a write-catalog
+ *   primitive IS a command).
+ *
+ * The compiled components register additively into the operations document
+ * through `buildOperations`' `contractInputs.behaviors` (each component emitted
+ * as `<RegistrationKey>__<method>`), and the TS runtime executes them through
+ * bc's `runBehavior` with graphddb's real DynamoDB handlers
+ * (`src/executor/behavior-exec.ts` — the Phase-1 handler-registry seam's
+ * behavior-execution counterpart, mirroring `python/graphddb_runtime/behavior_exec.py`).
+ */
+
+/**
+ * One published behavior method: the bc-lowered component (name = the method
+ * name), plus its graph-DERIVED CQRS effect (#297 SP2/SP4 — the classification
+ * source of truth is the component graph; `publishBehaviors` has no
+ * query/command vocabulary for the author to declare).
+ */
+interface BehaviorMethodSpec {
+    /** The method (= root Behavior = component) name. */
+    readonly name: string;
+    /** Graph-derived Query/Command classification (never author-declared). */
+    readonly effect: ContractEffect;
+    /** The lowered portable component (bc `compileBehaviors` output). */
+    readonly component: Component;
+}
+/**
+ * A resolved behavior contract — `publishBehaviors` output. Carries the whole
+ * bc-lowered {@link ComponentGraphIR} (directly `runBehavior`-executable; the
+ * component names are the method names) and the per-method specs with their
+ * derived effects. Register it into the operations document via
+ * `buildOperations(..., { behaviors: { Name: contract } })`.
+ */
+interface BehaviorModelContract {
+    /** Discriminates from the publishQuery/publishCommand contract objects. */
+    readonly kind: 'behaviors';
+    /** The authored class name (diagnostics only). */
+    readonly className: string;
+    /** The bc-lowered portable IR (all methods; `runBehavior`-executable). */
+    readonly ir: ComponentGraphIR;
+    /** The lowered components (`ir.components`, one per public method). */
+    readonly components: readonly Component[];
+    /** Method name → lowered component + derived effect. */
+    readonly methods: Readonly<Record<string, BehaviorMethodSpec>>;
+}
+/** Options passed through to bc `compileBehaviors` (additive; all optional). */
+interface PublishBehaviorsOptions {
+    /**
+     * Input Port schema overrides (method → port → schema): build-time evaluation
+     * derives port NAMES from `$` accesses; TS types are erased, so supply the
+     * type strings here if the registered document should carry them.
+     */
+    readonly inputPorts?: Record<string, Record<string, PortSchema>>;
+    /** Plan concurrency recorded on the lowered components (bc default: 16). */
+    readonly concurrency?: number;
+}
+/** The `catalogComponents(GRAPHDDB_CATALOG)` leaf-function map (typed). */
+type BehaviorComponentFns = Record<CatalogName, (ports: Record<string, unknown>) => Recorded>;
+/**
+ * The graphddb leaf components for the shared authoring surface:
+ * `catalogComponents(GRAPHDDB_CATALOG)` bound once, lazily. Call it at module
+ * scope of an authoring module (`const G = behaviorComponents()`) and invoke
+ * the leaves inside `SemanticBehavior` method bodies. `TransactWrite` is in the
+ * map but is `portableToIR: false`, so wiring it is rejected at record time —
+ * the atomic envelope is a TS-runtime execution concern, never authored.
+ */
+declare function behaviorComponents(): BehaviorComponentFns;
+/**
+ * Publish a `SemanticBehavior` class as a graphddb behavior contract (#297 SP3).
+ *
+ * Pipeline (all loud, nothing dropped):
+ *  1. bc `compileBehaviors(cls)` lowers every public method into one portable
+ *     component (bc owns ALL composition/lowering and self-checks portability);
+ *  2. graphddb validates every lowered component against `GRAPHDDB_CATALOG` —
+ *     the SAME {@link assertComponentsInCatalog} the spec emitter runs (SP1c),
+ *     covering the dynamic key-attribute / write record-family ports bc's
+ *     static schema check cannot enumerate;
+ *  3. the CQRS effect of every method is DERIVED from its graph
+ *     ({@link deriveContractEffect} — SP2/SP4; the author never declares it).
+ *
+ * @throws bc `AuthoringFailure` for a non-declarative body (native control
+ *   syntax, coercion, unknown/missing ports, …); an `Error` from the catalog
+ *   validation for an undeclared dynamic port.
+ */
+declare function publishBehaviors(cls: BehaviorClass, options?: PublishBehaviorsOptions): BehaviorModelContract;
+/** Runtime guard: is `value` a {@link BehaviorModelContract}? */
+declare function isBehaviorModelContract(value: unknown): value is BehaviorModelContract;
+
+export { type BehaviorModelContract as B, type PublishBehaviorsOptions as P, type BehaviorMethodSpec as a, type BehaviorComponentFns as b, behaviorComponents as c, isBehaviorModelContract as i, publishBehaviors as p };

package/dist/cdc/index.d.ts

@@ -1,7 +1,8 @@
-import { w as CdcEmulatorOptions, x as ChangeHandler, y as Unsubscribe, F as FaultSpec, z as ConcurrentRecomputeRef, v as ChangeEvent, A as EventLog, G as ReplayOptions, H as ShardId, I as MaintainTrigger, E as EffectPath, g as ProjectionMap, j as MembershipPredicate } from '../key-DR7_lpyk.js';
-export { J as BatchResult, K as CdcMode, L as ChangeBatch, N as ChangeEventName, O as ClockMode, V as StartingPosition, X as StreamViewType, Y as SubscribeHandler, Z as SubscribeHandlers, _ as buildSubscribeHandler } from '../key-DR7_lpyk.js';
-import { E as EntityMetadata } from '../types-BXLzIcQD.js';
-import '../types-2PMXEn5x.js';
+import { w as CdcEmulatorOptions, x as ChangeHandler, y as Unsubscribe, F as FaultSpec, z as ConcurrentRecomputeRef, v as ChangeEvent, A as EventLog, G as ReplayOptions, H as ShardId, I as MaintainTrigger, E as EffectPath, g as ProjectionMap, j as MembershipPredicate } from '../key-Dne-a20Q.js';
+export { J as BatchResult, K as CdcMode, L as ChangeBatch, N as ChangeEventName, O as ClockMode, V as StartingPosition, X as StreamViewType, Y as SubscribeHandler, Z as SubscribeHandlers, _ as buildSubscribeHandler } from '../key-Dne-a20Q.js';
+import { E as EntityMetadata } from '../types-BnFsTZwl.js';
+import '../types-CfxzTEFL.js';
+import 'behavior-contracts';
 
 /**
  * CDC emulator (issue #72). Subscribes to the core write-capture seam

package/dist/cdc/index.js

@@ -8,12 +8,12 @@ import {
   createMaintenanceDrainHandler,
   hashString,
   shardIdFor
-} from "../chunk-GS4C5VGO.js";
+} from "../chunk-YGQ2NO6J.js";
 import {
   buildSubscribeHandler,
   parseChange
-} from "../chunk-HNY2EJPV.js";
-import "../chunk-L2NEDS7U.js";
+} from "../chunk-KOIJ4SNO.js";
+import "../chunk-ZNU7OI5I.js";
 import "../chunk-XTWXMOHD.js";
 export {
   CdcEmulator,

package/dist/{chunk-HNY2EJPV.js → chunk-KOIJ4SNO.js}

@@ -1,7 +1,7 @@
 import {
   MetadataRegistry,
   attachHiddenKey
-} from "./chunk-L2NEDS7U.js";
+} from "./chunk-ZNU7OI5I.js";
 import {
   resolveKey,
   segmentFieldNames

package/dist/{chunk-LGHSZIEE.js → chunk-NWTEUWJD.js}

@@ -1,12 +1,12 @@
 import {
   evaluateKey
-} from "./chunk-I4LEJ4TF.js";
+} from "./chunk-XZTA4VJH.js";
 import {
-  SPEC_VERSION
-} from "./chunk-L4QRCHRQ.js";
+  SPEC_VERSION_KEY_EXPR
+} from "./chunk-WOFRHRXY.js";
 import {
   MetadataRegistry
-} from "./chunk-L2NEDS7U.js";
+} from "./chunk-ZNU7OI5I.js";
 import {
   TableMapping
 } from "./chunk-XTWXMOHD.js";
@@ -136,7 +136,9 @@ function buildManifest(registry = MetadataRegistry) {
     }
   }
   return {
-    version: SPEC_VERSION,
+    // #289 Phase 2: the IR SSoT is version 2.0 (major bump); the manifest tracks
+    // the same major so validateEnvelope's major-match passes (see Manifest.version).
+    version: SPEC_VERSION_KEY_EXPR,
     tables: sortedRecord(tables),
     entities
   };