@dcasegr/amm-client 0.0.0-stage → 0.38.1

package/dist/vendor/runar/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rúnar Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/vendor/runar/NOTICE

@@ -0,0 +1,15 @@
+Vendored from Rúnar (https://github.com/icellan/runar), commit
+d207ee8ec4c2b16e5d3b181da1e177fe1fd26c50 (the commit go.mod pins for the Go side),
+MIT licence (LICENSE beside this file).
+
+runar-sdk/src: the modules runar-sdk's contract.ts, state.ts and script-utils.ts import
+(their import closure), copied unchanged except:
+  - every `from 'runar-ir-schema'` reads `from '../../../../pool/runar-ir-schema.js'`
+    (that package's barrel without its node-only Ajv validators);
+  - anf-interpreter.ts takes ECDSA's `verify` from `@bsv/sdk`'s root export
+    (`ECDSA.verify`) instead of the subpath `@bsv/sdk/primitives/ECDSA`, which
+    @bsv/sdk 4's package exports do not name.
+runar-ir-schema/src: the eight modules that barrel re-exports, copied unchanged.
+
+Why vendored: runar-sdk 1.0.0-rc.1 is not published (npm has 0.4.6, on @bsv/sdk 2),
+and its package.json names runar-ir-schema as pnpm `workspace:*`.

package/dist/vendor/runar/runar-ir-schema/src/abi-type-encoding.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ABI-type → slot value encoding — the single source of truth for HOW a
+ * constructor arg of a given ABI type is represented in the locking script.
+ *
+ * Three consumers used to answer this question with three hand-maintained
+ * `switch` statements, and they drifted:
+ *
+ *   - the compiler's `slotValueEncoding` (artifact/assembler.ts), which stamps
+ *     `ConstructorSlot.valueEncoding`
+ *   - `runar-cli`'s `encodingForType` (commands/deploy.ts), which parses
+ *     `--args`
+ *   - the SDK's `interpretScriptElement` (script-utils.ts), which reads the
+ *     values back off chain
+ *
+ * The drift was a funds bug. `RabinSig` / `RabinPubKey` are `bigint` ALIASES
+ * (runar-lang/src/types.ts:68-71) and the compiler consumes them with OP_MOD,
+ * i.e. as Script NUMBERS — but they were absent from every one of those
+ * switches, so the slot was described as an opaque byte push. The CLI then
+ * accepted a big-endian hex modulus and spliced it in verbatim for OP_MOD to
+ * read little-endian: the covenant can never verify and the output is
+ * unspendable. `boolean` (the CANONICAL primitive name — `bool` is the alias)
+ * was missing from the read-back switch in six of the seven SDK tiers, with
+ * the same shape of consequence.
+ *
+ * This is the constructor-slot analogue of `STATE_FIELD_WIDTHS`, which does
+ * the same job for the state tail. Keep them side by side.
+ */
+/** How a constructor arg of a given ABI type is encoded into its slot. */
+export type AbiValueEncoding = 'data' | 'scriptnum' | 'bool';
+/**
+ * ABI type name → slot value encoding, for every type that is NOT a plain
+ * data push. Types absent from this table encode as `'data'`: a raw push of
+ * the value bytes (`PubKey`, `Sha256`, `Point`, `ByteString`, ...).
+ *
+ * Aliases are listed explicitly rather than resolved, because the ABI carries
+ * the SOURCE spelling: a `RabinPubKey` param is written `"type":"RabinPubKey"`
+ * in the artifact, never `"bigint"`. `int` is the surface spelling the
+ * Solidity/Move/Go/Rust/Python frontends lower to `bigint`.
+ */
+export declare const ABI_VALUE_ENCODINGS: Readonly<Record<string, AbiValueEncoding>>;
+/** Classify an ABI type name. Unknown / byte types are a raw data push. */
+export declare function abiValueEncoding(type: string): AbiValueEncoding;

package/dist/vendor/runar/runar-ir-schema/src/abi-type-encoding.js

@@ -0,0 +1,53 @@
+/**
+ * ABI-type → slot value encoding — the single source of truth for HOW a
+ * constructor arg of a given ABI type is represented in the locking script.
+ *
+ * Three consumers used to answer this question with three hand-maintained
+ * `switch` statements, and they drifted:
+ *
+ *   - the compiler's `slotValueEncoding` (artifact/assembler.ts), which stamps
+ *     `ConstructorSlot.valueEncoding`
+ *   - `runar-cli`'s `encodingForType` (commands/deploy.ts), which parses
+ *     `--args`
+ *   - the SDK's `interpretScriptElement` (script-utils.ts), which reads the
+ *     values back off chain
+ *
+ * The drift was a funds bug. `RabinSig` / `RabinPubKey` are `bigint` ALIASES
+ * (runar-lang/src/types.ts:68-71) and the compiler consumes them with OP_MOD,
+ * i.e. as Script NUMBERS — but they were absent from every one of those
+ * switches, so the slot was described as an opaque byte push. The CLI then
+ * accepted a big-endian hex modulus and spliced it in verbatim for OP_MOD to
+ * read little-endian: the covenant can never verify and the output is
+ * unspendable. `boolean` (the CANONICAL primitive name — `bool` is the alias)
+ * was missing from the read-back switch in six of the seven SDK tiers, with
+ * the same shape of consequence.
+ *
+ * This is the constructor-slot analogue of `STATE_FIELD_WIDTHS`, which does
+ * the same job for the state tail. Keep them side by side.
+ */
+/**
+ * ABI type name → slot value encoding, for every type that is NOT a plain
+ * data push. Types absent from this table encode as `'data'`: a raw push of
+ * the value bytes (`PubKey`, `Sha256`, `Point`, `ByteString`, ...).
+ *
+ * Aliases are listed explicitly rather than resolved, because the ABI carries
+ * the SOURCE spelling: a `RabinPubKey` param is written `"type":"RabinPubKey"`
+ * in the artifact, never `"bigint"`. `int` is the surface spelling the
+ * Solidity/Move/Go/Rust/Python frontends lower to `bigint`.
+ */
+export const ABI_VALUE_ENCODINGS = {
+    bigint: 'scriptnum',
+    int: 'scriptnum',
+    // `RabinSig` / `RabinPubKey` are `bigint` aliases. `verifyRabinSig` lowers
+    // to OP_MOD, which reads its operand as a little-endian sign-magnitude
+    // Script number — exactly what `bigint` gets.
+    RabinSig: 'scriptnum',
+    RabinPubKey: 'scriptnum',
+    // `boolean` is canonical; `bool` is the alias several frontends spell.
+    boolean: 'bool',
+    bool: 'bool',
+};
+/** Classify an ABI type name. Unknown / byte types are a raw data push. */
+export function abiValueEncoding(type) {
+    return ABI_VALUE_ENCODINGS[type] ?? 'data';
+}

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

@@ -0,0 +1,221 @@
+/**
+ * ANF IR — A-Normal Form intermediate representation (Pass 4 output).
+ *
+ * This is the **canonical conformance boundary** for Rúnar compilers.
+ * Two compilers that accept the same Rúnar source MUST produce
+ * byte-identical ANF IR (when serialised with canonical JSON).
+ *
+ * Every compound expression is decomposed into a flat sequence of
+ * let-bindings whose right-hand sides are *simple* values: constants,
+ * variable references, a single primitive operation, or a branch/loop.
+ */
+export interface ANFProgram {
+    contractName: string;
+    properties: ANFProperty[];
+    methods: ANFMethod[];
+}
+/**
+ * One FixedArray nesting level on a synthetic scalar leaf. Outermost level
+ * first. `base` is the property name one level up (`grid`, then `grid__0`),
+ * `index` this leaf's position at that level, `length` that level's arity.
+ */
+export interface ANFSyntheticArrayLevel {
+    base: string;
+    index: number;
+    length: number;
+}
+export interface ANFProperty {
+    name: string;
+    type: string;
+    readonly: boolean;
+    initialValue?: string | bigint | boolean;
+    /**
+     * N-095: present only on a scalar leaf minted by the expand-fixed-arrays
+     * pass. The artifact assembler consumes one level per pass to regroup the
+     * synthetic siblings back into a single FixedArray state/ABI entry, so this
+     * is load-bearing wire data: an ANF that drops it still compiles to the same
+     * script bytes but degrades the SDK's `state.grid` accessor into N raw
+     * scalars. The TS frontend reads the chain off the AST
+     * (`PropertyNode.__syntheticArrayChain`) instead and has no ANF-input mode,
+     * so it is the one tier that need not emit it.
+     */
+    syntheticArrayChain?: ANFSyntheticArrayLevel[];
+}
+export interface ANFMethod {
+    name: string;
+    params: ANFParam[];
+    body: ANFBinding[];
+    isPublic: boolean;
+}
+export interface ANFParam {
+    name: string;
+    type: string;
+}
+/**
+ * A single let-binding:  `let <name> = <value>`
+ *
+ * Names follow the pattern `t0`, `t1`, … and are scoped per method.
+ */
+export interface ANFBinding {
+    name: string;
+    value: ANFValue;
+    /** Debug-only: source location of the originating AST node. Not part of conformance. */
+    sourceLoc?: {
+        file: string;
+        line: number;
+        column: number;
+    };
+}
+export interface LoadParam {
+    kind: 'load_param';
+    name: string;
+}
+export interface LoadProp {
+    kind: 'load_prop';
+    name: string;
+}
+export interface LoadConst {
+    kind: 'load_const';
+    value: string | bigint | boolean;
+}
+export interface BinOp {
+    kind: 'bin_op';
+    op: string;
+    left: string;
+    right: string;
+    result_type?: string;
+}
+export interface UnaryOp {
+    kind: 'unary_op';
+    op: string;
+    operand: string;
+    result_type?: string;
+}
+export interface Call {
+    kind: 'call';
+    func: string;
+    args: string[];
+}
+export interface MethodCall {
+    kind: 'method_call';
+    object: string;
+    method: string;
+    args: string[];
+}
+export interface If {
+    kind: 'if';
+    cond: string;
+    then: ANFBinding[];
+    else: ANFBinding[];
+    /**
+     * Ordered named result slots both arms leave (`results[0]` deepest). Entries
+     * name a branch-merged local or an arm-written contract property. Absent
+     * when the `if` carries at most one result — see the copy of this type in
+     * `packages/runar-compiler/src/ir/anf-ir.ts` for the full contract.
+     */
+    results?: string[];
+}
+export interface Loop {
+    kind: 'loop';
+    count: number;
+    body: ANFBinding[];
+    iterVar: string;
+    start: bigint;
+    step: 1 | -1;
+}
+export interface Assert {
+    kind: 'assert';
+    value: string;
+    isAutoInjectedStateCheck?: boolean;
+}
+export interface UpdateProp {
+    kind: 'update_prop';
+    name: string;
+    value: string;
+}
+export interface GetStateScript {
+    kind: 'get_state_script';
+}
+export interface CheckPreimage {
+    kind: 'check_preimage';
+    preimage: string;
+    /**
+     * Issue #123: BIP-143 sighash flag the on-chain OP_PUSH_TX binding appends to
+     * the derived signature (so the node re-derives the tx sighash under this
+     * flag). Absent = default `ALL|FORKID` (0x41), byte-identical to the pinned
+     * cross-tier binding blob. Only set for a method that declares a non-default
+     * `@sighash` mode, keeping golden ANF unchanged for every existing contract.
+     */
+    sighashFlag?: number;
+}
+export interface DeserializeState {
+    kind: 'deserialize_state';
+    preimage: string;
+}
+export interface AddOutput {
+    kind: 'add_output';
+    satoshis: string;
+    stateValues: string[];
+    preimage: string;
+}
+export interface AddRawOutput {
+    kind: 'add_raw_output';
+    satoshis: string;
+    scriptBytes: string;
+}
+/**
+ * AddDataOutput — records an additional transaction output that is NOT a
+ * state continuation. The output is included in the auto-computed
+ * continuation hash (hashOutputs) in declaration order, after state
+ * outputs and before the change output. The emit shape is identical to
+ * `add_raw_output`: amount(8LE) + varint(scriptLen) + scriptBytes.
+ *
+ * Distinguished from `add_raw_output` only at the continuation-hash
+ * composition stage: `add_data_output` refs are concatenated AFTER all
+ * `add_output` (state) refs and BEFORE the change output.
+ */
+export interface AddDataOutput {
+    kind: 'add_data_output';
+    satoshis: string;
+    scriptBytes: string;
+}
+export interface ArrayLiteral {
+    kind: 'array_literal';
+    elements: string[];
+}
+/**
+ * RawScript — an opaque opcode-byte span with declared stack arity.
+ *
+ * Mirrors the definition in `packages/runar-compiler/src/ir/anf-ir.ts`.
+ * The IR stores resolved bytes (not mnemonics) so cross-compiler
+ * conformance reduces to byte equality.
+ */
+export interface RawScript {
+    kind: 'raw_script';
+    bytes: string;
+    in_arity: number;
+    out_arity: number;
+}
+export type ANFValue = LoadParam | LoadProp | LoadConst | BinOp | UnaryOp | Call | MethodCall | If | Loop | Assert | UpdateProp | GetStateScript | CheckPreimage | DeserializeState | AddOutput | AddRawOutput | AddDataOutput | ArrayLiteral | RawScript;
+/**
+ * Name prefix for the temporaries 04-anf-lower appends to BOTH arms of an
+ * if-statement that merges two or more locals (`appendMergedLocalResults`).
+ *
+ * Emitted by `appendBranchResults` (04-anf-lower) for — and ONLY for — an `if`
+ * that declares `results`. Both arms end with an identical 2K-binding block:
+ * K copies into `__merge$0..K-1`, then K rebinds of the declared results from
+ * those temps. That makes each arm hold exactly `results`, in `results` order,
+ * whichever arm ran and whichever of them that arm actually assigned.
+ *
+ * The block is a MATERIALISATION MECHANISM, not a signal. Stack lowering reads
+ * the node's `results` list — it does not count or recognise this block, and
+ * has not since the multi-result branch node landed (the `countMergedLocalResults`
+ * inference it used to do is deleted in all seven tiers). The prefix survives
+ * in two roles only: naming the temps, and letting the lowerer REFUSE an ANF
+ * that carries the block without `results`, which is a pre-multi-result wire
+ * format no current compiler can produce.
+ *
+ * The prefix is part of the ANF wire format: all seven compilers emit and
+ * recognise the same block.
+ */
+export declare const MERGED_LOCAL_TEMP_PREFIX = "__merge$";

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

@@ -0,0 +1,33 @@
+/**
+ * ANF IR — A-Normal Form intermediate representation (Pass 4 output).
+ *
+ * This is the **canonical conformance boundary** for Rúnar compilers.
+ * Two compilers that accept the same Rúnar source MUST produce
+ * byte-identical ANF IR (when serialised with canonical JSON).
+ *
+ * Every compound expression is decomposed into a flat sequence of
+ * let-bindings whose right-hand sides are *simple* values: constants,
+ * variable references, a single primitive operation, or a branch/loop.
+ */
+/**
+ * Name prefix for the temporaries 04-anf-lower appends to BOTH arms of an
+ * if-statement that merges two or more locals (`appendMergedLocalResults`).
+ *
+ * Emitted by `appendBranchResults` (04-anf-lower) for — and ONLY for — an `if`
+ * that declares `results`. Both arms end with an identical 2K-binding block:
+ * K copies into `__merge$0..K-1`, then K rebinds of the declared results from
+ * those temps. That makes each arm hold exactly `results`, in `results` order,
+ * whichever arm ran and whichever of them that arm actually assigned.
+ *
+ * The block is a MATERIALISATION MECHANISM, not a signal. Stack lowering reads
+ * the node's `results` list — it does not count or recognise this block, and
+ * has not since the multi-result branch node landed (the `countMergedLocalResults`
+ * inference it used to do is deleted in all seven tiers). The prefix survives
+ * in two roles only: naming the temps, and letting the lowerer REFUSE an ANF
+ * that carries the block without `results`, which is a pre-multi-result wire
+ * format no current compiler can produce.
+ *
+ * The prefix is part of the ANF wire format: all seven compilers emit and
+ * recognise the same block.
+ */
+export const MERGED_LOCAL_TEMP_PREFIX = '__merge$';

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

@@ -0,0 +1,288 @@
+/**
+ * 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.
+ */
+import type { ANFProgram } from './anf-ir.js';
+import type { StackProgram } from './stack-ir.js';
+export interface ABIParam {
+    name: string;
+    type: string;
+    /**
+     * Present when this ABI param represents an expanded FixedArray<T, N>.
+     * Callers can pass a plain array of length N; the SDK will flatten it
+     * into the underlying positional slots by `syntheticNames` order.
+     */
+    fixedArray?: {
+        elementType: string;
+        length: number;
+        syntheticNames: string[];
+    };
+}
+export interface ABIConstructor {
+    params: ABIParam[];
+}
+export interface ABIMethod {
+    name: string;
+    params: ABIParam[];
+    isPublic: boolean;
+    /** True for stateful contract methods that don't mutate state (no continuation output). */
+    isTerminal?: boolean;
+    /** True if the unlocking script is prefixed with `_codePart` (issue #100). */
+    usesCodePart?: boolean;
+    /**
+     * Issue #123: BIP-143 sighash type from a `@sighash` directive (e.g. `0x43`
+     * for SINGLE|FORKID). Absent = default `ALL|FORKID` (0x41).
+     */
+    sigHashType?: number;
+}
+export interface ABI {
+    constructor: ABIConstructor;
+    methods: ABIMethod[];
+}
+export interface SourceMapping {
+    opcodeIndex: number;
+    sourceFile: string;
+    line: number;
+    column: number;
+}
+export interface SourceMap {
+    mappings: SourceMapping[];
+}
+/**
+ * A compile-time default value for a state field.
+ *
+ * For scalar state fields this is a single `string | bigint | boolean`.
+ * For grouped FixedArray state fields the assembler stores a real
+ * JS array of element-typed values so the SDK can consume it without
+ * parsing a stringified tuple. For nested FixedArrays (e.g.
+ * `FixedArray<FixedArray<bigint, 2>, 2>`) the initial value is a
+ * recursive nested array that mirrors the declared shape.
+ */
+export type StateFieldInitialValue = string | bigint | boolean | ReadonlyArray<StateFieldInitialValue>;
+export interface StateField {
+    name: string;
+    type: string;
+    index: number;
+    initialValue?: StateFieldInitialValue;
+    /**
+     * For state fields representing an expanded FixedArray<T, N>:
+     * - `type` is the user-facing type string (e.g. `FixedArray<bigint, 9>`)
+     * - `fixedArray.elementType` is the element primitive type (e.g. `bigint`)
+     * - `fixedArray.length` is N
+     * - `fixedArray.syntheticNames` is the flat list of underlying scalar
+     *   state-field names (`Board__0`..`Board__8`), in order.
+     *
+     * Runtime SDKs use this to flatten and unflatten arrays on state read/write.
+     */
+    fixedArray?: {
+        elementType: string;
+        length: number;
+        syntheticNames: string[];
+    };
+    /**
+     * Wire encoding of the serialized field:
+     *  - 'num2bin-le8': bigint — 8 raw bytes, little-endian sign-magnitude
+     *                   (OP_NUM2BIN 8 semantics; sign bit = MSB of last byte).
+     *  - 'bool1':       bool — 1 raw byte (0x00 / 0x01).
+     *  - 'raw':         fixed-size byte types — raw bytes, no framing
+     *                   (PubKey 33, Addr/Ripemd160 20, Sha256 32, Point 64).
+     *  - 'pushdata':    variable-length types — push-data framed (length
+     *                   prefix + bytes); byte length is value-dependent.
+     */
+    encoding?: 'num2bin-le8' | 'bool1' | 'raw' | 'pushdata';
+    /** Byte offset from the byte AFTER the OP_RETURN separator. Omitted when
+     *  any preceding field is variable-length. */
+    byteOffset?: number;
+    /** Serialized length in bytes (for fixedArray fields: total across all
+     *  flattened leaves). Omitted for variable-length fields. */
+    byteLength?: number;
+    /** NEGATIVE byte offset from the END of the locking script (the state
+     *  tail is the script's suffix, so `scriptLen + tailOffset` is the
+     *  field's start). Omitted when this or any following field is
+     *  variable-length. */
+    tailOffset?: number;
+}
+/**
+ * One deploy-baked constructor slot: a 1-byte OP_0 placeholder in the
+ * TEMPLATE script (`artifact.script`) that the SDK replaces with the
+ * encoded constructor arg at deploy time.
+ *
+ * The verification-descriptor fields (`name`, `type`, `valueEncoding`,
+ * `fixedValueByteLength`, `fixedPushHeaderBytes`) are additive metadata that
+ * make cross-contract verification MECHANICAL: a consuming contract (or
+ * off-chain verifier) that inspects a companion input's parent transaction
+ * can locate each baked readonly value without re-deriving offsets by
+ * diffing/`indexOf`-ing compiled scripts — which is fragile and encoding-
+ * sensitive (bigint values 1..16 bake as a single OP_N opcode byte, 0 bakes
+ * as OP_0, and >=17 bakes as a multi-byte push that shifts every downstream
+ * offset).
+ *
+ * DESIGN SPLIT (value-independence): the compiler cannot know the byte
+ * length a slot occupies after deployment — that depends on the VALUE baked
+ * at deploy time (a 33-byte PubKey push vs. a 1-byte OP_N). So the artifact
+ * carries only value-INDEPENDENT metadata here, and the SDK's
+ * `resolveSlotLayout(artifact, constructorArgs)` / `computeTemplateHash(
+ * artifact, constructorArgs)` resolve concrete offsets/lengths/hashes for
+ * GIVEN args.
+ */
+export interface ConstructorSlot {
+    /** Index into `abi.constructor.params`. */
+    paramIndex: number;
+    /** Byte offset of the 1-byte OP_0 placeholder in the template script. */
+    byteOffset: number;
+    /** Constructor parameter name (matches `abi.constructor.params[paramIndex].name`). */
+    name?: string;
+    /** ABI type of the parameter (e.g. `PubKey`, `bigint`, `ByteString`). */
+    type?: string;
+    /**
+     * How the deploy-time value is encoded when spliced into the slot:
+     *  - 'data':      raw data push (push header + value bytes). Fixed-size
+     *                 types (PubKey 33B, Sha256 32B, ...) always take
+     *                 header 1B + value NB; variable-length ByteString
+     *                 header size depends on the value length.
+     *  - 'scriptnum': minimally-encoded Script number. 0 → OP_0 (1 opcode
+     *                 byte), 1..16 → single OP_N opcode byte (0x50+N),
+     *                 -1 → OP_1NEGATE, else 1-byte header + LE
+     *                 sign-magnitude bytes.
+     *  - 'bool':      single opcode byte (OP_TRUE / OP_0).
+     */
+    valueEncoding?: 'data' | 'scriptnum' | 'bool';
+    /** For fixed-size data types only: the baked value length in bytes
+     *  (PubKey 33, Sha256 32, Addr/Ripemd160 20, Point 64). */
+    fixedValueByteLength?: number;
+    /** For fixed-size data types only: the push-header length in bytes that
+     *  precedes the value (1 for all lengths <= 75). */
+    fixedPushHeaderBytes?: number;
+}
+export interface CodeSepIndexSlot {
+    /** Byte offset of the OP_0 placeholder in the template script */
+    byteOffset: number;
+    /** The template-relative codeSeparatorIndex value this placeholder represents */
+    codeSepIndex: number;
+}
+/**
+ * One piece of the slot-excised template identity.
+ *
+ * The resolved code part (template with constructor args spliced in) is
+ * split at every constructor slot's VALUE bytes: `code` pieces are the
+ * byte runs kept in the template (including each slot's push header, whose
+ * presence pins the baked value's length), `slot` pieces are the excised
+ * value bytes. A verifier recomputes the template hash by concatenating
+ * the `code` pieces of a candidate script — using the concrete boundaries
+ * from the SDK's `resolveSlotLayout` — and hashing the result.
+ */
+export interface TemplateDigestPiece {
+    kind: 'code' | 'slot';
+    /** For kind 'slot': the excised slot's constructor param name. */
+    slot?: string;
+    /** For kind 'slot': the slot's TEMPLATE byte offset (disambiguates
+     *  multiple slots baked from the same parameter). */
+    byteOffset?: number;
+}
+/**
+ * Recipe for recomputing the contract's slot-excised template hash.
+ *
+ * `hash256-excised-slots`: hash256 (double SHA-256) over the resolved code
+ * part with every constructor slot's VALUE bytes removed. Push headers of
+ * 'data'/'scriptnum' pushes remain in the hashed template; single-opcode
+ * encodings (OP_N / OP_0 / OP_1NEGATE / bool) contribute no header and the
+ * opcode byte itself is excised.
+ */
+export interface TemplateDigest {
+    algorithm: 'hash256-excised-slots';
+    /** Alternating code/slot pieces, in script order (starts and ends with a
+     *  `code` piece; boundary `code` pieces may be empty byte runs). */
+    pieces: TemplateDigestPiece[];
+}
+/**
+ * Byte range in the locking script produced by a `raw_script` ANF node
+ * (surfaced in source as `asm({ body, in_arity, out_arity })`).
+ *
+ * The static analyzer treats these spans as opaque — it does not walk the
+ * opcodes inside, since `raw_bytes` is a peephole barrier and the contents
+ * may be arbitrary bytes that don't form a well-formed opcode stream. The
+ * declared `inArity` / `outArity` carry the stack-effect contract so depth
+ * tracking remains sound across the span.
+ */
+export interface RawScriptSpan {
+    /** Byte offset of the span start in the locking script. */
+    offset: number;
+    /** Total length of the span, in bytes. */
+    length: number;
+    /** Number of stack values consumed before the span executes. */
+    inArity: number;
+    /** Number of stack values left on the stack after the span executes. */
+    outArity: number;
+}
+export interface RunarArtifact {
+    /** Schema version, e.g. "runar-v0.1.0" */
+    version: string;
+    /** Semver of the compiler that produced this artifact */
+    compilerVersion: string;
+    /** Name of the compiled contract */
+    contractName: string;
+    /**
+     * The base class the contract extends. Distinguishes stateful contracts
+     * (which auto-inject `checkPreimage` at method entry, placing the user
+     * `checkSig` AFTER the OP_CODESEPARATOR) from stateless / unsafe contracts.
+     *
+     * This is the authoritative stateful signal for the issue-#42 terminal
+     * sighash subscript trim: a `StatefulSmartContract` with zero mutable
+     * fields still needs the trim, even though its `stateFields` array is
+     * empty. Older artifacts that predate this field omit it.
+     */
+    parentClass?: 'SmartContract' | 'StatefulSmartContract' | 'UnsafeSmartContract';
+    /** Public ABI (constructor + methods) */
+    abi: ABI;
+    /** Hex-encoded locking script */
+    script: string;
+    /** Human-readable assembly (space-separated opcodes) */
+    asm: string;
+    /** Optional source-level debug mappings */
+    sourceMap?: SourceMap;
+    /** Optional IR snapshots for debugging / conformance checking */
+    ir?: {
+        anf?: ANFProgram;
+        stack?: StackProgram;
+    };
+    /** ANF IR for SDK state computation (always included for stateful contracts) */
+    anf?: ANFProgram;
+    /** State field descriptors (present only for stateful contracts) */
+    stateFields?: StateField[];
+    /** Byte offsets of constructor parameter placeholders in the script,
+     *  enriched with verification-descriptor metadata (name/type/encoding). */
+    constructorSlots?: ConstructorSlot[];
+    /** Recipe for recomputing the slot-excised template identity hash. */
+    templateDigest?: TemplateDigest;
+    /** Byte offsets of codeSepIndex placeholders in the script (OP_0 placeholders
+     *  that the SDK must replace with the adjusted codeSeparatorIndex). */
+    codeSepIndexSlots?: CodeSepIndexSlot[];
+    /** Byte offset of OP_CODESEPARATOR in the locking script (for BIP-143 sighash) */
+    codeSeparatorIndex?: number;
+    /** Per-method OP_CODESEPARATOR byte offsets (index 0 = first public method, etc.). */
+    codeSeparatorIndices?: number[];
+    /** Byte ranges produced by `raw_script` ANF nodes (opaque to the analyzer). */
+    rawScriptSpans?: RawScriptSpan[];
+    /** ISO-8601 build timestamp */
+    buildTimestamp: string;
+    /**
+     * Builtins reached by this script that the project does not claim are sound
+     * (R-062 / CL-BUG-105). Today the only member is `verifySP1FRI`, whose
+     * codegen is a documented proof-of-concept with stubbed protocol algebra.
+     *
+     * The compiler already REFUSES to emit such a script unless the author wrote
+     * `@acknowledgeUnsoundSP1FriVerifier` or the invoker passed
+     * `--acknowledge-unsound-sp1-fri`. That acknowledgement stopped at whoever
+     * ran the compiler: the artifact handed on afterwards looked like any other,
+     * and every SDK funded it without a word. Present here, the fact travels with
+     * the artifact, and each SDK's deploy path refuses to fund it unless the
+     * caller acknowledges the same list.
+     *
+     * Absent (not empty) on every artifact that reaches no such builtin, so
+     * nothing else in the repo is affected.
+     */
+    unsoundPrimitives?: string[];
+}