@niscorp/moss 0.8.2 → 0.9.1
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/CHANGELOG.md +22 -0
- package/DESIGN.md +1 -1
- package/DOCS.md +48 -21
- package/README.md +9 -8
- package/dist/{chunk-QB7U2JDQ.cjs → chunk-L2GHVTJW.cjs} +32 -10
- package/dist/chunk-L2GHVTJW.cjs.map +1 -0
- package/dist/{chunk-KLZYTSR2.cjs → chunk-LKTS4PCD.cjs} +5 -5
- package/dist/{chunk-KLZYTSR2.cjs.map → chunk-LKTS4PCD.cjs.map} +1 -1
- package/dist/{chunk-S4JSTWAE.js → chunk-UUOATPZ7.js} +3 -3
- package/dist/{chunk-S4JSTWAE.js.map → chunk-UUOATPZ7.js.map} +1 -1
- package/dist/{chunk-4M2MALV7.js → chunk-Y7PRASR3.js} +33 -12
- package/dist/chunk-Y7PRASR3.js.map +1 -0
- package/dist/index.cjs +14 -10
- package/dist/index.d.cts +6 -3
- package/dist/index.d.ts +6 -3
- package/dist/index.js +1 -1
- package/dist/node.cjs +6 -6
- package/dist/node.js +2 -2
- package/dist/vite.cjs +7 -7
- package/dist/vite.js +2 -2
- package/package.json +13 -13
- package/dist/chunk-4M2MALV7.js.map +0 -1
- package/dist/chunk-QB7U2JDQ.cjs.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,27 @@
|
|
|
1
1
|
# @niscorp/moss
|
|
2
2
|
|
|
3
|
+
## 0.9.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- efd5d03: The docs say what a boot does with the tables since `nisc migrate`: it checks them and refuses to start while a migration is pending, and applies them only under `migrations: 'apply'`. The sessions table, the boot order, a feature's sequences and how an old database adopts the ledger now read that way.
|
|
8
|
+
|
|
9
|
+
**What to change:** nothing. Documentation only.
|
|
10
|
+
|
|
11
|
+
## 0.9.0
|
|
12
|
+
|
|
13
|
+
### Minor Changes
|
|
14
|
+
|
|
15
|
+
- 2780c56: A real database's tables change only through `nisc migrate`. `migrations` on the runtime defaults to `'verify'`: `createServer` — and so `nisc dev`, `nisc build` and `nisc start` — checks the tables and refuses to start while a migration is pending, naming each one and the two commands that apply it (`npx nisc migrate --check`, then `npx nisc migrate`). On a database that is up to date the check only reads the ledger, so the app's database role needs `SELECT` on `strata_ledger` and no right to change tables. A runtime whose database starts empty every time (PGlite in memory) writes `migrations: 'apply'` and is migrated at boot as before.
|
|
16
|
+
|
|
17
|
+
The boot and `migrateTables` refuse a database whose ledger records a sequence they do not name (`UNKNOWN_SEQUENCE`): a sequence that has run stays in `runtime.tables`.
|
|
18
|
+
|
|
19
|
+
`migrateTables` and `nisc migrate` refuse a run that removes a table or a column, or changes a column's type, unless `allowRemoval` / `--allow-removal` is given; the refusal names each. A run that applied nothing, because another run had already applied it, is not refused.
|
|
20
|
+
|
|
21
|
+
`tableStatus(runtime, app)` and `nisc migrate --status`: what is applied and what is pending, read and nothing else.
|
|
22
|
+
|
|
23
|
+
BREAKING — approved by moccadroid, 2026-11-07: a runtime on a real database runs `nisc migrate` before the app starts (on Railway, the service's pre-deploy command `pnpm exec nisc migrate`); a runtime on in-memory PGlite writes `migrations: 'apply'`; every sequence that has run on the database is in `runtime.tables` (`TIDE_SEQUENCE` with the store made `migrate: false`), and the runtime migrates nothing itself and calls no `cache.init()`; a database that has not yet run `nisc.moss/4` is migrated once with `--allow-removal`.
|
|
24
|
+
|
|
3
25
|
## 0.8.2
|
|
4
26
|
|
|
5
27
|
### Patch Changes
|
package/DESIGN.md
CHANGED
|
@@ -320,7 +320,7 @@ that made the table:
|
|
|
320
320
|
|
|
321
321
|
| Table | Whose | Where its statements are written | What is somewhere else, and why |
|
|
322
322
|
|---|---|---|---|
|
|
323
|
-
| `sessions` | `identity` | `identity/sessions.ts`: five statements straight to the pool, before anybody is signed in | Its table is made in `data`'s one migration run, from a sequence `identity` declares |
|
|
323
|
+
| `sessions` | `identity` | `identity/sessions.ts`: five statements straight to the pool, before anybody is signed in | Its table is made in `data`'s one migration run (`migrateTables`, or boot under `migrations: 'apply'`; otherwise boot only checks it), from a sequence `identity` declares |
|
|
324
324
|
| `moss_generation` | `data` | `data/own-entries.ts`: two entries, one that reads and one that moves | `artifactory` decides when it moves (`artifactory/generation.ts`), through a function `data` hands over |
|
|
325
325
|
| `artifact_saves`, `artifacts` | `artifactory` | `artifactory/saves.ts`: three vex entries and the row rule they run under, replayed through a function `data` hands over (`Data.artifactEntries`) | The two tables are made by the core's sequence (`data/tables.ts`, `nisc.moss/5`). Their rows are somebody's, unlike the pointer's: the entries are replayed with the caller's scope, and vex keeps every read and write to the rows whose `principal` is the caller's `userId`. What is published for everybody is the rows of the principal `*`, replayed with that as the `userId` by the server's own code and by no caller. Moss updates and deletes no row, so a stored body is not rewritten when a grammar moves: it is brought to the current grammars where it is read |
|
|
326
326
|
| `integrations`, `integration_actions` | the `integrations` feature | `integrations/entries.ts`: vex entries, replayed through the seam the feature is handed | The two tables are made by the core's own sequence (`data/tables.ts`, `nisc.moss`): that is the history every database has run, and it is not edited. The documents stored in `integration_actions` are brought to the current grammars by `data`, which holds the pool, when the feature asks through its seam |
|
package/DOCS.md
CHANGED
|
@@ -786,7 +786,7 @@ type NiscRuntime = {
|
|
|
786
786
|
vexConfig?: QueryEngineConfig['config']; // the query engine's settings (limits, read timeout); default vex's own
|
|
787
787
|
session: SessionVerifier | 'sessions' | 'dev-open'; // REQUIRED — no default
|
|
788
788
|
origins?: readonly string[]; // origins that are the app's own page, beside the host a request names (a proxy that rewrites `Host`)
|
|
789
|
-
migrations?: 'apply' | 'verify'; // the boot's ledgered run; default '
|
|
789
|
+
migrations?: 'apply' | 'verify'; // the boot's ledgered run; default 'verify'
|
|
790
790
|
tables?: readonly Sequence[]; // the app's own table sequences, in that same run
|
|
791
791
|
shellIdleMs?: number; // idle shell eviction; default 30 min, `0` disables
|
|
792
792
|
artifactsUnusedMs?: number; // delete what a person generated once nobody has loaded it for this long; default never
|
|
@@ -921,9 +921,9 @@ the row.
|
|
|
921
921
|
this is for signing out somebody else (an owner removes a member).
|
|
922
922
|
No exported call deletes one token and leaves the principal's others.
|
|
923
923
|
- Who a token is, is asked of the server: `server.principalOf(token)`. The
|
|
924
|
-
table is made by `
|
|
925
|
-
`session: 'sessions'` and only then.
|
|
926
|
-
credential.
|
|
924
|
+
table is made by `migrateTables` (`nisc migrate`), and by `createServer`
|
|
925
|
+
under `migrations: 'apply'`, under `session: 'sessions'` and only then.
|
|
926
|
+
Nothing else is exported of the stored credential.
|
|
927
927
|
- **They are for a deployment whose `session` is `'sessions'`, and for no
|
|
928
928
|
other.** The stored sessions are what that verifier reads, and nothing else
|
|
929
929
|
reads them.
|
|
@@ -953,11 +953,16 @@ await revokeAllFor(runtime.pool, 'usr_ada');
|
|
|
953
953
|
integrations, their actions, the generation pointer, the two tables of what
|
|
954
954
|
was saved) and the sessions table's
|
|
955
955
|
(`nisc.moss.sessions`; the sequence itself is not exported) — and
|
|
956
|
-
`createServer`
|
|
957
|
-
one ledgered run before introspection:
|
|
958
|
-
|
|
959
|
-
runtime picks the posture: `'
|
|
960
|
-
refuses to boot
|
|
956
|
+
`createServer` checks them with the vex cache's sequence in
|
|
957
|
+
one ledgered run before introspection: refused if the ledger was edited, written
|
|
958
|
+
by newer code, or records a sequence the run does not name (strata's
|
|
959
|
+
`complete`). `migrations` on the runtime picks the posture: `'verify'` (default)
|
|
960
|
+
refuses to boot while anything is pending, naming each migration and the two
|
|
961
|
+
commands that apply it (`npx nisc migrate --check`, then `npx nisc migrate`) —
|
|
962
|
+
a real database's tables change only through `nisc migrate`; `'apply'` runs what
|
|
963
|
+
is pending, for a database that starts empty every time (PGlite in memory).
|
|
964
|
+
On a database that is up to date the check only reads the ledger, so the app's
|
|
965
|
+
database role needs no right to change tables.
|
|
961
966
|
|
|
962
967
|
The run's order is: `MOSS_SEQUENCE`, the sessions table's under
|
|
963
968
|
`session: 'sessions'`, the vex cache's, the tables the app's features keep (in
|
|
@@ -965,12 +970,15 @@ the order the app named the features), then `runtime.tables`.
|
|
|
965
970
|
|
|
966
971
|
`tables` on the runtime hands over the app's own table sequences. They join
|
|
967
972
|
that run last — one transaction, one lock, one posture, so `'verify'`
|
|
968
|
-
covers them.
|
|
969
|
-
owner's tables the app keeps
|
|
970
|
-
|
|
971
|
-
|
|
973
|
+
covers them. Every sequence that has run on the database is named there:
|
|
974
|
+
another owner's tables the app keeps (tide's: `TIDE_SEQUENCE`, from
|
|
975
|
+
`@niscorp/tide/postgres`, with the store made `migrate: false`), and a sequence
|
|
976
|
+
the app no longer uses — a removed feature's, or the sessions table's after the
|
|
977
|
+
app stopped storing sessions. To remove a sequence's tables, append a migration
|
|
978
|
+
that drops them. The runtime migrates nothing itself and calls no
|
|
979
|
+
`cache.init()`: the server does both, in that order.
|
|
972
980
|
|
|
973
|
-
#### `migrateTables(runtime, app, { dryRun? })`
|
|
981
|
+
#### `migrateTables(runtime, app, { dryRun?, allowRemoval? })`
|
|
974
982
|
|
|
975
983
|
The step that changes tables, for a deployment that migrates before it starts
|
|
976
984
|
(`nisc migrate` calls it). It applies everything pending in the one run,
|
|
@@ -999,6 +1007,21 @@ columns the run takes away), `retyped` (columns whose type it changes, as
|
|
|
999
1007
|
`table.column (was → now)`) and `alreadyBroken`. `dryRun` does all of it and
|
|
1000
1008
|
rolls it back.
|
|
1001
1009
|
|
|
1010
|
+
A run that removes a table or a column, or changes a column's type, is refused
|
|
1011
|
+
(`DOES_NOT_FIT`, a sentence each) unless `allowRemoval` is given. It sees what
|
|
1012
|
+
vex reads off the schema: not rows a step deletes, not keys a step takes out of
|
|
1013
|
+
a document. The picture before the run is read before the run's lock, so a
|
|
1014
|
+
removal another run made meanwhile can be refused here too; running again
|
|
1015
|
+
passes. moss's own sequence removes columns (`nisc.moss/4`): a database that
|
|
1016
|
+
has not run it needs `allowRemoval` once.
|
|
1017
|
+
|
|
1018
|
+
#### `tableStatus(runtime, app) : Plan`
|
|
1019
|
+
|
|
1020
|
+
What `migrateTables` would act on, read and nothing else — no lock, no
|
|
1021
|
+
transaction, nothing created: strata's plan (`applied` per sequence, `pending`
|
|
1022
|
+
in order, `problems`) over the same sequences. `nisc migrate --status` prints
|
|
1023
|
+
it.
|
|
1024
|
+
|
|
1002
1025
|
It sees entries and nothing else: not SQL written by hand, not a column a scope
|
|
1003
1026
|
rule stamps, not what a value means.
|
|
1004
1027
|
|
|
@@ -1013,7 +1036,8 @@ parsing them, stores them stamped current, and refuses a bundle built on newer
|
|
|
1013
1036
|
grammars than the host (*the host must be updated first*). Reads upgrade too:
|
|
1014
1037
|
a row another process wrote since boot is read current, and one it cannot read
|
|
1015
1038
|
is left out with a logged sentence. Migration 1 of each sequence is the DDL
|
|
1016
|
-
boots used to run, so a database from before the ledger adopts on its next
|
|
1039
|
+
boots used to run, so a database from before the ledger adopts on its next
|
|
1040
|
+
`nisc migrate`.
|
|
1017
1041
|
|
|
1018
1042
|
`shellFrameDelta` and `socketCompression` are the two wire-size knobs. They are
|
|
1019
1043
|
environment settings, not manifest ones — an operational decision about a
|
|
@@ -1053,7 +1077,8 @@ does nothing. Returns a Hono app extended with the `MossServer` members below.
|
|
|
1053
1077
|
`createServer` wires, and answers no question of its own (`src/server/`). In
|
|
1054
1078
|
order: the manifest is read and frozen; who a token is is resolved
|
|
1055
1079
|
(`runtime.session`; unset, the boot is refused here, before a table exists);
|
|
1056
|
-
the tables are migrated
|
|
1080
|
+
the tables are checked (migrated under `migrations: 'apply'`) and the data
|
|
1081
|
+
module stands; the running manifest is
|
|
1057
1082
|
created, which is the boot check, and the data module is told to ask it for an
|
|
1058
1083
|
entry (it compiles the ones it holds, and one vex cannot run refuses the boot);
|
|
1059
1084
|
identity; the server's own routes (the
|
|
@@ -1739,9 +1764,10 @@ it answers `undefined`, nothing is minted.
|
|
|
1739
1764
|
`createTideStore(pool, options?)`, `TIDE_SEQUENCE`, `TIDE_TABLES` and
|
|
1740
1765
|
`TIDE_DDL` are exported by `@niscorp/tide/postgres`. They were moss's, and do
|
|
1741
1766
|
what they did: see tide's [DOCS.md](../tide/DOCS.md), "The driver" and "The
|
|
1742
|
-
Postgres store". `createTideStore(runtime.pool)` takes the
|
|
1743
|
-
holds,
|
|
1744
|
-
|
|
1767
|
+
Postgres store". `createTideStore(runtime.pool, { migrate: false })` takes the
|
|
1768
|
+
pool the runtime holds, with `TIDE_SEQUENCE` in `runtime.tables`, and its tables
|
|
1769
|
+
are ordinary tables to moss: migrated by `nisc migrate`, introspected,
|
|
1770
|
+
grantable, and scoped by a behavior like any other.
|
|
1745
1771
|
|
|
1746
1772
|
### Features
|
|
1747
1773
|
|
|
@@ -1761,8 +1787,9 @@ app share a name. What a feature routes, keeps and serves is documented under
|
|
|
1761
1787
|
its entry point.
|
|
1762
1788
|
|
|
1763
1789
|
A feature names the tables that are its own and the strata sequences that make
|
|
1764
|
-
them. The sequences are
|
|
1765
|
-
starts
|
|
1790
|
+
them. The sequences are checked in the one ledgered run, before the feature
|
|
1791
|
+
starts (migrated there under `migrations: 'apply'`), and `migrateTables`
|
|
1792
|
+
applies them. A feature reads and writes those
|
|
1766
1793
|
tables through vex, as an app does, with entries of its own: they are seeded into a
|
|
1767
1794
|
cache of their own, held by an engine no route is handed, so `/api/vex`
|
|
1768
1795
|
answers `cache_miss` for one of them whatever the charter grants whoever asks,
|
package/README.md
CHANGED
|
@@ -178,14 +178,15 @@ never in moss core.
|
|
|
178
178
|
|
|
179
179
|
moss creates no table on its own: its tables (`MOSS_SEQUENCE`, plus the
|
|
180
180
|
sessions table's sequence when the runtime's `session` is `'sessions'`), the
|
|
181
|
-
vex cache's
|
|
182
|
-
[strata](../strata/README.md)
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
`migrations: '
|
|
188
|
-
|
|
181
|
+
vex cache's, the ones the app's features keep and the app's own
|
|
182
|
+
(`runtime.tables`) are [strata](../strata/README.md) sequences in one ledger.
|
|
183
|
+
A real database's tables change only through `nisc migrate`; a boot checks
|
|
184
|
+
them and refuses to start while a migration is pending, or when the ledger was
|
|
185
|
+
edited, written by newer code, or records a sequence nobody names. A runtime
|
|
186
|
+
whose database starts empty every time (PGlite in memory) writes
|
|
187
|
+
`migrations: 'apply'` and is migrated at boot. Tide's tables are tide's
|
|
188
|
+
(`TIDE_SEQUENCE`, from `@niscorp/tide/postgres`): the app hands the sequence
|
|
189
|
+
over in `runtime.tables` and makes the store `migrate: false`. Stored integration actions carry
|
|
189
190
|
a grammar stamp and are upgraded at boot, at intake and on read — through
|
|
190
191
|
nova's and Prism's grammars plus the app's own (`NiscApp.grammars`); a bundle or
|
|
191
192
|
row written by newer grammars is refused. See [DOCS.md](DOCS.md).
|
|
@@ -612,6 +612,18 @@ var oneAtATime = (query) => {
|
|
|
612
612
|
return next;
|
|
613
613
|
};
|
|
614
614
|
};
|
|
615
|
+
var ownersOf = (runtime, app) => ({
|
|
616
|
+
pool: runtime.pool,
|
|
617
|
+
cache: runtime.cache,
|
|
618
|
+
storesSessions: runtime.session === "sessions",
|
|
619
|
+
featureTables: featureTablesOf(app),
|
|
620
|
+
tables: runtime.tables
|
|
621
|
+
});
|
|
622
|
+
var tableStatus = async (runtime, app) => postgres.status(runtime.pool, tableSequencesOf(ownersOf(runtime, app)), { complete: true });
|
|
623
|
+
var removalsRefused = (found) => [
|
|
624
|
+
...found.removed.map((what) => `this run removes ${what}`),
|
|
625
|
+
...found.retyped.map((what) => `this run changes the type of ${what}`)
|
|
626
|
+
].map((sentence) => `${sentence} \u2014 nothing removed or retyped is applied unless it is allowed (\`allowRemoval\`; \`nisc migrate --allow-removal\`)`);
|
|
615
627
|
var migrateTables = async (runtime, app, options = {}) => {
|
|
616
628
|
const entries = chunkE6YAYR7G_cjs.entriesOf(app);
|
|
617
629
|
const cache = runtime.cache ?? vex.createPostgresCache({ pool: runtime.pool });
|
|
@@ -622,10 +634,10 @@ var migrateTables = async (runtime, app, options = {}) => {
|
|
|
622
634
|
if (misfitsBefore.has(entry.fingerprint) && await isSeededAs(cache, entry).catch(() => false)) excused.add(entry.fingerprint);
|
|
623
635
|
}
|
|
624
636
|
let found = { removed: [], retyped: [], alreadyBroken: [] };
|
|
625
|
-
const
|
|
626
|
-
|
|
637
|
+
const report = await postgres.migrate(runtime.pool, tableSequencesOf(ownersOf(runtime, app)), {
|
|
638
|
+
complete: true,
|
|
627
639
|
...options.dryRun === true ? { dryRun: true } : {},
|
|
628
|
-
guard: async (tx) => {
|
|
640
|
+
guard: async (tx, run) => {
|
|
629
641
|
const after = await vex.createPostgresAdapter({ pool: { query: oneAtATime((text, values) => tx.query(text, values)) } }).introspect();
|
|
630
642
|
const refused = [];
|
|
631
643
|
const alreadyBroken = [];
|
|
@@ -633,11 +645,12 @@ var migrateTables = async (runtime, app, options = {}) => {
|
|
|
633
645
|
if (excused.has(fingerprint)) alreadyBroken.push(`${fingerprint}: ${why}`);
|
|
634
646
|
else refused.push(`${fingerprint}: ${why}`);
|
|
635
647
|
}
|
|
636
|
-
|
|
637
|
-
|
|
648
|
+
const changes = run.applied.length === 0 ? { removed: [], retyped: [] } : changesBetween(before, after);
|
|
649
|
+
found = { ...changes, alreadyBroken };
|
|
650
|
+
return options.allowRemoval === true ? refused : [...refused, ...removalsRefused(changes)];
|
|
638
651
|
}
|
|
639
652
|
});
|
|
640
|
-
return { ...report, ...found
|
|
653
|
+
return { ...report, ...found };
|
|
641
654
|
};
|
|
642
655
|
var featureTablesOf = (app) => {
|
|
643
656
|
const features = /* @__PURE__ */ new Set();
|
|
@@ -997,7 +1010,15 @@ var createIntentAnswers = (deps) => {
|
|
|
997
1010
|
// src/data/data.ts
|
|
998
1011
|
var callerOfRoles = (roles) => ({ memoKey: memoKey(roles, void 0), roles });
|
|
999
1012
|
var prepareEngine = async (config) => {
|
|
1000
|
-
await postgres.migrate(config.pool, tableSequencesOf(config), { mode: config.migrations ?? "
|
|
1013
|
+
await postgres.migrate(config.pool, tableSequencesOf(config), { mode: config.migrations ?? "verify", complete: true }).catch((error) => {
|
|
1014
|
+
if (!(error instanceof strata.StrataError) || error.code !== "PENDING") throw error;
|
|
1015
|
+
throw new strata.StrataError(
|
|
1016
|
+
"PENDING",
|
|
1017
|
+
`The database is ${error.details.length} migration${error.details.length === 1 ? "" : "s"} behind this code, and the server only checks its tables at boot. Rehearse them with \`npx nisc migrate --check\`, then apply them with \`npx nisc migrate\`. A database that starts empty every time (PGlite in memory) is migrated at boot instead: its runtime sets \`migrations: 'apply'\`.`,
|
|
1018
|
+
error.details,
|
|
1019
|
+
{ cause: error }
|
|
1020
|
+
);
|
|
1021
|
+
});
|
|
1001
1022
|
const grammars = await createGrammarUpgrader({ grammars: config.grammars });
|
|
1002
1023
|
const layer = await createDataLayer(config);
|
|
1003
1024
|
return {
|
|
@@ -2630,7 +2651,7 @@ var refusalOf2 = (error) => {
|
|
|
2630
2651
|
var spanOf = (emit) => {
|
|
2631
2652
|
if (emit === void 0) return void 0;
|
|
2632
2653
|
const clock = chunkPVZMCEBX_cjs.spanClock();
|
|
2633
|
-
return (name,
|
|
2654
|
+
return (name, status2, hasPrincipal) => emit({ name, startUnixNano: clock.startUnixNano, endUnixNano: clock.endUnixNano(), status: status2, attributes: { hasPrincipal } });
|
|
2634
2655
|
};
|
|
2635
2656
|
var openingOf = (config, { seed, path }) => {
|
|
2636
2657
|
const route = path === void 0 ? void 0 : config.page?.(path);
|
|
@@ -3572,5 +3593,6 @@ exports.mintSession = mintSession;
|
|
|
3572
3593
|
exports.renderDocument = renderDocument;
|
|
3573
3594
|
exports.revokeAllFor = revokeAllFor;
|
|
3574
3595
|
exports.sessionCookies = sessionCookies;
|
|
3575
|
-
|
|
3576
|
-
//# sourceMappingURL=chunk-
|
|
3596
|
+
exports.tableStatus = tableStatus;
|
|
3597
|
+
//# sourceMappingURL=chunk-L2GHVTJW.cjs.map
|
|
3598
|
+
//# sourceMappingURL=chunk-L2GHVTJW.cjs.map
|