@astram/guide 0.2.16 → 0.2.17

package/CAPABILITIES.md

@@ -461,6 +461,41 @@ imports: [
   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.
 
+## In-app notifications (G-027 step 2; core 1.13, guard 0.24, identity 0.20)
+- **One store, per user and company.** Each notice belongs to one user in one company. A user
+  reads only the notices of the company their session is in (`POST /auth/scope-switch` switches
+  the inbox). Read/unread state is kept per notice.
+- **The user's own API** (session bearer, no grant needed; service-account keys get 401):
+  `GET /account/notifications?category=&unread=&page=&limit=` (newest first, `limit` ≤ 100,
+  `{ total, rows, page, limit }`), `GET /account/notifications/unread-count`
+  (`{ announcement, personal, total }`), `POST /account/notifications/:uuid/read` (204),
+  `POST /account/notifications/read-all?category=` (`{ updated }`). Another user's or company's
+  notice is a 404, like a missing one. Restricted sessions (re-enrolment, mandatory 2FA) get 403.
+- **Register your kinds** once: `ShieldModule.forRoot({ notificationKinds: [{ kind:
+  'naes.import_review', category: 'personal' }] })`. A kind is dotted lower-case
+  (`^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$`, ≤ 64); `shield.` is reserved. A bad or duplicate entry
+  fails boot. `category` is `announcement` (release news, notices to many) or `personal`.
+- **Post** with `NotificationService` (inject `SHIELD_NOTIFICATIONS` from `@astram/guard`):
+  `post({ tenantId, recipients, kind, title, body?, link?, dedupeKey? }, { query? })` ⇒
+  `{ created, skipped }`. `post` trusts its caller: take `tenantId` (and the recipients) from the
+  server side (the session, the record you just wrote), never from a request body or query.
+  Only active users with an active membership in `tenantId` receive it;
+  everyone else is skipped, not an error. `dedupeKey` (1–64 of `A–Z a–z 0–9 . _ : -`) makes a
+  retry safe: a repeat for the same user and company inserts nothing. Keys compare exactly (case
+  counts) and are shared by every kind, so put the kind in the key (`import_review:<id>`). Pass `{ query }` from an open
+  transaction to commit or roll back the notices with your write. An unregistered kind throws
+  `NotificationKindError`; bad text throws `NotificationValidationError` (names the field); a
+  database error throws `NotificationUnavailableError`.
+- Limits: `title` 1–160 characters, `body` ≤ 1000 (line breaks allowed), `link` ≤ 512 and an
+  app-relative path (`/…`, no `//`, scheme or `\`), 1–1000 recipients per call; no control
+  characters. Notices are plain text: render them as text, never HTML.
+- **Never put** passwords, tokens, keys, other users' data or full record payloads in a notice;
+  name only what concerns its recipient.
+- Retention: read notices are deleted after `NOTIFICATION_READ_RETENTION_DAYS` (90), every notice
+  after `NOTIFICATION_MAX_RETENTION_DAYS` (365), counted from posting; an hourly job does it.
+- Not yet: personal notices when a user's access changes (G-027 step 3), admin tasks for new
+  permissions (step 4), the frontend-core service and the scaffold bell (step 5), email delivery.
+
 ## 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:

package/package.json

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