pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/dist/sandbox/attribution/element-selector.js

@@ -0,0 +1,109 @@
+/**
+ * Turning a DOM element into a string that names it again later.
+ *
+ * Two callers want slightly different things, so this file offers two
+ * entry points over one identity ladder:
+ *
+ * - {@link ownerSelectorFor} is for an element the caller handed to pyric as
+ *   a listener's owner. The caller asked to be identified, so an element with
+ *   no identity of its own is GIVEN one: a generated `data-pyric-owner`
+ *   attribute that survives re-render and makes the selector stable.
+ * - {@link regionSelectorFor} is for an element pyric observed a callback
+ *   mutating. Observation must not change the page, so an element with no
+ *   identity of its own gets a structural path instead of a new attribute.
+ *
+ * Both prefer, in order: the element's `id`, then an existing
+ * `data-pyric-owner`, then their respective fallback.
+ */
+/** The attribute pyric reads, and mints, to name an owning element. */
+export const OWNER_ATTRIBUTE = 'data-pyric-owner';
+let mintedOwnerCount = 0;
+/** `true` when `value` responds to the element methods this file calls. */
+export function isSelectableElement(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    if (typeof candidate.getAttribute !== 'function')
+        return false;
+    return typeof candidate.tagName === 'string';
+}
+/** The element's lower-case tag name, or `'element'` when it reports none. */
+export function tagNameOf(element) {
+    const tag = element.tagName;
+    if (typeof tag !== 'string' || tag.length === 0)
+        return 'element';
+    return tag.toLowerCase();
+}
+/**
+ * A selector the element already earns on its own: its `id`, or a
+ * `data-pyric-owner` someone already set. `undefined` when it has neither.
+ */
+function existingIdentitySelector(element) {
+    const id = element.id;
+    if (typeof id === 'string' && id.length > 0)
+        return `#${id}`;
+    const owner = element.getAttribute(OWNER_ATTRIBUTE);
+    if (typeof owner === 'string' && owner.length > 0) {
+        return `[${OWNER_ATTRIBUTE}="${owner}"]`;
+    }
+    return undefined;
+}
+/** Position of `element` among its parent's children, 1-based. */
+function childIndexOf(element) {
+    const parent = element.parentElement;
+    if (!parent)
+        return 1;
+    const siblings = parent.children;
+    if (!siblings)
+        return 1;
+    for (let index = 0; index < siblings.length; index += 1) {
+        if (siblings[index] === element)
+            return index + 1;
+    }
+    return 1;
+}
+/**
+ * A structural path from the nearest identified ancestor down to `element`,
+ * such as `#board > div:nth-child(2) > li:nth-child(3)`. Walks at most eight
+ * levels so a deep tree produces a bounded string rather than the whole
+ * document path.
+ */
+function structuralPathFor(element) {
+    const steps = [];
+    let current = element;
+    let depth = 0;
+    while (current && depth < 8) {
+        const identity = existingIdentitySelector(current);
+        if (identity !== undefined) {
+            steps.unshift(identity);
+            return steps.join(' > ');
+        }
+        steps.unshift(`${tagNameOf(current)}:nth-child(${childIndexOf(current)})`);
+        current = current.parentElement;
+        depth += 1;
+    }
+    return steps.join(' > ');
+}
+/**
+ * Name an element the caller nominated as a listener's owner, minting a
+ * `data-pyric-owner` attribute when it has no identity of its own.
+ */
+export function ownerSelectorFor(element) {
+    const existing = existingIdentitySelector(element);
+    if (existing !== undefined)
+        return existing;
+    mintedOwnerCount += 1;
+    const minted = `${tagNameOf(element)}-${mintedOwnerCount.toString(36)}`;
+    element.setAttribute(OWNER_ATTRIBUTE, minted);
+    return `[${OWNER_ATTRIBUTE}="${minted}"]`;
+}
+/**
+ * Name an element a callback mutated, without writing to the document.
+ */
+export function regionSelectorFor(element) {
+    const existing = existingIdentitySelector(element);
+    if (existing !== undefined)
+        return existing;
+    return structuralPathFor(element);
+}
+//# sourceMappingURL=element-selector.js.map

