@niscorp/moss 0.8.2 → 0.9.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/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # @niscorp/moss
2
2
 
3
+ ## 0.9.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 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.
8
+
9
+ 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`.
10
+
11
+ `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.
12
+
13
+ `tableStatus(runtime, app)` and `nisc migrate --status`: what is applied and what is pending, read and nothing else.
14
+
15
+ 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`.
16
+
3
17
  ## 0.8.2
4
18
 
5
19
  ### Patch Changes
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
@@ -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
 
@@ -1739,9 +1762,10 @@ it answers `undefined`, nothing is minted.
1739
1762
  `createTideStore(pool, options?)`, `TIDE_SEQUENCE`, `TIDE_TABLES` and
1740
1763
  `TIDE_DDL` are exported by `@niscorp/tide/postgres`. They were moss's, and do
1741
1764
  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.
1765
+ Postgres store". `createTideStore(runtime.pool, { migrate: false })` takes the
1766
+ pool the runtime holds, with `TIDE_SEQUENCE` in `runtime.tables`, and its tables
1767
+ are ordinary tables to moss: migrated by `nisc migrate`, introspected,
1768
+ grantable, and scoped by a behavior like any other.
1745
1769
 
1746
1770
  ### Features
1747
1771
 
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