@geastack/compiler 1.0.15

package/dist/representation/policies.js

@@ -0,0 +1,107 @@
+/** The ownership a carrier states about itself, or `null` for one that states none. */
+const ownershipOf = (value) => {
+    switch (value.kind) {
+        case 'class-ref':
+        case 'record':
+        case 'record-with-index':
+        case 'native-record-ref':
+        case 'array-object':
+        case 'dictionary':
+        case 'typed-array':
+        // A keyed collection states its own ownership like every other reference
+        // carrier above, and omitting it here was not neutral: `forParameter` then
+        // fell through to `'owned'`, so a `Set<number>` PARAMETER was spelled
+        // `gea::Set<double>` by value while every binding of one inside the body
+        // stayed `std::shared_ptr<gea::Set<double>>` -- the exact "parameter's
+        // carrier and its passing mode are two different answers to one question"
+        // failure this policy's own comment below describes, and it did not
+        // compile. Passing as held is also the only reading that preserves the
+        // reference semantics a JavaScript Map/Set has: a callee that adds an
+        // entry must be adding it to the caller's collection, not to a copy.
+        case 'keyed-collection':
+            return value.ownership;
+        default:
+            return null;
+    }
+};
+/**
+ * Shared ownership for references, by-value for everything else, and a
+ * parameter passed exactly as its carrier is held.
+ *
+ * Borrowing at parameter positions is an optimization, and it was one this
+ * layer had not earned: nothing here proves a callee does not retain what it
+ * was handed. Worse, it made a parameter's carrier and its passing mode two
+ * different answers to one question -- the value inside the body was a shared
+ * reference while the formal declaring it was a borrowed one -- so the body
+ * initialized a `shared_ptr` from a reference and the emitted C++ did not
+ * compile. Passing as held keeps one answer; a proven non-escaping parameter
+ * may be narrowed to `borrowed` later, on top of this, not instead of it.
+ */
+export const defaultOwnershipPolicy = {
+    forShape: () => 'shared-refcount',
+    forParameter: (value) => ownershipOf(value) ?? 'owned'
+};
+/** No value records: every record is a shared handle, exactly as before. */
+export const defaultValueRecordPolicy = {
+    forType: () => false
+};
+/** No bindings installed: every declared type falls through to its structural answer, unchanged. */
+export const defaultHostBindingPolicy = {
+    forDeclaration: () => null,
+    basesOf: () => []
+};
+/** No typed-array declarations installed: every declared type falls through to its ordinary answer, unchanged. */
+export const defaultTypedArrayElementPolicy = {
+    forDeclaration: () => null
+};
+/** No `Promise` declaration installed: every declared type falls through to its ordinary answer, unchanged. */
+export const defaultPromiseDeclarationPolicy = {
+    forDeclaration: () => false
+};
+/** No `Date` declaration installed: every declared type falls through to its ordinary answer, unchanged. */
+export const defaultDateDeclarationPolicy = {
+    forDeclaration: () => null
+};
+/** No `Generator` declaration installed: every declared type falls through to its ordinary answer, unchanged. */
+export const defaultGeneratorDeclarationPolicy = {
+    forDeclaration: () => false
+};
+/** No keyed-collection declarations installed: every declared type falls through to its ordinary answer, unchanged. */
+export const defaultKeyedCollectionPolicy = {
+    forDeclaration: () => null
+};
+/** No buffer declarations installed: every declared type falls through to its ordinary answer, unchanged. */
+export const defaultStandardBufferPolicy = {
+    forDeclaration: () => null
+};
+/** No `RegExp` declarations installed: every declared type falls through to its ordinary answer, unchanged. */
+export const defaultRegExpDeclarationPolicy = {
+    forDeclaration: () => null
+};
+/** No `String` declaration installed: every declared type falls through to its ordinary answer, unchanged. */
+export const defaultStringObjectDeclarationPolicy = {
+    forDeclaration: () => null
+};
+export const defaultErrorDeclarationPolicy = { forDeclaration: () => null };
+/** No `Function` declaration installed: every declared type falls through to its ordinary answer, unchanged. */
+export const defaultFunctionDeclarationPolicy = {
+    forDeclaration: () => false
+};
+/** No implementors installed: every interface derives its own structural body, exactly as before this policy existed. */
+export const defaultInterfaceImplementorPolicy = {
+    forDeclaration: () => []
+};
+/** No copies installed: every generic class is one physical class, named by its root. */
+export const defaultClassCopyPolicy = {
+    copiesOf: () => []
+};
+/** No heritage installed: every class reads as a base class, and no upcast or intersection reduction is proposed. */
+export const defaultClassHeritagePolicy = {
+    forDeclaration: () => [],
+    constructorSlotSubclassesOf: () => []
+};
+/** No namespace roots installed: every type falls through to its structural answer, unchanged. */
+export const defaultHostNamespaceRootPolicy = {
+    forType: () => null
+};
+export const defaultRecordLayoutPolicy = { forShape: () => null };