package/dist/sandbox/attribution/element-selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-selector.js","sourceRoot":"","sources":["../../../src/sandbox/attribution/element-selector.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/attribution/listener-owners.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Deriving a listener's owners at the moment it attaches.
+ *
+ * Two owners can be known at attach time and no later:
+ *
+ * - the creation `frame`, read from a stack captured on the attaching call
+ *   stack. Once the listener is registered the caller's stack is gone, so
+ *   this has to happen here, and it costs exactly one `Error` construction
+ *   per attach, never one per delivery.
+ * - the caller's `tag`, taken from the `owner` listen option. That option is
+ *   pyric's own extension to `SnapshotListenOptions` and `ListenOptions`; the
+ *   Firebase SDKs have no such field and ignore it.
+ *
+ * The third owner kind, `regions`, is a property of a delivery rather than of
+ * an attach, and lives in `effect-regions.ts`.
+ */
+import type { ListenerOwner } from '../types/events.js';
+import { type SelectableElement } from './element-selector.js';
+/**
+ * The input form of a `component` owner, as a framework binding builds it.
+ *
+ * It differs from the recorded {@link ListenerOwner} `component` form in one
+ * field: `element` is the live DOM element, not a selector for it. The
+ * binding hands the element over and this module derives the selector,
+ * exactly as it does for an element hint, so that the selector rules live in
+ * one place and the binding never has to import pyric at runtime. Owners are
+ * serialized into events, so the element itself is never kept on the
+ * recorded owner.
+ */
+export interface ComponentOwnerInput {
+    kind: 'component';
+    /** The component function's name, read from the render-phase stack. */
+    name: string;
+    /** The chain of enclosing component frames, outermost first. */
+    path?: string[];
+    /** The component's root element, when the binding's ref was attached. */
+    element?: SelectableElement;
+}
+/**
+ * What a caller may pass as a listener's `owner`: a name, the DOM element the
+ * listener feeds, a fully-built {@link ListenerOwner} record, or a
+ * {@link ComponentOwnerInput}. The last two forms are for a framework binding
+ * (`@pyric/ui`'s `useListenerOwner`) that has already identified the owning
+ * component and wants it recorded as a `component` owner rather than wrapped
+ * in a `tag`.
+ */
+export type ListenerOwnerHint = string | SelectableElement | ListenerOwner | ComponentOwnerInput;
+/**
+ * Parse one V8 stack line into a `frame` owner. Both formats the runtime
+ * emits are handled: `at fn (/path/file.ts:12:5)` and `at /path/file.ts:12:5`.
+ * Anything else (a header line, a `native` frame, a runtime with a different
+ * stack format) returns `undefined` and is skipped.
+ */
+export declare function parseStackFrame(line: string): ListenerOwner | undefined;
+/**
+ * The first frame outside pyric's own files, read from `stack`. Exported for
+ * the test, which supplies a synthetic stack rather than a real one.
+ */
+export declare function callerFrameFromStack(stack: string): ListenerOwner | undefined;
+/**
+ * Capture the frame that created a listener. `undefined` when attribution is
+ * off, when the runtime produced no stack, or when every frame on it belongs
+ * to pyric.
+ */
+export declare function captureCreationFrame(): ListenerOwner | undefined;
+/**
+ * Build the explicit owner from whatever the caller passed as `owner`. A
+ * string is the name of a `tag` owner verbatim; an element contributes its
+ * tag name plus a selector that finds it again; an owner record (a framework
+ * binding's `component` owner) is recorded as it stands, except that a live
+ * element on a `component` owner is reduced to a selector here. Unlike frame
+ * capture this is not gated on the attribution switch: the caller asked for
+ * it by name.
+ */
+export declare function tagOwnerFor(hint: ListenerOwnerHint | undefined): ListenerOwner | undefined;
+/**
+ * The internal listen option that carries owners a caller already recorded.
+ *
+ * It exists for one caller: a client that reaches the sandbox across a port
+ * rather than calling it in the same context. The served page runs the
+ * sandbox in a SharedWorker, so an attach inside the worker sees a
+ * worker-bundle frame, no `owner` hint, and no DOM. That client derives the
+ * owners on the page, where all three are real, and hands them over here.
+ *
+ * The option is reached through `pyric/sandbox/internal` and is not part of
+ * any mirrored Firebase surface. The public `owner` hint is unchanged: a
+ * caller still passes a name, an element, or a component record, and the
+ * sandbox still derives the owners itself when no `owners` arrive.
+ */
+export interface RecordedListenerOwners {
+    readonly owners?: readonly ListenerOwner[];
+}
+/**
+ * Both attribution inputs a listen call can carry: the caller's `owner` hint
+ * and, for a caller on the other side of a port, the owners it already
+ * recorded. Backends that take attribution as one argument take this.
+ */
+export interface ListenerAttribution extends RecordedListenerOwners {
+    readonly owner?: ListenerOwnerHint;
+}
+/**
+ * Every owner known at attach time, in a stable order: frame first, then tag.
+ * Returns `undefined` rather than an empty array so an event with no
+ * attribution omits the field entirely.
+ *
+ * `recorded` owners replace both: the caller derived them where the calling
+ * frame and the DOM exist, so deriving them again here would only describe
+ * this context.
+ */
+export declare function listenerAttachOwners(hint?: ListenerOwnerHint, recorded?: readonly ListenerOwner[]): ListenerOwner[] | undefined;
+//# sourceMappingURL=listener-owners.d.ts.map

