@astram/guide 0.2.13 → 0.2.15

package/CAPABILITIES.md

@@ -429,6 +429,59 @@ imports: [
 - `actionsOf(reg)` (`@astram/guard`) returns a registration's vocabulary. `actionsFor(typeKey)`
   is deprecated and returns only the CRUD verbs for every type.
 
+## Separation of duties (ADR-0048; core 1.12, engine 0.14, guard 0.21, identity 0.18)
+- **Declare it on the type** when the people who started or asked about a record must not
+  approve it:
+  ```ts
+  @ObjectType({
+    typeKey: 'my_batch',
+    actions: ['approve'],
+    separationOfDuties: [{
+      actions: ['approve'],
+      actorFields: ['createdBy'],
+      related: [{ typeKey: 'my_review_request', via: 'batchUuid', actorFields: ['createdBy'] }],
+    }],
+    // ...
+  })
+  ```
+  `approve` is then denied (403) to whoever created the batch and to whoever created any
+  `my_review_request` row whose `batchUuid` is this batch, whatever their grants, owner
+  rights, shares or cross-tenant grants. No one is exempt: service accounts, delegated
+  operations and root (on a control-plane type) are bound too. Check it with
+  `records.authorize('my_batch', id, 'approve')`; an `update`/`delete` bound by the rule is
+  checked by the write itself. `records.authorizeType(typeKey, action)` refuses an action the
+  rule binds (`RegistrationError`): a type-level check cannot apply it. List both types in
+  `extraObjects`.
+- What counts: the record's own `actorFields` (`trusted: 'actorId'` fields, or `uuid` fields
+  declared `immutable: true`, so nobody named can clear them first) and every related row's
+  `actorFields` (`trusted: 'actorId'` fields only, e.g. `createdBy`), every related row whatever
+  its status or tenant. Related rows are found by a `uuid` field that holds this record's id
+  (`via`, "down" only): declare the action on the record that others point at, and create a
+  related row only after reaching its `via` record (`records.get` / `authorize`).
+- The rule reads the related rows that exist now: a requester who deletes their request is no
+  longer named. Do not grant `delete` on the related type to the people it names; cancel
+  requests through a status field instead (a cancelled row still counts).
+- It needs the authority `IdentityFeatureModule` builds (not the legacy `decisionAuthority`
+  option) and a single installed `@astram/engine`; otherwise every bound action is denied.
+- What it never does: bind `read` or `create` (boot refuses both), filter lists, or write an audit
+  row for the deny. If the principals cannot be read (a related value that is not a string, more
+  than 1,000 distinct people on one related field) the action is denied. A value of
+  `shield.separationOfDuties` that the engine did not build is dropped before the decision.
+- Inside `records.transaction(fn)` the check holds a shared lock on the related rows it read, so
+  a new review request cannot be added between the check and your write; commit promptly. This
+  needs the MariaDB default isolation (REPEATABLE READ) and an index on the `via` column. An
+  approver and a requester racing can deadlock (MariaDB error 1213): retry the transaction.
+- A bad declaration (undeclared action, unknown field, an own actor field that is neither `uuid`
+  nor `trusted: 'actorId'`, an own `uuid` actor field not declared `immutable: true`, a related
+  actor field that is not `trusted: 'actorId'`, a `via` that is
+  not an untrusted `uuid` field, unregistered related type, a tenant-scoped type pointing at a
+  type with no tenant column) fails boot with `RegistrationError`.
+- **Tenant policies on people fields**: a `trusted: 'actorId'` field (e.g. `createdBy`) is a
+  reference to `user`, and `@Field({ references: 'user' })` marks any other field as one. Record
+  policies may then use `is_owner` / `is_not_owner` on it ("is me" / "is not me" in the
+  scaffolded builder), e.g. deny `activate` where `createdBy` is me. A tenant admin can delete
+  such a policy: use the declared rule above for anything the app requires.
+
 ## File upload and object storage (`@astram/guard` + `@astram/identity`)
 One file per request, kept in a private S3/MinIO bucket with SSE-S3, with a `stored_file` record
 on the record pipe. You write no storage, MIME or authorization code.
@@ -534,7 +587,19 @@ upload(@Req() req: Record<string, unknown>) {
 - **Set `POOL_MAX_ENGINE`** (e.g. 10). Unset, the engine pool uses `APP_DB_MAX_CONNECTIONS`, and
   the single-layout budget `workers × (POOL_MAX_CORE + POOL_MAX_ENGINE + APP_AUTHZ_POOL_MAX) +
   headroom` fails boot. `APP_DB_MAX_USER_CONNECTIONS` (the account's cap, if the host sets one) is
-  checked too.
+  checked too. The budget also counts 1 connection per worker for the audit sealer's own pool.
+- **Set `POOL_WORKERS` and `APP_DB_MAX_CONNECTIONS` too** (your real worker count and what the
+  server gives you). Their defaults (8 workers, 250) describe a dedicated four-database server; on
+  them the single-layout budget is 8 × 27 + 40 = 256 > 250 and boot fails.
+- **Idle connections and timeouts (G-026, both layouts):** the `POOL_MAX_*` values are caps. Idle,
+  every framework pool shrinks to `POOL_MIN_IDLE` (default 1) after `POOL_IDLE_TIMEOUT_S` (default
+  600), so an idle process holds about 4 connections. Optional `APP_DB_QUERY_TIMEOUT_MS`
+  (1000–3600000) aborts a longer statement (the framework's lock waits and the sealer are exempt);
+  optional `POOL_LEAK_DETECTION_MS` logs a connection held longer. Invalid values fail boot. Never
+  build or patch a pool to tune these; if a setting is missing, flag a gap.
+- **Shutdown:** `main.ts` must call `app.enableShutdownHooks()` (the scaffold does; add it to an app
+  scaffolded before G-026). Then a SIGTERM stops the framework's jobs, finishes in-flight requests
+  and closes every pool. Set PM2 `kill_timeout` (e.g. 5000 ms) above the shutdown time.
 - All framework tables keep their names in `<db>`; your tables live there too. **Reserved
   table names:** your object types and migrations must not use a framework table name (`companies`,
   `users`, `roles`, `departments`, `branches`, `company_membership`, `membership_posting`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guide",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "license": "MIT",
   "description": "Astram framework — the AI/dev GUIDE layer (ADR-0025). Ships the framework's hard rules + capabilities manifest as installed, upgrade-refreshed docs. A consumer app's CLAUDE.md references FRAMEWORK_RULES.md from this package; `npm update` replaces it wholesale so new rules arrive cleanly, while the app's own .astram/guide/ layer is never touched. This is the framework-owned FLOOR: an app rule may tighten it, never weaken it.",
   "type": "commonjs",