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

package/dist/sandbox/branches/state-diff.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The structural difference between two full sandbox states, service by
+ * service.
+ *
+ * One walk serves both readers. `diff` renders it as {@link BranchDivergence}
+ * records that name the service and the path or uid they concern, and
+ * `promote` applies the same records as writes. Keeping them on one walk is
+ * what makes "what the diff showed" and "what the promotion landed" the same
+ * set by construction rather than by two implementations agreeing.
+ *
+ * The divergence kinds are the replay engine's, unchanged. A branch carries no
+ * captured write metadata that could license sentinel or auto-id drift, so
+ * every difference here is a `real-divergence`, which is the honest
+ * classification for state against state.
+ */
+import type { JsonValue } from '../../database/sandbox/data-tree.js';
+import type { FullSandboxState, SandboxService } from '../full-state.js';
+import type { Divergence } from '../replay/index.js';
+/**
+ * One divergence, tagged with the service whose state it concerns.
+ *
+ * Always a `real-divergence`. The replay engine's other kinds classify drift a
+ * captured write licenses, and a branch carries no such metadata, so state
+ * against state has only the one honest classification.
+ */
+export type BranchDivergence = Extract<Divergence, {
+    kind: 'real-divergence';
+}> & {
+    service: SandboxService;
+};
+/**
+ * The path auth's provider configuration reports under, in place of a uid. The
+ * leading dot is the same convention {@link DATABASE_PRIORITY_FIELD} uses, and
+ * it keeps the entry outside the uid keyspace the rest of the auth records use.
+ */
+export declare const AUTH_PROVIDER_CONFIG_PATH = ".providers";
+/** The field a Realtime Database priority reports under, beside its path. */
+export declare const DATABASE_PRIORITY_FIELD = ".priority";
+/** One change to the Realtime Database tree, at the shallowest path that differs. */
+export interface TreeChange {
+    path: string;
+    before: JsonValue;
+    after: JsonValue;
+}
+/** Structural equality over plain JSON values. */
+export declare function jsonEqual(a: unknown, b: unknown): boolean;
+/** The `data` subtree of a Realtime Database persistence envelope. */
+export declare function databaseTreeOf(state: FullSandboxState): JsonValue;
+/** The priorities map of a Realtime Database persistence envelope. */
+export declare function databasePrioritiesOf(state: FullSandboxState): Record<string, JsonValue>;
+/**
+ * Every change between two Realtime Database trees, each at the shallowest
+ * path that differs. Two objects are walked key by key; anything else is one
+ * change at that path, which is exactly the granularity `adminSet` takes.
+ */
+export declare function diffTrees(before: JsonValue, after: JsonValue): TreeChange[];
+/**
+ * Every difference between two full sandbox states, ordered service by service:
+ * Firestore, then the Realtime Database, then Storage, then auth, then rules.
+ *
+ * `before` is the reference and `after` is the state being described, so a
+ * record's `before` and `after` read the way a caller asking "what would
+ * landing this change do" expects.
+ */
+export declare function diffFullStates(before: FullSandboxState, after: FullSandboxState): BranchDivergence[];
+//# sourceMappingURL=state-diff.d.ts.map

package/dist/sandbox/branches/state-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-diff.d.ts","sourceRoot":"","sources":["../../../src/sandbox/branches/state-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,KAAK,EAEV,gBAAgB,EAChB,cAAc,EAEf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,CAAC,GAAG;IAChF,OAAO,EAAE,cAAc,CAAC;CACzB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,eAAe,CAAC;AAEtD,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAEnD,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,kDAAkD;AAClD,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAuBzD;AAOD,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAOjE;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAMvF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,UAAU,EAAE,CAI3E;AAwMD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,gBAAgB,GACtB,gBAAgB,EAAE,CAQpB"}

package/dist/sandbox/branches/state-diff.js

