@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/vendor/runar/runar-ir-schema/src/artifact.js

@@ -0,0 +1,8 @@
+/**
+ * Rúnar Artifact — the final compiled output of a Rúnar compiler (Pass 6).
+ *
+ * This is what gets consumed by wallets, SDKs, and deployment tooling.
+ * It bundles the locking script, ABI metadata, optional debug info,
+ * and (for stateful contracts) state field descriptors.
+ */
+export {};

package/dist/vendor/runar/runar-ir-schema/src/canonical-json.d.ts

@@ -0,0 +1,43 @@
+/**
+ * RFC 8785 / JCS (JSON Canonicalization Scheme) serializer.
+ *
+ * Produces a deterministic, byte-identical JSON string for any JSON-compatible
+ * value.  This is used to guarantee that two Rúnar compilers emitting the same
+ * ANF IR will produce identical output when serialised.
+ *
+ * Key properties:
+ * - Object keys are sorted by their UTF-16 code-unit values (per ES spec).
+ * - Numbers use ES `JSON.stringify` serialization (IEEE 754, no trailing
+ *   zeros, no positive sign on exponent, etc.).
+ * - No whitespace.
+ * - `undefined` values and `undefined` array slots are not allowed (will
+ *   throw).
+ * - `bigint` values are serialised as bare integers (no quotes), matching the
+ *   JSON Schema `integer` type used in the ANF IR schema.
+ *
+ * DoS-bound input guards:
+ * - Recursion depth is capped at {@link InputLimits.MAX_NESTING}.
+ * - Individual string values are capped at {@link InputLimits.MAX_STRING_BYTES}.
+ * - Total serialised output is capped at {@link InputLimits.MAX_IR_BYTES}.
+ * - Bound violations throw {@link CanonicalJsonError} with `code` / `limit` /
+ *   `actual` set for typed downstream handling.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc8785
+ */
+/**
+ * Serialise a value to canonical JSON (RFC 8785 / JCS).
+ *
+ * @throws {TypeError} if the value contains functions or symbols.
+ * @throws {CanonicalJsonError} if recursion depth, string byte length, or
+ *   total output byte length exceeds the documented {@link InputLimits}.
+ */
+export declare function canonicalJsonStringify(value: unknown): string;
+/**
+ * Parse a JSON string and re-serialise it to canonical form.
+ * Useful for normalising IR that was stored with pretty-printing.
+ *
+ * @throws {CanonicalJsonError} with `code: 'invalid'` if the input is not
+ *   valid JSON, or with `code: 'bytes'` / `'depth'` / `'string-bytes'` if
+ *   the canonicalised output would violate an {@link InputLimits} bound.
+ */
+export declare function canonicalise(json: string): string;

package/dist/vendor/runar/runar-ir-schema/src/canonical-json.js

