Struct WasmEngine 

pub struct WasmEngine { /* private fields */ }

The session engine, wasm-side.

Implementations

impl WasmEngine

pub fn new(seed: u64, pool_size: usize) -> WasmEngine

Create an engine with the default grammar and session config.

pub fn makeup_of(&self, id: u32) -> f64

Loudness-makeup linear gain for live playback of candidate id (evens patches out to the audition target). 1.0 for unknown ids.

pub fn edit_makeup(&self) -> f64

Loudness-makeup linear gain for the current workbench tree.

pub fn fill_step(&mut self, max_new: usize) -> usize

Add up to max_new vetted candidates. Returns how many were added, so the worker can post fill progress between calls.

The serial path, and the fallback whenever no farm is available. It folds the same indexed draw stream fill_draw/fill_absorb fold, so the pool it builds is the pool the farm builds.

pub fn phrase_json(&self) -> String

The audition stimulus as JSON, for the farm handshake.

Shipped rather than assumed: a farm worker that defaulted its own PhraseSpec would measure φ under a different stimulus the moment the engine’s phrase ever becomes configurable, and the drift would be silent because every individual render would still be internally consistent.

pub fn fill_cursor(&self) -> u32

Next index of the pool draw stream the engine will fold in.

pub fn fill_draw(&mut self, n: usize) -> String

Hand out up to n unrendered draws as JSON [{"i":7,"tree":{…},"dup":false}], possibly shorter than n or empty.

Empty means “nothing to issue right now” — the pool has as much work outstanding as it can use, or the draw budget is spent. It is a stop signal only in combination with nothing outstanding; see Engine::fill_draw.

pub fn draw_json(&self, index: u32) -> String

The term at index of the draw stream, as JSON ("" before the stream starts).

The re-issue path: a farm worker that dies or hangs loses nothing but its render, because the job it was doing is fully named by its index. No tree JSON has to be retained anywhere to recover it.

pub fn fill_absorb( &mut self, index: u32, cached_json: &str, samples: &[f32], ) -> u32

Fold one farm result into the pool, in index order.

cached_json == "" (or samples whose length disagrees with the render the farm reported) means the draw did not survive: the index is consumed and 0 returned, exactly as a vet failure burns an attempt in the serial loop. Returns the new candidate id otherwise, or 0 for a duplicate or a full pool.

pub fn import_session_deferred(&mut self, json: &str) -> String

Restore a session but leave the bank un-rendered: returns JSON [{"i":0,"tree":{…}}] in bank order. Every entry must come back through WasmEngine::bank_absorb, after which WasmEngine::restore_finish closes the restore.

pub fn bank_draw_json(&self, index: usize) -> String

The term of pending bank entry index, as JSON ("" if unknown) — the restore path’s re-issue hook.

pub fn bank_absorb( &mut self, index: usize, cached_json: &str, samples: &[f32], ) -> bool

Reinstate one restored bank entry from an off-engine featurization. Returns false for an unknown index or a result that did not survive — a bank entry that no longer vets is dropped, exactly as the serial restore drops it.

pub fn bank_render(&mut self, index: usize) -> bool

Featurize and reinstate pending bank entry index in this worker.

The deferred restore’s serial completion: whatever the farm did not finish is finished here, so a restore never depends on the farm having survived. Same work, same order, same result — it just blocks.

pub fn restore_finish(&mut self) -> usize

Close a deferred restore (standardizer + φ resolution). Returns the number of bank entries that landed.

pub fn standardize_now(&mut self)

Make the pool duel-able now, mid-fill: standardize every member, fitting a standardizer over whatever has been drawn so far if none exists yet. Cheap — no renders, just mean/variance over φ.

This is what lets a progressive boot hand the user a duel after ~8 candidates instead of after all 40: next_duel refuses any candidate with an empty phi_std, and without this the engine only standardizes when the pool first reaches its target.

pub fn restandardize_if_untaught(&mut self)