@@ -0,0 +1,270 @@
+/**
+ * The structural difference between two full sandbox states, service by
+ * service.
+ *
+ * One walk serves both readers. `diff` renders it as {@link BranchDivergence}
+ * records that name the service and the path or uid they concern, and
+ * `promote` applies the same records as writes. Keeping them on one walk is
+ * what makes "what the diff showed" and "what the promotion landed" the same
+ * set by construction rather than by two implementations agreeing.
+ *
+ * The divergence kinds are the replay engine's, unchanged. A branch carries no
+ * captured write metadata that could license sentinel or auto-id drift, so
+ * every difference here is a `real-divergence`, which is the honest
+ * classification for state against state.
+ */
+import { decodeStateDocument } from '../internal/state-values.js';
+/**
+ * The path auth's provider configuration reports under, in place of a uid. The
+ * leading dot is the same convention {@link DATABASE_PRIORITY_FIELD} uses, and
+ * it keeps the entry outside the uid keyspace the rest of the auth records use.
+ */
+export const AUTH_PROVIDER_CONFIG_PATH = '.providers';
+/** The field a Realtime Database priority reports under, beside its path. */
+export const DATABASE_PRIORITY_FIELD = '.priority';
+/** Structural equality over plain JSON values. */
+export function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    const aIsArray = Array.isArray(a);
+    const bIsArray = Array.isArray(b);
+    if (aIsArray !== bIsArray)
+        return false;
+    if (aIsArray && bIsArray) {
+        if (a.length !== b.length)
+            return false;
+        for (let index = 0; index < a.length; index++) {
+            if (!jsonEqual(a[index], b[index]))
+                return false;
+        }
+        return true;
+    }
+    const aObject = a;
+    const bObject = b;
+    const aKeys = Object.keys(aObject);
+    if (aKeys.length !== Object.keys(bObject).length)
+        return false;
+    for (const key of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(bObject, key))
+            return false;
+        if (!jsonEqual(aObject[key], bObject[key]))
+            return false;
+    }
+    return true;
+}
+/** True when a JSON value is a plain object the walk should descend into. */
+function isBranchingNode(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** The `data` subtree of a Realtime Database persistence envelope. */
+export function databaseTreeOf(state) {
+    const envelope = state.database;
+    if (!isBranchingNode(envelope))
+        return envelope;
+    if (!('.pyricRtdbPersistence' in envelope))
+        return envelope;
+    const data = envelope.data;
+    if (data === undefined)
+        return null;
+    return data;
+}
+/** The priorities map of a Realtime Database persistence envelope. */
+export function databasePrioritiesOf(state) {
+    const envelope = state.database;
+    if (!isBranchingNode(envelope))
+        return {};
+    const priorities = envelope.priorities;
+    if (!isBranchingNode(priorities))
+        return {};
+    return priorities;
+}
+/**
+ * Every change between two Realtime Database trees, each at the shallowest
+ * path that differs. Two objects are walked key by key; anything else is one
+ * change at that path, which is exactly the granularity `adminSet` takes.
+ */
+export function diffTrees(before, after) {
+    const changes = [];
+    walkTree(before, after, '', changes);
+    return changes;
+}
+function walkTree(before, after, path, out) {
+    if (jsonEqual(before, after))
+        return;
+    const bothBranch = isBranchingNode(before) && isBranchingNode(after);
+    if (!bothBranch) {
+        out.push({ path: path === '' ? '/' : path, before, after });
+        return;
+    }
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of keys) {
+        const childPath = path === '' ? key : `${path}/${key}`;
+        walkTree(before[key] ?? null, after[key] ?? null, childPath, out);
+    }
+}
+/** One divergence record, built once so every service reports the same shape. */
+function divergenceAt(service, path, field, before, after) {
+    if (field === undefined) {
+        return { kind: 'real-divergence', service, path, before, after };
+    }
+    return { kind: 'real-divergence', service, path, field, before, after };
+}
+/**
+ * Field-level walk over one document, producing dotted and bracketed leaf
+ * paths (`profile.lastSeen`, `tags[0]`), the same syntax the replay engine's
+ * own diff produces.
+ */
+function walkDocument(service, path, before, after, out) {
+    walk(before, after, '');
+    function walk(a, b, field) {
+        if (jsonEqual(a, b))
+            return;
+        if (isBranchingNode(a) && isBranchingNode(b)) {
+            const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+            for (const key of keys) {
+                const next = field === '' ? key : `${field}.${key}`;
+                walk(a[key], b[key], next);
+            }
+            return;
+        }
+        if (Array.isArray(a) && Array.isArray(b)) {
+            const length = Math.max(a.length, b.length);
+            for (let index = 0; index < length; index++) {
+                walk(a[index], b[index], `${field}[${index}]`);
+            }
+            return;
+        }
+        let leafField = field;
+        if (field === '')
+            leafField = undefined;
+        out.push(divergenceAt(service, path, leafField, a, b));
+    }
+}
+/** Compare user fields rather than the escaped representation stored on disk. */
+function documentForDiff(state, path) {
+    const document = state.firestore[path];
+    const isMissing = document === undefined;
+    if (isMissing)
+        return undefined;
+    return decodeStateDocument(document, state.firestoreEncoding);
+}
+/** Firestore documents, by full document path. */
+function diffFirestore(before, after) {
+    const out = [];
+    const paths = new Set([...Object.keys(before.firestore), ...Object.keys(after.firestore)]);
+    for (const path of paths) {
+        const beforeDoc = documentForDiff(before, path);
+        const afterDoc = documentForDiff(after, path);
+        const oneSideMissing = beforeDoc === undefined || afterDoc === undefined;
+        if (oneSideMissing) {
+            const bothMissing = jsonEqual(beforeDoc ?? null, afterDoc ?? null);
+            if (bothMissing)
+                continue;
+            out.push(divergenceAt('firestore', path, undefined, beforeDoc, afterDoc));
+            continue;
+        }
+        walkDocument('firestore', path, beforeDoc, afterDoc, out);
+    }
+    return out;
+}
+/** The Realtime Database tree and its priorities, by database path. */
+function diffDatabase(before, after) {
+    const out = [];
+    for (const change of diffTrees(databaseTreeOf(before), databaseTreeOf(after))) {
+        out.push(divergenceAt('database', change.path, undefined, change.before, change.after));
+    }
+    const beforePriorities = databasePrioritiesOf(before);
+    const afterPriorities = databasePrioritiesOf(after);
+    const paths = new Set([...Object.keys(beforePriorities), ...Object.keys(afterPriorities)]);
+    for (const path of paths) {
+        if (jsonEqual(beforePriorities[path], afterPriorities[path]))
+            continue;
+        out.push(divergenceAt('database', path, DATABASE_PRIORITY_FIELD, beforePriorities[path], afterPriorities[path]));
+    }
+    return out;
+}
+/** Storage objects by path, one map so a missing object is a path-level difference. */
+function objectsByPath(objects) {
+    return new Map(objects.map((object) => [object.path, object]));
+}
+/** Storage objects, by object path. Bytes, content type, and custom metadata. */
+function diffStorage(before, after) {
+    const out = [];
+    const beforeObjects = objectsByPath(before.storage);
+    const afterObjects = objectsByPath(after.storage);
+    const paths = new Set([...beforeObjects.keys(), ...afterObjects.keys()]);
+    for (const path of [...paths].sort()) {
+        const beforeObject = beforeObjects.get(path);
+        const afterObject = afterObjects.get(path);
+        const oneSideMissing = beforeObject === undefined || afterObject === undefined;
+        if (oneSideMissing) {
+            out.push(divergenceAt('storage', path, undefined, beforeObject, afterObject));
+            continue;
+        }
+        walkDocument('storage', path, beforeObject, afterObject, out);
+    }
+    return out;
+}
+/** Auth accounts by uid, plus the provider configuration over them. */
+function diffAuth(before, after) {
+    const out = [];
+    const beforeUsers = new Map(before.users.map((user) => [user.uid, user]));
+    const afterUsers = new Map(after.users.map((user) => [user.uid, user]));
+    const uids = new Set([...beforeUsers.keys(), ...afterUsers.keys()]);
+    for (const uid of [...uids].sort()) {
+        const beforeUser = beforeUsers.get(uid);
+        const afterUser = afterUsers.get(uid);
+        const oneSideMissing = beforeUser === undefined || afterUser === undefined;
+        if (oneSideMissing) {
+            out.push(divergenceAt('auth', uid, undefined, beforeUser, afterUser));
+            continue;
+        }
+        walkDocument('auth', uid, beforeUser, afterUser, out);
+    }
+    const providerIds = new Set([
+        ...Object.keys(before.providers),
+        ...Object.keys(after.providers),
+    ]);
+    for (const providerId of [...providerIds].sort()) {
+        if (before.providers[providerId] === after.providers[providerId])
+            continue;
+        out.push(divergenceAt('auth', AUTH_PROVIDER_CONFIG_PATH, providerId, before.providers[providerId], after.providers[providerId]));
+    }
+    return out;
+}
+/** The three rule sources, each under its own service name as the path. */
+function diffRules(before, after) {
+    const out = [];
+    if (before.rules.firestore !== after.rules.firestore) {
+        out.push(divergenceAt('rules', 'firestore', undefined, before.rules.firestore, after.rules.firestore));
+    }
+    if (!jsonEqual(before.rules.database, after.rules.database)) {
+        out.push(divergenceAt('rules', 'database', undefined, before.rules.database, after.rules.database));
+    }
+    if (before.rules.storage !== after.rules.storage) {
+        out.push(divergenceAt('rules', 'storage', undefined, before.rules.storage, after.rules.storage));
+    }
+    return out;
+}
+/**
+ * Every difference between two full sandbox states, ordered service by service:
+ * Firestore, then the Realtime Database, then Storage, then auth, then rules.
+ *
+ * `before` is the reference and `after` is the state being described, so a
+ * record's `before` and `after` read the way a caller asking "what would
+ * landing this change do" expects.
+ */
+export function diffFullStates(before, after) {
+    return [
+        ...diffFirestore(before, after),
+        ...diffDatabase(before, after),
+        ...diffStorage(before, after),
+        ...diffAuth(before.auth, after.auth),
+        ...diffRules(before, after),
+    ];
+}
+//# sourceMappingURL=state-diff.js.map

