pyric 0.0.1 → 0.1.0-alpha.7

package/dist/firestore-values/index.js

@@ -0,0 +1,148 @@
+/**
+ * Firestore value codec — the marker-based serialize/rehydrate of
+ * Firestore special scalar types (Timestamp, Bytes, LatLng/GeoPoint,
+ * Duration, Reference, Path, Vector).
+ *
+ * WHY THIS MODULE EXISTS (and why it is a LEAF)
+ * ---------------------------------------------
+ * Two very different consumers need this codec:
+ *
+ *   1. The sandbox persistence serializer (`sandbox/persistence/serialize.ts`)
+ *      — server-side, already pulls the whole engine, doesn't care about size.
+ *   2. The SharedWorker CLIENT (`pyric-tools/.../worker/client.ts` via
+ *      `protocol.ts`) — runs in EVERY page that opens a serve session. It only
+ *      needs to reconstruct Timestamp/Bytes/LatLng instances from the JSON
+ *      markers the worker host wrote; it must NOT drag the rules engine,
+ *      simulator, parser, or sandbox into the per-page bundle.
+ *
+ * Importing the wrapper CLASSES from the `pyric/rules` BARREL would execute the
+ * entire rules index (parser + linter + simulator + evaluator → ~10 MB). The
+ * wrapper modules themselves are leaf — each depends only on `wrappers/base.js`
+ * which has zero imports — so this codec imports them by their DIRECT leaf
+ * paths. The result: importing this module pulls ONLY the seven small wrapper
+ * classes + their `base.js`, nothing heavy.
+ *
+ * Real types, not structural stand-ins: because the wrapper constructors are
+ * already leaf-cheap, the codec reconstructs the SAME real `Timestamp`/`Bytes`/
+ * `LatLng`/etc. classes the in-page (`pyric/firestore`) path yields. This keeps
+ * `instanceof` checks and method calls (`.toDate()`, `.toMillis()`, byte
+ * access, `.lat`/`.lng`) identical on both sides of the MessagePort and in IDB
+ * persistence — there is ONE codec, not two that can drift.
+ *
+ * Marker formats handled (must stay in sync with each wrapper's `toJSON()`):
+ *
+ * 1. `pyric/rules` wrapper markers (from `Timestamp.toJSON()` etc.):
+ *   { __type: 'timestamp', seconds, nanos }   → Timestamp
+ *   { __type: 'bytes', base64 }               → Bytes   (base64url)
+ *   { __type: 'latlng', lat, lng }            → LatLng
+ *   { __type: 'duration', seconds, nanos }    → Duration
+ *   { __type: 'reference', path }             → Reference
+ *   { __type: 'path', segments }              → Path
+ *   { __type__: '__vector__', value }         → Vector
+ *
+ * 2. `firebase/firestore` SDK markers (from fb.Timestamp.toJSON() etc.),
+ *    produced when `pyric/firestore`'s `getDoc` returns `firebase/firestore`
+ *    class instances that are then serialized via JSON.stringify:
+ *   { type: 'firestore/timestamp/1.0', seconds, nanoseconds } → Timestamp
+ *   { type: 'firestore/bytes/1.0', bytes }                    → Bytes (std b64)
+ *   { type: 'firestore/geoPoint/1.0', latitude, longitude }   → LatLng
+ *
+ * Unknown `__type`/`type` values pass through as plain objects rather than
+ * throwing — the rest of the doc still restores cleanly.
+ */
+// Direct leaf imports — NOT the `pyric/rules` barrel. Each of these modules
+// depends only on `./base.js` (no imports), so this stays engine-free.
+import { Bytes } from '../rules/simulator/wrappers/bytes.js';
+import { Duration } from '../rules/simulator/wrappers/duration.js';
+import { LatLng } from '../rules/simulator/wrappers/latlng.js';
+import { Path } from '../rules/simulator/wrappers/path.js';
+import { Reference } from '../rules/simulator/wrappers/reference.js';
+import { Timestamp } from '../rules/simulator/wrappers/timestamp.js';
+import { Vector } from '../rules/simulator/wrappers/vector.js';
+/**
+ * Decode a base64url string (`-`/`_` alphabet, no padding) back into a
+ * Uint8Array. Mirrors the encode path in `Bytes.toBase64` (RFC 4648 section 5).
+ */
+function base64UrlDecode(s) {
+    const std = s.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = std.length % 4 === 0 ? '' : '='.repeat(4 - (std.length % 4));
+    const bin = atob(std + pad);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/**
+ * Decode a standard base64 string (`+`/`/` alphabet, possibly `=`-padded)
+ * back to a Uint8Array. Used for `firebase/firestore` Bytes which encode in
+ * standard base64 (unlike pyric/rules Bytes which use base64url).
+ */
+function base64StdDecode(s) {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/**
+ * Walk a parsed JSON tree and re-wrap any marker shape back into its real
+ * wrapper-class instance. Visits arrays and plain objects recursively. Plain
+ * values (and plain objects without a recognized discriminator) pass through.
+ *
+ * This is the canonical rehydrate used by BOTH the sandbox persistence
+ * serializer and the SharedWorker wire protocol, so the IDB format and the
+ * MessagePort wire format are guaranteed identical.
+ */
+export function rehydrateDocValue(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(rehydrateDocValue);
+    const obj = value;
+    if (obj.__type__ === '__vector__' && Array.isArray(obj.value)) {
+        return new Vector(obj.value);
+    }
+    // pyric/rules wrapper marker form (used for IDB persistence + wire).
+    if (typeof obj.__type === 'string') {
+        switch (obj.__type) {
+            case 'timestamp':
+                return new Timestamp(obj.seconds, obj.nanos);
+            case 'bytes':
+                return new Bytes(base64UrlDecode(obj.base64));
+            case 'latlng':
+                return new LatLng(obj.lat, obj.lng);
+            case 'duration':
+                return new Duration(obj.seconds, obj.nanos);
+            case 'reference':
+                return new Reference(obj.path);
+            case 'path':
+                return new Path(obj.segments);
+        }
+    }
+    // firebase/firestore SDK marker form (produced when pyric/firestore's
+    // getDoc returns fb-SDK class instances and JSON.stringify is called).
+    if (typeof obj.type === 'string') {
+        switch (obj.type) {
+            case 'firestore/timestamp/1.0': {
+                // fb.Timestamp.toJSON() emits { type, seconds, nanoseconds }.
+                // The rules Timestamp uses nanos (not nanoseconds) — same value.
+                const seconds = obj.seconds;
+                const nanoseconds = obj.nanoseconds;
+                return new Timestamp(seconds, nanoseconds);
+            }
+            case 'firestore/bytes/1.0': {
+                // fb.Bytes.toJSON() emits { type, bytes } where bytes is standard base64.
+                return new Bytes(base64StdDecode(obj.bytes));
+            }
+            case 'firestore/geoPoint/1.0': {
+                // fb.GeoPoint.toJSON() emits { latitude, longitude, type }.
+                return new LatLng(obj.latitude, obj.longitude);
+            }
+        }
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(obj))
+        out[k] = rehydrateDocValue(v);
+    return out;
+}
+//# sourceMappingURL=index.js.map

package/dist/firestore-values/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/firestore-values/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,4EAA4E;AAC5E,uEAAuE;AACvE,OAAO,EAAE,KAAK,EAAE,MAAM,sCAAsC,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,yCAAyC,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,uCAAuC,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,qCAAqC,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,0CAA0C,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,0CAA0C,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,uCAAuC,CAAC;AAE/D;;;GAGG;AACH,SAAS,eAAe,CAAC,CAAS;IAChC,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IACzE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;IAC5B,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,CAAS;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAE9D,MAAM,GAAG,GAAG,KAAgC,CAAC;IAE7C,IAAI,GAAG,CAAC,QAAQ,KAAK,YAAY,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9D,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,KAAiB,CAAC,CAAC;IAC3C,CAAC;IAED,qEAAqE;IACrE,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACnC,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC;YACnB,KAAK,WAAW;gBACd,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,OAAiB,EAAE,GAAG,CAAC,KAAe,CAAC,CAAC;YACnE,KAAK,OAAO;gBACV,OAAO,IAAI,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,MAAgB,CAAC,CAAC,CAAC;YAC1D,KAAK,QAAQ;gBACX,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,GAAa,EAAE,GAAG,CAAC,GAAa,CAAC,CAAC;YAC1D,KAAK,UAAU;gBACb,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAiB,EAAE,GAAG,CAAC,KAAe,CAAC,CAAC;YAClE,KAAK,WAAW;gBACd,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,IAAc,CAAC,CAAC;YAC3C,KAAK,MAAM;gBACT,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,QAAoB,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,uEAAuE;IACvE,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjC,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,yBAAyB,CAAC,CAAC,CAAC;gBAC/B,8DAA8D;gBAC9D,iEAAiE;gBACjE,MAAM,OAAO,GAAG,GAAG,CAAC,OAAiB,CAAC;gBACtC,MAAM,WAAW,GAAG,GAAG,CAAC,WAAqB,CAAC;gBAC9C,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YAC7C,CAAC;YACD,KAAK,qBAAqB,CAAC,CAAC,CAAC;gBAC3B,0EAA0E;gBAC1E,OAAO,IAAI,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,KAAe,CAAC,CAAC,CAAC;YACzD,CAAC;YACD,KAAK,wBAAwB,CAAC,CAAC,CAAC;gBAC9B,4DAA4D;gBAC5D,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,QAAkB,EAAE,GAAG,CAAC,SAAmB,CAAC,CAAC;YACrE,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;IACxE,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/project-scope.d.ts

@@ -0,0 +1,5 @@
+export interface ProjectScope {
+    readonly projectId: string;
+    resolveToken(): Promise<string>;
+}
+//# sourceMappingURL=project-scope.d.ts.map

package/dist/project-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-scope.d.ts","sourceRoot":"","sources":["../src/project-scope.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC"}

package/dist/project-scope.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=project-scope.js.map

package/dist/project-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-scope.js","sourceRoot":"","sources":["../src/project-scope.ts"],"names":[],"mappings":""}

package/dist/rules/extract.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `pyric/rules/extract`: composite-index extractor entry.
+ *
+ * The extractor statically analyzes JS/TS source (via the TypeScript compiler)
+ * for the modular Firestore client's `query(collection(...), where(...),
+ * orderBy(...))` pattern. The TS compiler is large (~10MB) and optimizer-
+ * hostile, so it lives on its OWN subpath rather than the `pyric/rules` root
+ * barrel.
+ *
+ * Why a subpath and not the root: every app that imports `firebase/firestore`
+ * reaches `pyric/rules` (via `pyric/firestore`), and Vite's dep optimizer
+ * bundles a bare-specifier dep WHOLESALE, so it cannot tree-shake an entry's
+ * exports, and it follows dynamic imports; a root re-export (static OR
+ * lazy) drags the whole TS compiler into every browser bundle and trips the
+ * optimizer. Keeping the extractor here means `pyric/rules` stays compiler-free
+ * for apps that never extract; browser callers that DO extract (the playground)
+ * and Node callers (the MCP) opt in by importing `pyric/rules/extract`.
+ *
+ * (The erasable extractor TYPES stay re-exported from the root barrel too, since
+ * type-only exports compile away and never reach a bundle.)
+ */
+export { extractIndexes } from './indexes/extract/extractor.js';
+export { ExtractFirestoreIndexesHandler } from './indexes/extractHandler.js';
+export { createFirestoreExtractTool } from './indexes/extractTool.js';
+export type { ExtractIndexesOptions } from './indexes/extractHandler.js';
+export type { ExtractResult, ExtractionWarning, ExtractionSignal, ExtractOptions, QueryShape, Filter as IndexFilter, Order as IndexOrder, Fragment as IndexFragment, QueryBaseDecl, AnnotationApplied, } from './indexes/extract/types.js';
+export type { ApiScope, ArrayConfig, Density, Index, IndexField, IndexFieldOrder, IndexOperation, IndexState, IndexesConfig, IndexesConfigEntry, QueryScope, VectorConfig, } from './indexes/types.js';
+//# sourceMappingURL=extract.d.ts.map

package/dist/rules/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/rules/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,MAAM,IAAI,WAAW,EACrB,KAAK,IAAI,UAAU,EACnB,QAAQ,IAAI,aAAa,EACzB,aAAa,EACb,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,QAAQ,EACR,WAAW,EACX,OAAO,EACP,KAAK,EACL,UAAU,EACV,eAAe,EACf,cAAc,EACd,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,YAAY,GACb,MAAM,oBAAoB,CAAC"}

package/dist/rules/extract.js

@@ -0,0 +1,25 @@
+/**
+ * `pyric/rules/extract`: composite-index extractor entry.
+ *
+ * The extractor statically analyzes JS/TS source (via the TypeScript compiler)
+ * for the modular Firestore client's `query(collection(...), where(...),
+ * orderBy(...))` pattern. The TS compiler is large (~10MB) and optimizer-
+ * hostile, so it lives on its OWN subpath rather than the `pyric/rules` root
+ * barrel.
+ *
+ * Why a subpath and not the root: every app that imports `firebase/firestore`
+ * reaches `pyric/rules` (via `pyric/firestore`), and Vite's dep optimizer
+ * bundles a bare-specifier dep WHOLESALE, so it cannot tree-shake an entry's
+ * exports, and it follows dynamic imports; a root re-export (static OR
+ * lazy) drags the whole TS compiler into every browser bundle and trips the
+ * optimizer. Keeping the extractor here means `pyric/rules` stays compiler-free
+ * for apps that never extract; browser callers that DO extract (the playground)
+ * and Node callers (the MCP) opt in by importing `pyric/rules/extract`.
+ *
+ * (The erasable extractor TYPES stay re-exported from the root barrel too, since
+ * type-only exports compile away and never reach a bundle.)
+ */
+export { extractIndexes } from './indexes/extract/extractor.js';
+export { ExtractFirestoreIndexesHandler } from './indexes/extractHandler.js';
+export { createFirestoreExtractTool } from './indexes/extractTool.js';
+//# sourceMappingURL=extract.js.map

package/dist/rules/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/rules/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/rules/generators/assembler.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Assembles a complete Firestore security rules file for a grid-based game.
+ *
+ * Optimization levels (applied automatically based on board size):
+ * - Small boards (≤42 cells): nested board map, static enumeration, single win function
+ * - Medium boards (43-121 cells): flat layout, dynamic access, MapDiff, directional win split
+ *
+ * Uses the stdlib convention: host/guest/currentTurn/status.
+ */
+import type { GridConfig } from './grid.js';
+export interface GameConfig {
+    collection: string;
+    grid: GridConfig;
+    winLineCount: number;
+    hasGravity: boolean;
+    hasLobby: boolean;
+}
+export declare function assembleGameRules(config: GameConfig): string;
+//# sourceMappingURL=assembler.d.ts.map

package/dist/rules/generators/assembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembler.d.ts","sourceRoot":"","sources":["../../../src/rules/generators/assembler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAW5C,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AA0BD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAW5D"}

package/dist/rules/generators/assembler.js

@@ -0,0 +1,292 @@
+/**
+ * Assembles a complete Firestore security rules file for a grid-based game.
+ *
+ * Optimization levels (applied automatically based on board size):
+ * - Small boards (≤42 cells): nested board map, static enumeration, single win function
+ * - Medium boards (43-121 cells): flat layout, dynamic access, MapDiff, directional win split
+ *
+ * Uses the stdlib convention: host/guest/currentTurn/status.
+ */
+import { generateWinLines } from './grid.js';
+import { winCheckExpr, splitWinLinesByDirection, gravityExpr, cellEmptyExpr, boardIntegrityExpr, placementExpr, } from './expressions.js';
+const SMALL_BOARD_THRESHOLD = 42;
+/** A single Firestore path segment we are willing to interpolate into a
+ *  `match /<collection>/{gameId}` block. Deliberately stricter than
+ *  Firestore's own collection-id rules: alphanumerics, dash, underscore,
+ *  1–64 chars. Anything else (slashes, braces, whitespace, newlines) could
+ *  break out of the match block and inject arbitrary rules, so we reject it
+ *  rather than escape it. */
+const COLLECTION_SEGMENT = /^[A-Za-z0-9_-]{1,64}$/;
+/** Validate a caller-supplied collection name before it is interpolated into
+ *  generated rules source. Throws on anything that isn't a plain path
+ *  segment — every caller of the public `pyric/rules` generator is safe by
+ *  default, no escaping required at the call site. */
+function assertSafeCollection(collection) {
+    if (typeof collection !== 'string' || !COLLECTION_SEGMENT.test(collection)) {
+        throw new Error(`assembleGameRules: invalid collection ${JSON.stringify(collection)} — ` +
+            `must match ${COLLECTION_SEGMENT} (a single Firestore path segment: ` +
+            `letters, digits, "-" or "_", 1–64 chars). Rejected to prevent rules injection.`);
+    }
+}
+export function assembleGameRules(config) {
+    const { grid, winLineCount, hasGravity, hasLobby, collection } = config;
+    assertSafeCollection(collection);
+    const totalCells = grid.cols * grid.rows;
+    const lines = generateWinLines(grid.cols, grid.rows, winLineCount);
+    const useOptimized = totalCells > SMALL_BOARD_THRESHOLD;
+    if (useOptimized) {
+        return assembleOptimized(config, lines);
+    }
+    return assembleClassic(config, lines);
+}
+// ---- Classic: nested board map, static enumeration ----
+function assembleClassic(config, lines) {
+    const { grid, hasGravity, hasLobby, collection } = config;
+    const totalCells = grid.cols * grid.rows;
+    const placementChecks = [`(${placementExpr(grid)})`];
+    if (hasGravity) {
+        placementChecks.unshift(`(${gravityExpr(grid)})`);
+    }
+    else {
+        placementChecks.unshift(`(${cellEmptyExpr(grid)})`);
+    }
+    const validMoveBody = placementChecks.join('\n          && ');
+    const integrityBody = boardIntegrityExpr(grid);
+    const commonMove = `request.auth != null
+        && resource.data.status == 'playing'
+        && (
+          (resource.data.currentTurn == 'host' && request.auth.uid == resource.data.host)
+          || (resource.data.currentTurn == 'guest' && request.auth.uid == resource.data.guest)
+        )
+        && (
+          (resource.data.currentTurn == 'host' && request.resource.data.currentTurn == 'guest')
+          || (resource.data.currentTurn == 'guest' && request.resource.data.currentTurn == 'host')
+        )
+        && request.resource.data.moveCount == resource.data.moveCount + 1
+        && request.resource.data.host == resource.data.host
+        && request.resource.data.guest == resource.data.guest`;
+    const locChecks = `&& request.resource.data.lastCol >= 0 && request.resource.data.lastCol <= ${grid.cols - 1}
+        && request.resource.data.lastRow >= 0 && request.resource.data.lastRow <= ${grid.rows - 1}`;
+    return `rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+
+    function hasWonHost(b) {
+      return ${winCheckExpr('host', lines, grid)};
+    }
+
+    function hasWonGuest(b) {
+      return ${winCheckExpr('guest', lines, grid)};
+    }
+
+    function validMove(nc, nr, mark, b, ob) {
+      return ${validMoveBody};
+    }
+
+    function boardOk(nc, nr, b, ob) {
+      return ${integrityBody};
+    }
+
+    match /${collection}/{gameId} {
+      allow read: if request.auth != null;
+${lobbyRules(hasLobby)}
+      // --- Normal move (game continues) ---
+      allow update: if ${commonMove}
+        ${locChecks}
+        && request.resource.data.status == 'playing'
+        && request.resource.data.winner == ''
+        && validMove(
+            request.resource.data.lastCol,
+            request.resource.data.lastRow,
+            resource.data.currentTurn,
+            request.resource.data.board,
+            resource.data.board
+          )${totalCells <= SMALL_BOARD_THRESHOLD ? `
+        && boardOk(
+            request.resource.data.lastCol,
+            request.resource.data.lastRow,
+            request.resource.data.board,
+            resource.data.board
+          )` : ''};
+
+      // --- Winning move (host) ---
+      allow update: if ${commonMove}
+        ${locChecks}
+        && request.resource.data.status == 'won'
+        && request.resource.data.winner == 'host'
+        && hasWonHost(request.resource.data.board);
+
+      // --- Winning move (guest) ---
+      allow update: if ${commonMove}
+        ${locChecks}
+        && request.resource.data.status == 'won'
+        && request.resource.data.winner == 'guest'
+        && hasWonGuest(request.resource.data.board);
+
+      // --- Draw ---
+      allow update: if ${commonMove}
+        && request.resource.data.moveCount == ${totalCells}
+        && request.resource.data.status == 'draw'
+        && request.resource.data.winner == '';
+    }
+  }
+}
+`;
+}
+// ---- Optimized: flat layout, dynamic access, MapDiff, directional win split ----
+function assembleOptimized(config, lines) {
+    const { grid, hasGravity, hasLobby, collection } = config;
+    const totalCells = grid.cols * grid.rows;
+    const dirs = splitWinLinesByDirection(lines, grid.cols);
+    function dirWinFn(name, mark, dirLines) {
+        if (dirLines.length === 0)
+            return `    function ${name}(b) { return false; }`;
+        return `    function ${name}(b) {
+      return ${winCheckExpr(mark, dirLines, grid)};
+    }`;
+    }
+    const winFunctions = [
+        dirWinFn('wonHH', 'host', dirs.horizontal),
+        dirWinFn('wonHV', 'host', dirs.vertical),
+        dirWinFn('wonHD1', 'host', dirs.diagUp),
+        dirWinFn('wonHD2', 'host', dirs.diagDown),
+        dirWinFn('wonGH', 'guest', dirs.horizontal),
+        dirWinFn('wonGV', 'guest', dirs.vertical),
+        dirWinFn('wonGD1', 'guest', dirs.diagUp),
+        dirWinFn('wonGD2', 'guest', dirs.diagDown),
+    ].join('\n\n');
+    const commonMove = `request.auth != null
+        && resource.data.status == 'playing'
+        && (
+          (resource.data.currentTurn == 'host' && request.auth.uid == resource.data.host)
+          || (resource.data.currentTurn == 'guest' && request.auth.uid == resource.data.guest)
+        )
+        && (
+          (resource.data.currentTurn == 'host' && request.resource.data.currentTurn == 'guest')
+          || (resource.data.currentTurn == 'guest' && request.resource.data.currentTurn == 'host')
+        )
+        && request.resource.data.moveCount == resource.data.moveCount + 1
+        && request.resource.data.host == resource.data.host
+        && request.resource.data.guest == resource.data.guest`;
+    // Dynamic cell validation + MapDiff integrity
+    const dynamicPlacement = `&& resource.data[request.resource.data.lastMove] == ''
+        && request.resource.data[request.resource.data.lastMove] == resource.data.currentTurn
+        && request.resource.data.diff(resource.data).affectedKeys().hasOnly(
+            ['lastMove', 'currentTurn', 'moveCount', request.resource.data.lastMove]
+          )`;
+    const dynamicWinPlacement = `&& resource.data[request.resource.data.lastMove] == ''
+        && request.resource.data[request.resource.data.lastMove] == resource.data.currentTurn`;
+    return `rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+
+${winFunctions}
+
+    match /${collection}/{gameId} {
+      allow read: if request.auth != null;
+${lobbyRulesOptimized(hasLobby)}
+      // --- Normal move (flat layout + MapDiff integrity) ---
+      allow update: if ${commonMove}
+        ${dynamicPlacement}
+        && request.resource.data.status == 'playing'
+        && request.resource.data.winner == '';
+
+      // --- Winning move (host) ---
+      allow update: if ${commonMove}
+        ${dynamicWinPlacement}
+        && request.resource.data.status == 'won'
+        && request.resource.data.winner == 'host'
+        && (wonHH(request.resource.data) || wonHV(request.resource.data) || wonHD1(request.resource.data) || wonHD2(request.resource.data));
+
+      // --- Winning move (guest) ---
+      allow update: if ${commonMove}
+        ${dynamicWinPlacement}
+        && request.resource.data.status == 'won'
+        && request.resource.data.winner == 'guest'
+        && (wonGH(request.resource.data) || wonGV(request.resource.data) || wonGD1(request.resource.data) || wonGD2(request.resource.data));
+
+      // --- Draw ---
+      allow update: if ${commonMove}
+        && request.resource.data.moveCount == ${totalCells}
+        && request.resource.data.status == 'draw'
+        && request.resource.data.winner == '';
+    }
+  }
+}
+`;
+}
+// ---- Lobby rules ----
+function lobbyRules(hasLobby) {
+    if (!hasLobby)
+        return `
+      allow create: if request.auth != null
+        && request.resource.data.host == request.auth.uid
+        && request.resource.data.currentTurn == 'host'
+        && request.resource.data.status == 'playing'
+        && request.resource.data.winner == ''
+        && request.resource.data.moveCount == 0;
+`;
+    return `
+      allow create: if request.auth != null
+        && request.resource.data.host == request.auth.uid
+        && request.resource.data.guest == ''
+        && request.resource.data.currentTurn == 'host'
+        && request.resource.data.status == 'waiting'
+        && request.resource.data.winner == ''
+        && request.resource.data.moveCount == 0
+        && request.resource.data.lastCol == -1
+        && request.resource.data.lastRow == -1;
+
+      allow update: if request.auth != null
+        && resource.data.status == 'waiting'
+        && request.resource.data.status == 'playing'
+        && resource.data.guest == ''
+        && request.resource.data.guest == request.auth.uid
+        && request.auth.uid != resource.data.host
+        && request.resource.data.host == resource.data.host
+        && request.resource.data.currentTurn == resource.data.currentTurn
+        && request.resource.data.winner == resource.data.winner
+        && request.resource.data.moveCount == resource.data.moveCount
+        && request.resource.data.lastCol == resource.data.lastCol
+        && request.resource.data.lastRow == resource.data.lastRow
+        && request.resource.data.board == resource.data.board;
+
+      allow delete: if request.auth != null
+        && resource.data.status == 'waiting'
+        && request.auth.uid == resource.data.host;
+`;
+}
+function lobbyRulesOptimized(hasLobby) {
+    if (!hasLobby)
+        return `
+      allow create: if request.auth != null
+        && request.resource.data.host == request.auth.uid
+        && request.resource.data.currentTurn == 'host'
+        && request.resource.data.status == 'playing'
+        && request.resource.data.winner == ''
+        && request.resource.data.moveCount == 0;
+`;
+    return `
+      allow create: if request.auth != null
+        && request.resource.data.host == request.auth.uid
+        && request.resource.data.guest == ''
+        && request.resource.data.currentTurn == 'host'
+        && request.resource.data.status == 'waiting'
+        && request.resource.data.winner == ''
+        && request.resource.data.moveCount == 0
+        && request.resource.data.lastMove == '';
+
+      allow update: if request.auth != null
+        && resource.data.status == 'waiting'
+        && request.resource.data.status == 'playing'
+        && resource.data.guest == ''
+        && request.resource.data.guest == request.auth.uid
+        && request.auth.uid != resource.data.host
+        && request.resource.data.diff(resource.data).affectedKeys().hasOnly(['guest', 'status']);
+
+      allow delete: if request.auth != null
+        && resource.data.status == 'waiting'
+        && request.auth.uid == resource.data.host;
+`;
+}
+//# sourceMappingURL=assembler.js.map

package/dist/rules/generators/assembler.js.map

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

package/dist/rules/generators/expressions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Firestore rules expression generators for grid-based games.
+ *
+ * Each function returns a string that is a valid Firestore rules boolean expression.
+ * The expressions use parameter names (b, ob, nc, nr, mark) that must match
+ * the function signatures in the generated rules.
+ */
+import type { GridConfig } from './grid.js';
+/**
+ * Win detection: OR of all winning lines for a specific mark.
+ * Uses `b` as the board parameter name.
+ *
+ * Example output: (b.c0r0 == 'R' && b.c1r0 == 'R' && b.c2r0 == 'R' && b.c3r0 == 'R') || ...
+ */
+export declare function winCheckExpr(mark: string, lines: number[][], grid: GridConfig): string;
+/**
+ * Split win lines by direction for per-direction functions.
+ * Returns { horizontal, vertical, diagUp, diagDown }.
+ */
+export declare function splitWinLinesByDirection(lines: number[][], cols: number): {
+    horizontal: number[][];
+    vertical: number[][];
+    diagUp: number[][];
+    diagDown: number[][];
+};
+/**
+ * Gravity: per-column lowest-empty-row check.
+ * Uses `nc` (new col), `nr` (new row), `ob` (old board) as parameter names.
+ *
+ * For each column: if nc == col, verify nr is the lowest empty row.
+ */
+export declare function gravityExpr(grid: GridConfig): string;
+/**
+ * Board integrity: verify all non-move cells are unchanged.
+ * Uses `nc`, `nr`, `b` (new board), `ob` (old board) as parameter names.
+ *
+ * For each cell: either it's the move cell OR old == new.
+ */
+export declare function boardIntegrityExpr(grid: GridConfig): string;
+/**
+ * Cell-was-empty check: verify the cell at (nc, nr) was empty before the move.
+ * Uses `nc`, `nr`, `ob` (old board) as parameter names.
+ * For gravity games this is redundant (gravity already checks ob.cell == ''),
+ * but for non-gravity games it prevents overwriting occupied cells.
+ */
+export declare function cellEmptyExpr(grid: GridConfig): string;
+/**
+ * Placement: verify the cell at (nc, nr) has the correct mark.
+ * Uses `nc`, `nr`, `mark`, `b` (new board) as parameter names.
+ */
+export declare function placementExpr(grid: GridConfig): string;
+//# sourceMappingURL=expressions.d.ts.map

package/dist/rules/generators/expressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../../../src/rules/generators/expressions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAQtF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,IAAI,EAAE,MAAM,GACX;IAAE,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,CAkB5F;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAepD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAW3D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAQtD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAQtD"}