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

package/dist/sandbox/branches/engine.js

@@ -0,0 +1,280 @@
+/**
+ * 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 { getOrCreateBackend } from '../../database/sandbox/backend-for.js';
+import { stripJsonComments } from '../../database/sandbox-controls.js';
+import { getAdminStorageSandbox, replaceStorageRules } from '../../storage/internal.js';
+import { Timestamp } from 'pyric/rules/internal';
+import { applyFullState, captureFullState, } from '../full-state.js';
+import { initializeSandbox } from '../index.js';
+import { getInternalEnv } from '../internal/sandbox-impl.js';
+import { promoteFullState } from './promotion.js';
+import { diffFullStates } from './state-diff.js';
+let nextBranchStorage = 1;
+/**
+ * Open the branch's Storage service on a database of its own.
+ *
+ * Storage durability is keyed by database name, not by sandbox, so two
+ * sandboxes that open the default database share one bucket. A branch that
+ * shared its bucket with the sandbox it forked from would leak every object it
+ * uploaded straight onto live, so the fork pins a name no other sandbox uses
+ * before anything reaches Storage. Every later reach resolves the service this
+ * call opened, because the service is cached per sandbox.
+ */
+function isolateBranchStorage(sandbox) {
+    const suffix = `${nextBranchStorage++}-${Math.random().toString(36).slice(2, 10)}`;
+    getAdminStorageSandbox(sandbox, { dbName: `pyric-branch-storage:${suffix}` });
+}
+/** A candidate rules argument in its normalized form. */
+function normalizeCandidateRules(candidate) {
+    if (candidate === undefined)
+        return {};
+    if (typeof candidate !== 'string')
+        return candidate;
+    if (candidate === '')
+        return {};
+    const asDatabaseRuleset = parseDatabaseRuleset(candidate);
+    if (asDatabaseRuleset !== null)
+        return { database: asDatabaseRuleset };
+    return { firestore: candidate };
+}
+/**
+ * One rules string read as a Realtime Database ruleset, or null when it is not
+ * one. A Realtime Database ruleset is JSON with a `rules` key, which no
+ * Firestore or Storage rules source can be, so the two are told apart by
+ * parsing rather than by asking the caller which they meant.
+ */
+function parseDatabaseRuleset(source) {
+    if (!source.trim().startsWith('{'))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(stripJsonComments(source));
+    }
+    catch {
+        return null;
+    }
+    const isObject = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);
+    if (!isObject)
+        return null;
+    const candidate = parsed;
+    if (!('rules' in candidate))
+        return null;
+    return candidate;
+}
+/** Install whichever candidate rule sources the fork was given. */
+async function installCandidateRules(sandbox, candidate) {
+    if (candidate.firestore !== undefined) {
+        getInternalEnv(sandbox).deployRules(candidate.firestore);
+    }
+    if (candidate.database !== undefined) {
+        getOrCreateBackend(sandbox).setRules(structuredClone(candidate.database));
+    }
+    if (candidate.storage !== undefined) {
+        await replaceStorageRules(sandbox, candidate.storage);
+    }
+}
+/**
+ * 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 async function fork(base, candidate) {
+    const candidateRules = normalizeCandidateRules(candidate);
+    const sandbox = initializeSandbox();
+    isolateBranchStorage(sandbox);
+    await applyFullState(sandbox, base);
+    await installCandidateRules(sandbox, candidateRules);
+    return { sandbox, candidateRules, base, events: [], discarded: false };
+}
+/**
+ * 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 function apply(branch, events) {
+    assertLive(branch);
+    const env = getInternalEnv(branch.sandbox);
+    const writes = events.filter((event) => event.kind === 'write');
+    for (const write of writes) {
+        const data = preResolutionDataFor(write, events) ?? write.data;
+        const requestTime = new Timestamp(write.requestTime.seconds, write.requestTime.nanoseconds);
+        if (write.autoId) {
+            const collection = write.path.slice(0, write.path.lastIndexOf('/'));
+            env.createWithAutoId(collection, (data ?? {}), write.auth);
+            continue;
+        }
+        try {
+            env.execute(executionFor(write, data, requestTime));
+        }
+        catch {
+            // A denied or failed re-issue surfaces later as state divergence in
+            // diff(), so one bad write does not abort the rest of the stream.
+        }
+    }
+    branch.events.push(...events);
+    return branch;
+}
+/** One re-issued write, assembled before it crosses the environment boundary. */
+function executionFor(write, data, requestTime) {
+    const execution = { method: write.method, path: write.path, auth: write.auth, requestTime };
+    if (data !== undefined)
+        execution.data = data;
+    return execution;
+}
+/**
+ * The pre-resolution payload for a write: the `request` event at or before it
+ * on the same path carries `request.resourceData` with sentinels intact.
+ * Mirrors the replay engine's own lookup.
+ */
+function preResolutionDataFor(write, allEvents) {
+    const writeIndex = allEvents.indexOf(write);
+    if (writeIndex < 0)
+        return undefined;
+    for (let index = writeIndex; index >= 0; index--) {
+        const event = allEvents[index];
+        if (!event || event.kind !== 'request')
+            continue;
+        if (event.path !== write.path)
+            continue;
+        return event.request?.resourceData;
+    }
+    return undefined;
+}
+/**
+ * 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 async function diff(branch, target) {
+    assertLive(branch);
+    const reference = await fullStateOf(target);
+    const current = await captureFullState(branch.sandbox);
+    return diffFullStates(reference, current);
+}
+/**
+ * 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 async function promote(branch, target) {
+    assertLive(branch);
+    const rollback = await captureFullState(target);
+    const current = await captureFullState(branch.sandbox);
+    try {
+        await promoteFullState(target, branch.base, current);
+    }
+    catch (error) {
+        await rollBackTo(target, rollback, error);
+    }
+    branch.discarded = true;
+    branch.sandbox.dispose();
+}
+/**
+ * Put the target back to the state the promotion started from, then rethrow.
+ *
+ * A restore that throws leaves the target part way through a partial
+ * promotion, which is the worst state to be told nothing about. The error
+ * raised carries both messages, the write that failed first, because that is
+ * the one that says what the caller was trying to do; the restore's message
+ * says how much of it is still there.
+ */
+async function rollBackTo(target, rollback, cause) {
+    try {
+        await applyFullState(target, rollback);
+    }
+    catch (restoreError) {
+        throw new Error(`Promotion failed and the target could not be restored. The promotion failed with: ${messageOf(cause)}. The restore then failed with: ${messageOf(restoreError)}. The target holds a partly promoted state.`, { cause });
+    }
+    throw cause;
+}
+/** One thrown value as a sentence, whether or not it was an Error. */
+function messageOf(thrown) {
+    if (thrown instanceof Error)
+        return thrown.message;
+    return String(thrown);
+}
+/**
+ * Discard a branch: drop its sandbox and mark it spent. The target is never
+ * touched, because nothing was promoted. Idempotent.
+ */
+export function discard(branch) {
+    if (branch.discarded)
+        return;
+    branch.discarded = true;
+    branch.sandbox.dispose();
+}
+function assertLive(branch) {
+    if (branch.discarded) {
+        throw new Error('Branch has been discarded or promoted; create a new fork.');
+    }
+}
+/** The full state behind a diff target, captured when the target is a sandbox. */
+async function fullStateOf(target) {
+    if (isSandbox(target))
+        return captureFullState(target);
+    return target;
+}
+function isSandbox(target) {
+    return typeof target.snapshot === 'function';
+}
+//# sourceMappingURL=engine.js.map