@@ -0,0 +1,204 @@
+/**
+ * RFC 8785 / JCS (JSON Canonicalization Scheme) serializer.
+ *
+ * Produces a deterministic, byte-identical JSON string for any JSON-compatible
+ * value.  This is used to guarantee that two Rúnar compilers emitting the same
+ * ANF IR will produce identical output when serialised.
+ *
+ * Key properties:
+ * - Object keys are sorted by their UTF-16 code-unit values (per ES spec).
+ * - Numbers use ES `JSON.stringify` serialization (IEEE 754, no trailing
+ *   zeros, no positive sign on exponent, etc.).
+ * - No whitespace.
+ * - `undefined` values and `undefined` array slots are not allowed (will
+ *   throw).
+ * - `bigint` values are serialised as bare integers (no quotes), matching the
+ *   JSON Schema `integer` type used in the ANF IR schema.
+ *
+ * DoS-bound input guards:
+ * - Recursion depth is capped at {@link InputLimits.MAX_NESTING}.
+ * - Individual string values are capped at {@link InputLimits.MAX_STRING_BYTES}.
+ * - Total serialised output is capped at {@link InputLimits.MAX_IR_BYTES}.
+ * - Bound violations throw {@link CanonicalJsonError} with `code` / `limit` /
+ *   `actual` set for typed downstream handling.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc8785
+ */
+import { InputLimits, CanonicalJsonError } from './input-limits.js';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Serialise a value to canonical JSON (RFC 8785 / JCS).
+ *
+ * @throws {TypeError} if the value contains functions or symbols.
+ * @throws {CanonicalJsonError} if recursion depth, string byte length, or
+ *   total output byte length exceeds the documented {@link InputLimits}.
+ */
+export function canonicalJsonStringify(value) {
+    const result = serialise(value, new Set(), 0);
+    // Final output-byte-length guard (UTF-8 bytes).
+    const byteLen = Buffer.byteLength(result, 'utf8');
+    if (byteLen > InputLimits.MAX_IR_BYTES) {
+        throw new CanonicalJsonError('bytes', `canonical JSON output exceeds ${InputLimits.MAX_IR_BYTES} bytes (actual ${byteLen})`, { limit: InputLimits.MAX_IR_BYTES, actual: byteLen });
+    }
+    return result;
+}
+/**
+ * Parse a JSON string and re-serialise it to canonical form.
+ * Useful for normalising IR that was stored with pretty-printing.
+ *
+ * @throws {CanonicalJsonError} with `code: 'invalid'` if the input is not
+ *   valid JSON, or with `code: 'bytes'` / `'depth'` / `'string-bytes'` if
+ *   the canonicalised output would violate an {@link InputLimits} bound.
+ */
+export function canonicalise(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        throw new CanonicalJsonError('invalid', `canonicalise: input is not valid JSON: ${e.message}`);
+    }
+    return canonicalJsonStringify(parsed);
+}
+// ---------------------------------------------------------------------------
+// Serialisation engine
+// ---------------------------------------------------------------------------
+function serialise(value, seen, depth) {
+    // null
+    if (value === null) {
+        return 'null';
+    }
+    // Primitives
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            return serialiseNumber(value);
+        case 'bigint':
+            // Serialise as a bare JSON integer — no quotes.
+            return value.toString();
+        case 'string':
+            return serialiseString(value);
+        case 'undefined':
+        case 'symbol':
+        case 'function':
+            throw new TypeError(`canonical JSON does not support ${typeof value}`);
+    }
+    // Objects and arrays (typeof === 'object' at this point)
+    // Depth guard before descending into the container.
+    //
+    // R-260/R-261: the bound is MAX_WIRE_NESTING (100), not MAX_NESTING (512).
+    // canonicalJson's output crosses a tier boundary and its bound has to be the
+    // same number verifyEnvelope will PARSE on the far side — if emit allowed
+    // more than parse, a tier could produce a legal, correctly-signed envelope
+    // another tier is physically unable to read. 512 stays the `--ir` loader's
+    // bound, where the input is a trusted local file.
+    if (depth >= InputLimits.MAX_WIRE_NESTING) {
+        throw new CanonicalJsonError('depth', `canonical JSON nesting exceeds ${InputLimits.MAX_WIRE_NESTING}`, { limit: InputLimits.MAX_WIRE_NESTING, actual: depth + 1 });
+    }
+    const obj = value;
+    // Circular reference detection
+    if (seen.has(obj)) {
+        throw new TypeError('canonical JSON does not support circular references');
+    }
+    seen.add(obj);
+    // Arrays and objects (including typed arrays, Date, RegExp, etc.) both
+    // route through serialiseObject which honours `toJSON` and otherwise
+    // walks own enumerable keys.
+    const result = Array.isArray(obj)
+        ? serialiseArray(obj, seen, depth + 1)
+        : serialiseObject(obj, seen, depth + 1);
+    seen.delete(obj);
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Number serialisation (ES2022 §25.5.2.1)
+// ---------------------------------------------------------------------------
+function serialiseNumber(n) {
+    if (!Number.isFinite(n)) {
+        throw new TypeError(`canonical JSON does not support ${n} (NaN / Infinity)`);
+    }
+    if (Object.is(n, -0)) {
+        return '0';
+    }
+    // JSON.stringify for finite numbers matches the ES spec requirement
+    // that RFC 8785 mandates.
+    return JSON.stringify(n);
+}
+// ---------------------------------------------------------------------------
+// String serialisation (RFC 8785 §3.2.2.2)
+// ---------------------------------------------------------------------------
+function serialiseString(s) {
+    // Per-string byte-length guard.
+    const byteLen = Buffer.byteLength(s, 'utf8');
+    if (byteLen > InputLimits.MAX_STRING_BYTES) {
+        throw new CanonicalJsonError('string-bytes', `canonical JSON string field exceeds ${InputLimits.MAX_STRING_BYTES} bytes (actual ${byteLen})`, { limit: InputLimits.MAX_STRING_BYTES, actual: byteLen });
+    }
+    // RFC 8785 §3.2.2.2 / audit D6: the input MUST be well-formed Unicode.
+    // JS strings are UTF-16 code-unit sequences and may legally contain
+    // unpaired surrogates; `JSON.stringify` happily emits them, producing
+    // bytes that the six other SDK tiers reject. Walk code units, reject any
+    // unpaired surrogate, and only then delegate to `JSON.stringify` for the
+    // actual escape table (which is correct on well-formed inputs).
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xD800 && c <= 0xDBFF) {
+            const next = i + 1 < s.length ? s.charCodeAt(i + 1) : -1;
+            if (next < 0xDC00 || next > 0xDFFF) {
+                throw new CanonicalJsonError('lone-surrogate', `canonical JSON: lone high surrogate U+${c.toString(16).toUpperCase().padStart(4, '0')} in string`);
+            }
+            i++; // skip the valid low surrogate
+        }
+        else if (c >= 0xDC00 && c <= 0xDFFF) {
+            throw new CanonicalJsonError('lone-surrogate', `canonical JSON: lone low surrogate U+${c.toString(16).toUpperCase().padStart(4, '0')} in string`);
+        }
+    }
+    // JSON.stringify already produces correct escaping for most cases.
+    // RFC 8785 additionally requires that code-points U+0000–U+001F are
+    // \uXXXX-escaped (which JSON.stringify does), and that there is no
+    // gratuitous escaping of solidus '/' (JSON.stringify does NOT escape it
+    // by default in modern engines, which is correct).
+    return JSON.stringify(s);
+}
+// ---------------------------------------------------------------------------
+// Array serialisation
+// ---------------------------------------------------------------------------
+function serialiseArray(arr, seen, depth) {
+    const parts = [];
+    for (let i = 0; i < arr.length; i++) {
+        const element = arr[i];
+        if (element === undefined) {
+            // JSON.stringify converts undefined array elements to null.
+            parts.push('null');
+        }
+        else {
+            parts.push(serialise(element, seen, depth));
+        }
+    }
+    return '[' + parts.join(',') + ']';
+}
+// ---------------------------------------------------------------------------
+// Object serialisation (keys sorted by UTF-16 code-unit value)
+// ---------------------------------------------------------------------------
+function serialiseObject(obj, seen, depth) {
+    // If the object has a toJSON method, use it (Date, etc.)
+    const asAny = obj;
+    if (typeof asAny['toJSON'] === 'function') {
+        return serialise(asAny['toJSON'](), seen, depth);
+    }
+    // Collect own enumerable string keys and sort by UTF-16 code units.
+    // In ES, `Array.prototype.sort()` without a comparator uses the
+    // default string comparison which is exactly UTF-16 code-unit order.
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const key of keys) {
+        const val = obj[key];
+        // JSON.stringify omits keys whose value is undefined.
+        if (val === undefined)
+            continue;
+        parts.push(serialiseString(key) + ':' + serialise(val, seen, depth));
+    }
+    return '{' + parts.join(',') + '}';
+}

