feat(language): describe canonical module interfaces

Author: hhenson

language/CMakeLists.txt

@@ -155,6 +155,7 @@ hgl_apply_warnings(hgl_graph_ir)
 # descriptor-only checking.
 add_library(hgl_descriptor STATIC
     src/descriptor/module_descriptor.cpp
+    src/descriptor/module_descriptor_json.cpp
 )
 add_library(hgl::descriptor ALIAS hgl_descriptor)
 target_compile_features(hgl_descriptor PUBLIC cxx_std_23)

language/docs/design/decisions/0004-json-module-descriptors.md

@@ -1,6 +1,6 @@
 # ADR 0004: Module descriptors use canonical versioned JSON
 
-Status: accepted; reader and complete interface schema pending
+Status: accepted; writer implemented, reader and native ABI metadata pending
 
 ## Context
 
@@ -9,9 +9,9 @@ authors can review, build tools can transport, and `hgl check` can eventually
 consume without loading executable code. The representation must not depend on
 C++ object layout, compiler ABI, parser internals, or a running hgraph registry.
 
-The first producer is the HGL C++ backend itself. It needs to establish the
-envelope and package inventories before the following slices add complete type,
-constraint, lifecycle, and fingerprint records.
+The first producer is the HGL C++ backend itself. The descriptor must carry
+enough structured source interface data for a later reader to check imports
+without reparsing HGL or loading executable code.
 
 ## Decision
 
@@ -20,18 +20,38 @@ Use UTF-8 JSON with the format identity `hgl.module` and an integer
 
 - module identity and HGL release version;
 - automatically public operators, exported structures, and exported functions;
+- generic and ordinary parameters, results, default values, struct parents and
+  effective fields;
+- canonical type, compile-time-expression, and constraint records reachable
+  from those public declarations and implementation candidates;
 - implementation-to-operator bindings and required provider identities;
 - generated public headers, known CMake packages and imported targets; and
 - the generated C++ registration symbol.
 
 The canonical emitter uses a fixed object-member order, lexically sorts and
-deduplicates set-like arrays, escapes every JSON control character, and writes
-one trailing line feed. A reader must treat object-member order and insignificant
+deduplicates set-like identity and build inventories, preserves semantic operand
+order inside expressions, escapes every JSON control character, and writes one
+trailing line feed. A reader must treat object-member order and insignificant
 whitespace as irrelevant, reject duplicate members and unsupported format
 versions, and ignore unknown members within a supported version. Adding an
 optional member is compatible; changing or removing existing meaning requires a
 new `format_version`.
 
+Declarations and candidates refer into three descriptor-local schema arenas:
+`types`, `constant_expressions`, and `constraints`. Records are assigned by
+visiting exported structures, local operators, exported functions, and provider
+implementations in that order, with each group ordered by stable identity.
+References are unsigned JSON integers and a missing optional reference is
+`null`; record IDs have no meaning outside their descriptor. Generic type and
+const parameters also retain a declaration-scoped binding identity, so repeated
+names from different contracts never alias.
+
+Integer and floating-point literal payloads are tagged strings. This preserves
+the full i64 range and HGL's `inf`, `-inf`, and `nan` values without depending on
+a JSON consumer's numeric range or its handling of non-standard JSON tokens.
+Booleans remain JSON booleans, strings remain strings, and temporal values use
+their canonical HGL spelling together with their temporal kind.
+
 Descriptor fingerprints will be computed over the canonical semantic form, not
 over arbitrary input whitespace. The fingerprint field itself is excluded from
 that input. Its algorithm and placement are intentionally left to the
@@ -49,9 +69,10 @@ install or aggregate it deliberately.
   formatting, registry access, and dynamic loading.
 - Scripted compilation and AOT generation retain the identical descriptor
   bytes with their other build artifacts.
-- The initial file is not yet sufficient for descriptor-only type checking;
-  signatures, constraints, ownership/effects, lifecycle ABI, and fingerprints
-  remain explicit Stage F work.
+- The file now contains structured HGL signatures, struct layouts, defaults,
+  generic bindings, and constraints. Descriptor reading, dependency closure,
+  phase/effect/ownership policy, lifecycle ABI, and fingerprints remain
+  explicit Stage F work before descriptor-only checking is complete.
 
 ## Alternatives
 

language/docs/design/native-interface.md

@@ -1,6 +1,6 @@
 # Native interface
 
-Status: accepted boundary; JSON envelope implemented, complete schema and ABI remain
+Status: accepted boundary; HGL interface schema implemented, native metadata and ABI remain
 
 ## Purpose
 
@@ -53,10 +53,12 @@ For every exposed native declaration the descriptor records:
 
 The serialized representation is the canonical, versioned JSON selected in
 [ADR 0004](decisions/0004-json-module-descriptors.md). The current compiler
-emits its envelope, public/provider inventories, and generated build metadata;
-complete signatures, constraints, phase/effect/ownership policy, lifecycle ABI,
-and fingerprints remain to be added. The native-package authoring API is not yet
-chosen. No HGL declaration syntax is implied by this list.
+emits its envelope, public/provider inventories, structured HGL signatures,
+struct layouts, defaults, canonical types and constraints, and generated build
+metadata. Descriptor reading and dependency closure,
+phase/effect/ownership policy, lifecycle ABI, and fingerprints remain to be
+added. The native-package authoring API is not yet chosen. No HGL declaration
+syntax is implied by this list.
 
 ## Native declaration categories
 

language/docs/design/roadmap.md