package/dist/sandbox/branches/engine.js.map

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

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

@@ -1,141 +1,14 @@
 /**
- * Branches — a fork / apply / diff / promote / discard primitive built
- * **on top of** the existing `snapshot()` + `replay()` surface. Nothing
- * here re-implements those; a branch is an in-memory sandbox seeded from
- * a {@link SandboxSnapshot}, with `apply` delegating to `replay()` and
- * `diff` reusing the replay engine's structural divergence classifier.
- *
- * Mental model (the Pyric Studio "experiment" primitive — see
- * the design rationale):
- *
- *   const branch = fork(live.snapshot(), rules);   // isolated copy
- *   apply(branch, agentPlanEvents);                // re-issue writes
- *   const changes = diff(branch, live);            // what changed vs live
- *   promote(branch, live);   // land the branch's mutations on live
- *   // ...or...
- *   discard(branch);         // drop it; live is untouched
- *
- * This is the substrate for Studio's agent dry-run → accept/reject
- * (A1), rules-failure "re-run against an edited ruleset" (F4), and
- * time-travel (A2). Each of those wants: an isolated copy of current
- * state, a way to play hypothetical writes against it, a structural
- * diff, and a commit/rollback gate.
- *
- * Granularity / honesty notes:
- *   - `fork` rehydrates **Firestore** state from the snapshot (the
- *     `firestore` key) plus rules. Per-service state in
- *     `snapshot.services` (auth users, etc.) is NOT rehydrated here —
- *     a fresh fork has no registered persistable services to restore
- *     into, mirroring how persistence skips unregistered services. If a
- *     consumer needs auth-in-a-branch it can register services on the
- *     branch sandbox and restore them; that's out of scope for v1.
- *   - `diff` reuses the replay engine's doc-level + field-level walk
- *     (`Divergence`). Without captured write metadata it can't license
- *     sentinel/auto-id drift, so every field difference surfaces as
- *     `real-divergence` — which is the correct, honest classification
- *     for "branch state vs live state" (there are no replayed sentinels
- *     to reconcile). Doc add/remove surface as presence divergences.
- *   - `promote` re-issues the branch's accumulated write events onto the
- *     target via `replay`'s machinery, then copies the resulting docs
- *     onto the target through the admin plane. It applies *mutations*
- *     (added/changed/removed docs), not a blind whole-snapshot replace —
- *     docs the branch never touched are left alone on the target.
- */
-import { type Divergence, type LocalSandbox, type SandboxEvent, type SandboxSnapshot } from '../index.js';
-/**
- * An isolated, in-memory experiment seeded from a {@link SandboxSnapshot}.
- *
- * A branch owns its own {@link LocalSandbox} (fully isolated from the source —
- * separate `LocalEnvironment`, separate event history) plus the
- * accumulated {@link SandboxEvent}s applied to it via {@link apply}. The
- * applied events are what {@link promote} replays onto the target.
- */
-export interface Branch {
-    /** The branch's own sandbox. Inspect it directly (`branch.sandbox.snapshot()`)
-     *  or read docs via `branch.sandbox.admin.getDocument(path)`. */
-    readonly sandbox: LocalSandbox;
-    /** Rules the branch was forked with — carried so {@link promote} can
-     *  re-seed a replay target identically. */
-    readonly rules: string;
-    /** The snapshot this branch was forked from. Retained so {@link diff}
-     *  and {@link promote} can reason about the baseline. */
-    readonly base: SandboxSnapshot;
-    /** Write/op events applied to this branch since fork, in order. These
-     *  are replayed onto the target by {@link promote}. */
-    readonly events: SandboxEvent[];
-    /** Flipped by {@link discard}; subsequent {@link apply}/{@link promote}
-     *  calls throw. */
-    discarded: boolean;
-}
-/** A reference to diff a branch against: a live sandbox or a bare snapshot. */
-export type DiffTarget = LocalSandbox | SandboxSnapshot;
-/**
- * Fork a new branch from a snapshot.
- *
- * Seeds a fresh sandbox with `rules` and the snapshot's Firestore docs
- * (the same `seed({ rules, documents })` path replay uses to stand up a
- * clean environment). The branch is fully isolated: writes on it never
- * touch the source sandbox.
- *
- * @param snapshot Baseline state — typically `liveSandbox.snapshot()`.
- * @param rules    Rules source for the branch. Pass the live rules to
- *                 reproduce production behaviour, or an *edited* ruleset
- *                 to test a rules change in isolation (Studio F4).
- */
-export declare function fork(snapshot: SandboxSnapshot, rules?: string): Branch;
-/**
- * Apply a stream of events to a branch by re-issuing their writes against
- * the branch's CURRENT state.
- *
- * This is the same per-write re-issue logic `replay()` runs (filter to
- * `kind: 'write'`, honour `autoId` / pinned `requestTime`, prefer the
- * pre-resolution `request.resourceData` so sentinels re-resolve), but
- * applied *incrementally* on the branch's existing env rather than on a
- * fresh empty sandbox — so it composes over base docs (e.g. an `update`
- * lands on a doc the snapshot seeded) and accumulates across multiple
- * `apply` calls. The applied events are folded into `branch.events` so
- * {@link promote} can reproduce the same sequence on the target.
- *
- * @returns the same branch (mutated in place) for chaining.
- */
-export declare function apply(branch: Branch, events: readonly SandboxEvent[]): Branch;
-/**
- * Structural diff of a branch's current state against a reference.
- *
- * Reuses the replay engine's `Divergence` result type and mirrors its
- * doc-level + field-level walk (see {@link diffDocSets}). With no captured
- * write metadata in play, differences surface as `real-divergence`
- * (field/doc changed) — the honest classification for "branch vs live".
- * Added/removed docs surface as presence divergences (one side
- * `undefined`).
- *
- * @param branch The experiment.
- * @param target Live sandbox or a snapshot to compare against.
- */
-export declare function diff(branch: Branch, target: DiffTarget): Divergence[];
-/**
- * Promote a branch's mutations onto a target (live) sandbox.
- *
- * "Honest promote": it computes the doc-level delta between the branch's
- * BASE snapshot and its current state — i.e. exactly what the applied
- * events changed — and lands only those mutations on the target through
- * the admin plane:
- *   - docs added/changed on the branch → `admin.setDocument`
- *   - docs deleted on the branch       → `admin.deleteDocument`
- *   - docs the branch never touched    → left untouched on the target
- *
- * Admin-plane application fires the target's listeners (matching how
- * persistence restore lands docs), so live UI/handles see the promotion.
- *
- * The branch is marked discarded afterward — a promoted branch is spent.
- *
- * @param branch The experiment to land.
- * @param target The live sandbox to land it on.
- */
-export declare function promote(branch: Branch, target: LocalSandbox): void;
-/**
- * Discard a branch: drop its sandbox and mark it spent. The target is
- * never touched (nothing was promoted). Idempotent.
- */
-export declare function discard(branch: Branch): void;
+ * `pyric/sandbox/branches` is the branch primitive's public surface.
+ *
+ * Re-exports only. The engine lives in `engine.ts`, the cross-service diff in
+ * `state-diff.ts`, and the promotion delta in `promotion.ts`. The on-disk
+ * store lives in `store.ts` and is published from its own subpath because it
+ * reads files.
+ */
+export { apply, diff, discard, fork, promote } from './engine.js';
+export type { Branch, BranchCandidateRules, DiffTarget } from './engine.js';
+export { diffFullStates } from './state-diff.js';
+export type { BranchDivergence, TreeChange } from './state-diff.js';
+export { promoteFullState } from './promotion.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sandbox/branches/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AASrB;;;;;;;GAOG;AACH,MAAM,WAAW,MAAM;IACrB;qEACiE;IACjE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B;+CAC2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;6DACyD;IACzD,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B;2DACuD;IACvD,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC;IAChC;uBACmB;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,eAAe,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,SAAK,GAAG,MAAM,CAmFlE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAiC7E;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,UAAU,EAAE,CAKrE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAuBlE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAI5C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sandbox/branches/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EAAE,MAAM,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}