package/dist/vendor/runar/runar-ir-schema/src/input-limits.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared DoS-bound input limits + typed error class used by all public
+ * canonical-JSON / IR-loading entry points across the runar-ir-schema
+ * package and its downstream consumers.
+ *
+ * Justifications:
+ * - MAX_SCRIPT_BYTES = 4 MiB — the largest legitimate script measured by
+ *   the script-size benchmark is `p384-wallet` at ~1.87 MB; 4 MiB gives
+ *   ~2× headroom without enabling pathological 50 MB scripts. An earlier
+ *   1 MiB cap incorrectly rejected p384-wallet — calibration bug caught
+ *   by the script-size baseline (Major-2).
+ * - MAX_IR_BYTES = 16 MiB — the largest compiled-IR JSON in the corpus is
+ *   `conformance/tests/token-ft/expected-ir.json` at 91,018 B (0.087 MiB),
+ *   so 16 MiB is ~184× headroom. An earlier note put the largest at "~2 MiB
+ *   (Mode 3 STARK contracts)" and the headroom at 8×; no checked-in
+ *   `expected-ir.json` has ever come within 24× of that figure. The bound is
+ *   sized against a pathological producer, not against this corpus, so the
+ *   real number being far larger is fine — it is the stated one that was
+ *   wrong, and a wrong one invites the next person to recalibrate downward
+ *   against a fiction.
+ * - MAX_NESTING = 512 — JS engine stack typically tolerates ~10k frames;
+ *   512 is well below crash threshold but accommodates legitimate deep
+ *   covenant ANF. This bound serves the `--ir` loader
+ *   (runar-compiler/src/index.ts), which reads a TRUSTED local file.
+ * - MAX_WIRE_NESTING = 100 — the bound for anything crossing a tier
+ *   boundary: canonicalJson's emit side and verifyEnvelope's parse side.
+ *   Different threat model from MAX_NESTING (unauthenticated network input,
+ *   not a local file), so deliberately a separate constant rather than a
+ *   shared one. 100 is the largest depth Ruby's `JSON.parse` accepts for
+ *   EVERY payload shape at its native default — measured on ruby 4.0.2 /
+ *   json 2.18.0, 100-deep parses for both arrays and objects, a 101-deep
+ *   OBJECT raises JSON::NestingError, and a 101-deep ARRAY still parses; the
+ *   gem counts the two shapes one level apart, so an earlier flat "100
+ *   accepted, 101 rejected" is true of objects and false of arrays. That
+ *   asymmetry is the whole reason the bound is 100 rather than 101: raising
+ *   it to the depth Ruby accepts for ARRAYS would keep working on every
+ *   array payload and start rejecting 101-deep OBJECTS at the Ruby tier
+ *   only — a shape-dependent, one-tier failure, which is the worst kind to
+ *   debug on a signed wire. 100 is
+ *   also 27 below rust serde_json's hard ceiling of 127, so every tier stays
+ *   inside its own library's default without hand-rolling or reconfiguring a
+ *   parser, and no tier is anywhere near its stack — at 1024 Python's
+ *   canonical_json dies of native stack exhaustion and the JVM crashes on a
+ *   513-deep object, so a higher bound would trade a clean typed rejection
+ *   for a crash. Headroom is ample: the deepest of the 165 checked-in
+ *   conformance artifacts measures depth 15, and
+ *   conformance/sdk-envelope/fixtures.json tops out at 6.
+ * - MAX_STRING_BYTES = 4 MiB — the binding case is a compiled script carried
+ *   as a hex string, not a verification key. The largest checked-in script is
+ *   `conformance/tests/p384-wallet/expected-script.hex`: 1,963,362 script
+ *   bytes = 3,926,724 hex characters, which is 93.6% of this bound. Real
+ *   headroom is 1.07×. An earlier note claimed "~3× headroom" against "the
+ *   largest checked-in hex pushdata (witness-assisted Groth16 VK)" — that
+ *   artifact, `examples/go/SP1Verifier.groth16.vk.json`, is 3,287 bytes in
+ *   total and was never the worst case; the justification named the wrong
+ *   artifact and overstated the margin by ~3×.
+ *
+ *   Structural consequence worth stating plainly: MAX_SCRIPT_BYTES admits
+ *   4 MiB of SCRIPT, and hex doubles it. So anything that reaches
+ *   signEnvelope as a hex string through canonicalJson is capped at 2 MiB of
+ *   script — HALF the advertised script bound — and the largest script in
+ *   the tree already sits at 93.6% of that. The next script family that
+ *   clears ~2 MiB needs a coordinated seven-tier bump of this constant, not
+ *   a local one: raising it in one tier splits the wire.
+ */
+export declare const InputLimits: {
+    readonly MAX_IR_BYTES: number;
+    readonly MAX_SCRIPT_BYTES: number;
+    readonly MAX_NESTING: 512;
+    readonly MAX_WIRE_NESTING: 100;
+    readonly MAX_STRING_BYTES: number;
+    readonly MAX_SOURCE_BYTES: number;
+};
+export type InputLimitsKey = keyof typeof InputLimits;
+/**
+ * Thrown when a public canonical-JSON / IR-loading entry point detects
+ * input that exceeds a documented InputLimits bound. Distinct typed
+ * exception so callers can distinguish DoS-bound rejection from generic
+ * RangeError / SyntaxError.
+ */
+export declare class CanonicalJsonError extends Error {
+    readonly code: 'depth' | 'bytes' | 'string-bytes' | 'circular' | 'invalid' | 'lone-surrogate';
+    readonly limit?: number;
+    readonly actual?: number;
+    constructor(code: 'depth' | 'bytes' | 'string-bytes' | 'circular' | 'invalid' | 'lone-surrogate', message: string, info?: {
+        limit?: number;
+        actual?: number;
+    });
+}

