graphddb 0.7.8 → 0.7.10

package/dist/{registry-pAnFcc62.d.ts → registry-LWE54Sdc.d.ts}

@@ -1,4 +1,4 @@
-import { m as EntityMetadata } from './maintenance-view-adapter-BCbgKG5d.js';
+import { m as EntityMetadata } from './maintenance-view-adapter-BAZ9uBGe.js';
 
 interface LintRule {
     id: string;

package/dist/{relation-depth-C9t4s9bt.d.ts → relation-depth-BRS513Tq.d.ts}

@@ -1,4 +1,4 @@
-import { b as Linter, L as LintRule } from './registry-pAnFcc62.js';
+import { b as Linter, L as LintRule } from './registry-LWE54Sdc.js';
 
 /**
  * Creates a Linter pre-loaded with rules safe for Entity registration.

package/dist/spec/index.d.ts

@@ -1,4 +1,5 @@
-export { a1 as BridgeBundle, a4 as CommandContractMethodSpec, a5 as CommandResolutionTarget, H as CommandSpec, a6 as CompiledFragment, a7 as CompiledMutationPlan, a8 as ComposeSpec, a9 as CompositionPlanSpec, a2 as ConditionSpec, J as ContextSpec, aa as ContractCardinality, ab as ContractCommandResult, ac as ContractInputArity, ad as ContractKeySpec, ae as ContractKind, af as ContractResolution, A as ContractSpec, ag as DerivedConditionCheck, ah as DerivedEdgeWrite, ai as DerivedIdempotencyGuard, aj as DerivedMaintainOutbox, ak as DerivedMaintainWrite, al as DerivedOutboxEvent, am as DerivedUniqueGuard, an as DerivedUpdate, ao as EntityRefResolver, ap as ExecutionPlanSpec, aq as FilterSpec, ar as MAX_TRANSACT_COMPOSE_ITEMS, a0 as Manifest, as as ManifestEntity, at as ManifestField, au as ManifestFieldType, av as ManifestGsi, aw as ManifestKey, ax as ManifestRelation, ay as ManifestTable, az as OperationSpec, _ as OperationsDocument, L as ParamSpec, aA as QueryContractMethodSpec, G as QuerySpec, aB as RangeConditionSpec, aC as ReadOperationType, K as SPEC_VERSION, aD as TransactionItemSpec, aE as TransactionItemType, I as TransactionSpec, aF as WhenSpec, aG as WriteOperationType, aH as assertNoCrossFragmentMaintainCollision, aI as compileFragment, aJ as compileMutationPlan, aK as compileSingleFragmentPlan, aL as resetMaintenanceGraphCache, aM as resolveLifecycle, aN as resolveMaintainers } from '../maintenance-view-adapter-BCbgKG5d.js';
-export { A as AnyModelContract, B as BuiltContracts, C as ContextOwnership, b as ContextOwnershipMap, c as ContractBoundaryViolation, d as ContractInputs, e as ContractMap, f as ContractN1Violation, O as PREPARED_FORMAT_VERSION, Q as PreparedBindMap, g as PreparedBindSpec, a as PreparedPlanDocument, h as PreparedPlanSpec, i as PreparedReadRouteSpec, P as PreparedWriteOpSpec, s as assertBundleSerializable, t as assertContractBoundaries, u as assertContractN1Safe, v as assertJsonSerializable, w as assertSupportedCondition, x as buildBridgeBundle, y as buildContexts, z as buildContracts, D as buildManifest, E as buildOperations, R as buildPreparedPlanDocument, F as buildQuerySpec, G as buildTransactionSpec, H as buildTransactions, S as canonicalJson, I as collectContractBoundaryViolations, J as collectContractN1Violations, U as compilePreparedPlan, V as entityFingerprint, X as planFingerprint } from '../index-Deugy2sa.js';
-import '../registry-pAnFcc62.js';
+export { L as CompiledFragment, N as CompiledMutationPlan, O as DerivedConditionCheck, X as DerivedEdgeWrite, Y as DerivedIdempotencyGuard, Z as DerivedMaintainOutbox, _ as DerivedMaintainWrite, $ as DerivedOutboxEvent, a0 as DerivedUniqueGuard, a1 as DerivedUpdate, a2 as EntityRefResolver, a3 as MAX_TRANSACT_COMPOSE_ITEMS, a4 as assertNoCrossFragmentMaintainCollision, a5 as compileFragment, a6 as compileMutationPlan, a7 as compileSingleFragmentPlan, a8 as resetMaintenanceGraphCache, a9 as resolveLifecycle, aa as resolveMaintainers } from '../maintenance-view-adapter-BAZ9uBGe.js';
+export { A as AnyModelContract, B as BuiltContracts, C as ContextOwnership, b as ContextOwnershipMap, c as ContractBoundaryViolation, d as ContractInputs, e as ContractMap, f as ContractN1Violation, X as PREPARED_FORMAT_VERSION, Y as PreparedBindMap, g as PreparedBindSpec, a as PreparedPlanDocument, h as PreparedPlanSpec, i as PreparedReadRouteSpec, P as PreparedWriteOpSpec, t as assertBundleSerializable, u as assertContractBoundaries, v as assertContractN1Safe, w as assertJsonSerializable, x as assertSupportedCondition, y as buildBridgeBundle, z as buildContexts, D as buildContracts, E as buildManifest, F as buildOperations, Z as buildPreparedPlanDocument, G as buildQuerySpec, H as buildTransactionSpec, I as buildTransactions, _ as canonicalJson, J as canonicalizeExpressionSpec, K as collectContractBoundaryViolations, L as collectContractN1Violations, $ as compilePreparedPlan, a0 as entityFingerprint, R as operationsContainScpNodes, U as operationsSpecVersion, a1 as planFingerprint } from '../index-Dc7d8mWI.js';
+import '../registry-LWE54Sdc.js';
+export { B as BridgeBundle, f as CommandContractMethodSpec, g as CommandResolutionTarget, a as CommandSpec, h as ComposeSpec, i as CompositionPlanSpec, d as ConditionSpec, b as ContextSpec, j as ContractCardinality, k as ContractCommandResult, l as ContractInputArity, m as ContractKeySpec, n as ContractKind, o as ContractResolution, C as ContractSpec, p as EXPR_VERSION, q as ExecutionPlanSpec, r as ExpressionArrNode, s as ExpressionFloatNode, t as ExpressionIntNode, u as ExpressionNode, v as ExpressionObjNode, w as ExpressionOpNode, x as ExpressionOperator, y as ExpressionRefNode, z as ExpressionRefOptNode, A as ExpressionScalar, E as ExpressionSpec, F as FilterSpec, M as Manifest, D as ManifestEntity, G as ManifestField, H as ManifestFieldType, I as ManifestGsi, J as ManifestKey, K as ManifestRelation, L as ManifestTable, N as OperationSpec, O as OperationsDocument, P as ParamSpec, R as QueryContractMethodSpec, Q as QuerySpec, U as RangeConditionSpec, V as ReadOperationType, S as SPEC_VERSION, W as SPEC_VERSION_SCP, X as SPEC_VERSION_SUPPORTED, e as SpecVersion, Y as TransactionItemSpec, Z as TransactionItemType, T as TransactionSpec, _ as WhenSpec, $ as WriteOperationType } from '../types-BQLzTEqh.js';
 import '@aws-sdk/client-dynamodb';

package/dist/spec/index.js

@@ -1,7 +1,6 @@
 import {
   MAX_TRANSACT_COMPOSE_ITEMS,
   PREPARED_FORMAT_VERSION,
-  SPEC_VERSION,
   assertBundleSerializable,
   assertContractBoundaries,
   assertContractN1Safe,
@@ -29,13 +28,26 @@ import {
   resetMaintenanceGraphCache,
   resolveLifecycle,
   resolveMaintainers
-} from "../chunk-NZRCBEWS.js";
-import "../chunk-HFFIB77D.js";
+} from "../chunk-EOJDN3SA.js";
+import "../chunk-DFUKGU2Q.js";
+import {
+  EXPR_VERSION,
+  SPEC_VERSION,
+  SPEC_VERSION_SCP,
+  SPEC_VERSION_SUPPORTED,
+  canonicalizeExpressionSpec,
+  operationsContainScpNodes,
+  operationsSpecVersion
+} from "../chunk-3UD3XIF2.js";
+import "../chunk-3ZU2VW3L.js";
 import "../chunk-PDUVTYC5.js";
 export {
+  EXPR_VERSION,
   MAX_TRANSACT_COMPOSE_ITEMS,
   PREPARED_FORMAT_VERSION,
   SPEC_VERSION,
+  SPEC_VERSION_SCP,
+  SPEC_VERSION_SUPPORTED,
   assertBundleSerializable,
   assertContractBoundaries,
   assertContractN1Safe,
@@ -52,6 +64,7 @@ export {
   buildTransactionSpec,
   buildTransactions,
   canonicalJson,
+  canonicalizeExpressionSpec,
   collectContractBoundaryViolations,
   collectContractN1Violations,
   compileFragment,
@@ -59,6 +72,8 @@ export {
   compilePreparedPlan,
   compileSingleFragmentPlan,
   entityFingerprint,
+  operationsContainScpNodes,
+  operationsSpecVersion,
   planFingerprint,
   resetMaintenanceGraphCache,
   resolveLifecycle,

package/dist/testing/index.d.ts

@@ -1,5 +1,6 @@
-import { n as Executor, D as DynamoDBOperation, o as ReadExecOptions, p as ExecutorResult, q as BatchGetExecInput, P as PutInput, W as WriteExecOptions, r as WriteResult, s as UpdateInput, t as DeleteInput, u as BatchWriteExecItem, v as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, w as DDBModel, c as ChangeEvent } from '../maintenance-view-adapter-BCbgKG5d.js';
+import { n as Executor, D as DynamoDBOperation, o as ReadExecOptions, p as ExecutorResult, q as BatchGetExecInput, P as PutInput, W as WriteExecOptions, r as WriteResult, s as UpdateInput, t as DeleteInput, u as BatchWriteExecItem, v as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, w as DDBModel, c as ChangeEvent } from '../maintenance-view-adapter-BAZ9uBGe.js';
 import '@aws-sdk/client-dynamodb';
+import '../types-BQLzTEqh.js';
 
 /**
  * In-process physical store backing the GraphDDB Memory Test Adapter

package/dist/testing/index.js

@@ -1,11 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-IA6MW2HP.js";
+} from "../chunk-AD6ZQTTE.js";
+import "../chunk-DFUKGU2Q.js";
 import {
   ClientManager,
   MetadataRegistry,
   resolveModelClass
-} from "../chunk-HFFIB77D.js";
+} from "../chunk-3ZU2VW3L.js";
 import {
   TableMapping
 } from "../chunk-PDUVTYC5.js";

package/dist/transform/index.d.ts

@@ -1,3 +1,6 @@
+import ts from 'typescript';
+import { E as ExpressionSpec } from '../types-BQLzTEqh.js';
+
 /**
  * Compile-time hoist transform + no-runtime-capture build lint for
  * `DDBModel.prepare` (issue #206, design #203 — phase 2 on top of the phase-1
@@ -213,4 +216,460 @@ interface PreparedAotOptions {
  */
 declare function transformPreparedSourceAot(fileName: string, sourceText: string, options: PreparedAotOptions): PreparedAotFileResult;
 
-export { AOT_LOADER_LOCAL, AOT_PLANS_LOCAL, AOT_SHIM_EXPORT, HOIST_SLOT_PREFIX, type PreparedAotFileResult, type PreparedAotOptions, type PreparedAotSite, type PreparedDiagnostic, type PreparedDiagnosticCode, type PreparedTransformOptions, type PreparedTransformResult, lintPreparedSource, transformPreparedSource, transformPreparedSourceAot };
+/**
+ * SCP expression lowerer + Portability Guard (issue #262, Phase 3 S2;
+ * behavior-contracts `expression-ir.md` §3).
+ *
+ * Lowers a TypeScript expression AST node to the closed Expression IR v1
+ * vocabulary shipped by #261 (`src/spec/expression.ts` /
+ * `ExpressionSpec` in `src/spec/types.ts`). The authoring surface is TS; the
+ * compiler analyzes the AST and lowers it to the §3 closed table:
+ *
+ *   literal / ref・refOpt / coalesce (`??`) / cond (`?:` in expression
+ *   position) / add・sub・mul・div・mod・neg / concat (string `+`, template
+ *   literals) / eq (`===`)・ne (`!==`)・lt・le・gt・ge / and (`&&`)・or
+ *   (`||`)・not (`!`) in expression position / obj・arr literals / len
+ *   (`.length` on arrays).
+ *
+ * ## Portability Guard — whitelist, never blacklist
+ *
+ * The pass dispatches on a **whitelist** of syntax kinds (the same lint
+ * discipline as `prepared-transform.ts`): anything outside the table is a
+ * compile error with the precise source position (`file:line:col`) and the
+ * offending construct's name — loose equality (`==` / `!=`), truthiness
+ * coercion, function calls (`Math.*`, methods, user functions), `new`,
+ * `Date`, bitwise operators, `typeof`, `instanceof`, assignment, `++`/`--`,
+ * regex literals, element access, spread, closures, `this`, tagged templates,
+ * optional chaining beyond `refOpt` property semantics, and template
+ * substitutions with non-string parts. Nothing unknown ever reaches the IR.
+ *
+ * ## Monomorphic typing (expression-ir.md §5; issue R7 design decision)
+ *
+ * The IR is monomorphic: TS's overloaded `+` is resolved **statically** to
+ * `add` (numeric) vs `concat` (string) via the `TypeChecker`; implicit
+ * `toString` (string + number) is a compile error, as is any operand whose
+ * static type is `any` / `unknown` / an unresolvable union (the guard never
+ * guesses). Numeric literals classify by their **token text**: a decimal
+ * point or exponent (`1.5`, `1e3`) means float, otherwise int (`1`, `0xff`);
+ * `1.0` lowers to the canonical `{float: 1}` wrapper, and an integer literal
+ * beyond ±2^53−1 lowers exactly from its token text to `{int:"…"}`.
+ *
+ * **R7 (int/float vs DynamoDB N / `@number`)**: TS (and graphddb's `@number`
+ * schema type, which surfaces DynamoDB's `N`) has a single `number` type that
+ * does not distinguish int from float. A `number`-typed reference therefore
+ * classifies as the numeric kind **`num`** (int-or-float, decided by the
+ * runtime value per §5 "DB 由来の値は列型が int/float を決める"): it may
+ * combine with either a known-int or a known-float operand, while a
+ * **statically provable** int×float mix (`1 + 1.5`) is a compile error. A
+ * kind mismatch that only the runtime value can reveal surfaces as a loud
+ * evaluation **Failure** in the S5/S6 evaluators (monomorphic operand
+ * checks), never as silent wrongness — exactly the R7 posture (mistakes are
+ * compile/runtime friction, not corrupted data). Authors force the float
+ * interpretation with an explicit float literal (`1.0`).
+ *
+ * Nullability is tracked from the checker: a possibly-null(/undefined)
+ * operand is only accepted where the IR gives it meaning — as the left side
+ * of `??`, compared against the `null` literal (`x === null`), as a `?.`
+ * chain result, or as an `obj`/`arr` construction value. Anywhere else it is
+ * a compile error (`refOpt` / `coalesce` are the escape hatches).
+ *
+ * ## References — the unified Input Port model (issue #264, Phase 3 S4)
+ *
+ * `$.field` — a property chain rooted at the **Input Port binding** — lowers
+ * to `{ref:["input","field"]}` and a `.map`/fan-out element chain to
+ * `{ref:["item","field"]}`. The scope names `input` / `item` are FIXED,
+ * mirroring the `{param}` / `{item.<field>}` template scopes the runtimes
+ * already render (behavior-contracts `runtime-boundary.md` §4.1 /
+ * `template-rendering.md`): one reference model behind three authoring
+ * proxies (`defineTransaction`'s `p.*`, `mutation`'s `$.*`,
+ * `prepare`'s `$.*` — see `src/define/transaction.ts` 「Input Port 統一」).
+ *
+ * **Symbol-based root resolution (S2/S3 audit hard requirement)**: a root
+ * identifier is recognized as an input/item root by its **`ts.Symbol`
+ * identity** — the checker-resolved binding must be the exact declaration
+ * the caller registered (`inputRootSymbols` / `itemRootSymbols`), never by
+ * identifier text. A local binding shadowing `$`/`p` (block-scoped `const`,
+ * a nested arrow parameter, an `import { $ } …`) resolves to its own symbol
+ * and is loud-rejected as a non-input root — a shadow can never be silently
+ * lowered as an input reference.
+ *
+ * **Declared-input gate (#264 AC / the #243 lesson)**: when the caller
+ * provides the declared Input Port surface (`inputFields` / `itemFields`,
+ * derived from the `param.*` descriptors — `src/define/param.ts`), a
+ * reference to an UNDECLARED field is a positioned compile error — an
+ * unbound reference must never leak to runtime.
+ *
+ * A chain containing `?.` lowers to `{refOpt:[…]}` (null-propagating over
+ * the whole path — the table's `a?.b` row), and every plain `.` link
+ * requires a checker-proven **non-null receiver** (§3: `a.b.c` 型上
+ * non-null — a possibly-null intermediate is a positioned compile error
+ * here, not a runtime NULL_REF). Any other identifier root is a loud
+ * compile error.
+ *
+ * `xs.length` lowers to `{len:[xs]}` **only when the checker proves the
+ * receiver is an array**; `.length` on a string is rejected (§8: v1 excludes
+ * string length — TS/Rust/Python unit mismatch), and on a plain object type
+ * it is an ordinary `ref` path segment.
+ *
+ * ## Guarantees
+ *
+ * Every produced expression is round-tripped through the S1 validator /
+ * canonicalizer (`canonicalizeExpressionSpec`) before being returned, so an
+ * emitted node is **by construction** in canonical §2.3/§2.4 form and inside
+ * the closed vocabulary (and satisfies behavior-contracts `assertPortable` —
+ * it is built from JSON scalars, arrays, and plain objects only).
+ *
+ * Zero runtime evaluation lives here (S5/S6/S7); this module is build-time
+ * only (`graphddb/transform` — it imports the `typescript` optional
+ * dependency, never the runtime entry, and no runtime module imports it).
+ */
+
+/** Diagnostic codes emitted by the expression lowerer / Portability Guard. */
+type ExpressionLowerDiagnosticCode = 
+/** A construct outside the expression-ir.md §3 closed set (whitelist miss). */
+'scp-closed-set'
+/** A monomorphic-typing violation (§5): kind mismatch, truthiness,
+ * possibly-null operand, or an unresolvable (`any` / `unknown`) type. */
+ | 'scp-type'
+/** An unlowerable reference: the root does not resolve (by SYMBOL identity)
+ * to the Input Port / fan-out element binding — including a shadowed
+ * placeholder — or it names an undeclared input field (issue #264). */
+ | 'scp-ref'
+/** The expression text does not parse (text entry point only). */
+ | 'scp-syntax';
+/** One lowering diagnostic, positioned in the original source. */
+interface ExpressionLowerDiagnostic {
+    readonly code: ExpressionLowerDiagnosticCode;
+    readonly category: 'error';
+    /** Human message; always names the offending construct. */
+    readonly message: string;
+    /** The offending construct's name (`'=='`, `'function call'`, …). */
+    readonly construct: string;
+    readonly file: string;
+    /** 1-based line in the source text. */
+    readonly line: number;
+    /** 1-based column in the source text. */
+    readonly column: number;
+}
+/** `file:line:col` + construct + message — the canonical one-line rendering
+ * (position info and the offending construct's name are always present). */
+declare function formatExpressionLowerDiagnostic(d: ExpressionLowerDiagnostic): string;
+/** Result of lowering one TS expression. */
+interface ExpressionLowerResult {
+    /** The canonical `{ exprVersion: 1, expr }` envelope — present iff
+     * `errorCount === 0` (already validated by the S1 canonicalizer). */
+    readonly expression?: ExpressionSpec;
+    readonly diagnostics: readonly ExpressionLowerDiagnostic[];
+    readonly errorCount: number;
+}
+/** Thrown by {@link lowerExpressionTextOrThrow} on any guard violation. */
+declare class ExpressionLowerError extends Error {
+    readonly diagnostics: readonly ExpressionLowerDiagnostic[];
+    constructor(diagnostics: readonly ExpressionLowerDiagnostic[]);
+}
+interface LowerTsExpressionOptions {
+    /** The program's type checker (monomorphic `+` resolution, `.length`
+     * disambiguation, truthiness/nullability checks are type-driven — and,
+     * since #264, symbol-based input-root resolution). */
+    readonly checker: ts.TypeChecker;
+    /** The source file containing the expression (position reporting). */
+    readonly sourceFile: ts.SourceFile;
+    /** Reported file name; defaults to `sourceFile.fileName`. */
+    readonly fileName?: string;
+    /**
+     * The `ts.Symbol`(s) of the **Input Port binding** (the `$` / `p`
+     * declaration — e.g. the `defineScpTransaction` callback's params
+     * parameter). A chain whose root identifier RESOLVES to one of these
+     * symbols lowers to the fixed `input` scope (`$.a` → `{ref:["input","a"]}`,
+     * issue #264's model). Matching is by **symbol identity, never identifier
+     * text** (S2/S3 audit requirement): a local binding shadowing the
+     * placeholder resolves to its own symbol and is a loud `scp-ref` error.
+     */
+    readonly inputRootSymbols: ReadonlySet<ts.Symbol>;
+    /**
+     * The `ts.Symbol`(s) of a **fan-out element** binding (issue #263, Phase 3
+     * S3): a chain rooted at one of these lowers to the fixed `item` scope
+     * (`$el.qty` → `{ref:["item","qty"]}`) — the Expression IR spelling of the
+     * existing `{item.<field>}` forEach template reference. Optional; defaults
+     * to empty. Symbol-identity matched, like {@link inputRootSymbols}.
+     */
+    readonly itemRootSymbols?: ReadonlySet<ts.Symbol>;
+    /**
+     * The DECLARED Input Port field names (issue #264: derived from the
+     * transaction's `param.*` descriptors — the single namespace shared with
+     * the serialized `ParamSpec`). When present, an input-root reference whose
+     * first segment is not in the set is a positioned `scp-ref` **compile
+     * error** (#243: never a runtime unbound leak). Absent → the checker type
+     * of the binding is the only gate (an unknown field still fails as an
+     * unresolvable-type error under `strict`, just less precisely).
+     */
+    readonly inputFields?: ReadonlySet<string>;
+    /** The declared fan-out element field names; same gate as
+     * {@link inputFields}, for the `item` scope. */
+    readonly itemFields?: ReadonlySet<string>;
+}
+/**
+ * Lower one TypeScript expression AST node to a canonical
+ * `{ exprVersion: 1, expr }` {@link ExpressionSpec}. Whitelist-dispatched
+ * (Portability Guard): any construct outside the expression-ir.md §3 closed
+ * set yields an error diagnostic carrying the source position and the
+ * construct's name, and no expression is returned. A returned expression has
+ * already passed the S1 validator/canonicalizer.
+ */
+declare function lowerTsExpression(expr: ts.Expression, options: LowerTsExpressionOptions): ExpressionLowerResult;
+/**
+ * A declared-input descriptor as the authoring surface provides it (issue
+ * #264: the `param.*` placeholder / `ParamDescriptor` shape of
+ * `src/define/param.ts` — every `param.string()` / `param.number()` /
+ * `param.literal(…)` / `param.array({…})` value matches structurally). The
+ * lowerer derives the Input Port TYPING from it — `param.number()` → the R7
+ * `num` kind (`ParamKind` carries no int/float distinction, exactly like
+ * DynamoDB `N` / `@number`), `param.literal(…)` → the literal-union kinds,
+ * `param.array({…})` → `arr` (so `.length` lowers to `len`) — and the
+ * declared-field set for the undeclared-reference compile gate.
+ */
+interface InputParamDescriptor {
+    readonly kind: 'string' | 'number' | 'literal' | 'array';
+    /** For `literal` params, the allowed values. */
+    readonly literals?: readonly (string | number)[];
+    /** For `array` params, the per-element field descriptors. */
+    readonly element?: Readonly<Record<string, InputParamDescriptor>>;
+}
+/** The TypeScript type text an {@link InputParamDescriptor} types its input
+ * field with (the same texts the S3 structural pass derives from a statically
+ * read `param.*` map — one typing rule for both entries). */
+declare function inputParamTypeText(d: InputParamDescriptor): string;
+interface LowerExpressionTextOptions {
+    /** Declared input fields: name → TypeScript type text (e.g. `{ qty:
+     * 'number', tag: 'string | null', items: 'string[]' }`). These type the
+     * input proxy for monomorphic resolution. */
+    readonly inputs?: Readonly<Record<string, string>>;
+    /**
+     * Declared input fields as `param.*` DESCRIPTORS (issue #264): name →
+     * placeholder, e.g. `{ qty: param.number(), status: param.literal('a','b'),
+     * items: param.array({ id: param.string() }) }`. The Input Port typing is
+     * derived per {@link inputParamTypeText}; a field present in both `params`
+     * and `inputs` takes the explicit `inputs` type text (the escape hatch for
+     * nullable / structured types the descriptor vocabulary cannot spell).
+     */
+    readonly params?: Readonly<Record<string, InputParamDescriptor>>;
+    /** The input-proxy identifier; defaults to `'$'`. */
+    readonly inputName?: string;
+    /**
+     * Declared **fan-out element** fields (issue #263, Phase 3 S3): name →
+     * TypeScript type text, typing the element proxy of a `.map` body. When
+     * present, references rooted at {@link itemName} lower to the fixed `item`
+     * scope (`$el.qty` → `{ref:["item","qty"]}`). Absent → plain S2 behavior.
+     */
+    readonly itemInputs?: Readonly<Record<string, string>>;
+    /** The element-proxy identifier (only meaningful with {@link itemInputs});
+     * defaults to `'$el'`. */
+    readonly itemName?: string;
+    /** Reported file name for diagnostics; defaults to `'scp-expression.ts'`. */
+    readonly fileName?: string;
+}
+/**
+ * Convenience / opt-in CLI entry: lower a TypeScript expression given as
+ * TEXT, typing the input proxy from `options.inputs`. Builds a minimal
+ * in-memory `ts.Program` (with the standard lib, so `string` / array types
+ * resolve) and delegates to {@link lowerTsExpression}. Diagnostic positions
+ * are `file:line:col` within the synthesized module (the input declaration
+ * comes first; the expression text follows on its own lines).
+ */
+declare function lowerExpressionText(exprText: string, options?: LowerExpressionTextOptions): ExpressionLowerResult;
+/** {@link lowerExpressionText}, throwing {@link ExpressionLowerError} (with
+ * every `file:line:col`-positioned, construct-named diagnostic) on violation. */
+declare function lowerExpressionTextOrThrow(exprText: string, options?: LowerExpressionTextOptions): ExpressionSpec;
+
+/**
+ * SCP structural lowering — Guard / Conditional (Φ) / `.map` onto the existing
+ * guard + forEach seams (issue #263, Phase 3 S3; behavior-contracts
+ * `semantic-contract-programming.md` 「構造化制御構文」/「Map」/「Conditional と Φ」,
+ * `scp-graphddb-consistency.md` §4.1).
+ *
+ * ## Structure-vs-expression dispatch
+ *
+ * SCP introduces no dedicated vocabulary for control structure: TS native
+ * syntax is lowered, and the compiler dispatches **deterministically** on
+ * Component presence — a branch / body that contains a Component (here: a
+ * `tx.*` write declaration) is a STRUCTURED construct and lowers to a
+ * gate/Map node (here: the existing `guard` slot / `forEach` binding); a pure
+ * expression lowers to Expression IR via the S2 lowerer (#262). The dispatch
+ * runs **before** the S2 lowerer ever sees a node, so a Component-bearing
+ * branch can never leak into Expression IR — and any shape that is neither a
+ * recognizable structural form nor a pure expression is a **positioned loud
+ * reject** (never a silent path):
+ *
+ *  - **Guard** — `cond && tx.put(Model, {…})` as a body statement → ONE item
+ *    carrying `guard: <cond lowered by S2>`. Guard-false = item skip = the
+ *    same semantics as the legacy `when`-false, converging on the scp-error.md
+ *    Skip rules (未生成 Port の伝播); the legacy `WhenSpec` is untouched
+ *    (issue R2: string-compare `when` vs typed guard semantics are never
+ *    mixed — `guard` is a separate node).
+ *  - **Conditional (Φ)** — `cond ? tx.put(A, {…}) : tx.put(B, {…})` as a body
+ *    statement → TWO items, `guard: cond` and `guard: {not:[cond]}`. Both
+ *    branches exist statically (SSA Φ: the DAG carries both; the guard picks
+ *    the executed side). Mixed shapes (one branch not a write, `: null`,
+ *    ternary chains) are loud rejects in v1 — write the guard form or two
+ *    explicit guarded items.
+ *  - **Map** — `p.items.map(($el) => tx.put(Model, {…}))` as a body statement
+ *    → the EXISTING `tx.forEach` recorder call over the declared array param.
+ *    `$el.<field>` element references flow through the untouched recorder →
+ *    `{item.<field>}` templates, and inside a lowered guard condition they
+ *    lower to `{ref:["item","<field>"]}` (the S2 `itemRoots` scope). The
+ *    serialized spec is **byte-identical** to the hand-written `tx.forEach`
+ *    form, so the five language runtimes (which already expand `forEach`)
+ *    need zero changes.
+ *  - **Guard-in-guard** (`a && (b && tx.put(…))`), guarded conditionals, and
+ *    nested `.map` fan-out are **loud rejects in v1** (decided in issue #263:
+ *    `&&`-composition of the conditions — `(a && b) && tx.put(…)` — is
+ *    equivalent and keeps the seam single-level; note the left-associative
+ *    parse of `a && b && tx.put(…)` IS that composed form).
+ *
+ * ## The authoring surface (design decision, issue #263 scope item)
+ *
+ * Native operators cannot be intercepted by the `defineTransaction` recorder
+ * (a Proxy sees property reads and coercions, not `&&` / `?:` / control
+ * flow — coercing a sentinel is exactly what its ledger loud-rejects). So the
+ * native-syntax body form is a **new, opt-in, source-transformed** entry —
+ * `defineScpTransaction(params, (tx, p) => { … })` (`src/define/transaction.ts`)
+ * — whose `p` proxy is **value-typed** (`p.qty: number`, `p.items: {…}[]`), so
+ * the native form typechecks as ordinary TS. This pass rewrites its body
+ * statements onto the untouched recorder vocabulary (`guard:` options,
+ * `tx.forEach`); at runtime `defineScpTransaction` simply delegates to
+ * `defineTransaction`, so:
+ *
+ *  - the TRANSFORMED output is ordinary recorder authoring (nothing about
+ *    `defineTransaction` changes, and the pass is idempotent);
+ *  - the pass **stamps every call it compiles** with the lowered-body marker
+ *    (`SCP_LOWERED_MARKER`, a third argument), and `defineScpTransaction`
+ *    THROWS at definition time when the marker is absent. This is the
+ *    mechanical no-silent-path closure: the recorder's coercion ledger never
+ *    fires on `===` / `!==` (no coercion) or bare truthiness (ToBoolean has
+ *    no Proxy trap), and its consumed-field check is token-level — a param
+ *    consumed by a native condition is masked whenever the same field ALSO
+ *    surfaces faithfully in another item — so without the marker an
+ *    untransformed body could silently record a dropped or unguarded item.
+ *    With it, an untransformed `defineScpTransaction` never records
+ *    anything; the ledger / differential / consumed-field checks remain as
+ *    defense-in-depth behind the marker.
+ *
+ * Like `transformPreparedSource` (#206), this is a source-to-source pass and
+ * a file with ANY violation is returned unrewritten (fail loudly, never emit
+ * a half-transformed file). Unlike #206 it needs the S2 **type-directed**
+ * lowerer for conditions; the condition types come from the statically read
+ * `param.*` declarations of the `defineScpTransaction` params map (the single
+ * source of truth for the tx's input surface), so the pass still never loads
+ * user modules.
+ *
+ * ## Symbol-based root verification (issue #264; S2/S3 audit requirement)
+ *
+ * A condition is lowered by SLICING its text into a synthesized module whose
+ * `declare const p / $el` bindings carry the descriptor-derived types — a
+ * re-synthesis that maps identifiers by NAME. To make that sound on real
+ * authoring files, the pass binds the file with a single-file `ts.Program`
+ * (binder only — `noResolve`/`noLib`, still no user-module loading) and
+ * verifies, BEFORE slicing, that every identifier whose text matches the
+ * params / element binding name actually RESOLVES (by `ts.Symbol` identity)
+ * to the `defineScpTransaction` callback's parameter declaration. A local
+ * binding shadowing `p`/the element (a nested callback parameter, an import
+ * of the same name) resolves to its own symbol and is a positioned loud
+ * reject — never silently re-typed as an input reference. The `.map` /
+ * `tx.forEach` source receiver (`p.<arrayParam>`) is symbol-verified the
+ * same way, and a fan-out element parameter named like `tx` / `p` is
+ * rejected outright (the re-synthesis namespace is name-keyed, so the
+ * collision itself is the error). The recorder (`tx`) probes stay textual:
+ * a false positive there is always a loud reject, never a silent lowering.
+ *
+ * ## Known boundaries (documented, intentional)
+ *
+ * - **`.map` is gated stricter than the recorder**: the receiver must be a
+ *   declared `param.array` (`p.<name>`), so a `.map` over a non-param literal
+ *   array rejects at transform time even though an eager evaluation would be
+ *   well-defined. Intentional: only fan-out over a declared array Port is a
+ *   static Map node with structure-guaranteed termination
+ *   (semantic-contract-programming.md Map — 配列 Port 限定), and the gated
+ *   direction keeps every fan-out on the forEach seam the runtimes already
+ *   expand.
+ * - **Φ records BOTH branches' write arguments at record time** (both writes
+ *   exist statically in the DAG — SSA Φ — so the recorder evaluates both
+ *   argument lists when the definition is captured). The Φ *condition* is
+ *   S2-pure by dispatch, but the branch ARGUMENTS are ordinary recorder
+ *   value positions: their soundness rests on the recorder's pre-existing
+ *   differential-pass / coercion-ledger impurity detection, exactly as for
+ *   any other write (an argument expression with side effects or per-pass
+ *   divergence is rejected there, not here).
+ *
+ * Build-time only (`graphddb/transform`): imports the optional `typescript`
+ * dependency; no runtime module imports it (the `SCP_LOWERED_MARKER` import
+ * is a build-time constant read from the define layer, not a reverse edge).
+ */
+
+/**
+ * Diagnostic codes of the structural pass. The S2 expression codes pass
+ * through unchanged (a guard condition that violates the Portability Guard is
+ * reported at its position in the ORIGINAL file); the `scp-structural` /
+ * `scp-nesting` / `scp-map` / `scp-params` codes are the structural dispatch's
+ * own loud rejects.
+ */
+type StructuralLowerDiagnosticCode = ExpressionLowerDiagnosticCode
+/** An undecidable structural shape, or a Component/write inside a pure
+ * expression position (the structure-vs-expression dispatch reject). */
+ | 'scp-structural'
+/** Nested structural constructs — guard-in-guard, a guarded conditional, a
+ * ternary chain (v1 decision: loud reject; compose conditions with `&&`). */
+ | 'scp-nesting'
+/** An unsupported `.map` fan-out shape (receiver not a declared array
+ * param, nested fan-out, unsupported callback shape). */
+ | 'scp-map'
+/** The params map / callback is not statically readable, so a condition
+ * cannot be typed for the monomorphic S2 lowering (fail-closed). */
+ | 'scp-params';
+/** One structural-lowering diagnostic, positioned in the original source. */
+interface StructuralLowerDiagnostic {
+    readonly code: StructuralLowerDiagnosticCode;
+    readonly category: 'error';
+    readonly message: string;
+    /** The offending construct's name (`'&&'`, `'?:'`, `'.map'`, …). */
+    readonly construct: string;
+    readonly file: string;
+    /** 1-based line in the ORIGINAL source text. */
+    readonly line: number;
+    /** 1-based column in the ORIGINAL source text. */
+    readonly column: number;
+}
+/** Result of {@link transformScpTransactionSource} on one source file. */
+interface ScpTransactionTransformResult {
+    readonly fileName: string;
+    /** The transformed source (identical to the input when nothing changed, in
+     * `check` mode, or when any violation was found). */
+    readonly text: string;
+    readonly changed: boolean;
+    /** Guard statements lowered to a `guard:` option (`cond && write`). */
+    readonly guardCount: number;
+    /** Conditional (Φ) statements expanded to two guarded items. */
+    readonly conditionalCount: number;
+    /** `.map` fan-out statements lowered to `tx.forEach`. */
+    readonly mapCount: number;
+    readonly diagnostics: readonly StructuralLowerDiagnostic[];
+    /** Count of error diagnostics (a build gate: non-zero fails, no rewrite). */
+    readonly errorCount: number;
+}
+interface ScpTransactionTransformOptions {
+    /** `transform` (default) verifies AND rewrites; `check` only verifies (the
+     * build-lint / drift gate) and never changes the text. */
+    readonly mode?: 'transform' | 'check';
+}
+/** `file:line:col — SCP structural lowering error [construct]: message`. */
+declare function formatStructuralLowerDiagnostic(d: StructuralLowerDiagnostic): string;
+/**
+ * Lower every `defineScpTransaction` body in one source file onto the
+ * existing recorder seams (see the module doc for the full dispatch table).
+ * A file carrying ANY violation is returned unrewritten with positioned
+ * diagnostics (fail loudly; never emit a half-transformed file). Idempotent:
+ * the transformed output contains only recorder vocabulary, which the pass
+ * leaves byte-identical.
+ */
+declare function transformScpTransactionSource(fileName: string, sourceText: string, options?: ScpTransactionTransformOptions): ScpTransactionTransformResult;
+
+export { AOT_LOADER_LOCAL, AOT_PLANS_LOCAL, AOT_SHIM_EXPORT, type ExpressionLowerDiagnostic, type ExpressionLowerDiagnosticCode, ExpressionLowerError, type ExpressionLowerResult, HOIST_SLOT_PREFIX, type InputParamDescriptor, type LowerExpressionTextOptions, type LowerTsExpressionOptions, type PreparedAotFileResult, type PreparedAotOptions, type PreparedAotSite, type PreparedDiagnostic, type PreparedDiagnosticCode, type PreparedTransformOptions, type PreparedTransformResult, type ScpTransactionTransformOptions, type ScpTransactionTransformResult, type StructuralLowerDiagnostic, type StructuralLowerDiagnosticCode, formatExpressionLowerDiagnostic, formatStructuralLowerDiagnostic, inputParamTypeText, lintPreparedSource, lowerExpressionText, lowerExpressionTextOrThrow, lowerTsExpression, transformPreparedSource, transformPreparedSourceAot, transformScpTransactionSource };