@pylonts/dsl 1.1.12 → 1.1.14

package/dist/convert.d.ts

@@ -1,14 +1,12 @@
-import type { SchemaBase } from './dsl.js';
+import type { CollectionSchemaBase, SchemaBase } from './dsl.js';
 import type { DtoMessage } from './dto.js';
 import type { TableSchema } from './db.js';
 import type { EntitySchema } from './entity.js';
-import type { ThirdMethodSchema } from './third-service.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
-/** A source/target collection of a convert — dto, entity, table or
- *  third-party message. Entity sources may carry aggregate fields
- *  (aggField), e.g. an aggregate result entity projected into a wire
- *  message. */
-export type ConvertSourceSchema = DtoMessage | TableSchema | ThirdMethodSchema | EntitySchema;
+/** A source/target collection of a convert — dto, entity or table. Entity
+ *  sources may carry aggregate fields (aggField), e.g. an aggregate result
+ *  entity projected into a wire message. */
+export type ConvertSourceSchema = DtoMessage | TableSchema | EntitySchema;
 /** Method input for defineConvert: type/schema/name are set by the builder. */
 export type ConvertMethodDef = Omit<ConvertMethodSchema, 'type' | 'schema' | 'name'>;
 /** One conversion: multiple source collections → single target collection. */
@@ -22,7 +20,7 @@ export interface ConvertMethodSchema extends SchemaBase {
     target: ConvertSourceSchema;
 }
 /** Declares multi-source → single-target schema integrations grouped by source identity. */
