@astram/guide 0.2.14 → 0.2.16

package/CAPABILITIES.md

@@ -429,6 +429,38 @@ imports: [
 - `actionsOf(reg)` (`@astram/guard`) returns a registration's vocabulary. `actionsFor(typeKey)`
   is deprecated and returns only the CRUD verbs for every type.
 
+## Permission labels and first-seen dates (G-027 step 1; engine 0.16, guard 0.23, identity 0.19)
+- **Declare text for every action of your types**, CRUD included:
+  `@ObjectType({ ..., label: 'Weld repair rate value', permissions: { read: { label: 'Weld repair
+  rate: view', description: 'See the monthly repair rate per site.', caution: '…' }, … } })`.
+  `label` is the type's human name. Each `permissions` entry needs a `label`; `description` and
+  `caution` are optional (the caution is for a warning an administrator should read before
+  granting, e.g. "Give only to roles that see every site").
+- Limits, checked at boot (`RegistrationError` naming the type, action and field): label 1–80
+  characters, description ≤ 255, caution ≤ 300 (after trimming), no control characters or line
+  breaks, and only actions the type declares (CRUD unless `crudActions: false`, plus `actions`).
+  An empty description or caution is refused: leave the field out instead.
+- **No text ⇒ a generated label** `"<type label>: <verb>"` (read → view, create → create, update →
+  edit, delete → delete, a custom `manage_keys` → "manage keys"; the type label is `label` or the
+  type key with `_` → space), and boot logs ONE warning naming your keys with no declared label
+  and those with no description. The framework declares text for all of its own keys.
+- **The catalog shows it**: `GET /identity/permission-catalog` rows carry `label`, `description`,
+  `caution`, `firstSeenAt` and `firstSeenVersion` (frontend-core `PermissionCatalogRow`; render
+  `label`, keep the raw `key` to a details view). `GET /identity/record-policies/schema` returns
+  the type `label`. The catalog reconcile (shortly after boot, then hourly) rewrites stored text
+  to match your code.
+- **The text is visible to every tenant.** The catalog is one list for anyone who may read
+  roles, in every company. Never put customer, company or person names, or anything specific to
+  one tenant, in a label, description or caution.
+- **First seen**: when the catalog first stores a key it records the date and `APP_RELEASE` (an
+  optional env value, 1–64 characters of letters, digits, `. _ + -`; a git tag or sha fits; an
+  invalid value stops boot; unset ⇒ date only). It is written once and never changed: a key
+  removed and added back keeps its first date. Keys already in the catalog when this release is
+  installed have no first-seen date. Set `APP_RELEASE` in your deploy (and `.env`).
+- Two releases running side by side (a rolling deploy) each write their own text on reconcile,
+  so labels can alternate until the old instances stop. First-seen data is not affected.
+- Text never grants anything: grants, the grant ceiling, wildcards and `decide()` are unchanged.
+
 ## 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:
@@ -587,7 +619,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.14",
+  "version": "0.2.16",
   "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",