@geastack/compiler 1.0.15

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

@@ -0,0 +1,280 @@
+import type { DeclarationId, StructuralTypeId } from '../../identity/ids.js';
+import type { AbiParameter, CallableAbi, Ownership, RecordField, Representation, ScalarDomain, TaggedUnionArm, TypedArrayElementDomain } from '../../representation/model.js';
+import type { ConstantLiteral } from '../../semantics/model/operands.js';
+export declare const sanitizeForCppIdentifier: (raw: string) => string;
+/** The emitted file-scope variable name for a binding cell a run-once region owns. */
+export declare const cppGlobalName: (declaration: DeclarationId) => string;
+/** The emitted struct name for a closed record shape (or a native record's own shape). The one authority other sections must also call. */
+export declare const cppRecordStructName: (shapeId: string) => string;
+/**
+ * The file-scope wrapper which closes one recursive native container equation.
+ *
+ * This is named from the sealed structural identity, never a source spelling:
+ * aliases can be anonymous or share a display name, while an interned id is
+ * the one fact derivation, verification, and every C++ use site agree names
+ * this one physical object type.
+ */
+export declare const cppRecursiveContainerName: (type: StructuralTypeId | string) => string;
+/**
+ * The emitted struct name for the typed fields an array-extending interface
+ * adds (`array-object.extension`). Named by the FIELDS' own identity --
+ * `arrayExtensionKey`, the same text the carrier's key carries -- hashed
+ * (FNV-1a, 64-bit, stable across runs) because a field list is not a C++
+ * identifier; two interfaces declaring the same fields over the same
+ * carriers share one struct, exactly as they share one carrier.
+ */
+export declare const cppArrayExtensionStructName: (extension: readonly RecordField[]) => string;
+/** The emitted variable name for one try statement's finally-clause scope guard, keyed by the region's own operation id so two in a function never collide. */
+export declare const cppFinallyGuardName: (region: string) => string;
+/** The slot one try statement parks an in-flight exception in while its finally clause runs; keyed the same way, and for the same reason, as the guard beside it. */
+export declare const cppFinallyPendingName: (region: string) => string;
+/**
+ * The emitted member name for a record field. Total: a JS property key is an
+ * arbitrary string, a C++ struct member is an identifier, and this is the one
+ * mapping between them.
+ *
+ * A tuple's slots are record fields keyed by their position -- `"0"`, `"1"` --
+ * because a position really is the key, and there is no separate tuple carrier
+ * by design. C++ has no such member name, so a positional key is spelled with
+ * the reserved `gea_` prefix rather than being prefixed ad hoc: `"0"` and a
+ * source property literally named `_0` would otherwise collide, and two
+ * distinct fields sharing one member is a silently wrong layout.
+ *
+ * A symbol-keyed field is the identical situation with a different shape of
+ * key: `derive.ts` publishes it as `sym(<declaration>)` rather than digits,
+ * and this is the one place that becomes `gea_sym_<mangled declaration>` --
+ * an ordinary struct member, not a runtime lookup, because a symbol key is a
+ * compile-time constant identity. Naming it by declaration id rather than by
+ * the symbol's own printable description is what keeps `{[Symbol.iterator]:
+ * f}` and `{"Symbol(Symbol.iterator)": f}` -- two different objects -- from
+ * ever mangling to the same member: the declaration id is stable identity,
+ * the description is not even unique (`Symbol('x')` and a second, unrelated
+ * `Symbol('x')` print identically and are still different symbols).
+ *
+ * A key that is already a C++ identifier, is not a reserved word, and is not
+ * inside this compiler's own `gea_` prefix passes through byte-for-byte, which
+ * is nearly every key any program writes: a member is named after the property
+ * it carries, so that reading the emitted struct against the source type is
+ * possible at all.
+ *
+ * Everything else is escaped into `gea_key_` -- a CSS class name used as a key
+ * (`counter-value`), a C++ keyword (`class`, `template`), a key that starts
+ * with a digit without spelling a position (`0x`), a non-ASCII key, the empty
+ * key, and any key already wearing the `gea_` prefix. Each of those used to
+ * throw. Throwing broke the contract `cppRecordDeclarations` states in
+ * `records.ts` -- "A gap here is reported, never thrown ... an exception
+ * escaping from there takes down a compilation that has a perfectly good
+ * report to give" -- and it was not even a gap to report: `{'counter-value':
+ * 1}` is ordinary, correct TypeScript, so a total spelling is what this
+ * function owes its callers rather than something it may decline to provide.
+ * Refusing by name would have been the fail-closed answer to a genuine gap;
+ * there is no gap here, only a name that has to be minted, and
+ * `escapeForCppMemberName` above carries the argument that minting it cannot
+ * collapse two properties into one member.
+ */
+/**
+ * Whether a record field key names a SYMBOL member rather than a string one.
+ *
+ * The two halves of a JavaScript object's key space are physically different
+ * at runtime -- `Object.keys` lists one and not the other -- and a dynamic
+ * `[[Get]]` arrives holding a `gea::Symbol` id minted while the program ran,
+ * which no compile-time declaration id can be compared against. So the field
+ * dispatcher `records.ts` renders has to know which of its fields it can match
+ * by text and which it cannot, and asking here rather than re-testing the
+ * `sym(...)` spelling in a second module keeps one authority over that marker.
+ */
+export declare const cppRecordFieldKeyIsSymbol: (key: string) => boolean;
+export declare const cppRecordFieldName: (key: string) => string;
+/**
+ * The presence bit paired with an optional record field.
+ *
+ * `RecordField.required` distinguishes a missing property from a property
+ * whose value is `undefined`; the value carrier cannot always do that (and an
+ * `optional<undefined | T>` must not be asked to).  Generated record structs
+ * therefore keep this independent bit.  The `gea_` prefix is collision-free
+ * with source members because `cppRecordFieldName` escapes every source key
+ * beginning with that reserved prefix.
+ */
+export declare const cppRecordFieldPresenceName: (key: string) => string;
+/**
+ * The environment a record carries for one accessor half whose body captures.
+ *
+ * An accessor occupies no storage for its VALUE -- that is what makes it an
+ * accessor -- but a getter written inside a function closes over that
+ * function's locals, and the only thing that can carry those to it is the
+ * object the getter is reached through. So a capturing accessor does occupy
+ * storage: one type-erased `gea::PackedEnvironment`, exactly what a
+ * `CallableObject` holds for the same reason, populated where the literal is
+ * allocated and read back at every call.
+ */
+export declare const cppRecordAccessorEnvironmentName: (key: string, half: "getter" | "setter") => string;
+/** The descriptor-attribute cell paired with one fixed native field. */
+export declare const cppRecordFieldAttributesName: (key: string) => string;
+/**
+ * The one spelling of `undefined` as a value.
+ *
+ * Both the constant path (a literal `undefined` in source) and `void`'s result
+ * name the same value, so they name it through the same constant rather than
+ * each spelling the struct themselves -- two places writing the same C++ text
+ * is exactly how the two drift apart when the runtime's spelling changes.
+ */
+export declare const cppUndefinedValue = "gea::Undefined{}";
+/**
+ * The value `undefined`, spelled into a carrier that can hold it -- `null` for
+ * one that cannot.
+ *
+ * Two sites ask this exact question and each used to answer it: an OMITTED
+ * argument (`emit-context.ts`, whose slot receives the `undefined` the language
+ * binds an unpassed parameter to, ECMA-262 10.2.11) and a `[[Get]]` of a key an
+ * object does not have (`emit-union-properties.ts`, 10.1.8 step 3). They are one
+ * question -- what is `undefined` in this carrier -- so they are one renderer.
+ *
+ * The four carriers that hold it, and no wider set: `undefined` itself; a
+ * `dynamic` box, which default-constructs to `Tag::Undefined`; an `optional`
+ * whose absence IS `undefined` (one spending its absence on `null` cannot);
+ * and a tagged union with an `undefined` ARM, named by index because a
+ * default-constructed union holds its FIRST arm, which need not be that one.
+ *
+ * Deliberately narrower than `carriesAbsence` below. That predicate answers
+ * "has an empty value that faults when used", which an empty `Ref<T>` does --
+ * but an empty `Ref` is a null pointer, not `undefined`, and handing one back
+ * for a property read would answer a program that compares the result to
+ * `undefined` with a crash instead of `true`.
+ */
+export declare const cppUndefinedIn: (representation: Representation) => string | null;
+export declare const cppConstantLiteral: (text: string, literal: ConstantLiteral, representation: Representation) => string;
+/** A literal view retains embedded NUL bytes without allocating or borrowing a temporary string. */
+export declare const cppStringViewLiteral: (content: string) => string;
+export declare const cppStringLiteral: (content: string) => string;
+/** The emitted class name for a nominal class declaration. */
+export declare const cppClassName: (declaration: DeclarationId) => string;
+/** The emitted function that performs one class's `[[Construct]]`: allocate, run field initializers, run the constructor body. */
+export declare const cppConstructName: (declaration: DeclarationId) => string;
+/**
+ * The emitted function that runs one class's initialization against an object
+ * that already exists -- the half of `[[Construct]]` after the allocation.
+ *
+ * `super(...)` needs exactly that half and no other: the derived construction
+ * allocated the object, and the base must initialize *it* rather than allocate
+ * a second one of its own type. Only a class some other class extends gets one
+ * emitted, because only such a class is ever initialized through a receiver it
+ * did not allocate.
+ */
+export declare const cppInitializeName: (declaration: DeclarationId) => string;
+/** The emitted function name for one executable body: a function, or a module/class-evaluation region. */
+export declare const cppBodyName: (owner: string) => string;
+/**
+ * The SOURCE DECLARATION a monomorphic copy belongs to: the owner id minus its
+ * `@N` copy ordinal.
+ *
+ * A generic function compiled for two instantiations is two bodies and two
+ * thunks, and it is still ONE JavaScript function object. `@N` is a copy
+ * ordinal, not a site, so stripping it is the whole of "which declaration is
+ * this". Anything that is not a trailing run of digits after the last `@` is
+ * left alone -- an owner that never had a copy ordinal is its own declaration.
+ */
+export declare const callableDeclarationOf: (owner: string) => string;
+/**
+ * The one program-wide object whose ADDRESS identifies a source declaration.
+ *
+ * `gea::identifyCallable<&X>` tags a callable with
+ * `detail::CallableDeclarationTag<X>`, documented in the runtime as "one
+ * program-wide address per emitted source declaration". Instantiating it on the
+ * per-COPY thunk pointer gave every copy its own tag, which is what made
+ * `stateStack[i] !== State.done` true forever in
+ * `generic-state-function-array.ts`. This name is shared by every copy of one
+ * declaration, so the tag finally is what its own comment says.
+ */
+export declare const cppCallableDeclarationTagName: (owner: string) => string;
+/** The one static module-record accessor for a resolved CommonJS module body. */
+export declare const cppCommonJsModuleName: (owner: string) => string;
+export declare const cppCommonJsRecordName: (owner: string) => string;
+export declare const cppScalarType: (domain: ScalarDomain | TypedArrayElementDomain) => string;
+/**
+ * A parameter's ownership replaces the carrier's own, it does not stack on top
+ * of it. The two state different facts -- how the value is stored versus how it
+ * is passed -- and applying both spells `std::shared_ptr<std::shared_ptr<T>>`
+ * for a shared record passed by shared reference: valid C++, and wrong.
+ *
+ * This is the one spelling of a formal, and the body's own declaration of the
+ * value it reads out of that formal must use it too. When the two were spelled
+ * separately -- the formal from the ABI's passing mode, the local from the
+ * carrier's storage -- they disagreed for every reference parameter.
+ */
+export declare const cppAbiParameterType: (parameter: AbiParameter) => string;
+/**
+ * Whether a receiver's carrier is a refcounted handle.
+ *
+ * A body that takes one BY VALUE increments and decrements a count on every
+ * call, for an object the caller already holds for the whole call -- so the
+ * count buys nothing and sits on the hot path of every method. Measured on
+ * `bench/comparison/fixtures/method_calls.ts`: 31.9ms taking the receiver by
+ * value, 15.9ms taking it by reference, against 19.0ms for the hand-written
+ * baseline whose receiver is a stack object.
+ *
+ * The ABI is untouched -- a `CallableObject` still stores the by-value
+ * convention every caller agrees on -- so this is the BODY's spelling only, the
+ * same split `formalsOf`'s `narrowed` makes.
+ */
+export declare const cppRefcountedReceiver: (representation: Representation) => boolean;
+/**
+ * A result position, where `void` is a real spelling rather than an error.
+ *
+ * `cppTypeOf` refuses `void` because no *value* can be carried by it, and that
+ * refusal is correct everywhere a value is stored. A function's return type is
+ * the one position where "carries nothing" is expressible in C++, and routing
+ * it through `cppTypeOf` made every `void`-returning callable unspellable --
+ * which read as a missing physical type for the whole carrier.
+ */
+export declare const cppResultTypeOf: (representation: Representation) => string;
+/**
+ * A broad source `Function` still carries a Value because it has no static
+ * callable ABI, but inside a typed sum it is not that sum's dynamic remainder.
+ * Give that arm a distinct physical type so runtime union admission can retain
+ * its checker-published Function-tag discriminator after Representation facts
+ * are no longer available to the C++ adapter.
+ */
+export declare const cppTaggedUnionArmType: (arm: TaggedUnionArm) => string;
+/**
+ * The calling convention as a C++ function-type spelling: result first, then
+ * the receiver (if any) as the first formal, then the declared parameters --
+ * mirroring `abiKey` in `representation/model.ts`, which keys this exact
+ * shape for plan-conflict detection. `function`/`function-family`/
+ * `constructor-family`/`function-value-family`/`function-value-dispatch` all
+ * carry one `CallableAbi` and therefore all resolve through this one helper.
+ */
+export declare const cppAbiType: (abi: CallableAbi) => string;
+export declare const beginUnionAliasing: () => void;
+/** The aliases recorded since `beginUnionAliasing`, in declaration order, and the end of aliasing. */
+export declare const endUnionAliasing: () => readonly {
+    readonly name: string;
+    readonly spelling: string;
+}[];
+export declare const cppTypeOf: (representation: Representation, ownership?: Ownership | null) => string;
+/**
+ * The C++ carrier for a captured cell this backend shares by aliasing rather
+ * than by copying (`emit-context.ts`'s `CaptureSlot.boxed`): a heap-allocated,
+ * reference-counted box every frame that touches the declaration -- the frame
+ * that owns it and every closure that captures it -- holds a copy of the same
+ * pointer to, reading and writing through one dereference.
+ *
+ * `std::shared_ptr`, not a bespoke cell type: it is the same reference-counted
+ * ownership `cppOwnershipWrap`'s `'shared-refcount'` arm already grants a
+ * record, class instance, or array -- copying the pointer aliases the same
+ * allocation, which is exactly the sharing a captured, mutated JavaScript
+ * binding needs. This is a distinct spelling from that wrap on purpose: a
+ * boxed cell's OWN representation can be a plain scalar (`aspectScale:
+ * number`) that has no `ownership` field of its own to override, so this
+ * wraps the whole physical type `cppTypeOf` already spells for it instead of
+ * threading a second, representation-shaped ownership parameter through.
+ */
+/**
+ * The integer a narrowed `number` is held in.
+ *
+ * 64 bits rather than 32: the values this narrowing admits are bounded by 2^53
+ * or grow with a loop's trip count, and both overflow an `int`. A `long long`
+ * holds every integer a double can hold exactly, so the narrowed and the
+ * unnarrowed form agree everywhere the census says they do.
+ */
+export declare const cppNarrowedIntegerType = "long long";
+export declare const cppBoxedType: (representation: Representation) => string;