package/dist/vendor/runar/runar-ir-schema/src/input-limits.js

@@ -0,0 +1,100 @@
+/**
+ * Shared DoS-bound input limits + typed error class used by all public
+ * canonical-JSON / IR-loading entry points across the runar-ir-schema
+ * package and its downstream consumers.
+ *
+ * Justifications:
+ * - MAX_SCRIPT_BYTES = 4 MiB — the largest legitimate script measured by
+ *   the script-size benchmark is `p384-wallet` at ~1.87 MB; 4 MiB gives
+ *   ~2× headroom without enabling pathological 50 MB scripts. An earlier
+ *   1 MiB cap incorrectly rejected p384-wallet — calibration bug caught
+ *   by the script-size baseline (Major-2).
+ * - MAX_IR_BYTES = 16 MiB — the largest compiled-IR JSON in the corpus is
+ *   `conformance/tests/token-ft/expected-ir.json` at 91,018 B (0.087 MiB),
+ *   so 16 MiB is ~184× headroom. An earlier note put the largest at "~2 MiB
+ *   (Mode 3 STARK contracts)" and the headroom at 8×; no checked-in
+ *   `expected-ir.json` has ever come within 24× of that figure. The bound is
+ *   sized against a pathological producer, not against this corpus, so the
+ *   real number being far larger is fine — it is the stated one that was
+ *   wrong, and a wrong one invites the next person to recalibrate downward
+ *   against a fiction.
+ * - MAX_NESTING = 512 — JS engine stack typically tolerates ~10k frames;
+ *   512 is well below crash threshold but accommodates legitimate deep
+ *   covenant ANF. This bound serves the `--ir` loader
+ *   (runar-compiler/src/index.ts), which reads a TRUSTED local file.
+ * - MAX_WIRE_NESTING = 100 — the bound for anything crossing a tier
+ *   boundary: canonicalJson's emit side and verifyEnvelope's parse side.
+ *   Different threat model from MAX_NESTING (unauthenticated network input,
+ *   not a local file), so deliberately a separate constant rather than a
+ *   shared one. 100 is the largest depth Ruby's `JSON.parse` accepts for
+ *   EVERY payload shape at its native default — measured on ruby 4.0.2 /
+ *   json 2.18.0, 100-deep parses for both arrays and objects, a 101-deep
+ *   OBJECT raises JSON::NestingError, and a 101-deep ARRAY still parses; the
+ *   gem counts the two shapes one level apart, so an earlier flat "100
+ *   accepted, 101 rejected" is true of objects and false of arrays. That
+ *   asymmetry is the whole reason the bound is 100 rather than 101: raising
+ *   it to the depth Ruby accepts for ARRAYS would keep working on every
+ *   array payload and start rejecting 101-deep OBJECTS at the Ruby tier
+ *   only — a shape-dependent, one-tier failure, which is the worst kind to
+ *   debug on a signed wire. 100 is
+ *   also 27 below rust serde_json's hard ceiling of 127, so every tier stays
+ *   inside its own library's default without hand-rolling or reconfiguring a
+ *   parser, and no tier is anywhere near its stack — at 1024 Python's
+ *   canonical_json dies of native stack exhaustion and the JVM crashes on a
+ *   513-deep object, so a higher bound would trade a clean typed rejection
+ *   for a crash. Headroom is ample: the deepest of the 165 checked-in
+ *   conformance artifacts measures depth 15, and
+ *   conformance/sdk-envelope/fixtures.json tops out at 6.
+ * - MAX_STRING_BYTES = 4 MiB — the binding case is a compiled script carried
+ *   as a hex string, not a verification key. The largest checked-in script is
+ *   `conformance/tests/p384-wallet/expected-script.hex`: 1,963,362 script
+ *   bytes = 3,926,724 hex characters, which is 93.6% of this bound. Real
+ *   headroom is 1.07×. An earlier note claimed "~3× headroom" against "the
+ *   largest checked-in hex pushdata (witness-assisted Groth16 VK)" — that
+ *   artifact, `examples/go/SP1Verifier.groth16.vk.json`, is 3,287 bytes in
+ *   total and was never the worst case; the justification named the wrong
+ *   artifact and overstated the margin by ~3×.
+ *
+ *   Structural consequence worth stating plainly: MAX_SCRIPT_BYTES admits
+ *   4 MiB of SCRIPT, and hex doubles it. So anything that reaches
+ *   signEnvelope as a hex string through canonicalJson is capped at 2 MiB of
+ *   script — HALF the advertised script bound — and the largest script in
+ *   the tree already sits at 93.6% of that. The next script family that
+ *   clears ~2 MiB needs a coordinated seven-tier bump of this constant, not
+ *   a local one: raising it in one tier splits the wire.
+ */
+export const InputLimits = {
+    MAX_IR_BYTES: 16 * 1024 * 1024, // 16 MiB — uncompressed ANF IR JSON
+    MAX_SCRIPT_BYTES: 4 * 1024 * 1024, // 4 MiB — single compiled Bitcoin Script
+    // (p384-wallet hits ~1.87 MB; 2× headroom)
+    MAX_NESTING: 512, // recursion depth for JSON / ANF traversal
+    // (trusted local --ir input)
+    MAX_WIRE_NESTING: 100, // recursion depth for anything crossing a
+    // tier boundary (canonicalJson emit,
+    // verifyEnvelope parse) — untrusted input
+    MAX_STRING_BYTES: 4 * 1024 * 1024, // 4 MiB — single string field inside JSON
+    // (hex doubles: an effective 2 MiB script
+    //  ceiling on the wire; today's largest is
+    //  at 93.6% of it)
+    MAX_SOURCE_BYTES: 4 * 1024 * 1024, // 4 MiB — single Rúnar source file
+    // (BUG-008 follow-up: source parser entry guard
+    //  across all 7 tiers)
+};
+/**
+ * Thrown when a public canonical-JSON / IR-loading entry point detects
+ * input that exceeds a documented InputLimits bound. Distinct typed
+ * exception so callers can distinguish DoS-bound rejection from generic
+ * RangeError / SyntaxError.
+ */
+export class CanonicalJsonError extends Error {
+    code;
+    limit;
+    actual;
+    constructor(code, message, info) {
+        super(message);
+        this.name = 'CanonicalJsonError';
+        this.code = code;
+        this.limit = info?.limit;
+        this.actual = info?.actual;
+    }
+}

