pyric-tools 0.1.0-alpha.7

package/dist/discover/merge.js

@@ -0,0 +1,394 @@
+/**
+ * Pure-data schema merge / inference for `firestore_discover_paths`.
+ *
+ * Validation-grade implementation promoted to production with the following
+ * additions:
+ *
+ *   1. Enum-candidate tracking on string/integer/double scalar fields
+ *      (Phase 3.2 lock — drives <select> codegen and discriminated unions).
+ *   2. Per-field example value (Phase 3.2 lock — drives form placeholders,
+ *      fixtures, README payloads).
+ *   3. `null` is never a peer entry in `types[]`; only `nullable` carries the
+ *      annotation (Phase 2.1 lock — suppresses redundant `type_expanded`
+ *      events for null observations).
+ *   4. SchemaChange enum aligned with the Phase 5 frozen list (`field_added`
+ *      replaces `new_key`; `array_grew` and `presence_dropped` removed —
+ *      array element growth surfaces as `type_expanded` with `'[]'` path
+ *      segment; presence shifts surface as `presence_changed`).
+ *
+ * Pure functions only — no Firestore SDK imports. Wire-format conversion
+ * lives in `wire.ts`; this module operates on already-typed observations.
+ */
+// ─── Constants ────────────────────────────────────────────────────────────
+/** Default enum-candidate distinct-value cap (Phase 3.2 lock). */
+export const DEFAULT_ENUM_THRESHOLD = 10;
+// ─── Empty schema ─────────────────────────────────────────────────────────
+export function emptySchema() {
+    return { fields: {}, samplesSeen: 0 };
+}
+// ─── Type key (for dedup; NaN-safe by construction) ───────────────────────
+/**
+ * Stable key for FieldType used in dedup. NaN/±Infinity all collapse to
+ * `s:double` so no special handling needed (Phase 1.2 lock).
+ */
+export function fieldTypeKey(t) {
+    switch (t.kind) {
+        case 'scalar':
+            return `s:${t.type}`;
+        case 'reference':
+            return `r:${t.targetCollection}`;
+        case 'vector':
+            return `v:${t.dimension}`;
+        case 'array': {
+            const inner = t.elementTypes.map(fieldTypeKey).sort().join('|');
+            return `a:[${inner}]`;
+        }
+        case 'map': {
+            const keys = Object.keys(t.fields).sort().join(',');
+            return `m:{${keys}}`;
+        }
+    }
+}
+function dedupTypes(types) {
+    const seen = new Map();
+    for (const t of types)
+        seen.set(fieldTypeKey(t), t);
+    return Array.from(seen.values());
+}
+// ─── Enum candidate helpers ───────────────────────────────────────────────
+/** True if a scalar field type is enum-eligible (string/int/double only). */
+function isEnumEligibleScalar(t) {
+    if (t.kind !== 'scalar')
+        return false;
+    return t.type === 'string' || t.type === 'integer' || t.type === 'double';
+}
+/**
+ * Merge a single field observation into an existing descriptor.
+ * `observation === 'absent'` means the field was missing from the doc.
+ * `newTotal` is the doc count after this observation.
+ */
+export function mergeDescriptorWithObservation(prev, observation, newTotal, path) {
+    if (observation === 'absent') {
+        // Field absent — bump total only. presence_changed is NOT emitted on
+        // every absence (would be noisy); callers fold presence into a separate
+        // sweep at finalization if needed.
+        return { merged: { ...prev, presenceTotal: newTotal }, changes: [] };
+    }
+    const { type: obs, isNull, example, enumSample } = observation;
+    const changes = [];
+    // Null observation: bump nullable + presenceSeen. Do NOT add `null` to
+    // types[] (Phase 2.1 lock). Emit `became_nullable` once, on the transition.
+    if (isNull) {
+        const becameNullable = !prev.nullable;
+        return {
+            merged: {
+                ...prev,
+                presenceSeen: prev.presenceSeen + 1,
+                presenceTotal: newTotal,
+                nullable: true,
+            },
+            changes: becameNullable ? [{ kind: 'became_nullable', path }] : [],
+        };
+    }
+    // Type union management (non-null observation).
+    //
+    // Container collapse rule: array and map kinds are SINGLETONS in the
+    // descriptor's types[] union — at most one array entry, at most one map
+    // entry. Element-type / field growth across observations merges into the
+    // existing container entry rather than creating a parallel union member.
+    // This is the Phase 5 lock: dropping `array_grew` in favor of
+    // `type_expanded` at `[..., '[]']` presumes arrays collapse this way.
+    // Vectors are NOT singletons — distinct dimensions stay distinct per
+    // Phase 1.2 vector-drift lock.
+    let mergedTypes = prev.types;
+    if (obs.kind === 'array') {
+        const existingIdx = prev.types.findIndex((t) => t.kind === 'array');
+        if (existingIdx !== -1) {
+            const existing = prev.types[existingIdx];
+            if (existing.kind === 'array') {
+                const result = mergeArrays(existing, obs, path);
+                const next = [...prev.types];
+                next[existingIdx] = result.merged;
+                mergedTypes = next;
+                changes.push(...result.changes);
+            }
+        }
+        else {
+            mergedTypes = [...prev.types, obs];
+            changes.push({ kind: 'type_expanded', path, addedType: obs });
+        }
+    }
+    else if (obs.kind === 'map') {
+        const existingIdx = prev.types.findIndex((t) => t.kind === 'map');
+        if (existingIdx !== -1) {
+            const existing = prev.types[existingIdx];
+            if (existing.kind === 'map') {
+                const result = mergeMaps(existing, obs, path);
+                const next = [...prev.types];
+                next[existingIdx] = result.merged;
+                mergedTypes = next;
+                changes.push(...result.changes);
+            }
+        }
+        else {
+            mergedTypes = [...prev.types, obs];
+            changes.push({ kind: 'type_expanded', path, addedType: obs });
+        }
+    }
+    else {
+        // Scalar / reference / vector union management. Vectors stay distinct
+        // per dimension (different keys for different dims) — that's the lock.
+        const obsKey = fieldTypeKey(obs);
+        const prevKeys = new Set(prev.types.map(fieldTypeKey));
+        if (!prevKeys.has(obsKey)) {
+            mergedTypes = dedupTypes([...prev.types, obs]);
+            if (obs.kind === 'vector' && prev.types.some((t) => t.kind === 'vector')) {
+                changes.push({
+                    kind: 'vector_dim_drift',
+                    path,
+                    addedDimension: obs.dimension,
+                });
+            }
+            else {
+                changes.push({ kind: 'type_expanded', path, addedType: obs });
+            }
+        }
+    }
+    // Enum candidate update. Drop if the type union widened past enum
+    // eligibility (more than one type, or non-eligible type added).
+    let enumCandidate = prev.enumCandidate;
+    const stillEnumEligible = mergedTypes.length === 1 && isEnumEligibleScalar(mergedTypes[0]);
+    if (!stillEnumEligible && enumCandidate) {
+        changes.push({ kind: 'enum_dropped', path, reason: 'type_widened' });
+        enumCandidate = undefined;
+    }
+    else if (stillEnumEligible && enumSample !== undefined) {
+        const result = updateEnumCandidate(enumCandidate, enumSample, path);
+        enumCandidate = result.next;
+        changes.push(...result.changes);
+    }
+    // Example: capture on first non-null observation. Don't overwrite once set
+    // (deterministic for codegen).
+    const nextExample = prev.example === undefined && example !== undefined ? example : prev.example;
+    return {
+        merged: {
+            types: mergedTypes,
+            presenceSeen: prev.presenceSeen + 1,
+            presenceTotal: newTotal,
+            nullable: prev.nullable,
+            enumCandidate,
+            example: nextExample,
+            reservedReason: prev.reservedReason,
+        },
+        changes,
+    };
+}
+// ─── Enum candidate state machine ─────────────────────────────────────────
+/**
+ * Progress an enum candidate by one observation. State transitions:
+ *
+ *   undefined     + new sample → tracking (1 value, no event)
+ *   tracking(1)   + same       → tracking (no event)
+ *   tracking(1)   + new        → tracking (2 values), emit `enum_added`
+ *   tracking(N>1) + new (N+1<=threshold) → tracking, emit `enum_widened`
+ *   tracking(N=threshold) + new → undefined, emit `enum_dropped(over_threshold)`
+ */
+function updateEnumCandidate(prev, sample, path) {
+    if (prev === undefined) {
+        // First sighting — start tracking silently. Single value isn't an enum yet.
+        return {
+            next: { qualifies: false, values: [sample], threshold: DEFAULT_ENUM_THRESHOLD },
+            changes: [],
+        };
+    }
+    if (prev.values.includes(sample)) {
+        return { next: prev, changes: [] };
+    }
+    // New value — does it fit?
+    if (prev.values.length >= prev.threshold) {
+        return {
+            next: undefined,
+            changes: [{ kind: 'enum_dropped', path, reason: 'over_threshold' }],
+        };
+    }
+    const nextValues = [...prev.values, sample];
+    const wasFirstAdd = prev.values.length === 1;
+    // Mark qualifies once we have 2+ distinct values (still under threshold).
+    const next = { qualifies: true, values: nextValues, threshold: prev.threshold };
+    if (wasFirstAdd) {
+        return {
+            next,
+            changes: [{ kind: 'enum_added', path, values: nextValues }],
+        };
+    }
+    return {
+        next,
+        changes: [{ kind: 'enum_widened', path, addedValue: sample }],
+    };
+}
+// ─── Container-type recursive merges ──────────────────────────────────────
+function mergeArrays(prev, obs, path) {
+    // Empty array no-op merge (Phase 1.2 lock).
+    if (obs.elementTypes.length === 0)
+        return { merged: prev, changes: [] };
+    if (prev.elementTypes.length === 0) {
+        return { merged: { kind: 'array', elementTypes: obs.elementTypes }, changes: [] };
+    }
+    const prevKeys = new Set(prev.elementTypes.map(fieldTypeKey));
+    const changes = [];
+    const merged = [...prev.elementTypes];
+    const elementPath = [...path, '[]'];
+    for (const et of obs.elementTypes) {
+        if (!prevKeys.has(fieldTypeKey(et))) {
+            merged.push(et);
+            // Array element-type expansion surfaces as `type_expanded` at the
+            // `[]` path segment per Phase 5 SchemaChange enum.
+            changes.push({ kind: 'type_expanded', path: elementPath, addedType: et });
+        }
+    }
+    return { merged: { kind: 'array', elementTypes: dedupTypes(merged) }, changes };
+}
+function mergeMaps(prev, obs, path) {
+    // Empty map no-op merge (Phase 1.2 lock).
+    if (Object.keys(obs.fields).length === 0)
+        return { merged: prev, changes: [] };
+    if (Object.keys(prev.fields).length === 0) {
+        return { merged: { kind: 'map', fields: { ...obs.fields } }, changes: [] };
+    }
+    const changes = [];
+    const fields = { ...prev.fields };
+    for (const [k, obsDesc] of Object.entries(obs.fields)) {
+        const prevDesc = fields[k];
+        if (!prevDesc) {
+            fields[k] = obsDesc;
+            changes.push({ kind: 'field_added', path: [...path, k], type: obsDesc.types[0] });
+            continue;
+        }
+        // Recurse on the single observed type.
+        const obsType = obsDesc.types[0];
+        const isNull = obsDesc.nullable && obsDesc.types.length === 0;
+        const subResult = mergeDescriptorWithObservation(prevDesc, {
+            type: obsType ?? { kind: 'scalar', type: 'null' },
+            isNull,
+            example: obsDesc.example,
+            enumSample: extractEnumSample(obsType, obsDesc.example),
+        }, prevDesc.presenceTotal + 1, [...path, k]);
+        fields[k] = subResult.merged;
+        changes.push(...subResult.changes);
+    }
+    return { merged: { kind: 'map', fields }, changes };
+}
+/** Best-effort extraction of an enum sample from a nested-map observation. */
+function extractEnumSample(type, example) {
+    if (!type || !isEnumEligibleScalar(type))
+        return undefined;
+    if (typeof example === 'string' || typeof example === 'number')
+        return example;
+    return undefined;
+}
+// ─── Top-level mergeDoc ───────────────────────────────────────────────────
+/**
+ * Merge a single document's typed field observations into a collection-level
+ * schema. Returns the next schema and the changes emitted.
+ *
+ * The wire layer (`wire.ts`) is responsible for converting Firestore wire
+ * values into the `Record<string, FieldObservation>` shape expected here.
+ */
+export function mergeDoc(prev, doc) {
+    const newTotal = prev.samplesSeen + 1;
+    const allKeys = new Set([...Object.keys(prev.fields), ...Object.keys(doc)]);
+    const fields = {};
+    const changes = [];
+    for (const k of allKeys) {
+        const prevDesc = prev.fields[k];
+        const obs = doc[k];
+        if (!prevDesc && obs) {
+            // First time seeing this key.
+            const isNull = obs.isNull;
+            const enumEligible = !isNull && isEnumEligibleScalar(obs.type);
+            const enumCandidate = enumEligible && obs.enumSample !== undefined
+                ? {
+                    qualifies: false,
+                    values: [obs.enumSample],
+                    threshold: DEFAULT_ENUM_THRESHOLD,
+                }
+                : undefined;
+            fields[k] = {
+                types: isNull ? [] : [obs.type],
+                presenceSeen: 1,
+                presenceTotal: newTotal,
+                nullable: isNull,
+                enumCandidate,
+                example: obs.example,
+            };
+            if (!isNull) {
+                changes.push({ kind: 'field_added', path: [k], type: obs.type });
+            }
+            else {
+                // Null-only first observation: emit field_added with null kind so
+                // agents see the field surfaced; nullable annotation handles the
+                // rest. No became_nullable on first observation — there's no prior
+                // non-null state to flip from.
+                changes.push({
+                    kind: 'field_added',
+                    path: [k],
+                    type: { kind: 'scalar', type: 'null' },
+                });
+            }
+            continue;
+        }
+        if (prevDesc && !obs) {
+            const result = mergeDescriptorWithObservation(prevDesc, 'absent', newTotal, [k]);
+            fields[k] = result.merged;
+            changes.push(...result.changes);
+            continue;
+        }
+        if (prevDesc && obs) {
+            const result = mergeDescriptorWithObservation(prevDesc, obs, newTotal, [k]);
+            fields[k] = result.merged;
+            changes.push(...result.changes);
+        }
+    }
+    return { next: { fields, samplesSeen: newTotal }, changes };
+}
+/**
+ * Stream-driven convergence runner. Used by the production crawler's
+ * sampling loop and by Phase 2.x tests that replay corpus snapshots.
+ *
+ * `stopOnStable` is the optimistic early-exit signal (Phase 2.1 lock — must
+ * be paired with a `maxSamples` hard cap in the crawler, not here).
+ */
+export function runConvergence(docs, stopOnStable) {
+    let schema = emptySchema();
+    let consecutiveStable = 0;
+    let declaredAt = null;
+    let totalChanges = 0;
+    const missedChangesAfterDeclared = [];
+    let i = 0;
+    for (const doc of docs) {
+        const { next, changes } = mergeDoc(schema, doc);
+        schema = next;
+        totalChanges += changes.length;
+        if (changes.length === 0) {
+            consecutiveStable++;
+            if (declaredAt === null && consecutiveStable >= stopOnStable) {
+                declaredAt = i;
+            }
+        }
+        else {
+            consecutiveStable = 0;
+            if (declaredAt !== null) {
+                missedChangesAfterDeclared.push(...changes);
+            }
+        }
+        i++;
+    }
+    return {
+        declaredAt,
+        totalDocs: i,
+        totalChanges,
+        finalSchema: schema,
+        missedChangesAfterDeclared,
+    };
+}
+//# sourceMappingURL=merge.js.map