-export interface ConvertSchema extends SchemaBase {
+export interface ConvertSchema extends CollectionSchemaBase {
     type: 'convert';
     /** The backend api module this convert belongs to (shared instance from
      *  project.config.ts apis). Storage is convert_schema/{api.name}/{app.name}/

package/dist/curd.js

@@ -33,7 +33,7 @@ export function defineCurd(name, schema) {
             assertColumns(curd, `actionPages.${pageName}`, page.columns);
     }
     if (curd.list.filter !== undefined && curd.list.filter.app !== curd.app) {
-        throw new Error(`curd ${name}: list.filter '${curd.list.filter.name}' is bound to app '${curd.list.filter.app.name}' but the curd belongs to app '${curd.app.name}'`);
+        throw new Error(`curd ${name}: list.filter '${curd.list.filter.name}' is bound to ${curd.list.filter.app?.name ?? 'common'} but the curd belongs to app '${curd.app.name}'`);
     }
     assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
     return curd;

package/dist/dao.d.ts

@@ -1,18 +1,21 @@
-import { SchemaBase, Field } from './dsl.js';
+import { CollectionSchemaBase, SchemaBase, Field } from './dsl.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 import { TableSchema } from './db.js';
 import type { EntitySchema } from './entity.js';
 import type { FilterSchema } from './filter.js';
 import type { SetExpr } from './expr.js';
-/** A data-access layer bound to exactly one frontend app. */
-export interface DaoSchema extends SchemaBase {
+/** A data-access layer bound to one frontend app, or to the api-level common
+ *  domain layer (app unset — shared across modules). */
+export interface DaoSchema extends CollectionSchemaBase {
     type: 'dao';
     /** The backend api module this DAO belongs to (shared instance from
      *  project.config.ts apis). DAOs are always backend-side, so storage is
-     *  dao_schema/{api.name}/{app.name}/dao/. */
+     *  dao_schema/{api.name}/{app.name}/dao/ — app unset = the api-level common
+     *  domain layer, stored at dao_schema/{api.name}/common/dao/. */
     api: ProjectApiSchema;
-    /** The frontend app this DAO belongs to (shared instance from project.config). */
-    app: FrontAppSchema;
+    /** The frontend app this DAO belongs to (shared instance from project.config).
+     *  Unset = api-level common domain DAO shared by all modules of the api. */
+    app?: FrontAppSchema;
     /** The table this DAO operates on (single-table atomicity). */
     table: TableSchema;
     /** Methods keyed by name — the map key is written back as the method name. */
@@ -29,7 +32,7 @@ export declare function tenantFkOf(dao: DaoSchema): Field | undefined;
 export declare function defineDao(options: {
     name: string;
     api: ProjectApiSchema;
-    app: FrontAppSchema;
+    app?: FrontAppSchema;
     table: TableSchema;
     methods: Record<string, DaoMethodDef>;
     description?: string;

package/dist/dao.js

@@ -1,16 +1,18 @@
+import { isAggregate } from './dsl.js';
 /** The tenant column of the dao table when the app declares a tenant.
  *  Deterministic name derivation: `{tenant.phrase}_{tenant.pk}` (e.g. shop
  *  with pk id → `shop_id`) — checked directly against the table columns,
  *  no FK traversal. Tables without that column are global tables (valid:
  *  system config tables carry no tenant id). Exported for generator/linter. */
 export function tenantFkOf(dao) {
-    const tenant = dao.app.tenant;
-    if (!tenant)
+    const app = dao.app;
+    const tenant = app?.tenant;
+    if (!tenant || !app)
         return undefined;
     const pk = tenant.primaryKey;
     const phrase = tenant.phrase;
     if (!pk || Array.isArray(pk) || !phrase) {
-        throw new Error(`app '${dao.app.name}' tenant table '${tenant.name}' must declare a single-column primaryKey and a phrase (tenant column name = {phrase}_{pk})`);
+        throw new Error(`app '${app.name}' tenant table '${tenant.name}' must declare a single-column primaryKey and a phrase (tenant column name = {phrase}_{pk})`);
     }
     return dao.table.columns[`${phrase.name}_${pk.name}`];
 }
@@ -51,6 +53,10 @@ function validateValueExpr(dao, expr, params, methodName) {
 function validateUpdateSet(dao, methodName, m) {
     const argCols = new Set(m.args.columns.map((c) => c.name));
     const version = versionOf(dao);
+    // Where criteria columns are locators carried by args, not direct assignments —
+    // expression-setting the same column is the conditional-update idiom
+    // (WHERE state = row.state, SET state = ?).
+    const whereCols = new Set((m.where?.conditions ?? []).map((c) => c.field.name));
     for (const setExpr of m.set ?? []) {
         if (version && setExpr.col === version) {
             throw new Error(`dao ${dao.name}.${methodName}: set must not touch version column '${version.name}' — the optimistic lock manages it`);
@@ -58,7 +64,7 @@ function validateUpdateSet(dao, methodName, m) {
         if (!Object.values(dao.table.columns).includes(setExpr.col)) {
             throw new Error(`dao ${dao.name}.${methodName}: set column '${setExpr.col.name}' is not a column of table ${dao.table.name}`);
         }
-        if (argCols.has(setExpr.col.name)) {
+        if (argCols.has(setExpr.col.name) && !whereCols.has(setExpr.col.name)) {
             throw new Error(`dao ${dao.name}.${methodName}: set column '${setExpr.col.name}' also appears in args '${m.args.name}' — a column is either directly assigned or expression-set, never both`);
         }
         validateValueExpr(dao, setExpr.expr, new Set(), methodName);
@@ -152,7 +158,7 @@ function validateAggregateResults(dao, methodName, m) {
         throw new Error(`dao ${dao.name}.${methodName}: aggregate has no results`);
     }
     for (const c of columns) {
-        if (c.type === 'aggregate') {
+        if (isAggregate(c)) {
             if (c.expr.field)
                 assertColumnReachable(dao, methodName, c.expr.field);
         }
@@ -250,7 +256,7 @@ function validateRowCarriedColumns(dao, methodName, method) {
     }
 }
 export function defineDao(options) {
-    if (!options.api.apps.includes(options.app)) {
+    if (options.app && !options.api.apps.includes(options.app)) {
         throw new Error(`dao ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
     }
     const schema = {
@@ -265,7 +271,14 @@ export function defineDao(options) {
     for (const key of Object.keys(options.methods)) {
         const method = options.methods[key];
         for (const ref of [method.args, 'where' in method ? method.where : undefined]) {
-            if (isFilterSchema(ref) && (ref.api !== options.api || ref.app !== options.app)) {
+            if (isFilterSchema(ref) && ref.api !== options.api) {
+                throw new Error(`dao ${options.name}: method '${key}' references filter '${ref.name}' bound to ${ref.api.name}/${ref.app?.name ?? 'common'} but the dao is bound to ${options.api.name}/${options.app?.name ?? 'common'}`);
+            }
+            // app-bound dao may use common or same-app filters; common dao may only use common filters.
+            if (isFilterSchema(ref) && ref.api === options.api && !options.app && ref.app) {
+                throw new Error(`dao ${options.name}: method '${key}' references app-bound filter '${ref.name}' (${ref.app.name}) but the dao is api-level common`);
+            }
+            if (isFilterSchema(ref) && ref.api === options.api && options.app && ref.app && ref.app !== options.app) {
                 throw new Error(`dao ${options.name}: method '${key}' references filter '${ref.name}' bound to ${ref.api.name}/${ref.app.name} but the dao is bound to ${options.api.name}/${options.app.name}`);
             }
         }

package/dist/dsl.d.ts

@@ -118,13 +118,30 @@ interface ObjectField extends BaseField {
  *  so that aggregate result entities can carry it like any other column.
  *  jsType follows the aggregate precision rule: count → number;
  *  sum/avg over an integer column → number, anything else → string. */
-interface AggregateField extends BaseField {
+export interface AggregateField extends BaseField {
     type: 'aggregate';
     jsType: 'number' | 'string';
     /** The aggregate expression producing this column. */
     expr: ComputeExpr;
 }
+/** Whether the field is an aggregate result column — narrows to AggregateField. */
+export declare function isAggregate(field: Field): field is AggregateField;
 export type Field = StringField | TextField | IntField | BigintField | DecimalField | RateField | BooleanField | DateField | TimeField | DateTimeField | EnumField | JsonField | ArrayField | ObjectField | AggregateField;
+/** TS type of a field in generated code (row interfaces, dao params, filter
+ *  args): enum → its JS name, date/datetime → string (transported as ISO
+ *  strings), everything else → jsType. Aggregate fields carry their precision
+ *  rule in jsType already. The single source for this mapping — renderers
+ *  must not branch on field.type for a TS type string. */
+export declare function fieldJsType(field: Field): string;
+/** Enum JS names referenced by a field, recursing into array/object
+ *  containers (wire-format nesting). First-occurrence order — callers that
+ *  need uniqueness collect into a Set. */
+export declare function collectEnumRefs(field: Field, out?: string[]): string[];
+/** Depth-first walk over a field's container structure: visit is called for
+ *  every field including containers (top-level, array items, object
+ *  properties). `key` is the object property name the field sits under
+ *  (undefined for the top-level field and for array items). */
+export declare function walkContainer(field: Field, visit: (f: Field, key?: string) => void, key?: string): void;
 type FieldExtras<T extends Field> = Omit<T, 'name' | 'type' | 'jsType'>;
 export declare function stringField(extra?: FieldExtras<StringField>): StringField;
 export declare function textField(extra?: FieldExtras<TextField>): TextField;

package/dist/dsl.js

@@ -10,6 +10,46 @@ export function rateScale(unit) {
 export function defineEnum(jsName, valueType, values) {
     return { jsName, valueType, values };
 }
+/** Whether the field is an aggregate result column — narrows to AggregateField. */
+export function isAggregate(field) {
+    return field.type === 'aggregate';
+}
+/** TS type of a field in generated code (row interfaces, dao params, filter
+ *  args): enum → its JS name, date/datetime → string (transported as ISO
+ *  strings), everything else → jsType. Aggregate fields carry their precision
+ *  rule in jsType already. The single source for this mapping — renderers
+ *  must not branch on field.type for a TS type string. */
+export function fieldJsType(field) {
+    if (field.type === 'enum')
+        return field.enum.jsName;
+    if (field.type === 'date' || field.type === 'datetime')
+        return 'string';
+    return field.jsType;
+}
+/** Enum JS names referenced by a field, recursing into array/object
+ *  containers (wire-format nesting). First-occurrence order — callers that
+ *  need uniqueness collect into a Set. */
+export function collectEnumRefs(field, out = []) {
+    walkContainer(field, (leaf) => {
+        if (leaf.type === 'enum')
+            out.push(leaf.enum.jsName);
+    });
+    return out;
+}
+/** Depth-first walk over a field's container structure: visit is called for
+ *  every field including containers (top-level, array items, object
+ *  properties). `key` is the object property name the field sits under
+ *  (undefined for the top-level field and for array items). */
+export function walkContainer(field, visit, key) {
+    visit(field, key);
+    if (field.type === 'array') {
+        walkContainer(field.items, visit);
+    }
+    else if (field.type === 'object') {
+        for (const [k, child] of Object.entries(field.properties))
+            walkContainer(child, visit, k);
+    }
+}
 export function stringField(extra = {}) {
     return { name: '', type: 'string', jsType: 'string', ...extra };
 }

package/dist/dto.d.ts

@@ -2,7 +2,6 @@ import { BaseField, CollectionSchemaBase, Field, Operator, SchemaBase } from './
 import { TableSchema } from './db.js';
 import type { EntitySchema } from './entity.js';
 import type { ImportBase } from './import-base.js';
-import type { ThirdMethodSchema } from './third-service.js';
 /** Re-export — Operator lives on the DSL level (see dsl.ts). */
 export type { Operator } from './dsl.js';
 /** Re-export — ImportBase lives on its own module (see import-base.ts). */
@@ -48,6 +47,8 @@ export declare class DtoField implements SchemaBase {
     operator?: Operator;
     /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
     default?: unknown;
+    /** Optional reference to another DtoField — this field reuses the referenced field's type/constraints */
+    ref?: DtoField;
     constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef);
     setPattern(value: string): this;
     setDescription(value: string): this;
@@ -57,6 +58,8 @@ export declare class DtoField implements SchemaBase {
     setOptional(value: boolean): this;
     /** Set a default value — emitted as a TypeBox schema default annotation */
     setDefault(value: unknown): this;
+    /** Reference another DtoField — this field reuses the referenced field's type/constraints */
+    setRef(value: DtoField): this;
     /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
     setOperator(value: Operator): this;
     /** optional 优先于 field.optional */
@@ -90,7 +93,11 @@ export declare class DtoMessage implements CollectionSchemaBase {
     /** 引用已存在的 TypeBox base schema，例如 include({ from: '@pylonts/core', name: 'PageRequest' }) */
     include(...refs: ImportRef[]): this;
 }
-export declare function dtoField(field: Field): DtoField;
+export declare function dtoField(field: Field | DtoArrayFieldDef | DtoObjectFieldDef): DtoField;
+/** Structural check — DtoMessage instances may come from a different module copy, so instanceof is unreliable. */
+export declare function isDtoMessage(v: unknown): v is DtoMessage;
+/** Structural check — a DtoField wraps a Field in a .field property and has no .type of its own. */
+export declare function isDtoField(v: unknown): v is DtoField;
 export declare function dtoArrayField(def: {
     items: DtoField | DtoMessage;
 } & Omit<BaseField, 'name'>): DtoArrayField;
@@ -101,9 +108,11 @@ export declare function buildInput(name: string, fields: Record<string, DtoField
 export declare function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
 export declare function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
 export declare function buildPk(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
-/** Field-collection source a DTO can project from: a DB table, a third-party
- *  method message, or an entity (which may carry aggregate fields). */
-export type DtoFieldSource = TableSchema | ThirdMethodSchema | EntitySchema;
-/** Project fields from a field-collection source (table, third-party method
- *  message or entity) and wrap them as DTO fields (aligned with dto.from). */
-export declare function from(source: DtoFieldSource, fields: Field[]): Record<string, DtoField>;
+/** Field-collection source a DTO can project from: a DB table, another DTO
+ *  message (protocol fields keep their names), or an entity (which may carry
+ *  aggregate fields). */
+export type DtoFieldSource = TableSchema | DtoMessage | EntitySchema;
+/** Project fields from a field-collection source (table, DTO message or
+ *  entity) and wrap them as DTO fields (aligned with dto.from). Shared Field
+ *  instances keep their original identity — the projection references them. */
+export declare function from(source: DtoFieldSource, fields: (Field | DtoArrayFieldDef | DtoObjectFieldDef)[]): Record<string, DtoField>;

package/dist/dto.js

@@ -1,3 +1,4 @@
+import { walkContainer } from './dsl.js';
 import { toCamelCase } from '@pylonts/core';
 export class DtoField {
     /** DTO 语义字段名（接口字段名），与 field.name（数据库列名）含义不同。
@@ -13,6 +14,8 @@ export class DtoField {
     operator;
     /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
     default;
+    /** Optional reference to another DtoField — this field reuses the referenced field's type/constraints */
+    ref;
     constructor(field) {
         this.name = '';
         this.field = field;
@@ -41,6 +44,11 @@ export class DtoField {
         this.default = value;
         return this;
     }
+    /** Reference another DtoField — this field reuses the referenced field's type/constraints */
+    setRef(value) {
+        this.ref = value;
+        return this;
+    }
     /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
     setOperator(value) {
         this.operator = value;
@@ -95,6 +103,18 @@ export class DtoMessage {
 export function dtoField(field) {
     return new DtoField(field);
 }
+/** Structural check — DtoMessage instances may come from a different module copy, so instanceof is unreliable. */
+export function isDtoMessage(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    return v.type === 'dto';
+}
+/** Structural check — a DtoField wraps a Field in a .field property and has no .type of its own. */
+export function isDtoField(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    return 'field' in v && !('type' in v);
+}
 export function dtoArrayField(def) {
     // Items stay as-is: an inline DtoField is rendered inline, a DtoMessage is
     // referenced by name (the driver renders Type.Array(<DtoName>)).
@@ -123,9 +143,54 @@ function buildMessage(name, direction, fields, description) {
             df.field.name = key;
             df.field.schema = message;
         }
+        writeBackNested(df, message);
     }
     return message;
 }
+/** Write back name/schema on nested DTO fields (array items, object
+ *  properties) — both plain-Field containers (objectField/arrayField) and
+ *  DtoField containers (dtoObjectField/dtoArrayField). DtoMessage item
+ *  references are skipped — they carry their own identity. */
+function writeBackNested(df, message) {
+    const f = df.field;
+    if (f.type === 'array') {
+        const items = f.items;
+        if (isDtoMessage(items))
+            return;
+        if (isDtoField(items)) {
+            writeBackNested(items, message);
+            return;
+        }
+        walkContainer(items, writeBackLeaf(message));
+        return;
+    }
+    if (f.type === 'object') {
+        for (const [key, child] of Object.entries(f.properties)) {
+            if (isDtoField(child)) {
+                child.name = key;
+                child.schema = message;
+                if (child.field.schema === undefined) {
+                    child.field.name = key;
+                    child.field.schema = message;
+                }
+                writeBackNested(child, message);
+            }
+            else {
+                writeBackLeaf(message)(child, key);
+            }
+        }
+    }
+}
+/** Name/schema write-back for a plain Field (own fields only — shared
+ *  instances keep their original identity). */
+function writeBackLeaf(message) {
+    return (f, key) => {
+        if (key !== undefined && f.schema === undefined) {
+            f.name = key;
+            f.schema = message;
+        }
+    };
+}
 export function buildInput(name, fields, description) {
     const message = buildMessage(name, DtoDirection.Input, fields, description);
     // Rule A — set optionality from the DB column rule (skips fields the author
@@ -164,28 +229,25 @@ export function buildPk(name, fields, description) {
     }
     return message;
 }
-// Type guard instead of a plain discriminant check: TableSchema.type is declared
-// as a class property, so TS widens it to string and cannot narrow the union.
-function isThirdMethod(source) {
-    return source.type === 'thirdMethod';
-}
 function ownsField(source, field) {
-    if (isThirdMethod(source))
-        return Object.values(source.fields).includes(field);
-    return Object.values(source.columns).includes(field);
+    if (isDtoMessage(source)) {
+        return Object.values(source.fields).some((df) => df.field === field);
+    }
+    return Object.values(source.columns).some((c) => c === field);
 }
-/** Project fields from a field-collection source (table, third-party method
- *  message or entity) and wrap them as DTO fields (aligned with dto.from). */
+/** Project fields from a field-collection source (table, DTO message or
+ *  entity) and wrap them as DTO fields (aligned with dto.from). Shared Field
+ *  instances keep their original identity — the projection references them. */
 export function from(source, fields) {
     const out = {};
     for (const field of fields) {
         if (!ownsField(source, field)) {
-            throw new Error(`dto.from(${source.name}): field ${field.name} does not belong to this ${source.type}`);
+            throw new Error(`dto.from(${source.name}): field ${field.name} does not belong to this ${isDtoMessage(source) ? 'dto' : source.type}`);
         }
         // DB columns map to camelCase interface names (mer_id → merId); aggregate
-        // field names are already camel and pass through; wire-format names are
+        // field names are already camel and pass through; DTO message fields are
         // protocol names themselves and stay untouched.
-        out[isThirdMethod(source) ? field.name : toCamelCase(field.name)] = dtoField(field);
+        out[isDtoMessage(source) ? field.name : toCamelCase(field.name)] = dtoField(field);
     }
     return out;
 }

package/dist/entity.d.ts

@@ -13,8 +13,9 @@ export interface EntitySchema extends SchemaBase {
     /** The backend api module this entity belongs to (shared instance from
      *  project.config.ts apis). Entities are always backend-side. */
     api: ProjectApiSchema;
-    /** The frontend app this entity belongs to (shared instance from project.config). */
-    app: FrontAppSchema;
+    /** The frontend app this entity belongs to (shared instance from project.config).
+     *  Unset = api-level common domain entity shared by all modules of the api. */
+    app?: FrontAppSchema;
     /** The columns of this row object: main-table columns, external reference
      *  columns, and — for aggregate result entities — aggField columns
      *  (count/sum/avg outputs). */
@@ -23,7 +24,7 @@ export interface EntitySchema extends SchemaBase {
 export declare function defineEntity(options: {
     name: string;
     api: ProjectApiSchema;
-    app: FrontAppSchema;
+    app?: FrontAppSchema;
     columns: Field[];
     description?: string;
 }): EntitySchema;

package/dist/entity.js

@@ -1,5 +1,5 @@
 export function defineEntity(options) {
-    if (!options.api.apps.includes(options.app)) {
+    if (options.app && !options.api.apps.includes(options.app)) {
         throw new Error(`entity ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
     }
     return {

package/dist/filter.d.ts

@@ -21,10 +21,12 @@ export interface FilterSchema extends SchemaBase {
     type: 'filter';
     /** The backend api module this filter belongs to (shared instance from
      *  project.config.ts apis). Filters are backend-side, so storage is
-     *  filter_schema/{api.name}/{app.name}/filter/. */
+     *  filter_schema/{api.name}/{app.name}/filter/ — app unset = the api-level
+     *  common domain layer, stored at filter_schema/{api.name}/common/filter/. */
     api: ProjectApiSchema;
-    /** The frontend app this filter belongs to (shared instance from project.config). */
-    app: FrontAppSchema;
+    /** The frontend app this filter belongs to (shared instance from project.config).
+     *  Unset = api-level common domain filter shared by all modules of the api. */
+    app?: FrontAppSchema;
     /** AND-combined conditions (may be empty when keyword is present). */
     conditions: FilterCondition[];
     /** Fuzzy keyword search: one input value matched against multiple columns
@@ -36,7 +38,7 @@ export interface FilterSchema extends SchemaBase {
 export declare function defineFilter(options: {
     name: string;
     api: ProjectApiSchema;
-    app: FrontAppSchema;
+    app?: FrontAppSchema;
     conditions?: FilterCondition[];
     keyword?: {
         columns: Field[];

package/dist/filter.js

@@ -1,5 +1,5 @@
 export function defineFilter(options) {
-    if (!options.api.apps.includes(options.app)) {
+    if (options.app && !options.api.apps.includes(options.app)) {
         throw new Error(`filter ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
     }
     const conditions = options.conditions ?? [];

package/dist/flow-script.js

@@ -9,7 +9,7 @@
 // The IR stays the single executable model (mermaid, must-analysis, throws
 // coverage, service contracts all consume it); this layer is a lowering, not
 // a parallel model.
-import { defineFlow, defineSlots, edge, guard, ifNode, isCall, isEnd, isFlowNode, isGuard, isIfNode, methodOf, node, tryNode, } from './flow.js';
+import { defineFlow, defineSlots, edge, guard, ifNode, isCall, isEnd, isFlowNode, isFlowSlot, isGuard, isIfNode, methodOf, node, tryNode, } from './flow.js';
 /** Call a method as a statement or (in IF position) as a utils predicate. */
 export function invoke(method, args, result) {
     return { kind: 'invoke', method, args, result };
@@ -133,7 +133,7 @@ function addUsed(ctx, slot) {
 }
 function addConditionUsed(ctx, c) {
     if (!isCall(c)) {
-        addUsed(ctx, c.field.slot);
+        addUsed(ctx, isFlowSlot(c.field) ? c.field : c.field.slot);
         return;
     }
     for (const t of c.args ?? [])
@@ -175,6 +175,9 @@ function methodThrows(m) {
  *  label when THROW carries no message). */
 function renderCondition(c) {
     if (!isCall(c)) {
+        if (isFlowSlot(c.field)) {
+            return c.op === 'isNull' ? `${c.field.name} is null` : `${c.field.name} is not null`;
+        }
         const field = c.field.field;
         const ref = `${c.field.slot.name}.${field.name}`;
         switch (c.op) {
@@ -473,6 +476,9 @@ function rewriteSlots(nodes, edges, slots, entrySlots) {
     };
     const cond = (c) => {
         if (!isCall(c)) {
+            if (isFlowSlot(c.field)) {
+                return { kind: 'comparison', op: c.op, field: map(c.field), value: c.value };
+            }
             return { kind: 'comparison', op: c.op, field: { slot: map(c.field.slot), field: c.field.field }, value: c.value };
         }
         return { method: c.method, args: c.args?.map(map), result: c.result ? map(c.result) : undefined };

package/dist/flow.d.ts

@@ -9,7 +9,9 @@ import type { ServiceMethodSchema } from './service.js';
 import type { ThirdServiceMethodSchema } from './third-service.js';
 import type { UtilsMethodSchema } from './utils.js';
 /** A method a flow step can invoke: contract references, or a pure descriptor
- *  (MethodSchema) for the period before the contract file exists. */
+ *  (MethodSchema) for the period before the contract file exists.
+ *  Third-party methods are their own contract (ThirdServiceMethodSchema) —
+ *  they can never bind a flow. */
 export type FlowMethodRef = MethodSchema | ConvertMethodSchema | DaoMethodSchema | ServiceMethodSchema | ThirdServiceMethodSchema | UtilsMethodSchema;
 /** One named data slot of a flow — a register holding a whole object (like a
  *  compiler's register file). The built-in args slot carries the flow input
@@ -85,7 +87,9 @@ export type CompareOp = 'lt' | 'le' | 'gt' | 'ge' | 'eq' | 'ne' | 'isNull' | 'is
 export interface Comparison {
     kind: 'comparison';
     op: CompareOp;
-    field: SlotFieldRef;
+    /** Field-level comparisons bind a slot field; slot-level null checks
+     *  (isNull/isNotNull on the slot itself) bind the slot directly. */
+    field: SlotFieldRef | FlowSlot;
     /** Compared-against value; null checks take none. */
     value?: string | number | EnumValue;
 }
@@ -93,6 +97,10 @@ export interface Comparison {
  *  (optional): a utils predicate call (its boolean result decides) or a field
  *  comparison. */
 export type GuardCondition = FlowCall | Comparison;
+/** True when the condition operand is the slot itself (slot-level null check),
+ *  not a field access on it. Slot metadata (name) lives on the proxy target and
+ *  reads without field interception; a field access resolves to { slot, field }. */
+export declare function isFlowSlot(v: unknown): v is FlowSlot;
 export declare function lt(field: unknown, value: string | number): Comparison;
 export declare function le(field: unknown, value: string | number): Comparison;
 export declare function gt(field: unknown, value: string | number): Comparison;