package/dist/vendor/runar/runar-ir-schema/src/stack-ir.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Stack IR — the low-level stack-machine representation (Pass 5 output).
+ *
+ * Each method is lowered to a flat sequence of stack operations that map
+ * almost 1-to-1 to Bitcoin Script opcodes.  This representation is
+ * compiler-specific (not part of the conformance boundary).
+ */
+export interface StackProgram {
+    contractName: string;
+    methods: StackMethod[];
+}
+export interface StackMethod {
+    name: string;
+    ops: StackOp[];
+    maxStackDepth: number;
+}
+/** Optional source location for debug source maps. */
+export interface StackSourceLoc {
+    file: string;
+    line: number;
+    column: number;
+}
+export interface PushOp {
+    op: 'push';
+    value: Uint8Array | bigint | boolean;
+    sourceLoc?: StackSourceLoc;
+}
+export interface DupOp {
+    op: 'dup';
+    sourceLoc?: StackSourceLoc;
+}
+export interface SwapOp {
+    op: 'swap';
+    sourceLoc?: StackSourceLoc;
+}
+export interface RollOp {
+    op: 'roll';
+    depth: number;
+    sourceLoc?: StackSourceLoc;
+}
+export interface PickOp {
+    op: 'pick';
+    depth: number;
+    sourceLoc?: StackSourceLoc;
+}
+export interface DropOp {
+    op: 'drop';
+    sourceLoc?: StackSourceLoc;
+}
+export interface OpcodeOp {
+    op: 'opcode';
+    code: string;
+    sourceLoc?: StackSourceLoc;
+}
+export interface IfOp {
+    op: 'if';
+    then: StackOp[];
+    else?: StackOp[];
+    sourceLoc?: StackSourceLoc;
+}
+export interface NipOp {
+    op: 'nip';
+    sourceLoc?: StackSourceLoc;
+}
+export interface OverOp {
+    op: 'over';
+    sourceLoc?: StackSourceLoc;
+}
+export interface RotOp {
+    op: 'rot';
+    sourceLoc?: StackSourceLoc;
+}
+export interface TuckOp {
+    op: 'tuck';
+    sourceLoc?: StackSourceLoc;
+}
+export interface PlaceholderOp {
+    op: 'placeholder';
+    paramIndex: number;
+    paramName: string;
+    sourceLoc?: StackSourceLoc;
+}
+export interface PushCodeSepIndexOp {
+    op: 'push_codesep_index';
+    sourceLoc?: StackSourceLoc;
+}
+/**
+ * R-095 — pin `SIZE(_codePart)` against the code part's own DEPLOYED byte
+ * length. See `packages/runar-compiler/src/ir/stack-ir.ts` for the full
+ * contract; the emitter reserves a fixed-width 9-byte sequence and
+ * back-patches the length plus the comparison opcode after the whole script
+ * has been emitted.
+ */
+export interface VerifyCodePartLenOp {
+    op: 'verify_code_part_len';
+    /** Deploy-time byte growth of the template's OP_0 placeholders. */
+    delta: number;
+    /** true -> exact equality pin; false -> lower-bound pin. */
+    exact: boolean;
+    sourceLoc?: StackSourceLoc;
+}
+/**
+ * Opaque raw byte span produced by lowering a `raw_script` ANF node.
+ *
+ * Emitted verbatim by the emit pass. Treated as a hard barrier by every
+ * windowed optimizer (peephole) — rules must never bridge across an
+ * adjacent `raw_bytes`. Stack effect is declared via `in_arity` /
+ * `out_arity`; the analyzer reads these to keep depth tracking sound
+ * without inspecting the contents.
+ */
+export interface RawBytesOp {
+    op: 'raw_bytes';
+    bytes: Uint8Array;
+    in_arity: number;
+    out_arity: number;
+    sourceLoc?: StackSourceLoc;
+}
+export type StackOp = PushOp | DupOp | SwapOp | RollOp | PickOp | DropOp | OpcodeOp | IfOp | NipOp | OverOp | RotOp | TuckOp | PlaceholderOp | PushCodeSepIndexOp | VerifyCodePartLenOp | RawBytesOp;

