ADR-008: relocate the multi-tenancy framework to NetKingdom canon
Multi-tenancy is part of the IT-security framework NetKingdom provides, so it belongs beside the IAM Profile and the tenant-engine boundary contract rather than in the work-factory canon. Operator decision. Relocation surfaced two things a review would have caught embarrassingly late. NetKingdom's accepted platform-identity-security-architecture has used the word plane since July for a trust and deployment layer - bootstrap, platform control, tenant. This framework was using the same word for an independent dimension of concern. Two senses of one word in one canon is precisely the concept-ownership collision the estate is careful about, and the newcomer yields: they are now axes. The rename is also just better, since a posture vector is a point in five-dimensional space. That same document also disproves the framework's opening line. It has described the trust model, the tenant model and a capability progression since 2026-07-23, so the claim that the estate had never written down what it was building was wrong. The accurate and narrower claim is that nothing said how far a given service had got, or could hold several answers at once. Stub left behind so the ADR-008 identifier resolves. The renderer moved to policy-nexus, which owns publication. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
codex
parent
1c65257352
commit
1674ea550d
3 changed files with 21 additions and 1290 deletions
|
|
@ -1,741 +1,34 @@
|
|||
---
|
||||
id: ADR-008
|
||||
type: architecture-decision-record
|
||||
title: "Tenancy Posture: Five Planes, Graduated Levels, Declared Conformance"
|
||||
status: proposed
|
||||
title: "Multi-Tenancy Framework — relocated to NetKingdom"
|
||||
status: superseded
|
||||
decided_by: Bernd Worsch
|
||||
date: "2026-08-17"
|
||||
revision: "draft-4"
|
||||
tags: ["architecture", "multi-tenancy", "isolation", "placement", "retention", "maturity", "tenant-engine", "flex-auth", "rapp-postgres", "scaling"]
|
||||
---
|
||||
|
||||
# ADR-008: Tenancy Posture — Five Planes, Graduated Levels, Declared Conformance
|
||||
# ADR-008 — relocated
|
||||
|
||||
## Status
|
||||
Drafts 1–4 of the multi-tenancy framework were written here. On 2026-08-17 the
|
||||
operator determined that multi-tenancy is part of the IT-security framework
|
||||
NetKingdom provides, so the framework belongs in NetKingdom canon beside the
|
||||
IAM Profile and the tenant-engine boundary contract.
|
||||
|
||||
**Proposed, draft-4.**
|
||||
**It now lives at `net-kingdom/canon/standards/tenancy-posture_v0.1.md`.**
|
||||
|
||||
- **draft-1** proposed a single model with fixed characteristics. Rejected: it
|
||||
could not describe a repo that is not there yet.
|
||||
- **draft-2** reframed to graduated levels per plane. Externally corroborated
|
||||
(§16), but four of its statements were wrong and one thing it needed was
|
||||
missing.
|
||||
- **draft-3** applied those corrections, added the retention plane, and
|
||||
recorded an adoption stance.
|
||||
- **draft-4** closes the two gaps draft-3 left open: `R4` had no mechanism
|
||||
beyond waiting, and the noisy-neighbour evidence artifact asserted something
|
||||
shared infrastructure cannot provide. Both were found by research, not by
|
||||
review.
|
||||
Two things changed on relocation:
|
||||
|
||||
Informed by five external research digests in `research/2026-08-17-adr008-*`,
|
||||
which carry full citations for every external claim made here.
|
||||
1. The five dimensions were renamed from **planes** to **axes**. NetKingdom's
|
||||
accepted `platform-identity-security-architecture` already uses *plane* for
|
||||
a trust and deployment layer (bootstrap / platform control / tenant), and
|
||||
two senses of one word in one canon is a concept-ownership collision.
|
||||
2. The opening claim that the estate "has never written down what it is
|
||||
building" was corrected. That architecture document has described the trust
|
||||
and tenant model since 2026-07-23. What was actually missing is a way to say
|
||||
how far a given service has got.
|
||||
|
||||
Reviewed by nobody yet. §19 lists what each owner is being asked to accept.
|
||||
This stub remains so that the ADR-008 identifier resolves rather than
|
||||
dangling. It is not a second copy and must not be edited as one.
|
||||
|
||||
## 1. Context
|
||||
|
||||
The estate has been building multi-tenancy for months and has never written
|
||||
down what it is building. Five documents each cover a slice:
|
||||
|
||||
| Document | Covers | Status |
|
||||
|---|---|---|
|
||||
| `iam-profile_v0.3` (NetKingdom) | Tenant identifier shape, `tenant_roles` claim, staleness rules | Ratified |
|
||||
| `tenant-engine-boundary-contract_v0.1` (NetKingdom) | Who owns tenant records, roles, plan assignment | Ratified |
|
||||
| `business-app-service-contract_v0.1` §1 (Custodian) | Business apps: instance-per-client, tenant-keyed data | Ratified |
|
||||
| `rapp-postgres` ADR-0001 | Consumer + tenant isolation in PostgreSQL | Proposed, governs one repo |
|
||||
| `rapp-postgres` ADR-0002 | Per-consumer retention and the erasure horizon | Proposed, governs one repo |
|
||||
| `shared-platform-relational-storage_v0.1` | The stacked-boundary gap | Routed 2026-08-10, **still unratified** |
|
||||
|
||||
Four failures follow.
|
||||
|
||||
**The gap was diagnosed once and the fix stalled.** The v0.1 draft was written
|
||||
to fill this hole and has sat unratified in neither canon directory. §20
|
||||
attaches a ratification path so this one does not join it.
|
||||
|
||||
**Placement is owned by nobody.** `user-engine-pg` and `target-revenue-pg` are
|
||||
dedicated; `apps-pg`, `net-kingdom-pg`, `platform-pg`, `state-hub-db` and
|
||||
`forgejo-db` are shared. Both live, neither written down. `tenant-engine`
|
||||
raised this with `railiance-platform` on 2026-08-16; unanswered.
|
||||
|
||||
**Two contradictory defaults are already ratified.** Business apps get
|
||||
instance-per-client; platform services pool. Nothing says which shape a new
|
||||
service takes, and no definition separates the categories.
|
||||
|
||||
**There is no honest way to describe a repo that is not there yet.** The estate
|
||||
absorbs repos with weak or absent tenant separation. Today such a repo is
|
||||
simply non-conformant, leaving it two bad options: misrepresent its posture, or
|
||||
stay outside the framework.
|
||||
|
||||
## 2. What this document is
|
||||
|
||||
**A framework, not a model.** It specifies no single correct implementation. It
|
||||
supplies terminology (§3, §4), a declaration (§5), a conformance rule (§6),
|
||||
methodology (§12), and evidence definitions (§13).
|
||||
|
||||
A service is conformant when its declared posture is accurate and its
|
||||
trajectory recorded. A service is non-conformant when it claims a level it
|
||||
cannot evidence — regardless of how high or low that level is.
|
||||
|
||||
## 3. Five orthogonal planes
|
||||
|
||||
"Is this multi-tenant?" is treated as one question. It is five, and they are
|
||||
independent:
|
||||
|
||||
| Plane | Question | Vocabulary owner |
|
||||
|---|---|---|
|
||||
| **Identity (I)** | How is a tenant named and validated? | `tenant-engine` / IAM Profile |
|
||||
| **Authorization (A)** | How is a request bound to the tenants it may act for? | `flex-auth` |
|
||||
| **Enforcement (E)** | Where, mechanically, is the tenant boundary enforced? | This framework |
|
||||
| **Placement (P)** | Which substrate holds a tenant's data? | `railiance-platform` |
|
||||
| **Retention (R)** | How long does data persist, and how is it erased? | The storage platform; policy by the consumer |
|
||||
|
||||
Conflation produces errors today. `rapp-postgres`'s `PostgresConsumer` carries
|
||||
`tenantIsolation: consumer-service-boundary` — an **E**-plane fact in a
|
||||
**P**-plane artifact, reading as though storage enforces something it does not.
|
||||
The "dedicated versus shared" argument mixes P (capacity, blast radius) with E
|
||||
(correctness).
|
||||
|
||||
The planes are separated *precisely so each may sit at a different level*.
|
||||
|
||||
**Decision 3.1:** every document, declaration and plan tier that says
|
||||
"isolation" MUST name which plane it means.
|
||||
|
||||
**Decision 3.2:** the planes couple at their tops and the couplings MUST be
|
||||
stated where they apply, not used to argue the planes are one:
|
||||
|
||||
- `E4` is reachable only at `P3` or above.
|
||||
- `R`'s erasure horizon is bounded below by `P` — on shared substrate, a
|
||||
consumer's horizon is the instance maximum (§4.5).
|
||||
- `R4` by key destruction is bounded by the **key boundary**, which is an
|
||||
E-plane property. Shredding a single tenant's data requires the application
|
||||
to encrypt under a per-tenant key before writing; the storage platform cannot
|
||||
supply it. **Reaching the top of the retention ladder is not a retention
|
||||
project.**
|
||||
|
||||
**Decision 3.3 — scope.** The P and R ladders describe a service's **primary
|
||||
datastore**. Caches, search indices, message queues and background jobs are
|
||||
named leak surfaces in the external baselines and are assessed separately, not
|
||||
covered by a posture vector. Saying so is honest; implying the vector covers
|
||||
them would not be.
|
||||
|
||||
## 4. Graduated levels
|
||||
|
||||
Each plane carries an ordered ladder. Higher is stronger, not better: the right
|
||||
level is the one a service can evidence and its risk warrants.
|
||||
|
||||
### 4.1 Identity (I)
|
||||
|
||||
| Level | State |
|
||||
|---|---|
|
||||
| **I0** | No tenant concept. Data not attributable to a tenant. |
|
||||
| **I1** | A local tenant notion exists but is not canonical, **or** the tenant is taken from the request rather than from a verified token. |
|
||||
| **I2** | Canonical identifiers, bound at the identity provider and carried as a verified claim; `tenant-engine` is the source of existence. |
|
||||
| **I3** | I2 plus capability roles honoured, with live `tenant-engine` re-query for privileged, destructive, credential-vending or `aal2`-class decisions. |
|
||||
|
||||
I1 now explicitly absorbs request-supplied tenant identifiers. "Never trust
|
||||
client-supplied tenant IDs without validation" is a named anti-pattern; a
|
||||
service reading the tenant from a header is at I1 however canonical the string.
|
||||
|
||||
`business-app-service-contract` §2.1 sets app-local accounts as the v1 baseline
|
||||
for business apps — a sanctioned low level with recorded triggers for moving
|
||||
up. That is the pattern this framework generalises.
|
||||
|
||||
### 4.2 Authorization (A)
|
||||
|
||||
| Level | State |
|
||||
|---|---|
|
||||
| **A0** | No authorization, or tenant context not carried. |
|
||||
| **A1** | Ad-hoc checks scattered through handlers. |
|
||||
| **A2** | A single local authorization boundary; tenant context bound once, centrally. |
|
||||
| **A3** | Decisions delegated to `flex-auth` as PDP, with live re-query where the IAM Profile requires it. |
|
||||
| **A4** | A3 over a **standard** PDP interface (OpenID AuthZEN Authorization API 1.0), so the decision point is swappable and the enforcement point is not coupled to one engine's request shape. |
|
||||
|
||||
A4 is new. `flex-auth` uses a bespoke `CheckRequest` and a bespoke action
|
||||
vocabulary, with action strings copied verbatim between repos to avoid
|
||||
re-derivation — exactly the coupling AuthZEN removes. The specification reached
|
||||
Final in January 2026 and Keycloak shipped experimental support in May. We are
|
||||
not wrong, we are pre-standard, and the ladder should have somewhere to go.
|
||||
|
||||
**Internal service-to-service calls are in scope for this plane.** "Skipping
|
||||
tenant validation for internal services" is a named anti-pattern, and our
|
||||
estate is mostly internal calls — `flex-auth` calls `tenant-engine`
|
||||
synchronously on the authorization path. A service identity acting on behalf of
|
||||
a tenant must carry and revalidate tenant context to claim A2 or above.
|
||||
|
||||
### 4.3 Enforcement (E)
|
||||
|
||||
| Level | Mechanism |
|
||||
|---|---|
|
||||
| **E0** | None. Data not tenant-keyed; separation incidental or absent. |
|
||||
| **E1** | Data tenant-keyed, filtering applied per query at call sites. |
|
||||
| **E2** | Filtering centralised at a single service-side choke point binding authenticated identity to permitted tenants. |
|
||||
| **E3** | E2 **plus** platform-assisted filtering: row-level security keyed on a tenant GUC set transaction-locally, or an equivalent enforced data-access layer. |
|
||||
| **E4** | Structural: the credential a workload holds cannot address another tenant's data at all. Requires per-tenant credentials and per-tenant substrate. |
|
||||
|
||||
**Correction from draft-2.** Draft-2 described E3 as something "the application
|
||||
cannot trivially route around". That is false and it was this document
|
||||
overclaiming in exactly the way §6 prohibits. Any session can re-issue `SET` on
|
||||
a custom GUC, so an attacker with SQL execution can reset the tenant and read
|
||||
across the boundary. What E3 buys is precise, and the ladder must say so:
|
||||
|
||||
| Threat | E1 | E2 | E3 | E4 |
|
||||
|---|:--:|:--:|:--:|:--:|
|
||||
| A developer forgets a tenant predicate | ✗ | ✓ | ✓ | ✓ |
|
||||
| A new code path bypasses the choke point | ✗ | ✗ | ✓ | ✓ |
|
||||
| SQL injection reaching the connection | ✗ | ✗ | ✗ | ✓ |
|
||||
| The application process is compromised | ✗ | ✗ | ✗ | ✓ |
|
||||
|
||||
E3 is a strong control against **accident** — the common case, and the one that
|
||||
causes real breaches — and no control at all against **compromise**. Only E4
|
||||
holds against both, because the credential itself cannot address another
|
||||
tenant's data.
|
||||
|
||||
**Correction: E3 layers on E2, it does not replace it.** External practice
|
||||
treats application-layer and database-layer filtering as complementary. A
|
||||
service that dropped its choke point on reaching E3 would be *worse* off, since
|
||||
E3 fails open under injection. Claiming E3 therefore requires the E2 evidence
|
||||
artifact as well.
|
||||
|
||||
**Correction: the GUC is set transaction-locally.** Draft-2 said "at pool
|
||||
checkout", which is session scope and the wrong instrument. Under a pooler in
|
||||
statement mode, `SET` leaks between clients and returns other tenants' rows —
|
||||
a failure that appears only under production concurrency and produces no error.
|
||||
Use `SET LOCAL` inside an explicit transaction.
|
||||
|
||||
**Platform enforcement is a platform obligation.** Reaching E3 requires the
|
||||
storage platform to *offer* the mechanism: provisioned policies, a documented
|
||||
GUC contract, and a probe. Where a consumer wants E3 and the platform has not
|
||||
supplied it, the gap is the platform's. §19.6 asks `rapp-postgres` to define
|
||||
that contract, which must carry `FORCE ROW LEVEL SECURITY` on every tenant
|
||||
table (without it the table owner bypasses policies silently, and ADR-0001
|
||||
already established that our migration role owns the tables it creates), no
|
||||
`BYPASSRLS` on leased roles, `SECURITY INVOKER` for ordinary logic, and an
|
||||
`EXPLAIN` comparison because RLS disables functional indexes built on
|
||||
non-leakproof functions.
|
||||
|
||||
**Default expectation** for a new platform service: E2 at first serve, E3
|
||||
recorded as target. Services whose cross-tenant exposure would be a reportable
|
||||
breach SHOULD target E3 or above.
|
||||
|
||||
### 4.4 Placement (P)
|
||||
|
||||
| Level | Shape | Live occupants |
|
||||
|---|---|---|
|
||||
| **P0** | Shares a database with another consumer. | None sanctioned; the state absorbed repos arrive in. |
|
||||
| **P1** | Database per consumer, shared cluster. | `audit-core`, `tenant-engine` on `platform-pg` |
|
||||
| **P2** | Dedicated cluster per consumer. | `user-engine-pg`, `target-revenue-pg` |
|
||||
| **P3** | Dedicated cluster per tenant. | Business apps per `business-app-service-contract` §1.2 |
|
||||
| **P4** | P3 plus separate region or jurisdiction. | None |
|
||||
|
||||
Enforcement and placement are independent axes. Plotted together, with where
|
||||
each service actually sits — parenthesised entries are targets or defaults
|
||||
rather than current positions, and `—` marks a cell the coupling in §3.2 makes
|
||||
unreachable:
|
||||
|
||||
| E \ P | P0 | P1 | P2 | P3 | P4 |
|
||||
|---|---|---|---|---|---|
|
||||
| **E4** | — | — | — | (business app) | |
|
||||
| **E3** | | (target) | | | |
|
||||
| **E2** | | tenant-engine<br>audit-core | | | |
|
||||
| **E1** | (absorbed repo) | | | | |
|
||||
| **E0** | | | | | |
|
||||
|
||||
**P0 → P1 → P2 is movement along the horizontal axis only.** Those steps buy
|
||||
consumer isolation, capacity predictability, independent retention and a
|
||||
smaller operational blast radius. They do not raise the tenant boundary by one
|
||||
step. Only P3 makes E4 reachable. This is the most misusable fact in the
|
||||
framework and §11 governs how it may be described.
|
||||
|
||||
**Decision 4.4.1:** P1 is the default for platform services; P3 for
|
||||
client-facing business apps, as already ratified. A service unsure which it is
|
||||
must resolve that first (§19.4).
|
||||
|
||||
**Decision 4.4.2 — placement scopes to data substrate.** Identity-provider
|
||||
placement (realm-per-tenant versus Organizations) is the same silo/pool
|
||||
decision on a different substrate, is live in our estate, and is undecided.
|
||||
Realm-per-tenant carries a stated ceiling around 5–20 tenants, far below our
|
||||
target. Recorded here as a parallel question (§19.7), not folded into P.
|
||||
|
||||
### 4.5 Retention and erasure (R)
|
||||
|
||||
New in draft-3. Implemented abstractly by the storage platform for any dataset;
|
||||
policy is built on top of that interface by the consumer or its governance
|
||||
layer. Reference implementation: `rapp-postgres` ADR-0002.
|
||||
|
||||
| Level | State |
|
||||
|---|---|
|
||||
| **R0** | No retention or deletion position. Data kept indefinitely by default; no deletion path exists. |
|
||||
| **R1** | Platform default retention applies (N=30 days). The consumer has declared no requirement. |
|
||||
| **R2** | Retention declared as N days per dataset; the **erasure horizon** is published, and the consumer makes no promise shorter than it. |
|
||||
| **R3** | Policy-driven deletion: the consumer or its governance layer declares what is due, the platform sweeps whole datasets on that instruction and evidences each run. |
|
||||
| **R4** | Verified erasure: data proven unrecoverable across live storage, backups and derived copies, by one of the two routes below. |
|
||||
|
||||
**R4 has two routes and a service MUST name which one it uses.**
|
||||
|
||||
| Route | Mechanism | Cost |
|
||||
|---|---|---|
|
||||
| **Horizon-elapsed** | Wait out the published erasure horizon; the data ages out of every retained copy. | Available to everyone, proves little, and the wait is set by a co-resident's retention requirement rather than your own. |
|
||||
| **Key-destroyed** | Encrypt per entity, then destroy the key. Retained copies survive but are unreadable. | Requires per-entity keys, strong encryption, and an auditable destruction record. Immediate. |
|
||||
|
||||
**Regulatory standing of the key-destroyed route, stated carefully because
|
||||
overclaiming here is worse than anywhere else in this framework.** Data
|
||||
protection authorities have accepted key destruction as erasure where physical
|
||||
deletion would be manifestly disproportionate, and the practice is recognised
|
||||
under conditions — strong encryption, irreversible destruction, and an auditable
|
||||
record of it. **The EDPB has not formally endorsed it as Article 17 erasure.** A
|
||||
service reaching R4 by key destruction is making a defensible claim, not a
|
||||
settled one, and must say so rather than reporting a clean "deleted".
|
||||
|
||||
Three further properties.
|
||||
|
||||
**The erasure horizon is the interval between deleting data and it ceasing to
|
||||
be recoverable from anything the platform holds.** Deleting a row does not
|
||||
remove it from yesterday's backup. With an N-day window, deleted data remains
|
||||
recoverable for N days. That is the difference between "deleted" and "erased"
|
||||
and the estate had never written it down.
|
||||
|
||||
**On shared substrate, retention is not per-consumer.** Physical backup is
|
||||
instance-wide — one WAL stream, one window — so the instance retention is
|
||||
*derived* as the maximum across co-resident consumers, and every consumer's
|
||||
horizon is that maximum. A consumer declaring 7 days beside one declaring 90
|
||||
gets 90. This is the retention analogue of ADR-0001's blast-radius disclosure:
|
||||
state the coupling rather than imply an isolation that is not there.
|
||||
|
||||
**Retention is therefore a placement trigger.** A consumer needing a horizon
|
||||
shorter than the instance floor cannot have one at P1. It moves to P2 for a
|
||||
reason with nothing to do with performance — which is exactly why it needs
|
||||
recording, since nobody looks for a retention argument when reviewing
|
||||
placement.
|
||||
|
||||
Deletion splits mechanism from policy. The platform deletes whole **datasets**
|
||||
on instruction and records an opaque policy reference it never interprets, so
|
||||
every deletion traces to what authorised it. Rows are not a dataset: row expiry
|
||||
is the consumer's own DML under its migration lease. Dropping a consumer's
|
||||
whole database is an operator-gated offboarding step, never a scheduled one.
|
||||
|
||||
## 5. The posture vector
|
||||
|
||||
A service states one level per plane, plus a target, a date, and any placement
|
||||
exceptions:
|
||||
|
||||
```yaml
|
||||
tenancy:
|
||||
current: { I: 2, A: 3, E: 2, P: 1, R: 1 }
|
||||
target: { I: 2, A: 3, E: 3, P: 1, R: 2 }
|
||||
reviewed: "2026-08-17"
|
||||
gap:
|
||||
E: "Choke point exists and is tested; RLS not provisioned. Blocked on
|
||||
rapp-postgres publishing the GUC contract. Target Q4."
|
||||
R: "Retention declared; erasure horizon not yet published to consumers."
|
||||
```
|
||||
|
||||
**Placement exceptions.** Draft-2 assigned one P level per service, which
|
||||
cannot express the vertically partitioned model — most tenants pooled, some
|
||||
dedicated — that §11's isolation tiers require. A tier requiring `P2` bought by
|
||||
three tenants would put the service at two levels at once, forcing an over- or
|
||||
under-claim. Placement is therefore declared as a default plus exceptions:
|
||||
|
||||
```yaml
|
||||
placement_exceptions:
|
||||
- tenants: ["tenant:enterprise:*"]
|
||||
P: 3
|
||||
reason: "isolation tier; see adaptive-pricing tier definition"
|
||||
```
|
||||
|
||||
A service with exceptions must be able to say which tenants are on which
|
||||
substrate. That mapping is a first-class artifact, not archaeology.
|
||||
|
||||
Worked examples, best-effort and subject to owner correction:
|
||||
|
||||
| Service | Current | Notes |
|
||||
|---|---|---|
|
||||
| `tenant-engine` | `I2 A3 E2 P1 R1` | Moving to P1 under TEN-WP-0009; retention declared, horizon not yet published. |
|
||||
| `audit-core` | `I2 A3 E2 P1 R1` | Holds audit evidence, so both E3 and R2 are urgent targets. |
|
||||
| A newly absorbed repo | `I1 A1 E1 P0 R0` | Conformant **if declared**, with a recorded path. |
|
||||
|
||||
**Decision 5.1:** the posture vector is declared in the repo, not in the hub,
|
||||
consistent with local-files-are-source-of-truth.
|
||||
|
||||
## 6. Conformance is accuracy, not altitude
|
||||
|
||||
> **A service is conformant when its declared posture is accurate, its target
|
||||
> is recorded, and it does not claim a level it cannot evidence. It is
|
||||
> non-conformant when it overclaims — at any altitude.**
|
||||
|
||||
- Declaring `E0` is conformant. Concealing `E0` is not.
|
||||
- A repo may be absorbed at any posture. It may not be absorbed silently.
|
||||
- No service is blocked from the estate for being low on a ladder. Services MAY
|
||||
be blocked from *specific work* — serving a tenant grouping, holding a data
|
||||
class, carrying a plan tier — by requirements expressed as minimum levels.
|
||||
- Downgrading is permitted and must be declared. A regression found by guarding
|
||||
is a defect; a regression declared in advance is a decision.
|
||||
|
||||
Without the plane separation, "not rigorous about tenant separation" is one
|
||||
verdict a repo passes or fails. With it, the same repo is `I1 A1 E1 P0 R0` with
|
||||
a path — a plan, not an indictment.
|
||||
|
||||
## 7. Portability across placement levels
|
||||
|
||||
Movement between P levels must be operational, not a rebuild:
|
||||
|
||||
- Connect by injected credential only — no cluster, host, namespace or database
|
||||
name in source.
|
||||
- Own a whole database, never tables inside someone else's.
|
||||
- Idempotent schema creation.
|
||||
- No cross-database joins or co-location assumptions.
|
||||
|
||||
**Decision 7.1:** mandatory at P1 and above. At P3, SHOULD rather than MUST — a
|
||||
per-client instance that never moves is not misconformant for naming its own
|
||||
database.
|
||||
|
||||
## 8. Placement triggers
|
||||
|
||||
Recorded at provisioning time: noisy neighbour on a latency-critical path; a
|
||||
compliance or residency requirement; a plan tier requiring a higher minimum; an
|
||||
erasure horizon that no longer fits (§4.5); connection or memory ceiling
|
||||
reached.
|
||||
|
||||
**Decision 8.1:** triggers MUST be *monitored*, not merely recorded. A trigger
|
||||
in a YAML comment nobody re-reads is documentation, not control.
|
||||
|
||||
**Decision 8.2:** placement policy ownership is proposed to
|
||||
`railiance-platform`, **co-signed by `adaptive-pricing`**. Tenancy model
|
||||
selection is a commercial decision as much as a technical one; an
|
||||
operations-shaped repo should not hold it alone.
|
||||
|
||||
## 9. Credentials as a tenancy control
|
||||
|
||||
Short-lived leased credentials re-read at connection checkout, with
|
||||
overlap-first rotation, bound the residual risk at every E level below E4: a
|
||||
leaked credential expires rather than persisting. Stronger than the industry
|
||||
norm of a long-lived per-service secret.
|
||||
|
||||
**Decision 9.1:** static long-lived database credentials are not a sanctioned
|
||||
path for any service above E0.
|
||||
|
||||
## 10. Blast radius must be published
|
||||
|
||||
**Decision 10.1:** every platform holding consumer data MUST publish, in
|
||||
concrete terms, what a leaked runtime credential can and cannot reach at the
|
||||
levels it operates. `rapp-postgres` ADR-0001 §5 is the reference. Where the
|
||||
model cannot provide a guarantee, the platform says so and names the
|
||||
escalation.
|
||||
|
||||
**Decision 10.2 — quotas are disclosed, not discovered.** The same obligation
|
||||
extends from what a leaked credential can reach to what the platform will
|
||||
refuse to do for you. Every consumer MUST be told, at provisioning, the
|
||||
throttles and quotas enforced against it — connection limits, statement
|
||||
timeouts, idle-transaction timeouts — and told again when they change. A
|
||||
consumer learning its statement timeout by hitting it in production is a
|
||||
disclosure failure, not a consumer bug. This is how `tenant-engine` was
|
||||
provisioned, by good practice rather than by rule; the rule now exists.
|
||||
|
||||
## 11. Commercial expression
|
||||
|
||||
- **11.1** Plan tiers are expressed *internally* as minimum levels. A tier may
|
||||
require `E3 P2 R2`; it need not print that anywhere customer-facing.
|
||||
- **11.2** Marketing and product language is free. No requirement to expose
|
||||
level labels or this document. "Dedicated infrastructure", "isolated
|
||||
tenancy", "private instance" all remain available.
|
||||
- **11.3** The constraint is on **evidence, not vocabulary**. A customer-facing
|
||||
isolation, availability or retention claim must map to a minimum level the
|
||||
delivering service actually holds, recorded once when the tier is defined.
|
||||
The review is internal and happens at tier definition — not per campaign.
|
||||
- **11.4** Two hard lines, because these reach contracts and compliance
|
||||
questionnaires:
|
||||
- A claim that another tenant **cannot** reach the customer's data requires
|
||||
**E4**.
|
||||
- A claim that deleted data **is gone** requires **R4**, or an erasure
|
||||
horizon disclosed alongside it. Where R4 is reached by key destruction, the
|
||||
claim is defensible but not settled law (§4.5) — it may be made, and it may
|
||||
not be made in language that implies a regulator has blessed it.
|
||||
|
||||
## 12. Methodology — analyze, establish, improve, guard
|
||||
|
||||
**Analyze.** Assess a repo against the ladders; produce `tenancy.current` with
|
||||
reasoning recorded. Applies to new and absorbed services alike.
|
||||
|
||||
**Establish.** Declare the target and gap. The target is set by data class,
|
||||
tenant groupings served and plan tiers carried — not by ambition.
|
||||
|
||||
**Improve.** Move one plane at a time. Raising P while leaving E untouched is
|
||||
the characteristic misstep.
|
||||
|
||||
**Guard.** Verify continuously that the declared posture holds — **against the
|
||||
service's own declaration**, not a universal maximum. Nobody must prove every
|
||||
service is at E4; the check is that none is below what it declared.
|
||||
|
||||
Regression found by guarding is a defect; regression declared in advance is a
|
||||
decision. The estate has been bitten twice by silent pin rollbacks producing
|
||||
ordinary-looking 403s and 404s rather than errors. Posture regression looks the
|
||||
same — an RLS context leak returns correct-looking rows for the wrong tenant.
|
||||
Guarding must be designed for invisible failure, not for crashes.
|
||||
|
||||
## 13. Evidence per level
|
||||
|
||||
**Decision 13.1:** a level is claimed only with its evidence artifact present.
|
||||
This turns §6's accuracy rule from an honour system into a check.
|
||||
|
||||
**Decision 13.4 — an artifact must assert something achievable.** Draft-3's
|
||||
noisy-neighbour evidence required proof that a saturating consumer "does not
|
||||
breach" another's allowance. Shared infrastructure cannot provide that; the
|
||||
risk is inherent and cannot be wholly removed. An artifact that can only fail,
|
||||
or that passes by being run gently enough, is an overclaim wearing the costume
|
||||
of evidence. Where a property cannot be guaranteed, the artifact measures and
|
||||
records it instead.
|
||||
|
||||
**Decision 13.2 — evidence is of two kinds, and conflating them is an
|
||||
overclaim.** *Mechanical* evidence is a structural assertion a machine can make
|
||||
and belongs in CI. *Adversarial* evidence is semantic, requires setting up
|
||||
separate tenant contexts and comparing responses, and carries a review date
|
||||
rather than a green build. Cross-tenant findings are the category external
|
||||
testing practice identifies as needing human review. **A passing CI run is not
|
||||
E2 evidence.**
|
||||
|
||||
| Level | Evidence | Kind |
|
||||
|---|---|---|
|
||||
| **I2** | Identifiers validated against the vocabulary; rejection test for a malformed id; binding shown to come from a verified token | Mechanical |
|
||||
| **I3** | Live re-query demonstrated on an `aal2`-class path; cached-claim path shown unused there | Mechanical |
|
||||
| **A2** | Choke point identified; test that an unbound request is refused | Mechanical |
|
||||
| **A3** | Live decision with a denial observed at the endpoint, not only at the decision surface | Mechanical |
|
||||
| **A4** | Decision served over the standard interface; a second PDP substituted without PEP change | Mechanical |
|
||||
| **E1** | Every tenant-owned table carries the tenant key | Mechanical |
|
||||
| **E2** | Choke point identified; identity bound to tenant A demonstrably cannot read tenant B | **Adversarial**, with a review date |
|
||||
| **E3** | `FORCE ROW LEVEL SECURITY` on every tenant table; no `BYPASSRLS` on leased roles; probe that a session without the GUC reads nothing; probe that a wrong GUC reads nothing; `EXPLAIN` comparison | Mechanical |
|
||||
| **E4** | Per-tenant credential demonstrated unable to connect to another tenant's substrate | Mechanical |
|
||||
| **P1–P4** | Provisioning declaration plus the platform's isolation probes | Mechanical |
|
||||
| **P1–P2 (noisy neighbour)** | A recorded baseline of per-consumer resource usage; a run in which one consumer saturates its declared allowance; evidence that the governance controls **bind** (the greedy consumer is held at its limits) and that the degradation co-residents experience is **measured, recorded and judged acceptable**; the aggregate headroom at time of measurement | **Adversarial**, load-generated, with a review date |
|
||||
| **R2** | Declared retention rendered; erasure horizon published and reported in the operator surface | Mechanical |
|
||||
| **R3** | Sweep evidence records: timestamp, dataset, identifiers removed, authorising policy reference | Mechanical |
|
||||
| **R4** | Erasure demonstrated across live data, backups and derived copies within the horizon | **Adversarial** |
|
||||
|
||||
**Decision 13.3:** the E2, E3 and noisy-neighbour artifacts do not exist
|
||||
anywhere in the estate today. `rapp-postgres` runs 15 adversarial probes, all
|
||||
against the *consumer* boundary, none against the tenant boundary inside a
|
||||
consumer. Externally, what this framework calls a tenant boundary failure is
|
||||
**Broken Object Level Authorization** — OWASP API1, top of the API Security Top
|
||||
10 since that list launched, and the most commonly exploited API vulnerability
|
||||
in published assessments. We have no coverage for the highest-ranked risk in
|
||||
our class of system. §19.3 seeks an owner.
|
||||
|
||||
## 14. Adoption stance — structure, not tooling
|
||||
|
||||
**Decision 14.1:** external research is design input. This estate adopts
|
||||
published standards and structural patterns; it does not adopt tooling unless
|
||||
that tooling is an established industry standard with broad application.
|
||||
Everything else is built ground-up, so it can be optimised and refactored as
|
||||
the estate sees fit.
|
||||
|
||||
| Class | Stance |
|
||||
|---|---|
|
||||
| Security baselines (OWASP Multi-Tenant Security Cheat Sheet, API Security Top 10) | Adopt as the external reference our ladders answer to |
|
||||
| Standards bodies (OpenID AuthZEN 1.0) | Adopt — this is what A4 is |
|
||||
| Reference taxonomies (Azure tenancy models, AWS SaaS Lens, cell architecture) | Adopt as structure |
|
||||
| Engine behaviour (PostgreSQL RLS mechanics) | Facts, not tooling |
|
||||
| Third-party analyzers and test frameworks | **Do not adopt.** Take their rule taxonomies as checklists for probes we write ourselves |
|
||||
|
||||
The practical effect is small and good: `rapp-postgres` already owns a
|
||||
ground-up probe harness — bash and psql, no dependency tree — that found four
|
||||
real defects in its own provisioning SQL. The evidence artifacts in §13 become
|
||||
new probes in a tool we control. One idea worth reimplementing from the
|
||||
external survey is **policy-diff classification**: labelling a change to an
|
||||
enforcement policy as safe or breaking *before* it lands.
|
||||
|
||||
## 15. Alternatives considered
|
||||
|
||||
**One fixed model with a single set of characteristics** (draft-1). *Rejected:*
|
||||
cannot describe a repo that is not there yet, forcing absorbed repos to
|
||||
misrepresent their posture or stay outside. A framework that can only describe
|
||||
its own end state is not a framework.
|
||||
|
||||
**A maturity model with a single overall level.** *Rejected:* collapses the
|
||||
plane separation. A service strong on identity and weak on enforcement has a
|
||||
specific, actionable gap; one composite score hides it and invites averaging.
|
||||
|
||||
**Prohibiting row-level security** (draft-2's inherited position). *Rejected in
|
||||
draft-2, refined in draft-3:* RLS is a real rung against the common threat. The
|
||||
error was never RLS — it was describing E3 in E4's language.
|
||||
|
||||
**Schema-per-consumer in one database.** *Rejected:* `pg_catalog` is readable
|
||||
per-database, so every co-resident enumerates every other's table and column
|
||||
names regardless of grants. Retained as a describable state, never a target.
|
||||
|
||||
**Mandating E4 for everyone.** *Rejected:* the tenant taxonomy includes
|
||||
`consumer` (private individuals) and `family`. A cluster per private individual
|
||||
is economically impossible; the taxonomy is itself evidence pooling is
|
||||
required.
|
||||
|
||||
**Per-consumer physical backup retention.** *Rejected:* CNPG retention is a
|
||||
property of the instance's WAL archive. There is no mechanism, and claiming it
|
||||
would be a fabricated guarantee. Hence the derived maximum in §4.5.
|
||||
|
||||
**Platform-scheduled row expiry.** *Rejected:* requires the platform to hold
|
||||
DML authority over consumer schemas and interpret consumer data semantics, both
|
||||
forbidden by ADR-0001. The consumer's migration lease is the correct
|
||||
instrument.
|
||||
|
||||
**Leaving each repo to its own model.** *Rejected:* the status quo, which
|
||||
produced two contradictory ratified defaults and an unowned placement question.
|
||||
|
||||
## 16. Held against outside practice
|
||||
|
||||
**The graduated reframe is corroborated, not invented here.** Microsoft's
|
||||
tenancy-model guidance states it almost verbatim: *"Instead of viewing
|
||||
isolation as a discrete property, consider it a spectrum. You can deploy
|
||||
components of your architecture that are more isolated or less isolated than
|
||||
other components in the same architecture."* The same guidance derives our E↔P
|
||||
coupling independently — shared deployment means enforcement lives in
|
||||
application code; dedicated deployment means it is structural.
|
||||
|
||||
**Stronger than typical.** Most multi-tenancy literature models one boundary,
|
||||
tenant-to-tenant. This estate has **two stacked boundaries**: platform-service
|
||||
to platform-service, and tenant to tenant inside a consumer. Naming them
|
||||
separately and refusing to enforce both with one mechanism is uncommon and
|
||||
correct. Graduated per-plane levels also beat the silo/pool/bridge trichotomy,
|
||||
which is approximately our P plane with the other four missing — which is why
|
||||
it cannot express "pooled infrastructure, structurally enforced boundary".
|
||||
|
||||
**Weaker than typical.** The pool model's standard mitigation is a *verified*
|
||||
enforcement layer every service is demonstrably routed through. We have the
|
||||
concept and none of the verification (§13.3).
|
||||
|
||||
**Adopted without naming it.** Short-lived leased credentials re-read at
|
||||
checkout beat the long-lived-secret norm. §9 promotes it to a tenancy control.
|
||||
|
||||
**Still unexplored.** Neither P nor R describes a **cell** — a slice of
|
||||
infrastructure with a *fixed maximum size*, sized so one cell's failure is
|
||||
survivable and cell count scales linearly. `platform-pg` is, in these terms, an
|
||||
uncapped cell: §17 computes a ceiling and nothing enforces it (§19.8).
|
||||
|
||||
Sources: the four research digests in `research/2026-08-17-adr008-*`, which
|
||||
carry full citations for every claim in this section.
|
||||
|
||||
## 17. Scaling demands
|
||||
|
||||
Measured against the live `platform-pg` specification, not estimated.
|
||||
|
||||
```
|
||||
instances: 1 (no HA; single-node rail)
|
||||
max_connections: 100
|
||||
memory limit: 1Gi
|
||||
per consumer: 14 connections (12 runtime + 2 migration)
|
||||
```
|
||||
|
||||
**Connection ceiling: roughly six consumers — and this is the aggregate
|
||||
noisy-neighbour bound, not a capacity statistic.** Seven consumers request 98
|
||||
of 100 before CNPG's instance manager, metrics exporter and reserved slots.
|
||||
Every one of them is politely inside its declared 14-connection allowance; the
|
||||
instance still fails.
|
||||
|
||||
That distinction matters because our governance addresses the wrong shape.
|
||||
Per-consumer `connection_limit`, `statement_timeout` and
|
||||
`idle_in_transaction_session_timeout` guard well against **one greedy
|
||||
consumer**. They do nothing about **the aggregate of many modest ones**, which
|
||||
is the second and less intuitive noisy-neighbour failure and the one this
|
||||
number describes. Two consumers are provisioned. We are at roughly a third of
|
||||
the bound, and the third request will not feel like a scaling event.
|
||||
|
||||
**Memory likely binds first.** 100 backends against 1Gi is ~10MB per backend.
|
||||
Connection exhaustion errors clearly; memory pressure OOM-kills and degrades
|
||||
every co-resident at once.
|
||||
|
||||
**E3 and pooling.** *Corrected from draft-2, which had this backwards.*
|
||||
Transaction-scoped context (`SET LOCAL` inside an explicit transaction) is what
|
||||
makes E3 **safe** under a pooler. Statement-level pooling is what breaks it,
|
||||
serving other tenants' rows under concurrency with no error. E3 constrains
|
||||
which pooling mode is available, not whether pooling is available.
|
||||
|
||||
**Retention consumes the volume.** WAL accumulates with the window, and §4.5
|
||||
makes the window the maximum across consumers. A consumer declaring a long
|
||||
retention extends everyone's horizon *and* everyone's storage draw against a
|
||||
20Gi volume.
|
||||
|
||||
**Restore time couples all consumers.** Physical backup is instance-wide, so a
|
||||
consumer's RTO is a function of *total* instance size, not its own.
|
||||
|
||||
**No P1 tenant has HA.** `instances: 1` means a tier promising uptime cannot be
|
||||
satisfied at P1 as built — an availability floor belongs in §11's
|
||||
minimum-level vocabulary alongside isolation.
|
||||
|
||||
## 18. Consequences
|
||||
|
||||
- The estate gains one vocabulary and a way to be honest about partial
|
||||
adoption.
|
||||
- Absorbed repos get a described state and a path instead of a failing grade.
|
||||
- `tenantIsolation` in `PostgresConsumer` is revealed as a mislabelled field.
|
||||
- The verification problem becomes tractable: guard against declaration.
|
||||
- Draft-2's RLS prohibition is reversed and its E3 description corrected;
|
||||
`rapp-postgres` acquires an obligation to define and offer the mechanism.
|
||||
- Adding a consumer with long retention **silently extends everyone's erasure
|
||||
horizon**. This must reach the consumer review checklist, not only this
|
||||
document.
|
||||
- A service selling an isolation tier must maintain a tenant→substrate mapping
|
||||
it does not have today.
|
||||
- Nothing here changes a running system.
|
||||
|
||||
## 19. Open questions
|
||||
|
||||
1. **`tenantIsolation` field** — `rapp-postgres`: rename to name its plane and
|
||||
carry a level (`tenancy.E: 2`), or move it out of the storage declaration.
|
||||
2. **Placement ownership** — `railiance-platform` with `adaptive-pricing`:
|
||||
accept the ladder, triggers and the §8.1 monitoring obligation; appoint a
|
||||
recorded placement owner per workload.
|
||||
3. **E2, E3 and noisy-neighbour evidence** — *owner needed.* Now three
|
||||
artifacts of two kinds: E3 and noisy-neighbour are buildable as probes in
|
||||
the existing harness; E2 is adversarial and needs a review cadence. Both
|
||||
`audit-core` and `tenant-engine` have declined fleet-scope work on correct
|
||||
boundary reasoning, so this needs appointing. Highest-severity gap.
|
||||
4. **Business app vs platform service** — Custodian canon: a classification
|
||||
rule. Candidate: reuse `repo-classification-standard_v1.0`.
|
||||
5. **Tier → minimum level mapping** — `adaptive-pricing` and `tenant-engine`:
|
||||
required only for tiers making isolation, availability or retention claims.
|
||||
6. **The E3 mechanism** — `rapp-postgres`: publish the GUC contract with the
|
||||
`FORCE`/`BYPASSRLS`/`SECURITY INVOKER`/`EXPLAIN` requirements in §4.3.
|
||||
7. **Identity-provider placement** — owner of `key-cape`: realm-per-tenant or
|
||||
Organizations? Realm-per-tenant's ~5–20 tenant ceiling is below our target.
|
||||
8. **Cell sizing** — reframed from "should we adopt cells" to **"what is
|
||||
`platform-pg`'s declared maximum size, and what is the overflow target?"**
|
||||
The connection ceiling forces this whether or not we adopt the vocabulary.
|
||||
9. **Retention floor and ceiling** — should `backupRetentionDays` have a
|
||||
platform minimum (so a consumer asking for 1 day gets a validation error
|
||||
rather than a quiet disappointment) and a maximum (so nobody exhausts the
|
||||
volume)?
|
||||
10. **Engine neutrality** — the P ladder rests on a PostgreSQL property.
|
||||
State it engine-specifically and say so, or abstract it and risk a
|
||||
non-Postgres implementation that silently differs?
|
||||
11. **Erasure versus audit** — `audit-core`: crypto-shredding a tenant's audit
|
||||
records destroys the evidence the service exists to hold, and ADR-0001 §2
|
||||
deliberately built the role model so history could not be rewritten. The
|
||||
usual resolution separates the *fact* of an event, retained, from its
|
||||
*personal payload*, encrypted per subject and shreddable. Raised because a
|
||||
naive "R4 everywhere" target would instruct the audit service to destroy
|
||||
its own evidence. The answer is `audit-core`'s, not this framework's.
|
||||
12. **Quality of service** — *owner needed.* The framework has no vocabulary
|
||||
for saying one consumer's latency matters more than another's.
|
||||
`tenant-engine` sits on `flex-auth`'s synchronous authorization path and
|
||||
chose a 5s statement timeout for that reason; it shares an instance with
|
||||
`audit-core`, which is not latency-critical. Nothing prioritises between
|
||||
them. Either add a QoS dimension or state that all co-residents are equal
|
||||
and latency-critical consumers must escalate to P2.
|
||||
|
||||
**Routed elsewhere, deliberately.** The tenant identifier
|
||||
`tenant:<grouping>:<name>` embeds headcount bands (`small`, `medium`, `large`)
|
||||
that change as a tenant grows, contradicting the consensus that identifiers
|
||||
should not encode mutable attributes. That is a critique of ADR-0013, not of
|
||||
this framework, and belongs to `tenant-engine` and NetKingdom canon. Folding it
|
||||
in here would overreach.
|
||||
|
||||
## 20. Ratification path
|
||||
|
||||
1. Reviewed by `tenant-engine`, `flex-auth`, `rapp-postgres`,
|
||||
`railiance-platform` and `adaptive-pricing` against §19.
|
||||
2. Each publishes its own posture vector (§5) as part of review. **The
|
||||
framework is validated by whether it can describe them accurately** — if a
|
||||
repo cannot express itself in these five ladders, the ladders are wrong and
|
||||
this document changes, not the repo.
|
||||
3. On acceptance, **supersedes** the routing of
|
||||
`rapp-postgres/docs/canon-drafts/shared-platform-relational-storage_v0.1-draft.md`,
|
||||
whose §§3–8 are absorbed here. That draft is withdrawn rather than left
|
||||
pending.
|
||||
4. On acceptance, `rapp-postgres` ADR-0001 and ADR-0002 move to `accepted` and
|
||||
are annotated as the PostgreSQL implementation of the E, P and R ladders.
|
||||
The publication renderer that lived in `tools/` moved to `policy-nexus`, which
|
||||
owns publication.
|
||||
|
|
|
|||
|
|
@ -1,185 +0,0 @@
|
|||
:root{
|
||||
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
|
||||
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
|
||||
--rule:#D3D7DC; --rule-strong:#B6BCC3;
|
||||
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
|
||||
--clay:#8A3A2C; --clay-soft:#F2DFDA;
|
||||
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
|
||||
--chip-fg:#F6F7F8;
|
||||
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
|
||||
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
|
||||
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
|
||||
--measure:66ch;
|
||||
}
|
||||
@media (prefers-color-scheme:dark){
|
||||
:root:not([data-theme="light"]){
|
||||
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
|
||||
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
|
||||
--rule:#2A3138; --rule-strong:#3B444D;
|
||||
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
|
||||
--clay:#D08A76; --clay-soft:#3A211B;
|
||||
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
|
||||
--chip-fg:#12161A;
|
||||
}
|
||||
}
|
||||
:root[data-theme="dark"]{
|
||||
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
|
||||
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
|
||||
--rule:#2A3138; --rule-strong:#3B444D;
|
||||
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
|
||||
--clay:#D08A76; --clay-soft:#3A211B;
|
||||
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
|
||||
--chip-fg:#12161A;
|
||||
}
|
||||
|
||||
*{box-sizing:border-box}
|
||||
body{
|
||||
margin:0; background:var(--paper); color:var(--ink);
|
||||
font-family:var(--font-body); font-size:17px; line-height:1.62;
|
||||
-webkit-font-smoothing:antialiased;
|
||||
}
|
||||
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
|
||||
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
|
||||
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
|
||||
|
||||
/* ---------- rail ---------- */
|
||||
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
|
||||
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
|
||||
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
|
||||
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
|
||||
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
|
||||
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
|
||||
|
||||
/* ---------- header ---------- */
|
||||
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
|
||||
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
|
||||
.eyebrow .stat{color:var(--clay)}
|
||||
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
|
||||
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
|
||||
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
|
||||
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
|
||||
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
|
||||
|
||||
/* ---------- typography ---------- */
|
||||
section{margin-bottom:60px;scroll-margin-top:24px}
|
||||
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
|
||||
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
|
||||
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
|
||||
p{margin:0 0 15px;max-width:var(--measure)}
|
||||
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
|
||||
li{margin-bottom:7px}
|
||||
strong{font-weight:600}
|
||||
em{font-style:italic}
|
||||
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
|
||||
a{color:var(--brass)}
|
||||
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
|
||||
|
||||
/* ---------- devices ---------- */
|
||||
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
|
||||
.callout p:last-child{margin-bottom:0}
|
||||
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
|
||||
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
|
||||
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
|
||||
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
|
||||
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
|
||||
.hard p:last-child{margin-bottom:0}
|
||||
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
|
||||
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
|
||||
|
||||
/* ---------- tables ---------- */
|
||||
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
|
||||
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
|
||||
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
|
||||
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
|
||||
td:first-child{color:var(--ink);font-weight:600}
|
||||
tbody tr:last-child td{border-bottom:none}
|
||||
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
|
||||
|
||||
/* ---------- ladders ---------- */
|
||||
.breakout{margin:34px 0 40px}
|
||||
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
|
||||
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
|
||||
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
|
||||
.ladders{display:grid;gap:26px}
|
||||
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
|
||||
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
|
||||
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
|
||||
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
|
||||
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
|
||||
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
|
||||
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
|
||||
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
|
||||
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
|
||||
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
|
||||
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
|
||||
.rung.na{opacity:.42}
|
||||
|
||||
/* ---------- matrix ---------- */
|
||||
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
|
||||
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
|
||||
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
|
||||
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
|
||||
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
|
||||
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
|
||||
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
|
||||
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
|
||||
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
|
||||
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
|
||||
.rlab{min-height:60px}
|
||||
.clab{padding-top:7px;min-height:22px}
|
||||
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
|
||||
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
|
||||
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
|
||||
.mnote .k{display:flex;align-items:center;gap:7px}
|
||||
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
|
||||
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
|
||||
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
|
||||
@media (max-width:640px){
|
||||
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
|
||||
.mcell{min-height:52px;padding:4px}
|
||||
.pin{font-size:8px;padding:1px 3px}
|
||||
.rlab{min-height:52px}
|
||||
}
|
||||
|
||||
/* ---------- methodology ---------- */
|
||||
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
|
||||
.verb{background:var(--surface);padding:18px 18px 20px}
|
||||
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
|
||||
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
|
||||
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
|
||||
|
||||
/* ---------- questions ---------- */
|
||||
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
|
||||
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
|
||||
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
|
||||
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
|
||||
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
|
||||
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
|
||||
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
|
||||
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
|
||||
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
|
||||
|
||||
/* ---------- misc ---------- */
|
||||
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
|
||||
.numbers .v{color:var(--ink);font-weight:600}
|
||||
.numbers .k{color:var(--ink-3)}
|
||||
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
|
||||
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
|
||||
.alt:last-of-type{border-bottom:none}
|
||||
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
|
||||
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
|
||||
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
|
||||
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
|
||||
.tm td,.tm th{text-align:center}
|
||||
.tm td:first-child,.tm th:first-child{text-align:left}
|
||||
.yes{color:var(--l4);font-weight:700}
|
||||
.no{color:var(--clay);font-weight:700}
|
||||
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
|
||||
.kind.adv{border-color:var(--clay);color:var(--clay)}
|
||||
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
|
||||
.route{background:var(--surface);padding:16px 18px}
|
||||
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
|
||||
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
|
||||
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
|
||||
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
|
||||
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
|
||||
|
|
@ -1,377 +0,0 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Render a canon markdown document into a styled, self-contained artifact page.
|
||||
|
||||
Single source of truth: the markdown. The page is generated, never hand-edited,
|
||||
so the two cannot diverge.
|
||||
|
||||
Design devices are recognised from conventions already present in the markdown
|
||||
rather than from extra markup, so the source stays a readable document:
|
||||
|
||||
* a table whose first column is `**X0**`/`**X1**`... renders as a level ladder
|
||||
* a table whose first header cell is `Threat` renders as a threat matrix
|
||||
* a table with a `Kind` column renders with mechanical/adversarial chips
|
||||
* a table whose first header cell is `E \\ P` renders as the E x P matrix
|
||||
* a blockquote renders as a pull quote
|
||||
* `**Decision N.N...**` at the start of a paragraph renders as a decision
|
||||
* `## N. Title` headings build the section rail
|
||||
|
||||
Stdlib only, per the estate's structure-not-tooling stance: a publishing step
|
||||
that needs its own toolchain is a publishing step that stops being run.
|
||||
|
||||
Usage:
|
||||
python3 tools/render-artifact.py <source.md> --output <page.html> \\
|
||||
[--title "Name"] [--subtitle "..."]
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import html
|
||||
import pathlib
|
||||
import re
|
||||
import sys
|
||||
|
||||
STYLE = pathlib.Path(__file__).parent / "artifact-style.css"
|
||||
|
||||
INLINE_CODE = re.compile(r"`([^`]+)`")
|
||||
BOLD = re.compile(r"\*\*([^*]+)\*\*")
|
||||
EM = re.compile(r"(?<![*\w])\*([^*]+)\*(?!\*)")
|
||||
LINK = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
|
||||
HEADING = re.compile(r"^(#{1,4})\s+(.*)$")
|
||||
SECTION_NO = re.compile(r"^(\d+)\.\s+(.*)$")
|
||||
LEVEL_CELL = re.compile(r"^\*\*([IAEPR])(\d)\*\*$")
|
||||
DECISION = re.compile(r"^\*\*(Decision [\d.]+[^*]*)\*\*(.*)$", re.S)
|
||||
|
||||
|
||||
def inline(text: str) -> str:
|
||||
"""Escape, then apply inline markdown. Order matters: code first."""
|
||||
slots: list[str] = []
|
||||
|
||||
def stash(rendered: str) -> str:
|
||||
slots.append(rendered)
|
||||
return f"\x00{len(slots) - 1}\x00"
|
||||
|
||||
text = INLINE_CODE.sub(lambda m: stash(f"<code>{html.escape(m.group(1))}</code>"), text)
|
||||
text = html.escape(text, quote=False)
|
||||
text = LINK.sub(
|
||||
lambda m: f'<a href="{html.escape(m.group(2), quote=True)}">{m.group(1)}</a>', text
|
||||
)
|
||||
text = BOLD.sub(r"<strong>\1</strong>", text)
|
||||
text = EM.sub(r"<em>\1</em>", text)
|
||||
for i, rendered in enumerate(slots):
|
||||
text = text.replace(f"\x00{i}\x00", rendered)
|
||||
return text
|
||||
|
||||
|
||||
def split_frontmatter(source: str) -> tuple[dict, str]:
|
||||
if not source.startswith("---\n"):
|
||||
return {}, source
|
||||
end = source.index("\n---\n", 4)
|
||||
meta = {}
|
||||
for line in source[4:end].splitlines():
|
||||
if ":" in line and not line.startswith((" ", "-")):
|
||||
key, _, value = line.partition(":")
|
||||
meta[key.strip()] = value.strip().strip('"')
|
||||
return meta, source[end + 5 :]
|
||||
|
||||
|
||||
def parse_table(lines: list[str], start: int) -> tuple[list[list[str]], int]:
|
||||
rows, i = [], start
|
||||
while i < len(lines) and lines[i].lstrip().startswith("|"):
|
||||
cells = [c.strip() for c in lines[i].strip().strip("|").split("|")]
|
||||
if not all(set(c) <= set("-: ") for c in cells):
|
||||
rows.append(cells)
|
||||
i += 1
|
||||
return rows, i
|
||||
|
||||
|
||||
# --- table renderers -------------------------------------------------------
|
||||
|
||||
|
||||
def render_ladder(rows: list[list[str]]) -> str:
|
||||
"""A level table becomes a stepped scale. Colour depth encodes strength."""
|
||||
body = rows[1:]
|
||||
plane = LEVEL_CELL.match(body[0][0]).group(1)
|
||||
names = {
|
||||
"I": "Identity", "A": "Authorization", "E": "Enforcement",
|
||||
"P": "Placement", "R": "Retention",
|
||||
}
|
||||
rungs = []
|
||||
for cells in body:
|
||||
match = LEVEL_CELL.match(cells[0])
|
||||
if not match:
|
||||
continue
|
||||
n = int(match.group(2))
|
||||
text = cells[1] if len(cells) > 1 else ""
|
||||
rungs.append(
|
||||
f'<div class="rung r{n}"><span class="code">{plane}{n}</span>'
|
||||
f'<span class="txt">{inline(text)}</span></div>'
|
||||
)
|
||||
while len(rungs) < 5:
|
||||
rungs.append('<div class="rung na"><span class="code">—</span>'
|
||||
f'<span class="txt">Ladder ends at {plane}{len(rungs) - 1}.</span></div>')
|
||||
return (
|
||||
'<div class="ladder"><div class="pname">'
|
||||
f'{names.get(plane, plane)}<span>plane {plane}</span></div>'
|
||||
f'<div class="rungs">{"".join(rungs)}</div></div>'
|
||||
)
|
||||
|
||||
|
||||
def render_threat(rows: list[list[str]]) -> str:
|
||||
head = "".join(f"<th>{inline(c)}</th>" for c in rows[0])
|
||||
body = []
|
||||
for cells in rows[1:]:
|
||||
tds = [f"<td>{inline(cells[0])}</td>"]
|
||||
for c in cells[1:]:
|
||||
cls = "yes" if "✓" in c else "no" if "✗" in c else ""
|
||||
tds.append(f'<td class="{cls}">{inline(c)}</td>')
|
||||
body.append(f"<tr>{''.join(tds)}</tr>")
|
||||
return (f'<div class="scroll"><table class="tm"><thead><tr>{head}</tr></thead>'
|
||||
f'<tbody>{"".join(body)}</tbody></table></div>')
|
||||
|
||||
|
||||
def render_matrix(rows: list[list[str]]) -> str:
|
||||
"""`E \\ P` table becomes the two-axis grid. Cells hold pins or markers."""
|
||||
cols = rows[0][1:]
|
||||
cells = ['<div class="mgrid">']
|
||||
for cells_row in rows[1:]:
|
||||
e = cells_row[0].strip("*")
|
||||
level = int(e[1]) if len(e) > 1 and e[1].isdigit() else 0
|
||||
cells.append(f'<div class="rlab">{html.escape(e)}</div>')
|
||||
for value in cells_row[1:]:
|
||||
v = value.strip()
|
||||
if v == "—":
|
||||
cells.append('<div class="mcell void"></div>')
|
||||
continue
|
||||
tint = f" tint{level}" if level else ""
|
||||
pins = ""
|
||||
for entry in (p.strip() for p in v.split("<br>") if p.strip()):
|
||||
ghost = " ghost" if entry.startswith("(") else ""
|
||||
pins += f'<span class="pin{ghost}">{inline(entry.strip("()"))}</span>'
|
||||
cells.append(f'<div class="mcell{tint}">{pins}</div>')
|
||||
cells.append('<div class="rlab"></div>')
|
||||
cells.extend(f'<div class="clab">{html.escape(c)}</div>' for c in cols)
|
||||
cells.append("</div>")
|
||||
return (
|
||||
'<div class="matrix-shell"><div class="ylab">Enforcement →</div>'
|
||||
+ "".join(cells)
|
||||
+ "</div>"
|
||||
'<div class="mnote">'
|
||||
'<span class="k"><span class="sw"></span>Where a service sits today</span>'
|
||||
'<span class="k"><span class="sw g"></span>Target or default</span>'
|
||||
'<span class="k"><span class="sw v"></span>Unreachable at this placement</span>'
|
||||
"</div>"
|
||||
)
|
||||
|
||||
|
||||
def render_table(rows: list[list[str]]) -> str:
|
||||
if not rows:
|
||||
return ""
|
||||
header = [c.strip() for c in rows[0]]
|
||||
first = header[0].lower()
|
||||
if first.replace(" ", "") in {"e\\p", "e\\p"}:
|
||||
return render_matrix(rows)
|
||||
if first == "threat":
|
||||
return render_threat(rows)
|
||||
kind_col = header.index("Kind") if "Kind" in header else None
|
||||
# A level table is a ladder. The evidence table also leads with `Level` but
|
||||
# carries a `Kind` column, and is a table of artifacts, not of rungs.
|
||||
if first == "level" and kind_col is None and len(rows) > 1 and LEVEL_CELL.match(rows[1][0]):
|
||||
return render_ladder(rows)
|
||||
head = "".join(f"<th>{inline(c)}</th>" for c in header)
|
||||
body = []
|
||||
for cells in rows[1:]:
|
||||
tds = []
|
||||
for i, c in enumerate(cells):
|
||||
if i == kind_col:
|
||||
adv = "adv" if "adversarial" in c.lower() else ""
|
||||
label = re.sub(r"[*_]", "", c).strip()
|
||||
tds.append(f'<td><span class="kind {adv}">{html.escape(label)}</span></td>')
|
||||
else:
|
||||
tds.append(f"<td>{inline(c)}</td>")
|
||||
body.append(f"<tr>{''.join(tds)}</tr>")
|
||||
return (f'<div class="scroll"><table><thead><tr>{head}</tr></thead>'
|
||||
f'<tbody>{"".join(body)}</tbody></table></div>')
|
||||
|
||||
|
||||
# --- document ---------------------------------------------------------------
|
||||
|
||||
|
||||
def render_body(markdown: str) -> tuple[str, list[tuple[str, str, str]]]:
|
||||
lines = markdown.splitlines()
|
||||
out: list[str] = []
|
||||
rail: list[tuple[str, str, str]] = []
|
||||
open_section = False
|
||||
ladders_open = False
|
||||
i = 0
|
||||
|
||||
def close_ladders() -> None:
|
||||
nonlocal ladders_open
|
||||
if ladders_open:
|
||||
out.append("</div></div>")
|
||||
ladders_open = False
|
||||
|
||||
while i < len(lines):
|
||||
line = lines[i]
|
||||
stripped = line.strip()
|
||||
|
||||
if not stripped:
|
||||
i += 1
|
||||
continue
|
||||
|
||||
heading = HEADING.match(stripped)
|
||||
if heading:
|
||||
level, text = len(heading.group(1)), heading.group(2)
|
||||
if level == 1:
|
||||
i += 1
|
||||
continue
|
||||
if level == 2:
|
||||
close_ladders()
|
||||
if open_section:
|
||||
out.append("</section>")
|
||||
match = SECTION_NO.match(text)
|
||||
if match:
|
||||
num, title = match.group(1), match.group(2)
|
||||
anchor = f"s{num}"
|
||||
rail.append((anchor, num, title))
|
||||
out.append(
|
||||
f'<section id="{anchor}"><h2>'
|
||||
f'<span class="sn">{int(num):02d}</span>{inline(title)}</h2>'
|
||||
)
|
||||
else:
|
||||
anchor = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
|
||||
rail.append((anchor, "·", text))
|
||||
out.append(f'<section id="{anchor}"><h2>{inline(text)}</h2>')
|
||||
open_section = True
|
||||
else:
|
||||
close_ladders()
|
||||
out.append(f"<h3>{inline(text)}</h3>")
|
||||
i += 1
|
||||
continue
|
||||
|
||||
if stripped.startswith("|"):
|
||||
rows, i = parse_table(lines, i)
|
||||
rendered = render_table(rows)
|
||||
if 'class="ladder"' in rendered:
|
||||
if not ladders_open:
|
||||
out.append('<div class="breakout"><div class="ladders">')
|
||||
ladders_open = True
|
||||
out.append(rendered)
|
||||
else:
|
||||
close_ladders()
|
||||
out.append(rendered)
|
||||
continue
|
||||
|
||||
close_ladders()
|
||||
|
||||
if stripped.startswith("```"):
|
||||
block = []
|
||||
i += 1
|
||||
while i < len(lines) and not lines[i].strip().startswith("```"):
|
||||
block.append(lines[i])
|
||||
i += 1
|
||||
out.append(f"<pre>{html.escape(chr(10).join(block))}</pre>")
|
||||
i += 1
|
||||
continue
|
||||
|
||||
if stripped.startswith(">"):
|
||||
quote = []
|
||||
while i < len(lines) and lines[i].strip().startswith(">"):
|
||||
quote.append(lines[i].strip().lstrip(">").strip())
|
||||
i += 1
|
||||
out.append(f'<div class="rule-quote"><p>{inline(" ".join(quote))}</p></div>')
|
||||
continue
|
||||
|
||||
if re.match(r"^[-*]\s+", stripped) or re.match(r"^\d+\.\s+", stripped):
|
||||
ordered = bool(re.match(r"^\d+\.\s+", stripped))
|
||||
items = []
|
||||
while i < len(lines):
|
||||
s = lines[i].strip()
|
||||
if re.match(r"^[-*]\s+", s) or re.match(r"^\d+\.\s+", s):
|
||||
items.append(re.sub(r"^([-*]|\d+\.)\s+", "", s))
|
||||
elif s and lines[i].startswith((" ", "\t")) and items:
|
||||
items[-1] += " " + s
|
||||
else:
|
||||
break
|
||||
i += 1
|
||||
tag = "ol" if ordered else "ul"
|
||||
body = "".join(f"<li>{inline(t)}</li>" for t in items)
|
||||
out.append(f"<{tag}>{body}</{tag}>")
|
||||
continue
|
||||
|
||||
if set(stripped) <= set("-") and len(stripped) >= 3:
|
||||
i += 1
|
||||
continue
|
||||
|
||||
para = [stripped]
|
||||
i += 1
|
||||
while i < len(lines) and lines[i].strip() and not re.match(
|
||||
r"^(\||>|```|#{1,4}\s|[-*]\s|\d+\.\s|---)", lines[i].strip()
|
||||
):
|
||||
para.append(lines[i].strip())
|
||||
i += 1
|
||||
text = " ".join(para)
|
||||
decision = DECISION.match(text)
|
||||
if decision:
|
||||
out.append(
|
||||
f'<p><span class="dec">{inline(decision.group(1))}</span>'
|
||||
f"{inline(decision.group(2))}</p>"
|
||||
)
|
||||
else:
|
||||
out.append(f"<p>{inline(text)}</p>")
|
||||
|
||||
close_ladders()
|
||||
if open_section:
|
||||
out.append("</section>")
|
||||
return "\n".join(out), rail
|
||||
|
||||
|
||||
def main() -> int:
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("source", type=pathlib.Path)
|
||||
ap.add_argument("--output", required=True, type=pathlib.Path)
|
||||
ap.add_argument("--title", default=None)
|
||||
ap.add_argument("--subtitle", default="")
|
||||
args = ap.parse_args()
|
||||
|
||||
meta, markdown = split_frontmatter(args.source.read_text())
|
||||
body, rail = render_body(markdown)
|
||||
|
||||
title = args.title or meta.get("title", args.source.stem)
|
||||
display = title.split(":")[0].strip()
|
||||
eyebrow = " ".join(
|
||||
f"<span{' class=\"stat\"' if k == 'status' else ''}>{html.escape(v)}</span>"
|
||||
for k, v in (
|
||||
("id", meta.get("id", "")),
|
||||
("status", f"{meta.get('status', '')} · {meta.get('revision', '')}".strip(" ·")),
|
||||
("date", meta.get("date", "")),
|
||||
)
|
||||
if v
|
||||
)
|
||||
rail_html = "".join(
|
||||
f'<li><a href="#{a}"><span class="n">{n}</span>{html.escape(t)}</a></li>'
|
||||
for a, n, t in rail
|
||||
)
|
||||
|
||||
page = (
|
||||
f"<title>{html.escape(display)}</title>\n"
|
||||
f"<style>\n{STYLE.read_text()}\n</style>\n"
|
||||
'<div class="wrap"><header>'
|
||||
f'<div class="eyebrow">{eyebrow}<span>generated from canon — do not edit</span></div>'
|
||||
f"<h1>{html.escape(display)}</h1>"
|
||||
+ (f'<p class="sub">{html.escape(args.subtitle)}</p>' if args.subtitle else "")
|
||||
+ '</header><div class="layout">'
|
||||
f'<nav class="rail" aria-label="Sections"><ol>{rail_html}</ol></nav>'
|
||||
f"<main>{body}"
|
||||
f'<footer><span>{html.escape(meta.get("id", ""))} · '
|
||||
f'{html.escape(meta.get("revision", ""))} · {html.escape(meta.get("status", ""))}</span>'
|
||||
"<span>generated from the-custodian/canon</span></footer>"
|
||||
"</main></div></div>\n"
|
||||
)
|
||||
args.output.write_text(page)
|
||||
print(f"{args.output}: {len(rail)} sections, {len(page)} bytes")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Loading…
Add table
Add a link
Reference in a new issue