@@ -228,6 +228,8 @@ HGraph IR; unsupported language-depth items remain explicit roadmap work.
 ### F. Constrained native interface
 
 - [x] choose and version a reviewable descriptor representation;
+- [x] emit structured public/provider signatures, struct layouts, defaults,
+  canonical types, and generic constraints;
 - choose and version the lifecycle ABI;
 - provide a native-package authoring API which emits descriptors and normalized
   wrappers;

language/docs/developer-guide/compiler-and-lowering.md

@@ -1011,11 +1011,23 @@ registry, loader, or C++ formatter dependency. `hgl emit-cpp` writes
 `<stem>.hgl-module.json` beside the generated source, and scripted native builds
 retain the same bytes in their content-addressed artifacts.
 
-Version 1 currently materializes the module/version envelope, public declaration
-identities and categories, implementation/provider inventories, baseline build
-requirements, and the generated registration symbol. This is a staging
-checkpoint, not descriptor-only checking: canonical signature and constraint
-records, effect/ownership policy, lifecycle entry points, and fingerprints are
+Version 1 materializes the module/version envelope, public declarations,
+implementation/provider inventories, baseline build requirements, and the
+generated registration symbol. Public structures, operators, functions, and
+implementation candidates reference structured signatures and three
+descriptor-local arenas for canonical types, compile-time expressions, and
+constraints. Only records reachable from those surfaces are retained; private
+body types do not leak into the package interface.
+
+Record IDs are assigned by a fixed traversal of declarations ordered by stable
+identity and are meaningful only inside that descriptor. A symbol type carries
+both its nominal spelling and, for a generic parameter, its declaration-scoped
+binding identity. Defaults and const-generic bounds remain expression trees,
+not strings to be reparsed. Tagged textual i64/f64 payloads retain the full i64
+range and non-finite HGL floats while keeping the output valid JSON.
+
+This is still not descriptor-only checking: a reader and locked dependency
+closure, effect/ownership policy, lifecycle entry points, and fingerprints are
 the following Stage F slices.
 
 A descriptor separates its importable interface from its provider inventory.

language/docs/user-guide/modules-and-tools.md

@@ -258,13 +258,52 @@ generated `operators` namespace contains transparent type aliases rather than
 derived marker classes, so the registry contract visible in the source is the
 exact hgraph `Operator` type.
 
-The JSON sidecar is canonical and versioned. Its first checkpoint records the
-module and language versions, public declaration identities, operator
-implementations and provider requirements, generated header, baseline hgraph
-CMake dependency, and registration symbol. Complete imported signatures,
-constraints, native ownership/effect declarations, lifecycle entry points, and
-fingerprints are not implemented yet, so this checkpoint does not provide
-descriptor-only `hgl check`.
+The JSON sidecar is canonical and versioned. It records the module and language
+versions; public structures, operators, and functions; implementation
+candidates and provider requirements; and the generated build boundary. Its
+structured schema records preserve generic bindings, parameters and results,
+struct inheritance and effective fields, defaults and rolling bounds, nominal
+type applications, and `requires` constraints. Integer and float literal
+payloads are tagged strings so the full i64 range and non-finite floats remain
+valid JSON.
+
+For example, a generic operator points to descriptor-local type records rather
+than embedding source text that another tool would need to parse:
+
+```json
+{
+  "category": "operator",
+  "identity": "examples.windows.summarize",
+  "signature": {
+    "generic_parameters": [
+      {
+        "name": "T",
+        "kind": "type",
+        "binding": "examples.windows.summarize::T",
+        "type": null
+      }
+    ],
+    "parameters": [
+      {
+        "name": "window",
+        "kind": "signal",
+        "binding": "examples.windows.summarize::window",
+        "type": 1,
+        "default": null
+      }
+    ],
+    "result": 2,
+    "requires": null
+  }
+}
+```
+
+The `type`, `result`, `default`, and `requires` numbers refer to records in the
+same file's `schema` object. They have no identity outside that one descriptor.
+
+Descriptor loading, transitive dependency locking, native ownership/effect
+declarations, lifecycle entry points, and fingerprints are not implemented yet,
+so this checkpoint does not provide descriptor-only `hgl check`.
 
 A package is a CMake project. `hgl_add_module()`, installed with `hgl` in
 `lib/cmake/hgl/HglLanguage.cmake`, runs `emit-cpp` at build time and compiles

language/src/README.md

@@ -11,7 +11,7 @@ them.
 | `semantics/` | name binding, nominal hierarchy, generic argument roles, function classification | syntax plus descriptors to resolved names and shapes |
 | `ir/` | source-ranged HIR, canonical types, substitutions, constraint solving, phase/effect completion | resolved frontend state to typed HIR |
 | `hgraph_ir/` | canonical execution-facing types, compile-time expressions, constraints, typed source-order declaration handles, struct contracts, operator and callable interfaces | typed HIR to executable composition and runtime-node plans |
-| `descriptor/` | versioned module descriptor model and canonical JSON serialization | hgraph IR to reviewable package metadata |
+| `descriptor/` | versioned module/interface schema, deterministic HGraph-IR snapshot, and canonical JSON serialization | hgraph IR to reviewable package metadata |
 | `wiring/` | direct walk over hgraph IR | hgraph IR to public erased wiring calls |
 | `codegen/` | hgraph-IR declaration, interface, dependency, composition-body, and runtime-body emission | hgraph IR to formatted C++ and build artifacts |
 | `driver/` | commands, native build/cache/load, REPL orchestration | assemble inputs and invoke passes |