@jskit-ai/agent-docs 0.1.283 → 0.1.285

package/guide/agent/framework/crud-operations.md

@@ -13,10 +13,15 @@ Take database, surface, access, ownership, operations, and fields from product
 intent and current source. Ask when a material choice is missing. Do not
 translate the work into generator options.
 
-Read the narrow package-owned pattern in the [source pattern
-library](/patterns/): `crud/resource-contract` for the resource,
-`crud/json-api-resource-package` for the server, and `crud/crud-screen-set`
-for routed UI. Child-resource and row-policy patterns own those variations.
+Read the package-owned pattern in the [source pattern
+library](/patterns/): `database/table-resource` for the table,
+`crud/crud-contract` for its HTTP surface,
+`crud/crud-feature-package` for the server, and `crud/crud-screen-set`
+for routed UI; the [row
+policies](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/heuristics/row-policies.md)
+and [child
+CRUDs](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/heuristics/child-cruds.md)
+heuristics cover those variations.
 
 Normal CRUD tables use one non-null integer primary key. Foreign keys are
 single-column; composite unique indexes are business constraints, not
@@ -26,26 +31,38 @@ Match visibility to real ownership and test allowed plus cross-owner cases.
 ## Author the resource normally
 
 1. Write an immutable app-owned migration.
-2. Define the shared resource contract through `defineCrudResource()`.
-3. Use `defineCrudJsonApiFeature()` for standard repository, service, action,
-   permission, resource-host, and route mechanics.
+2. Define the table resource with `defineTableResource()` and its HTTP surface
+   with `defineCrudContract()`, which names its `namespace`: the routes',
+   messages' and events' public name, never taken from the resource.
+3. Use `defineCrudFeature()` for standard table ownership, service, action,
+   permission, and route mechanics.
 4. Customize through `decorateRepository`, `decorateService`,
    `operationLifecycle`, and named `actions`; do not copy the standard CRUD
    repository/action/route stack.
 5. Build routed screens from the matching `http-web`/CRUD UI pattern.
 
-The resource is canonical for fields, operations, validation, transport,
-messages, and route parameters. Do not duplicate its schema or serializers.
+The table resource is canonical for fields, columns, ownership and search; the
+CRUD contract for operations, validation, transport, messages and route
+parameters. A contract shows and accepts only the fields its `fields` names (stored
+`createdAt` and `updatedAt` show without an entry; `createdAt: { output:
+false }` hides one), so a column added later stays out of every API until a
+contract names it. A CRUD feature's answers follow the same rule: an unnamed
+relationship is left out, and an included record shows only its id, its
+relation's `labelKey` and the fields the including contract lists in that
+field's `output.includeFields` (`{ breed: ["name"] }` in the list shows a
+record it links to, as deep as listed), never another contract's output.
+A package with a CRUD feature lists `crud.contracts` in its descriptor's
+`capabilities.requires`. Do not duplicate their schema or serializers.
 Prefer `useCrudListScreen()`, `useCrudViewScreen()`, and
 `useCrudAddEditScreen()`; use `useCommand()` or `useEndpointResource()` for
 non-standard operations.
 
 Add resource service methods with `decorateService`; expose commands such as
-`confirm`, `publish`, or `cancel` through named `actions`. With `operationLifecycle`, mutation `before`,
-`execute`, and `after` share one repository transaction, `execute` receives
-`standard(nextInput)`, and `afterCommit` follows commit. Repositories persist;
-services and hooks orchestrate. Use a transactional outbox for durable
-external work.
+`confirm` or `cancel` through named `actions`. With `operationLifecycle`, mutation `before`,
+`execute`, and `after` share one transaction, rerun on deadlock, so they touch
+only the database; `execute` receives `standard(nextInput)`. Outside effects go
+in `afterCommit`, run once after commit, or an outbox when durable.
+Repositories persist; services and hooks orchestrate.
 
 ## Choose ownership, API access and client access independently
 
@@ -53,37 +70,31 @@ These controls answer different questions:
 
 | Control | Purpose | Public records | Owner-scoped records |
 | --- | --- | --- | --- |
