@astram/guide 0.1.0

package/CAPABILITIES.md

@@ -0,0 +1,58 @@
+<!--
+  @astram/guide — CAPABILITIES.md   (framework-owned, version 0.1.0)
+
+  What the Astram framework provides THIS version. Refreshed on upgrade (ADR-0025).
+  Use this to answer "does the framework already do X?" before building — and, if it
+  does NOT, that's a Rule-4 gap (STOP and flag in .astram/guide/gaps.md).
+-->
+
+# Astram Framework — Capabilities (v0.1.0)
+
+The building blocks the framework provides. Consume these; do not reimplement them.
+
+## Enforcement (`@astram/guard`)
+- **Global deny-by-default guard** — every route is denied unless `@Public()` or
+  `@Classified({ typeKey, action })`.
+- **Request authentication** — a `@Classified` route resolves the bearer access token
+  → `Principal` → `decide()` automatically. `request.principal` is available to the
+  handler (act as the logged-in user).
+- **The ONE seam** — `ShieldModule.forRoot({ auth?, credentialResolver?, decisionAuthority?, config? })`.
+
+## Auth surface (`@astram/guard`, opt-in `auth: true`)
+- `POST /auth/login` `{ identityHint, password }` → `{ session, tokens }` (or an MFA challenge).
+- `POST /auth/mfa` · `POST /auth/refresh` · `POST /auth/logout`.
+- Argon2id password verification, sessions, refresh-token rotation + reuse detection,
+  opaque access tokens bound to the principal (server-revocable; logout = immediate kill).
+- MFA/TOTP.
+- You provide: a `CredentialResolver` (reads your users) + a `DecisionAuthority` (your policy).
+
+## The record pipe (`@astram/engine`)
+- **`RecordEngine`** (token `RECORD_ENGINE`) — create/read/update/delete/list over
+  registered tables, through one unbypassable pipe: permission gate (`decide()`) →
+  server-trusted write-context (anti-forgery) → validate → write (real table) →
+  junction sync → audit → event.
+- **Cross-tenant isolation** — a `tenantId`-trusted field auto-scopes reads AND writes
+  to the actor's tenant.
+- **Physical wall** — the raw DB pool is sealed in the engine; feature scope never
+  receives it. Off-road DB access fails the build (the app's `eslint.config.js`).
+- **Gap signal** — an unsupported field type / operation throws
+  `CapabilityNotSupportedError` (a Rule-4 STOP).
+- Field types supported this version: `string`, `number`, `boolean`, `uuid`,
+  `timestamp`, `json`. (Anything else → flag a gap.)
+
+## Migrations (`@astram/migrate`)
+- Deploy-time code-table migration runner: timestamped `up()`/`down()` files, a
+  `schema_migrations` table, `migrate` / `migrate:revert` / `migrate:status`. Raw SQL
+  through a DDL-capable deploy account (the running app never holds DDL).
+
+## Frontend SDK (`@astram/sdk`)
+- Platform-agnostic fact projection for building UIs against the framework.
+
+## NOT provided yet (as of v0.1.0) — these are Rule-4 gaps if you need them
+- Runtime (no-code) object definition / admin-defined objects + runtime DDL.
+- Formula / lookup / rollup computed fields (the pipe's compute stage is a no-op).
+- Business-rule events (the pipe's emit-event stage is a no-op).
+- Extension-field sidecar (runtime custom fields on a registered table).
+- Membership-scoped list filtering (e.g. "companies I belong to").
+
+If you need one of these, STOP and flag it in `.astram/guide/gaps.md` (Rule 4).

package/FRAMEWORK_RULES.md

@@ -0,0 +1,110 @@
+<!--
+  @astram/guide — FRAMEWORK_RULES.md   (framework-owned, version 0.1.0)
+
+  This file is the FRAMEWORK layer of the two-layer AI guide (ADR-0025). It is
+  installed in node_modules and REPLACED WHOLESALE on `npm update` — never edit it
+  in your repo (your edits would be lost on upgrade, and it is not yours to change).
+  Put YOUR project's rules in `.astram/guide/` instead; those are never touched by an
+  upgrade.
+
+  These are the framework's HARD RULES — the FLOOR. A project rule in `.astram/guide/`
+  may ADD to or TIGHTEN a rule here, but may NEVER weaken or override one. The
+  never-touch-core / never-bypass-enforcement rules are non-overridable, full stop.
+-->
+
+# Astram Framework — Hard Rules (the floor)
+
+You are building features on the **Astram framework** — a sealed security kernel your
+app installs read-only. These rules are non-negotiable. If a project rule in
+`.astram/guide/` appears to relax one of these, the framework rule wins.
+
+## 0. After a framework upgrade, RE-READ this file first
+
+The framework evolves. When the app's `@astram/guide` version changes (a framework
+upgrade — `npm update`), this file is replaced with a newer one that may add rules or
+capabilities. **Before continuing feature work after any upgrade, re-read this file
+and `CAPABILITIES.md` from `node_modules/@astram/guide/`** so you are working against
+the current rules, not a stale memory of them. Your project's own rules in
+`.astram/guide/` are unchanged and still apply on top.
+
+## 1. NEVER edit or bypass the framework
+
+The framework packages (`@astram/core`, `@astram/guard`, `@astram/engine`,
+`@astram/migrate`, `@astram/sdk`, `@astram/guide`) live in `node_modules` and are
+**immutable**. Do not edit them, patch them, monkey-patch them, or reach around their
+public API. You register your app through the ONE seam — `ShieldModule.forRoot(...)` —
+and consume the exported building blocks. That is the entire contract.
+
+- **`@astram/core` is especially sacred.** It is the pure security engine. It has no
+  reason to be imported directly by feature code and must never be modified.
+
+## 2. All data access goes through the RecordEngine pipe — never raw DB
+
+Feature code must **never** touch the database directly: no `mariadb`/`mysql`/`pg`/
+`typeorm` import, no `DataSource`, no `QueryRunner`, no `SHIELD_DB_POOL`, no
+repository `.save()`/`.query()`. Every create/read/update/delete goes through the
+injected **`RecordEngine`** (`@astram/engine`, token `RECORD_ENGINE`), which applies
+the permission gate, validation, audit, and cross-tenant isolation on every write —
+by construction.
+
+This is enforced two ways: the raw DB pool is **sealed inside the engine module** (you
+cannot inject what you are not given), and the app's `eslint.config.js` **fails the
+build** on any off-road DB access under `src/features/**`. If you find yourself
+wanting a raw query, see Rule 4.
+
+## 3. Classify every route (deny-by-default)
+
+Every HTTP route is DENIED by the global enforcement guard unless you classify it:
+- **`@Public()`** — an explicit, code-reviewed open route (login, health probes).
+- **`@Classified({ typeKey, action })`** — a guarded route. The framework resolves the
+  request's bearer token → `Principal` → `decide()` and allows only on `allow`. No
+  token → 401; denied → 403.
+
+An unclassified route is a 403, by design — a forgotten declaration locks the door
+instead of silently exposing it. Never make a route public to "make it work"; classify
+it correctly.
+
+## 4. When the framework can't do it: STOP and FLAG the gap — do NOT work around it
+
+This is the most important rule. When a feature needs a capability the framework does
+not provide — an unsupported field type, a missing engine operation, an auth capability
+that isn't there — **you must STOP**. Do not:
+- reach into or edit the core/framework to add it,
+- hand-roll a raw-SQL / off-pipe workaround,
+- weaken a classification or security check to get past it.
+
+Instead, **record the gap** in `.astram/guide/gaps.md` (a short entry: what capability
+is missing, where it was needed, why). The gap is a signal to the **framework team** to
+implement the capability properly, into the framework. Once the framework provides it
+(a new version), you resume the feature against the real capability.
+
+The framework surfaces many gaps for you: the engine throws a typed
+`CapabilityNotSupportedError` naming exactly what's missing. Treat that error as a STOP
+signal, not something to catch-and-work-around.
+
+## 5. Never surface raw UUIDs (or secrets) to end users
+
+Resolve internal ids to human-readable labels before they reach a UI or a response a
+user sees. Never put a password, hash, token, or secret in a response body or a log.
+
+## 6. Auth is the framework's; you provide only DATA + POLICY
+
+You do not write login/session/token code — the framework owns it (`ShieldModule
+.forRoot({ auth: true })` gives you `POST /auth/{login,mfa,refresh,logout}` for free).
+Your app contributes exactly two things through the seam:
+- a **`CredentialResolver`** — reads YOUR user/identity tables to answer "what's this
+  user's password hash, tenant, roles?",
+- a **`DecisionAuthority`** — your allow/deny policy.
+
+Never reimplement session handling, token verification, or password hashing in app
+code. If the auth surface lacks something you need, that's Rule 4 (flag the gap).
+
+## 7. Fail closed, always
+
+On any ambiguity or error in a security path — deny. Never "allow on error", never
+default-open, never swallow a security failure into a success.
+
+---
+
+*These rules are the framework floor. Your project's rules (in `.astram/guide/`) add to
+them. On upgrade, this file is refreshed (Rule 0) and your project rules are preserved.*

package/index.js

@@ -0,0 +1,28 @@
+/**
+ * @astram/guide — programmatic access to the framework guide docs.
+ *
+ * The docs (FRAMEWORK_RULES.md, CAPABILITIES.md) are the real payload; this module
+ * just exposes their absolute paths + the guide version so a consumer's sync step can
+ * copy them into `.claude/rules/` (see the scaffolded app's `sync-astram-guide` script).
+ * The version travels with the framework, so a consumer can detect an upgrade.
+ */
+
+'use strict';
+
+const { join } = require('node:path');
+
+/** Absolute path to the framework hard-rules file (the floor, ADR-0025). */
+const FRAMEWORK_RULES_PATH = join(__dirname, 'FRAMEWORK_RULES.md');
+
+/** Absolute path to the capabilities manifest for this framework version. */
+const CAPABILITIES_PATH = join(__dirname, 'CAPABILITIES.md');
+
+/** The guide version (== the framework release it ships with). */
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { version } = require('./package.json');
+
+module.exports = {
+  FRAMEWORK_RULES_PATH,
+  CAPABILITIES_PATH,
+  version,
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@astram/guide",
+  "version": "0.1.0",
+  "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",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./FRAMEWORK_RULES.md": "./FRAMEWORK_RULES.md",
+    "./CAPABILITIES.md": "./CAPABILITIES.md",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "FRAMEWORK_RULES.md",
+    "CAPABILITIES.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}