@githolon/dsl 0.102.2 → 0.102.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.102.2",
+  "version": "0.102.3",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_dart_application.ts

@@ -31,6 +31,7 @@ import {
 } from "./framework/framework_aggregates.js";
 import { isBusinessIntent } from "./intent.js";
 import { contractTypeName } from "./contract.js";
+import { admitsNull } from "./null_meta.js";
 import type {
   WorkspaceSharingPolicy,
   WorkspaceSharingReceipt,
@@ -1051,7 +1052,10 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           ? sourceFieldMember.slice(0, -2)
           : `${sourceFieldMember}Ref`;
         const method = member(stem);
-        const memberNullable = field.isFromBirth !== true;
+        const memberNullable = admitsNull(field) || field.isFromBirth !== true;
+        const sourceFieldValue = admitsNull(field)
+          ? `record.${sourceFieldMember}.valueOrNull`
+          : `record.${sourceFieldMember}`;
         const isSameDomain = sameDomainRefs.some(([name]) => name === fieldName);
         const isCrossDomain = crossDomainRefs.some(([name]) => name === fieldName);
         if (!isSameDomain && !isCrossDomain) continue;
@@ -1064,7 +1068,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
             `  Future<${targetModel}?> ${method}(${sourceModel} record) async {`,
             ...(memberNullable
               ? [
-                  `    final id = record.${sourceFieldMember};`,
+                  `    final id = ${sourceFieldValue};`,
                   `    if (id == null) return null;`,
                   `    final rows = await _client.${targetById}(NmsInternalNomosRefs.id(id));`,
                 ]
@@ -1095,7 +1099,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  Future<${targetModel}?> ${method}(${sourceModel} record) async {`,
           ...(memberNullable
             ? [
-                `    final id = record.${sourceFieldMember};`,
+                `    final id = ${sourceFieldValue};`,
                 `    if (id == null) return null;`,
                 `    final application = await ${opener}(`,
                 `      _client.bridge,`,
@@ -1107,7 +1111,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
                 `    );`,
               ]
             : [
-                `    final id = record.${sourceFieldMember};`,
+                `    final id = ${sourceFieldValue};`,
                 `    final application = await ${opener}(`,
                 `      _client.bridge,`,
                 `      id,`,
@@ -1126,7 +1130,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  Future<${targetApplication}?> ${applicationMethod}(${sourceModel} record) {`,
           ...(memberNullable
             ? [
-                `    final id = record.${sourceFieldMember};`,
+                `    final id = ${sourceFieldValue};`,
                 `    if (id == null) return Future<${targetApplication}?>.value(null);`,
                 `    return ${opener}(`,
                 `      _client.bridge,`,
@@ -1151,12 +1155,15 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         ? contractTypeName(foreign.targetAggregateId)
         : concreteClassName(foreign.targetAggregateId);
       const fieldMember = member(fieldName);
+      const fieldValue = admitsNull(field)
+        ? `record.${fieldMember}.valueOrNull`
+        : `record.${fieldMember}`;
       const stem = fieldMember.endsWith("Id") ? fieldMember.slice(0, -2) : fieldMember;
       const method = member(`${stem}Of`);
       addCollectionMember(aggregate.id, method, [
         `  /// Follow [record]'s ${fieldName} to its typed business record.`,
         `  Future<${target}?> ${method}(${sourceModel} record) async {`,
-        `    final reference = record.${fieldMember};`,
+        `    final reference = ${fieldValue};`,
         `    if (reference == null) return null;`,
         `    final target = await NmsInternalForeignRefs.resolve(reference, _client.bridge.foreignReader());`,
         `    if (target == null) return null;`,
@@ -1179,7 +1186,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         addCollectionMember(aggregate.id, applicationMethod, [
           `  /// Open the business application containing [record]'s ${fieldName}.`,
           `  Future<${targetApplication}?> ${applicationMethod}(${sourceModel} record) {`,
-          `    final reference = record.${fieldMember};`,
+          `    final reference = ${fieldValue};`,
           `    if (reference == null) return Future<${targetApplication}?>.value(null);`,
           `    return ${opener}(`,
           `      _client.bridge,`,

package/src/codegen_dart_client.ts

@@ -62,6 +62,7 @@ import { buildNomosDescribeModel, type NomosDescribeModel } from "./describe_mod
 import { assertModelClientMemberAvailable } from "./generated_client_names.js";
 import { ownedRecordActionDirectiveId } from "./framework/owned_custody.js";
 import { contractTypeName } from "./contract.js";
+import { admitsNull } from "./null_meta.js";
 
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
 const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
@@ -1268,14 +1269,15 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       // the DSL schema's `.optional()` — a partial fold decodes every scalar `null` when absent
       // (`emitReadModel`'s own doc: "PARTIAL folds"), so the member is nullable UNLESS the field is
       // `.fromBirth()` (birth-presence law — the ONE case the projection types non-null).
-      const memberNullable = f.isFromBirth !== true;
+      const memberNullable = admitsNull(f) || f.isFromBirth !== true;
+      const memberValue = admitsNull(f) ? `${member}.valueOrNull` : member;
       lines.push(
         `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType}) by dispatching to`,
         `  /// [${className}.${byIdMethod}] — the existing by-id read lane, never a second one.`,
         `  Future<${targetModel}?> ${method}(${className} client) async {`,
         ...(memberNullable
           ? [
-              `    final id = ${member};`,
+              `    final id = ${memberValue};`,
               `    if (id == null) return null;`,
               `    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(id));`,
             ]
@@ -1301,7 +1303,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       const member = dartMemberName(fieldName);
       const methodStem = member.length > 2 && member.endsWith("Id") ? member.slice(0, -2) : `${member}Ref`;
       const method = safeMethod(methodStem);
-      const memberNullable = f.isFromBirth !== true;
+      const memberNullable = admitsNull(f) || f.isFromBirth !== true;
+      const memberValue = admitsNull(f) ? `${member}.valueOrNull` : member;
       lines.push(
         `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType}, a CROSS-DOMAIN ref) by`,
         `  /// dispatching to [${targetClient}.${byIdMethod}] on the target domain's client — same by-id`,
@@ -1310,7 +1313,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `  Future<${targetModel}?> ${method}(${targetClient} client) async {`,
         ...(memberNullable
           ? [
-              `    final id = ${member};`,
+              `    final id = ${memberValue};`,
               `    if (id == null) return null;`,
               `    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(id));`,
             ]
@@ -1341,6 +1344,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       }
       const targetConcrete = concreteClassName(targetType);
       const member = dartMemberName(fieldName);
+      const memberValue = admitsNull(f) ? `${member}.valueOrNull` : member;
       // The stored locator member is a typed `ForeignRef<Target>?` getter, so the resolver takes a
       // `remote…` name to avoid colliding with it (and to read as "the far side of the reference").
       const method = safeMethod(`remote${cap(camel(member))}`);
@@ -1350,7 +1354,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `  /// implementation opens the foreign workspace on demand; tenant code sees only this business method.`,
         `  /// Null locator (absent / empty id or workspace) ⇒ null.`,
         `  Future<${targetConcrete}?> ${method}(NomosEngine engine, {String? cloud}) {`,
-        `    final ref = ${member};`,
+        `    final ref = ${memberValue};`,
         `    if (ref == null) return Future<${targetConcrete}?>.value(null);`,
         `    return NmsInternalForeignRefs.resolve(ref, engine.foreignReader(cloud: cloud));`,
         `  }`,

package/src/law_check.ts

@@ -729,7 +729,7 @@ function dottedQueryKeyFindings(mod: DomainModule, aggById: ReadonlyMap<string,
 // admits before a null is lawful (t.optional / t.clearable / t.nullable / t.json({null})). These
 // twins pre-fire the three refusals the gate would raise: (a) a payload field that ADMITS null with
 // no null-admitting receiver; (b) a null-admitting field used where a null is structurally illegal
-// (authority gate, identity ref, spatial index, read key); (c) a plan op writing literal null into a
+// (authority gate, spatial index, read key); (c) a plan op writing literal null into a
 // field that never declared null a meaning. All PAYLOAD-INDEPENDENT (pure declarations) ⇒ REFUSE.
 
 /** The verbatim null-semantics guidance (`null_semantics.md`) — the `fix` on twin N-a/N-c. */
@@ -843,7 +843,10 @@ function nullBanFindings(mod: DomainModule, aggById: ReadonlyMap<string, Aggrega
     });
   };
 
-  // Facet gates (authority/standing) + identity refs — a null in these breaks the very thing they decide.
+  // Facet gates (authority/standing) — a null in these breaks the very thing they decide. A plain
+  // typed ref is an association, not structural identity: clearing `asset.spaceId`, for example,
+  // means the asset is no longer in a space. If a ref participates in a query/group/spatial key the
+  // corresponding structural check below still refuses it.
   for (const agg of mod.aggregates) {
     for (const [name, f0] of Object.entries(agg.fields)) {
       const f = f0 as Field;
@@ -851,9 +854,6 @@ function nullBanFindings(mod: DomainModule, aggById: ReadonlyMap<string, Aggrega
       if (f.facet === "authority" || f.facet === "standing") {
         ban(agg.id, name, "an authority/standing gate", "drop the null semantic — an authority sink must always resolve to a subject.");
       }
-      if (f.kind === "ref") {
-        ban(agg.id, name, "an identity reference", "an identity ref must always point somewhere — model absence with a separate presence flag, not a null ref.");
-      }
     }
   }
   // Read keys / group-bys / spatial indexes — a null key row is a silent dead index.