@githolon/dsl 0.107.4 → 0.108.1

package/dart/lib/src/result_usda.dart

@@ -0,0 +1,487 @@
+/// Constrained canonical-USDA reader used by generated Nomos domain decoders.
+///
+/// This is syntax infrastructure, not a second domain model. Generated clients
+/// supply the exact aggregate and field law paths they were compiled from and
+/// refuse any result whose relationships do not match them.
+@internal
+library;
+
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:meta/meta.dart' show internal;
+
+final class NmsUsdaProperty {
+  const NmsUsdaProperty(this.name, this.value);
+
+  final String name;
+  final Object value;
+}
+
+final class NmsUsdaPrim {
+  NmsUsdaPrim(this.typeName, this.name);
+
+  final String typeName;
+  final String name;
+  final List<NmsUsdaProperty> properties = [];
+  final List<NmsUsdaPrim> children = [];
+
+  Object? property(String propertyName) {
+    for (final property in properties) {
+      if (property.name == propertyName) return property.value;
+    }
+    return null;
+  }
+
+  String? relationship(String propertyName) {
+    final value = property(propertyName);
+    return value is String ? value : null;
+  }
+
+  String requiredStringProperty(String propertyName) {
+    final value = property(propertyName);
+    if (value is! String) {
+      throw FormatException('$typeName has no textual $propertyName');
+    }
+    return value;
+  }
+
+  String? optionalStringProperty(String propertyName) {
+    final value = property(propertyName);
+    if (value == null) return null;
+    if (value is! String) {
+      throw FormatException('$typeName has a non-textual $propertyName');
+    }
+    return value;
+  }
+
+  int requiredIntProperty(String propertyName) {
+    final value = property(propertyName);
+    if (value is! int) {
+      throw FormatException('$typeName has no integer $propertyName');
+    }
+    return value;
+  }
+
+  List<String> requiredStringArrayProperty(String propertyName) {
+    final value = property(propertyName);
+    if (value is! List || value.any((entry) => entry is! String)) {
+      throw FormatException('$typeName has no string array $propertyName');
+    }
+    return List.unmodifiable(value.cast<String>());
+  }
+
+  NmsUsdaPrim? field(String lawPath) {
+    for (final child in children) {
+      if (child.relationship('nomos:field') == lawPath) return child;
+    }
+    return null;
+  }
+
+  NmsUsdaPrim requiredField(String lawPath) {
+    final value = field(lawPath);
+    if (value == null) {
+      throw FormatException('USDA row omits required law field $lawPath');
+    }
+    return value;
+  }
+
+  NmsUsdaPrim? child(String childName) {
+    for (final child in children) {
+      if (child.name == childName) return child;
+    }
+    return null;
+  }
+
+  NmsUsdaPrim requiredChild(String childName) {
+    final value = child(childName);
+    if (value == null) {
+      throw FormatException('$typeName has no $childName child');
+    }
+    return value;
+  }
+
+  NmsUsdaPrim? jsonMember(String key) {
+    final object = switch (typeName) {
+      'NomosRecordValue' || 'NomosJsonValue' => requiredChild('Value'),
+      'NomosJsonObject' => this,
+      _ => throw FormatException('$typeName is not a USDA object value'),
+    };
+    if (object.typeName != 'NomosJsonObject') {
+      throw FormatException('${object.typeName} is not a USDA JSON object');
+    }
+    for (final member in object.children) {
+      if (member.requiredStringProperty('nomos:key') == key) {
+        return member.requiredChild('Value');
+      }
+    }
+    return null;
+  }
+
+  NmsUsdaPrim requiredJsonMember(String key) {
+    final value = jsonMember(key);
+    if (value == null)
+      throw FormatException('$typeName has no JSON member $key');
+    return value;
+  }
+
+  String stringValue() {
+    final value = property('nomos:value');
+    if (value is! String)
+      throw const FormatException('USDA value is not textual');
+    return value;
+  }
+
+  int intValue() {
+    final value = property('nomos:value');
+    if (value is! int)
+      throw const FormatException('USDA value is not an integer');
+    return value;
+  }
+
+  num numberValue() {
+    final value = property('nomos:value');
+    if (value is! num) throw const FormatException('USDA value is not numeric');
+    return value;
+  }
+
+  bool boolValue() {
+    final value = property('nomos:value');
+    if (value is! bool)
+      throw const FormatException('USDA value is not boolean');
+    return value;
+  }
+
+  Object? jsonValue() {
+    switch (typeName) {
+      case 'NomosNullValue':
+        return null;
+      case 'NomosBoolValue':
+        return boolValue();
+      case 'NomosIntValue':
+      case 'NomosNumberValue':
+        return numberValue();
+      case 'NomosStringValue':
+      case 'NomosTokenValue':
+        return stringValue();
+      case 'NomosJsonValue':
+      case 'NomosRecordValue':
+        return _requiredChild('Value').jsonValue();
+      case 'NomosJsonArray':
+        return children
+            .map((child) => child.jsonValue())
+            .toList(growable: false);
+      case 'NomosJsonObject':
+        return <String, Object?>{
+          for (final member in children)
+            member._requiredStringProperty('nomos:key'):
+                member._requiredChild('Value').jsonValue(),
+        };
+      default:
+        throw FormatException('Unsupported nominal JSON prim $typeName');
+    }
+  }
+
+  Map<String, T> mapValue<T>(T Function(NmsUsdaPrim value) decode) =>
+      <String, T>{
+        for (final entry in children)
+          entry._requiredStringProperty('nomos:key'):
+              decode(entry._requiredChild('Value')),
+      };
+
+  NmsUsdaPrim _requiredChild(String childName) {
+    for (final child in children) {
+      if (child.name == childName) return child;
+    }
+    throw FormatException('$typeName has no $childName child');
+  }
+
+  String _requiredStringProperty(String propertyName) {
+    final value = property(propertyName);
+    if (value is! String) {
+      throw FormatException('$typeName has no textual $propertyName');
+    }
+    return value;
+  }
+}
+
+/// Syntax-level view of the framework-owned maintained conflict index. The
+/// generated domain client supplies the application field types and law paths.
+final class NmsUsdaConflictResult {
+  const NmsUsdaConflictResult({required this.rows});
+
+  final List<NmsUsdaPrim> rows;
+
+  factory NmsUsdaConflictResult.parse(Uint8List bytes) {
+    final root = NmsUsdaLayer.parse(bytes);
+    if (root.typeName != 'NomosPendingConflicts' || root.name != 'Conflicts') {
+      throw const FormatException('Expected NomosPendingConflicts');
+    }
+    final rows = root.requiredChild('Rows');
+    if (rows.typeName != 'NomosListValue') {
+      throw const FormatException('Pending conflict Rows is not a list');
+    }
+    return NmsUsdaConflictResult(rows: List.unmodifiable(rows.children));
+  }
+}
+
+final class NmsUsdaConflictCount {
+  const NmsUsdaConflictCount({
+    required this.aggregatePath,
+    required this.count,
+  });
+
+  final String aggregatePath;
+  final int count;
+}
+
+/// Exact framework summary. Aggregate identities remain authenticated law
+/// relationships rather than host-authored labels.
+final class NmsUsdaConflictSummaryResult {
+  const NmsUsdaConflictSummaryResult({
+    required this.total,
+    required this.ready,
+    required this.evolutionRequired,
+    required this.byAggregate,
+  });
+
+  final int total;
+  final int ready;
+  final int evolutionRequired;
+  final List<NmsUsdaConflictCount> byAggregate;
+
+  factory NmsUsdaConflictSummaryResult.parse(Uint8List bytes) {
+    final root = NmsUsdaLayer.parse(bytes);
+    if (root.typeName != 'NomosPendingConflictSummary' ||
+        root.name != 'ConflictSummary') {
+      throw const FormatException('Expected NomosPendingConflictSummary');
+    }
+    int integer(String name) {
+      final value = root.property(name);
+      if (value is! int || value < 0) {
+        throw FormatException('$name is not an unsigned integer');
+      }
+      return value;
+    }
+
+    final counts = root.requiredChild('ByAggregate');
+    if (counts.typeName != 'NomosConflictCounts') {
+      throw const FormatException(
+          'Conflict summary counts have the wrong type');
+    }
+    return NmsUsdaConflictSummaryResult(
+      total: integer('nomos:total'),
+      ready: integer('nomos:ready'),
+      evolutionRequired: integer('nomos:evolutionRequired'),
+      byAggregate: List.unmodifiable(counts.children.map((entry) {
+        final aggregatePath = entry.relationship('nomos:type');
+        final count = entry.property('nomos:count');
+        if (aggregatePath == null || count is! int || count < 0) {
+          throw const FormatException('Malformed aggregate conflict count');
+        }
+        return NmsUsdaConflictCount(
+          aggregatePath: aggregatePath,
+          count: count,
+        );
+      })),
+    );
+  }
+}
+
+final class NmsUsdaResult {
+  const NmsUsdaResult({required this.rows, this.cursor, required this.done});
+
+  final List<NmsUsdaPrim> rows;
+  final String? cursor;
+  final bool done;
+
+  factory NmsUsdaResult.parse(Uint8List bytes) {
+    final root = NmsUsdaLayer.parse(bytes);
+    if (root.typeName != 'NomosReadResult') {
+      throw const FormatException('Expected NomosReadResult');
+    }
+    NmsUsdaPrim? rows;
+    for (final child in root.children) {
+      if (child.typeName == 'NomosListValue' && child.name == 'Rows') {
+        rows = child;
+        break;
+      }
+    }
+    if (rows == null)
+      throw const FormatException('NomosReadResult has no Rows');
+    final cursor = root.property('nomos:cursor');
+    final done = root.property('nomos:done');
+    if (cursor != null && cursor is! String) {
+      throw const FormatException('NomosReadResult cursor is not textual');
+    }
+    if (done != null && done is! bool) {
+      throw const FormatException('NomosReadResult done marker is not boolean');
+    }
+    return NmsUsdaResult(
+      rows: List.unmodifiable(rows.children),
+      cursor: cursor as String?,
+      done: done as bool? ?? true,
+    );
+  }
+}
+
+/// Syntax-only entry point for generated nominal USDA contracts which are not
+/// read-result pages (for example a transported framework capability).
+@internal
+abstract final class NmsUsdaLayer {
+  static NmsUsdaPrim parse(Uint8List bytes) => _parseLayer(bytes);
+
+  static String quote(String value) {
+    final out = StringBuffer('"');
+    for (final code in value.codeUnits) {
+      switch (code) {
+        case 0x22:
+          out.write(r'\"');
+        case 0x5c:
+          out.write(r'\\');
+        case 0x0a:
+          out.write(r'\n');
+        case 0x0d:
+          out.write(r'\r');
+        case 0x09:
+          out.write(r'\t');
+        case 0x08:
+          out.write(r'\b');
+        case 0x0c:
+          out.write(r'\f');
+        default:
+          if (code < 0x20) {
+            out.write(r'\u');
+            out.write(code.toRadixString(16).padLeft(4, '0'));
+          } else {
+            out.writeCharCode(code);
+          }
+      }
+    }
+    out.write('"');
+    return out.toString();
+  }
+}
+
+NmsUsdaPrim _parseLayer(Uint8List bytes) {
+  final roots = <NmsUsdaPrim>[];
+  final stack = <NmsUsdaPrim>[];
+  NmsUsdaPrim? pending;
+  for (final original in const LineSplitter().convert(utf8.decode(bytes))) {
+    final line = original.trim();
+    if (line.isEmpty ||
+        line.startsWith('#') ||
+        line == '(' ||
+        line == ')' ||
+        line.startsWith('defaultPrim')) {
+      continue;
+    }
+    final declaration = RegExp(
+      r'^def\s+([A-Za-z_][A-Za-z0-9_]*)\s+("(?:[^"\\]|\\.)*")$',
+    ).firstMatch(line);
+    if (declaration != null) {
+      pending = NmsUsdaPrim(
+        declaration.group(1)!,
+        _unquote(declaration.group(2)!),
+      );
+      continue;
+    }
+    if (line == '{') {
+      final prim = pending;
+      if (prim == null)
+        throw const FormatException('USDA scope has no declaration');
+      if (stack.isEmpty) {
+        roots.add(prim);
+      } else {
+        stack.last.children.add(prim);
+      }
+      stack.add(prim);
+      pending = null;
+      continue;
+    }
+    if (line == '}') {
+      if (stack.isEmpty) throw const FormatException('Unbalanced USDA scope');
+      stack.removeLast();
+      continue;
+    }
+    final property = RegExp(
+      r'^custom(?:\s+uniform)?\s+(?:rel|[A-Za-z0-9_\[\]]+)\s+([A-Za-z0-9_:]+)\s*=\s*(.+)$',
+    ).firstMatch(line);
+    if (property != null) {
+      if (stack.isEmpty)
+        throw const FormatException('USDA property outside prim');
+      stack.last.properties.add(
+        NmsUsdaProperty(property.group(1)!, _atom(property.group(2)!)),
+      );
+      continue;
+    }
+    throw FormatException('Unsupported canonical USDA line: $line');
+  }
+  if (stack.isNotEmpty || roots.length != 1) {
+    throw const FormatException(
+        'USDA result must contain one balanced root prim');
+  }
+  return roots.single;
+}
+
+Object _atom(String source) {
+  final value = source.trim();
+  if (value.startsWith('"')) return _unquote(value);
+  if (value == 'true') return true;
+  if (value == 'false') return false;
+  final integer = int.tryParse(value);
+  if (integer != null) return integer;
+  final number = double.tryParse(value);
+  if (number != null && number.isFinite) return number;
+  if (value.startsWith('<') && value.endsWith('>')) {
+    return value.substring(1, value.length - 1);
+  }
+  throw FormatException('Unsupported USDA value $value');
+}
+
+String _unquote(String source) {
+  if (source.length < 2 || !source.startsWith('"') || !source.endsWith('"')) {
+    throw const FormatException('Invalid USDA string');
+  }
+  final out = StringBuffer();
+  for (var index = 1; index < source.length - 1; index++) {
+    final character = source[index];
+    if (character != r'\') {
+      out.write(character);
+      continue;
+    }
+    if (++index >= source.length - 1) {
+      throw const FormatException('Truncated USDA escape');
+    }
+    final escaped = source[index];
+    switch (escaped) {
+      case 'n':
+        out.write('\n');
+      case 'r':
+        out.write('\r');
+      case 't':
+        out.write('\t');
+      case 'b':
+        out.write('\b');
+      case 'f':
+        out.write('\f');
+      case '"':
+        out.write('"');
+      case r'\':
+        out.write(r'\');
+      case 'u':
+        if (index + 4 >= source.length) {
+          throw const FormatException('Truncated USDA unicode escape');
+        }
+        final digits = source.substring(index + 1, index + 5);
+        final code = int.tryParse(digits, radix: 16);
+        if (code == null)
+          throw const FormatException('Invalid USDA unicode escape');
+        out.writeCharCode(code);
+        index += 4;
+      default:
+        throw FormatException('Unsupported USDA escape $escaped');
+    }
+  }
+  return out.toString();
+}