@jskit-ai/agent-docs 0.1.94 → 0.1.96

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

@@ -230,6 +230,24 @@ w/[workspaceSlug]/admin/...
 
 then `workspace` is usually the normal default. If you are generating a CRUD for a global operator or account area, `public` or `user` may make more sense.
 
+## Schema contract for generated CRUD
+
+Generated CRUD tables use one single-column integer primary key, normally
+`id`. Each foreign key must also be single-column and must reference the target
+table's single-column primary key. Composite indexes remain useful for business
+uniqueness such as `(workspace_id, slug)`, but they are never relationship
+targets.
+
+Tenant isolation comes from a direct `workspace_id` and/or `user_id` ownership
+column, the exactly matching generated ownership filter, scoped service
+lookups, and cross-tenant tests. Do not encode ownership into a composite
+foreign key such as `(workspace_id, parent_id) -> (workspace_id, id)`.
+
+The generator rejects unsupported key shapes. If an approved application truly
+needs a different persistence model, record the durable decision in
+`.jskit/APP_BLUEPRINT.md` and use the explicit table-ownership exception path
+instead of modifying generated CRUD files.
+
 ## Example 1: `contacts`
 
 This is the baseline pattern. If you understand this example, the rest of the chapter becomes much easier.

package/package.json

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

package/patterns/crud-scaffolding.md

@@ -14,9 +14,38 @@ Check first:
 - `jskit show crud-server-generator --details`
 - whether the request is server-only CRUD or server-plus-UI CRUD
 
+## Non-negotiable database contract
+
+Before database, schema, CRUD, repository, or persistence work, read this
+pattern completely. Use the database selected for this app's development
+runtime; never alter a production, legacy, historical, or other valuable
+database to develop or verify schema changes. Prove the complete migration
+chain against a fresh disposable database before reporting completion.
+
+For normal app-owned CRUD tables:
+
+- use exactly one non-null integer primary-key column, normally
+  `id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY`
+- make every foreign key single-column and point it directly to the referenced
+  table's single-column primary key
+- use multi-column unique indexes only for business uniqueness, never as
+  relationship targets
+- use only direct `workspace_id` and/or `user_id` columns for generated JSKIT
+  ownership, and select the ownership filter that matches those columns exactly
+- express tenant-safe relationships as direct ownership plus a normal
+  `parent_id -> parent.id` relationship; resolve related IDs through the
+  workspace-scoped service and test both allowed and cross-workspace cases
+
+Do not use composite primary keys or composite foreign keys to encode tenant
+ownership, target a business key from a foreign key, or duplicate parent
+identity when the related row ID already identifies it. Stop before generation
+if the proposed table violates these constraints.
+
 Rules:
 
-- For a CRUD-backed entity, start with `jskit generate crud-server-generator scaffold ...`.
+- For a CRUD-backed entity, create the validated table in the managed
+  development database first. Then make
+  `jskit generate crud-server-generator scaffold ...` the first JSKIT scaffold.
 - Unless the table is already owned by a JSKIT baseline package or is an explicit narrow exception recorded in `.jskit/table-ownership.json`, every persisted app-owned table must go through that server CRUD step first.
 - That server scaffold is the crucial first step even if no CRUD UI will be created yet.
 - 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.
@@ -64,6 +93,19 @@ When a weird-custom persistence lane is proposed:
 - Record the exact approval and the approved exception in `.jskit/WORKBOARD.md` before coding.
 - If that exception changes the durable architecture rather than only the current chunk, record it in `.jskit/APP_BLUEPRINT.md` too.
 - Without that explicit approval record, do not take the weird-custom persistence path.
+- Record durable, approved schema exceptions in `.jskit/APP_BLUEPRINT.md` as
+  well as the table-ownership exception; an exception must not silently weaken
+  the normal generated CRUD contract.
+
+Before reporting completion:
+
+- verify there are no composite primary or foreign keys in the generated CRUD
+  tables
+- verify every generated CRUD foreign key targets a single-column primary key
+- apply the generated migrations from zero to a fresh disposable database
+- compare the recreated schema with the intended development schema
+- run positive and negative cross-workspace relationship tests where ownership
+  applies, then run JSKIT Doctor and the project's normal verifier
 
 Avoid:
 