package/dist/sandbox/branches/state-diff.js.map

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

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

@@ -0,0 +1,64 @@
+import { type Branch } from './engine.js';
+/** The tag every branch manifest carries, so an unrelated directory is not read as one. */
+export declare const BRANCH_FORMAT = "pyric-branch-v2";
+/** Where branches live, relative to the project directory. */
+export declare const BRANCH_STORE_RELATIVE: string;
+/** The names a branch may take: one path segment, so a name can never escape the store. */
+export declare const BRANCH_NAME_PATTERN: RegExp;
+/** A branch name the store refuses. Thrown rather than returned: it is a caller mistake. */
+export declare class BranchNameError extends Error {
+    constructor(name: string);
+}
+/** The manifest a branch directory carries, without the name its directory already states. */
+export interface BranchManifest {
+    format: typeof BRANCH_FORMAT;
+    /** When the branch was forked, as an ISO 8601 instant. */
+    created: string;
+    /** `live`, or the name of the checkpoint the fork was taken from. */
+    base: string;
+    /** How many events have been applied to the branch. */
+    eventCount: number;
+}
+/** One entry of a branch listing: the manifest plus the name the directory carries. */
+export interface BranchListing extends BranchManifest {
+    name: string;
+}
+/** A loaded branch: the rebuilt in-memory branch plus what the manifest recorded. */
+export interface LoadedBranch {
+    name: string;
+    branch: Branch;
+    manifest: BranchManifest;
+}
+/** What a save records beyond the branch itself. */
+export interface SaveBranchOptions {
+    /** `live`, or the name of the checkpoint the fork was taken from. */
+    base: string;
+    /** The creation instant to record. Defaults to now, which is what a fork wants. */
+    created?: string;
+}
+/** The directory one branch occupies. */
+export declare function branchDirectory(projectDir: string, name: string): string;
+/**
+ * Write one branch to its own directory, replacing whatever was there. The
+ * base, the current state, and the event log are all written from the branch
+ * itself, so a save after an `apply` or after a write on any service records
+ * exactly what the engine holds.
+ */
+export declare function saveBranch(projectDir: string, name: string, branch: Branch, options: SaveBranchOptions): Promise<BranchManifest>;
+/**
+ * Rebuild one branch from its directory, or null when the project has no
+ * branch by that name. The branch's sandbox is forked onto the stored current
+ * state, and the stored base and event log are restored beside it, so a loaded
+ * branch and a branch that never left memory are the same value in every
+ * service rather than only in the one the event log records.
+ */
+export declare function loadBranch(projectDir: string, name: string): Promise<LoadedBranch | null>;
+/**
+ * Every branch the project holds, ordered by name. A directory that carries no
+ * manifest this store wrote is skipped rather than failing the listing, so an
+ * unrelated file under the branch directory does not take the listing down.
+ */
+export declare function listBranches(projectDir: string): BranchListing[];
+/** Remove one branch directory. Returns whether there was one to remove. */
+export declare function removeBranch(projectDir: string, name: string): boolean;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/sandbox/branches/store.ts"],"names":[],"mappings":"AAiDA,OAAO,EAAQ,KAAK,MAAM,EAA6B,MAAM,aAAa,CAAC;AAE3E,2FAA2F;AAC3F,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,QAAsC,CAAC;AAUzE,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,QAAgC,CAAC;AAEjE,4FAA4F;AAC5F,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,IAAI,EAAE,MAAM;CAMzB;AAED,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,aAAa,CAAC;IAC7B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,uFAAuF;AACvF,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAOD,yCAAyC;AACzC,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxE;AA2ED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,cAAc,CAAC,CAsBzB;AAwCD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAa9B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,EAAE,CAYhE;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAKtE"}