@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 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 'apply'
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 `createServer`, and by `migrateTables`, under
925
- `session: 'sessions'` and only then. Nothing else is exported of the stored
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` applies them with the vex cache's sequence in
957
- one ledgered run before introspection: once, recorded in `strata_ledger`, and
958
- refused if the ledger was edited or written by newer code. `migrations` on the
959
- runtime picks the posture: `'apply'` (default) runs what is pending; `'verify'`
960
- refuses to boot if anything is, for a deployment that migrates as a deploy step.
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. Absent, the app migrates its own tables itself, as before. Another
969
- owner's tables the app keeps go in the same list (tide's: `TIDE_SEQUENCE`,
970
- from `@niscorp/tide/postgres`), and a
971
- runtime that hands tables over does not also migrate them itself.
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 boot.
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 and the data module stands; the running manifest is
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 pool the runtime
1743
- holds, and its tables are ordinary tables to moss: introspected, grantable,
1744
- and scoped by a behavior like any other.
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 migrated in the one ledgered run, before the feature
1765
- starts, and `migrateTables` runs them too. A feature reads and writes those
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 and the ones the app's features keep go through one
182
- [strata](../strata/README.md) ledger run at boot — once,
183
- recorded, refused if the ledger was edited or written by newer code. Tide's
184
- tables are tide's (`TIDE_SEQUENCE`, from `@niscorp/tide/postgres`): they go
185
- through the same ledger when `createTideStore(pool)` is called, or in moss's
186
- own run when the app hands the sequence over in `runtime.tables`.
187
- `migrations: 'verify'` on the
188
- runtime refuses to boot with anything pending. Stored integration actions carry
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 owners = { pool: runtime.pool, cache: runtime.cache, storesSessions: runtime.session === "sessions", featureTables: featureTablesOf(app), tables: runtime.tables };
626
- const report = await postgres.migrate(runtime.pool, tableSequencesOf(owners), {
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
- found = { ...changesBetween(before, after), alreadyBroken };
637
- return refused;
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, ...report.applied.length === 0 ? { removed: [], retyped: [] } : {} };
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 ?? "apply" });
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, status, hasPrincipal) => emit({ name, startUnixNano: clock.startUnixNano, endUnixNano: clock.endUnixNano(), status, attributes: { hasPrincipal } });
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
- //# sourceMappingURL=chunk-QB7U2JDQ.cjs.map
3576
- //# sourceMappingURL=chunk-QB7U2JDQ.cjs.map
3596
+ exports.tableStatus = tableStatus;
3597
+ //# sourceMappingURL=chunk-L2GHVTJW.cjs.map
3598
+ //# sourceMappingURL=chunk-L2GHVTJW.cjs.map