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

package/src/firestore/transactions.ts

@@ -1,20 +1,39 @@
+import { runSdkWrite } from '../sandbox/internal/sdk-write-activity.js';
+import { beginFirestoreGroupActivity } from './sdk-activity.js';
 /**
  * `pyric/firestore` — transactions + batched writes.
  *
  * `runTransaction` and `writeBatch`. Handles resolve a chainable bound to
  * the current user and freeze that identity for the duration.
  */
-import type { Transaction as ChainTransaction } from 'pyric/sandbox/admin-firestore';
+import type {
+  Transaction as ChainTransaction,
+  Query as ChainQuery,
+  AdminQuerySnapshot,
+} from 'pyric/sandbox/admin-firestore';
 
 import {
   targetOf,
   sandboxDb,
   tag,
+  converterOf,
+  type Target,
 } from './state.js';
-import type { Firestore, Transaction, TransactionOptions, WriteBatch } from './types.js';
+import { applyConverterToDocSnap, tagSnapshotRefs, wrapSandboxDocSnap } from './snapshots.js';
+import { requireDocumentData } from './internal/document-data.js';
+import type { DocumentData, DocumentReference, DocumentSnapshot, Firestore, FirestoreDataConverter, Transaction, TransactionOptions, WriteBatch } from './types.js';
 
 // ─── Transactions + batches ───────────────────────────────────────────
 
