@githolon/dsl 0.101.6 → 0.102.1

package/src/codegen_dart_scenario.ts

@@ -0,0 +1,299 @@
+import type { DomainModule } from "./codegen_dart.js";
+import { cap } from "./codegen_dart.js";
+import { dartApplicationClassName } from "./codegen_dart_application.js";
+import { synthesizePayload } from "./codegen_proof.js";
+import { isBusinessIntent } from "./intent.js";
+
+const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
+
+export const dartScenarioClassName = (domain: string): string => `${cap(camel(domain))}Scenario`;
+export const dartTestPersonClassName = (domain: string): string => `${cap(camel(domain))}TestPerson`;
+export const dartScenarioGivenClassName = (domain: string): string => `${cap(camel(domain))}ScenarioGiven`;
+
+interface DelegatedScenarioPermission {
+  readonly method: string;
+  readonly domain: string;
+  readonly acceptanceIntent: string;
+  readonly relation: string;
+  readonly subjectField: string;
+  readonly certificateField: string;
+  readonly sampleFacts: Readonly<Record<string, unknown>>;
+  readonly actorFields: readonly string[];
+  readonly timeFields: readonly string[];
+}
+
+function delegatedScenarioPermissions(modules: readonly DomainModule[]): DelegatedScenarioPermission[] {
+  const declarations = modules.flatMap((module) => {
+    const domain = module.domain ?? module.name;
+    return (module.directives ?? []).map((directive) => ({ domain, directive }));
+  });
+  const gated = declarations.filter(
+    ({ directive }) => isBusinessIntent(directive) && directive.requiresRelationGate !== undefined,
+  );
+  const duplicateIds = new Map<string, number>();
+  for (const { directive } of gated) {
+    duplicateIds.set(directive.id, (duplicateIds.get(directive.id) ?? 0) + 1);
+  }
+  const out: DelegatedScenarioPermission[] = [];
+  for (const target of gated) {
+    const relation = target.directive.requiresRelationGate!.relation;
+    const acceptance = declarations.find(
+      ({ directive }) =>
+        isBusinessIntent(directive) &&
+        directive.delegatedRoleGate?.relation === relation,
+    );
+    if (acceptance?.directive.delegatedRoleGate === undefined) continue;
+    const gate = acceptance.directive.delegatedRoleGate;
+    const synthesized = synthesizePayload(
+      acceptance.directive.payloadSchema,
+      `scenario permission ${target.domain}/${target.directive.id}`,
+    );
+    const sample = synthesized.value;
+    const sampleFacts: Record<string, unknown> = { ...sample };
+    delete sampleFacts[gate.subjectField];
+    delete sampleFacts[gate.certField];
+    const actorFields = Object.keys(sampleFacts).filter(
+      (field) => typeof sampleFacts[field] === "string" && /(?:By|Actor|Principal|Subject)$/.test(field),
+    );
+    const timeFields = [
+      ...Object.keys(sampleFacts).filter(
+        (field) => typeof sampleFacts[field] === "string" && /(?:At|Time|Timestamp)$/.test(field),
+      ),
+      ...synthesized.autoStamped,
+    ].filter((field, index, fields) => fields.indexOf(field) === index);
+    for (const field of [...actorFields, ...timeFields]) delete sampleFacts[field];
+    const methodStem = (duplicateIds.get(target.directive.id) ?? 0) > 1
+      ? `${target.domain}_${target.directive.id}`
+      : target.directive.id;
+    out.push({
+      method: `may${cap(camel(methodStem))}`,
+      domain: acceptance.domain,
+      acceptanceIntent: acceptance.directive.id,
+      relation,
+      subjectField: gate.subjectField,
+      certificateField: gate.certField,
+      sampleFacts,
+      actorFields,
+      timeFields,
+    });
+  }
+  return out.sort((left, right) => left.method.localeCompare(right.method));
+}
+
+/** Generate the test environment for one application without exporting the underlying harness. */
+export function generateDartScenario(
+  mod: DomainModule,
+  clientPackage: string,
+  testPackage: string,
+  deployFile: string,
+  options: {
+    readonly surfaceName?: string;
+    readonly applicationFile?: string;
+    readonly applicationModules?: readonly DomainModule[];
+  } = {},
+): string {
+  const domain = options.surfaceName ?? mod.domain ?? mod.name;
+  const application = dartApplicationClassName(domain);
+  const scenario = dartScenarioClassName(domain);
+  const testPerson = dartTestPersonClassName(domain);
+  const scenarioGiven = dartScenarioGivenClassName(domain);
+  const permissions = delegatedScenarioPermissions(options.applicationModules ?? [mod]);
+  const usesJsonFacts = permissions.some(
+    (permission) => Object.keys(permission.sampleFacts).length > 0,
+  );
+  const bind = `nomosInternalBind${application}`;
+  const applicationFile = options.applicationFile ?? `${mod.name}.application`;
+  return [
+    `// AUTO-GENERATED by nomos-compile — business application test environment.`,
+    // This generated package is the deliberate framework-test friend boundary. Tenant production code
+    // receives only the business application barrel; scenarios may drive private harness setup underneath it.
+    `// ignore_for_file: invalid_use_of_internal_member`,
+    ...(usesJsonFacts ? [`import 'dart:convert' show jsonDecode;`] : []),
+    `import 'dart:io';`,
+    ``,
+    `import 'package:flutter/services.dart' show rootBundle;`,
+    `import 'package:flutter/widgets.dart' show WidgetsFlutterBinding;`,
+    `import 'package:${clientPackage}/${clientPackage}.dart' show ${application};`,
+    `import 'package:${clientPackage}/src/generated/${applicationFile}.dart' show ${bind};`,
+    `import 'package:nomos_flutter/src/generated_application_host.dart' show NmsInternalApplicationUserBinding;`,
+    `import 'package:nomos_client/src/home.dart' show nmsInternalReceivingGroupNameOf;`,
+    `import 'package:nomos_client/src/nms_test_environment.dart' show NomosTestCloud, NomosTestHarness;`,
+    ``,
+    `final class ${testPerson} {`,
+    `  static final RegExp _idPattern = RegExp(r'^[A-Za-z0-9][A-Za-z0-9._-]*$');`,
+    `  final String id;`,
+    `  final String _principal;`,
+    ``,
+    `  factory ${testPerson}.named(String id) {`,
+    `    if (id.isEmpty || !_idPattern.hasMatch(id)) {`,
+    `      throw ArgumentError.value(id, "id", "must use only letters, numbers, dots, underscores, or hyphens");`,
+    `    }`,
+    `    return ${testPerson}._(id: id, principal: "user:\$id");`,
+    `  }`,
+    ``,
+    `  ${testPerson}._({required this.id, required String principal}) : _principal = principal;`,
+    `}`,
+    ``,
+    `final class ${scenarioGiven} {`,
+    ...(permissions.length === 0
+      ? [`  const ${scenarioGiven}._();`]
+      : [
+          `  final ${scenario} _scenario;`,
+          `  final ${testPerson} _person;`,
+          `  ${scenarioGiven}._(this._scenario, this._person);`,
+        ]),
+    ...permissions.flatMap((permission) => {
+      const jsonFacts = JSON.stringify(permission.sampleFacts);
+      return [
+        ``,
+        `  /// Establish the real business authority needed to perform this action.`,
+        `  Future<void> ${permission.method}() async {`,
+        `    await _scenario._environment.nomosInternalAllowDelegatedScenarioAction(`,
+        `      domain: ${JSON.stringify(permission.domain)},`,
+        `      acceptanceIntent: ${JSON.stringify(permission.acceptanceIntent)},`,
+        `      relation: ${JSON.stringify(permission.relation)},`,
+        `      subject: _person._principal,`,
+        `      subjectField: ${JSON.stringify(permission.subjectField)},`,
+        `      certificateField: ${JSON.stringify(permission.certificateField)},`,
+        `      facts: <String, Object?>{`,
+        ...(Object.keys(permission.sampleFacts).length === 0
+          ? []
+          : [`        ...Map<String, Object?>.from(jsonDecode(${JSON.stringify(jsonFacts)}) as Map),`]),
+        ...permission.actorFields.map((field) => `        ${JSON.stringify(field)}: _person._principal,`),
+        ...permission.timeFields.map((field) => `        ${JSON.stringify(field)}: '2000-01-01T00:00:00.000Z',`),
+        `      },`,
+        `    );`,
+        `  }`,
+      ];
+    }),
+    `}`,
+    ``,
+    `final class ${scenario} {`,
+    `  final NomosTestHarness _environment;`,
+    `  final String _principal;`,
+    `  final File _packageFile;`,
+    `  ${application} _application;`,
+    `  ${scenario}._(this._environment, this._principal, this._packageFile, this._application);`,
+    ``,
+    `  /// The exact generated application used by production widgets.`,
+    `  ${application} get application => _application;`,
+    ``,
+    `  /// State a typed business precondition for the person currently using this scenario.`,
+    `  ${scenarioGiven} given(${testPerson} person) {`,
+    `    if (person._principal != _principal) {`,
+    `      throw ArgumentError.value(person.id, 'person', 'start a separate scenario to act as another person');`,
+    `    }`,
+    `    return ${permissions.length === 0 ? `const ${scenarioGiven}._()` : `${scenarioGiven}._(this, person)`};`,
+    `  }`,
+    ``,
+    `  /// Start a fresh local application with networking forbidden.`,
+    `  static Future<${scenario}> offline({`,
+    `    ${testPerson}? signedInAs,`,
+    `    void Function(Future<void> Function())? registerTearDown,`,
+    `  }) async {`,
+    `    final person = signedInAs ?? ${testPerson}.named('test');`,
+    `    final packageFile = await _applicationPackage();`,
+    `    final environment = await NomosTestHarness.ephemeral(`,
+    `      deployJsonPaths: [packageFile.path],`,
+    `      ownerSubject: person._principal,`,
+    `      workspace: nmsInternalReceivingGroupNameOf(person._principal),`,
+    `      nodeEntry: Platform.environment['NOMOS_NODE_ENTRY'],`,
+    `      phaseTimeout: const Duration(minutes: 2),`,
+    `      onDiagnostic: Platform.environment['NOMOS_TEST_DIAGNOSTICS'] == '1' ? stderr.writeln : null,`,
+    `    );`,
+    `    final application = await ${bind}(`,
+    `      environment.session(environment.workspace), NmsInternalApplicationUserBinding.fromActor(person._principal),`,
+    `    );`,
+    `    final scenario = ${scenario}._(environment, person._principal, packageFile, application);`,
+    `    registerTearDown?.call(scenario.close);`,
+    `    return scenario;`,
+    `  }`,
+    ``,
+    `  /// Start with real remote custody under an isolated local test cloud.`,
+    `  static Future<${scenario}> connected({`,
+    `    ${testPerson}? signedInAs,`,
+    `    void Function(Future<void> Function())? registerTearDown,`,
+    `  }) async {`,
+    `    final person = signedInAs ?? ${testPerson}.named('test');`,
+    `    final serverEntry = Platform.environment['NOMOS_TEST_CLOUD_ENTRY'];`,
+    `    if (serverEntry == null || serverEntry.isEmpty) {`,
+    `      throw StateError('Connected scenarios require the Nomos test cloud. Run this test through githolon test.');`,
+    `    }`,
+    `    final applicationName = 'test-application-\${DateTime.now().microsecondsSinceEpoch}';`,
+    `    final packageFile = await _applicationPackage();`,
+    `    final cloud = await NomosTestCloud.start(`,
+    `      serverEntry: serverEntry, platform: applicationName, deployJsonPath: packageFile.path,`,
+    `    );`,
+    `    late final NomosTestHarness environment;`,
+    `    try {`,
+    `      environment = await NomosTestHarness.cloudBound(`,
+    `        cloud: cloud, deployJsonPaths: [packageFile.path],`,
+    `        platformWorkspace: applicationName, subject: person._principal,`,
+    `        nodeEntry: Platform.environment['NOMOS_NODE_ENTRY'],`,
+    `        phaseTimeout: const Duration(minutes: 2),`,
+    `      );`,
+    `    } catch (_) {`,
+    `      await cloud.stop();`,
+    `      rethrow;`,
+    `    }`,
+    `    final application = await ${bind}(environment.homeSession, NmsInternalApplicationUserBinding.fromActor(person._principal));`,
+    `    final scenario = ${scenario}._(environment, person._principal, packageFile, application);`,
+    `    registerTearDown?.call(scenario.close);`,
+    `    return scenario;`,
+    `  }`,
+    ``,
+    `  /// Simulate losing connectivity. Local business actions remain available.`,
+    `  void disconnect() => _environment.testCloud?.setOnline(false);`,
+    ``,
+    `  /// Restore connectivity and wait until hidden custody exchange has settled.`,
+    `  Future<void> reconnect() async {`,
+    `    final cloud = _environment.testCloud;`,
+    `    if (cloud == null) return;`,
+    `    cloud.setOnline(true);`,
+    `    await _environment.converge();`,
+    `  }`,
+    ``,
+    `  /// Kill and reopen the application from durable local state, then return the same business API.`,
+    `  Future<${application}> restart() async {`,
+    `    await _environment.restart();`,
+    `    _application = await ${bind}(_environment.homeSession, NmsInternalApplicationUserBinding.fromActor(_principal));`,
+    `    return _application;`,
+    `  }`,
+    ``,
+    `  /// Remove local custody and reinstall entirely from remote history.`,
+    `  Future<${application}> reinstall() async {`,
+    `    await _environment.reinstall();`,
+    `    _application = await ${bind}(_environment.homeSession, NmsInternalApplicationUserBinding.fromActor(_principal));`,
+    `    return _application;`,
+    `  }`,
+    ``,
+    `  Future<void> close() async {`,
+    `    await _environment.dispose();`,
+    `    await _environment.testCloud?.stop();`,
+    `    try { await _packageFile.parent.delete(recursive: true); } catch (_) {}`,
+    `  }`,
+    ``,
+    `  static Future<File> _applicationPackage() async {`,
+    `    WidgetsFlutterBinding.ensureInitialized();`,
+    `    final assetKeys = [`,
+    `      'packages/${testPackage}/lib/src/generated/${deployFile}',`,
+    `      'lib/src/generated/${deployFile}',`,
+    `    ];`,
+    `    Object? lastError;`,
+    `    for (final key in assetKeys) {`,
+    `      try {`,
+    `        final data = await rootBundle.load(key);`,
+    `        final dir = await Directory.systemTemp.createTemp('nms-application-package-');`,
+    `        final file = File('\${dir.path}\${Platform.pathSeparator}${deployFile}');`,
+    `        await file.writeAsBytes(data.buffer.asUint8List(data.offsetInBytes, data.lengthInBytes), flush: true);`,
+    `        return file;`,
+    `      } catch (error) {`,
+    `        lastError = error;`,
+    `      }`,
+    `    }`,
+    `    throw StateError('The generated application package asset is missing: \$lastError');`,
+    `  }`,
+    `}`,
+    ``,
+  ].join("\n");
+}