package/dist/sandbox/attribution/listener-owners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-owners.d.ts","sourceRoot":"","sources":["../../../src/sandbox/attribution/listener-owners.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,yEAAyE;IACzE,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,iBAAiB,GACjB,aAAa,GACb,mBAAmB,CAAC;AA2FxB;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAuBvE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAS7E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,aAAa,GAAG,SAAS,CAKhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAS1F;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,CAAC,EAAE,iBAAiB,EACxB,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,GAClC,aAAa,EAAE,GAAG,SAAS,CAS7B"}

package/dist/sandbox/attribution/listener-owners.js

@@ -0,0 +1,215 @@
+/**
+ * Deriving a listener's owners at the moment it attaches.
+ *
+ * Two owners can be known at attach time and no later:
+ *
+ * - the creation `frame`, read from a stack captured on the attaching call
+ *   stack. Once the listener is registered the caller's stack is gone, so
+ *   this has to happen here, and it costs exactly one `Error` construction
+ *   per attach, never one per delivery.
+ * - the caller's `tag`, taken from the `owner` listen option. That option is
+ *   pyric's own extension to `SnapshotListenOptions` and `ListenOptions`; the
+ *   Firebase SDKs have no such field and ignore it.
+ *
+ * The third owner kind, `regions`, is a property of a delivery rather than of
+ * an attach, and lives in `effect-regions.ts`.
+ */
+import { listenerAttributionEnabled } from './attribution-mode.js';
+import { isSelectableElement, ownerSelectorFor, tagNameOf, } from './element-selector.js';
+/** `true` when `value` is already an owner record rather than a name or an
+ *  element to derive one from. */
+function isOwnerRecord(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    return 'kind' in value && typeof value.kind === 'string';
+}
+/**
+ * Turn an owner record into its recorded form. A `component` owner carrying a
+ * live element has that element replaced by a selector; a `component` owner
+ * whose `element` is not a selectable element drops the field. Every other
+ * owner kind is already in recorded form and passes through unchanged.
+ */
+function recordedOwner(value) {
+    if (value.kind !== 'component')
+        return value;
+    const owner = {
+        kind: 'component',
+        name: value.name,
+    };
+    if (value.path !== undefined && value.path.length > 0)
+        owner.path = value.path;
+    const element = value.element;
+    if (typeof element === 'string') {
+        owner.element = element;
+    }
+    else if (element !== undefined && isSelectableElement(element)) {
+        owner.element = ownerSelectorFor(element);
+        owner.tag = tagNameOf(element);
+    }
+    return owner;
+}
+/**
+ * Pyric's own root directory, derived from this module's own location.
+ *
+ * A frame is "pyric's own" when its path starts here. Deriving the root from
+ * `import.meta.url` rather than hardcoding `packages/pyric` makes the test
+ * work for both trees the mirror ships from: under source this resolves to
+ * `.../packages/pyric/src`, and under a build to `.../pyric/dist`. Either way
+ * it is the directory that contains every pyric file that could appear on the
+ * stack between the caller and the attach.
+ */
+const PYRIC_ROOT = pyricRoot();
+function pyricRoot() {
+    // This file sits at `<root>/sandbox/attribution/listener-owners.{ts,js}`,
+    // so the root is three path segments up. A bundler that inlines this module
+    // into one artifact leaves `import.meta.url` undefined; there is then no
+    // pyric directory to recognize, and frame filtering falls back to the
+    // `node_modules` test alone.
+    const here = importMetaUrl();
+    if (here === undefined)
+        return '';
+    const withoutFile = here.slice(0, here.lastIndexOf('/'));
+    const withoutAttribution = withoutFile.slice(0, withoutFile.lastIndexOf('/'));
+    const withoutSandbox = withoutAttribution.slice(0, withoutAttribution.lastIndexOf('/'));
+    return stripFileScheme(withoutSandbox);
+}
+/** This module's own URL, or `undefined` inside a bundle that erased it. */
+function importMetaUrl() {
+    try {
+        const url = import.meta.url;
+        if (typeof url !== 'string')
+            return undefined;
+        return url;
+    }
+    catch {
+        return undefined;
+    }
+}
+function stripFileScheme(url) {
+    if (url.startsWith('file://'))
+        return url.slice('file://'.length);
+    return url;
+}
+/** A frame inside pyric itself, or inside an installed dependency. */
+function isInternalFrame(file) {
+    if (file.includes('/node_modules/'))
+        return true;
+    if (PYRIC_ROOT.length > 0 && file.startsWith(`${PYRIC_ROOT}/`))
+        return true;
+    // Source and built SDK copies share the page journal. Its registration frame
+    // can therefore come from the sibling tree during workspace development.
+    const sibling = PYRIC_ROOT.endsWith('/src') ? `${PYRIC_ROOT.slice(0, -4)}/dist`
+        : PYRIC_ROOT.endsWith('/dist') ? `${PYRIC_ROOT.slice(0, -5)}/src` : '';
+    if (sibling && file.startsWith(`${sibling}/`))
+        return true;
+    return false;
+}
+const FRAME_WITH_FUNCTION = /^\s*at\s+(.+?)\s+\((.+):(\d+):(\d+)\)\s*$/;
+const FRAME_WITHOUT_FUNCTION = /^\s*at\s+(.+):(\d+):(\d+)\s*$/;
+/**
+ * Parse one V8 stack line into a `frame` owner. Both formats the runtime
+ * emits are handled: `at fn (/path/file.ts:12:5)` and `at /path/file.ts:12:5`.
+ * Anything else (a header line, a `native` frame, a runtime with a different
+ * stack format) returns `undefined` and is skipped.
+ */
+export function parseStackFrame(line) {
+    const named = FRAME_WITH_FUNCTION.exec(line);
+    if (named) {
+        const owner = {
+            kind: 'frame',
+            file: stripFileScheme(named[2]),
+            line: Number(named[3]),
+            column: Number(named[4]),
+            function: named[1],
+        };
+        return owner;
+    }
+    const bare = FRAME_WITHOUT_FUNCTION.exec(line);
+    if (bare) {
+        const owner = {
+            kind: 'frame',
+            file: stripFileScheme(bare[1]),
+            line: Number(bare[2]),
+            column: Number(bare[3]),
+        };
+        return owner;
+    }
+    return undefined;
+}
+/**
+ * The first frame outside pyric's own files, read from `stack`. Exported for
+ * the test, which supplies a synthetic stack rather than a real one.
+ */
+export function callerFrameFromStack(stack) {
+    for (const line of stack.split('\n')) {
+        const frame = parseStackFrame(line);
+        if (frame === undefined)
+            continue;
+        if (frame.kind !== 'frame')
+            continue;
+        if (isInternalFrame(frame.file))
+            continue;
+        return frame;
+    }
+    return undefined;
+}
+/**
+ * Capture the frame that created a listener. `undefined` when attribution is
+ * off, when the runtime produced no stack, or when every frame on it belongs
+ * to pyric.
+ */
+export function captureCreationFrame() {
+    if (!listenerAttributionEnabled())
+        return undefined;
+    const stack = new Error().stack;
+    if (typeof stack !== 'string')
+        return undefined;
+    return callerFrameFromStack(stack);
+}
+/**
+ * Build the explicit owner from whatever the caller passed as `owner`. A
+ * string is the name of a `tag` owner verbatim; an element contributes its
+ * tag name plus a selector that finds it again; an owner record (a framework
+ * binding's `component` owner) is recorded as it stands, except that a live
+ * element on a `component` owner is reduced to a selector here. Unlike frame
+ * capture this is not gated on the attribution switch: the caller asked for
+ * it by name.
+ */
+export function tagOwnerFor(hint) {
+    if (hint === undefined)
+        return undefined;
+    if (typeof hint === 'string') {
+        if (hint.length === 0)
+            return undefined;
+        return { kind: 'tag', name: hint };
+    }
+    if (isOwnerRecord(hint))
+        return recordedOwner(hint);
+    if (!isSelectableElement(hint))
+        return undefined;
+    return { kind: 'tag', name: tagNameOf(hint), element: ownerSelectorFor(hint) };
+}
+/**
+ * Every owner known at attach time, in a stable order: frame first, then tag.
+ * Returns `undefined` rather than an empty array so an event with no
+ * attribution omits the field entirely.
+ *
+ * `recorded` owners replace both: the caller derived them where the calling
+ * frame and the DOM exist, so deriving them again here would only describe
+ * this context.
+ */
+export function listenerAttachOwners(hint, recorded) {
+    if (recorded !== undefined && recorded.length > 0)
+        return [...recorded];
+    const owners = [];
+    const frame = captureCreationFrame();
+    if (frame !== undefined)
+        owners.push(frame);
+    const tag = tagOwnerFor(hint);
+    if (tag !== undefined)
+        owners.push(tag);
+    if (owners.length === 0)
+        return undefined;
+    return owners;
+}
+//# sourceMappingURL=listener-owners.js.map