Re-fit the standardizer once the fill completes, over the full pool rather than the first few draws. No-op if a posterior already exists — moving the scale under live θ would rescale every utility on screen.

pub fn status(&self) -> String

Engine status as JSON.

pub fn next_duel(&mut self) -> String

Choose the next duel: JSON [idA, idB], or null if the pool is small. See WasmEngine::next_duel_ex for the annotated form.

pub fn next_duel_ex(&mut self) -> String

Choose the next duel, with the reasoning attached — null if the pool is too small:

{"a":12,"b":31,"info_gain":0.41,"random_check":false,"method":"bald"}

a/b are candidate ids. info_gain is expected information about θ in nats (max ln 2 ≈ 0.693). method is "bald", "check" (a uniformly-random calibration probe — worth labelling in the UI, since the model is deliberately not choosing it) or "random" (no posterior yet).

pub fn render_of(&mut self, id: u32) -> Vec<f32>

The audition buffer of candidate id (mono, ±1.0), for WebAudio.

&mut self, and it can take a render. Under the lazy policy this engine boots with, the buffer is materialized here on first request rather than retained from the fill. An empty return means the term no longer renders (a restored bank can outlive the DSP that made it) — callers must treat it as a failure and stop waiting, not as “not yet”.

pub fn prefetch_render(&mut self, id: u32) -> bool

Materialize id’s audition buffer without returning it.

The deal path calls this for both sides the moment a pair is chosen, so the lazy render happens while the user is still reading the cards rather than after they press ▶. Cheap and idempotent once resident.

pub fn memo_stats(&self) -> String

Featurization-memo counters as JSON ({hits, misses, features, audio, audio_bytes}) — how much rendering the memo is deleting, and how much audio is resident.

pub fn sample_rate(&self) -> f64

The render sample rate.

pub fn sexpr_of(&self, id: u32) -> String

Patch term of candidate id, as an s-expression.

pub fn tree_json_of(&self, id: u32) -> String

The patch tree of candidate id as JSON — the payload the live instrument (LivePoly in the AudioWorklet) compiles and plays.

pub fn edit_tree_json(&self) -> String

The workbench tree as JSON (null if the bench is empty), for live playing of in-progress edits.

pub fn describe_of(&self, id: u32) -> String

Rack description (modules, knobs with live trace addresses, wires) of candidate id, as JSON. null for an unknown id.

pub fn record_duel(&mut self, a: u32, b: u32, chose_a: bool)

Record a duel outcome between candidate ids.

pub fn record_keep(&mut self, id: u32, kept: bool)

Record a keep/kill decision on a candidate id.

pub fn record_stars(&mut self, id: u32, rating: u8)

Record a star rating on a candidate id.

pub fn fit(&mut self)

Re-fit the taste posterior from the log (seconds of MCMC — worker!).

pub fn refine(&mut self)

One round of taste-guided refinement (renders — worker!).

pub fn refine_begin(&mut self) -> String

Open a generation; returns the parent ids to refine from as a JSON array, or [] if there is no taste to refine toward yet (in which case no generation is opened).

Paired with WasmEngine::refine_seed so the caller can drive a generation one seed at a time and show progress. A generation is tens of seconds of render-bound work; as a single call it looks like a hang.

pub fn refine_seed(&mut self, parent_id: u32) -> u32

Refine one seed of the open generation. Returns the child id, or 0 if the walk was rejected or landed on a patch already in the pool.

pub fn refine_from(&mut self, id: u32, locked_json: &str) -> u32