package/src/codegen_openapi.ts

@@ -40,6 +40,7 @@ import { finishSum } from "./sum.js";
 import { finishExtremum } from "./extremum.js";
 import { nullDocLine } from "./null_meta.js";
 import type { Field } from "./fields.js";
+import { isBusinessIntent } from "./intent.js";
 
 type AnyDirective = Directive<unknown>;
 
@@ -128,7 +129,7 @@ function generateOpenApiSurface(
     const businessBirth = (dir as {
       businessBirth?: { aggregateId: string; publicPayloadSchema: unknown };
     }).businessBirth;
-    const publicId = businessBirth === undefined ? dir.id : "birth";
+    const publicId = businessBirth === undefined || isBusinessIntent(dir) ? dir.id : "birth";
     const publicDir = businessBirth === undefined
       ? dir
       : { ...dir, payloadSchema: businessBirth.publicPayloadSchema } as AnyDirective;
@@ -266,10 +267,12 @@ export function generateOpenApiFragment(
   const isInternal = (value: unknown) =>
     !!value && typeof value === "object"
       && (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
+  const publicDirectiveIds = new Set(module.applicationIntents?.map((intent) => intent.id) ?? []);
+  const publicDirectives = module.applicationIntents ?? module.directives;
   const publicModule: DomainModule = {
     ...module,
     aggregates: module.aggregates.filter((a) => !isInternal(a)),
-    directives: module.directives.filter((d) => !isInternal(d)),
+    directives: publicDirectives.filter((d) => !isInternal(d)),
     ...(module.queries === undefined ? {} : { queries: module.queries.filter((q) => !isInternal(q)) }),
   };
   const publicDoc = generateOpenApiSurface(publicModule, opts);
@@ -286,7 +289,9 @@ export function generateOpenApiFragment(
   const frameworkModule: DomainModule = {
     ...module,
     aggregates: module.aggregates.filter(isInternal),
-    directives: module.directives.filter(isInternal),
+    directives: module.directives.filter((directive) =>
+      isInternal(directive) ||
+      (module.applicationIntents !== undefined && !publicDirectiveIds.has(directive.id))),
     ...(module.queries === undefined ? {} : { queries: module.queries.filter(isInternal) }),
     // Framework routing is for declared internal offers/queries. Business maintained reads remain
     // on the public module; do not duplicate them into the private table.