@jskit-ai/agent-docs 0.1.87 → 0.1.90

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

@@ -197,11 +197,15 @@ In JSKIT persistence code, **visibility** means "which rows should this request
 - `public`
   - the record is not scoped by owner columns
 - `workspace`
-  - the record belongs to one workspace, usually through `workspace_id`
+  - the record belongs to one workspace through the exact reserved column `workspace_id`
 - `user`
-  - the record belongs to one user, usually through `user_id`
+  - the record belongs to one user through the exact reserved column `user_id`
 - `workspace_user`
-  - the record belongs to one workspace and one user together
+  - the record belongs to one workspace and one user through both reserved columns
+
+Only `workspace_id` and `user_id` carry this standard ownership contract. Specifically named foreign keys such as `recipient_user_id`, `created_by_user_id`, and `assignee_user_id` describe domain relationships; they are not alternate owner columns. Keep both fields when a row has an owner and a separate related actor, and never rename the relationship to an owner column merely to make a tool accept the schema.
+
+The selected ownership filter must match the direct reserved columns exactly. A table with only `workspace_id` is `workspace`; a table with only `user_id` is `user`; and a table with both is `workspace_user`. A declaration cannot override or ignore either column.
 
 That is why the shared helpers exist. Repositories should not have to re-implement the same ownership rules by hand every time they filter a query or build an insert payload.
 

package/guide/agent/generators/advanced-cruds.md

@@ -33,7 +33,8 @@ npx jskit generate crud-server-generator scaffold \
   --namespace contacts \
   --surface admin \
   --ownership-filter workspace \
-  --table-name contacts
+  --table-name contacts \
+  --grant-role member
 
 npx jskit generate crud-ui-generator crud \
   w/[workspaceSlug]/admin/contacts \
@@ -140,6 +141,8 @@ So the distinction is:
 
 That is why `--internal` is not a permissions shortcut and not a UI setting. It is a server-route exposure choice on top of the same CRUD ownership model.
 
+The workspace role-grant decision is separate too. Every workspace-required generation must choose `--grant-role <role-id>` or `--no-role-grant`; there is no implicit role. An application that assigns generated CRUD permissions to `member` uses `--grant-role member`. In particular, `--internal` does not imply `--no-role-grant`.
+
 ### Ownership controls which owner columns are expected
 
 The repository layer ultimately applies visibility through the standard owner columns:
@@ -147,6 +150,12 @@ The repository layer ultimately applies visibility through the standard owner co
 - `workspace_id`
 - `user_id`
 
+Those names are exact and reserved. `workspace_id` is workspace ownership; `user_id` is user ownership; both together are workspace-user ownership. Other foreign keys such as `recipient_user_id`, `created_by_user_id`, and `assignee_user_id` remain domain relationships and must not be treated as ownership aliases.
+
+The generated ownership filter must match that exact set of reserved columns. Neither an explicit filter nor generated metadata can override what those direct columns mean.
+
+If a row is workspace-owned but refers to a recipient, keep both concepts explicit: use `workspace_id` for ownership and `recipient_user_id` for the relationship. Renaming the relationship to `user_id` would opt the field into JSKIT's hidden owner-field and user-filtering behavior.
+
 That means the generated CRUD behaves like this:
 
 - `public`

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

@@ -99,6 +99,27 @@ The supported values are:
 | `workspace` | rows belong to one workspace | `workspace_id` |
 | `workspace_user` | rows belong to one workspace and one user together | `workspace_id` and `user_id` |
 
+### Ownership column names are exact and reserved
+
+JSKIT ownership is explicit and materialized. Only these exact database columns carry the standard generated ownership contract:
+
+- `workspace_id`
+- `user_id`
+
+They are not ordinary foreign-key names. Generated CRUD infrastructure uses them for visibility filtering, create-time owner stamping, and hidden owner-field handling.
+
+Other foreign keys are domain relationships, even when their names end in `_user_id` or `_workspace_id`. For example:
+
+- `recipient_user_id` identifies a recipient
+- `created_by_user_id` records an author
+- `assignee_user_id` identifies an assignee
+
+Those fields do not become ownership aliases merely because they point to a user-owned table.
+
+The ownership filter must match the direct reserved columns exactly. A table with only `workspace_id` is `workspace`; one with only `user_id` is `user`; and one with both is `workspace_user`. Neither the CLI declaration nor generated metadata overrides those columns.
+
+Decide ownership first, select the matching ownership filter, and then model other actors with specifically named foreign keys. A workspace-owned notification outbox item that targets a user normally has `workspace_id` for ownership and `recipient_user_id` for the recipient relationship. Do not rename `recipient_user_id` to `user_id` merely to satisfy a generator or Doctor check; that would change the resource's ownership semantics.
+
 ### What each value means
 
 #### `public`