+/** Apply the model converter before the backing adapter captures document data. */
+function convertSetData(ref: DocumentReference<unknown>, data: unknown): DocumentData {
+  const converter = converterOf(ref);
+  const hasConverter = converter !== undefined && converter !== null;
+  let payload = data;
+  if (hasConverter) payload = converter.toFirestore(data);
+  return requireDocumentData(payload);
+}
+
 export async function runTransaction<R>(
   db: Firestore,
   fn: (tx: Transaction) => Promise<R> | R,
@@ -23,14 +42,75 @@ export async function runTransaction<R>(
   const target = targetOf(db);
   // For sandbox-live, the transaction runs under the auth captured at
   // `runTransaction` start and stays identity-stable until completion.
-  return sandboxDb(target).runTransaction(
-    fn as (tx: ChainTransaction) => Promise<R> | R,
-    options,
-  );
+  const database = sandboxDb(target);
+  return runSdkWrite(beginFirestoreGroupActivity(target, 'runTransaction'), () => database.runTransaction((backing) => {
+    const transaction: Transaction = {
+      get: modularTransactionRead(backing.get.bind(backing), database, target),
+      set(ref, data, options) {
+        const payload = convertSetData(ref, data);
+        backing.set(database.doc(ref.path), payload, options);
+        return transaction;
+      },
+      update(ref, data) {
+        backing.update(database.doc(ref.path), data);
+        return transaction;
+      },
+      delete(ref) {
+        backing.delete(database.doc(ref.path));
+        return transaction;
+      },
+    };
+    return fn(transaction);
+  }, options));
+}
+
+/** Normalize document results without moving reads outside the transaction. */
+function modularTransactionRead(read: ChainTransaction['get'], database: ReturnType<typeof sandboxDb>, target: Target): Transaction['get'] {
+  function get<T = DocumentData>(reference: DocumentReference<T>): Promise<DocumentSnapshot<T> & { exists(): boolean }>;
+  function get(query: ChainQuery): Promise<AdminQuerySnapshot>;
+  async function get<T>(reference: DocumentReference<T> | ChainQuery): Promise<(DocumentSnapshot<T> & { exists(): boolean }) | AdminQuerySnapshot> {
+    const readsQuery = 'where' in reference;
+    if (readsQuery) return read(reference);
+    const snapshot = await read(database.doc(reference.path));
+    const converter = converterOf(reference);
+    const hasConverter = converter !== undefined && converter !== null;
+    if (hasConverter) {
+      return applyConverterToDocSnap(snapshot, converter as FirestoreDataConverter<T>, target, 'document');
+    }
+    tagSnapshotRefs(snapshot, target);
+    return wrapSandboxDocSnap<T>(snapshot, target);
+  }
+  return get;
 }
 
 export function writeBatch(db: Firestore): WriteBatch {
   const target = targetOf(db);
-  const batch = sandboxDb(target).batch();
-  return tag(batch as unknown as object, target) as WriteBatch;
+  const database = sandboxDb(target);
+  const backing = database.batch();
+  let writes = 0;
+  let deletes = 0;
+  const batch: WriteBatch = {
+    set(ref, data, options) {
+      const payload = convertSetData(ref, data);
+      backing.set(database.doc(ref.path), payload, options);
+      writes++;
+      return batch;
+    },
+    update(ref, data) {
+      backing.update(database.doc(ref.path), data);
+      writes++;
+      return batch;
+    },
+    delete(ref) {
+      backing.delete(database.doc(ref.path));
+      deletes++;
+      return batch;
+    },
+    commit(options) {
+      return runSdkWrite(beginFirestoreGroupActivity(target, 'writeBatch.commit'),
+        () => backing.commit(options),
+        () => ({ documentWrites: writes, documentDeletes: deletes }));
+    },
+  };
+  return tag(batch, target);
 }

package/src/firestore/types.ts

@@ -17,9 +17,11 @@ import {
   type LintResult,
   type OrderDirection,
   type WhereFilterOp,
-  type WriteBatch as ChainWriteBatch,
-  type Transaction as ChainTransaction,
+  type Query as ChainQuery,
+  type AdminQuerySnapshot,
 } from 'pyric/sandbox/admin-firestore';
+import type { SetOptions } from './writes.js';
+import type { OperationOptions } from './sandbox/admin-compat/types.js';
 import type { AuthState, Sandbox, SandboxContext } from 'pyric/sandbox';
 import type { FirebaseApp } from '../app/types.js';
 import { TARGET_SYMBOL, type Target } from './state.js';
@@ -75,15 +77,21 @@ export type AppFirestore = Firestore & { readonly app: FirebaseApp };
 export interface DocumentReference<_T = DocumentData> {
   readonly id: string;
   readonly path: string;
+  withConverter<T, D extends DocumentData = DocumentData>(converter: FirestoreDataConverter<T, D>): DocumentReference<T>;
+  withConverter(converter: null): DocumentReference<DocumentData>;
 }
 /** A reference to a Firestore collection. Backend-opaque. */
-export interface CollectionReference<_T = DocumentData> {
+export interface CollectionReference<_T = DocumentData> extends Query<_T> {
   readonly id: string;
   readonly path: string;
+  withConverter<T, D extends DocumentData = DocumentData>(converter: FirestoreDataConverter<T, D>): CollectionReference<T>;
+  withConverter(converter: null): CollectionReference<DocumentData>;
 }
 /** A Firestore query (a collection ref or one with where/orderBy/limit applied). */
 export interface Query<_T = DocumentData> {
   readonly _isQuery?: true;
+  withConverter<T, D extends DocumentData = DocumentData>(converter: FirestoreDataConverter<T, D>): Query<T>;
+  withConverter(converter: null): Query<DocumentData>;
 }
 export interface SnapshotMetadata {
   readonly fromCache: boolean;
@@ -113,8 +121,21 @@ export interface QuerySnapshot<T = DocumentData> {
   readonly docs: ReadonlyArray<QueryDocumentSnapshot<T>>;
   readonly metadata: SnapshotMetadata;
 }
-export interface WriteBatch extends ChainWriteBatch {}
-export interface Transaction extends ChainTransaction {}
+export interface WriteBatch {
+  set<T = DocumentData>(ref: DocumentReference<T>, data: T, options?: SetOptions): WriteBatch;
+  update(ref: DocumentReference, data: DocumentData): WriteBatch;
+  delete(ref: DocumentReference): WriteBatch;
+  /** Retains the existing sandbox-only per-commit auth override. */
+  commit(options?: OperationOptions): Promise<void>;
+}
+export interface Transaction {
+  get<T = DocumentData>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T> & { exists(): boolean }>;
+  /** Existing sandbox query extension; modular Firebase transactions read documents. */
+  get(query: ChainQuery): Promise<AdminQuerySnapshot>;
+  set<T = DocumentData>(ref: DocumentReference<T>, data: T, options?: SetOptions): Transaction;
+  update(ref: DocumentReference, data: DocumentData): Transaction;
+  delete(ref: DocumentReference): Transaction;
+}
 export type Unsubscribe = () => void;
 
 export const CACHE_SIZE_UNLIMITED = -1;

package/src/firestore/vector-value.ts

@@ -0,0 +1,54 @@
+import { registerQueryValue } from './sandbox/query-value-registry.js';
+
+export class VectorValue {
+  private constructor(readonly _values: number[]) {
+    registerQueryValue(this, Object.freeze({
+      type: 'vector',
+      values: Object.freeze(_values.slice()),
+    }), () => new VectorValue(_values.slice()));
+  }
+
+  static create(values: number[]): VectorValue {
+    const hasNonNumericComponent = !values.every((value) => typeof value === 'number');
+    if (hasNonNumericComponent) {
+      throw new TypeError('Vector values must be numbers.');
+    }
+    return new VectorValue(values.slice());
+  }
+
+  toArray(): number[] {
+    return this._values.slice();
+  }
+
+  isEqual(other: VectorValue): boolean {
+    const hasDifferentType = !(other instanceof VectorValue);
+    if (hasDifferentType) return false;
+    const theirs = other._values;
+    return theirs !== undefined
+      && this._values.length === theirs.length
+      && this._values.every((value, index) => value === theirs[index]);
+  }
+
+  toJSON(): object {
+    return {
+      type: 'firestore/vectorValue/1.0',
+      vectorValues: this.toArray(),
+    };
+  }
+
+  static fromJSON(json: object): VectorValue {
+    const value = json as { readonly type?: unknown; readonly vectorValues?: unknown };
+    const hasUnexpectedMarker = value.type !== 'firestore/vectorValue/1.0';
+    const isInvalidVectorJson = hasUnexpectedMarker
+      || !Array.isArray(value.vectorValues)
+      || !value.vectorValues.every((entry) => typeof entry === 'number');
+    if (isInvalidVectorJson) {
+      throw new TypeError('Invalid VectorValue JSON value.');
+    }
+    return VectorValue.create(value.vectorValues);
+  }
+}
+
+export function vector(values: number[] = []): VectorValue {
+  return VectorValue.create(values);
+}

package/src/firestore/writes.ts

@@ -5,6 +5,8 @@
  * `SetOptions` shape. Operations route through the sandbox's chainable
  * adapter, running any converter on `setDoc` / `addDoc`.
  */
+import { runSdkWrite } from '../sandbox/internal/sdk-write-activity.js';
+import { beginFirestoreActivity } from './sdk-activity.js';
 import type {
   DocumentData,
   SetOptions as ChainSetOptions,
@@ -64,16 +66,18 @@ export async function setDoc<T = DocumentData>(
   options?: SetOptions,
 ): Promise<void> {
   const target = targetOf(ref);
-  const conv = converterOf(ref);
-  const payload = conv
-    ? (conv as FirestoreDataConverter<T>).toFirestore(data)
-    : (data as unknown as DocumentData);
-  return clientStateFor(target).runWrite(
-    () => withFirestoreFirebaseError(() =>
-      chainDocFor(target, ref).set(payload, options as ChainSetOptions | undefined),
-    ),
-    ref.path,
-  );
+  return runSdkWrite(beginFirestoreActivity(target, ref, 'setDoc', 'operation'), async () => {
+    const conv = converterOf(ref);
+    const payload = conv
+      ? (conv as FirestoreDataConverter<T>).toFirestore(data)
+      : (data as unknown as DocumentData);
+    return clientStateFor(target).runWrite(
+      () => withFirestoreFirebaseError(() =>
+        chainDocFor(target, ref).set(payload, options as ChainSetOptions | undefined),
+      ),
+      ref.path,
+    );
+  });
 }
 
 /**
@@ -86,18 +90,22 @@ export async function setDoc<T = DocumentData>(
  */
 export async function updateDoc(ref: DocumentReference, data: DocumentData): Promise<void> {
   const target = targetOf(ref);
-  return clientStateFor(target).runWrite(
-    () => withFirestoreFirebaseError(() => chainDocFor(target, ref).update(data)),
-    ref.path,
-  );
+  return runSdkWrite(beginFirestoreActivity(target, ref, 'updateDoc', 'operation'), async () => {
+    return clientStateFor(target).runWrite(
+      () => withFirestoreFirebaseError(() => chainDocFor(target, ref).update(data)),
+      ref.path,
+    );
+  });
 }
 
 export async function deleteDoc(ref: DocumentReference): Promise<void> {
   const target = targetOf(ref);
-  return clientStateFor(target).runWrite(
-    () => withFirestoreFirebaseError(() => chainDocFor(target, ref).delete()),
-    ref.path,
-  );
+  return runSdkWrite(beginFirestoreActivity(target, ref, 'deleteDoc', 'operation'), async () => {
+    return clientStateFor(target).runWrite(
+      () => withFirestoreFirebaseError(() => chainDocFor(target, ref).delete()),
+      ref.path,
+    );
+  });
 }
 
 export async function addDoc<T = DocumentData>(
@@ -105,33 +113,35 @@ export async function addDoc<T = DocumentData>(
   data: T,
 ): Promise<DocumentReference<T>> {
   const target = targetOf(coll);
-  const conv = converterOf(coll);
-  const payload = conv
-    ? (conv as FirestoreDataConverter<T>).toFirestore(data)
-    : (data as unknown as DocumentData);
-  const ref = await clientStateFor(target).runWrite(async () => {
-    const created = await withFirestoreFirebaseError(() => chainCollFor(target, coll).add(payload));
-    clientStateFor(target).cachePath(created.path);
-    return created;
-  });
-  const absPath = (ref as unknown as { path: string }).path;
-  const tagged = tagSandboxRef(
-    ref as object,
-    target,
-    (fresh) => fresh.doc(absPath) as unknown as object,
-  );
-  registerActivityValue(tagged, boundedActivityIdentity('reference', absPath));
-  registerReferenceQueryValue(tagged, absPath, target, tagged);
-  if (conv) {
-    const shell = buildSandboxShell(
-      tagged as { id: string; path: string },
+  return runSdkWrite(beginFirestoreActivity(target, coll, 'addDoc', 'operation'), async () => {
+    const conv = converterOf(coll);
+    const payload = conv
+      ? (conv as FirestoreDataConverter<T>).toFirestore(data)
+      : (data as unknown as DocumentData);
+    const ref = await clientStateFor(target).runWrite(async () => {
+      const created = await withFirestoreFirebaseError(() => chainCollFor(target, coll).add(payload));
+      clientStateFor(target).cachePath(created.path);
+      return created;
+    });
+    const absPath = (ref as unknown as { path: string }).path;
+    const tagged = tagSandboxRef(
+      ref as object,
       target,
-      conv,
+      (fresh) => fresh.doc(absPath) as unknown as object,
     );
-    copyQueryValueRegistration(tagged, shell);
-    return shell as DocumentReference<T>;
-  }
-  return tagged as DocumentReference<T>;
+    registerActivityValue(tagged, boundedActivityIdentity('reference', absPath));
+    registerReferenceQueryValue(tagged, absPath, target, tagged);
+    if (conv) {
+      const shell = buildSandboxShell(
+        tagged as { id: string; path: string },
+        target,
+        conv,
+      );
+      copyQueryValueRegistration(tagged, shell);
+      return shell as DocumentReference<T>;
+    }
+    return tagged as DocumentReference<T>;
+  });
 }
 
 import { writeBatch } from './transactions.js';

package/src/functions/events.ts

@@ -0,0 +1,27 @@
+/**
+ * What the Functions trigger runtime puts on the sandbox event stream.
+ *
+ * The runtime itself lives in `@pyric/cli` because it loads a project's own
+ * trigger module from disk. The event vocabulary lives here, beside every
+ * other service's, because the sandbox core derives the stream's service union
+ * from these records and `@pyric/cli` depends downward on `pyric`.
+ *
+ * This file is not part of the deferred `pyric/functions` mirror beside it,
+ * which stands in for `firebase/functions` callables. It is data, and the
+ * deferred barrel does not re-export it.
+ */
+import type { ServiceEventRecord } from '../sandbox/types/service-event-record.js';
+
+export const FUNCTIONS_EVENT_RECORD = {
+  service: 'functions',
+  operations: ['trigger_discovered', 'handler_fired', 'execution_finished'],
+  target: {
+    name: 'ref',
+    description:
+      "The trigger's reference pattern on discovery, and the synthetic event's concrete path once a handler fires.",
+    always: false,
+  },
+} as const satisfies ServiceEventRecord;
+
+/** Every operation the Functions trigger runtime emits. */
+export type FunctionsEventOperation = (typeof FUNCTIONS_EVENT_RECORD)['operations'][number];

package/src/messaging/broker/broker.test.ts

@@ -258,3 +258,117 @@ describe('messaging broker — typed sandbox events (tracing consumes the stream
     for (const event of events) expect(event.service).toBe('messaging');
   });
 });
+
+describe('messaging broker, registered tokens and their topics', () => {
+  it('lists every minted token with its state and topic membership', () => {
+    const broker = new MessagingBroker();
+    const a = broker.getTokenFor('reg-a');
+    const b = broker.getTokenFor('reg-b');
+    broker.subscribeToTopic([a], 'news');
+    broker.subscribeToTopic([a, b], 'sports');
+
+    const listed = broker.tokens();
+    expect(listed.map((entry) => entry.token).sort()).toEqual([a, b].sort());
+
+    const entryA = listed.find((entry) => entry.token === a)!;
+    expect(entryA.state).toBe('active');
+    expect(entryA.topics.sort()).toEqual(['news', 'sports']);
+
+    const entryB = listed.find((entry) => entry.token === b)!;
+    expect(entryB.topics).toEqual(['sports']);
+  });
+
+  it('lists a subscribed token this sandbox never minted, state unknown', () => {
+    const broker = new MessagingBroker();
+    const foreign = 'foreign-device-01:APA91bForeignSuffix';
+    broker.subscribeToTopic([foreign], 'alerts');
+
+    const entry = broker.tokens().find((candidate) => candidate.token === foreign);
+    expect(entry).toBeDefined();
+    expect(entry!.state).toBe('unknown');
+    expect(entry!.topics).toEqual(['alerts']);
+  });
+
+  it('reports a deleted token as unregistered, with its subscriptions cleared by unsubscribe', () => {
+    const broker = new MessagingBroker();
+    const token = broker.getTokenFor('reg-c');
+    broker.subscribeToTopic([token], 'news');
+    broker.deleteTokenFor('reg-c');
+
+    const entry = broker.tokens().find((candidate) => candidate.token === token)!;
+    expect(entry.state).toBe('unregistered');
+  });
+});
+
+describe('messaging broker, the delivery history', () => {
+  it('reads the delivery history off the sandbox event stream', () => {
+    const sandbox = initializeSandbox();
+    const broker = new MessagingBroker({ sandbox });
+    broker.setClientVisibility('window-0', 'visible');
+    broker.deliver({ data: { k: 'v' } });
+
+    const delivered = sandbox
+      .history()
+      .filter(
+        (event) =>
+          event.kind === 'service_mutation'
+          && event.service === 'messaging'
+          && event.op === 'message_delivered',
+      ) as Array<{ at: number; detail?: Record<string, unknown> }>;
+    expect(delivered.length).toBe(1);
+
+    const [entry] = broker.deliveries();
+    expect(entry!.messageId).toBe(delivered[0]!.detail!.messageId as string);
+    expect(entry!.at).toBe(delivered[0]!.at);
+    expect(entry!.payload).toEqual(delivered[0]!.detail!.payload as never);
+  });
+
+  it('records a topic send as delivered, foreground or background, per the visibility rule', () => {
+    const broker = new MessagingBroker({ sandbox: initializeSandbox() });
+    const token = broker.getTokenFor('reg-1');
+    broker.subscribeToTopic([token], 'news');
+
+    broker.setClientVisibility('window-0', 'hidden');
+    broker.send({ topic: 'news', data: { k: 'v1' } });
+
+    broker.setClientVisibility('window-0', 'visible');
+    broker.send({ topic: 'news', data: { k: 'v2' } });
+
+    const log = broker.deliveries();
+    expect(log.length).toBe(2);
+    expect(log[0]!.route).toBe('background');
+    expect(log[0]!.handled).toBe(false);
+    expect(log[1]!.route).toBe('foreground');
+  });
+
+  it('records a delivery with no matching recipient as unhandled, and never delivers unrouted sends', () => {
+    const broker = new MessagingBroker({ sandbox: initializeSandbox() });
+    const token = broker.getTokenFor('reg-1');
+    broker.setClientVisibility('window-0', 'visible');
+    broker.onForegroundMessage(() => {});
+
+    // A send to an empty topic reaches no recipient, so route() never runs and
+    // the delivery log stays empty for it.
+    broker.send({ topic: 'nobody-subscribed' });
+    expect(broker.deliveries().length).toBe(0);
+
+    // A direct `deliver()` call always routes, so it always logs, handled or not.
+    broker.deliver({ data: { k: 'v' } });
+    expect(broker.deliveries().length).toBe(1);
+    expect(broker.deliveries()[0]!.handled).toBe(true);
+
+    void token;
+  });
+
+  it('filters by since, the cursor the deliveries method reads', () => {
+    const broker = new MessagingBroker({ sandbox: initializeSandbox() });
+    broker.deliver({ data: { seq: '1' } });
+    const cursor = Date.now();
+    broker.deliver({ data: { seq: '2' } });
+
+    const after = broker.deliveries(cursor);
+    expect(after.length).toBeGreaterThanOrEqual(1);
+    expect(after.every((entry) => entry.at >= cursor)).toBe(true);
+    expect(broker.deliveries().length).toBe(2);
+  });
+});