package/dist/representation/primitive-domain.d.ts

@@ -0,0 +1 @@
+export { primitiveDomainOf, sharedPrimitiveDomainOf } from '../semantics/model/primitive-domain.js';

package/dist/representation/primitive-domain.js

@@ -0,0 +1 @@
+export { primitiveDomainOf, sharedPrimitiveDomainOf } from '../semantics/model/primitive-domain.js';

package/dist/representation/primitives.d.ts

@@ -0,0 +1,44 @@
+import type { Representation } from './model.js';
+/**
+ * The lattice's bottom, carrying why it was reached.
+ *
+ * Not an answer: `unresolved` is what a deriver publishes when it has no
+ * carrier to name, and every consumer treats it as a gap to report rather than
+ * a storage decision to act on (`docs/ARCHITECTURE.md` invariant 3).
+ */
+export declare const unresolved: (reason: string) => Representation;
+/**
+ * The carrier a *stored* position holds, where `void` is a value.
+ *
+ * `void` is two different facts wearing one spelling. As a function's own
+ * result it means "this evaluation completes with no result", which occupies
+ * no storage and is C++'s own `void`. Anywhere a value is actually kept --
+ * a union arm, a parameter slot, a record field, an array element -- there is
+ * no such thing as a value that is not there: ECMAScript's answer is
+ * `undefined`, which is what a `void`-returning call evaluates to, what
+ * `Promise<void>.then` hands its callback, and what a `void[]` holds.
+ *
+ * Deriving `{kind: 'void'}` into those positions is what produced carriers no
+ * backend could spell -- `tagged-union(0:void|1:...)` for
+ * `TResult | PromiseLike<TResult>` at `TResult = void`, `array-object(void)`,
+ * `(void) -> void` for `Promise<void>`'s own `then` callback -- and seven
+ * corpus apps were refused for it. The refusal was right; the carrier was
+ * wrong.
+ *
+ * `never` maps to the same physical nothing and is converted with it, and that
+ * is sound for the same reason it is uninteresting: a slot typed `never` is
+ * never reached, so which empty carrier stands in its place is unobservable --
+ * `never[]` is the empty array literal, and `(event: never) => void` is a
+ * listener no call site can supply an argument for. What matters is that a
+ * position which must be able to hold something is given a carrier that can.
+ *
+ * The one place where `never` is NOT interchangeable is a union arm, and that
+ * is handled where it belongs: the union deriver drops `never` members before
+ * building any arm, because `T | never` is `T` and an arm for the empty type
+ * would be an arm nothing can ever be. Left in, `null | never` came out as a
+ * sum of two absences -- one flag, two meanings -- and a field that is plainly
+ * just `null` was refused.
+ */
+export declare const storedCarrier: (representation: Representation) => Representation;
+/** The carrier a primitive type name occupies, or `null` for a name that is not one. */
+export declare const primitiveCarrier: (primitive: string) => Representation | null;

package/dist/representation/primitives.js

