@storylet-studio/runtime 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,656 @@
+import { ScalarValue, ScopeResolver, ExprNode } from '@wildwinter/expr';
+export { Prng, makePrng, shuffleInPlace } from '@wildwinter/expr';
+import { Bundle, Card, Expression, Deck, Box, Hand, HandTemplate, TagGroup, PropertyDecl, FlowSave, SaveEnvelope, PropertyType, ScalarValue as ScalarValue$1 } from '@storylet-studio/model';
+import { PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+
+interface EngineOptions {
+    /** Default seed for each flow's PRNG; override per flow in openFlow
+     *  (cross-runtime determinism, schema 3.3). Default 0. */
+    seed?: number;
+    /** Retain each flow's event log for introspection - the game-engine seam
+     *  (schema 5): every trace event, sequence-stamped and turn-stamped where
+     *  the event has a box context. `true` keeps the default 1000 entries
+     *  (oldest dropped first). Off by default; subscribeTrace stays the
+     *  zero-retention stream. */
+    log?: boolean | {
+        cap?: number;
+    };
+    /**
+     * The host's resolver for @world - the values the game owns and the
+     * story reads (and, where `set` is offered, writes). Omit it and the
+     * engine self-backs @world from the declared defaults. Engine-level,
+     * shared by all flows, never in saveGame(): the host saves its container
+     * once, each engine saves its own envelope (design/flows.md).
+     */
+    world?: ScopeResolver;
+}
+interface OpenFlowOptions {
+    /** Seed for this flow's PRNG (defaults to the engine's `seed`). */
+    seed?: number;
+}
+/** A card view in a dealt hand or a peeked list. Carries NO outcome
+ *  availability - ask `outcomes()` for current truth (schema 5). */
+interface DealtCard {
+    id: string;
+    gameId: string;
+    title?: string;
+    purpose?: string;
+    fields?: Record<string, ScalarValue>;
+}
+interface OutcomeView {
+    id: string;
+    gameId: string;
+    title?: string;
+    purpose?: string;
+    /** Evaluated against CURRENT state at the moment of the ask. */
+    available: boolean;
+}
+/** What a peek returns: the top of the stock, looked at and put back.
+ *  The engine has no pick policy (Reboot 2.1). */
+interface RankedList {
+    box: string;
+    cards: DealtCard[];
+}
+interface PlayOptions {
+    /** Turn advance override; default settings.playAdvancesTurns. */
+    advanceTurns?: number;
+}
+/** Why a card did or did not make an ask, in availability order (schema 3.1). */
+type TraceVerdict = "dealt" | "capped" | "cooldown" | "deck-gate" | "tags" | "condition" | "priority" | "claimed" | "claimed-elsewhere" | "taken";
+/** One event on the deal/play log - "why did Ambush at the ford get dealt
+ *  here?" is answered by the ask event's per-card verdicts and keys. The
+ *  verb is the event type, so a peek is distinguishable from a deal when
+ *  reading a run back. */
+type TraceEvent = {
+    type: "deal";
+    /** Hand gameId. */
+    hand: string;
+    cards: {
+        id: string;
+        verdict: TraceVerdict;
+        priority?: number;
+        specificity?: number;
+    }[];
+} | {
+    type: "peek";
+    /** Box gameId. */
+    box: string;
+    criteria: Record<string, string>;
+    cards: {
+        id: string;
+        verdict: TraceVerdict;
+        priority?: number;
+        specificity?: number;
+    }[];
+} | {
+    type: "evict";
+    hand: string;
+    card: string;
+    reason: TraceVerdict | "hand-condition" | "vanished";
+} | {
+    type: "play";
+    card: string;
+    outcome: string;
+    turn: number;
+}
+/** One landed outcome change; `path` is the resolved store location (a
+ *  routed @hand write shows where it actually went, schema 3.6). `prev`
+ *  is the value it replaced, so a log can read "0 -> 1". */
+ | {
+    type: "write";
+    target: string;
+    path: string;
+    value: ScalarValue;
+    prev?: ScalarValue;
+}
+/** An explicit clock advance via advanceTurns (schema 3.4); `turn` is the
+ *  box's new value. Plays stamp their own turn on the play event. */
+ | {
+    type: "turns";
+    box: string;
+    turn: number;
+}
+/** An expression eval error: never a silent pass (schema 3.1), always a
+ *  visible diagnostic. */
+ | {
+    type: "diagnostic";
+    where: string;
+    message: string;
+};
+type TraceHandler = (event: TraceEvent) => void;
+/** The engine-level tap: every flow's events, tagged with the flow id -
+ *  the tools' one stream. */
+type EngineTraceHandler = (flow: string, event: TraceEvent) => void;
+/** A retained log entry: the trace event plus its place in flow time.
+ *  `seq` orders the whole flow (monotonic; survives clearLog). `turn` is
+ *  the clock of the box the event happened in when it fired (peek: the box;
+ *  deal/evict: the hand's box; play and its writes: the played card's box,
+ *  stamped together with the play's own turn). Diagnostics carry no turn. */
+type LogEntry = TraceEvent & {
+    seq: number;
+    turn?: number;
+};
+/** One entry on the ENGINE's log: the same event, plus the flow it happened
+ *  in. A run is several flows over shared state, so "what happened in this
+ *  run" is only answerable in one ordered stream, and only if each line says
+ *  who. The flow's own log stays flow-local and unchanged. */
+type EngineLogEntry = LogEntry & {
+    flow: string;
+};
+interface CardEntry {
+    card: Card<Expression>;
+    deck: Deck<Expression>;
+    box: Box<Expression>;
+}
+/** One examiner row, addressed by the property-path grammar
+ *  (getProperty / setProperty take the same `path`). */
+interface PropertyView extends PropertyRow {
+    path: string;
+}
+/** One kernel bag with its store path prefix (story / box.<id> / deck.<id>
+ *  / hand.<id> / value.<id>): the state logger's mount surface
+ *  (design/engine-runtimes.md 3.4 - the logger builds on the PropertyBag
+ *  audit hook, so it needs the bags themselves, not just their rows).
+ *  The Engine lists the shared bags, a Flow its own; the @world container
+ *  is the host's bag and the host mounts it itself. loadGame() replaces
+ *  every bag, so re-enumerate after a load. */
+interface BagMount {
+    prefix: string;
+    bag: PropertyBag;
+}
+/** One box on the enumeration surface (examiners, hosts): identity plus
+ *  its clock (per flow). */
+interface BoxView {
+    id: string;
+    gameId: string;
+    title?: string;
+    turn: number;
+}
+/** One side's five stores (shared on the engine, per-flow on each flow). */
+interface Partition {
+    story: PropertyBag;
+    box: Map<string, PropertyBag>;
+    deck: Map<string, PropertyBag>;
+    hand: Map<string, PropertyBag>;
+    value: Map<string, PropertyBag>;
+}
+/** Everything a Flow shares with its Engine: the bundle-derived lookups
+ *  (immutable), the shared stores (replaced wholesale by loadGame/reset),
+ *  and the seams. One object, held by both classes - the two are one
+ *  machine in two lifetimes. */
+interface Internals {
+    bundle: Bundle;
+    logCap?: number;
+    cardsById: Map<string, CardEntry>;
+    cardsByGameId: Map<string, CardEntry>;
+    boxesByGameId: Map<string, Box<Expression>>;
+    boxesById: Map<string, Box<Expression>>;
+    handsById: Map<string, {
+        hand: Hand<Expression>;
+        box: Box<Expression>;
+    }>;
+    handsByGameId: Map<string, {
+        hand: Hand<Expression>;
+        box: Box<Expression>;
+    }>;
+    templatesById: Map<string, HandTemplate<Expression>>;
+    groupsById: Map<string, {
+        group: TagGroup;
+        box: Box<Expression>;
+    }>;
+    requiredGroups: Set<string>;
+    nodeCache: WeakMap<Expression, ExprNode>;
+    ladders: {
+        world: Map<string, readonly string[]>;
+        story: Map<string, readonly string[]>;
+        box: Map<string, Map<string, readonly string[]>>;
+        deck: Map<string, Map<string, readonly string[]>>;
+        value: Map<string, Map<string, readonly string[]>>;
+        hand: Map<string, Map<string, readonly string[]>>;
+    };
+    hasQualities: boolean;
+    /** Does ANY deck or card in the bundle opt into shared scarcity? False for
+     *  the overwhelming majority of projects, and when it is false the two
+     *  claim-ledger walks in dealing are skipped entirely. Same idea as
+     *  `hasQualities` above: a bundle that does not use a feature must not pay
+     *  for it. */
+    hasShared: boolean;
+    /** The per-flow halves of every declaration list, precomputed once: each
+     *  new flow builds its bags from these. */
+    flowDecls: {
+        story: PropertyDecl[];
+        box: Map<string, PropertyDecl[]>;
+        deck: Map<string, PropertyDecl[]>;
+        hand: Map<string, PropertyDecl[]>;
+        value: Map<string, PropertyDecl[]>;
+    };
+    /** The shared stores. Reassigned wholesale by loadGame/reset. */
+    shared: Partition;
+    /** @world: the host's resolver, or the self-backed bag's. */
+    worldResolver: ScopeResolver;
+    /** `turn` is the box clock the event happened on, where the caller knows it
+     *  - the same stamp the flow's own log carries. Unity and Unreal passed it
+     *  from the start; JS and Godot dropped it, so their examiners printed "[-]"
+     *  on every deal, peek, evict and write line while the other two printed the
+     *  real turn. Four runtimes, two different run logs (2026-08-29). */
+    emitEngine: (flow: string, event: TraceEvent, turn?: number) => void;
+    engineTracing: () => boolean;
+}
+declare class Engine {
+    private readonly internals;
+    private readonly seed;
+    private readonly flowsById;
+    private readonly engineTraceHandlers;
+    /** The host's @world binding, if the engine was built with one: it
+     *  outlives reset/loadGame (the host's container is the host's). The
+     *  self-backed resolver is rebuilt instead. */
+    private readonly hostWorld?;
+    constructor(bundle: Bundle, opts?: EngineOptions);
+    /** Build the shared stores and the @world seam. `hostWorld` sticks for the
+     *  engine's lifetime; reset/loadGame rebuild the shared bags around it. */
+    private initShared;
+    /** Quality ladders by scope for the eval channel (design/quality.md):
+     *  world/story keyed by name; box/deck/value keyed by owner id then name.
+     *  Built once - a bundle's declarations never change. Ladders are
+     *  declaration-level, so the sharing flag does not touch them. */
+    private initLadders;
+    /** Open (or REPLACE) the named flow. An existing id's flow is closed
+     *  first - re-opening a name is a reset of that name's whole per-flow
+     *  state; shared state is untouched. There is no default flow: "main" is
+     *  a caller convention, not an engine rule. */
+    openFlow(id: string, opts?: OpenFlowOptions): Flow;
+    getFlow(id: string): Flow | undefined;
+    /** Every live flow, open order. */
+    flows(): Flow[];
+    /** Close the named flow: its handle goes INERT (every verb throws). A
+     *  dropped-but-held flow must not keep writing shared state (Patter's
+     *  stale-handle lesson). Unknown ids are a quiet no-op, like closing a
+     *  closed door. */
+    closeFlow(id: string): void;
+    /** @internal - Flow.close() routes here so both doors agree. */
+    dropFlow(id: string, flow: Flow): void;
+    /** Close every flow and reseed the shared state to its defaults (the
+     *  self-backed @world included; a host-bound @world is the host's and is
+     *  not touched). */
+    reset(): void;
+    /** Cards a shared `redraw: "never"` has taken out of the world, by card id.
+     *  The claim ledger is DERIVED from live boards and so needs no storage;
+     *  this one is durable, so it rides the save's shared half. */
+    private spent;
+    /** @internal */
+    isTaken(cardId: string): boolean;
+    /** @internal */
+    markTaken(cardId: string): void;
+    /** Every flow's events in one ordered stream, each tagged with its flow.
+     *  Opt in with the same `log` option the flow logs use; capped the same way.
+     *
+     *  This exists because a flow's own log cannot answer the question a run
+     *  raises: when a story action in ANOTHER flow moves shared state, your
+     *  flow's log says nothing and your value simply changes. Reading a run
+     *  needs one stream that says who did what, and merging the per-flow logs by
+     *  hand is a thing every host would otherwise have to write. */
+    private engineLog;
+    private engineSeq;
+    log(): readonly EngineLogEntry[];
+    clearLog(): void;
+    /** @internal - shared claims across every LIVE flow, card id -> holders.
+     *  Derived, which is what makes closeFlow and the openFlow replace release
+     *  what a flow was holding: its board leaves the map with it. */
+    sharedClaims(): Map<string, number>;
+    /**
+     * Read shared state by path: "world.x", "story.gold" (when shared),
+     * "box.b_x.heat" (when shared). A ref that resolves PER-FLOW throws,
+     * naming the fix - silently answering with some flow's copy (or a junk
+     * default) was the bug Patter's engine.getProperty guard exists to stop.
+     */
+    getProperty(path: string): ScalarValue;
+    setProperty(path: string, value: ScalarValue): void;
+    private resolveShared;
+    /** The shared surface as examiner rows: @world (read through the
+     *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
+    listProperties(): PropertyView[];
+    /** The SHARED kernel bags with their store path prefixes (the state
+     *  logger's mount surface). The @world container is the host's own bag -
+     *  the host mounts it itself. */
+    listBags(): BagMount[];
+    /** Every flow's trace, one stream, each event tagged with its flow id. */
+    subscribeTrace(handler: EngineTraceHandler): () => void;
+    /** The whole engine, one envelope: the shared partitions once, then
+     *  every live flow keyed by its id. @world is NEVER here - the host
+     *  saves its container, each engine saves its own envelope. */
+    saveGame(): SaveEnvelope;
+    /** Restore: shared state once, then every flow REBUILT from its blob.
+     *  Handles held from before the load are closed and inert (Patter's
+     *  rule); take fresh ones from getFlow()/flows(). */
+    loadGame(envelope: SaveEnvelope): void;
+}
+declare class Flow {
+    readonly id: string;
+    private readonly engine;
+    private readonly internals;
+    private closed;
+    private prng;
+    /** Per-box turn counters, keyed by box id (schema 3.4) - per flow. */
+    private turnCounts;
+    private cooldowns;
+    /** The board: hand contents (card ids, dealt order), keyed by hand id. */
+    private boardContents;
+    private playLog;
+    private playCount;
+    private lastPlayOf;
+    private tagPlayCount;
+    private lastPlayInTag;
+    /** The per-flow property partitions (the not-shared halves). */
+    private stores;
+    private traceHandlers;
+    private logEntries;
+    private logSeq;
+    /** Merged read view per scope, built once (bags are stable for the
+     *  flow's life): the flow's own bag first, the shared bag behind it.
+     *  Names are disjoint (shared XOR per-flow by declaration), so "first"
+     *  is routing, not shadowing. */
+    private readonly storyReader;
+    private readonly boxReaders;
+    private readonly deckReaders;
+    /** @internal - built by Engine.openFlow / Engine.loadGame only. */
+    constructor(engine: Engine, internals: Internals, id: string, seed: number);
+    get isClosed(): boolean;
+    /** Close this flow: the handle goes inert, every verb throws. */
+    close(): void;
+    /** @internal */
+    markClosed(): void;
+    private assertOpen;
+    /** A box's current turn (schema 3.4), on THIS flow's clock. */
+    turn(boxRef: string): number;
+    /** Subscribe to this flow's deal/play trace (schema 5). Returns the
+     *  unsubscribe. With no subscribers anywhere the flow does no trace work. */
+    subscribeTrace(handler: TraceHandler): () => void;
+    private get tracing();
+    private emit;
+    /** The retained flow log (opt-in via the Engine's `log`), oldest first,
+     *  capped. The introspection seam for hosts and tools; the durable play
+     *  history in a save stays `playLog` (schema 4) - the log is a
+     *  flow-lifetime utility and is NOT saved. */
+    log(): readonly LogEntry[];
+    /** Empty the retained log; `seq` keeps counting, so ordering across a
+     *  clear stays meaningful. */
+    clearLog(): void;
+    private node;
+    /** Tag group names are box-scoped: two boxes may name a group the same way
+     *  (schema 1 - boxes namespace their groups), so a name is only ever
+     *  resolved inside the box being asked, never bundle-wide. Ids are
+     *  project-unique and accepted here too, still confined to the box. */
+    private groupInBox;
+    /** Fold one play into the indexes. O(the card's tags), not O(the log). */
+    private indexPlay;
+    /** Rebuild the indexes from the log. Called wherever `playLog` is REPLACED
+     *  rather than appended to, which is `restore` alone. */
+    private rebuildPlayIndex;
+    /** `box` is the box whose ask is being evaluated: the play-history
+     *  functions take a bare group name, so it resolves there (a card's tags
+     *  reference its own box's group, which keeps the counts box-local).
+     *  History is THIS flow's: countPlayed answers "have I done this". */
+    /** One host per box, built once.
+     *
+     *  The closures below read `this.playCount`, `this.turnCounts` and the rest
+     *  LIVE, so a cached host answers with current state - which is what makes
+     *  caching safe rather than a snapshot bug. Unreal did this from the start
+     *  (`hostsByBox_`, built at flow construction) and the other three rebuilt a
+     *  host, and its closures, on every `evalCtx` call: once per deck per ask,
+     *  and once per surviving card in the eviction pass. Structural divergence
+     *  in one port AND the allocation the audit flagged, so the other three
+     *  copied it (2026-08-29). Lazy rather than eager, so a bundle's unvisited
+     *  boxes cost nothing. */
+    private hostsByBox;
+    private host;
+    private makeHost;
+    /** The evaluation environment (schema 3.1/6.2): @box/@deck resolve to the
+     *  card under evaluation; in hand-condition contexts @deck is an empty bag,
+     *  so any reference is an eval error (missing-policy throw). Every scope
+     *  is the flow's MERGED view - its own copies over the shared values,
+     *  names disjoint - and @world reads through the engine's resolver. */
+    private evalCtx;
+    /** The ladder behind one composed @hand name, or undefined when the name is
+     *  not a quality (or came from criteria, which are tag NAMES, never state). */
+    private handLadder;
+    private eval;
+    private passes;
+    private tagByGameId;
+    /** A deal's ask: the hand's template bindings + chosen tags, or its rule's
+     *  bindings, plus the implicit home binding (schema 2.4). */
+    private askForHand;
+    /** A peek's ask: raw criteria ({group gameId: tag gameId}), bindings only,
+     *  no condition slot (schema 3.1; the boundary, Reboot 4). */
+    private askForPeek;
+    /**
+     * Bind every `boundBy` group in the box from the property it names.
+     *
+     * The gap this closes: only a hand could bind a group, and `deal` takes no
+     * criteria, so an axis driven by state (an act, a chapter) had nowhere to
+     * gate. Runs AFTER the hand's own bindings and never overwrites one: an
+     * explicit binding is a deliberate act and beats a default.
+     *
+     * A value naming no tag in the group leaves the group UNBOUND rather than
+     * matching nothing. Unbound is a wildcard, so the ask still deals; a silent
+     * empty hand would look like content that does not exist, and the diagnostic
+     * is what says otherwise.
+     */
+    private bindStateGroups;
+    /** A store's full value view for one owner: the shared half under the
+     *  flow's half. Names are disjoint, so the spread is routing, not
+     *  shadowing. */
+    private valuesOf;
+    private buildHandEnv;
+    /** The claims ledger, derived from THIS flow's board: card id -> holding
+     *  hands (schema 3.5). Claims are per flow - another flow holding the
+     *  card is another playthrough, not a rival hand. */
+    private claims;
+    /** @internal - every card id on THIS flow's board, one entry per holding
+     *  hand. The engine sums these across live flows for the shared ledger. */
+    heldCardIds(): string[];
+    private copiesOf;
+    /** The claims step (schema 3.1 step 6) for one card, as a verdict or null
+     *  for "available". Two caps apply to a shared card and they are different
+     *  statements, so they get different verdicts: `copies` is your own board
+     *  filling up, `sharedCopies` is somebody else already holding it, and a
+     *  participant told "claimed" about a card sitting on another person's
+     *  table would read it as an engine fault (design/shared-scarcity 9.3.1).
+     *
+     *  `mine` counts this flow's holdings, `world` every live flow's. */
+    private claimVerdict;
+    /** Tag matching (schema 3.1 step 3): for every bound group the card lists
+     *  the bound tag or omits the group (wildcard); the home group inverts -
+     *  a homed card requires a matching home binding (schema 2.4). */
+    private tagsMatch;
+    /** Run one ask: availability filter then ranking. `claimed` decides the
+     *  claims step (step 6) per card, returning the verdict that refused it or
+     *  null for available. `trace` (when a subscriber exists) collects the
+     *  per-card verdicts. */
+    private runAsk;
+    /** Flip eligible-but-not-taken trace entries to "capped". */
+    private capTrace;
+    private view;
+    private handCapacity;
+    private resolveHand;
+    /** Look at the top of the stock through raw tag criteria (schema 3.1):
+     *  claims respected, nothing registered, nothing left behind but the
+     *  trace line. You can never play a card you only peeked. */
+    peek(boxRef: string, criteria?: Record<string, string>, n?: number): RankedList;
+    /** Refresh one hand (schema 3.5); returns its new shape. */
+    deal(handRef: string): DealtCard[];
+    /** Re-deal several / all hands (schema 3.5): seeded hand-order shuffle
+     *  (fairness), evict, seed the ledger from survivors, fill in order.
+     *  Returns the dealt slice - the new contents of exactly the hands this
+     *  call dealt, keyed by hand gameId (board() stays the whole-board read). */
+    dealMany(handRefs?: string[]): Record<string, DealtCard[]>;
+    /** The board: current hand contents, in dealt order, keyed by hand gameId
+     *  (schema 5). Read it for what is out; peek the stock for what could
+     *  come.
+     *
+     *  `boxRef` (a box gameId or id) narrows the read to that box's hands, in
+     *  the same shape and the same order: "give me the barks hands" is a
+     *  common host query, and boxes are how a game separates its storylet
+     *  systems, so the grouping belongs here rather than in every host. An
+     *  unknown box throws, as it does on turn() and peek(). */
+    board(boxRef?: string): Record<string, DealtCard[]>;
+    /** Resolve a played/inspected card within a hand on the board. */
+    private resolveDealt;
+    /** Outcome availability, evaluated against CURRENT state on every ask
+     *  (schema 3.1/5) - never a deal-time snapshot. */
+    outcomes(cardId: string, from: string): OutcomeView[];
+    /** Apply an outcome (schema 3.7): the card must sit in a hand on the
+     *  board (you never play a card from inside the deck). Throws before any
+     *  mutation on a gated-shut outcome or a bad write target. */
+    play(cardId: string, outcomeGameId: string, from: string, opts?: PlayOptions): void;
+    /** Land one change in whichever partition declares the name: the flow's
+     *  bag when the property is per-flow, the shared bag when it is shared -
+     *  the union/partition invariant made executable. */
+    private landIn;
+    /** Land one change; returns the resolved store path (for the trace) and
+     *  the value it replaced (for the log's "0 -> 1" reading). */
+    private applyWrite;
+    /** Advance one box's clock (schema 3.4): a turn is one draw-from-stock
+     *  session for that box, on THIS flow's clock. */
+    advanceTurns(boxRef: string, n?: number): void;
+    /** Every box, bundle order: identity + this flow's clock (the enumeration
+     *  surface examiners key their turns sections on; parity member). */
+    listBoxes(): BoxView[];
+    /** THIS flow's kernel bags with their store path prefixes (the state
+     *  logger's mount surface; parity member). The shared bags are the
+     *  Engine's listBags; the flows are rebuilt by loadGame, so consumers
+     *  re-enumerate after a load. */
+    listBags(): BagMount[];
+    /** The flow's FULL merged view as examiner rows (the property examiner /
+     *  editor surface, parity across all runtimes): @world read through the
+     *  resolver, then per scope the shared values and this flow's own.
+     *  Bundle order: world, story, then per-box / per-deck / per-hand /
+     *  per-tag stores. */
+    listProperties(): PropertyView[];
+    /** Read by path: "world.x", "story.gold", "value.v_docks.danger",
+     *  "box.b_x.heat", "deck.k_main.n", "hand.h_board.owner" - the flow's
+     *  merged view, routed by the declaration's sharing. */
+    getProperty(path: string): ScalarValue;
+    setProperty(path: string, value: ScalarValue): void;
+    private resolvePath;
+    /** @internal - this flow's blob inside the engine's envelope. */
+    snapshot(): FlowSave;
+    /** @internal - restore a freshly opened flow from its blob (loadGame).
+     *  Orphaned keys (deleted entities) drop; new declarations keep defaults. */
+    restore(saved: FlowSave): void;
+}
+
+/** What bundle this is: the staleness/identity triple plus the schema tag. */
+interface BundleIdentity {
+    /** The bundle schema tag ("storylets/bundle@0"). */
+    schema: string;
+    /** content.project - the project name a save must agree with. */
+    project: string;
+    /** content.version - the authored bundle version. */
+    version: string;
+    /** content.hash - hash32 over the canonical source shards (schema 2.8). */
+    hash: string;
+    /** "full" | "stripped": whether authoring metadata (titles) survived. */
+    metadata: string;
+}
+/** One hand: the deal() surface. `gameId` is the name deal() is called with. */
+interface HandSummary {
+    gameId: string;
+    title?: string;
+    /** The owning box's gameId (peek's first argument for the same stock). */
+    box: string;
+    /** The effective slot cap: the hand's override, else its template's or
+     *  rule's, else "unbounded". */
+    slots: number | "unbounded";
+    /** The hand template's gameId; absent for a standalone (inline-rule) hand. */
+    template?: string;
+}
+/** One tag group and its tags, by gameId: the peek() criteria surface (a
+ *  criteria entry is `{ [group gameId]: tag gameId }`). */
+interface TagGroupSummary {
+    gameId: string;
+    tags: string[];
+}
+/** One box: identity, its ranking policy, its tag groups, and counts. */
+interface BoxSummary {
+    gameId: string;
+    title?: string;
+    /** The only per-box ranking policy (Reboot 2.2). */
+    ranking: {
+        specificity: boolean;
+    };
+    tagGroups: TagGroupSummary[];
+    counts: {
+        decks: number;
+        cards: number;
+        hands: number;
+        templates: number;
+        tagGroups: number;
+    };
+}
+/** One declared property: what expressions read and what a host may set. */
+interface PropertySummary {
+    name: string;
+    type: PropertyType;
+    default: ScalarValue$1;
+    /** Enum / flags options, where declared. */
+    values?: string[];
+    purpose?: string;
+}
+/** The scope a declaration block belongs to. `tag` declarations compose into
+ *  @hand for any ask that binds the tag (schema 3.6). */
+type PropertyScopeKind = "world" | "story" | "box" | "deck" | "hand" | "tag";
+/** One scope's declared properties. `owner` is the owning entity's gameId
+ *  (empty for world / story); `box` names its box; `group` names a tag's
+ *  group. */
+interface PropertyScopeSummary {
+    scope: PropertyScopeKind;
+    owner: string;
+    box?: string;
+    group?: string;
+    properties: PropertySummary[];
+}
+/**
+ * One map the bundle was asked to carry (design/graphical-views.md 2).
+ *
+ * Counts rather than the geometry itself, which is the same judgement the rest
+ * of this file makes: an inspector answers "what is in here", and a host that
+ * wants the polygons reads `bundle.maps` directly. Reported because a bundle
+ * that silently carried a map would fail the promise this API exists for.
+ */
+interface MapSummary {
+    /** The owning box, by gameId. */
+    box: string;
+    /** The tag group this is a map of, by gameId. */
+    group: string;
+    zones: number;
+    backgrounds: number;
+}
+/** What a bundle offers a host, read from the asset alone. */
+interface BundleDescription {
+    identity: BundleIdentity;
+    /** Orientation, not inventory: no card lists (Reboot 2.1). */
+    totals: {
+        boxes: number;
+        decks: number;
+        cards: number;
+        hands: number;
+        templates: number;
+        tagGroups: number;
+    };
+    boxes: BoxSummary[];
+    /** Every hand in the bundle, box by box: the deal() surface. */
+    hands: HandSummary[];
+    /** world, story, then per box: the box, its decks, its hands, its tags.
+     *  Scopes that declare nothing are omitted (world and story always show,
+     *  so their absence reads as "this bundle declares none"). */
+    properties: PropertyScopeSummary[];
+    /** Maps carried as inert payload, when the build asked for them. Empty is
+     *  the normal state and means the bundle has no geometry in it. */
+    maps: MapSummary[];
+}
+/** Describe a compiled bundle: the callable surface of an imported asset, no
+ *  session required (design/engine-runtimes.md 2, piece 6). Bundle order
+ *  throughout; the same shape every runtime returns. */
+declare function describeBundle(bundle: Bundle): BundleDescription;
+
+export { type BagMount, type BoxSummary, type BoxView, type BundleDescription, type BundleIdentity, type DealtCard, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, Flow, type HandSummary, type LogEntry, type MapSummary, type OpenFlowOptions, type OutcomeView, type PlayOptions, type PropertyScopeKind, type PropertyScopeSummary, type PropertySummary, type PropertyView, type RankedList, type TagGroupSummary, type TraceEvent, type TraceHandler, type TraceVerdict, describeBundle };