package/dist/vendor/runar/runar-ir-schema/src/stack-ir.js

@@ -0,0 +1,8 @@
+/**
+ * Stack IR — the low-level stack-machine representation (Pass 5 output).
+ *
+ * Each method is lowered to a flat sequence of stack operations that map
+ * almost 1-to-1 to Bitcoin Script opcodes.  This representation is
+ * compiler-specific (not part of the conformance boundary).
+ */
+export {};

package/dist/vendor/runar/runar-ir-schema/src/state-layout.d.ts

@@ -0,0 +1,56 @@
+/**
+ * State-tail byte layout — the single source of truth for WHERE each
+ * serialized state field lives in a stateful contract's locking script.
+ *
+ * Mirrors the SDK's `serializeState` wire format exactly:
+ *
+ *   <code part> OP_RETURN <field0> <field1> ... <fieldN>
+ *
+ *   - bigint / int : 8 raw bytes, little-endian sign-magnitude (OP_NUM2BIN 8)
+ *   - bool         : 1 raw byte (0x00 / 0x01)
+ *   - PubKey       : 33 raw bytes          - Addr / Ripemd160 : 20 raw bytes
+ *   - Sha256       : 32 raw bytes          - Point            : 64 raw bytes
+ *   - P256Point    : 64 raw bytes          - P384Point        : 96 raw bytes
+ *   - anything else: push-data framed (variable length)
+ *
+ * The curve-point types are raw and fixed-width because `runar-lang`'s
+ * `P256Point` / `P384Point` cast constructors hard-assert 64 / 96 bytes, and
+ * all seven COMPILERS emit them as fixed raw slices in the state tail. An SDK
+ * that push-data frames them instead deploys a state section one (64 -> 0x40)
+ * or two (96 -> OP_PUSHDATA1) bytes longer than the script's own reader
+ * expects, and the first spend fails with the funds locked.
+ *
+ * Fields are concatenated in `StateField.index` order. FixedArray fields
+ * serialize as their flattened leaves back-to-back.
+ *
+ * Lives in runar-ir-schema so the compiler (which annotates `stateFields`
+ * in the artifact), the SDK's state codec, and any verifier tooling share
+ * ONE width table instead of re-deriving it.
+ */
+import type { StateField } from './artifact.js';
+export type StateFieldEncoding = NonNullable<StateField['encoding']>;
+/**
+ * Fixed serialized widths (bytes) for scalar state-field types.
+ * Types absent from this table serialize as push-data framed variable-length
+ * values ('pushdata').
+ */
+export declare const STATE_FIELD_WIDTHS: Readonly<Record<string, {
+    readonly size: number;
+    readonly encoding: StateFieldEncoding;
+}>>;
+/**
+ * Annotate state fields with their byte layout (`encoding`, `byteOffset`,
+ * `byteLength`, `tailOffset`). Returns NEW field objects (inputs are not
+ * mutated), sorted by `index` — the serialization order.
+ *
+ * `byteOffset` counts from the byte AFTER the OP_RETURN separator and is
+ * present only while every preceding field is fixed-length. `tailOffset` is
+ * a NEGATIVE offset from the END of the locking script and is present only
+ * when the field itself and every following field is fixed-length.
+ */
+export declare function annotateStateFieldLayout(fields: StateField[]): StateField[];
+/**
+ * Total serialized state length in bytes (after the OP_RETURN byte), or
+ * undefined when any field is variable-length.
+ */
+export declare function totalStateByteLength(fields: StateField[]): number | undefined;