@astram/guide 0.2.10 → 0.2.12

package/CAPABILITIES.md

@@ -187,10 +187,23 @@ imports: [
   service is built without `IdentityFeatureModule.forRoot`) when no credential was made.
   Once your `EmailSender` works, `POST /auth/forgot-password` reaches the user. A user whose email
   is set later stays locked until the next `bootstrap:org` run gives them a credential.
-- **Role owner.** Every role records an owner company when it is created: a non-root admin's
-  active company; none when root creates it in the admin UI (a shared, root-only role). It cannot
-  be changed by update. Deleting a company clears the owner of its roles. This round records
-  ownership only: which roles an admin can see or administer is unchanged.
+- **Roles belong to one company** (G-013, ADR-0047). A role is assigned only in its own company
+  (postings and service accounts; 400 otherwise, root included), read and managed through the owner
+  wall (a parent company's admins manage their subsidiaries' roles; out of reach ⇒ 404), and its name
+  is unique within its company only (409 names the existing role). `GET|POST
+  /identity/companies/:companyUuid/roles`; `POST /identity/roles` creates the role in the caller's
+  active company (400 "Choose a company for the role." without one). Role routes need
+  `identity:company:read` (the `access-admin` bundle grants it). An ownerless role (seeded without
+  `r_owner_company_uuid`) is root-only and assignable nowhere.
+- **Departments and branches belong to one company** (G-012). `POST
+  /identity/companies/:companyUuid/departments` and `/branches` (`{ name }`), `PUT` (rename) and
+  `DELETE` on `/identity/departments/:uuid` and `/identity/branches/:uuid`; the list routes are walled
+  and return `{ rows: [{ uuid, name, usedBy? }], total, page, limit }` (`?page&limit&search`). Names
+  are unique per company ignoring case and accents (409); delete is refused (409) while any posting
+  uses the row; at most 1000 of each per company. Access bundle `org-structure`.
+- **The active membership is always `active`** (G-011): `PUT /identity/memberships/:uuid` refuses
+  activating a non-active membership or moving the active one off `active` (409), and a body that
+  sets `isActive: true` with another status (400).
 - **Security policies (mandatory 2FA, ADR-0045).** `GET|POST /identity/security-policies`,
   `GET|PUT|DELETE /identity/security-policies/:uuid` (permissions
   `identity:security_policy:{read,create,update,delete}`; no access bundle carries them). Any holder
@@ -233,7 +246,8 @@ imports: [
   `ASTRAM_BOOTSTRAP_OPERATOR`. Root passwords: `ASTRAM_BOOTSTRAP_ROOT_PASSWORD_<USERNAME>` (a
   `secret-ref:` outside development/test, so a `SECRETS_PROVIDER` is needed) or `--interactive`.
   Other flags: `--reissue-links`, `--link-ttl-hours <1..168>` (default 72), `--links-to-stdout`,
-  `--claim-unowned-roles`. Runs hold a database lock.
+  `--claim-unowned-roles` (a no-op notice since roles belong to one company). Runs hold a database
+  lock.
 - **First sign-in.** Non-root users get a locked credential and a one-time set-password link,
   printed once, to a terminal only (`--links-to-stdout` sends them to a pipe, where logs can keep
   them). The operator delivers each link; the user redeems it at the reset page. Outside
@@ -241,9 +255,11 @@ imports: [
 - **Roots.** The run prints each root's uuid and a `SHIELD_ROOT_IDS=…` line: set it and restart
   (`rootIdsFromEnv`, above).
 - **Re-runs and new tenants.** Additive and idempotent: a second `--apply` writes nothing. A file
-  covers only the tenants it declares, so onboard a new tenant with a new file. A role name owned by
-  another tenant is a `conflict` (roles are still global by name); an unowned role needs
-  `--claim-unowned-roles`.
+  covers only the tenants it declares, so onboard a new tenant with a new file. Roles, departments
+  and branches are created in the company that declares them, and the same name may exist in
+  another company. A posting must use a role declared on its own company (a role declared only on a
+  parent is a file error). After renaming a department or branch in the app, rename it in the file
+  too, or a re-run creates the old name again.
 - **What it does NOT do.** No deletes, renames, moves or revokes (differences are reported only);
   it never activates an inactive membership or updates a changed email. No upload from the UI.
   Department and branch admin routes are separate. With `emailSender` configured, `--email-links`
@@ -308,7 +324,11 @@ imports: [
   joins the outer transaction.
 - `transaction(fn)` runs several pipe calls in one unit of work (rolls back on any failed write);
   `lockForUpdate(typeKey, id)` serialises a check-then-write.
-- `@Field({ immutable: true })` create-only fields; `trusted` fields are stamped server-side.
+- `@Field({ immutable: true })` create-only fields; `@Field({ nullable: true })` fields that
+  create, update and `createMany` may set to NULL (`json` included: SQL NULL, not `"null"`;
+  the audit row lists the cleared keys, never values; the column must be NULL-able in your
+  migration; refused on trusted, primary-key, `readScope` and `required` fields). Without
+  `nullable`, `null` is a validation error. `trusted` fields are stamped server-side.
   `readScope` declares the subtree wall; `create: 'unscoped'` opts a type out of the create wall.
 - **Physical wall** — the raw DB pool is sealed in the engine. The scaffold's
   `server/eslint.config.mjs` fails lint on driver imports, raw pools, `.query()` and the
@@ -321,6 +341,28 @@ imports: [
   (a Rule-4 STOP). Field types this version: `string`, `number`, `boolean`, `uuid`, `timestamp`,
   `json`.
 
+## Shared reference data: global types (ADR-0046; engine 0.11, guard 0.20)
+- **Declare** `@ObjectType({ ..., access: { plane, global: true } })` for rows every tenant reads the
+  same (code lists, catalogues, units). No tenant field, no `readScope`. Registration refuses
+  `global` with `tenantScoped`, `owned`, `system`, a `readScope`, a `trusted: 'tenantId'` field,
+  `crudActions: true` or any action other than `read`, naming the type.
+- **Reads** (list, get, `aggregate()`, search) carry no tenant clause, but the type's `read` grant
+  and deny policies still apply: a caller without `read` sees nothing. Root follows the plane:
+  `plane: 'data'` keeps root denied, `plane: 'control'` lets root read.
+- **Writes** through the engine (create, update, delete, `createMany`) are refused for everyone,
+  root included, before any SQL. Seed and change rows only in an app migration, idempotent and
+  select-before-insert on the business key.
+- **Policies do not cascade.** A record policy on a global type applies only to callers whose
+  active tenant is the policy's tenant, plus platform policies; a parent's deny does not reach its
+  child companies' users. To hide a row across a group, author the policy in each tenant or as a
+  platform policy.
+- **No sharing, no cross-tenant reach**: a global type is never `owned`, so never a share target.
+- **Tenant-less data types are now refused writes.** A `plane: 'data'` type with no tenant field,
+  no `readScope` and not global refuses non-root create, update, delete and `createMany`
+  (`AuthorizationDeniedError('tenantless_data_write_denied')`). Boot logs the global types once and
+  warns once per such type: make it global, give it a tenant field, or add a `readScope`.
+- Never fake shared data with a match-all `readScope`, and never put tenant data in a global type.
+
 ## Custom object actions (ADR-0038; engine 0.7, guard 0.14, identity 0.11)
 - **Declare domain verbs on the type**: `@ObjectType({ ..., actions: ['activate', 'review'] })`.
   The type's vocabulary is `read, create, update, delete` plus the declared actions, and each one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guide",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "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",