@scriptc/compiler 0.0.18 → 0.0.20

package/dist/library/sidecar.js

@@ -24,15 +24,17 @@
  * pattern) is allowed with a pinned order: depth-first source order of
  * the constituent declarations (A's arms in A's own declaration order,
  * then B's), an arm name appearing in several constituents keeping its
- * FIRST occurrence. A type alias of a named type is transparent: the
- * table derives from the aliased declaration, the alias adds no entry
- * and no reordering.
+ * FIRST occurrence. Type aliases are transparent where the wire has no
+ * alias identity: a reference alias tables the target declaration, while
+ * a scalar alias projects as its underlying bool/number/string/bytes
+ * TypeRef. Neither alias adds a table entry or reorders the target.
  *
  * Integer slots (ask 4): the profile's `sidecar.integer_slots` declares
  * specific number slots i64/u64 by slot path; the projection spells each
- * declared slot's TypeRef/descriptor `i64` (the frozen format-1
- * vocabulary — u64 is the stricter compile-time obligation over the same
- * wire spelling), refuses paths that resolve to no plain number slot,
+ * declared slot's TypeRef/descriptor `i64`, nested under `optional` when
+ * the TypeScript slot is optional (the frozen format-1 vocabulary — u64 is
+ * the stricter compile-time obligation over the same wire spelling), and
+ * refuses paths that resolve to no bare or optional number slot,
  * and emits `integer_slots` as the resolved-decision list, in profile
  * declaration order, each entry recording the DECLARED class ({i64, u64}
  * — the flattening is TypeRef-only). The list is an ATTESTATION (schema
@@ -137,6 +139,10 @@ function classify(decl, index) {
     if (s.k === "object") {
         return { c: "struct", storage: decl.form === "interface" ? "node" : "value", fields: s.fields, decl, index };
     }
+    if (decl.form === "alias" &&
+        (s.k === "bool" || s.k === "number" || s.k === "text" || s.k === "bytes")) {
+        return { c: "scalar", shape: s, decl, index };
+    }
     if (decl.form === "alias" && s.k === "ref")
         return { c: "alias", target: s.name, decl, index };
     if (decl.form === "alias" && s.k === "stringLit")
@@ -191,7 +197,10 @@ class Projector {
     table = new Map();
     inProgress = new Set();
     flatArms = new Map();
+    allFlatArms = new Map();
     flattening = new Set();
+    allFlattening = new Set();
+    irPatterning = new Set();
     synthCounter = 0;
     /** The profile's declared integer slots (ask 4), by slot path; entries
      * move to `intConsumed` as the projection spells them — a declared path
@@ -200,9 +209,11 @@ class Projector {
     intDeclared = new Map();
     intConsumed = new Map();
     /** The record-field slots' resolution facts for the inference: the
-     * containing record's full projected field-name list plus the target
-     * field (ir shapes intern structurally by field names). */
-    intRecordFacts = [];
+     * containing record's complete projected IR shape plus the target field
+     * (IR shapes intern structurally by field names and field types). Pattern
+     * construction is deferred until the whole contract graph has projected,
+     * so an invalid later sibling still takes its ordinary SidecarError path. */
+    pendingIntRecordFacts = [];
     constructor(facts, config, entryLoc) {
         this.facts = facts;
         this.config = config;
@@ -216,20 +227,28 @@ class Projector {
             this.intDeclared.set(e.slot, e.cls);
     }
     /** Spell a projected slot i64 when the profile declared it (ask 4).
-     * Only a PLAIN NUMBER slot can be integer-declared: optionals, slices,
-     * and named types refuse — the declaration must match the wire shape
-     * the schema freezes. The document spells i64 for both classes (the
-     * frozen format-1 vocabulary has no u64; u64 is the stricter
-     * compile-time obligation over the same wire spelling). */
+     * A NUMBER slot may be bare or optional: optional<number> composes the
+     * schema's two existing constructors as optional<i64>, and the proof
+     * applies only to its present numeric arm. Slices and named types still
+     * refuse — the declaration must match the wire shape the schema freezes.
+     * The document spells i64 for both classes (the frozen format-1
+     * vocabulary has no u64; u64 is the stricter compile-time obligation
+     * over the same wire spelling). */
     intify(ref, slotPath, loc) {
         const cls = this.intDeclared.get(slotPath);
         if (cls === undefined)
             return ref;
-        if (ref.kind !== "f64") {
-            throw new SidecarError(`the profile declares integer slot '${slotPath}' (${cls}), but that slot is not a plain number slot (it projects as '${ref.kind}')`, loc);
+        if (ref.kind === "f64") {
+            this.intConsumed.set(slotPath, cls);
+            return { kind: "i64" };
+        }
+        if (ref.kind === "optional" && ref.inner.kind === "f64") {
+            this.intConsumed.set(slotPath, cls);
+            return { kind: "optional", inner: { kind: "i64" } };
+        }
+        {
+            throw new SidecarError(`the profile declares integer slot '${slotPath}' (${cls}), but that slot is not a number or optional number slot (it projects as '${ref.kind}')`, loc);
         }
-        this.intConsumed.set(slotPath, cls);
-        return { kind: "i64" };
     }
     /** intify for a struct field (declared or synthesized), recording the
      * record-resolution fact the inference maps onto interned IR shapes. */
@@ -238,15 +257,123 @@ class Projector {
         const before = this.intConsumed.has(slotPath);
         const out = this.intify(ref, slotPath, loc);
         if (!before && this.intConsumed.has(slotPath)) {
-            this.intRecordFacts.push({
-                fieldNames: allFields,
+            this.pendingIntRecordFacts.push({
+                fields: allFields,
+                tagged: false,
                 targetField: field,
                 cls: this.intConsumed.get(slotPath),
                 path: slotPath,
+                loc,
             });
         }
         return out;
     }
+    /** Canonical union constructor mirroring the frontend: nested unions
+     * flatten, structurally repeated arms collapse, and one surviving arm is
+     * just that arm. */
+    irUnionPattern(arms) {
+        const flat = [];
+        for (const arm of arms) {
+            if (arm.kind === "union")
+                flat.push(...arm.arms);
+            else
+                flat.push(arm);
+        }
+        const unique = new Map();
+        for (const arm of flat)
+            unique.set(JSON.stringify(arm), arm);
+        const canonical = [...unique.entries()]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([, arm]) => arm);
+        if (canonical.length === 0)
+            throw new Error("sidecar pattern bug: empty union");
+        return canonical.length === 1 ? canonical[0] : { kind: "union", arms: canonical };
+    }
+    irFieldPattern(field) {
+        const inner = this.irTypePattern(field.shape, field.loc);
+        return field.optional
+            ? this.irUnionPattern([inner, { kind: "undefinedT" }])
+            : inner;
+    }
+    irRecordPattern(fields, tagged = false) {
+        const projected = fields.map((field) => ({
+            name: field.name,
+            type: this.irFieldPattern(field),
+        }));
+        if (tagged)
+            projected.push({ name: "kind", type: { kind: "string" } });
+        projected.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        return {
+            kind: "record",
+            fields: projected,
+            ...(tagged ? { kindMayBeOmitted: true } : {}),
+        };
+    }
+    /** Flatten a tagged union for IR identity, preserving every source
+     * constituent. This is deliberately separate from unionArms(): the
+     * sidecar's wire table is first-discriminant-name-wins, while the
+     * frontend's structural union interner retains later same-named arms
+     * whenever their payload shapes differ. irUnionPattern performs the
+     * frontend's structural deduplication after this walk. */
+    irTaggedArmPatterns(unionName, loc) {
+        return this.allUnionArms(unionName, loc).map((arm) => this.irRecordPattern(arm.fields, true));
+    }
+    /** Convert a sidecar-supported syntactic type into the exact structural
+     * IR pattern the frontend maps it to. Projection has already refused
+     * unsupported shapes before an integer fact is recorded, so the default
+     * cases are internal consistency checks. */
+    irTypePattern(shape, loc) {
+        switch (shape.k) {
+            case "number":
+                return { kind: "f64" };
+            case "text":
+            case "stringLit":
+                return { kind: "string" };
+            case "bool":
+                return { kind: "bool" };
+            case "bytes":
+                return { kind: "bytes", elem: "u8" };
+            case "absent":
+                return { kind: shape.unit === "null" ? "nullT" : "undefinedT" };
+            case "array":
+                return { kind: "array", elem: this.irTypePattern(shape.elem, loc) };
+            case "union":
+                return this.irUnionPattern(shape.parts.map((part) => this.irTypePattern(part, loc)));
+            case "object":
+                // A declared `{}` annotation is TypeScript's top non-nullish type,
+                // not the inferred shape of an empty object literal. The frontend
+                // therefore lowers it to dyn (types.ts's declared-empty rule).
+                return shape.fields.length === 0
+                    ? { kind: "dyn" }
+                    : this.irRecordPattern(shape.fields);
+            case "ref": {
+                const resolved = this.resolve(shape.name, loc);
+                if (resolved.c.c === "scalar")
+                    return this.irTypePattern(resolved.c.shape, loc);
+                if (resolved.c.c === "enum")
+                    return { kind: "string" };
+                if (resolved.c.c === "struct" && resolved.c.fields.length === 0) {
+                    return { kind: "dyn" };
+                }
+                if (this.irPatterning.has(resolved.name)) {
+                    throw new SidecarError(`the contract type graph is cyclic through '${resolved.name}' — recursive contract types cannot encode`, loc);
+                }
+                this.irPatterning.add(resolved.name);
+                try {
+                    return resolved.c.c === "struct"
+                        ? this.irRecordPattern(resolved.c.fields)
+                        : this.irUnionPattern(this.irTaggedArmPatterns(resolved.name, loc));
+                }
+                finally {
+                    this.irPatterning.delete(resolved.name);
+                }
+            }
+            case "void":
+            case "tuple":
+            case "unsupported":
+                throw new SidecarError(`an integer-slot record contains a shape outside the sidecar's structural vocabulary (${shape.k})`, loc);
+        }
+    }
     /** A declared slot path that the whole projection never spelled: the
      * path names nothing (or names a slot outside the schema's integer
      * grammar), and silently ignoring it would drop an ABI obligation. */
@@ -294,6 +421,17 @@ class Projector {
             cur = c.target;
         }
     }
+    /** Resolve only aliases whose names have no wire identity. Named
+     * records/enums/unions return null and retain their table projection. */
+    scalarShape(shape, loc) {
+        if (shape.k === "bool" || shape.k === "number" || shape.k === "text" || shape.k === "bytes") {
+            return shape;
+        }
+        if (shape.k !== "ref")
+            return null;
+        const resolved = this.resolve(shape.name, loc);
+        return resolved.c.c === "scalar" ? resolved.c.shape : null;
+    }
     /** A kind-tagged union's arms, its reference constituents flattened
      * DEPTH-FIRST IN SOURCE ORDER (the ask-3 composition rule, pinned by
      * conformance): an inline arm lands where it is spelled; a constituent
@@ -346,6 +484,113 @@ class Projector {
             this.flattening.delete(unionName);
         }
     }
+    /** Every source constituent of a composed tagged union, including later
+     * occurrences of an already-seen discriminant name. The wire table keeps
+     * first occurrence, but structural matching and integer obligations must
+     * retain all shapes the frontend can lower under that discriminant. */
+    allUnionArms(unionName, loc) {
+        const memo = this.allFlatArms.get(unionName);
+        if (memo !== undefined)
+            return memo;
+        if (this.allFlattening.has(unionName)) {
+            throw new SidecarError(`union composition is cyclic through '${unionName}' — a union cannot spread itself`, loc);
+        }
+        const c = this.lookup(unionName, loc);
+        if (c.c !== "tagged") {
+            throw new SidecarError(`'${unionName}' is not a kind-tagged union of object literals`, c.decl.loc);
+        }
+        this.allFlattening.add(unionName);
+        try {
+            const out = [];
+            for (const part of c.parts) {
+                if (part.p === "arm") {
+                    out.push({ name: part.name, fields: part.fields, loc: part.loc });
+                    continue;
+                }
+                const r = this.resolve(part.name, part.loc);
+                if (r.c.c !== "tagged") {
+                    throw new SidecarError(`constituent '${part.name}' of union '${unionName}' is not a kind-tagged union — only kind-tagged unions compose by reference`, part.loc);
+                }
+                out.push(...this.allUnionArms(r.name, part.loc));
+            }
+            this.allFlatArms.set(unionName, out);
+            return out;
+        }
+        finally {
+            this.allFlattening.delete(unionName);
+        }
+    }
+    /** Record one integer obligation for every lowered structural arm carrying
+     * the wire-selected discriminant. A composed union can repeat an arm name
+     * with a different payload field name; the sidecar's scalar descriptor
+     * omits that source name, so each compatible record shape must prove the
+     * same boundary slot. Incompatible later payloads refuse rather than let a
+     * non-integer value ride an integer-attested wire arm. */
+    recordIntegerUnionArmFacts(unionName, armName, intifiedRef, cls, path, loc) {
+        const selectedOptional = intifiedRef.kind === "optional" && intifiedRef.inner.kind === "i64";
+        if (intifiedRef.kind !== "i64" && !selectedOptional) {
+            throw new Error(`sidecar pattern bug: integer arm '${path}' has ref '${intifiedRef.kind}'`);
+        }
+        for (const arm of this.allUnionArms(unionName, loc)) {
+            if (arm.name !== armName)
+                continue;
+            if (arm.fields.length !== 1) {
+                throw new SidecarError(`integer slot '${path}' (${cls}) selects a scalar ${selectedOptional ? "optional " : ""}number payload, but another composed '${armName}' arm has ${arm.fields.length === 0 ? "no payload" : `${arm.fields.length} payload fields`}`, arm.loc);
+            }
+            const field = arm.fields[0];
+            const ref = this.fieldRef(field, unionName);
+            const candidateOptional = ref.kind === "optional" && ref.inner.kind === "f64";
+            if (ref.kind !== "f64" && !candidateOptional) {
+                throw new SidecarError(`integer slot '${path}' (${cls}) selects a scalar ${selectedOptional ? "optional " : ""}number payload, but another composed '${armName}' arm projects as '${ref.kind}'`, arm.loc);
+            }
+            if (!selectedOptional && candidateOptional) {
+                throw new SidecarError(`integer slot '${path}' (${cls}) selects a required number payload, but another composed '${armName}' arm makes that payload optional`, arm.loc);
+            }
+            this.pendingIntRecordFacts.push({
+                fields: arm.fields,
+                tagged: true,
+                targetField: field.name,
+                cls,
+                path,
+                loc: arm.loc,
+            });
+        }
+    }
+    /** Record a number_bytes obligation for every composed occurrence of the
+     * wire-selected discriminant. Unlike a scalar descriptor, number_bytes
+     * exposes both source field names, so a later same-named arm must retain
+     * those names and the required number-then-bytes family. Text and bytes
+     * are the same sidecar bytes payload but distinct IR shapes; compatible
+     * occurrences therefore each need their own structural inference fact. */
+    recordIntegerNumberBytesArmFacts(unionName, armName, numberField, bytesField, cls, path, loc) {
+        for (const arm of this.allUnionArms(unionName, loc)) {
+            if (arm.name !== armName)
+                continue;
+            const [number, bytes] = arm.fields;
+            const numberShape = number === undefined ? null : this.scalarShape(number.shape, number.loc);
+            const bytesShape = bytes === undefined ? null : this.scalarShape(bytes.shape, bytes.loc);
+            const compatible = arm.fields.length === 2 &&
+                number !== undefined &&
+                bytes !== undefined &&
+                !number.optional &&
+                !bytes.optional &&
+                number.name === numberField &&
+                bytes.name === bytesField &&
+                numberShape?.k === "number" &&
+                (bytesShape?.k === "text" || bytesShape?.k === "bytes");
+            if (!compatible) {
+                throw new SidecarError(`integer slot '${path}' (${cls}) selects number_bytes payload fields '${numberField}' and '${bytesField}', but another composed '${armName}' arm does not have the same required number-then-bytes fields`, arm.loc);
+            }
+            this.pendingIntRecordFacts.push({
+                fields: arm.fields,
+                tagged: true,
+                targetField: numberField,
+                cls,
+                path,
+                loc: arm.loc,
+            });
+        }
+    }
     /** Project a syntactic field to a TypeRef, tabling every named type it
      * references. `container`/`member` seed synthesized names. */
     fieldRef(field, container) {
@@ -380,9 +625,12 @@ class Projector {
                 throw new SidecarError(`'${container}.${member}' is an inline union — declare it as a named kind-tagged union (or a string-literal-union enum) and reference it by name`, loc);
             }
             case "ref": {
-                // Aliases are transparent: the table entry (and its order) is the
-                // ALIASED declaration's, under the aliased declaration's name.
+                // Scalar aliases dissolve to their underlying TypeRef. Named-type
+                // aliases remain transparent to the aliased table declaration.
                 const r = this.resolve(shape.name, loc);
+                if (r.c.c === "scalar") {
+                    return this.shapeRef(r.c.shape, container, member, loc);
+                }
                 if (r.c.c === "struct") {
                     this.tableNamed(r.name, loc);
                     return { kind: r.c.storage, name: r.name };
@@ -430,6 +678,11 @@ class Projector {
             this.tableNamed(this.resolve(name, loc).name, loc);
             return;
         }
+        if (c.c === "scalar") {
+            // Scalar aliases dissolve at their reference site and never have a
+            // type-table entry of their own.
+            return;
+        }
         this.inProgress.add(name);
         try {
             if (c.c === "enum") {
@@ -453,7 +706,7 @@ class Projector {
                     seen.add(f.name);
                     entry.fields.push({
                         name: f.name,
-                        type: this.intifyStructField(this.fieldRef(f, name), name, f.name, c.fields.map((x) => x.name), f.loc),
+                        type: this.intifyStructField(this.fieldRef(f, name), name, f.name, c.fields, f.loc),
                     });
                 }
                 this.table.set(name, { kind: "struct", entry, anchor: c.index, sub: -1 });
@@ -469,14 +722,7 @@ class Projector {
                 const before = this.intConsumed.has(slotPath);
                 payload = this.intify(payload, slotPath, arm.loc);
                 if (!before && this.intConsumed.has(slotPath)) {
-                    // The one intifiable arm shape is a single number payload
-                    // field; its IR record carries the 'kind' discriminant too.
-                    this.intRecordFacts.push({
-                        fieldNames: [...arm.fields.map((f) => f.name), "kind"],
-                        targetField: arm.fields[0].name,
-                        cls: this.intConsumed.get(slotPath),
-                        path: slotPath,
-                    });
+                    this.recordIntegerUnionArmFacts(name, arm.name, payload, this.intConsumed.get(slotPath), slotPath, arm.loc);
                 }
                 entry.arms.push({ name: arm.name, payload });
             }
@@ -518,7 +764,7 @@ class Projector {
             seen.add(f.name);
             entry.fields.push({
                 name: f.name,
-                type: this.intifyStructField(this.fieldRef(f, name), name, f.name, fields.map((x) => x.name), f.loc),
+                type: this.intifyStructField(this.fieldRef(f, name), name, f.name, fields, f.loc),
             });
         }
         return name;
@@ -530,43 +776,35 @@ class Projector {
             return { kind: "void" };
         if (fields.length === 2) {
             const [first, second] = [fields[0], fields[1]];
+            const firstShape = this.scalarShape(first.shape, first.loc);
+            const secondShape = this.scalarShape(second.shape, second.loc);
             // Family 4 covers exactly the number-first two-field record; a
             // bytes-first spelling takes the record family instead
             // (declaration order is semantic everywhere — the clarified rule).
             if (!first.optional &&
                 !second.optional &&
-                first.shape.k === "number" &&
-                (second.shape.k === "text" || second.shape.k === "bytes")) {
+                firstShape?.k === "number" &&
+                (secondShape?.k === "text" || secondShape?.k === "bytes")) {
                 // The number half is an ask-4 declarable slot:
                 // `<msg>.<arm>.<numberField>` (the schema's number_bytes path).
                 const slotPath = `${msgName}.${arm.name}.${first.name}`;
                 const numRef = this.intify({ kind: "f64" }, slotPath, first.loc);
                 if (numRef.kind === "i64") {
-                    this.intRecordFacts.push({
-                        fieldNames: [first.name, second.name, "kind"],
-                        targetField: first.name,
-                        cls: this.intConsumed.get(slotPath),
-                        path: slotPath,
-                    });
+                    this.recordIntegerNumberBytesArmFacts(msgName, arm.name, first.name, second.name, this.intConsumed.get(slotPath), slotPath, first.loc);
                 }
                 return { kind: "number_bytes", number_field: first.name, number_class: numRef.kind, bytes_field: second.name };
             }
         }
         if (fields.length === 1 && !fields[0].optional) {
             let ref = this.fieldRef(fields[0], msgName);
-            if (ref.kind === "f64") {
-                // A plain number payload is an ask-4 declarable slot: `<msg>.<arm>`.
-                const slotPath = `${msgName}.${arm.name}`;
-                const before = this.intConsumed.has(slotPath);
-                ref = this.intify(ref, slotPath, arm.loc);
-                if (!before && this.intConsumed.has(slotPath)) {
-                    this.intRecordFacts.push({
-                        fieldNames: [fields[0].name, "kind"],
-                        targetField: fields[0].name,
-                        cls: this.intConsumed.get(slotPath),
-                        path: slotPath,
-                    });
-                }
+            // A bare or optional number payload is an ask-4 declarable slot:
+            // `<msg>.<arm>`. Calling intify for every one-field family also makes
+            // a declaration targeting a non-number refuse at the precise arm.
+            const slotPath = `${msgName}.${arm.name}`;
+            const before = this.intConsumed.has(slotPath);
+            ref = this.intify(ref, slotPath, arm.loc);
+            if (!before && this.intConsumed.has(slotPath)) {
+                this.recordIntegerUnionArmFacts(msgName, arm.name, ref, this.intConsumed.get(slotPath), slotPath, arm.loc);
             }
             switch (ref.kind) {
                 case "bytes":
@@ -591,6 +829,14 @@ class Projector {
         // payload fields — tables a synthesized record (family 5).
         return { kind: "record", name: this.tableSynthesized(msgName, arm.name, fields, arm.loc) };
     }
+    /** Materialize structural join patterns only after normal sidecar
+     * projection has validated every field reachable from these facts. */
+    finishedIntRecordFacts() {
+        return this.pendingIntRecordFacts.map(({ fields, tagged, ...fact }) => ({
+            shape: this.irRecordPattern(fields, tagged),
+            ...fact,
+        }));
+    }
     /** The finished type table, each array in declaration order (synthesized
      * entries anchor at their containing declaration). */
     finishedTable() {
@@ -760,6 +1006,7 @@ export function buildSidecar(input) {
         // Every declared integer slot must have been spelled by now — the
         // whole contract (model, msg, helpers, channels) is projected.
         projector.checkIntConsumed();
+        const intRecordFacts = projector.finishedIntRecordFacts();
         const doc = {
             format: SIDECAR_FORMAT,
             wire_version: config.wireVersion,
@@ -818,7 +1065,7 @@ export function buildSidecar(input) {
             ok: true,
             doc,
             json: JSON.stringify(doc, null, 2) + "\n",
-            integerSlotFacts: { helpers: helperIntFacts, records: projector.intRecordFacts },
+            integerSlotFacts: { helpers: helperIntFacts, records: intRecordFacts },
         };
     }
     catch (e) {