package/reference/autogen/packages/crud-server-generator.md

@@ -68,6 +68,7 @@ Local functions
 - `renderJsonRestSearchSchemaLines(columns = [])`
 - `renderJsonRestDefaultSortLine(columns = [])`
 - `renderResourceDefaultSortLiteral(columns = [])`
+- `renderCurrentTimestampExpression(expression, column)`
 - `renderMigrationDefaultClause(column)`
 - `renderMigrationSpecificStringType(column, { tableCollation = "" } = {})`
 - `renderTemporalColumnBuilder(column, methodName)`

package/reference/autogen/packages/database-runtime-mysql.md

@@ -44,15 +44,19 @@ Local functions
 - `toBoolean(value)`
 - `toNullableNumber(value)`
 - `normalizeColumnDefault(value)`
+- `normalizeCurrentTimestampExpression(value)`
+- `normalizeOnUpdateExpression(value)`
 - `parseEnumValues(columnType = "")`
 - `resolveTypeKind(column)`
 - `normalizeColumn(row = {})`
 - `normalizePrimaryKeyColumns(rows = [])`
+- `normalizePrimaryKeyColumnsByTable(rows = [])`
 - `normalizeIndexes(rows = [])`
 - `normalizeForeignKeys(rows = [])`
 - `normalizeCheckConstraints(rows = [])`
 - `requireIdColumn(columns, idColumn)`
 - `requirePrimaryKeyContainsId(primaryKeyColumns, idColumn)`
+- `requireSupportedForeignKeys(foreignKeys, primaryKeyColumnsByTable)`
 
 ### root
 

package/reference/autogen/packages/workspaces-web.md

@@ -353,6 +353,8 @@ Exports
 ### `templates/src/surfaces/admin/index.vue`
 Exports
 - None
+Local functions
+- `adminChildPath(suffix = "")`
 
 ### `templates/src/surfaces/admin/root.vue`
 Exports

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

@@ -465,7 +465,7 @@ Exports
 - `isSensitiveManagedTextRecord({ packageEntry = {}, record = {} } = {})`
 - `isSensitivePackageOption(packageEntry = {}, optionName = "")`
 - `isSensitiveTextMutation({ packageEntry = {}, mutation = {}, resolvedKey = "" } = {})`
-- `resolveSensitiveOptionEnvFallbacks({ packageEntry = {}, appRoot = "", optionInput = {}, readFileBufferIfExists } = {})`
+- `resolveSensitiveOptionEnvFallbacks({ packageEntry = {}, appRoot = "", optionInput = {}, readFileBufferIfExists, environment = process.env } = {})`
 - `sanitizeInstalledPackageRecordForLock(record = {}, packageEntry = {})`
 - `sanitizeLockSecretsForWrite(lock = {}, packageRegistry = null)`
 - `sanitizeManagedTextForLock(packageEntry = {}, managedText = {})`
@@ -550,8 +550,9 @@ Local functions
 - `cookieHeader(setCookie = [])`
 - `responsePayload(response = {})`
 - `upstreamError(payload = {}, response = {}, extra = {})`
+- `request(fetchImpl, href, options)`
 - `postJson(fetchImpl, href, body, headers = {})`
-- `readSession(fetchImpl, targetOrigin, setCookie = [])`
+- `readSession(fetchImpl, targetOrigin)`
 - `logout(fetchImpl, targetOrigin, session)`
 - `login(fetchImpl, targetOrigin, identity, secret, session)`
 

package/templates/app/AGENTS.md

@@ -7,4 +7,7 @@ Recommended references:
 - `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`
 - `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md`
 
+Before database, schema, CRUD, repository, or persistence work, read and follow
+`node_modules/@jskit-ai/agent-docs/patterns/crud-scaffolding.md`.
+
 Keep changes scoped to the user request and verify runtime behavior with tests or explicit checks.