behavior-contracts 0.1.3 → 0.2.0

package/README.md

@@ -27,6 +27,11 @@ Requires Node.js >= 22 (ESM only).
 | `renderTemplate` | pure `{param}` string substitution |
 | `runPlan` | execute the portable execution-plan IR |
 | `canonicalValue` / `canonicalJson` | deterministic canonical serialization (sorted keys, compact JSON, `repr(float)`-parity decimals) |
+| `runBehavior` | execute the portable component-graph IR (handlers injected at the boundary) |
+| `assertPortable` / `assertPortableComponentGraph` | Portability Guard (fail-closed structural validation of portable IR) |
+| `SemanticBehavior` / `behavior` / `compileBehaviors` / `catalogComponents` / `when` + expression builders | shared, effect-agnostic SCP authoring surface — each public method of a marked class lowers to one component-graph root Behavior (consumers supply only their catalog) |
+| `referencedComponents` / `classifyBehaviorEffect` | consumer-side CQRS derivation from the lowered graph (authoring never names Query/Command) |
+| `buildComponentDefinition` | data-registration IF for model-driven consumers — validates and canonicalizes a pre-composed component graph (caller node ids, `parent`/`bindField`/`relationKind`, v2 `map` vocabulary, dynamic ports via catalog `additionalPorts: true`); byte-stable output, recorder-independent |
 
 ## Usage
 
@@ -49,10 +54,11 @@ library (semver) version:
 
 | Spec | Version |
 |---|---|
-| expression | 1 |
+| expression | 2 |
 | template | 1 |
 | plan | 1 |
-| canonical | 1 |
+| canonical | 2 |
+| behavior | 2 |
 | envelope | 1.1 |
 
 ## License

package/dist/authoring.d.ts