@@ -0,0 +1,78 @@
+/**
+ * The lattice's bottom, carrying why it was reached.
+ *
+ * Not an answer: `unresolved` is what a deriver publishes when it has no
+ * carrier to name, and every consumer treats it as a gap to report rather than
+ * a storage decision to act on (`docs/ARCHITECTURE.md` invariant 3).
+ */
+export const unresolved = (reason) => ({ kind: 'unresolved', reason });
+/**
+ * The carrier a *stored* position holds, where `void` is a value.
+ *
+ * `void` is two different facts wearing one spelling. As a function's own
+ * result it means "this evaluation completes with no result", which occupies
+ * no storage and is C++'s own `void`. Anywhere a value is actually kept --
+ * a union arm, a parameter slot, a record field, an array element -- there is
+ * no such thing as a value that is not there: ECMAScript's answer is
+ * `undefined`, which is what a `void`-returning call evaluates to, what
+ * `Promise<void>.then` hands its callback, and what a `void[]` holds.
+ *
+ * Deriving `{kind: 'void'}` into those positions is what produced carriers no
+ * backend could spell -- `tagged-union(0:void|1:...)` for
+ * `TResult | PromiseLike<TResult>` at `TResult = void`, `array-object(void)`,
+ * `(void) -> void` for `Promise<void>`'s own `then` callback -- and seven
+ * corpus apps were refused for it. The refusal was right; the carrier was
+ * wrong.
+ *
+ * `never` maps to the same physical nothing and is converted with it, and that
+ * is sound for the same reason it is uninteresting: a slot typed `never` is
+ * never reached, so which empty carrier stands in its place is unobservable --
+ * `never[]` is the empty array literal, and `(event: never) => void` is a
+ * listener no call site can supply an argument for. What matters is that a
+ * position which must be able to hold something is given a carrier that can.
+ *
+ * The one place where `never` is NOT interchangeable is a union arm, and that
+ * is handled where it belongs: the union deriver drops `never` members before
+ * building any arm, because `T | never` is `T` and an arm for the empty type
+ * would be an arm nothing can ever be. Left in, `null | never` came out as a
+ * sum of two absences -- one flag, two meanings -- and a field that is plainly
+ * just `null` was refused.
+ */
+export const storedCarrier = (representation) => representation.kind === 'void' ? { kind: 'undefined' } : representation;
+/** The carrier a primitive type name occupies, or `null` for a name that is not one. */
+export const primitiveCarrier = (primitive) => {
+    switch (primitive) {
+        // `never` denotes a value that is never produced, so it carries nothing.
+        // That is not the same as `void`, which is a completed evaluation with no
+        // result -- but physically both occupy no storage, so both are the one
+        // carrier and `bottom` records which of the two facts this position holds.
+        // Only the decisions that turn on "can a value ever arrive here" read it
+        // (`Promise<never>` adopting into `Promise<T>`); every storage decision
+        // reads `kind` and cannot tell them apart, which is the point.
+        case 'never':
+            return { kind: 'void', bottom: true };
+        case 'void':
+            return { kind: 'void' };
+        case 'undefined':
+            return { kind: 'undefined' };
+        case 'null':
+            return { kind: 'null' };
+        case 'boolean':
+            return { kind: 'scalar', domain: 'boolean' };
+        case 'number':
+            return { kind: 'scalar', domain: 'number' };
+        case 'bigint':
+            return { kind: 'scalar', domain: 'bigint' };
+        case 'string':
+            return { kind: 'string' };
+        case 'symbol':
+            return { kind: 'symbol' };
+        // The program declared this value dynamic and never narrowed it. This is one
+        // of the four reasons the boxed carrier is admissible at all.
+        case 'unknown':
+        case 'any':
+            return { kind: 'dynamic', reason: 'declared-any-never-narrowed' };
+        default:
+            return null;
+    }
+};

package/dist/representation/publish.d.ts