@@ -257,7 +278,8 @@ npx jskit generate crud-server-generator scaffold \
   --namespace contacts \
   --surface admin \
   --ownership-filter workspace \
-  --table-name contacts
+  --table-name contacts \
+  --grant-role member
 ```
 
 This creates an app-local package under `packages/contacts/`.
@@ -278,6 +300,46 @@ Use that when:
 
 Do **not** use `--internal` as a substitute for ownership or permissions design. It is only about whether the public HTTP CRUD routes exist.
 
+### Choose workspace role grants explicitly
+
+Workspace-required CRUD actions use the normal named permission ids:
+
+- `crud.<namespace>.list`
+- `crud.<namespace>.view`
+- `crud.<namespace>.create`
+- `crud.<namespace>.update`
+- `crud.<namespace>.delete`
+
+The generator never guesses which role should receive all five permissions. Every workspace-required CRUD command must choose one of these options:
+
+```bash
+--grant-role administrator
+```
+
+or:
+
+```bash
+--no-role-grant
+```
+
+`--grant-role` must name a configured role. `--no-role-grant` keeps the generated actions and their permission requirements but leaves the app's role catalog unchanged. The options are mutually exclusive.
+
+To assign the generated permissions to `member`, make that decision explicit:
+
+```bash
+--grant-role member
+```
+
+This decision is independent of `--internal`. For an internal, workspace-owned persistence resource whose generated actions should not be assigned to any actor role, use both:
+
+```bash
+--ownership-filter workspace \
+--internal \
+--no-role-grant
+```
+
+If neither explicit grant option is supplied, generation fails during preflight before writing files, even when a `member` role exists.
+
 Before generating anything, decide these with the developer:
 
 - which operations are allowed for this CRUD
@@ -420,7 +482,8 @@ npx jskit generate crud-server-generator scaffold \
   --namespace addresses \
   --surface admin \
   --ownership-filter workspace \
-  --table-name addresses
+  --table-name addresses \
+  --grant-role member
 ```
 
 Then install the generated local package:
@@ -596,7 +659,8 @@ npx jskit generate crud-server-generator scaffold \
   --namespace comments \
   --surface admin \
   --ownership-filter workspace \
