@tech4good/platform-data 0.1.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/FUTURE-WORK.md ADDED
@@ -0,0 +1,328 @@
1
+ # Platform-data: decisions, watch points and future work
2
+
3
+ Maintainer handoff: September 10, 2026. This records the accepted design and
4
+ proposals for later work. It does not authorize implementing every proposal or
5
+ claim that every risk below is an observed defect.
6
+
7
+ Read [EXTRACTION-CHANGES.md](EXTRACTION-CHANGES.md) for the implementation history,
8
+ [MIGRATION.md](MIGRATION.md) before adopting it, and [BACKENDS.md](BACKENDS.md)
9
+ before introducing another backend. Source paths in this guide refer to the
10
+ repository checkout, not files included in the npm tarball.
11
+
12
+ ## Decisions to preserve
13
+
14
+ 1. There is one shared root entity store per collection. Components select from
15
+ that common state and share matching listeners. Independent instances of the
16
+ same collection store are not the intended model.
17
+ 2. Global stream teardown stops listeners and nested observers. It preserves
18
+ records and load history. An explicit `store.reset()` clears that store's
19
+ records and only its collection's history. `clearCache()` is an explicit
20
+ global listener/history invalidation, not the normal logout operation.
21
+ 3. The app chooses auth/profile/session state to reset. Generated auth resets
22
+ UserStore, available UserContextStore and the telemetry session identifier.
23
+ Other domain stores retain records/history. Entity discovery must not acquire
24
+ an implicit reset-all policy.
25
+ 4. Ordinary pending reads and writes may finish after teardown/reset. General
26
+ session epochs and automatic store resets were deliberately removed. Keep
27
+ listener-specific teardown guards; they solve a different problem.
28
+ 5. Stored records require identity, shared timestamps and soft-delete metadata.
29
+ Core and `/testing` remain Firebase-free. Firestore owns SDK conversion.
30
+ 6. Runtime logging is shared through platform-logging. Auth flows, navigation,
31
+ domain policies, rules and deletion graphs remain app-owned today.
32
+
33
+ These are product/architecture choices made during review, not accidental
34
+ omissions to silently "fix" in the next refactor. Revisit them with a concrete
35
+ use case or reproducible failure.
36
+
37
+ ## 1. Monitor the chosen session cleanup policy
38
+
39
+ ### Why we chose it
40
+
41
+ Mentor's July 28 `5b132ce` commit documents stopping old credential-bound
42
+ listeners to prevent denied reads after sign-out/deletion. Its reset list did
43
+ cover all stores then present; later chat entities simply were not added. The
44
+ history did not establish a separate incident requiring all local records to be
45
+ cleared. The user chose explicit auth-state reset and retained domain data, as
46
+ with ordinary navigation, while retaining **global** listener teardown.
47
+
48
+ Retained load history is paired with retained records. Clearing only the history
49
+ of reset stores avoids forcing full reloads in otherwise retained stores. This
50
+ assumes those records and cutoffs are still appropriate for the next use of the
51
+ query. A selector chooses from local data; it is not an authentication filter.
52
+
53
+ ### Concrete watch points
54
+
55
+ | Situation | Current behavior / uncertainty | What to check before changing policy |
56
+ | --- | --- | --- |
57
+ | Account A signs out, then B signs in without a page reload | Domain records remain in memory. There is no claim that every selector in every app excludes A's retained records. | Exercise real app screens and root-level components; inspect records rendered before and after B's load. Check account/workspace predicates and auth-gated display. Capture an actual incorrect result before choosing a targeted reset or different cache scope. |
58
+ | A signed-out/public screen needs cached data | Retention intentionally permits this. Clearing every store would change that behavior. | Include public/offline-oriented flows in adoption tests so an auth change does not erase deliberately reusable state. |
59
+ | An ordinary read or optimistic write finishes after logout | It can apply records/history or rollback local state; it is not just a possible console error. | Delay the operation, sign out, then observe the next screen and next account. If results are wrong, determine which auth-sensitive operation needs guarding instead of reintroducing a blanket cancellation system. |
60
+ | The effective dataset changes while the collection/query key stays the same | Retained incremental cutoffs can be inappropriate after an app changes account/workspace scope or query meaning. | Reproduce with the app's actual filters and authorization model. Decide whether that transition should reset a particular store, explicitly clear history, or use a distinct query. Rules should not be assumed to filter a broad query for the caller. |
61
+ | Another tab signs out, or auth identity changes externally | Generated cleanup is called by explicit logout/guest-deletion flows. The auth observer is not yet a general cleanup coordinator for every external transition. | Test externally observed sign-out and direct UID switches, including active profile provisioning and root listeners. This is a requirement for a future auth package. |
62
+ | `store.reset()` is called while its listeners remain active | Reset does not unsubscribe. Records may return on updates, and a matching cached connection may not resend an initial snapshot merely because local records were emptied. | Normal auth flow tears down first. If another feature needs a standalone reset-and-reload operation, define and test that lifecycle explicitly. |
63
+ | `store.init()` replaces an already-used store | It replaces records without resetting history. It is not a complete cache-invalidation API. | Check any use outside initial setup/tests. If replacement must invalidate cutoffs, do so explicitly or design a dedicated operation. |
64
+
65
+ No verified cross-account UI incident was found in the review that led to this
66
+ decision. That is a validation limit, not proof that all app selectors are safe.
67
+ Firebase SDK persistence, mock persistence and backend records have separate
68
+ lifetimes; clearing an NgRx store does not clear them.
69
+
70
+ ### Adoption scenarios to retain as regression coverage
71
+
72
+ - Normal logout and guest deletion: all active and retiring listeners close;
73
+ user/profile/session state resets; intended domain records and both kinds of
74
+ domain load history survive.
75
+ - Reset one collection, then load it and an untouched collection: the reset
76
+ collection loads fully; the untouched collection continues incrementally.
77
+ - A root-provided store used by two components shares data/listeners. Leaving
78
+ one component does not interrupt the other; returning during the grace period
79
+ reuses the connection.
80
+ - Delayed reads and profile provisioning around sign-out, a second sign-in,
81
+ logout without routing, and any public page that can remain mounted.
82
+ - External auth changes and browser restoration, with the app's actual cache
83
+ configuration and selector predicates.
84
+
85
+ The package and generated-app tests cover the first behaviors, including an
86
+ ordinary late read. Actual MathPets/Mentor account-switch screens and external
87
+ auth transitions still need application-level validation.
88
+
89
+ ## 2. Remaining data-engine questions
90
+
91
+ These are boundaries to investigate when an application needs them, not a
92
+ commitment to redesign the entire synchronization system now.
93
+
94
+ ### Keep later refactors separate from extraction
95
+
96
+ The first-extraction review restored the original selector ID branches, separate
97
+ batch modes, explicit Firestore option/write branches, mock snapshot/pairwise
98
+ stream flow, and direct ordinary mock writes. See the review table in
99
+ [EXTRACTION-CHANGES.md](EXTRACTION-CHANGES.md#extraction-review-preserve-the-original-flow)
100
+ for the original-to-package mapping and reasons for the differences retained.
101
+
102
+ Do not consolidate these branches or replace them with a new pipeline merely
103
+ while moving files or adopting the package. A later refactor can be worthwhile,
104
+ but give it its own commit, explain its benefit, and compare behavior and work
105
+ performed on large stores. In particular, keep ID lookup from enumerating the
106
+ whole store, and avoid whole-collection batch staging for ordinary mock writes.
107
+
108
+ Preserve the original comments' explanations, examples and tradeoffs as well as
109
+ the code's flow. For example, the optional __hashtagId query explains why an
110
+ undefined filter is ignored; replacing it with "ignore optional operands" loses
111
+ the reason and the concrete use case. When moving code, move that context with it.
112
+ If behavior changed, update the specific claim while retaining the useful example
113
+ and explaining the new behavior. Do not copy obsolete limitations as current facts.
114
+
115
+ ### Optional filters and empty `in` lists
116
+
117
+ Decision from the selector/load review: **keep the existing nested-load rule**
118
+ in `processLoadQueries`. If any filter in a nested query contains `in []`, do
119
+ not call `store.load()` for that query. Other nested queries still run. This
120
+ avoids sending the empty `in` request to Firestore. The guard remains in
121
+ `packages/data/src/query-descriptors.ts`; it was present before extraction.
122
+
123
+ Keep these three behaviors distinct:
124
+
125
+ - An undefined filter value is intentionally ignored for optional relationships.
126
+ The other filters still apply. If none remain, selection includes all active
127
+ records already in the store.
128
+ - An empty `in` list makes the nested-load helper skip the **entire query**.
129
+ It does not clear existing records or establish that the store has no matches.
130
+ - The current local selector treats `in []` as matching no records. The original
131
+ selector discarded that filter instead. The ID lookup fix did not change this
132
+ separate selection policy; any further change needs an explicit decision.
133
+
134
+ Watch for a page assuming a skipped load clears old related data, or treating
135
+ "nothing was loaded" as proof that no related records exist. Also check callers
136
+ that build ID lists from optional relationships: ignoring one filter and
137
+ skipping an entire query have different effects when other filters are present.
138
+ Reproduce with already-cached records and multiple nested queries before changing
139
+ these rules. Existing coverage now checks that an empty-list query is skipped
140
+ while a separate valid query still runs. Do not remove the load guard merely to
141
+ make these different operations behave alike.
142
+
143
+ ### Incremental loading and query membership
144
+
145
+ The existing algorithm uses timestamp cutoffs and soft-deleted records. Review
146
+ client/server clock differences, timestamp precision, writes at a cutoff and
147
+ concurrent changes when diagnosing missed updates. Hard deletion leaves no
148
+ tombstone for a later delta load. A record can also leave a filtered/limited
149
+ query without being globally deleted. Query membership and global entity
150
+ existence are different concepts; any new limited-query or backend behavior
151
+ needs tests for that distinction.
152
+
153
+ Do not equate an `await store.stream(...)` registration or its loading flag
154
+ with a guarantee that all initial backend snapshots and nested streams have
155
+ arrived. If a feature needs explicit readiness, define that contract and error
156
+ state before using it in guards or navigation. Nested failures are available
157
+ through `CachedListenersService.errors$`; apps may need a visible retry/error
158
+ experience. Automatic reconnection/backoff is not currently supplied by that API.
159
+
160
+ ### Writes, rollback and Undo
161
+
162
+ Reverse-order compensation fixes ordering within a write operation. It does
163
+ not resolve overlapping optimistic operations on the same entity or conflicts
164
+ with another client's newer changes. Undo is a new write and can fail. Revisit
165
+ version checks, conflict behavior or operation serialization only with a concrete
166
+ consumer and tests for dependent/overlapping writes.
167
+
168
+ A post-commit feedback/local-patch error can reject after persistence succeeded.
169
+ The coordinator avoids rolling back committed optimistic data, but the caller
170
+ may still interpret rejection as "nothing saved" and retry. If observed, separate
171
+ persisted-write success from local/feedback failure in the public result contract.
172
+ Do not implement blind write retries without considering duplicate operations.
173
+
174
+ ### Mock and adapter parity
175
+
176
+ Mocks cover the supported query/write behavior, not all Firestore semantics.
177
+ When adding operators, dotted-field updates, transforms, cursor types or complex
178
+ SDK values, compare local selectors, mock reads/writes and the real adapter.
179
+ Use focused emulator cases for adapter behavior and real index validation where
180
+ needed; passing mock tests alone is insufficient.
181
+
182
+ Persistence may eventually need an explicit seed/schema version and migration
183
+ policy. Review cross-tab changes and storage clearing as well as malformed data;
184
+ the current fallback is not a general migration system. Keep browser-storage
185
+ ownership/lifetime explicit and keep production fixtures out of bundles.
186
+
187
+ ### Contracts and external writers
188
+
189
+ Required TypeScript metadata does not validate existing documents, Cloud
190
+ Functions, imports or administrative writes. Check that they preserve `_createdAt`,
191
+ advance `_updatedAt` and use `_deleted` consistently. Add a validation/migration
192
+ tool if real data warrants it, rather than silently inventing missing history.
193
+
194
+ Some inherited adapter/query internals still use `any`. Tighten those contracts
195
+ incrementally with public consumer type tests; avoid imposing an exhaustive
196
+ application entity union on the library again. Keep the no-Firebase core tests
197
+ and timestamp round-trip tests whenever dependencies or public values change.
198
+
199
+ ## 3. Future auth/profile package
200
+
201
+ This is proposed work, **not an implemented package/API**. The detailed research
202
+ is in `docs-plans/platform-auth-and-onboarding-extraction.md` in the repository.
203
+ The working package name is `@tech4good/platform-auth`; proposed `/profiles`,
204
+ `/firebase` and `/testing` paths would be secondary entry points released with it.
205
+
206
+ The user wants profile assurance to be standard: an authenticated session should
207
+ resolve its profile, creating one if necessary. New profiles should default to
208
+ non-admin status while allowing app-specific fields/defaults. Existing profiles
209
+ must not have roles, consent or access state overwritten by new-user defaults.
210
+
211
+ Recommended responsibilities:
212
+
213
+ | Shared | App-owned |
214
+ | --- | --- |
215
+ | Session model, auth adapter contract, restoration and sign-in/link/sign-out operations | Which sign-in choices appear on each entry screen |
216
+ | Profile assurance, configurable new-profile factory and reconciliation policies | Domain profile fields, intentional role transitions and authorization |
217
+ | Coordination of auth notifications, provisioning, readiness, errors/retry and teardown | Guards, routes, return destinations and ordering of onboarding steps |
218
+ | Firebase adapter and auth simulator using the same lifecycle | Firebase project configuration and test personas |
219
+ | Data-integration cleanup hook plus explicit auth/profile reset | Extra session/analytics state and any evidence-based domain invalidation |
220
+ | An injectable account-deletion operation | Server-side deletion graph and guest save/delete prompts |
221
+
222
+ The current local Firebase and mock facades remain because they still implement
223
+ these app policies. Eventually consumers should use separate data and auth
224
+ contracts; data must not depend back on auth. A combined database facade can
225
+ delegate temporarily during migration.
226
+
227
+ Important design requirements:
228
+
229
+ - Share the profile algorithm across real and mock persistence. Custom factories
230
+ should not require reimplementing ordinary profile assurance.
231
+ - Use an atomic ensure/create-if-missing persistence contract. Current `DataAccess`
232
+ does not expose that capability; a read followed by an add is not sufficient
233
+ for concurrent tabs. Keep retryable factories free of external side effects.
234
+ - Distinguish authentication success from profile readiness/failure. A failed
235
+ profile write should leave a retryable state, not a guard waiting forever or
236
+ an unnecessary attempt to recreate an authenticated account.
237
+ - Coordinate explicit and observed sign-out, UID changes, restored sessions and
238
+ delayed profile operations. Target stale **auth/profile** work without turning
239
+ every domain store read into a session-cancelled operation.
240
+ - Preserve Google/anonymous sign-in, email-link sign-in, account linking and
241
+ their distinct outcomes. Configure callback URLs and storage namespaces;
242
+ return credential conflicts for the app to resolve rather than merging accounts.
243
+ - Keep teardown separate from domain retention. Test preserved domain records
244
+ and history, not a removed automatic store registry/reset-all assumption.
245
+
246
+ Start with configurable profile assurance, then auth lifecycle/adapters, then
247
+ update generated app composition. Test standard lab defaults and Mentor's role
248
+ behavior, repeated/concurrent provisioning, missing related records, offline or
249
+ denied writes, email callbacks, linking conflicts and external auth transitions.
250
+
251
+ ## 4. Shared consent and other UI flows
252
+
253
+ Proposed `@tech4good/platform-onboarding` can distribute actual standalone Angular
254
+ components, templates and styles, with `/material` for the default UI. An app
255
+ imports them and receives package-owned fixes on dependency upgrade/rebuild.
256
+ Schematics should generate host/configuration code, not another copied consent
257
+ implementation.
258
+
259
+ Begin with consent rather than a universal configurable onboarding wizard:
260
+
261
+ - Share checkbox validation, pending state, duplicate-submit prevention,
262
+ already-accepted state and error/retry behavior. Offer a controller for apps
263
+ needing a different layout and a Material component for the common case.
264
+ - Customize text/options through typed inputs, richer sections through content
265
+ slots/templates, and appearance through supported theme tokens. App-replaced
266
+ templates stay app-owned and do not automatically receive package fixes.
267
+ - Await a save callback/service and report completion only after it succeeds.
268
+ Keep navigation separate so a routing failure is not reported as failed
269
+ persistence. Do not assume emitting an output awaits the parent's async save.
270
+ - Leave access-state transitions to configuration: MathPets/schematics currently
271
+ advance to `DONE`, while Mentor advances only from `CONSENT`.
272
+ - Keep consent document identity/version and acceptance policy separate from
273
+ npm version. A UI bug fix should not silently require everyone to consent again.
274
+
275
+ Try a built tarball in disposable MathPets and Mentor apps to demonstrate both
276
+ shared fixes and preserved local policy. Consent is a useful independent UI
277
+ pilot and need not wait for a complete auth migration.
278
+
279
+ ## 5. Future databases
280
+
281
+ The shared timestamp value removes a core dependency on Firebase; it does not
282
+ by itself make the query, write and realtime contracts database-independent.
283
+ No Supabase or PostgreSQL adapter has been implemented.
284
+
285
+ [BACKENDS.md](BACKENDS.md) records the deferred design: timestamp mapping and
286
+ precision, server-authored metadata, query capabilities, change cursors,
287
+ realtime initial snapshots plus changes, writes/Undo, and app-owned schema/auth.
288
+ Use it as the starting point. Validate a small real consumer before broadening
289
+ `DataAccess` or promising that another database behaves exactly like Firestore.
290
+
291
+ ## 6. Next adoption and release work
292
+
293
+ 1. Rebuild the exact candidate and install its tarball in a disposable app first.
294
+ Install a matching platform-logging version too. Core, Firestore, testing and
295
+ Material entry points are one data release; logging is a separate package.
296
+ 2. Follow the migration guide on a MathPets or Mentor branch. Earlier disposable
297
+ trials predate some final changes; they are not proof the current real apps
298
+ have adopted platform-data. Check timestamps, complete metadata/fixtures,
299
+ direct imports, providers, entity generation and app-specific auth cleanup.
300
+ 3. Run package tests and the application's lint/build/tests/rules/index and
301
+ entity-registry checks. Exercise the session scenarios above in the actual
302
+ application. Firebase emulator success does not prove production composite
303
+ indexes exist.
304
+ 4. Inspect the production bundle for mock seeds and check the installed package
305
+ exports/peer dependencies. Test a real tarball rather than relying solely on
306
+ workspace or npm-link resolution.
307
+ 5. Follow the README's release instructions. Publish logging before a data
308
+ version that requires it, use the intended alpha tag, and publish the built
309
+ data `dist` directory. Inspect current manifests rather than assuming the
310
+ version in this dated note is still current.
311
+
312
+ There is no automatic commit, publish, deployment or real-app migration implied
313
+ by this handoff. Add release notes for actual changes after this initial record.
314
+
315
+ ## For the next agent
316
+
317
+ Start with the README, these two handoff documents and MIGRATION.md. Inspect
318
+ current source and git status, including untracked package files: the initial
319
+ extraction was documented before its commit. Use baseline `fda18e3` for the
320
+ original copied templates and the named Mentor commits for the teardown history.
321
+
322
+ The repository's chronological extraction plan contains superseded experiments
323
+ and multiple validation milestones. Prefer the final decisions here when they
324
+ conflict with an earlier paragraph. Do not treat disposable test artifacts under
325
+ `/private/tmp` as durable evidence or assume older passing counts validate a new
326
+ artifact. Record new reproduction cases, decisions and validation with the change
327
+ that needs them. In particular, do not silently restore reset-all registration,
328
+ multi-instance store ownership or general pending-read/write cancellation.
package/MIGRATION.md ADDED
@@ -0,0 +1,227 @@
1
+ # Migrating an existing lab application
2
+
3
+ Use a branch or disposable copy and an installed package tarball first. Do not
4
+ rerun `ng-add` over an existing application: authentication policy, profiles,
5
+ entity registrations, routes and configuration differ between the apps.
6
+
7
+ Before migrating, read [changes beyond extraction](EXTRACTION-CHANGES.md) for
8
+ behavior changes and [future work/watch points](FUTURE-WORK.md) for the accepted
9
+ store-retention policy and application scenarios that still need validation.
10
+
11
+ ## 1. Preserve app entities and domain code
12
+
13
+ Keep app entity interfaces, mock seeds, `LoadX`/`StreamX` classes, and domain stores.
14
+ Change their shared imports to the package directly:
15
+
16
+ ```ts
17
+ import {
18
+ withEntitiesAndDBMethods, withEntitiesAndSelectMethods,
19
+ selectEntities, entityInQueryResults, processLoadQueries,
20
+ EntityLoadQuery, EntityStreamQuery, QueryParams, QueryOptions,
21
+ CachedListenersService, StreamMultiplexer, BATCH_WRITE_SERVICE,
22
+ } from '@tech4good/platform-data';
23
+ import { withEntitiesForMockDB, BatchWriteMockService } from '@tech4good/platform-data/testing';
24
+ import { FirestoreBatchWriteService } from '@tech4good/platform-data/firestore';
25
+ ```
26
+
27
+ Update components, auth stores, app configuration, tests and any custom generators
28
+ as well. Delete the old `core/store/app.store.ts`, listener/cache and batch-service
29
+ forwarding files after updating their consumers. Do not introduce reexports at
30
+ those paths. Replace infrastructure uses of the app's `AnyEntity` with `DataEntity`,
31
+ then remove `app.model.ts` if it only held that union. Import shared query types
32
+ directly. An app-specific exhaustive union, if needed, can derive from the
33
+ generated `AppEntityMap[keyof AppEntityMap]` instead of a handwritten list.
34
+
35
+ The shared `simulate-load.spec.ts`, `simulate-stream.spec.ts` and
36
+ `simulation.mock.ts` now live in the data package's repository test suite. Remove
37
+ their copied versions from `core/firebase` after checking for any app-specific
38
+ cases you added. Keep those cases, along with tests of your providers, entity
39
+ relationships, auth flows and security rules, in the app.
40
+
41
+ Make each stored model extend `DataEntity` and remove its optional declarations
42
+ of `__id`, `_createdAt`, `_updatedAt`, `_deleted`. The inherited fields are required.
43
+ Use `NewDataEntity<MyEntity>` for creation inputs that have not received metadata;
44
+ `store.add()` supplies it. Direct adapter adds still require an ID. Seed factories,
45
+ raw mock-store inserts and `store.init()` must return complete stored records.
46
+ Update fixtures to use `createMockX()` or supply both timestamps and `_deleted`.
47
+
48
+ Check existing persisted data and every external writer for missing metadata.
49
+ Required TypeScript fields do not repair old documents. Missing `_deleted` can
50
+ exclude a record from active queries; missing `_updatedAt` prevents reliable
51
+ incremental loading and nested-stream update detection. `_createdAt` is the
52
+ creation-time convention, though the incremental algorithm does not filter on it.
53
+
54
+ ### Replace Firebase timestamp values in application records
55
+
56
+ Import `DataTimestamp` and its helpers from `@tech4good/platform-data`:
57
+
58
+ | Old application usage | Shared value usage |
59
+ | --- | --- |
60
+ | `Timestamp` field type | `DataTimestamp` |
61
+ | `Timestamp.now()` | `dataTimestampNow()` |
62
+ | `Timestamp.fromMillis(ms)` | `dataTimestampFromMillis(ms)` |
63
+ | `Timestamp.fromDate(date)` | `dataTimestampFromDate(date)` |
64
+ | `timestamp.toMillis()` | `dataTimestampToMillis(timestamp)` (potentially lossy) |
65
+ | `timestamp.toDate()` | `dataTimestampToDate(timestamp)` (display conversion) |
66
+ | `a.isEqual(b)` or object identity checks | `dataTimestampEquals(a, b)` |
67
+ | Chronological comparison | `compareDataTimestamps(a, b)` |
68
+
69
+ Update metadata seeds and domain timestamp fields (for example,
70
+ `User.joinedWaitlistAt`), their factories, UI formatters and assertions.
71
+ Use `isDataTimestamp(value)` instead of `instanceof Timestamp`. Clock-controlled
72
+ store tests can spy on `Date.now()`; query cutoff operands are shared values.
73
+
74
+ The adapter decodes **all native timestamp values** in document maps/arrays,
75
+ not just metadata. It encodes tagged shared values on all write and query paths.
76
+ Ordinary strings/maps are preserved; `__type: 'DataTimestamp'` is a reserved tag.
77
+ Native SDK operations outside this adapter use `fromFirestoreTimestamp()` and
78
+ `toFirestoreTimestamp()` from `/firestore` at their boundaries. If a timestamp is
79
+ inside an SDK sentinel such as `arrayUnion`, convert it before making the sentinel.
80
+
81
+ Keep database/server timestamp generation in Firestore. Existing persisted
82
+ Firestore documents, Cloud Functions, security rules and indexes retain their
83
+ native representation. Mock persistence can read the previous tagged Timestamp
84
+ format without importing Firebase. The core/testing can now run without Firebase
85
+ installed; applications using `/firestore` still need the Firebase peer.
86
+
87
+ ## 2. Split shared data from app auth policy
88
+
89
+ Keep `AuthSession` and the app's authentication/profile interface locally. Extend
90
+ the package `DataAccess` interface, and alias its token:
91
+
92
+ ```ts
93
+ import { InjectionToken } from '@angular/core';
94
+ import { DATA_ACCESS, DataAccess } from '@tech4good/platform-data';
95
+
96
+ export interface DatabaseService extends DataAccess {
97
+ // Keep your app's existing auth/profile methods here.
98
+ }
99
+ export const DATABASE_SERVICE = DATA_ACCESS as InjectionToken<DatabaseService>;
100
+ ```
101
+
102
+ Extend `FirestoreDataService` from `/firestore` in the app's `FirebaseService`.
103
+ Remove only its duplicated data methods: createId, streamEntity, streamEntities,
104
+ streamEntitiesChanges, query-constraint construction, getEntity, getEntities,
105
+ count, aggregate, addEntity, updateEntity, removeEntity, incrementEntityField.
106
+ Keep auth mapping, login/linking, email-link context, profile provisioning,
107
+ account deletion and logout unchanged. Call `super()` in its constructor.
108
+ The base uses `dataFirestore`, so an app-specific `firestore` member can remain
109
+ where provisioning requires it.
110
+
111
+ Provide `PLATFORM_FIRESTORE` with the instance the app already configures. Supply
112
+ the combined app facade under `DATABASE_SERVICE`; do not also create a different
113
+ auth/data token. If using `provideFirestoreData()`, put the app facade override
114
+ after that provider. `useExisting` avoids creating a second instance when the
115
+ facade is also injected by class.
116
+
117
+ ## 3. Preserve mock profiles and seeds
118
+
119
+ Extend `MockDataService` from `/testing` in the local `FirebaseMockService`.
120
+ Keep the app's `AuthMockDB` and auth/profile methods. Replace its handwritten
121
+ collection map and seed initialization with entity-local definitions:
122
+
123
+ 1. Export `problemEntity = defineEntity<Problem>({ collection: 'problems' })`
124
+ beside the interface in `problem.model.ts`. Preserve existing collection names.
125
+ 2. Use `problemEntity.collection` in the entity store, mock store, and load/stream
126
+ descriptors instead of repeating the string.
127
+ 3. In `problem.mock.ts`, directly import the definition from `./problem.model`
128
+ and export `problemMock = defineEntityMock(problemEntity, { store: ProblemMockDB,
129
+ seeds: PROBLEM_DB })`. The mock store uses `withEntitiesForMockDB<Problem>`.
130
+ 4. Install platform-tooling alpha.2 or later and run `t4g-entities`. It writes
131
+ `entities.generated.ts` and `entity-mocks.generated.ts` inside the application.
132
+ 5. In the facade, import `APP_ENTITY_MOCKS` from the generated mock file and use
133
+ `override readonly DB = createMockRegistry(APP_ENTITY_MOCKS)`. Call
134
+ `super(injector)` in the constructor. Remove per-entity imports, manual seed
135
+ initialization, and duplicated data methods/latency controls.
136
+ 6. Change test seed options to `collections: { users: [...], problems: [...] }`.
137
+ Type these with `MockSeedOverrides<typeof APP_ENTITY_MOCKS>` and apply them
138
+ through `seedMockRegistry<typeof APP_ENTITY_MOCKS>(service.DB, collections)`.
139
+ Explicit overrides replace persisted fixtures, including empty arrays.
140
+ 7. Wrap development commands with `t4g-entities --watch -- ng serve` (or the
141
+ existing watch command). Prefix one-off builds/tests/lint with `t4g-entities &&`.
142
+ Add `generate:entities` and `check:entities` scripts; keep generated files in git.
143
+ 8. Move mock provider imports into a development provider module. Configure the
144
+ production Angular build to replace it with a real-only provider module;
145
+ an environment check alone does not guarantee fixture imports are absent.
146
+
147
+ `createMockRegistry`, `seedMockRegistry`, and `defineEntityMock` come from
148
+ `@tech4good/platform-data/testing`. Apps without an auth facade may use
149
+ `provideMockData({ collections: () => createMockRegistry(APP_ENTITY_MOCKS) })`.
150
+ The generated registry retains each concrete mock-store type; tests that inject
151
+ `ProblemMockDB` still see the same backend instance. Domain models remain local.
152
+
153
+ Generation does not migrate existing data, rewrite security rules, or change
154
+ application auth policy. A missing custom mock declaration produces an empty
155
+ in-memory collection; add the declaration to preserve existing seeded/persisted
156
+ mock behavior. No manual `AnyEntity` or per-entity facade edits are needed after
157
+ this one-time migration.
158
+
159
+ Import `BatchWriteMockService` and `WriteBatchMock` directly from `/testing`, and
160
+ `FirestoreBatchWriteService` from `/firestore`. The mock batch provider uses the mock
161
+ adapter configured under `DATA_ACCESS`, including an app facade subclass.
162
+
163
+ ## 4. Configure optional integrations and logout cleanup
164
+
165
+ Add `provideMaterialDataFeedback()` to preserve existing snackbar/undo options.
166
+ Install `@tech4good/platform-logging` alongside the data package and configure
167
+ `providePlatformLogging(...)` once in the app. Data diagnostics use its `data`
168
+ namespace; remove `DATA_LOGGER` providers and the `logger` option previously
169
+ accepted by `providePlatformData`. Import `Logger`, `injectLogger` and
170
+ `LoggingService` directly from the logging package. Replace module-level
171
+ `getLogger(...)` calls with `injectLogger(...)` in an injection context, or pass
172
+ a logger to non-injectable helpers. Delete the copied local logging service
173
+ after migrating its consumers; no compatibility reexports are needed.
174
+
175
+ Tests can capture `{ namespace, level, values }` through the logging provider's
176
+ `sink` option. Saved `query` filters should change to `data`. Generated apps only
177
+ enable optional persistence/DevTools access in development; logging output itself
178
+ defaults to disabled. The logging package README includes a migration checklist.
179
+ Configure
180
+ `MOCK_PERSISTENCE` using the app's existing cache setting if persistence is wanted.
181
+ The package itself imports no environment file or Material service in its root.
182
+
183
+ Keep global `CachedListenersService.teardownAllStreams()` before removing
184
+ credentials: it closes listeners/nested observers while preserving records and
185
+ load history in every entity store. Keep the app's explicit auth-related resets, session-ID
186
+ cleanup, and provisioning coordination. Generated apps call this composition
187
+ `AuthStore.clearSessionState()` and reset `UserStore` and `UserContextStore`,
188
+ including each collection's query and per-entity load history.
189
+
190
+ Remove blanket domain-store resets from logout when adopting this policy. Domain
191
+ records remain available across navigation and logout; the app's selectors decide
192
+ what to display. Ordinary pending reads/writes still complete and can update local
193
+ state afterward. `store.reset()` clears its own collection's local records and
194
+ load history, so its next load starts fresh. Other stores keep both and can load
195
+ deltas. `clearCache()` remains an explicit global listener/history cleanup for
196
+ tests or deliberate invalidation; do not use it for normal logout.
197
+
198
+ Use one root store per collection. The package does not register stores for automatic
199
+ reset or isolate multiple store instances for the same collection. Entity/model and
200
+ mock registries do not impose a session cleanup policy.
201
+
202
+ ## 5. Validate behavior and release adoption
203
+
204
+ Run lint, an Angular production build, data/auth/mock tests, and emulator rule
205
+ tests. Test an account switch while a data read is pending. Exercise initial and
206
+ incremental reads, nested queries, listener navigation/retry, optimistic writes,
207
+ failed batches and Undo. Run platform-tooling against unchanged indexes.
208
+
209
+ Check these intentional behavior corrections while reviewing test expectations:
210
+
211
+ - Missing IDs and empty membership queries no longer select unrelated entities.
212
+ - Aggregation aliases work; empty numeric averages return null.
213
+ - Mock raw data reads can return soft-deleted records for incremental removal.
214
+ - Ordered null values remain queryable; descending and tuple cursors use their
215
+ declared direction. Unknown local operators fail explicitly.
216
+ - Queries are keyed by collection and query without mutating input arrays.
217
+ Components share the same root entity store and matching listeners.
218
+ - Global listener teardown retains records and load history; each store reset
219
+ clears only its collection’s records and timestamps. Pending reads
220
+ and local write compensation retain the existing apps’ completion behavior.
221
+ - Mock batch update of a missing document rejects atomically, like Firestore.
222
+
223
+ Once the alpha is published, replace the local tarball dependency with that
224
+ exact npm version and commit the application's manifest/lockfile plus its
225
+ composition changes. Upgrading platform-data later should normally require only
226
+ a version/lockfile change and validation, unless release notes identify an API
227
+ migration.