@hydranium/core 1.0.0-next.29 → 1.0.0-next.298

package/lib/langium/ast-extension/ast-extension-service.js

@@ -9,6 +9,24 @@
 import { Logger } from '@hydranium/protocol';
 import { AstUtils, DocumentState } from '@hydranium/langium';
 import { Registry } from '../../util/registry.js';
+export var AstExtensionPhase;
+(function (AstExtensionPhase) {
+    /**
+     * Every {@link AstExtensionPhase}, in build order. `BuildPipelineIntegration`
+     * wires one `onDocumentPhase` listener per entry and `register` refuses a
+     * phase outside it, so the two cannot drift apart. A fresh array each call.
+     */
+    function all() {
+        return [
+            DocumentState.Parsed,
+            DocumentState.ComputedScopes,
+            DocumentState.Linked,
+            DocumentState.IndexedReferences,
+            DocumentState.Validated
+        ];
+    }
+    AstExtensionPhase.all = all;
+})(AstExtensionPhase || (AstExtensionPhase = {}));
 /**
  * Default {@link AstExtensionService} implementation. Generic registry for
  * build-phase AST-node enrichment: computed properties and synthetic
@@ -23,19 +41,19 @@ import { Registry } from '../../util/registry.js';
  * owns the registry + per-node logic, not the listener lifecycle.
  *
  * **Performance:** `extendDocument` shares a single `streamAllContents` walk
- * per document per wired phase; cost is O(registrations-for-state × nodes),
- * and it early-outs when no registration targets the state or the document.
+ * per document per wired phase; cost is O(registrations-for-phase × nodes),
+ * and it early-outs when no registration targets the phase or the document.
  */
 export class DefaultAstExtensionService {
     services;
     extensions = new Registry();
     /**
-     * Per-state bucket of registrations targeting each state. Rebuilt lazily
+     * Per-phase bucket of registrations targeting each phase. Rebuilt lazily
      * on the first refresh after a registry mutation — staleness is detected
      * via reference identity of the registry's cached array (see {@link Registry.all}).
      */
-    stateBuckets = new Map();
-    stateBucketsFor;
+    phaseBuckets = new Map();
+    phaseBucketsFor;
     tracer;
     constructor(services, options = {}) {
         this.services = services;
@@ -59,16 +77,24 @@ export class DefaultAstExtensionService {
      * which calls {@link extendDocument} for the wired phases.
      */
     register(extension) {
+        // A phase outside the wired set type-checks only past a cast, and a
+        // registration there is accepted and never fires.
+        if (!AstExtensionPhase.all().includes(extension.phase)) {
+            throw new Error(`AST extension '${extension.id}' registered at phase ${DocumentState[extension.phase]} would never fire. ` +
+                `Allowed phases are ${AstExtensionPhase.all()
+                    .map(phase => DocumentState[phase])
+                    .join(', ')}.`);
+        }
         // Cast: TypeScript can't see that `T extends AstNode` makes the extension
         // assignable to the default-parameter form. The runtime contract is the same.
         return this.extensions.register(extension);
     }
     /**
      * Production code goes through {@link extendDocument} via the
-     * `onDocumentPhase(state)` listener wired by `BuildPipelineIntegration`.
+     * `onDocumentPhase(phase)` listener wired by `BuildPipelineIntegration`.
      */
     extendNode(node, document, phase) {
-        const bucket = this.getStateBucket(phase);
+        const bucket = this.getPhaseBucket(phase);
         for (const extension of bucket) {
             if (extension.documentFilter && !extension.documentFilter(document)) {
                 continue;
@@ -96,7 +122,7 @@ export class DefaultAstExtensionService {
         if (cancelToken?.isCancellationRequested) {
             return;
         }
-        const bucket = this.getStateBucket(phase);
+        const bucket = this.getPhaseBucket(phase);
         if (bucket.length === 0) {
             return;
         }
@@ -129,32 +155,32 @@ export class DefaultAstExtensionService {
         session?.report('debug');
     }
     /**
-     * Bucket-by-state view of {@link extensions}, rebuilt lazily when the
+     * Bucket-by-phase view of {@link extensions}, rebuilt lazily when the
      * registry's cached `all()` reference changes. Replaces per-call allocation
      * on the per-node hot path — for a workspace with many documents at the
-     * same state, the bucket is computed once and reused until the next
+     * same phase, the bucket is computed once and reused until the next
      * register / unregister.
      */
-    getStateBucket(phase) {
+    getPhaseBucket(phase) {
         const current = this.extensions.all();
-        if (this.stateBucketsFor !== current) {
+        if (this.phaseBucketsFor !== current) {
             const next = new Map();
             for (const extension of current) {
-                let bucket = next.get(extension.state);
+                let bucket = next.get(extension.phase);
                 if (!bucket) {
                     bucket = [];
-                    next.set(extension.state, bucket);
+                    next.set(extension.phase, bucket);
                 }
                 bucket.push(extension);
             }
-            this.stateBuckets = next;
-            this.stateBucketsFor = current;
+            this.phaseBuckets = next;
+            this.phaseBucketsFor = current;
         }
-        return this.stateBuckets.get(phase) ?? EMPTY_STATE_BUCKET;
+        return this.phaseBuckets.get(phase) ?? EMPTY_PHASE_BUCKET;
     }
 }
-/** Shared empty result so `getStateBucket` doesn't allocate per call on the cold path. */
-const EMPTY_STATE_BUCKET = Object.freeze([]);
+/** Shared empty result so `getPhaseBucket` doesn't allocate per call on the cold path. */
+const EMPTY_PHASE_BUCKET = Object.freeze([]);
 /**
  * Assign a non-enumerable own property — for synthetic children that must NOT
  * be walked by Langium's `streamContents`.

package/lib/langium/ast-extension/ast-extension-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"ast-extension-service.js","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-extension-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,MAAM,EAA6B,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAgB,QAAQ,EAAE,aAAa,EAAwB,MAAM,oBAAoB,CAAC;AAIjG,OAAO,EAAE,QAAQ,EAAqB,MAAM,wBAAwB,CAAC;AAuHrE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,0BAA0B;IAad;IAZH,UAAU,GAAG,IAAI,QAAQ,EAAgB,CAAC;IAC7D;;;;OAIG;IACO,YAAY,GAAG,IAAI,GAAG,EAA0C,CAAC;IACjE,eAAe,CAAsC;IAE5C,MAAM,CAAS;IAElC,YACsB,QAAgC,EACnD,UAAsC,EAAE;QADrB,aAAQ,GAAR,QAAQ,CAAwB;QAGnD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAElG,kEAAkE;QAClE,qEAAqE;QACrE,gEAAgE;QAChE,oEAAoE;QACpE,MAAM,aAAa,GAAG,QAAQ,CAAC,GAAG,EAAE,UAAU,IAAI,EAAE,CAAC;QACrD,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;YACvD,YAAY,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAC5C,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAoB,SAA0B;QACnD,0EAA0E;QAC1E,8EAA8E;QAC9E,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAyB,CAAC,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,IAAa,EAAE,QAAyB,EAAE,KAAoB;QACtE,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC1C,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;YAC9B,IAAI,SAAS,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnE,SAAS;YACZ,CAAC;YACD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,SAAS;YACZ,CAAC;YACD,SAAS,CAAC,OAAO,CAAC,IAAwB,EAAE,QAAQ,CAAC,CAAC;QACzD,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,QAAyB,EAAE,KAAoB,EAAE,WAA+B;QAC5F,IAAI,WAAW,EAAE,uBAAuB,EAAE,CAAC;YACxC,OAAO;QACV,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO;QACV,CAAC;QACD,4EAA4E;QAC5E,+EAA+E;QAC/E,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,cAAc,IAAI,SAAS,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/G,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO;QACV,CAAC;QACD,2EAA2E;QAC3E,0EAA0E;QAC1E,uEAAuE;QACvE,+DAA+D;QAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1H,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,iBAAiB,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACzE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBAClC,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC9B,mEAAmE;oBACnE,qEAAqE;oBACrE,IAAI,OAAO,EAAE,CAAC;wBACX,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,IAAwB,EAAE,QAAQ,CAAC,CAAC,CAAC;oBAC5F,CAAC;yBAAM,CAAC;wBACL,SAAS,CAAC,OAAO,CAAC,IAAwB,EAAE,QAAQ,CAAC,CAAC;oBACzD,CAAC;gBACJ,CAAC;YACJ,CAAC;QACJ,CAAC;QACD,sFAAsF;QACtF,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACO,cAAc,CAAC,KAAoB;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,eAAe,KAAK,OAAO,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAiC,CAAC;YACtD,KAAK,MAAM,SAAS,IAAI,OAAO,EAAE,CAAC;gBAC/B,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBACvC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACX,MAAM,GAAG,EAAE,CAAC;oBACZ,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;gBACrC,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC1B,CAAC;YACD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,kBAAkB,CAAC;IAC7D,CAAC;CACH;AAED,0FAA0F;AAC1F,MAAM,kBAAkB,GAA4B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAI,IAAY,EAAE,QAAgB,EAAE,KAAQ;IAC1E,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE;QACnC,KAAK;QACL,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,KAAK;KACnB,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"ast-extension-service.js","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-extension-service.ts"],"names":[],"mappings":"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"}

package/lib/langium/ast-extension/ast-node-builder.d.ts

@@ -68,15 +68,13 @@ export type AstNodeBuilder<TMap> = <TType extends string & keyof TMap>(typeConst
  * AST-interface mapping, so call sites get full inference from the type
  * constant alone — no explicit generic parameter at every call site.
  *
- * Runtime behaviour: reads `reflection.getTypeMetaData(type).properties` and,
- * for every property whose metadata carries a `defaultValue`, pre-fills the
- * result before merging the caller's `init`. Array defaults are materialised
- * as a fresh `[]` per call (never shared with the metadata's array instance,
- * which downstream callers mutate); scalar defaults (`false`, `0`, `''`, …)
- * are copied as-is since they're immutable. Grammar-generated containment
- * lists and `?=`-style boolean flags therefore default automatically;
- * TS-augmented fields (declared via `declare module './generated/ast.js'`)
- * are unaffected by the runtime defaulting but remain typed at call sites.
+ * Runtime behaviour: pre-fills every grammar-declared default (see
+ * {@link withTypeDefaults}) before merging the caller's `init`, so containment
+ * lists and `?=`-style boolean flags default automatically. TS-augmented fields
+ * (declared via `declare module './generated/ast.js'`) are unaffected by the
+ * runtime defaulting but remain typed at call sites.
+ *
+ * Use {@link buildAstNode} instead when the type name is only known at runtime.
  *
  * The init shape only relaxes array-typed fields to optional (via
  * {@link ArrayKeys}) — there is no equivalent structural signal for "this
@@ -86,5 +84,30 @@ export type AstNodeBuilder<TMap> = <TType extends string & keyof TMap>(typeConst
  * rather than a way to drop fields from the typed call site.
  */
 export declare function makeAstNodeBuilder<TMap>(reflection: AstReflection): AstNodeBuilder<TMap>;
+/**
+ * Build a node whose type is only known as a RUNTIME string.
+ *
+ * The typed {@link makeAstNodeBuilder} cannot express this: its `TMap` generic
+ * resolves the AST interface from a `$type` literal, and a type name that
+ * arrives over the wire — a protocol-layer reference request naming a node that
+ * does not exist yet — has no literal to resolve from. Callers that DO know the
+ * type at compile time want the typed builder, which checks their mandatory
+ * fields; this one checks nothing beyond the reflection lookup.
+ *
+ * Applies the same reflection-driven defaulting, so a node built here carries
+ * grammar-declared containment arrays rather than leaving them `undefined`. An
+ * unknown type name yields a node with `$type` and whatever `init` supplied,
+ * because reflection answers no metadata for it and refusing would turn a
+ * permissive lookup into a throw at a call site that can only guess.
+ *
+ * **The `type` argument is authoritative: `init` cannot rebind `$type`.** The
+ * typed builder gets this for free — `AstNodeInit` omits `$type`, so a call site
+ * cannot reach it — but here `init` is loosely typed, and the case that needs
+ * the guarantee is RETYPING: a caller spreading an existing node to produce one
+ * of a different type (`{ ...source }`) carries the SOURCE's `$type` in, which
+ * would silently win over the type actually requested and hand back a node of
+ * the wrong type with no error anywhere.
+ */
+export declare function buildAstNode<TAst extends AstNode = AstNode>(reflection: AstReflection, type: string, init?: Partial<AstNode> & Record<string, unknown>): TAst;
 export {};
 //# sourceMappingURL=ast-node-builder.d.ts.map

package/lib/langium/ast-extension/ast-node-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast-node-builder.d.ts","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-node-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACxB;AAED;;;;;GAKG;AACH,KAAK,SAAS,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK;CAAE,CAAC,MAAM,CAAC,CAAC,CAAC;AAEnG;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,GAC/E,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,oBAAoB,GAAG,iBAAiB,CAAC,CAAC,GAAG;IAC/E,UAAU,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEL;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,IAAI,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI,EAClE,YAAY,EAAE,eAAe,CAAC,KAAK,CAAC,EACpC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAChD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,aAAa,GAAG,cAAc,CAAC,IAAI,CAAC,CA2BxF"}
+{"version":3,"file":"ast-node-builder.d.ts","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-node-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACxB;AAED;;;;;GAKG;AACH,KAAK,SAAS,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK;CAAE,CAAC,MAAM,CAAC,CAAC,CAAC;AAEnG;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,GAC/E,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,oBAAoB,GAAG,iBAAiB,CAAC,CAAC,GAAG;IAC/E,UAAU,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEL;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,IAAI,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI,EAClE,YAAY,EAAE,eAAe,CAAC,KAAK,CAAC,EACpC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAChD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,aAAa,GAAG,cAAc,CAAC,IAAI,CAAC,CAexF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO,EACxD,UAAU,EAAE,aAAa,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjD,IAAI,CAON"}

package/lib/langium/ast-extension/ast-node-builder.js

@@ -17,15 +17,13 @@
  * AST-interface mapping, so call sites get full inference from the type
  * constant alone — no explicit generic parameter at every call site.
  *
- * Runtime behaviour: reads `reflection.getTypeMetaData(type).properties` and,
- * for every property whose metadata carries a `defaultValue`, pre-fills the
- * result before merging the caller's `init`. Array defaults are materialised
- * as a fresh `[]` per call (never shared with the metadata's array instance,
- * which downstream callers mutate); scalar defaults (`false`, `0`, `''`, …)
- * are copied as-is since they're immutable. Grammar-generated containment
- * lists and `?=`-style boolean flags therefore default automatically;
- * TS-augmented fields (declared via `declare module './generated/ast.js'`)
- * are unaffected by the runtime defaulting but remain typed at call sites.
+ * Runtime behaviour: pre-fills every grammar-declared default (see
+ * {@link withTypeDefaults}) before merging the caller's `init`, so containment
+ * lists and `?=`-style boolean flags default automatically. TS-augmented fields
+ * (declared via `declare module './generated/ast.js'`) are unaffected by the
+ * runtime defaulting but remain typed at call sites.
+ *
+ * Use {@link buildAstNode} instead when the type name is only known at runtime.
  *
  * The init shape only relaxes array-typed fields to optional (via
  * {@link ArrayKeys}) — there is no equivalent structural signal for "this
@@ -36,19 +34,7 @@
  */
 export function makeAstNodeBuilder(reflection) {
     return function astNode(typeConstant, init, extras) {
-        const meta = reflection.getTypeMetaData(typeConstant.$type);
-        const result = { $type: typeConstant.$type };
-        if (meta?.properties) {
-            for (const [propName, propInfo] of Object.entries(meta.properties)) {
-                const defaultValue = propInfo.defaultValue;
-                if (defaultValue === undefined) {
-                    continue;
-                }
-                // Arrays are duplicated so each node carries its own mutable instance;
-                // scalars are immutable and safe to copy by reference.
-                result[propName] = Array.isArray(defaultValue) ? [...defaultValue] : defaultValue;
-            }
-        }
+        const result = withTypeDefaults(reflection, typeConstant.$type);
         Object.assign(result, init);
         if (extras) {
             // Extras win over init: this is the explicit escape hatch, so when a
@@ -58,4 +44,56 @@ export function makeAstNodeBuilder(reflection) {
         return result;
     };
 }
+/**
+ * Build a node whose type is only known as a RUNTIME string.
+ *
+ * The typed {@link makeAstNodeBuilder} cannot express this: its `TMap` generic
+ * resolves the AST interface from a `$type` literal, and a type name that
+ * arrives over the wire — a protocol-layer reference request naming a node that
+ * does not exist yet — has no literal to resolve from. Callers that DO know the
+ * type at compile time want the typed builder, which checks their mandatory
+ * fields; this one checks nothing beyond the reflection lookup.
+ *
+ * Applies the same reflection-driven defaulting, so a node built here carries
+ * grammar-declared containment arrays rather than leaving them `undefined`. An
+ * unknown type name yields a node with `$type` and whatever `init` supplied,
+ * because reflection answers no metadata for it and refusing would turn a
+ * permissive lookup into a throw at a call site that can only guess.
+ *
+ * **The `type` argument is authoritative: `init` cannot rebind `$type`.** The
+ * typed builder gets this for free — `AstNodeInit` omits `$type`, so a call site
+ * cannot reach it — but here `init` is loosely typed, and the case that needs
+ * the guarantee is RETYPING: a caller spreading an existing node to produce one
+ * of a different type (`{ ...source }`) carries the SOURCE's `$type` in, which
+ * would silently win over the type actually requested and hand back a node of
+ * the wrong type with no error anywhere.
+ */
+export function buildAstNode(reflection, type, init) {
+    const result = withTypeDefaults(reflection, type);
+    if (init) {
+        Object.assign(result, init);
+        result.$type = type;
+    }
+    return result;
+}
+/**
+ * Seed a node with `$type` plus every property the grammar declares a default
+ * for. Array defaults are materialised as a fresh `[]` per call — never shared
+ * with the metadata's own array instance, which downstream callers mutate —
+ * while scalar defaults are copied as-is since they are immutable.
+ */
+function withTypeDefaults(reflection, type) {
+    const result = { $type: type };
+    const meta = reflection.getTypeMetaData(type);
+    if (meta?.properties) {
+        for (const [propName, propInfo] of Object.entries(meta.properties)) {
+            const defaultValue = propInfo.defaultValue;
+            if (defaultValue === undefined) {
+                continue;
+            }
+            result[propName] = Array.isArray(defaultValue) ? [...defaultValue] : defaultValue;
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=ast-node-builder.js.map

package/lib/langium/ast-extension/ast-node-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"ast-node-builder.js","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-node-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AA8DlF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,kBAAkB,CAAO,UAAyB;IAC/D,OAAO,SAAS,OAAO,CACpB,YAAoC,EACpC,IAAgD,EAChD,MAAgC;QAEhC,MAAM,IAAI,GAAG,UAAU,CAAC,eAAe,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC5D,MAAM,MAAM,GAA4B,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC;QACtE,IAAI,IAAI,EAAE,UAAU,EAAE,CAAC;YACpB,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;gBAClE,MAAM,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC;gBAC3C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;oBAC9B,SAAS;gBACZ,CAAC;gBACD,uEAAuE;gBACvE,uDAAuD;gBACvD,MAAM,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;YACrF,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC5B,IAAI,MAAM,EAAE,CAAC;YACV,qEAAqE;YACrE,+DAA+D;YAC/D,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,MAAkD,CAAC;IAC7D,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"ast-node-builder.js","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-node-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AA8DlF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,kBAAkB,CAAO,UAAyB;IAC/D,OAAO,SAAS,OAAO,CACpB,YAAoC,EACpC,IAAgD,EAChD,MAAgC;QAEhC,MAAM,MAAM,GAAG,gBAAgB,CAAC,UAAU,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAChE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC5B,IAAI,MAAM,EAAE,CAAC;YACV,qEAAqE;YACrE,+DAA+D;YAC/D,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,MAAkD,CAAC;IAC7D,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CACzB,UAAyB,EACzB,IAAY,EACZ,IAAiD;IAEjD,MAAM,MAAM,GAAG,gBAAgB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAClD,IAAI,IAAI,EAAE,CAAC;QACR,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC5B,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;IACvB,CAAC;IACD,OAAO,MAAyB,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,UAAyB,EAAE,IAAY;IAC9D,MAAM,MAAM,GAA4B,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACxD,MAAM,IAAI,GAAG,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,IAAI,EAAE,UAAU,EAAE,CAAC;QACpB,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAClE,MAAM,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC;YAC3C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;gBAC9B,SAAS;YACZ,CAAC;YACD,MAAM,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;QACrF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AACjB,CAAC"}

package/lib/langium/bootstrap.d.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { type LangiumServices, type LangiumSharedServices } from '@hydranium/langium/lsp';
-import type { ServerSharedServicesMinimal } from './shared-services.js';
+import type { ServerSharedServices } from './module.js';
 /**
  * Verify that the slots `@hydranium/core` is responsible for
  * binding are populated after composition. Throws an error with a
@@ -60,27 +60,34 @@ export declare function warnOnUnexpectedBindings(shared: LangiumSharedServices,
  *   dispatch every build-phase pass and drive AST enrichment, and
  *   registers the framework integrity passes itself. The per-language
  *   feature services it routes to (`ast.AstExtensionService` +
- *   `integrity.IntegrityService`, plus `references.ScopeExtensionService`
- *   read by the scope provider) hold the registries and the logic but own
+ *   `integrity.IntegrityService`) hold the registries and the logic but own
  *   no listeners, so they need not be eager: each language's services
- *   construct lazily when the orchestrator (or scope provider) first
- *   reaches them, and their constructors register that language's rules /
- *   extensions just-in-time.
- * - **`profilers.LangiumProfiler`** — self-registers a `Validated`
- *   BuildPhasePass that flushes the aggregated parse/link/validate profile
- *   once per build. No production cost (the profiler is trace-gated), but
- *   the pass must be registered up front.
+ *   construct lazily when the orchestrator first reaches them, and their
+ *   constructors register that language's rules / extensions just-in-time.
+ *   `references.ScopeExtensionService`, read by the scope provider, does
+ *   subscribe to the builder, but only to report its own calls, so
+ *   constructing it at its first call misses none.
+ * - **`profilers.LangiumProfiler`** — subscribes to
+ *   `documentBuilder.onBuildEnded` to flush the aggregated
+ *   parse/link/validate profile once per build. No production cost (the
+ *   profiler is trace-gated), but the listener must be attached before the
+ *   first build ends.
  * - **`workspace.CstResidencyService`** — self-registers a `Validated`
  *   BuildPhasePass that sheds the CST of closed documents. The framework
  *   default strategy is `always-keep`, so the pass runs but sheds nothing
  *   until an adopter configures a shedding strategy.
+ * - **`workspace.AstDocumentManager`** — subscribes to the build pipeline
+ *   and the text store to track opens, deletions and each build's causes.
+ * - **`model.ModelService`** — subscribes to the settled document phase to
+ *   bring the language client up to date. A tree without an LSP `initialize`,
+ *   such as a headless init, may not resolve it before the first build.
  *
  * Consumers with no additional eager targets can omit the third argument
  * to {@link bootstrapLangium} — the parameter default is this exact set.
  * Adopters needing extra eager targets spread this constant into their own
  * array and append their accessors.
  */
-export declare const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServicesMinimal) => unknown>;
+export declare const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServices) => unknown>;
 /**
  * After `inject(...)` returns, services are constructed lazily on first
  * access. Some framework services attach to the build pipeline in their
@@ -96,36 +103,39 @@ export declare const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerShar
  * discarded.
  *
  * Bootstrap responsibilities, in order:
- *  1. Hand the shared services to `shared.ServiceRegistry` if it accepts
+ *  1. {@link assertSingleLangiumCopy} — fail fast when the shared
+ *     `AstReflection` is built on a second copy of `langium`, before any
+ *     later check can fail first and name the wrong cause.
+ *  2. Hand the shared services to `shared.ServiceRegistry` if it accepts
  *     them after construction, so Langium's declared-languageId lookup
  *     rung works however the adopter's registry binding was built.
- *  2. {@link assertDistinctFileRouting} — before registration, because
+ *  3. {@link assertDistinctFileRouting} — before registration, because
  *     `register` resolves a routing collision by last-wins and afterwards
  *     the evidence is gone.
- *  3. Register `language` against `shared.ServiceRegistry`, the
+ *  4. Register `language` against `shared.ServiceRegistry`, the
  *     required final step of any Langium DI bootstrap. Done before slot
  *     validation so subclassed registries (typed-accessor extensions)
  *     populate any side state before validation walks construct services
  *     that read from the registry.
- *  4. {@link assertCoreSlotsBound} — fail fast if the consumer's
+ *  5. {@link assertCoreSlotsBound} — fail fast if the consumer's
  *     `inject(...)` composition is missing a `@hydranium/core` module. May
  *     trigger lazy service construction as side effect of walking the
  *     slots; that construction expects a populated `ServiceRegistry`,
  *     hence the order.
- *  5. {@link warnOnUnexpectedBindings} — opt-in (gated by
+ *  6. {@link warnOnUnexpectedBindings} — opt-in (gated by
  *     {@link STRICT_BINDINGS_ENV}); warns when a framework slot is bound
  *     to a non-subclass of its framework base. No-op unless the env is set.
- *  6. {@link assertReflectionCoversLanguages} — catch a clobbered shared
+ *  7. {@link assertReflectionCoversLanguages} — catch a clobbered shared
  *     `AstReflection` before it starts silently answering `isSubtype`
  *     false for a registered language's types. Skipped here, since a lone
  *     language has no sibling that could clobber it.
- *  7. Invoke eager-construction accessors in array order.
+ *  8. Invoke eager-construction accessors in array order.
  *
  * Multi-grammar adopters use {@link bootstrapLangiumLanguages}, which
  * registers every language before validating slots or constructing the
  * eager set.
  */
-export declare function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServicesMinimal, TLang extends LangiumServices>(shared: TShared, language: TLang, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
+export declare function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(shared: TShared, language: TLang, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
     shared: TShared;
     language: TLang;
 };
@@ -139,29 +149,32 @@ export declare function bootstrapLangium<TShared extends LangiumSharedServices &
  * ORDER across languages is what makes this a distinct function rather
  * than a loop the caller could write:
  *
- *  1. **Every** language is registered against `shared.ServiceRegistry`
- *     first. Slot validation and eager construction both build services
+ *  1. {@link assertSingleLangiumCopy} runs **once**, before anything else,
+ *     since every language shares the one `AstReflection`.
+ *  2. **Every** language is registered against `shared.ServiceRegistry`
+ *     next. Slot validation and eager construction both build services
  *     that read the registry — a per-language
  *     register-then-validate-then-eager loop would run them while later
  *     languages were still missing, so a shared service that walks
  *     `ServiceRegistry.all` (or resolves by extension) would see a
  *     half-populated registry and cache the wrong answer.
- *  2. `assertCoreSlotsBound` / `warnOnUnexpectedBindings` per language —
+ *  3. `assertCoreSlotsBound` / `warnOnUnexpectedBindings` per language —
  *     each language composes its own module chain, so each is checked.
- *  3. Eager accessors run **once**, after all registrations. They take
- *     the shared tier, and the framework's eager set is shared-tier only
- *     (`ProjectManager`, `BuildPipelineIntegration`, `LangiumProfiler`,
- *     `CstResidencyService`) — `BuildPipelineIntegration` in particular
- *     routes per document URI to each language's `IntegrityService` /
- *     `AstExtensionService`, so it must be constructed knowing all of
- *     them. Running the set per language would attach its
- *     `documentBuilder` listeners N times and enforce each phase N times.
+ *  4. {@link assertReflectionCoversLanguages} runs **once**, on the one
+ *     shared `AstReflection`.
+ *  5. Eager accessors run **once**, after all registrations. They take
+ *     the shared tier, and the framework's eager set is shared-tier only —
+ *     `BuildPipelineIntegration` in particular routes per document URI to
+ *     each language's `IntegrityService` / `AstExtensionService`, so it
+ *     must be constructed knowing all of them. Running the set per language
+ *     would attach its `documentBuilder` listeners N times and enforce each
+ *     phase N times.
  *
  * Throws when `languages` is empty: a shared tier with no registered
  * language never validates its slots, which silently defers a
  * composition error to the first build.
  */
-export declare function bootstrapLangiumLanguages<TShared extends LangiumSharedServices & ServerSharedServicesMinimal, TLang extends LangiumServices>(shared: TShared, languages: ReadonlyArray<TLang>, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
+export declare function bootstrapLangiumLanguages<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(shared: TShared, languages: ReadonlyArray<TLang>, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
     shared: TShared;
     languages: ReadonlyArray<TLang>;
 };
@@ -203,11 +216,11 @@ export declare function assertDistinctFileRouting(languages: ReadonlyArray<Langi
  *
  * The check is per language, on the types its grammar can produce, and costs
  * one grammar walk per language at boot; a single-language composition, which
- * nothing can clobber, is skipped entirely. It cannot repair the situation — a
- * reflection that spans independently generated grammars is a real design piece
- * (a composite reflection dispatching per owning language) and is not attempted
- * here; the point is to turn a silent runtime misbehaviour into a boot failure
- * that names the language and the mistake.
+ * nothing can clobber, is skipped entirely. It cannot repair the situation, since
+ * the losing reflection is already gone; the point is to turn a silent runtime
+ * misbehaviour into a boot failure that names the language and the mistake. The
+ * repair is the adopter's: bind a `CompositeAstReflection` over every package's
+ * generated reflection, or generate all grammars in one `langium-cli` run.
  *
  * **Two severities, because a clobber is not always total.** Throwing only when
  * NONE of a language's types are known misses the realistic case: two grammars

package/lib/langium/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/langium/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AA+GxE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAanG;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAmF/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAiBvG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,2BAA2B,KAAK,OAAO,CAKpG,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,qBAAqB,GAAG,2BAA2B,EAAE,KAAK,SAAS,eAAe,EAChI,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,KAAK,EACf,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,CAGtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACtC,OAAO,SAAS,qBAAqB,GAAG,2BAA2B,EACnE,KAAK,SAAS,eAAe,EAE7B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,EAC/B,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CAAE,CAiCtD;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CA+BzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,qBAAqB,EAAE,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CAiC9H"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/langium/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAyHxD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAanG;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAiG/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAiBvG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAO7F,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,qBAAqB,GAAG,oBAAoB,EAAE,KAAK,SAAS,eAAe,EACzH,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,KAAK,EACf,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,CAGtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,SAAS,qBAAqB,GAAG,oBAAoB,EAAE,KAAK,SAAS,eAAe,EAClI,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,EAC/B,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CAAE,CAsCtD;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CA+BzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,qBAAqB,EAAE,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CAkC9H"}