-  --table-name comments
+  --table-name comments \
+  --grant-role member
 ```
 
 Then install the generated local package:

package/guide/agent/generators/row-policies.md

@@ -515,7 +515,7 @@ The `json-rest-api` package owns exhaustive framework tests for pagination, coun
 
 ## AnyAPI comes later
 
-`json-rest-api@1.0.25` can apply row policies with `RestApiAnyapiKnexPlugin`. JSKIT's current `internal.json-rest-api` host installs `RestApiKnexPlugin`, so the code in this chapter targets normal tables.
+`json-rest-api@1.0.26` can apply row policies with `RestApiAnyapiKnexPlugin`, including grouped predicates evaluated after the policy hook returns. JSKIT's current `internal.json-rest-api` host installs `RestApiKnexPlugin`, so the code in this chapter targets normal tables.
 
 Do not add backend detection, fallback queries, or an `isAnyApi` branch to the normal-table policy in anticipation of a host that does not exist.
 

package/package.json

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

package/patterns/crud-scaffolding.md

@@ -24,6 +24,9 @@ Rules:
 - 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.
 - Do not scaffold CRUD UI, hand-build CRUD routes, or hand-build CRUD endpoints before the server CRUD package and shared resource file exist.
 - Treat the generated shared resource file as the canonical CRUD contract for later UI scaffolding and CRUD behavior changes.
+- Treat the exact columns `workspace_id` and `user_id` as reserved JSKIT ownership columns. They are the only standard columns used for generated ownership filtering and create-time owner stamping.
+- Treat other foreign keys such as `recipient_user_id`, `created_by_user_id`, `assignee_user_id`, and similarly specific names as domain relationships, not ownership aliases. Do not rename a relationship to `user_id` or `workspace_id` merely to satisfy tooling.
+- Require the resolved ownership filter to match the reserved columns exactly: neither the filter nor the schema may silently add or omit `workspace_id` or `user_id` ownership.
 - `feature-server-generator` is not the default lane for ordinary persisted entities. Use it for workflows or orchestration that sit on top of CRUD-owned tables, or for rare explicit non-CRUD exceptions.
 - Generated CRUD UI must be compact-first. Lists need searchable cards on compact widths and tables only for medium/expanded layouts.
 - Generated CRUD list screens need real loading, empty, and error states. Empty copy should name the resource, such as "No customers yet", and offer the create action when available.
@@ -41,6 +44,14 @@ Meaning of `--internal`:
 - it keeps the generated repository, service, actions, provider, resource, and CRUD migration ownership chain
 - it only suppresses public HTTP CRUD route registration
 - it is not a substitute for ownership columns or action/route permissions
+- it does not suppress generated action permission ids or decide which role receives them
+
+Workspace role grants:
+
+- every workspace-required CRUD generation must explicitly choose `--grant-role <role-id>` or `--no-role-grant`
+- applications that assign generated CRUD permissions to `member` must say `--grant-role member`; fixed-role applications must name one of their real roles or choose no automatic grant
+- `--grant-role` and `--no-role-grant` are permission-design choices independent of `--internal`
+- never invent a `member` role only to satisfy the generator
 
 When a weird-custom persistence lane is proposed:
 

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

@@ -21,13 +21,16 @@ Exports
 - `resolveGenerationSnapshot({ appRoot, tableName, idColumnOption } = {})`
 - `renderCanonicalResourceFieldSchema(column, { fieldContractEntry = null } = {})`
 - `buildFieldContractEntries({ outputColumns = [], writableColumns = [], snapshot = {} } = {})`
-- `resolveCrudGenerationSurfaceId({ appRoot, options } = {})`
+- `resolveCrudGenerationSurfaceId({ appRoot, options, appConfig = null } = {})`
+- `prepareInstallHook({ appRoot, packageOptions = {} } = {})`
 - `__testables`
 Local functions
 - `resolveAllowedValues(schema = {}, fallbackValues = [])`
 - `resolveGlobalScaffoldCache()`
 - `asRecord(value)`
+- `resolveBooleanFlagOption(options = {}, optionName = "")`
 - `resolveInternalRouteOption(options = {})`
+- `resolveNoRoleGrantOption(options = {})`
 - `normalizeRequestedOwnershipFilter(value, { strict = false } = {})`
 - `inferOwnershipFilterFromSnapshot(snapshot)`
 - `assertOwnershipColumnsForFilter(snapshot, filter)`
@@ -36,7 +39,7 @@ Local functions
 - `loadEnvFromApp(appRoot)`
 - `createAppRequire(appRoot)`
 - `importModuleFromApp(appRequire, moduleId, contextLabel)`
-- `resolveCrudSurfaceRequiresWorkspace({ appRoot, options, surface = "" } = {})`
+- `resolveCrudSurfaceRequiresWorkspace({ appRoot, options, surface = "", appConfig = null } = {})`
 - `loadCrudAppConfig(appRoot = "")`
 - `resolveSurfaceDefinitions(appConfig = {})`
 - `resolveDefaultCrudSurfaceIdFromAppConfig(appConfig = {})`
@@ -84,8 +87,11 @@ Local functions
 - `normalizeFieldMetaUiOptions(rawOptions = [])`
 - `resolveEnumFieldMetaUiOptions(enumValues = [])`
 - `buildCrudPermissionIds(namespace = "")`
+- `resolveConfiguredRoleEntries(appConfig = {})`
+- `formatAvailableRoleIds(roleEntries = [])`
+- `resolveCrudPermissionGrantRole(appConfig = {}, options = {}, { requiresNamedPermissions = true } = {})`
 - `normalizeCrudOperation(operation = "", context = "CRUD operation")`
-- `renderRoleCatalogPermissionGrants(namespace = "", { requiresNamedPermissions = true } = {})`
+- `renderRoleCatalogPermissionGrants(namespace = "", { requiresNamedPermissions = true, grantRoleId = "" } = {})`
 - `renderActionPermissionSupport(namespace = "", { requiresNamedPermissions = true } = {})`
 - `renderActionPermissionExpression(operation = "", { requiresNamedPermissions = true } = {})`
 - `renderRouteWorkspaceSupportImports({ surfaceRequiresWorkspace = true } = {})`
@@ -96,7 +102,7 @@ Local functions
 - `renderObjectSchemaDefinition(lines = [], { mode = "patch" } = {})`
 - `renderActionInputExpressions({ surfaceRequiresWorkspace = true } = {})`
 - `renderRouteValidatorConstants({ surfaceRequiresWorkspace = true } = {})`
-- `buildReplacementsFromSnapshot({ namespace = "", snapshot, resolvedOwnershipFilter, surfaceRequiresWorkspace = true, surfaceId = "", routeInternal = false })`
+- `buildReplacementsFromSnapshot({ namespace = "", snapshot, resolvedOwnershipFilter, surfaceRequiresWorkspace = true, surfaceId = "", routeInternal = false, permissionGrantRoleId = "" })`
 - `resolveCrudGenerationTableName(options = {})`
 - `createCacheKey({ appRoot, options })`
 - `buildCrudTemplateContext(input = {})`