@geastack/compiler 1.0.15

package/dist/targets/cpp/records.d.ts

@@ -0,0 +1,277 @@
+import type { DeclarationId, FunctionId } from '../../identity/ids.js';
+import type { ClassLayout } from '../../projection/classes.js';
+import { declaredFieldRepresentationOf, declaredRecordFieldOf, nativeBaseFieldOf, recordAccessorBodiesOf, recordAccessorsOfShape, recordFieldsOfShape } from '../../projection/fields.js';
+export { declaredFieldRepresentationOf, declaredRecordFieldOf, nativeBaseFieldOf, recordAccessorBodiesOf, recordAccessorsOfShape, recordFieldsOfShape };
+import type { ClassStaticFieldStorage } from './class-layout.js';
+import type { ReactiveCellPlan } from './host/host-members.js';
+import type { RepresentationDeriver } from '../../representation/derive.js';
+import type { RecordIndexSidecar, Representation } from '../../representation/model.js';
+import type { SealedRepresentationPlan } from '../../representation/plan.js';
+import type { ReflectionExposure } from '../../ir/reflection-demand.js';
+/**
+ * The value carrier of a struct's dynamic-property sidecar, plus its key
+ * domain. The representation model owns this pair; this module only re-exports
+ * the type alongside the layout helpers that consume it.
+ */
+export type { RecordIndexSidecar } from '../../representation/model.js';
+/** One struct whose layout could not be rendered, named by the struct rather than by a semantic owner it has none of. */
+export interface CppRecordRefusal {
+    readonly structName: string;
+    readonly reason: string;
+}
+/**
+ * The one shape a class's struct is built from, by struct name.
+ *
+ * A class's C++ struct is named by its DECLARATION (`cppClassName`), and the
+ * projection collapses a generic class's copies onto one declaration
+ * (`projection/classes.ts`'s `collapseSpecializations`). Its `class-ref`
+ * carriers, however, still name whichever instance SHAPE the site that built
+ * them derived -- an uninstantiated root's `Context<E>` and a monomorphized
+ * copy's `Context<{ ... }>` are two shapes under one struct name.
+ *
+ * `collectRequiredStructs`'s cycle guard then rendered the struct from
+ * whichever of them the plan happened to walk first, and every operation typed
+ * against the other one compiled against members that were not there: hono's
+ * `Context.env` was declared `gea::Value` from the unbound root while its own
+ * constructor stored an `Optional<Ref<...>>` into it, and clang rejected the
+ * assignment. Silently, from the compiler's side -- both halves certified.
+ *
+ * `ClassLayout.instance` is already the authority for the OTHER half of this
+ * question: `classBaseLinks` above subtracts a base's members using the base
+ * class's instance shape, not whatever shape a `class-ref` to it carried. This
+ * makes the struct itself, and every field lookup against it, read the same
+ * one, so a class has exactly one layout everywhere.
+ */
+export declare const classInstanceShapes: (classes: ReadonlyMap<DeclarationId, Pick<ClassLayout, "declaration" | "instance">>) => ReadonlyMap<string, string>;
+/**
+ * Whether a representation names any struct this compilation mints --
+ * `gea_record_*` or `gea_class_*`, from `cppRecordStructName`/`cppClassName`
+ * above -- anywhere in its type, including nested inside a callable ABI, a
+ * collection element, or an optional/union payload.
+ *
+ * `translation-unit.ts` asks this of a cell's `extern`/absent declaration to
+ * decide whether the declaration can be hoisted ahead of the unnamed
+ * namespace an isolated unit wraps its definitions in: a struct minted by
+ * this compilation is defined INSIDE that namespace, so a declaration naming
+ * one cannot be placed ahead of it. The question is answered by walking the
+ * representation `visitRepresentation` already walks for struct dependency
+ * ordering -- the same one, not a second one -- rather than by searching the
+ * declaration's own rendered C++ text for the name prefixes, which is a
+ * source-shaped approximation of a fact this compilation already knows from
+ * the representation it rendered that text from. A `native-record-ref` with a
+ * stated `.native` name is excluded by `visitRepresentation` itself (it never
+ * calls back for one), which is correct here too: that struct is the host's,
+ * declared in a header already included, not one this compilation defines.
+ */
+export declare const representationNamesMintedStruct: (representation: Representation) => boolean;
+/**
+ * The struct name a carrier IS, when holding one by value embeds it.
+ *
+ * `native-record-ref` with a stated `native` name is the host's own struct and
+ * this module emits no definition for it, so it can never be a name this order
+ * has to place.
+ */
+export declare const cppStructNameOf: (representation: Representation) => string | null;
+/**
+ * A shape's own dynamic-property sidecars, or an empty list when its layout
+ * has none.
+ *
+ * `native-record-ref` (model.ts) names a shape rather than carrying its own
+ * `indexes` inline the way `record-with-index` does -- it is a
+ * reference, resolved by `recordLayoutOfShape` exactly as
+ * `recordFieldsOfShape` already resolves the named half. A computed-key
+ * `[[Get]]`/`[[Set]]` on a `native-record-ref` receiver (`emit-properties.ts`)
+ * needs this to find the identical sidecar members `renderStructDefinition`
+ * gives the struct when its shape has index
+ * signatures -- an `ArrayLike<number>`-shaped interface (`{ length: number;
+ * [index: number]: number }`) derives `native-record-ref` here the same way
+ * any other named interface does, and its computed reads have nowhere else to
+ * go. An empty result is not a gap to fill: there is no sidecar member to route
+ * to, and `preflight/run.ts` checks this same
+ * question per site before certifying one (see its own comment for why an
+ * unconditional claim would over-claim).
+ */
+export declare const recordIndexesOfShape: (deriver: RepresentationDeriver, shapeId: string) => readonly RecordIndexSidecar[];
+/**
+ * The reserved member name for a record's dynamic-property sidecar.
+ *
+ * `cppRecordFieldName` (types.ts) throws for any source key inside the
+ * `gea_` prefix, so no field a program actually declares can collide with
+ * this name -- the sidecar and an ordinary field are drawn from disjoint
+ * namespaces by construction, not by hoping no one names a property this.
+ */
+export declare const cppRecordIndexSidecarName = "gea_dynamic";
+/** Domain-specific name when a record carries both text and symbol tables. */
+export declare const cppRecordIndexSidecarNameFor: (index: RecordIndexSidecar, indexes: readonly RecordIndexSidecar[]) => string;
+/**
+ * Attribute state for entries in `gea_dynamic`.
+ *
+ * The index dictionary deliberately remains typed: this companion table holds
+ * only the three data-property bits that an ordinary assignment cannot carry.
+ * It is therefore not a second value store and cannot turn an indexed record
+ * into a boxed object merely because one entry is non-enumerable or sealed.
+ */
+export declare const cppRecordIndexAttributesName = "gea_dynamic_attributes";
+export declare const cppRecordIndexAttributesNameFor: (index: RecordIndexSidecar, indexes: readonly RecordIndexSidecar[]) => string;
+export declare const enumerationOrdered: <T>(entries: readonly T[], keyOf: (entry: T) => string) => readonly T[];
+/**
+ * The same hook declaration with every parameter its body never reads left
+ * UNNAMED.
+ *
+ * A protocol hook ignores its parameters entirely or reads them all, according
+ * to what the record declares -- a struct with no index properties reads none
+ * of `gea_ownIndexPresent`'s. Both the declaration and the body are generated
+ * side by side here, so the body's own text is the only authority on which
+ * names it reads: there is no earlier fact to consult, because the body is
+ * already rendered C++ by the time the two meet. C++ spells "deliberately
+ * unused" by omitting the name, which is the same reason `nameOf` above
+ * withholds `gea_name` from a hook with no fields.
+ *
+ * Only the emitter's own `gea_`-prefixed names are touched, so a parameter
+ * this file did not name is left exactly as written.
+ */
+export declare const withUnreadParametersUnnamed: (declaration: string, body: readonly string[]) => string;
+/**
+ * The C++ storage one field of this struct occupies.
+ *
+ * Ordinarily that is exactly the carrier's own type. A field the installed
+ * plugin marked reactive is instead held in that plugin's cell, wrapping the
+ * SAME carrier -- `Signal<double>` for a `double`, never a box. The cell is
+ * storage and nothing else: it converts to `const T&` on read and assigns on
+ * write, so every read and write this emitter renders keeps the spelling it
+ * had, and no value in the program becomes dynamic. That is the whole reason a
+ * cell is admissible under the no-boxing rule where a `gea::Value` would not
+ * be.
+ *
+ * Only three carriers are celled, and the restriction is the cell's own
+ * requirements rather than a policy: it default-constructs its value, copy-
+ * assigns it, and compares it with `==` to skip a no-op write. A number, a
+ * boolean and a string all satisfy that. An array, a record, a handle or a
+ * class reference may not -- a `std::shared_ptr` compares by identity, so a
+ * mutation through it would compare EQUAL to itself and notify nobody, which
+ * is a silent failure to re-render rather than a loud one. Those fields stay
+ * plain members here; a template that reads one is refused by name at the JSX
+ * site (`emit-jsx.ts`) rather than being wired to a cell that cannot tell it
+ * changed.
+ */
+export declare const representationCanCell: (representation: Representation) => boolean;
+/**
+ * The companion revision cell a reactive field gets when its own carrier
+ * cannot be a cell.
+ *
+ * `count = 0` becomes `Signal<double> count` and every write notifies through
+ * the cell itself. `cells = [...]` cannot: the cell compares with `==` to skip
+ * unchanged writes, and a `shared_ptr` to a vector compares equal to itself
+ * after the vector is mutated, so it would notify nobody. v1 hit this and
+ * answered it by leaving the vector a plain member and declaring a companion
+ * `<field>__rev` Signal beside it that mutations tick
+ * (`cpp-reactive-component.ts`'s `arrayRevFieldName`); this is that answer,
+ * emitted rather than spliced into generated text.
+ *
+ * `cppRecordFieldName` throws for any source key in the `gea_` prefix, and a
+ * TypeScript identifier cannot contain `__rev` as a suffix without being a
+ * different key -- but a program CAN declare both `cells` and `cells__rev`, so
+ * the two would collide. That is a real, narrow collision and it is left
+ * visible rather than papered over with a mangled name nothing else can spell:
+ * the emitter names this member from this one function, so a future guard has
+ * exactly one place to check.
+ */
+export declare const cppReactiveRevisionFieldName: (key: string) => string;
+/**
+ * Every struct definition the selected carriers require, in a deterministic
+ * order, plus the ones no layout could be rendered for.
+ *
+ * A gap here is reported, never thrown. A struct is required by every carrier
+ * that names it, so a missing layout is discovered in the middle of assembling
+ * a file -- and an exception escaping from there takes down a compilation that
+ * has a perfectly good report to give, which is the same objection
+ * `renderTranslationUnit` already answers for a refused body.
+ */
+export declare const cppRecordDeclarations: (plan: SealedRepresentationPlan, deriver: RepresentationDeriver, classes: ReadonlyMap<DeclarationId, ClassLayout>, reactive: ReactiveCellPlan, 
+/** Which record members a JSX slot binds -- `reactiveBoundRecordFields`. */
+boundRecordFields: ReadonlyMap<string, ReadonlySet<string>>, 
+/** Dispatch member declarations by struct name -- `virtualMethodEmission().membersByStruct`. */
+virtualMembersByStruct?: ReadonlyMap<string, readonly string[]>, 
+/** The members that may be declared `long long` -- `integerStorageCensusOf().slots`. */
+narrowedSlots?: ReadonlySet<string>, 
+/**
+ * The frontend's declaration-identity census of `SymbolConstructor`'s own
+ * members (`host-protocols.ts`'s `wellKnownSymbolDeclarationsOf`) -- what
+ * lets a symbol-keyed field's dispatcher tell `Symbol.iterator` and its
+ * fourteen siblings, whose runtime identity is fixed at a known low id,
+ * apart from a genuinely unique symbol whose id only exists once the
+ * program runs. See `wellKnownSymbolEnumNameOf`.
+ */
+wellKnownSymbols?: ReadonlyMap<DeclarationId, string>, splitFieldDefinitions?: boolean, reflection?: ReflectionExposure, representations?: readonly Representation[], physicalClasses?: ReadonlyMap<DeclarationId, Pick<ClassLayout, "declaration" | "base" | "nativeBase" | "instance" | "nativeStorage">>, 
+/**
+ * Whether an accessor body carries an environment -- `captures.ts`'s
+ * admission, asked rather than re-derived, so the member this struct
+ * declares and the formal that body takes cannot come apart.
+ */
+accessorCarriesEnvironment?: (body: FunctionId) => boolean, 
+/** `program-facts.ts`'s `fixedFieldStateConstant` -- see `renderStructDefinition`'s parameter of the same name. */
+fixedFieldStateConstant?: boolean, 
+/** `program-facts.ts`'s `singleEvaluationClasses` -- which classes may hold their method state statically. */
+singleEvaluationClasses?: ReadonlySet<DeclarationId>) => {
+    readonly declarations: readonly string[];
+    readonly fieldDefinitionsByStruct: ReadonlyMap<string, readonly string[]>;
+    /**
+     * The classes whose struct holds `gea_method_state` as a STATIC member --
+     * this renderer's decision, reported so the construct function fills the
+     * static in rather than a member the struct does not have.
+     */
+    readonly staticMethodStateClasses: ReadonlySet<DeclarationId>;
+    /** Authenticated program-class ancestry; the translation unit owns namespace placement. */
+    readonly runtimeClassBases: readonly {
+        readonly derived: string;
+        readonly base: string;
+    }[];
+    readonly refused: readonly CppRecordRefusal[];
+    /**
+     * Which reactive fields got the COMPANION revision cell rather than a cell of
+     * their own -- this renderer's own decision, reported so the emitter
+     * subscribes to the member that actually exists.
+     *
+     * Reported rather than recomputed because the decision is
+     * `representationCanCell` applied to the field's carrier as this layout
+     * states it, and a second reader deriving that carrier its own way is exactly
+     * the two-authorities shape that produces a member pointer to a member the
+     * struct does not have.
+     */
+    readonly revisionFields: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Which struct members this renderer actually put in a `Signal<T>`, by struct name. */
+    readonly celledFields: ReadonlyMap<string, ReadonlySet<string>>;
+};
+/**
+ * Real `static` storage for the whole program's `ClassName.KEY = value`
+ * sites (`class-layout.ts`'s `censusClassStaticFieldStorage`), as bare
+ * translation-unit-scope definitions -- zero-initialized, exactly the way
+ * `translation-unit.ts`'s own `globalDefinitions` declares a module-scope
+ * cell's storage. A bare definition rather than one with an inline
+ * initializer on purpose: the ACTUAL value (`new Vector3(0, 1, 0)`, a
+ * `WeakMap`-closed-over reference, ...) is whatever expression the source
+ * assignment itself computed, and that expression already runs -- once, at
+ * the point the enclosing module body reaches that statement -- through the
+ * ordinary `[[Set]]` this storage exists to give a home to. Initializing it a
+ * second time here would run that expression twice, or (for one with a
+ * side effect, or one that reads another module-scope cell not yet set)
+ * run it too EARLY.
+ *
+ * Emitted after every struct declaration and before any body, mirroring
+ * `translation-unit.ts`'s own ordering for `globalDefinitions`: a static
+ * whose declared carrier is itself a struct (`Object3D.DEFAULT_UP`'s
+ * `Vector3`) needs that struct to already be a complete type.
+ *
+ * Sorted by name for the same reason every other whole-program list in this
+ * file is: byte-identical output from one compile to the next, so a diff
+ * between two builds is never just iteration order.
+ */
+export declare const classStaticFieldDefinitions: (storage: ReadonlyMap<DeclarationId, ReadonlyMap<string, ClassStaticFieldStorage>>) => readonly string[];
+/**
+ * The same storage as (type, name) pairs, for a layout that has to spell each
+ * one twice -- `extern` in a shared header, defined in exactly one unit.
+ */
+export declare const classStaticFieldStorageRows: (storage: ReadonlyMap<DeclarationId, ReadonlyMap<string, ClassStaticFieldStorage>>) => readonly {
+    readonly type: string;
+    readonly name: string;
+}[];