-| Resource `autofilter` | Which rows belong to the request scope | `"public"`; no ownership column | `"user"`; real non-null `userId` column |
-| Resource `apiAccess` | Who may call the API | `"public"` | `"authenticated"` |
-| Feature `ownershipFilter` | Server route/action ownership scope | `"public"` | `"user"` |
+| Table resource `ownership` | Which rows belong to the request scope | `"public"`; no ownership column | `"user"`; real non-null `userId` column |
+| CRUD contract `apiAccess` | Who may call the API | `"public"` | `"authenticated"` |
+| Feature route visibility | Server route/action scope: the table's `ownership` unless the feature names `visibility` | `"public"` | `"user"` |
 | Client `access` | Whether to require bootstrap permissions | Default `"auto"` with no permission requirements | Default `"auto"`; declare permissions when required |
 
-`access` accepts `auto`, `always`, or `never`, not `public`. With `auto`, a
-screen with no permission requirements does not require a permissions bootstrap.
-`always` does require it. Do not add authentication or workspace machinery to
-compensate for an unnecessary `always` override. Server access and ownership
+`access` accepts `auto`, `always`, or `never`, not `public`. `auto` requires a
+permissions bootstrap only for a screen with permission requirements; `always`
+always does. Do not add authentication or workspace machinery to
+make up for an unneeded `always` override. Server access and ownership
 remain authoritative.
 
-The Books source patterns demonstrate user ownership. For an intentionally
-public create/list resource, use the same patterns with this resource contract:
+The Books source patterns show user ownership. For a public create/list
+resource, use them with this table resource and CRUD contract:
 
 ```js
-const bookResource = defineCrudResource({
-  namespace: "books",
+const bookResource = defineTableResource({
+  name: "books",
   tableName: "books",
-  apiAccess: "public",
-  autofilter: "public",
-  crudOperations: ["list", "view", "create"],
+  ownership: "public",
   schema: {
     title: {
       type: "string",
       required: true,
       minLength: 1,
-      maxLength: 255,
-      operations: {
-        output: { required: true },
-        create: { required: true }
-      }
+      maxLength: 255
     }
   },
   searchSchema: {
@@ -96,20 +107,27 @@ const bookResource = defineCrudResource({
     }
   }
 });
+
+const bookCrud = defineCrudContract(bookResource, {
+  namespace: "books",
+  apiAccess: "public",
+  operations: ["list", "view", "create"],
+  fields: { title: { output: "required", create: "required" } }
+});
 ```
 
-Import `defineCrudResource` from
-`@jskit-ai/resource-crud-core/shared/crudResource`. Its app-owned migration
-creates `books` with an integer primary key `id` and non-null `title`; omit
-`userId` and its foreign key for this public variant. `list` requires `view`
-in the shared resource contract, even when the UI has no detail page. A create
-response uses the resource output contract. Keep operation names such as
-`list`, `view` and `create`; do not invent output-operation aliases.
-
-Bind `defineCrudJsonApiFeature()` with this resource, `ownershipFilter:
-"public"`, `relativePath: "/books"` and the application's configured public
-surface. Keep the existing package/provider and migration registration from
-`crud/json-api-resource-package`.
+Import `defineTableResource` from `@jskit-ai/resource-core/shared/tableResource`
+and `defineCrudContract` from `@jskit-ai/resource-crud-core/shared/crudContract`.
+Its migration creates `books` with an integer `id` and non-null `title`; omit
+`userId` and its foreign key.
+`list` requires `view` in the CRUD contract, even when the UI has no detail
+page. A create response uses the CRUD contract's output. Keep operation names
+such as `list`, `view` and `create`; do not invent output-operation aliases.
+
+Bind `defineCrudFeature()` with `crud: bookCrud`, `relativePath: "/books"`
+and the application's configured public surface; the table's `"public"`
+ownership makes its routes public. Keep the existing package/provider and migration registration from
+`crud/crud-feature-package`.
 
 For the list, keep `BookListPage.vue` thin: use `resourceNamespace: "books"`
 in `useCrudListScreen()` on the configured public surface, remove unsupported