@astram/guide 0.2.5 → 0.2.7

package/CAPABILITIES.md

@@ -313,16 +313,86 @@ upload(@Req() req: Record<string, unknown>) {
   the upload check.
 - **Lint wall** — the scaffold bans `multer`, `@aws-sdk/*`, `minio`, `fs` / `node:fs` (and
   `/promises`) in `src/features/**`: use `FileIntake` and `FilesService`, never the bucket.
-- Do not grant `stored_file:create` to app roles; uploads go through `FilesService`.
+- Roles that upload need `stored_file:create` (FilesService creates the record as the caller), but app code must create `stored_file` rows only through `FilesService.store()` — never `records.create('stored_file', …)` / `createMany`, which would let a caller set its own `storageKey` (downloads still refuse a key outside the caller's tenant, KI #137).
 - Not provided: malware scanning, per-tenant encryption of file bytes (SSE-S3 only), streaming
   downloads, dedup (each upload is its own record; `sha256` is returned so you can detect repeats).
 
+## Database names and several environments on one server (`SHIELD_DB_NAMESPACE`, ADR-0037)
+- The framework uses four databases, `<ns>_app`, `<ns>_identity`, `<ns>_authz` and `<ns>_audit`,
+  with its own accounts (`<ns>_core`, `<ns>_migrate`, `<ns>_audit_ops`, …). If you leave
+  `SHIELD_DB_NAMESPACE` unset, `<ns>` is `shield` (`shield_app`, …), which is unchanged from
+  earlier releases.
+- **To run dev and beta on one MariaDB server**, give each environment its own namespace. It must
+  be lowercase letters and digits only (`beta`, `staging2`; no `_`). Then:
+  1. Provision it with the framework's `db-provision --namespace beta` (from the astram-framework
+     repo, runbook §6). Use distinct passwords per namespace.
+  2. Set `SHIELD_DB_NAMESPACE=beta` for both the server and `npm run migration:run`. The same
+     value must reach both.
+  3. Run migrations (the ledger is `beta_app.schema_migrations`), then start the server.
+- Defaults follow the namespace: `APP_DB_USER` ⇒ `<ns>_core`, `APP_DB_NAME` ⇒ `<ns>_identity`,
+  `DDL_DB_USER` ⇒ `<ns>_migrate`. Explicit values win.
+- **Rules your app must follow:**
+  - `APP_DB_NAME` must be one of the four framework databases, even with the namespace unset.
+    Any other value refuses to boot.
+  - An invalid namespace refuses to boot and to migrate.
+  - Use a separate Redis (instance or DB index) per environment: Redis keys are not namespaced.
+  - Your own object types keep a literal `schema` or none. Do not hard-code `shield_*` names in
+    app SQL or migrations: read them from the injected `FRAMEWORK_SCHEMAS` (`@astram/guard`).
+- **Boot check:** outside development/test (an unset `NODE_ENV` counts as production), the server
+  refuses to start when framework migrations are missing from the ledger, no ledger is found, or
+  the ledger is unreachable. Run `migration:run` before starting. With the namespace unset, the
+  server looks for the ledger in `DDL_DB_NAME`, its own `APP_DB_NAME`, then `shield_app`, so
+  `migration:run` with the server's `.env` is found. If your migrate job uses a different
+  `APP_DB_NAME`, set the same `DDL_DB_NAME` for migrate and the server.
+- The `<ns>_backup` and `<ns>_monitor` accounts keep server-wide grants and can see every
+  namespace on the server.
+- One database per account (some managed hosts): see the single-database layout below.
+
+## Single-database layout (`SHIELD_DB_LAYOUT=single`, ADR-0041, opt-in, reduced isolation)
+- For hosts that give one database per account. The four-database layout stays the default.
+- **Set:** `SHIELD_DB_LAYOUT=single`, `SHIELD_DB_NAME=<db>` (`^[a-z0-9_]{1,64}$`),
+  `SHIELD_DB_LAYOUT_ACK_REDUCED_ISOLATION=1` (exactly `1`, every environment, production
+  included), `APP_DB_USER`. Leave `SHIELD_DB_NAMESPACE` unset; `APP_DB_NAME`/`DDL_DB_NAME` unset
+  or `<db>`. Same values for the server and `npm run migration:run`. Anything else refuses to boot
+  and to migrate.
+- **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.
+- 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`,
+  `company_departments`, `company_branches`, `service_account`, `shared_resource`, `stored_file`,
+  `identity_credential`, `session`, `refresh_token`, `mfa_device`, `password_reset_token`,
+  `mfa_recovery_code`, `email_change_token`, `permission`, `role_permission`,
+  `authz_permission_version`, `access_bundle`, `access_bundle_permission`,
+  `record_permission_rule`, `record_share`, `scope_closure`, `service_account_key`,
+  `cross_tenant_grant`, `audit_log`, the ledger `schema_migrations`) or `prune_audit`. In single
+  mode a clash refuses to boot (object type) or to migrate (`CREATE TABLE` in your migrations);
+  in the four layout it only warns, so you see it early. The migration check reads whole files,
+  `down()` included: an app whose migrations ever created or renamed onto a reserved name cannot
+  migrate in single mode.
+- **One account** (`DDL_DB_*` unset ⇒ `APP_DB_*`): migrations and the server share the account
+  (`ALL PRIVILEGES ON <db>.*`). You lose append-only audit (#6), no runtime DDL and schema
+  separation (#11), the DB-enforced retention floor, and the separate DDL account; `audit:prune`
+  refuses to run. Boot logs this list every time (the privilege probe runs with
+  `ShieldModule.forRoot({ auth: true })`).
+- **Two accounts** (if the host allows a second user): the framework repo's
+  `db-provision --layout single` keeps `audit_log` append-only and the runtime free of DDL, and
+  installs `prune_audit`; re-run it after a migration adds a table. Schema separation is still lost.
+- Choose the layout at install: switching an existing install is not supported. MariaDB only.
+
 ## Migrations (`@astram/migrate`)
 - `migrate` / `migrate:revert` / `migrate:status` with the deploy-time DDL account (`DDL_DB_*`);
   the running app never holds DDL. Framework migrations merge with yours (`APP_MIGRATION_DIR`).
 - Numeric ordering, duplicate-id detection, a database lock so concurrent deploys never apply a
   migration twice (`APP_MIGRATION_LOCK_TIMEOUT`, default 120 s), and drift detection (a changed
   applied file is reported; `--strict` fails on it). Never edit a migration that already ran.
+- Upgrade `@astram/migrate` together with `@astram/guard` and `@astram/identity`. The framework
+  migrations read the database names from the migrate context (`ctx.schemas`). An older migrate
+  works only while `SHIELD_DB_NAMESPACE` is unset, and stops with "upgrade @astram/migrate"
+  otherwise. On upgrade, `migrate:status --strict` reports the framework's rewritten migrations as
+  SUPERSEDED, not drift, and `migrate` updates their ledger rows without re-running them.
 
 ## Frontend (`@astram/frontend-core`, `@astram/sdk`, scaffolded `frontend/`)
 - `@astram/frontend-core`: auth, account, identity, audit, record-policy, share, cross-tenant and

package/package.json

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