@@ -0,0 +1,49 @@
+import type { ComponentId, FunctionId, StructuralTypeId } from '../identity/ids.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+import type { DateDeclarationPolicy, HostBindingPolicy, HostNamespaceRootPolicy, KeyedCollectionPolicy, OwnershipPolicy, PromiseDeclarationPolicy, GeneratorDeclarationPolicy, InterfaceImplementorPolicy, RegExpDeclarationPolicy, RepresentationDeriver, StandardBufferPolicy, StringObjectDeclarationPolicy, ErrorDeclarationPolicy, FunctionDeclarationPolicy, ClassHeritagePolicy, ClassCopyPolicy, TypedArrayElementPolicy, ValueRecordPolicy } from './derive.js';
+import type { RepresentationConflict, SealedRepresentationPlan } from './plan.js';
+import type { RepresentationViolation } from './verify.js';
+/**
+ * Turning a sealed semantic graph into a sealed representation plan.
+ *
+ * The order here is the mandatory publication order, and it is not an
+ * implementation detail: every carrier is published as evidence first, then each
+ * authority component selects once and commits, then the plan seals, then the
+ * guards run. Selecting while publication is still open is what creates the
+ * window in which one consumer reads a weaker answer than another.
+ *
+ * Components commit independently. A component whose carriers conflict commits
+ * nothing and is reported, but it does not veto the rest of the program -- that
+ * is the difference between a compiler that reports one defect and a compiler
+ * that reports "nothing worked".
+ */
+export interface RepresentationPublication {
+    readonly plan: SealedRepresentationPlan;
+    /** Components that committed, in deterministic order. */
+    readonly committed: readonly ComponentId[];
+    /** Components that selected nothing because their carriers disagreed. */
+    readonly blocked: readonly ComponentId[];
+    readonly conflicts: readonly RepresentationConflict[];
+    /** The complete guard violation set; empty means the plan is materializable. */
+    readonly violations: readonly RepresentationViolation[];
+    /**
+     * The deriver that produced this plan, handed out rather than rebuilt.
+     *
+     * A carrier is a function of a structural type *and* the policies this
+     * compilation supplied -- which declared types are host handles, which are
+     * typed-array views. Both policies come from the frontend's own census, so a
+     * deriver constructed anywhere else defaults them to `() => null` and answers
+     * a different question: measured on one 14-line fixture, a default-policy
+     * deriver disagreed with this one about **10 of 32** structural types,
+     * reading `typed-array(float32)` as `native-record-ref` and
+     * `native-handle(ArrayBuffer@1)` as `native-record-ref`.
+     *
+     * Emission needs shape-keyed answers the plan does not index by shape (a
+     * declared type's body is resolved from the structural table at emission --
+     * see `records.ts`), so it has to ask a deriver. It must be *this* one. Two
+     * instances are not "cheap and identical"; they are two authorities over
+     * what a type physically is, and the drift between them is silent.
+     */
+    readonly deriver: RepresentationDeriver;
+}
+export declare const publishRepresentations: (graph: SemanticGraph, ownership?: OwnershipPolicy, binding?: HostBindingPolicy, elements?: TypedArrayElementPolicy, promise?: PromiseDeclarationPolicy, collections?: KeyedCollectionPolicy, buffers?: StandardBufferPolicy, namespaceRoots?: HostNamespaceRootPolicy, date?: DateDeclarationPolicy, generator?: GeneratorDeclarationPolicy, regexp?: RegExpDeclarationPolicy, stringObject?: StringObjectDeclarationPolicy, functionType?: FunctionDeclarationPolicy, heritage?: ClassHeritagePolicy, valueRecords?: ValueRecordPolicy, implementors?: InterfaceImplementorPolicy, errors?: ErrorDeclarationPolicy, dynamicFallback?: boolean, dynamicFallbackTypes?: ReadonlySet<StructuralTypeId>, dynamicFallbackCallables?: ReadonlySet<FunctionId>, dynamicWrittenTypes?: ReadonlySet<StructuralTypeId>, classCopies?: ClassCopyPolicy) => RepresentationPublication;