@@ -0,0 +1,202 @@
+/**
+ * authoring.ts — 共有 SCP authoring surface（effect 非依存の `SemanticBehavior`, bc#24）。
+ *
+ * SCP の原則 C2「difference is catalog only」を authoring 層で成立させる COMMON 実装。
+ * consumer（graphddb / litedbmodel / …）は **Catalog（leaf 専用コンポーネント）だけ**を供給し、
+ * Behavior の合成・命名・root 指定・配線・structured control はこの共有層が担う:
+ *
+ *   - **root 指定はクラス単位**: `SemanticBehavior` 基底（既定）または `@behavior` クラス
+ *     デコレータ（同義）。そのクラスの **各 public メソッド = 1 root Behavior（合成コンポーネント）**。
+ *     `#`-private / `_`-prefix はヘルパで publish されない。per-method マーカーは持たない。
+ *   - **Behavior 名 = メソッド名 / Input Port = `$` 引数（`$: In<...>`）/ Output Port = 返り値 /
+ *     内部 DAG = `$` 参照と structured control（Conditional・Guard・Map）から Compiler が導出**。
+ *     `await` / 実行順は書かない（plan は依存から導出）。
+ *   - **effect 非依存**: Query / Command（read-only か write か）は authoring の語彙に存在しない。
+ *     CQRS 分類は consumer の CQRS 層が lowering 済み component graph から導出する
+ *     （{@link referencedComponents} / {@link classifyBehaviorEffect} が共有の導出ヘルパ）。
+ *
+ * ## ビルド時評価（throwing-sentinel recording + source scan）
+ *
+ * メソッド本体は **定義時に一度だけ**、`$` と Catalog コンポーネント関数を recorder に
+ * 差し替えて評価される（graphddb `publishQuery` で実証済みの方式）。本体は静的に解釈可能で
+ * なければならない（concept.md §5.1: `Date.now` / random / fetch / env 禁止）。
+ *
+ * **ビルド時に loud に失敗する範囲（正確な列挙）**:
+ *   - recorder 値への ToPrimitive 暗黙変換（テンプレートリテラル補間・算術/関係演算子・
+ *     `valueOf`/`toString`/`toJSON`）→ `NOT_RECORDABLE`（Proxy トラップ）。
+ *   - recorder 値の列挙・spread・代入 → `NOT_RECORDABLE`（`ownKeys`/`set` トラップ）。
+ *   - 演算結果へのプロパティアクセス → `COMPUTED_ACCESS`。
+ *   - {@link when} に渡された非 recorder 条件（ネイティブ `===` の結果等）→ `BAD_CONDITION`。
+ *   - **ネイティブ制御構文の source scan** → `NATIVE_CONTROL_SYNTAX`: JS Proxy には
+ *     ToBoolean / strict-equality のトラップが**存在しない**ため、recorder 値上の
+ *     `?:` / `&&` / `||` / `??` / `?.` / `!` / `==` / `===` / `!=` / `!==` / `if (...)` /
+ *     `switch (...)` / `??=` / `&&=` / `||=` は評価では観測できず、（このスキャン以前は）
+ *     **黙って誤った DAG に lower され得た**（例: `$.flag ? C.Get(..) : C.Put(..)` は無条件
+ *     Get に、`$.limit ?? "d"` は default 消失に化ける）。そのため {@link compileBehaviors}
+ *     は評価の**前に**メソッド / ヘルパ / クラスのソースを走査し、これらのトークンを一律
+ *     fail-closed で拒否する（{@link scanNativeControlSyntax}。文字列リテラル・テンプレート
+ *     リテラルのテキスト部・コメント・正規表現リテラルは除外し、`${...}` 内コードは走査する）。
+ *
+ * **残余リスク（source scan の外 — ここに限り誤った DAG が黙って出得る。正直な限界）**:
+ *   - クラス外で定義された関数（モジュールレベル / import されたヘルパ / `eval` /
+ *     `new Function`）を record 中に呼び、その内部でネイティブ制御構文を recorder に
+ *     適用した場合。scan はクラス（と親クラス連鎖）のソースしか見ない。
+ *   - `for` / `while` のループ条件に recorder を書いた場合（ToBoolean(Proxy)=true のため
+ *     ビルドがハング / 空振りする — silent な誤 DAG ではないが loud なエラーでもない）。
+ *   - recorder に触れない任意 JS（閉包変数への分岐等）が record 結果を変える場合
+ *     （concept.md §5.1 で禁止だが機械検出されない）。
+ *   - behavior クラスを ES5 等へ downlevel するトランスパイラ（ヘルパ由来の `?:` 等が
+ *     注入され偽陽性になる）。behavior クラスのソースは modern ES のまま実行すること。
+ * 「誤った DAG が黙って出ることはない」はこの残余を除いた範囲でのみ成立する。
+ *
+ * JS の評価では recorder 値上のネイティブ `?:` / `&&` / `??` / `===` / `+` は観測できない
+ * （ToBoolean にトラップが無い等）ため、**式・構造化制御は既存 IR 語彙と 1:1 の関数表面**で
+ * 書く（新しい意味論は導入しない — 各関数は expression-ir.md §3 の operator /
+ * scp-ir-architecture.md §5 のノード種に 1:1 で lower される）:
+ *
+ *   - Expression: `concat` / `add` … / `eq` … / `and` / `or` / `not` / `coalesce`（`??`）/
+ *     `len` / `opt`（`?.` = refOpt）。オブジェクト・配列・スカラのリテラルはそのまま書ける
+ *     （`{obj:...}` / `{arr:[...]}` へ自動 lower）。
+ *   - Conditional / Guard: {@link when}。分岐が**純式のみ**なら Expression IR の `cond` へ、
+ *     分岐に **Component 宣言を含む**なら gate（CondNode）+ null-binding skip / Φ ノードへ
+ *     lower する（semantic-contract-programming.md「構造化制御構文」の Compiler 規則そのもの）。
+ *   - Map: ノード結果 recorder の **ネイティブ `.map(callback)`**（v2 語彙 `when`（要素 guard,
+ *     callback 内の {@link when}）/ `into` / `batched`（第2引数 opts）に対応）。
+ *
+ * lowering 先は **既存の component-graph IR そのもの**（behavior.ts / scp-ir-architecture.md §5。
+ * IR スキーマは変えない）。生成 IR は `assertPortableComponentGraph` を通り、`runBehavior` で
+ * そのまま実行できる。
+ */
+import type { Catalog, ComponentGraphIR, Component, PortSchema } from "./behavior.js";
+export type AuthoringFailureCode = "NOT_A_BEHAVIOR_CLASS" | "NO_PUBLIC_METHOD" | "NO_FRAME" | "NOT_RECORDABLE" | "NATIVE_CONTROL_SYNTAX" | "COMPUTED_ACCESS" | "WHOLE_INPUT" | "BAD_PORT_VALUE" | "UNKNOWN_PORT" | "MISSING_PORT" | "PORT_TYPE_MISMATCH" | "NOT_PORTABLE_COMPONENT" | "BAD_CONDITION" | "BAD_BRANCH" | "NESTED_BRANCH" | "MAP_IN_BRANCH" | "NESTED_MAP" | "MAP_NOT_LOWERABLE" | "MAP_MULTI_COMPONENT" | "BAD_OUTPUT";
+export declare class AuthoringFailure extends Error {
+    code: AuthoringFailureCode;
+    constructor(code: AuthoringFailureCode, message: string);
+}
+/**
+ * `SemanticBehavior` — 共有 authoring の基底クラス（既定の root マーカー）。
+ * 継承したクラスの各 public メソッドが 1 root Behavior として publish される。
+ * マーカー以外の実装・状態は持たない（authoring は effect 非依存・宣言のみ）。
+ */
+export declare class SemanticBehavior {
+}
+/** `compileBehaviors` が受け付けるクラス（0 引数 new 可能）。 */
+export type BehaviorClass = new () => object;
+/**
+ * `@behavior` — クラスデコレータ形の root マーカー（`SemanticBehavior` 継承と**同義**。
+ * 同じクラス本体はどちらのマーカーでも同一 IR に lower される）。
+ * TC39 standard / legacy いずれのデコレータ位置でも、素の関数呼び出しでも使える。
+ */
+export declare function behavior<T extends BehaviorClass>(cls: T, _context?: unknown): T;
+/**
+ * `In<T>` — 公開メソッドの `$` 引数の型（Input Port の compile-time 契約）。
+ * ランタイム値は recorder Proxy（`$` の各フィールドアクセスが `{ref:[<field>]}` へ lower され、
+ * アクセスされたフィールド名が component の `inputPorts` に記録される）。
+ */
+export type In<T> = Readonly<T>;
+/**
+ * recorder 値の実行時像（record 用 Proxy）。compile-time の型は authoring の関心事
+ * （`In<...>` / consumer の Catalog 型）に委ね、recorder は構造の記録に徹する。
+ */
+export type Recorded = any;
+/** `+`（文字列連結）。n-ary（min 2）。 */
+export declare function concat(...parts: unknown[]): Recorded;
+export declare const add: (a: unknown, b: unknown) => Recorded;
+export declare const sub: (a: unknown, b: unknown) => Recorded;
+export declare const mul: (a: unknown, b: unknown) => Recorded;
+export declare const div: (a: unknown, b: unknown) => Recorded;
+export declare const mod: (a: unknown, b: unknown) => Recorded;
+export declare const neg: (a: unknown) => Recorded;
+export declare const eq: (a: unknown, b: unknown) => Recorded;
+export declare const ne: (a: unknown, b: unknown) => Recorded;
+export declare const lt: (a: unknown, b: unknown) => Recorded;
+export declare const le: (a: unknown, b: unknown) => Recorded;
+export declare const gt: (a: unknown, b: unknown) => Recorded;
+export declare const ge: (a: unknown, b: unknown) => Recorded;
+export declare const and: (a: unknown, b: unknown) => Recorded;
+export declare const or: (a: unknown, b: unknown) => Recorded;
+export declare const not: (a: unknown) => Recorded;
+/** `??`。 */
+export declare const coalesce: (a: unknown, b: unknown) => Recorded;
+export declare const len: (a: unknown) => Recorded;
+/**
+ * `opt(x)` — `?.`（optional chaining）の record 形。ref recorder を refOpt に変換する
+ * （以降のプロパティアクセスは中間 null で null を返す — expression-ir.md `refOpt`）。
+ */
+export declare function opt(x: unknown): Recorded;
+/**
+ * catalogComponents — consumer の Catalog から、authoring 本体で呼べる leaf コンポーネント
+ * 関数群を作る（C2: consumer が供給するのはこの Catalog だけ）。
+ *
+ * 各関数は `Component({ port: <expr | literal> })` の呼び出しを componentRef ノードとして
+ * record し、ノード結果の recorder（後続配線・`.map`・Output 参照に使える）を返す。
+ * Port は catalog の Port schema に対して build-time 検証される（未知 Port / required 欠落は
+ * fail-closed）。`portableToIR: false` のエントリは可搬 IR に載らないため拒否する。
+ */
+export declare function catalogComponents<C extends Catalog>(catalog: C): {
+    [K in keyof C]: (ports: Record<string, unknown>) => Recorded;
+};
+/**
+ * when — Conditional（`?:`）/ Guard（`&&`）の record 形（semantic-contract-programming.md
+ * 「構造化制御構文」の Compiler 規則を評価モードで実装する）:
+ *
+ *   - 両分岐（else 省略時は then のみ）が**純式のみ** → Expression IR `{cond:[c,t,e]}` へ
+ *     inline lower（body ノードは増えない。else 省略は `null`）。
+ *   - 分岐に **Component 宣言を含む** → 分岐ごとに gate（CondNode + null-binding skip）を
+ *     立て、両分岐が値を持つ場合は Φ（CondNode）ノードで合流する（採用側のみ実行される）。
+ *     Guard 形（else 無し）は then の値をそのまま返す — 条件不成立時は当該ノードが Skip され、
+ *     下流へは未生成 Port の Skip 伝播規則で連鎖する。
+ *   - `.map` コールバック内では **per-element guard**（v2 `map.when`）として record される
+ *     （guard 形のみ。false の要素は handler 未呼び出しで結果から除外）。
+ *
+ * 条件は recorder 式でなければならない（ネイティブ `===` / `&&` の結果は record できない —
+ * eq/and/... builder を使う）。
+ */
+export declare function when(condition: unknown, then: () => unknown, otherwise?: () => unknown): Recorded;
+export interface CompileBehaviorsOptions {
+    /** 生成 IR の exprVersion（既定: SPEC_VERSIONS.expression）。 */
+    exprVersion?: number;
+    /** plan の concurrency（既定 16）。 */
+    concurrency?: number;
+    /**
+     * Input Port schema の上書き（メソッド名 → Port 名 → schema）。ビルド時評価は `$` の
+     * アクセスから Port **名**を導出するが、TS の型（`In<...>`）はランタイムに残らないため、
+     * 型文字列を IR に載せたい consumer はここで供給する（型抽出ツールの接続点）。
+     */
+    inputPorts?: Record<string, Record<string, PortSchema>>;
+}
+/**
+ * compileBehaviors — `SemanticBehavior` 継承（または `@behavior` 付き）クラスを
+ * component-graph IR（scp-ir-architecture.md §5）へ lower する共有 Compiler。
+ *
+ * - **各 public メソッド = 1 root Behavior**（`components[]` の 1 エントリ。名前 = メソッド名）。
+ *   `#`-private はランタイム不可視でそもそも列挙されない。TS の `private` 修飾子は型消去で
+ *   ランタイムに残らないため、**評価ベースのヘルパ規約は `#` または `_`-prefix**（`_` 始まりは
+ *   publish されない）。ヘルパはメソッド本体からの呼び出しで record にインライン展開される。
+ * - 評価の**前に**メソッド / ヘルパ / クラスソースを {@link scanNativeControlSyntax} で走査し、
+ *   評価では観測できないネイティブ制御構文（`?:` / `&&` / `||` / `??` / `?.` / `!` /
+ *   `==`/`===`/`!=`/`!==` / `if` / `switch` / 複合論理代入）を `NATIVE_CONTROL_SYNTAX` で
+ *   fail-closed に拒否する（bc#24 audit fix — 残余はヘッダ docstring 参照）。
+ * - メソッド本体は throwing-sentinel recorder で 1 回評価され、`$` 参照・component 呼び出し・
+ *   structured control（{@link when} / `.map`）が body ノード・Wire・plan に lower される。
+ * - 生成 IR は `assertPortableComponentGraph` を必ず通してから返す（fail-closed の自己検査）。
+ *   実行は既存の `runBehavior` がそのまま担う。
+ *
+ * effect（Query/Command）はここでは一切扱わない — {@link classifyBehaviorEffect} を参照。
+ */
+export declare function compileBehaviors(cls: BehaviorClass, opts?: CompileBehaviorsOptions): ComponentGraphIR;
+/**
+ * referencedComponents — lowering 済み合成コンポーネントの body が参照する catalog 名
+ * （componentRef / map。重複除去・出現順）。
+ */
+export declare function referencedComponents(component: Component): string[];
+export type BehaviorEffect = "read-only" | "writing";
+/**
+ * classifyBehaviorEffect — CQRS の Query/Command 分類を **component graph から導出**する
+ * consumer 向けヘルパ。authoring は effect 非依存（Query/Command の語彙を持たない）であり、
+ * 分類は「body が consumer の write-catalog（`PutItem`/`Insert`/… — consumer が指定）を
+ * 参照するか」という graph の性質にすぎない、という責務分離（bc#24 / litedbmodel v2 §2.4）の
+ * 実装点。
+ */
+export declare function classifyBehaviorEffect(component: Component, writeComponents: Iterable<string>): BehaviorEffect;
+//# sourceMappingURL=authoring.d.ts.map

package/dist/authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"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"}