package/dist/discover/merge.js.map

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

package/dist/discover/rest-crawler-firestore.d.ts

@@ -0,0 +1,51 @@
+/**
+ * REST-backed `CrawlerFirestore` — the minimum surface
+ * `firestore_discover_paths` needs, satisfied by hitting the Firestore
+ * REST API directly with a Bearer token.
+ *
+ * Why this exists: the modular Web SDK (`firebase/firestore`) does NOT
+ * expose `listCollections()` at all — it's an admin-only operation.
+ * Anyone running discover from a browser (or any non-admin environment
+ * with an OAuth access token but no firebase-admin) needs this shim
+ * because there's no standard SDK alternative.
+ *
+ * Implements the structural `CrawlerFirestore` / `CrawlerCollectionRef`
+ * / `CrawlerDocumentRef` contracts from `./crawler.ts`. The shim is
+ * deliberately narrow — no client SDK, no admin SDK, no listeners. The
+ * crawler only ever calls `listCollections` / `listDocuments` / `get`,
+ * so that's all this provides.
+ *
+ * Wire format: REST returns `{ name, fields, createTime, updateTime }`
+ * where `fields` is the same `Record<string, FirestoreValue>` shape
+ * that firebase-admin exposes as `DocumentSnapshot._fieldsProto`. We
+ * surface it under exactly that key so `discover/wire.ts`'s
+ * `snapshotToObservations()` reads it unchanged — no translation
+ * layer, no type-narrowing loss.
+ *
+ * Auth: caller supplies an access token with `auth/datastore` scope
+ * (covered by `auth/firebase`). Token is bearer-injected on every
+ * request; expiry is the caller's problem.
+ */
+import type { CrawlerFirestore } from './crawler.js';
+export interface RestCrawlerFirestoreOptions {
+    /** Google OAuth access token, bearer-injected on every request. */
+    accessToken: string;
+    /** Firebase project id (project number is also accepted by the REST API). */
+    projectId: string;
+    /** Database id — defaults to `(default)`. Non-default DBs land in
+     *  `databases/<id>` instead of `databases/(default)`. */
+    databaseId?: string;
+    /** Override fetch — useful for tests. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export declare class RestCrawlerFirestoreError extends Error {
+    readonly status: number;
+    readonly endpoint: string;
+    constructor(status: number, endpoint: string, body: string);
+}
+/**
+ * Build the `CrawlerFirestore` the crawler expects. Returned object
+ * satisfies the structural contract — no class, no inheritance.
+ */
+export declare function createRestCrawlerFirestore(opts: RestCrawlerFirestoreOptions): CrawlerFirestore;
+//# sourceMappingURL=rest-crawler-firestore.d.ts.map

package/dist/discover/rest-crawler-firestore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest-crawler-firestore.d.ts","sourceRoot":"","sources":["../../src/discover/rest-crawler-firestore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAKtB,MAAM,WAAW,2BAA2B;IAC1C,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB;6DACyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,yBAA0B,SAAQ,KAAK;aAEhC,MAAM,EAAE,MAAM;aACd,QAAQ,EAAE,MAAM;gBADhB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChC,IAAI,EAAE,MAAM;CAKf;AAMD;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,2BAA2B,GAAG,gBAAgB,CAqJ9F"}

package/dist/discover/rest-crawler-firestore.js

@@ -0,0 +1,154 @@
+const FIRESTORE_REST = 'https://firestore.googleapis.com/v1';
+export class RestCrawlerFirestoreError extends Error {
+    status;
+    endpoint;
+    constructor(status, endpoint, body) {
+        super(`RestCrawlerFirestore ${endpoint}: ${status} ${truncate(body, 200)}`);
+        this.status = status;
+        this.endpoint = endpoint;
+        this.name = 'RestCrawlerFirestoreError';
+    }
+}
+function truncate(s, max) {
+    return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
+/**
+ * Build the `CrawlerFirestore` the crawler expects. Returned object
+ * satisfies the structural contract — no class, no inheritance.
+ */
+export function createRestCrawlerFirestore(opts) {
+    const databaseId = opts.databaseId ?? '(default)';
+    const docsRoot = `projects/${opts.projectId}/databases/${databaseId}/documents`;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    async function api(method, fullName, body, query) {
+        const qs = query
+            ? Object.entries(query)
+                .filter(([, v]) => v !== undefined)
+                .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+                .join('&')
+            : '';
+        const url = `${FIRESTORE_REST}/${fullName}${qs ? `?${qs}` : ''}`;
+        const res = await fetchImpl(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${opts.accessToken}`,
+                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            throw new RestCrawlerFirestoreError(res.status, url, await res.text());
+        }
+        return res.json();
+    }
+    /**
+     * Resolve a list of collection ids under `parentName` (the docs root
+     * for top-level collections, or `documents/path/to/doc` for
+     * subcollections). The REST endpoint pages, but a Firestore project
+     * realistically has <1k collection ids per document — first page is
+     * usually enough. We still follow `nextPageToken` defensively.
+     */
+    async function listCollectionIds(parentName) {
+        const ids = [];
+        let pageToken;
+        do {
+            const result = (await api('POST', `${parentName}:listCollectionIds`, pageToken ? { pageToken } : {}));
+            if (result.collectionIds)
+                ids.push(...result.collectionIds);
+            pageToken = result.nextPageToken;
+        } while (pageToken);
+        return ids;
+    }
+    /**
+     * Build a `CrawlerCollectionRef` from a path relative to the docs
+     * root (e.g. `users/alice/posts`). `id` is the last segment.
+     */
+    function makeCollectionRef(relativePath) {
+        const fullName = `${docsRoot}/${relativePath}`;
+        const id = relativePath.slice(relativePath.lastIndexOf('/') + 1);
+        return {
+            id,
+            path: relativePath,
+            async listDocuments() {
+                // `mask.fieldPaths=__name__` skips the document bodies — we
+                // only need ids/paths here. Sampling fetches bodies later
+                // via `get()`. `showMissing=true` so docs that exist only as
+                // subcollection parents still surface as refs (matches
+                // admin SDK's `listDocuments`).
+                const out = [];
+                let pageToken;
+                do {
+                    const result = (await api('GET', fullName, undefined, {
+                        'mask.fieldPaths': '__name__',
+                        showMissing: 'true',
+                        pageSize: '300',
+                        pageToken,
+                    }));
+                    for (const d of result.documents ?? []) {
+                        // `name` is the full resource path; strip the docs root
+                        // to get the workspace-relative path the crawler uses.
+                        const docPath = d.name.slice(`${docsRoot}/`.length);
+                        out.push(makeDocumentRef(docPath));
+                    }
+                    pageToken = result.nextPageToken;
+                } while (pageToken);
+                return out;
+            },
+        };
+    }
+    /**
+     * Build a `CrawlerDocumentRef` from a path relative to the docs
+     * root (e.g. `users/alice`). `id` is the last segment.
+     */
+    function makeDocumentRef(relativePath) {
+        const fullName = `${docsRoot}/${relativePath}`;
+        const id = relativePath.slice(relativePath.lastIndexOf('/') + 1);
+        return {
+            id,
+            path: relativePath,
+            async listCollections() {
+                const ids = await listCollectionIds(fullName);
+                return ids.map((cid) => makeCollectionRef(`${relativePath}/${cid}`));
+            },
+            async get() {
+                let result;
+                try {
+                    result = (await api('GET', fullName));
+                }
+                catch (e) {
+                    // 404 = "phantom missing parent" — a path that has
+                    // subcollections but no actual doc. firebase-admin's
+                    // `DocumentReference.get()` returns a snapshot with
+                    // `exists: false` and no fields here; we mirror that by
+                    // returning an empty-fields snapshot so the wire reader
+                    // produces zero observations instead of throwing.
+                    if (e instanceof RestCrawlerFirestoreError && e.status === 404) {
+                        return { _fieldsProto: {}, ref: { path: relativePath } };
+                    }
+                    throw e;
+                }
+                // Surface `fields` under the `_fieldsProto` key the wire
+                // reader looks for. The REST format is byte-identical to
+                // admin SDK's internal protobuf at this level (integerValue
+                // vs doubleValue preserved), so no translation is needed.
+                return {
+                    _fieldsProto: result.fields ?? {},
+                    ref: { path: relativePath },
+                };
+            },
+        };
+    }
+    return {
+        async listCollections() {
+            const ids = await listCollectionIds(docsRoot);
+            return ids.map((id) => makeCollectionRef(id));
+        },
+        collection(path) {
+            return makeCollectionRef(path);
+        },
+        doc(path) {
+            return makeDocumentRef(path);
+        },
+    };
+}
+//# sourceMappingURL=rest-crawler-firestore.js.map

package/dist/discover/rest-crawler-firestore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest-crawler-firestore.js","sourceRoot":"","sources":["../../src/discover/rest-crawler-firestore.ts"],"names":[],"mappings":"AAmCA,MAAM,cAAc,GAAG,qCAAqC,CAAC;AAc7D,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAEhC;IACA;IAFlB,YACkB,MAAc,EACd,QAAgB,EAChC,IAAY;QAEZ,KAAK,CAAC,wBAAwB,QAAQ,KAAK,MAAM,IAAI,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAJ5D,WAAM,GAAN,MAAM,CAAQ;QACd,aAAQ,GAAR,QAAQ,CAAQ;QAIhC,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,CAAS,EAAE,GAAW;IACtC,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAiC;IAC1E,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,WAAW,CAAC;IAClD,MAAM,QAAQ,GAAG,YAAY,IAAI,CAAC,SAAS,cAAc,UAAU,YAAY,CAAC;IAChF,MAAM,SAAS,GAAiB,IAAI,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAEpF,KAAK,UAAU,GAAG,CAChB,MAAsB,EACtB,QAAgB,EAChB,IAAc,EACd,KAA0C;QAE1C,MAAM,EAAE,GAAG,KAAK;YACd,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;iBAClB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;iBAClC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAW,CAAC,EAAE,CAAC;iBAC9E,IAAI,CAAC,GAAG,CAAC;YACd,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,GAAG,GAAG,GAAG,cAAc,IAAI,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACjE,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;YAC/B,MAAM;YACN,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,IAAI,CAAC,WAAW,EAAE;gBAC3C,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtE;YACD,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9D,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,yBAAyB,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,UAAU,iBAAiB,CAAC,UAAkB;QACjD,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,IAAI,SAA6B,CAAC;QAClC,GAAG,CAAC;YACF,MAAM,MAAM,GAAG,CAAC,MAAM,GAAG,CACvB,MAAM,EACN,GAAG,UAAU,oBAAoB,EACjC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAC/B,CAAyD,CAAC;YAC3D,IAAI,MAAM,CAAC,aAAa;gBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;YAC5D,SAAS,GAAG,MAAM,CAAC,aAAa,CAAC;QACnC,CAAC,QAAQ,SAAS,EAAE;QACpB,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;OAGG;IACH,SAAS,iBAAiB,CAAC,YAAoB;QAC7C,MAAM,QAAQ,GAAG,GAAG,QAAQ,IAAI,YAAY,EAAE,CAAC;QAC/C,MAAM,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACjE,OAAO;YACL,EAAE;YACF,IAAI,EAAE,YAAY;YAClB,KAAK,CAAC,aAAa;gBACjB,4DAA4D;gBAC5D,0DAA0D;gBAC1D,6DAA6D;gBAC7D,uDAAuD;gBACvD,gCAAgC;gBAChC,MAAM,GAAG,GAAyB,EAAE,CAAC;gBACrC,IAAI,SAA6B,CAAC;gBAClC,GAAG,CAAC;oBACF,MAAM,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE;wBACpD,iBAAiB,EAAE,UAAU;wBAC7B,WAAW,EAAE,MAAM;wBACnB,QAAQ,EAAE,KAAK;wBACf,SAAS;qBACV,CAAC,CAA+D,CAAC;oBAClE,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;wBACvC,wDAAwD;wBACxD,uDAAuD;wBACvD,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,QAAQ,GAAG,CAAC,MAAM,CAAC,CAAC;wBACpD,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;oBACrC,CAAC;oBACD,SAAS,GAAG,MAAM,CAAC,aAAa,CAAC;gBACnC,CAAC,QAAQ,SAAS,EAAE;gBACpB,OAAO,GAAG,CAAC;YACb,CAAC;SACF,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,SAAS,eAAe,CAAC,YAAoB;QAC3C,MAAM,QAAQ,GAAG,GAAG,QAAQ,IAAI,YAAY,EAAE,CAAC;QAC/C,MAAM,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACjE,OAAO;YACL,EAAE;YACF,IAAI,EAAE,YAAY;YAClB,KAAK,CAAC,eAAe;gBACnB,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;gBAC9C,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,iBAAiB,CAAC,GAAG,YAAY,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;YACvE,CAAC;YACD,KAAK,CAAC,GAAG;gBACP,IAAI,MAA2D,CAAC;gBAChE,IAAI,CAAC;oBACH,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAGnC,CAAC;gBACJ,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,mDAAmD;oBACnD,qDAAqD;oBACrD,oDAAoD;oBACpD,wDAAwD;oBACxD,wDAAwD;oBACxD,kDAAkD;oBAClD,IAAI,CAAC,YAAY,yBAAyB,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;wBAC/D,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,CAAC;oBAC3D,CAAC;oBACD,MAAM,CAAC,CAAC;gBACV,CAAC;gBACD,yDAAyD;gBACzD,yDAAyD;gBACzD,4DAA4D;gBAC5D,0DAA0D;gBAC1D,OAAO;oBACL,YAAY,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;oBACjC,GAAG,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE;iBAC5B,CAAC;YACJ,CAAC;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,CAAC,eAAe;YACnB,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAC9C,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC;QAChD,CAAC;QACD,UAAU,CAAC,IAAY;YACrB,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,CAAC,IAAY;YACd,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;KACF,CAAC;AACJ,CAAC"}