@felixdrp/gcf-wasm 0.0.0-stage → 0.1.0

package/dist/host.d.ts

@@ -0,0 +1,330 @@
+/** Every engine failure carries the spec's error category (e.g. "count_mismatch"). */
+export declare class GcfError extends Error {
+    readonly code: string;
+    readonly detail: string;
+    readonly line: number;
+    constructor(code: string, detail: string, line: number);
+}
+/** @deprecated alias kept for older imports. */
+export declare const GcfDecodeError: typeof GcfError;
+export type GcfDecodeError = GcfError;
+/**
+ * Policy for integers beyond ±(2^53-1), which a JS number cannot hold
+ * exactly (SPEC §2.3.2). Default `'error'`.
+ */
+export type LargeIntMode = "error" | "string" | "bigint" | "number";
+export interface DecodeOptions {
+    largeInt?: LargeIntMode;
+}
+export interface EncodeOptions {
+    /** Do not promote fixed-shape nested objects to `a>b` path columns. */
+    noFlatten?: boolean;
+}
+export interface BytesOptions {
+    /**
+     * Return a zero-copy view into the engine's memory instead of a copy. The
+     * view is only valid until the next call on the same codec (the arena is
+     * reset and the memory may grow). Default: false (an owned copy).
+     */
+    view?: boolean;
+}
+export interface GraphSymbol {
+    qualifiedName: string;
+    kind: string;
+    score: number;
+    provenance: string;
+    distance: number;
+}
+export interface GraphEdge {
+    source: string;
+    target: string;
+    edgeType: string;
+    status?: string;
+}
+export interface GraphPayload {
+    tool?: string;
+    tokenBudget?: number;
+    tokensUsed?: number;
+    packRoot?: string;
+    symbols: GraphSymbol[];
+    edges: GraphEdge[];
+}
+export interface GraphDelta {
+    tool?: string;
+    baseRoot: string;
+    newRoot: string;
+    removed: Pick<GraphSymbol, "qualifiedName" | "kind">[];
+    added: (Omit<GraphSymbol, "distance"> & {
+        distance?: number;
+    })[];
+    removedEdges: GraphEdge[];
+    addedEdges: GraphEdge[];
+    deltaTokens?: number;
+    fullTokens?: number;
+}
+/** A keyed record set for generic delta encoding (SPEC §10a). */
+export interface GenericSet {
+    name?: string;
+    key: string;
+    fields: string[];
+    rows: Record<string, unknown>[];
+}
+export interface GenericDelta {
+    tool?: string;
+    key: string;
+    fields: string[];
+    baseRoot: string;
+    newRoot: string;
+    added?: Record<string, unknown>[];
+    changed?: Record<string, unknown>[];
+    removed?: unknown[];
+    deltaTokens?: number;
+    fullTokens?: number;
+}
+interface Exports {
+    memory: WebAssembly.Memory;
+    gcf_input_alloc(len: number): number;
+    gcf_decode(len: number): number;
+    gcf_decode_graph_columns(len: number): number;
+    gcf_decode_tape(len: number): number;
+    gcf_encode(len: number, flags: number): number;
+    gcf_encode_graph(len: number): number;
+    /** WAT build only (feature-detected): columnar graph input written by the host. */
+    gcf_encode_graph_cols?: (len: number) => number;
+    /** WAT build only: optional features (bit 0 graph columns, bit 1 JS-host numbers in gcf_encode). */
+    gcf_features?: () => number;
+    gcf_encode_graph_session(len: number): number;
+    gcf_encode_graph_delta(len: number): number;
+    gcf_encode_generic_full(len: number): number;
+    gcf_encode_generic_delta(len: number): number;
+    gcf_generic_diff(len: number): number;
+    gcf_encode_grouped(len: number): number;
+    gcf_pack_root(len: number): number;
+    gcf_delta_verify(len: number): number;
+    gcf_delta_decode_apply(len: number): number;
+    gcf_graph_delta_apply(len: number): number;
+    gcf_output_ptr(): number;
+    gcf_output_len(): number;
+    gcf_output_unsafe_ints(): number;
+    gcf_error_name_ptr(): number;
+    gcf_error_name_len(): number;
+    gcf_error_message_ptr(): number;
+    gcf_error_message_len(): number;
+    gcf_error_line(): number;
+}
+type Columns = {
+    tool: string;
+    tokenBudget: number;
+    tokensUsed: number;
+    packRoot: string;
+    unchanged?: boolean;
+    session?: boolean;
+    names: string[];
+    kinds: string[];
+    provs: string[];
+    types: string[];
+    statuses: string[];
+    k: number[];
+    p: number[];
+    s: number[];
+    d: number[];
+    es: number[];
+    et: number[];
+    ty: number[];
+    st: number[];
+    references?: number[];
+};
+export declare class GcfCodec {
+    readonly exports: Exports;
+    private constructor();
+    static instantiate(wasm: BufferSource | WebAssembly.Module): Promise<GcfCodec>;
+    /** Copy the input into the engine's arena and return its byte length. */
+    private load;
+    private output;
+    /** Raw output bytes: an owned copy, or a view valid until the next call. */
+    private outputBytes;
+    private run;
+    /** JSON.parse with the large-integer policy applied (SPEC §2.3.2). */
+    private parse;
+    /** Decode to the spec-shaped JSON text (exact integers, no policy needed). */
+    decodeToJson(input: string | Uint8Array): string;
+    /** Decode to a JS value. */
+    decode(input: string | Uint8Array, opts?: DecodeOptions): unknown;
+    /**
+     * Lazy decode: returns objects and arrays that look and behave like plain
+     * JS values (property access, `Object.keys`, iteration, `JSON.stringify`)
+     * but convert each value only when it is read. The engine writes a compact
+     * binary tape (numbers in binary, strings in a byte pool, keys interned)
+     * that is copied out of wasm memory, so the result stays valid after later
+     * codec calls. Use it when you read part of a document; `toPlain(value)`
+     * converts a lazy value (or any sub-tree) into ordinary JS objects.
+     */
+    decodeLazy(input: string | Uint8Array, opts?: DecodeOptions): unknown;
+    /** Rebuild `{tool, tokenBudget, tokensUsed, packRoot, ..., symbols, edges}`. */
+    static graphFromColumns(c: Columns): unknown;
+    /** JSON bytes (UTF-8) -> GCF bytes. `profile: "graph"` for graph payloads. */
+    encodeJsonBytes(json: Uint8Array | string, opts?: EncodeOptions & BytesOptions & {
+        profile?: "generic" | "graph";
+    }): Uint8Array;
+    /** GCF bytes -> spec-shaped JSON bytes (exact integers, no policy needed). */
+    decodeToJsonBytes(gcf: Uint8Array | string, opts?: BytesOptions): Uint8Array;
+    /** Encode any JSON value (object, array or scalar) as generic-profile GCF. */
+    encode(value: unknown, opts?: EncodeOptions): string;
+    /**
+     * Encode JSON *text*. Use this when key order matters exactly: JS objects
+     * move integer-like keys ("5", "3") to the front, JSON text does not.
+     */
+    encodeJson(json: string, opts?: EncodeOptions): string;
+    /** Graph payload (buffered, canonical ordering, SPEC §16.1). */
+    encodeGraph(payload: GraphPayload): string;
+    /**
+     * Write the graph as columns into wasm memory (layout: gcf_encode_graph_cols
+     * in src/wat/13_graph_enc.wat): a 48-byte header, 40 bytes per symbol
+     * (score, distance as f64; qualifiedName, kind, provenance as string
+     * offset/length), 32 bytes per edge (source, target, edgeType, status),
+     * then every string, encoded with a single encodeInto call.
+     *
+     * Field values follow the JSON path exactly: a non-string is "", a
+     * non-number or a non-finite number is 0, -0 is 0. Anything that
+     * JSON.stringify would not read the same way (a non-plain object, toJSON,
+     * a bigint, an object in a recognised field, a string with a lone
+     * surrogate) returns null. One difference remains by design: members the
+     * graph encoding never reads (extra fields) are not inspected, so an
+     * ill-formed string there is rejected by the JSON path (invalid_surrogate)
+     * but ignored here.
+     */
+    private encodeGraphColumns;
+    /** Graph delta payload (SPEC §10.1). */
+    encodeGraphDelta(delta: GraphDelta): string;
+    /** Opt-in value-grouped keyed set (SPEC §7.4.8). */
+    encodeGrouped(data: Record<string, unknown>[], keyField: string, groupField: string): string;
+    /** Delta-participating full payload for a keyed set (SPEC §10a.1). */
+    encodeGenericFull(set: GenericSet, tool?: string): string;
+    /** Encode an explicit generic delta payload (SPEC §10a.2). */
+    encodeGenericDelta(delta: GenericDelta): string;
+    /**
+     * Diff two keyed sets and encode the delta (added / changed / removed,
+     * sorted by identity). Throws GcfError("invalid_input") on a schema change:
+     * send a full payload instead (SPEC §10a.7).
+     */
+    encodeGenericDiff(base: GenericSet, next: GenericSet, opts?: {
+        tool?: string;
+        deltaTokens?: number;
+        fullTokens?: number;
+    }): string;
+    /** `gcf-pack-root-v1`: graph `{symbols, edges}` or keyed set `{fields, rows}`. */
+    packRoot(input: Pick<GraphPayload, "symbols" | "edges"> | Pick<GenericSet, "rows"> & Partial<GenericSet>): string;
+    /** Apply a generic delta wire to a base set atomically; returns the new root. */
+    applyGenericDelta(wire: string, base: GenericSet, expectedNewRoot?: string): string;
+    /** Apply a graph delta wire to a base snapshot; returns the new root and snapshot. */
+    applyGraphDelta(wire: string, base: Pick<GraphPayload, "symbols" | "edges">): {
+        root: string;
+        snapshot: Pick<GraphPayload, "symbols" | "edges">;
+    };
+    /** @internal used by GraphSession */
+    encodeGraphSessionRaw(payload: GraphPayload, known: Record<string, number>, next: number): string;
+}
+/** @deprecated alias kept for older imports. */
+export declare const GcfDecoder: typeof GcfCodec;
+export type GcfDecoder = GcfCodec;
+/**
+ * Graph session deduplication (SPEC §9): symbols sent in an earlier call are
+ * re-sent as bare `@id  # previously transmitted` references with stable IDs.
+ */
+export declare class GraphSession {
+    private ids;
+    private nextId;
+    private readonly codec;
+    constructor(codec: GcfCodec);
+    encode(payload: GraphPayload): string;
+    get size(): number;
+    reset(): void;
+}
+export type ReanchorPolicy = {
+    mode: "fixedN";
+    n: number;
+} | {
+    mode: "sizeGuard";
+};
+export declare const DEFAULT_REANCHOR_N = 15;
+/**
+ * Producer-side delta session with re-anchoring (SPEC §10a.8): emits deltas
+ * against the previous turn and, per policy, a full payload every N turns
+ * (`fixedN`) or when accumulated deltas reach a full payload's size
+ * (`sizeGuard`). A schema change always re-anchors.
+ */
+export declare class GenericDeltaSession {
+    private turnCount;
+    private cum;
+    private policy;
+    private readonly codec;
+    private base;
+    private readonly tool;
+    constructor(codec: GcfCodec, base: GenericSet, tool?: string, policy?: ReanchorPolicy);
+    currentFull(): string;
+    turn(): number;
+    next(nextSet: GenericSet): {
+        wire: string;
+        isFull: boolean;
+    };
+    private reanchor;
+}
+/** Convert a value from `decodeLazy` (or any part of it) to plain JS values. */
+export declare function toPlain(value: unknown): unknown;
+/** True when a string must be quoted (SPEC §2.4). */
+export declare function needsQuote(s: string): boolean;
+/** JSON-compatible quoted string with the canonical escapes (SPEC §2.2). */
+export declare function quoteString(s: string): string;
+/** Key grammar (SPEC §2a): bare when valid, otherwise quoted. */
+export declare function formatKey(k: string): string;
+/** Canonical number (SPEC §2.3.1). */
+export declare function formatNumber(f: number): string;
+/** Canonical scalar: null `-`, booleans, numbers, strings quoted when needed. */
+export declare function formatScalar(v: unknown): string;
+/** Graph score: two decimals, round-half-to-even on the exact double (SPEC §5). */
+export declare function formatScore(x: number): string;
+export interface StreamWriter {
+    write(chunk: string): void;
+}
+export interface GraphStreamOptions {
+    tokenBudget?: number;
+    tokensUsed?: number;
+    packRoot?: string;
+    session?: boolean;
+    /** Emit `counts=targets:2,...,edges:3` instead of positional counts (SPEC §8.4.1). */
+    labeledTrailerCounts?: boolean;
+}
+/** Zero-buffering graph encoder: symbols, then edges, then `close()`. */
+export declare class GraphStreamEncoder {
+    private ids;
+    private nextId;
+    private group;
+    private groupCounts;
+    private edges;
+    private edgesStarted;
+    private readonly w;
+    private readonly opts;
+    constructor(w: StreamWriter, tool: string, opts?: GraphStreamOptions);
+    private enterGroup;
+    writeSymbol(s: GraphSymbol): void;
+    /** A symbol already delivered earlier in the session (SPEC §9). */
+    writeBareRef(qualifiedName: string, distance: number): void;
+    writeEdge(e: GraphEdge): void;
+    close(): void;
+}
+/** Zero-buffering generic encoder: `[?]` sections plus a `##! summary` trailer. */
+export declare class GenericStreamEncoder {
+    private sections;
+    private current;
+    private readonly w;
+    constructor(w: StreamWriter);
+    private checkFields;
+    beginArray(name: string, fields: string[]): void;
+    beginKeyedMap(name: string, keyLabel: string, valueFields: string[]): void;
+    writeRow(values: unknown[]): void;
+    endArray(): void;
+    writeKV(key: string, value: unknown): void;
+    writeInlineArray(name: string, values: unknown[]): void;
+    close(): void;
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./host.js";
+import { GcfCodec } from "./host.js";
+export type WasmSource = BufferSource | WebAssembly.Module | URL | string | Response | Promise<Response>;
+/**
+ * Create a codec. Without arguments, returns a shared instance backed by the
+ * `gcf.wasm` shipped with this package (loaded once). Each codec owns its
+ * own WebAssembly memory; create more than one only for parallel use.
+ */
+export declare function init(source?: WasmSource): Promise<GcfCodec>;