package/dist/sandbox/attribution/listener-owners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-owners.js","sourceRoot":"","sources":["../../../src/sandbox/attribution/listener-owners.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/branches/engine.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Branches: fork, apply, diff, promote, discard.
+ *
+ * A branch is an isolated sandbox seeded from a {@link FullSandboxState}, plus
+ * the events applied to it since the fork. The mental model:
+ *
+ *   const branch = await fork(await captureFullState(live), candidateRules);
+ *   apply(branch, agentPlanEvents);
+ *   const changes = await diff(branch, live);
+ *   await promote(branch, live);
+ *   // ...or...
+ *   discard(branch);
+ *
+ * What a branch carries. Everything the sandbox holds: Firestore documents,
+ * the Realtime Database tree, Storage objects with their bytes and metadata,
+ * auth accounts, and the three rule sources. A branch that silently held only
+ * Firestore would report a clean diff over state it never looked at, so the
+ * fork seeds from a full state and the promotion lands one.
+ *
+ * Why these are asynchronous. Storage objects live behind an asynchronous
+ * backend, so any operation that reads or writes the whole sandbox is
+ * asynchronous too. `apply` and `discard` touch neither, so they stay
+ * synchronous.
+ *
+ * Diff honesty. Every difference is a `real-divergence`. A branch carries no
+ * captured write metadata that could license sentinel or auto-id drift, so
+ * that is the correct classification for state against state. Each record also
+ * names its service and the path or uid it concerns.
+ *
+ * Promotion honesty. A promotion writes the delta between the state the branch
+ * forked from and the state it holds now, so state on the target that the
+ * branch never touched survives. It is atomic from the caller's point of view:
+ * the target's full state is captured first, and any throw restores that
+ * capture, rethrows the original error, and leaves the branch undiscarded.
+ */
+import { type DatabaseRuleset, type FullSandboxState } from '../full-state.js';
+import type { SandboxEvent } from '../types/events.js';
+import type { LocalSandbox } from '../types/service.js';
+import { type BranchDivergence } from './state-diff.js';
+/**
+ * Rule sources a fork installs on the branch in place of the ones the state
+ * carries. Each is independent: naming one replaces that service's rules and
+ * leaves the other two as the forked state had them.
+ */
+export interface BranchCandidateRules {
+    /** Firestore Security Rules source to run the branch under. */
+    firestore?: string;
+    /** Realtime Database ruleset to run the branch under. */
+    database?: DatabaseRuleset;
+    /** Storage Security Rules source to run the branch under. */
+    storage?: string;
+}
+/**
+ * An isolated experiment seeded from a {@link FullSandboxState}.
+ *
+ * A branch owns its own {@link LocalSandbox}, fully isolated from the source:
+ * separate environment, separate event history, separate service backends.
+ */
+export interface Branch {
+    /** The branch's own sandbox. Read it directly, or through `captureFullState`. */
+    readonly sandbox: LocalSandbox;
+    /** The candidate rules the fork installed, so a store can rebuild the branch. */
+    readonly candidateRules: BranchCandidateRules;
+    /** The full state this branch was forked from. The baseline a promotion is a delta against. */
+    readonly base: FullSandboxState;
+    /** Events applied since the fork, in order. */
+    readonly events: SandboxEvent[];
+    /** Set by {@link discard} and by a completed {@link promote}. */
+    discarded: boolean;
+}
+/** What a branch can be compared against: a live sandbox, or a captured state. */
+export type DiffTarget = LocalSandbox | FullSandboxState;
+/**
+ * Fork a new branch from a captured full state.
+ *
+ * The branch's sandbox reads identically to the state it was forked from in
+ * every service, and writes on it never reach the source.
+ *
+ * @param base      The baseline, typically `await captureFullState(live)`.
+ * @param candidate Rule sources to run the branch under in place of the
+ *                  baseline's. A string is read as a Realtime Database ruleset
+ *                  when it parses as JSON with a `rules` key, and as Firestore
+ *                  rules otherwise. An object names each service explicitly.
+ */
+export declare function fork(base: FullSandboxState, candidate?: string | BranchCandidateRules): Promise<Branch>;
+/**
+ * Apply a stream of events to a branch by re-issuing their writes against the
+ * branch's current state.
+ *
+ * This is the per-write re-issue logic `replay()` runs (filter to writes,
+ * honour `autoId` and the pinned `requestTime`, prefer the pre-resolution
+ * `request.resourceData` so sentinels re-resolve), applied incrementally on
+ * the branch's existing environment rather than on a fresh empty sandbox. The
+ * applied events are folded into `branch.events` so a store can rebuild the
+ * branch from its base and its log.
+ *
+ * @returns the same branch, mutated in place, for chaining.
+ */
+export declare function apply(branch: Branch, events: readonly SandboxEvent[]): Branch;
+/**
+ * Every difference between a branch's current state and a reference, across
+ * every service. Each record names its service and the path or uid it
+ * concerns, with the reference's value as `before` and the branch's as
+ * `after`.
+ *
+ * @param branch The experiment.
+ * @param target A live sandbox, or a state captured from one.
+ */
+export declare function diff(branch: Branch, target: DiffTarget): Promise<BranchDivergence[]>;
+/**
+ * Land a branch's changes on a target, across every service.
+ *
+ * Atomic from the caller's point of view: the target's full state is captured
+ * before the first write, and any throw restores that capture, rethrows the
+ * original error, and leaves the branch undiscarded so the caller can inspect
+ * or retry it. On success the branch is spent and its sandbox is disposed.
+ *
+ * When the restore itself throws the target is not atomic any more, and the
+ * error says so: it carries the promotion's message first and the restore's
+ * after it, because a caller reading it needs to know both what failed and
+ * that the target still holds part of the change.
+ */
+export declare function promote(branch: Branch, target: LocalSandbox): Promise<void>;
+/**
+ * Discard a branch: drop its sandbox and mark it spent. The target is never
+ * touched, because nothing was promoted. Idempotent.
+ */
+export declare function discard(branch: Branch): void;
+//# sourceMappingURL=engine.d.ts.map

package/dist/sandbox/branches/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/sandbox/branches/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,cAAc,EAAE,oBAAoB,CAAC;IAC9C,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC;IAChC,iEAAiE;IACjE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAoEzD;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CACxB,IAAI,EAAE,gBAAgB,EACtB,SAAS,CAAC,EAAE,MAAM,GAAG,oBAAoB,GACxC,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAyB7E;AA6CD;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAK1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAWjF;AAiCD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAI5C"}