Locked refinement from candidate id: evolve everything except the locked addresses (locked_json = JSON array of key#site strings). Returns the new child id, or 0 if no move was accepted.

pub fn ranked(&self) -> String

Ranked pool as JSON ([{id, mean, std, origin, name, named, signature, sexpr}]).

pub fn name_of(&self, id: u32) -> String

Display name of one candidate (user-given, else musical).

pub fn explain(&self, id: u32) -> String

Why this patch scores what it does, as JSON, or null before the first fit / for an unknown id:

{"id":12,"style":1,"style_name":"Dark Drones",
 "utility":0.84,"utility_std":0.31,
 "mix_utility":0.91,"responsibility":0.86,
 "contributions":[{"name":"centroid_mean","theta":0.42,
                   "phi_std":1.01,"contribution":0.42}, …]}

Contributions are sorted by descending |contribution| and sum exactly to utility — utility is linear within a lens, so this is an exact decomposition rather than a surrogate approximation.

Draw mix_utility as the score. It is the value ranked() sorts the bank by; utility is the lens-conditional quantity the contributions explain, and it is always ≤ mix_utility. Rendering utility beside a row ranked by mix_utility shows a number that disagrees with its own list. responsibility says how much that distinction matters for this patch: near 1 the two coincide, well below 1 the patch sits between styles.

pub fn calibration(&self) -> String

Prequential calibration as JSON — a proper score, replacing the running hit rate (which is not one, and which the acquisition function pins near 50 % by design):

{"n":42,"brier":0.19,"log_loss":0.58,"skill":0.24,
 "bins":[{"lo":0.0,"hi":0.2,"n":7,"predicted":0.11,"observed":0.14}, …],
 "check_n":4,"check_skill":0.18,"check_log_loss":0.61,"hit_rate":0.55}

skill is 1 − Brier/0.25: 0 means no better than a coin flip, 1 means perfect and certain. log_loss is in nats (ln 2 ≈ 0.693 is the coin-flip baseline). bins is the reliability diagram over P(A wins). check_* restricts the score to the uniformly-random check duels, which is the only selection-bias-free number here.

pub fn taste_map(&self) -> String

The 2D taste map (pool + history ghosts) as JSON, or null when there is too little to project.

pub fn styles(&self) -> String

Style lenses of the aligned posterior as JSON ([{share, theta: [{name, mean, std}], exemplars: [ids]}]), or null before the first fit. Inactive lenses have share ≈ 0.

pub fn phi_scale(&self) -> String

The standardizer’s per-coordinate scale, as {"n_filter":1.42,…} ({} before one is fitted).

θ lives in standardized space and everything that has ever been shown to the user lived there with it, which was fine while the only claim being made was “this coefficient is positive”. Pricing a placement is a different claim: adding one filter is a raw unit step in n_filter, and turning that into a utility needs the divisor that carried it into z-scores. Without it the client can render θ and cannot render what θ is worth.

Names rather than a bare vector, because the client already keys every module to its coordinate by name (MODULES[k].phi) and an index agreement across the wasm boundary is a silent-drift bug waiting for the next φ column to land. Mean is deliberately absent: a delta is invariant to it, so shipping it would only invite someone to use it.

pub fn lineage(&self) -> String

The lineage log (evolution/edit events, oldest first) as JSON.

pub fn set_name(&mut self, id: u32, name: &str)

Name (or rename; empty clears) a candidate.

pub fn set_pinned(&mut self, id: u32, pinned: bool) -> bool

Pin or unpin a patch against eviction. Returns false when the id is gone or the pin budget is full — the caller must say which, because a pin control that silently does nothing is the exact failure this whole mechanism exists to end.

pub fn pin_budget(&self) -> Vec<u32>

How many patches are pinned, and the ceiling, as [count, cap].

pub fn set_style_name(&mut self, k: usize, name: &str)

Name an aligned style index.

pub fn log_event(&mut self, kind: &str, id: u32, value: f64)

Log an implicit preference event (promote, play counts, …).

pub fn duel_pred(&self, a: u32, b: u32) -> f64

Model’s predicted probability that a beats b (−1 before the first fit / unknown ids).

pub fn best_style_of(&self, id: u32) -> i32

The aligned style index that best explains candidate id (−1 before the first fit / unknown id).

pub fn preset_list(&self) -> String

The built-in preset bank as JSON ([{index, name, category, blurb, sig}]).

category is what the browser groups by and what the warm start samples across — with the library past two dozen, an unstratified sample of nine would keep landing in one corner of the space, which is the same cold-start bias the warm start exists to remove.

pub fn load_preset(&mut self, index: usize) -> u32

Load preset index into the bank; returns its id (existing id if the identical patch is already there), or 0 on failure.

pub fn import_patch(&mut self, tree_json: &str, name: &str) -> u32

Import a shared patch (tree JSON + optional name) into the bank. Returns the new id, or 0 (bad JSON / duplicate / vet failure).

pub fn edit_begin(&mut self, id: u32) -> bool

Load candidate id onto the workbench. Returns false for unknown id.

pub fn edit_param(&mut self, addr: &str, value: f64, is_index: bool) -> bool

Write one knob on the workbench tree (value is the normalized continuous value, or the index when is_index), then re-render and re-vet. Returns false if the edit was rejected (structural site, unknown address, no workbench).

pub fn edit_structure_apply(&mut self, op_json: &str) -> String

Adopt a structural edit (replace/insert/delete/set_mod/swap_mix, as JSON — see auracle_grammar::StructOp) without re-rendering. Returns an empty string on success or the rejection reason.

Split out of Self::edit_structure because the render is the entire cost. The live worklet can swap a new tree in ~23 ms; the featurizer takes the better part of a second, and the only thing that ever put it between a player’s gesture and the sound was that the two lived in one call. A caller that splits gets to speak to the audio thread first and featurize after — but it owes a following Self::edit_revet, because until then edit_render/edit_vet_ok describe the tree before this edit.

pub fn edit_set_tree_apply(&mut self, tree_json: &str) -> String

Adopt a whole replacement workbench tree (undo/redo restore, and every client-side rewrite the graph editor commits) without re-rendering. Returns an empty string on success or the rejection reason.

The ceiling check is the load-bearing line. This route does not go through apply_struct_op, so until validate_tree existed it was a hole straight through MAX_SIZE / MAX_DEPTH / MAX_MOD_DEPTH — and it is exactly the route a move or a reconnect uses. A patch built past those ceilings is not just big: it has ~zero mass under the prior, sits outside the range the standardizer was fitted on, and gets mutated back inside them by the next refinement, so the player’s structure disappears on the next evolve with nothing ever having said no.

pub fn edit_revet(&mut self)

Re-render and re-vet whatever tree is currently on the bench.

The expensive half of an edit, callable on its own so the cheap half can be delivered to the ear first. Idempotent.

pub fn edit_structure(&mut self, op_json: &str) -> String

Apply a structural edit and re-render in one call — apply + revet, for callers with nothing to do in between.

pub fn edit_set_tree(&mut self, tree_json: &str) -> String

Replace the whole workbench tree and re-render in one call.

pub fn edit_render(&self) -> Vec<f32>

The workbench audition buffer (empty when the current edit failed vetting — the gate’s rule is that no unvetted patch ever plays).

pub fn edit_vet_ok(&self) -> bool

Whether the current workbench state passed vetting.

pub fn preview_op(&mut self, op_json: &str, seconds: f64) -> Vec<f32>

Render the first seconds of the bench tree with op applied, without the bench ever having held that tree.

Hearing a module before you place it is the whole point, and the one thing it must not cost is the patch you already have. Every other route to a rendered edit goes through bench_tree — apply, revet, and now the player’s patch is the proposal, recoverable only by an undo they did not ask for. So this clones, applies to the clone, and drops it: bench_tree, bench_render, bench_phi and bench_vet_ok are all untouched, which is what lets a hover be free of consequence.

It takes a whole StructOp rather than a key and a fragment because the placement it is previewing is a StructOp — the same JSON, from the same call site. A preview built from a re-derived splice would be a second implementation of insertion semantics, and the day the two disagreed the app would be lying about a sound.

The render is the full phrase, truncated after the fact. Two reasons, and the second is the one that makes previewing usable at all: a shorter phrase is a different stimulus, so its φ would not be the φ this patch is scored under and its loudness normalization would not match the bench’s; and the full phrase is the memo’s key, so re-hovering a socket — which is what hovering is — costs a hash lookup instead of a render. An empty return means “nothing to play”: no bench, a rejected op, or a term that failed vetting. Never a silent zero-filled buffer.

pub fn edit_describe(&self) -> String

Rack description of the workbench tree as JSON (null if empty).

pub fn edit_commit(&mut self, outcome: &str) -> u32

Commit the workbench tree as a new candidate. Returns the new candidate id, or 0 (duplicate / unvetted / empty bench).

outcome is what the player reported about the edit against the original, as a wire string:

• "none" — they said nothing. Lineage only.
• "heard_edited" / "heard_original" — they heard both and picked. "heard_original" is the point of this API: an edit that lost is the more informative half of the comparison and had no way to be said before (EditOutcome).
• "self_edited" — the express “my edit is better” checkbox, tagged [Provenance::SelfReport] so calibration can score an assertion against a heard comparison instead of averaging them.

An unknown string is "none": a typo must not silently become a vote.

pub fn edit_original_id(&self) -> u32

The pool id the bench was opened from (0 for none) — what a commit duel plays against.

pub fn edit_differs_from_original(&self) -> bool

Has the bench actually diverged from the patch it was opened from?

The gate on dealing a real duel at commit. The panel’s own dirty flag answers “did the player touch anything”, which is not the same question: turn a knob and turn it back, or undo to the start, and there is nothing to compare. Asking two patches that are the same patch which one is better is a question with no answer, and an answer to it is a row of noise in the log.

PatchTree’s equality is content equality — Uid’s PartialEq is unconditionally true by construction (see term.rs), so a reconnect that reissued nothing and a rewrite that minted fresh identities compare the same way, which is what “the same patch” has to mean here.

pub fn edit_utility(&self) -> String

What the model currently thinks of the tree on the bench: {"ok":bool,"u":f64,"sd":f64,"lens":string}.

u is the mixture utility — the same quantity the bank is ranked by, so the number above the rack and the number beside the patch in the bank are the same claim. ok:false means there is nothing honest to show yet (no posterior, no standardizer, or a bench that failed vetting), and the panel says so rather than drawing a zero.

pub fn edit_explain(&self) -> String

The exact per-feature decomposition of that number (null before the first fit). Same shape as Self::explain, for the bench.

pub fn log_edit_event( &mut self, kind: &str, id: u32, value: f64, detail: &str, with_phi: bool, )

Append one row of the editor’s implicit stream (WS-8 §3): a revert, a commit, an evolve-from, a structural op, a link-drag query.

detail is opaque JSON. with_phi attaches the bench’s φ on both sides of the event, which only a transition (a revert) has — everything else passes false and stores the strings it knows.

None of this enters the likelihood, and that is deliberate: a revert is confounded with plain curiosity, and the fit the app shows a number from is not the place to smuggle in an unvalidated signal. It is logged because it cannot be logged retroactively.

pub fn edit_cancel(&mut self)

Clear the workbench.

pub fn export_session(&self) -> String

Export the full session (profile + bank trees/names/origins + lineage) as JSON, for autosave.

pub fn import_session(&mut self, json: &str) -> usize

Restore a saved session (replacing pool, log, lineage). Returns the number of bank entries restored, 0 on parse failure. Re-featurizes every tree — seconds of work; call from the worker.

pub fn repair_report(&self) -> String

What the last restore had to mend, as JSON {"terms":n,"cells":n,"dropped":n} — saved patches whose knobs were outside their range, observation-log cells clamped back inside it, and votes dropped because a coordinate was not a number.

All three are 0 for any session written by a build that carries the domain gate. Non-zero means the profile was being fitted on values that were not measurements, and the player is entitled to be told so rather than have it quietly corrected under them.

pub fn export_profile(&self) -> String

Export the portable profile (observation log + its standardizer — θ is only meaningful relative to the standardizer, so they travel together) as JSON.

pub fn import_profile(&mut self, json: &str) -> bool

Import a profile, replacing the log, adopting its standardizer, and starting a new session on top. Returns false on parse failure.

Trait Implementations

impl From<WasmEngine> for JsValue

fn from(value: WasmEngine) -> Self

Converts to this type from the input type.

impl FromWasmAbi for WasmEngine

type Abi = WasmPtr<WasmRefCell<WasmEngine>>

The Wasm ABI type that this converts from when coming back out from the ABI boundary.

unsafe fn from_abi(js: Self::Abi) -> Self

Recover a Self from Self::Abi.

impl IntoWasmAbi for WasmEngine

type Abi = WasmPtr<WasmRefCell<WasmEngine>>

The Wasm ABI type that this converts into when crossing the ABI boundary.

fn into_abi(self) -> Self::Abi

Convert self into Self::Abi so that it can be sent across the wasm ABI boundary.

impl LongRefFromWasmAbi for WasmEngine

type Abi = WasmPtr<WasmRefCell<WasmEngine>>

Same as RefFromWasmAbi::Abi

type Anchor = RcRef<WasmEngine>

Same as RefFromWasmAbi::Anchor

unsafe fn long_ref_from_abi(js: Self::Abi) -> Self::Anchor

Same as RefFromWasmAbi::ref_from_abi

impl OptionFromWasmAbi for WasmEngine

fn is_none(abi: &Self::Abi) -> bool

Tests whether the argument is a “none” instance. If so it will be deserialized as None, and otherwise it will be passed to FromWasmAbi.

impl OptionIntoWasmAbi for WasmEngine

fn none() -> Self::Abi

Returns an ABI instance indicating “none”, which JS will interpret as the None branch of this option.

impl RefFromWasmAbi for WasmEngine

type Abi = WasmPtr<WasmRefCell<WasmEngine>>

The Wasm ABI type references to Self are recovered from.

type Anchor = RcRef<WasmEngine>

The type that holds the reference to Self for the duration of the invocation of the function that has an &Self parameter. This is required to ensure that the lifetimes don’t persist beyond one function call, and so that they remain anonymous.

unsafe fn ref_from_abi(js: Self::Abi) -> Self::Anchor

Recover a Self::Anchor from Self::Abi.

impl RefMutFromWasmAbi for WasmEngine

type Abi = WasmPtr<WasmRefCell<WasmEngine>>

Same as RefFromWasmAbi::Abi

type Anchor = RcRefMut<WasmEngine>

Same as RefFromWasmAbi::Anchor

unsafe fn ref_mut_from_abi(js: Self::Abi) -> Self::Anchor

Same as RefFromWasmAbi::ref_from_abi

impl TryFromJsValue for WasmEngine

fn try_from_js_value(value: JsValue) -> Result<Self, JsValue>

Performs the conversion.

fn try_from_js_value_ref(value: &JsValue) -> Option<Self>

Performs the conversion.

impl VectorFromWasmAbi for WasmEngine

type Abi = <Box<[JsValue]> as FromWasmAbi>::Abi

unsafe fn vector_from_abi(js: Self::Abi) -> Box<[WasmEngine]>

impl VectorIntoWasmAbi for WasmEngine

type Abi = <Box<[JsValue]> as IntoWasmAbi>::Abi

fn vector_into_abi(vector: Box<[WasmEngine]>) -> Self::Abi

impl WasmDescribe for WasmEngine

fn describe()

impl WasmDescribeVector for WasmEngine

fn describe_vector()

impl SupportsConstructor for WasmEngine

impl SupportsInstanceProperty for WasmEngine

impl SupportsStaticProperty for WasmEngine