@jskit-ai/agent-docs 0.1.100 → 0.1.102

package/guide/agent/app-setup/database-layer.md

@@ -96,6 +96,16 @@ The app has two different migration-related layers:
 
 Those are **not** the same step.
 
+There is also an important ownership distinction:
+
+- a CRUD generator owns the installed baseline migration for the table it
+  scaffolds
+- the table's app-local package owns later additive schema evolution
+
+Never modify or replace a generator-owned baseline migration. Later schema
+evolution must use a new immutable, package-owned additive migration in the
+table's app-local package, declared through `install-migration`.
+
 The npm scripts hide the easy-to-miss first step for normal use. `npm run db:migrate` and `npm run db:migrate:status` run `npm run db:migrations:sync` first, then run Knex. That means package upgrades can add new JSKIT-managed migration files before Knex checks what is pending.
 
 ### `jskit migrations ...` writes managed migration files
@@ -157,6 +167,52 @@ So:
 - sometimes you need only `npm run db:migrate`
 - sometimes, after repair or re-materialization work, you need **both**
 
+### Authoring a later app-owned schema change
+
+When an existing CRUD-owned table needs a new column, constraint, index, or
+other compatible evolution, keep the generated baseline unchanged. Ask JSKIT
+to create a new migration source in the app-local package that owns the table:
+
+```bash
+npx jskit create migration \
+  --package @local/workflow-record-report-values \
+  --id extend-report-value-field-types
+```
+
+This command:
+
+1. verifies that the owner is an installed app-local package
+2. rejects duplicate or unsafe migration ids
+3. creates an editable template under the package's
+   `templates/migrations/` directory
+4. adds the matching `install-migration` mutation to the package descriptor
+5. leaves the migration unmaterialized so its implementation can still be
+   completed
+
+Implement and test the template first. It intentionally fails if someone tries
+to apply the untouched scaffold. Then materialize and apply it:
+
+```bash
+npx jskit migrations package @local/workflow-record-report-values
+npm run db:migrate
+```
+
+The materialized migration and its lock record are managed artifacts. Once
+installed, the migration id and content are immutable. Any later correction
+must use another additive migration with a new id.
+
+SQL inside the source-controlled migration is supported when Knex does not
+express the required schema operation directly. Ad-hoc SQL applied only to a
+development or live database is not a migration and must not be used: it
+creates schema drift, breaks fresh reconstruction, and leaves deployment
+history incomplete.
+
+Before completion, exercise the complete migration chain against a fresh
+disposable database as well as the intended upgrade path. A down migration
+must refuse safely when narrowing the schema would invalidate existing data;
+it must never delete or silently transform valuable rows merely to make a
+rollback pass.
+
 ### Shared database helpers
 
 The database layer also gives later server code a shared helper surface:

package/guide/agent/generators/crud-generators.md

@@ -286,6 +286,25 @@ The exact fields will vary by app. What matters for the generator is:
 - the column names are stable enough to become part of your app's resource contract
 - if you are using `crud-server-generator`, do **not** hand-write a separate CRUD migration for this table; the server generator installs the CRUD migration scaffold itself
 
+That last rule governs the generated baseline, not every future schema change.
+Never modify or replace a generator-owned baseline migration after it has been
+installed. Later schema evolution must use a new immutable, package-owned
+additive migration in the table's app-local package, declared through
+`install-migration`.
+
+Create that source and descriptor mutation together with:
+
+```bash
+npx jskit create migration \
+  --package @local/contacts \
+  --id add-contact-status
+```
+
+Implement the generated template before running
+`npx jskit migrations package @local/contacts`. SQL or Knex schema operations
+inside the source-controlled migration are supported. Running ad-hoc SQL
+against only one database is not, because it creates schema drift.
+
 In this table, `workspace_id` is the important ownership clue. That is why the next step uses:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.100",
+  "version": "0.1.102",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/crud-scaffolding.md

@@ -51,6 +51,9 @@ Rules:
 - If the table should already be CRUD-owned but should not expose public CRUD HTTP routes yet, scaffold it with `jskit generate crud-server-generator scaffold ... --internal` instead of dropping to direct knex or a hand-built pseudo-repository.
 - Create the real table directly in the database before scaffolding. `crud-server-generator` reads the live table shape.
 - If `crud-server-generator` is going to own the CRUD, do not hand-write a separate CRUD migration for that table. The generator installs and manages the CRUD migration scaffold itself.
+- Never modify or replace a generator-owned baseline migration after it has
+  been installed. Later schema evolution must use a new immutable,
+  package-owned additive migration declared through `install-migration`.
 - Keep generated table creation in `migrations/` and generated foreign keys in
   `migrations/constraints/`. The database runtime deliberately runs those
   phases in that order so valid mutual foreign keys rebuild cleanly without
@@ -72,6 +75,38 @@ Rules:
 - Structured filters should use shared filter definitions and collapse to compact filter controls/sheets when they outgrow simple search. Do not stack dense desktop filter bars on phone widths.
 - Use `--navigation-role` for CRUD list placement intent. Main resources can stay `primary`; nested/detail/workflow CRUD routes should usually be `secondary`, `workflow`, or `none`.
 
+## Baseline generation versus later schema evolution
+
+The initial CRUD scaffold and a later schema change are different operations:
+
+- The server generator owns the baseline migration that recreates the table
+  from zero. Do not edit, replace, or regenerate that installed baseline to
+  express a later change.
+- The table's app-local package owns later schema evolution. Create each change
+  as a new immutable additive migration:
+
+  ```bash
+  npx jskit create migration \
+    --package @local/workflow-record-report-values \
+    --id extend-report-value-field-types
+  ```
+
+- The authoring command creates an editable migration template and adds its
+  `install-migration` mutation to the owning package descriptor in one
+  operation. Implement and test the template before materializing it.
+- Materialize the completed source with
+  `npx jskit migrations package <package-id>`, then apply it with
+  `npm run db:migrate`.
+- SQL or Knex schema operations inside that source-controlled migration are
+  supported. Ad-hoc SQL applied only to one database is not: it creates schema
+  drift and leaves fresh installations incorrect.
+- Installed migration ids and content are immutable. A correction to an
+  installed migration is another additive migration with a new id.
+
+A package-owned additive migration is not the prohibited "separate CRUD
+migration." The prohibition applies to competing with or modifying the
+generator-owned baseline.
+
 Meaning of `--internal`:
 
 - it keeps the generated repository, service, actions, provider, resource, and CRUD migration ownership chain

package/reference/autogen/tooling/jskit-cli.md

@@ -777,6 +777,19 @@ Local functions
 Exports
 - `runPackageCreateCommand(ctx = {}, { positional, options, cwd, io })`
 
+### `src/server/commandHandlers/packageCommands/createMigration.js`
+Exports
+- `addInstallMigrationMutationToDescriptor(source = "", mutation = {})`
+- `createMigrationTemplate({ packageId, migrationId } = {})`
+- `runMigrationCreateCommand(ctx = {}, { options, cwd, io })`
+Local functions
+- `maskNonCode(source = "")`
+- `findMatchingDelimiter(source, openIndex, openCharacter, closeCharacter)`
+- `findMutationsFilesArray(source = "")`
+- `lineIndentAt(source = "", index = 0)`
+- `renderInstallMigrationMutation({ from, id, indent } = {})`
+- `writeMigrationSourceAndDescriptor({ descriptorPath, descriptorSource, migrationPath, migrationSource, mkdir, rename, rm, writeFile, path } = {})`
+
 ### `src/server/commandHandlers/packageCommands/discoverabilityHelp.js`
 Exports
 - `isHelpToken(value = "")`