@feltdb/core 0.11.4 → 0.11.6
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/dist/architecture-invariant.d.ts +407 -0
- package/dist/architecture-invariant.d.ts.map +1 -0
- package/dist/architecture-invariant.js +708 -0
- package/dist/collection.d.ts.map +1 -1
- package/dist/collection.js +3 -1
- package/dist/create/package-versions.js +1 -1
- package/dist/create/server-source/crates/feltdb/src/lib.rs +10 -1
- package/dist/create/server-source/crates/feltdb/src/semantic_decision.rs +124 -12
- package/dist/create/server-source/crates/feltdb/src/semantic_query.rs +599 -0
- package/dist/create/server-source/crates/feltdb/src/state_contract.rs +222 -0
- package/dist/create/server-source/crates/feltdb/tests/pr7_self_authorization_proof.rs +1 -0
- package/dist/create/server-source/crates/feltdb/tests/saas_invitation_lifecycle.rs +1 -0
- package/dist/create/server-source/crates/feltdb/tests/semantic_query.rs +767 -0
- package/dist/create/server-source/crates/feltdb/tests/semantic_query_contract.rs +363 -0
- package/dist/create/server-source/crates/feltdb-server/src/app_state.rs +5 -0
- package/dist/create/server-source/crates/feltdb-server/src/main.rs +150 -2
- package/dist/db.d.ts +46 -0
- package/dist/db.d.ts.map +1 -1
- package/dist/db.js +60 -0
- package/dist/embedded-query.d.ts +1 -0
- package/dist/embedded-query.d.ts.map +1 -1
- package/dist/embedded-query.js +15 -4
- package/dist/feltdb-vision-invariants.d.ts +46 -0
- package/dist/feltdb-vision-invariants.d.ts.map +1 -0
- package/dist/feltdb-vision-invariants.js +240 -0
- package/dist/feltdb.d.ts +7 -0
- package/dist/feltdb.d.ts.map +1 -1
- package/dist/http-db.d.ts +9 -0
- package/dist/http-db.d.ts.map +1 -1
- package/dist/http-db.js +8 -0
- package/dist/index-core.d.ts +3 -0
- package/dist/index-core.d.ts.map +1 -1
- package/dist/index-core.js +3 -0
- package/dist/runtime-snapshot.d.ts +337 -0
- package/dist/runtime-snapshot.d.ts.map +1 -0
- package/dist/runtime-snapshot.js +482 -0
- package/dist/semantic-decision.d.ts +57 -0
- package/dist/semantic-decision.d.ts.map +1 -1
- package/dist/state-contract.d.ts +3 -2
- package/dist/state-contract.d.ts.map +1 -1
- package/dist/studio-app/assets/{feltdb_wasm-BGgGSBOP.js → feltdb_wasm-D58hv7aa.js} +1 -1
- package/dist/studio-app/assets/feltdb_wasm_bg-BgFXYOtc.wasm +0 -0
- package/dist/studio-app/assets/index-gR6d3Tys.js +30 -0
- package/dist/studio-app/index.html +1 -1
- package/dist/wasm/feltdb_wasm_bg.wasm +0 -0
- package/package.json +1 -1
- package/dist/studio-app/assets/feltdb_wasm_bg-ClM6Qpod.wasm +0 -0
- package/dist/studio-app/assets/index-ptUom553.js +0 -30
package/dist/index-core.d.ts
CHANGED
|
@@ -22,6 +22,7 @@ export * from './index-recovery.js';
|
|
|
22
22
|
export * from './query-planner.js';
|
|
23
23
|
export type { AuthorityQueryPage, AuthorityQueryRequest } from './http-db.js';
|
|
24
24
|
export type { EmbeddedQueryExplanation, EmbeddedQueryStats } from './embedded-query.js';
|
|
25
|
+
export * from './runtime-snapshot.js';
|
|
25
26
|
export * from './index-analytics.js';
|
|
26
27
|
export * from './analytics-backend.js';
|
|
27
28
|
export * from './index-dashboard.js';
|
|
@@ -65,6 +66,8 @@ export * from './module.js';
|
|
|
65
66
|
export * from './module-intent.js';
|
|
66
67
|
export * from './application-understanding.js';
|
|
67
68
|
export * from './convergence.js';
|
|
69
|
+
export * from './architecture-invariant.js';
|
|
70
|
+
export * from './feltdb-vision-invariants.js';
|
|
68
71
|
export * from './intent.js';
|
|
69
72
|
export { ProtocolHandler, type Message, type Operation as ProtocolOperation, type Response as ProtocolResponse, } from './protocol.js';
|
|
70
73
|
/**
|
package/dist/index-core.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index-core.d.ts","sourceRoot":"","sources":["../src/index-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC9E,YAAY,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACxF,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,iCAAiC,CAAC;AAChD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,IAAI,iBAAiB,EACnC,KAAK,QAAQ,IAAI,gBAAgB,GAClC,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AAEnC;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACnE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzE;;GAEG;AACH,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC"}
|
|
1
|
+
{"version":3,"file":"index-core.d.ts","sourceRoot":"","sources":["../src/index-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC9E,YAAY,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACxF,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,iCAAiC,CAAC;AAChD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,IAAI,iBAAiB,EACnC,KAAK,QAAQ,IAAI,gBAAgB,GAClC,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AAEnC;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACnE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzE;;GAEG;AACH,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC"}
|
package/dist/index-core.js
CHANGED
|
@@ -20,6 +20,7 @@ export * from './index-backend.js';
|
|
|
20
20
|
export * from './index-store.js';
|
|
21
21
|
export * from './index-recovery.js';
|
|
22
22
|
export * from './query-planner.js';
|
|
23
|
+
export * from './runtime-snapshot.js';
|
|
23
24
|
export * from './index-analytics.js';
|
|
24
25
|
export * from './analytics-backend.js';
|
|
25
26
|
export * from './index-dashboard.js';
|
|
@@ -63,6 +64,8 @@ export * from './module.js';
|
|
|
63
64
|
export * from './module-intent.js';
|
|
64
65
|
export * from './application-understanding.js';
|
|
65
66
|
export * from './convergence.js';
|
|
67
|
+
export * from './architecture-invariant.js';
|
|
68
|
+
export * from './feltdb-vision-invariants.js';
|
|
66
69
|
export * from './intent.js';
|
|
67
70
|
export { ProtocolHandler, } from './protocol.js';
|
|
68
71
|
/**
|
|
@@ -0,0 +1,337 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Native materialized runtime snapshots.
|
|
3
|
+
*
|
|
4
|
+
* A hot path — an authorization decision, an agent loop, a rendered view —
|
|
5
|
+
* reads the same durable state hundreds of times per second. Asking the
|
|
6
|
+
* durable authority every time is slow, so applications build their own cache,
|
|
7
|
+
* and that cache becomes an unofficial second database: mutable, unversioned,
|
|
8
|
+
* invalidated by hand, and eventually disagreeing with FeltDB.
|
|
9
|
+
*
|
|
10
|
+
* A runtime snapshot is FeltDB's answer. It is a *derived representation* of
|
|
11
|
+
* authoritative FeltDB state, not a second source of truth:
|
|
12
|
+
*
|
|
13
|
+
* - it says which durable state it represents, through the same revision
|
|
14
|
+
* semantics `freshness.ts` defines, or says honestly that it cannot;
|
|
15
|
+
* - it is immutable once published, so a consumer mid-decision cannot be
|
|
16
|
+
* overtaken by a partial rebuild;
|
|
17
|
+
* - it is replaced atomically, so consumers observe one complete snapshot or
|
|
18
|
+
* another, never a mixture;
|
|
19
|
+
* - it holds no reference to the database, so reading it cannot perform
|
|
20
|
+
* durable I/O — that is a structural property, not a promise;
|
|
21
|
+
* - it answers bounded queries through the same executor the embedded
|
|
22
|
+
* storage boundary uses, so filtering, ordering, cursors, and index
|
|
23
|
+
* selection mean what they already mean in FeltDB.
|
|
24
|
+
*
|
|
25
|
+
* Writes never go here. A snapshot has no `set` and no `delete`, because
|
|
26
|
+
* mutation belongs to the authoritative state APIs and nothing else.
|
|
27
|
+
*
|
|
28
|
+
* See docs/reference/runtime-snapshots.md for the contract, the consistency
|
|
29
|
+
* and staleness rules, and the memory and lifecycle semantics.
|
|
30
|
+
*/
|
|
31
|
+
import { type FreshnessCapability, type Revision } from './freshness.js';
|
|
32
|
+
import { type EmbeddedQueryExplanation } from './embedded-query.js';
|
|
33
|
+
import type { AuthorityQueryPage, AuthorityQueryRequest } from './http-db.js';
|
|
34
|
+
import type { IndexConfig } from './index-types.js';
|
|
35
|
+
/** A snapshot query is the bounded authority query, executed against materialized state. */
|
|
36
|
+
export type SnapshotQueryRequest = AuthorityQueryRequest;
|
|
37
|
+
/** A snapshot query page is the bounded authority query page. */
|
|
38
|
+
export type SnapshotQueryPage<T = Record<string, unknown>> = AuthorityQueryPage<T>;
|
|
39
|
+
/** One condition of a bounded query, reused for materialization filters. */
|
|
40
|
+
export type SnapshotCondition = NonNullable<AuthorityQueryRequest['where']>[number];
|
|
41
|
+
/** One collection this snapshot materializes, and the runtime indexes built over it. */
|
|
42
|
+
export interface SnapshotSourceDefinition {
|
|
43
|
+
collection: string;
|
|
44
|
+
/**
|
|
45
|
+
* Restrict what is materialized. Conditions are ANDed and carry exactly one
|
|
46
|
+
* operator each, as in a bounded query. A snapshot that holds a subset of a
|
|
47
|
+
* collection is still derived from authoritative state; it simply derives
|
|
48
|
+
* less of it.
|
|
49
|
+
*/
|
|
50
|
+
where?: SnapshotCondition[];
|
|
51
|
+
/**
|
|
52
|
+
* Runtime indexes over the materialized records. They use the same
|
|
53
|
+
* `IndexConfig` shape as collection indexes and are consumed by the same
|
|
54
|
+
* planner, so an indexed snapshot query is bounded for the same reasons a
|
|
55
|
+
* durable one is.
|
|
56
|
+
*/
|
|
57
|
+
indexes?: IndexConfig[];
|
|
58
|
+
}
|
|
59
|
+
/** Read access to what a build materialized, handed to `derive`. */
|
|
60
|
+
export interface SnapshotMaterializationView {
|
|
61
|
+
readonly collections: readonly string[];
|
|
62
|
+
all<T = Record<string, unknown>>(collection: string): readonly T[];
|
|
63
|
+
}
|
|
64
|
+
export interface SnapshotDefinition<D = undefined> {
|
|
65
|
+
/** Stable name. `db.snapshot(name)` resolves the handle by it. */
|
|
66
|
+
name: string;
|
|
67
|
+
/** The durable collections this snapshot is derived from. At least one. */
|
|
68
|
+
sources: SnapshotSourceDefinition[];
|
|
69
|
+
/**
|
|
70
|
+
* Derive additional read-optimized state from the materialized records.
|
|
71
|
+
*
|
|
72
|
+
* Called once per build, before publication, and must be pure: it may read
|
|
73
|
+
* the materialization and return a value, and must not mutate records or
|
|
74
|
+
* reach for the database. The returned value is frozen and published with
|
|
75
|
+
* the snapshot.
|
|
76
|
+
*/
|
|
77
|
+
derive?: (view: SnapshotMaterializationView) => D;
|
|
78
|
+
/**
|
|
79
|
+
* Reject a candidate snapshot before it is published, by throwing.
|
|
80
|
+
*
|
|
81
|
+
* A rejected build leaves the active snapshot in place. This is where an
|
|
82
|
+
* application states what "complete enough to serve" means for its own
|
|
83
|
+
* derived state.
|
|
84
|
+
*/
|
|
85
|
+
validate?: (candidate: RuntimeSnapshot<D>) => void;
|
|
86
|
+
/**
|
|
87
|
+
* How many times a build may be retried when durable state moves underneath
|
|
88
|
+
* it. Applies only to runtimes that can prove coherence with a revision.
|
|
89
|
+
* Defaults to 3.
|
|
90
|
+
*/
|
|
91
|
+
coherenceAttempts?: number;
|
|
92
|
+
/**
|
|
93
|
+
* Freeze every materialized record (default). Freezing costs one pass over
|
|
94
|
+
* the records at build time and makes "published snapshots are immutable" a
|
|
95
|
+
* property of the objects rather than a convention. Turning it off is a
|
|
96
|
+
* deliberate trade of that guarantee for build throughput.
|
|
97
|
+
*/
|
|
98
|
+
freezeRecords?: boolean;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* What durable state a snapshot represents.
|
|
102
|
+
*
|
|
103
|
+
* Deliberately shaped like `FreshnessCapability`: a snapshot can only be as
|
|
104
|
+
* honest about its version as the runtime it was derived from. A runtime that
|
|
105
|
+
* cannot produce an authoritative revision does not get one invented for it.
|
|
106
|
+
*/
|
|
107
|
+
export interface SnapshotBasis {
|
|
108
|
+
/** `revision` when the snapshot carries an authoritative revision; `refresh` when it cannot. */
|
|
109
|
+
validation: 'revision' | 'refresh';
|
|
110
|
+
/** The FeltDB revision this snapshot represents. Present exactly when validation is `revision`. */
|
|
111
|
+
revision?: Revision;
|
|
112
|
+
/** Why no revision identifies this snapshot. Present exactly when validation is `refresh`. */
|
|
113
|
+
reason?: string;
|
|
114
|
+
/**
|
|
115
|
+
* `proven` when the revision was unchanged across the whole materialization,
|
|
116
|
+
* so the snapshot is a point-in-time view of one durable state. `unproven`
|
|
117
|
+
* when the runtime offers no revision to compare, and the materialization
|
|
118
|
+
* may therefore span concurrent writes.
|
|
119
|
+
*/
|
|
120
|
+
coherence: 'proven' | 'unproven';
|
|
121
|
+
/** When materialization completed. Reporting only; never a freshness signal. */
|
|
122
|
+
materializedAt: number;
|
|
123
|
+
}
|
|
124
|
+
/** Whether a published snapshot still represents current durable state. */
|
|
125
|
+
export interface SnapshotStaleness {
|
|
126
|
+
/** `unknown` means the runtime cannot prove currency — not that the snapshot is current. */
|
|
127
|
+
state: 'current' | 'stale' | 'unknown';
|
|
128
|
+
/** The revision the snapshot was built from, when it has one. */
|
|
129
|
+
snapshot?: Revision;
|
|
130
|
+
/** The runtime's current revision, when it has one. */
|
|
131
|
+
current?: Revision;
|
|
132
|
+
/** Why currency could not be decided. */
|
|
133
|
+
reason?: string;
|
|
134
|
+
}
|
|
135
|
+
export interface SnapshotIndexDescription {
|
|
136
|
+
collection: string;
|
|
137
|
+
name: string;
|
|
138
|
+
fields: string[];
|
|
139
|
+
/** Index entries held, which is one per materialized record of the collection. */
|
|
140
|
+
entries: number;
|
|
141
|
+
}
|
|
142
|
+
export interface SnapshotSourceDescription {
|
|
143
|
+
collection: string;
|
|
144
|
+
records: number;
|
|
145
|
+
/** Whether a materialization filter was applied to this source. */
|
|
146
|
+
filtered: boolean;
|
|
147
|
+
indexes: string[];
|
|
148
|
+
}
|
|
149
|
+
/** What a snapshot is, in enough detail to reason about its runtime behavior. */
|
|
150
|
+
export interface SnapshotExplanation {
|
|
151
|
+
name: string;
|
|
152
|
+
/** Publication counter. Increments once per published snapshot, never reused. */
|
|
153
|
+
generation: number;
|
|
154
|
+
records: number;
|
|
155
|
+
basis: SnapshotBasis;
|
|
156
|
+
buildMs: number;
|
|
157
|
+
sources: SnapshotSourceDescription[];
|
|
158
|
+
indexes: SnapshotIndexDescription[];
|
|
159
|
+
}
|
|
160
|
+
/** What a handle has done, including what it failed to do. */
|
|
161
|
+
export interface SnapshotHandleExplanation extends SnapshotExplanation {
|
|
162
|
+
/** Builds that reached publication. */
|
|
163
|
+
builds: number;
|
|
164
|
+
/** Builds that failed. A failed build never replaces the active snapshot. */
|
|
165
|
+
failures: number;
|
|
166
|
+
lastFailure?: {
|
|
167
|
+
at: number;
|
|
168
|
+
message: string;
|
|
169
|
+
};
|
|
170
|
+
/**
|
|
171
|
+
* Durable collection reads this handle has performed, across every build.
|
|
172
|
+
*
|
|
173
|
+
* Reading a published snapshot never increments it: that is what "the hot
|
|
174
|
+
* path performs no durable I/O" means, stated as a number rather than a
|
|
175
|
+
* claim.
|
|
176
|
+
*/
|
|
177
|
+
durableReads: number;
|
|
178
|
+
}
|
|
179
|
+
export declare class SnapshotDefinitionError extends Error {
|
|
180
|
+
constructor(message: string);
|
|
181
|
+
}
|
|
182
|
+
/** A build failed. The previously published snapshot, if any, remains active. */
|
|
183
|
+
export declare class SnapshotBuildError extends Error {
|
|
184
|
+
readonly cause?: unknown | undefined;
|
|
185
|
+
constructor(message: string, cause?: unknown | undefined);
|
|
186
|
+
}
|
|
187
|
+
/** A snapshot was read before anything was published. */
|
|
188
|
+
export declare class SnapshotNotPublishedError extends Error {
|
|
189
|
+
constructor(message: string);
|
|
190
|
+
}
|
|
191
|
+
/** Proof of currency was required and the runtime cannot provide it. */
|
|
192
|
+
export declare class SnapshotFreshnessError extends Error {
|
|
193
|
+
constructor(message: string);
|
|
194
|
+
}
|
|
195
|
+
/**
|
|
196
|
+
* A published runtime snapshot.
|
|
197
|
+
*
|
|
198
|
+
* Every method answers from materialized state. None of them touch storage,
|
|
199
|
+
* the network, or the database handle, because the implementation holds no
|
|
200
|
+
* reference to any of them.
|
|
201
|
+
*/
|
|
202
|
+
export interface RuntimeSnapshot<D = undefined> {
|
|
203
|
+
readonly name: string;
|
|
204
|
+
readonly generation: number;
|
|
205
|
+
readonly basis: SnapshotBasis;
|
|
206
|
+
/** The revision this snapshot represents, when the runtime has one. */
|
|
207
|
+
readonly revision?: Revision;
|
|
208
|
+
readonly materializedAt: number;
|
|
209
|
+
/** Materialized records, across every source. */
|
|
210
|
+
readonly records: number;
|
|
211
|
+
readonly collections: readonly string[];
|
|
212
|
+
get<T = Record<string, unknown>>(collection: string, id: string | number): T | undefined;
|
|
213
|
+
has(collection: string, id: string | number): boolean;
|
|
214
|
+
/** Every materialized record of one collection, in materialization order. Frozen. */
|
|
215
|
+
all<T = Record<string, unknown>>(collection: string): readonly T[];
|
|
216
|
+
/** A bounded, optionally indexed query over materialized state. Synchronous. */
|
|
217
|
+
query<T = Record<string, unknown>>(request: SnapshotQueryRequest): SnapshotQueryPage<T>;
|
|
218
|
+
/** Whatever the definition's `derive` returned for this build. */
|
|
219
|
+
derived(): D;
|
|
220
|
+
/** What this snapshot is, or which access path a query would take. */
|
|
221
|
+
explain(): SnapshotExplanation;
|
|
222
|
+
explain(request: SnapshotQueryRequest): EmbeddedQueryExplanation;
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* The durable state a snapshot is derived from.
|
|
226
|
+
*
|
|
227
|
+
* A port rather than a concrete database, so the same semantics hold for every
|
|
228
|
+
* FeltDB runtime — embedded, browser, file, server, WASM — with each supplying
|
|
229
|
+
* its own reads and its own honest freshness answer.
|
|
230
|
+
*/
|
|
231
|
+
export interface SnapshotSourceRuntime {
|
|
232
|
+
/** Read every authoritative record of one collection. */
|
|
233
|
+
readRecords(collection: string): Promise<Array<Record<string, unknown>>>;
|
|
234
|
+
/** What freshness validation the underlying runtime can honestly support. */
|
|
235
|
+
freshness(): Promise<FreshnessCapability>;
|
|
236
|
+
/** The runtime's current revision. Called only when freshness advertises one. */
|
|
237
|
+
revision(): Promise<Revision>;
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* The lifecycle owner: CREATE → BUILD → VALIDATE → PUBLISH → READ → REPLACE.
|
|
241
|
+
*
|
|
242
|
+
* The handle is mutable — it is what replacement means. Everything it
|
|
243
|
+
* publishes is not.
|
|
244
|
+
*/
|
|
245
|
+
export declare class RuntimeSnapshotHandle<D = undefined> {
|
|
246
|
+
readonly definition: SnapshotDefinition<D>;
|
|
247
|
+
private readonly source;
|
|
248
|
+
private active?;
|
|
249
|
+
private generation;
|
|
250
|
+
private building?;
|
|
251
|
+
private readonly listeners;
|
|
252
|
+
private builds;
|
|
253
|
+
private failures;
|
|
254
|
+
private durableReads;
|
|
255
|
+
private lastFailure?;
|
|
256
|
+
private closed;
|
|
257
|
+
constructor(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime);
|
|
258
|
+
get name(): string;
|
|
259
|
+
/**
|
|
260
|
+
* The active snapshot, or `undefined` before the first successful build.
|
|
261
|
+
*
|
|
262
|
+
* Never performs I/O and never blocks: this is the hot-path accessor.
|
|
263
|
+
*/
|
|
264
|
+
get current(): RuntimeSnapshot<D> | undefined;
|
|
265
|
+
/** The active snapshot, or an error explaining that nothing is published yet. */
|
|
266
|
+
read(): RuntimeSnapshot<D>;
|
|
267
|
+
/**
|
|
268
|
+
* Build and publish a snapshot.
|
|
269
|
+
*
|
|
270
|
+
* When the runtime offers an authoritative revision and the active snapshot
|
|
271
|
+
* already represents it, nothing is rebuilt and the active snapshot is
|
|
272
|
+
* returned — the cheapest correct incremental step there is. `force` skips
|
|
273
|
+
* that check.
|
|
274
|
+
*
|
|
275
|
+
* A failed build throws and leaves the active snapshot untouched.
|
|
276
|
+
*/
|
|
277
|
+
refresh(options?: {
|
|
278
|
+
force?: boolean;
|
|
279
|
+
}): Promise<RuntimeSnapshot<D>>;
|
|
280
|
+
/**
|
|
281
|
+
* A snapshot proven to represent current durable state.
|
|
282
|
+
*
|
|
283
|
+
* Rebuilds when stale, and refuses when currency cannot be established,
|
|
284
|
+
* rather than serving state of unknown age. Security-sensitive consumers —
|
|
285
|
+
* authorization above all — use this instead of `current`, so that their
|
|
286
|
+
* freshness requirement is explicit in the code that depends on it.
|
|
287
|
+
*/
|
|
288
|
+
fresh(): Promise<RuntimeSnapshot<D>>;
|
|
289
|
+
/** Whether the active snapshot still represents current durable state. */
|
|
290
|
+
staleness(): Promise<SnapshotStaleness>;
|
|
291
|
+
/** Observe publications. The listener receives the snapshot that became active. */
|
|
292
|
+
subscribe(listener: (snapshot: RuntimeSnapshot<D>) => void): () => void;
|
|
293
|
+
/** What this handle holds, how it was built, and what it failed to build. */
|
|
294
|
+
explain(): SnapshotHandleExplanation;
|
|
295
|
+
/**
|
|
296
|
+
* Release the active snapshot.
|
|
297
|
+
*
|
|
298
|
+
* A handle retains exactly one snapshot, so this is what bounds retention
|
|
299
|
+
* when an application is done with a snapshot but keeps the database open.
|
|
300
|
+
* Consumers still holding a snapshot keep reading it; they always could.
|
|
301
|
+
*/
|
|
302
|
+
close(): void;
|
|
303
|
+
private assertOpen;
|
|
304
|
+
/**
|
|
305
|
+
* Single-flight build. Two concurrent refreshes produce one materialization
|
|
306
|
+
* and one publication, not two builds racing to replace each other.
|
|
307
|
+
*/
|
|
308
|
+
private build;
|
|
309
|
+
private runBuild;
|
|
310
|
+
private materialize;
|
|
311
|
+
/**
|
|
312
|
+
* VALIDATE, then PUBLISH.
|
|
313
|
+
*
|
|
314
|
+
* Publication is the single assignment below. A consumer holding the
|
|
315
|
+
* previous snapshot keeps a complete snapshot; a consumer reading after it
|
|
316
|
+
* gets a complete snapshot; there is no moment at which half of each is
|
|
317
|
+
* visible.
|
|
318
|
+
*/
|
|
319
|
+
private publish;
|
|
320
|
+
}
|
|
321
|
+
export declare function assertSnapshotDefinition(definition: SnapshotDefinition<any>): void;
|
|
322
|
+
/**
|
|
323
|
+
* Create a snapshot handle over any FeltDB runtime.
|
|
324
|
+
*
|
|
325
|
+
* `StateFirstDB.snapshot()` is the application-facing form; this is the same
|
|
326
|
+
* primitive for runtimes and tools that hold a source of their own.
|
|
327
|
+
*/
|
|
328
|
+
export declare function createRuntimeSnapshot<D = undefined>(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime): RuntimeSnapshotHandle<D>;
|
|
329
|
+
/**
|
|
330
|
+
* Whether two definitions describe the same snapshot.
|
|
331
|
+
*
|
|
332
|
+
* Sources, filters, indexes, and options compare structurally; `derive` and
|
|
333
|
+
* `validate` compare by identity, because two functions with the same text can
|
|
334
|
+
* still compute different things and nothing here can tell.
|
|
335
|
+
*/
|
|
336
|
+
export declare function snapshotDefinitionsMatch(left: SnapshotDefinition<any>, right: SnapshotDefinition<any>): boolean;
|
|
337
|
+
//# sourceMappingURL=runtime-snapshot.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"runtime-snapshot.d.ts","sourceRoot":"","sources":["../src/runtime-snapshot.ts"],"names":[],"mappings":"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"}
|