@terpjs/spec 0.14.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,417 @@
+# The Terp Standard — rule catalog + violation corpus
+
+This repository is the **stack-neutral specification** of Terp's
+secure-by-default rules (ADR 0080, made consumable by ADR 0081). The framework
+([terp-framework](https://github.com/AITT-NL/terp-framework)) is the
+**reference implementation**; this spec is what any other stack would
+implement and be verified against. It is deliberately self-contained (no
+`terp.*` imports, plain JSON + sample files) and consumed as a **package**,
+never a repo path (ADR 0082).
+
+## The package seam (ADR 0082)
+
+The directory doubles as two thin distributions over one data set:
+
+- **`terp-spec`** (Python, `pyproject.toml`): a dependency-free `terp_spec`
+  accessor — `spec_dir()` returns the on-disk spec root, `spec_version()` the
+  `VERSION` semver. A uv workspace member; the framework's certification tests
+  locate the spec only through it.
+- **`@terpjs/spec`** (npm, `package.json`): data only; consumers resolve the
+  spec root via `require.resolve("@terpjs/spec/package.json")`. An npm workspace
+  member; the ESLint adapter's corpus/surface tests depend on it.
+
+Both are **published from the tag workflow** (ADR 0086) — `terp-spec` on PyPI,
+`@terpjs/spec` on npm, via Trusted Publishing (OIDC), so a consumer pins an
+ordinary version. Pinning the git tag instead keeps working.
+
+Both manifests carry the **spec version** (`VERSION`) — independent of the
+platform's lockstep release version, per ADR 0081's certification model; the
+standalone suite holds the three declarations equal.
+
+The spec-only validations (versioning, schema validity, the refused surface's
+shape, the corpus ratchet and directory discipline) live in `spec/tests/` and
+run standalone (`python -m pytest` from `spec/`; CI: the path-filtered
+`spec.yml` workflow). The framework gate keeps the *parity* half — everything
+that needs the live implementations. Because the framework consumes a **pinned
+release**, this repository's CI additionally runs `certify-against-reference`:
+it checks out the reference framework, substitutes the candidate spec for the
+pinned `terp-spec` / `@terpjs/spec`, and runs the framework's parity + corpus
+certification — so a catalog or corpus change is proven against the live
+implementations *before* release, and the framework's later pin bump re-proves
+it in the framework's own gate. Splitting the spec out is then purely a
+manifest change: move `spec/` + `spec.yml`, repin `terp-spec` / `@terpjs/spec`
+from workspace sources to a git tag or registry release
+(`tests/architecture/test_repo_split_readiness.py` fails the build if code
+re-couples the units by path).
+
+The artifacts:
+
+1. **`VERSION`** — the semver of the standard. A checker certified against the
+   corpus records the spec version it was certified for.
+2. **The catalog** (`catalog/`) — one JSON document per rule (validated by
+   `catalog/schema.json`): what the rule is, why it exists, and how it is
+   enforced today.
+3. **The corpus** (`corpus/`) — violating and compliant code samples per rule:
+   the executable meaning of the rule. `corpus/PENDING.json` is the coverage
+   ratchet — the explicit list of rules still without cases, which only shrinks.
+4. **The finding format** (`findings.schema.json`) — what a conformant checker
+   emits, so checkers are interoperable and a corpus harness can be generic.
+5. **The check-report format** (`app-check-report.schema.json`) — the complete
+   result of one checker invocation over one application tree: the finding
+   format plus the run's own evaluated-rule inventory, spec version, checker
+   identity and verdict, so a driving tool can join per-rule verdicts to the
+   catalog fail-closed.
+6. **The refused surface** (`restricted-surface.json`) — the stack-neutral,
+   normative declaration of the raw frontend primitives an app module must not
+   author (elements, attributes, egress globals/member calls, stylesheet
+   extensions, deep-import segments). The portable prohibition rules cite it
+   structurally (the `restricted_surface` catalog field); which sanctioned
+   component answers each primitive is per-stack configuration.
+7. **The residual ratchet** (`corpus/RESIDUALS.json`) — the statically-erased
+   or renamed forms deliberately outside the corpus contract, per rule, as
+   shrink-only data (see "Detector boundaries" below).
+8. **The scorecard format** (`scorecard.schema.json`) — the machine-readable
+   certification summary a conformant checker emits (spec version, per-rule
+   verdicts over the corpus, residuals claimed), so "certified against spec
+   X.Y.Z" is a verifiable artifact instead of a claim.
+9. **The changelog** (`CHANGELOG.md`) — the change history keyed to `VERSION`
+   (the top entry must match, held by the spec suite), so a checker certified
+   against an earlier version can see exactly what changed since.
+10. **The rule pages** (`docs/rules/`) — plain-language documentation generated
+    from the catalog (`tools/generate_rule_docs.py`; regenerate-and-compare
+    parity in the spec suite, so the pages cannot drift from the data).
+
+Everything is locked to the live implementations by build-time parity tests
+(`tests/architecture/test_spec_catalog.py`, `tests/architecture/test_spec_corpus.py`,
+`packages/frontend/eslint-boundaries/src/corpus.test.js` and
+`packages/frontend/eslint-boundaries/src/surface.test.js` — the latter holds the
+reference adapter to `restricted-surface.json` both structurally and
+behaviourally), following the
+same "docs can't lie" discipline as the rest of the gate: a rule cannot ship
+without a catalog entry, a catalog entry cannot outlive its rule, and every
+enforcement reference must resolve to real code.
+
+## Scope: what the standard claims — and delegates
+
+The catalog is **Terp-specific secure architecture, not complete application
+security**. A rule is admitted only when Terp provides a *privileged seam* or
+a *more precise invariant* than a generic analyzer can state — a framework
+chokepoint to pair with (`runtime.applicability: required`), a
+refused-surface entry, a trait/registry the rule holds code to. Generic
+vulnerability classes that stock security analyzers already detect well
+(command injection, unsafe deserialization, weak security randomness, …) are
+**delegated, never duplicated**: a conformant toolchain
+runs a generic security baseline for its language *next to* the Terp rules
+(the reference stack pins ruff's bandit-derived `S` rules, wired into the
+platform repo, the client template, and each generated project's own gate —
+platform ADR 0085). Classes no stock analyzer detects well — path traversal,
+secrets in logs, browser-storage auth material — are addressed
+**constructively** by the reference framework (streamed storage behind
+declared references, central log redaction, the session/refresh model) and
+earn a detective catalog rule only through the same admission bar, never as a
+checkbox. Baseline findings are **not** Terp findings: the finding
+format's `rule` pattern admits only catalog ids, so a generic finding can
+never masquerade as (or dilute) a Terp verdict — it travels as the baseline
+tool's own output (or the envelope's `unattributed` bucket, ADR 0083).
+
+Catalog entries deliberately carry **no CWE/OWASP mappings**: no governance
+consumer exists for them, and the delegated baseline's own documentation
+already maps the generic classes. Metadata joins the catalog when something
+machine-consumes it, not before.
+
+## Catalog format
+
+`catalog/<surface>/<rule>.json`, validated against `catalog/schema.json` (the
+schema is normative and travels with the spec). The normative statement of a
+rule is its `title` + `intent`, and that prose is **stack-neutral by
+construction**: plain prose, no docstring markup, no reference-implementation
+symbols, package paths, marker spellings, or repo-internal pointers (sibling
+rules are cited by catalog rule name). The reference realisation lives in the
+non-normative fields (`enforcement`, `reference`, `opt_out`, `guide_topic`).
+The standalone suite enforces the split
+(`test_normative_prose_is_stack_neutral`).
+
+| Field | Meaning |
+|---|---|
+| `id` | `<surface>/<rule>` — `backend/<snake_case>` (a `terp.arch` rule) or `frontend/<kebab-case>` (a boundary rule). **Findings are attributed to this id**, never to a tool-internal rule id. |
+| `surface` | `backend` or `frontend`. |
+| `title` | One-line statement of the invariant. |
+| `intent` | Why the rule exists — the drift or threat it prevents. |
+| `layer` | Cheapest faithful verification for a *new* stack: see below. |
+| `enforcement` | How the reference implementation enforces it (first entry: the `build-time` check). A `runtime` entry names the fail-closed runtime control pairing with it (the two-layer discipline a Level 3 stack must reproduce for the rules that require it); a `black-box` entry names the `@terp/conformance` probe title. For frontend rules, `reported_as` is the ESLint rule id violations surface as — several catalog rules share one core rule id, so the adapter publishes a `catalogRuleId()` mapping and findings are attributed through it. |
+| `runtime` | **Mandatory.** The rule's runtime-applicability classification (`required` / `not-applicable` / `deferred`) plus a `rationale` (mandatory for exemptions) and, for `deferred`, a `tracking` reference naming where the deferral is tracked — see “Runtime applicability” below. |
+| `restricted_surface` | Frontend prohibition rules only: the `restricted-surface.json` keys the rule realises — the structural citation the spec suite resolves (every key must be claimed by some rule; a prose mention in `intent` must agree with the field). |
+| `opt_out` | The *reference realisation* of the abstract escape-hatch contract (see below). |
+| `reference` | Optional reference-implementation metadata: the compliant realisation the reference stack offers (component / helper names). **Not normative** — the `title` and `intent` state the stack-neutral invariant; another stack ships its own realisation. |
+| `guide_topic` | Reference-implementation metadata (backend only): the `terp guide` topic teaching the compliant pattern. Not normative for other stacks. |
+| `corpus` | Whether `corpus/<id>/` cases exist yet (the parity test holds this flag to the directory truth; a covered rule needs at least one `violation-*` **and** one `compliant-*` case). |
+
+### Enforcement layers
+
+- **`black-box`** — the invariant is observable by probing a *running* app
+  (no source access needed). Portable to any stack via a conformance suite;
+  each such rule names its probe in a `black-box` enforcement entry
+  (`packages/frontend/conformance/tests/standard.spec.ts`).
+- **`static-portable`** — expressible as source patterns a generic engine
+  (Semgrep/ast-grep-class) can realise per language from this spec.
+- **`static-bespoke`** — needs deep framework knowledge (traits, `ModuleSpec`,
+  archetype slots); built per officially certified stack only.
+
+The classification is a judgment about *porting cost*, not a limit on the
+reference implementation — today every rule is enforced by `terp.arch` or
+`@terp/eslint-boundaries` regardless of layer.
+
+### Runtime applicability (the two-layer discipline, per rule)
+
+Whether a rule *additionally* pairs with a fail-closed runtime control is not a
+blanket claim — it is recorded per rule in the mandatory `runtime` block and
+held coherent by the spec suite:
+
+- **`required`** — the invariant is observable in the running system and the
+  reference implementation owns a fail-closed control for it; the entry **must**
+  declare that control as a `kind: "runtime"` enforcement entry (whose `ref`
+  must resolve to a real symbol — the framework's parity test fails otherwise).
+- **`not-applicable`** — the invariant is a property of the authored artifact
+  (source form, imports, justification markers, checked-in files) that is
+  erased or already materialised by the time the app runs, so no runtime seam
+  can enforce it. The mandatory `rationale` states why; the build-time check is
+  the control, by recorded decision.
+- **`deferred`** — a runtime control would add independent fidelity on a seam
+  the reference framework owns, but has not shipped yet: an explicit, reviewed
+  gap, never a silent one. The mandatory `rationale` names the seam, and the
+  mandatory `tracking` reference names where the deferral is tracked (an issue
+  URL or the reference implementation's tracker document plus the seam) — so a
+  deferral has a lifecycle instead of being open-ended.
+
+Fail-closed consistency (spec suite): `required` iff a `runtime` enforcement
+entry exists; an exemption always carries a non-empty rationale; a deferral
+always carries a tracking reference.
+
+### The escape-hatch contract
+
+Every rule has **at most one** governed opt-out, and its *semantics* are the
+normative part: a **justified inline marker** on (or immediately above) the
+violating line that names the **catalog rule name** (the `<rule>` half of the
+id — never a tool-internal rule id, mirroring findings attribution) and states
+a reason; an unjustified marker is itself a violation; marker counts must
+exactly match a checked-in per-app budget that can only shrink (the ratchet).
+The `opt_out` field records the reference realisation's concrete spelling
+(`# arch-allow-<rule>: <reason>` in Python, `// terp-allow-<rule>: <reason>`
+in TypeScript) — the spelling is derived from the rule id, and the spec suite
+holds the derivation. The escape-hatch **governance rules themselves** (the
+budget ratchet, the ungoverned-marker condition) carry no `opt_out`:
+governance cannot be waived by the mechanism it governs. Another stack
+implements the same contract with its own comment syntax.
+
+The `<reason>` is free text, and MAY carry structured metadata tokens so a
+long-lived exception stays visible and auditable rather than eternal:
+`owner:<who>` (who answers for the exception), `ticket:<ref>` (where its
+removal is tracked), and `review-by:<YYYY-MM-DD>` (when it must be re-justified).
+The tokens are a convention, not a gate — the marker's semantics are unchanged,
+and a checker MUST NOT reject a reason without them — but a toolchain SHOULD
+surface expired `review-by:` dates in its reporting.
+
+## Finding format
+
+A conformant checker emits an array of findings per checked tree, shaped by
+`findings.schema.json`: each finding names the **catalog rule id** it realises
+(`rule`), the file `path` relative to the checked tree's root, and optionally a
+`line`, a directive `message`, a `fix_hint` (the compliant construct, for agent
+consumers acting on findings without re-reading the catalog), and a
+`fingerprint` (a stable, checker-chosen per-instance identifier so a finding
+can be tracked across line-shifting edits). Attribution is always to the
+stack-neutral catalog id — the reference ESLint adapter, whose core rule ids
+are shared between several catalog rules, publishes this mapping as
+`catalogRuleId()` in `@terp/eslint-boundaries`.
+
+## Check-report format
+
+Findings alone cannot support a per-rule verdict: a rule with zero findings is
+only *passing* if the run actually evaluated it, and the consumer must never
+supply that knowledge itself — its own catalog copy can be newer or older than
+the checked app's pinned toolchain (version skew), and some enforcement is
+conditional (an escape-hatch budget only when one is checked in, a layout
+contract only when the app opts in). So a conformant checker reports a whole
+run as one **application check report** (`app-check-report.schema.json`): a
+format marker (`terp_check_report: 1`), the **spec version** its rule ids
+resolve against, the **checker identity** (the same identity its certification
+scorecard carries), the run **verdict** (`ok`, or an explicit `error` for a
+run that failed to complete — an erroring run never claims ok and never claims
+rules it did not finish evaluating), the **evaluated-rule inventory**
+(`rules`), the opt-in rules published as **`not_applicable`** (their own
+state — never passing, never unknown), the **findings** (exactly the finding
+format's item shape — the spec suite holds the two identical), and
+**`unattributed`** messages (diagnostics outside the standard, surfaced rather
+than dropped). A consumer joins per-rule verdicts to the catalog exclusively
+through the report's inventory, fail closed: pass = evaluated with no
+attributed finding; a rule the run did not publish renders unknown, never
+green. A multi-surface toolchain emits one report per checker run and a
+consumer merges reports through their inventories.
+
+## Scorecard format
+
+A checker claiming certification emits a scorecard (`scorecard.schema.json`):
+the spec version it certified against, the checker's identity, and one entry
+per claimed rule with its pass/fail verdict over the corpus and the residuals
+it relies on (which must be a subset of `corpus/RESIDUALS.json` for the rule —
+claiming an unrecorded residual is a conformance failure). A consumer can
+re-run the corpus and reproduce the scorecard, making the certification claim
+verifiable.
+
+## Assurance profile
+
+Conformance to the rule catalog proves the *Terp-specific* half of release
+readiness. The **assurance profile** (`assurance-profile.schema.json`) is the
+machine-readable composition of that with the generic evidence lanes a release
+also stands on — one document a toolchain emits from its release verification
+profile, so "this build is releasable" becomes a checkable artifact instead of
+a habit.
+
+The lane vocabulary and each lane's requirement level are **normative** and
+fixed here — an emitter cannot demote a required lane, which is why the
+requirement level is deliberately not a field of the document:
+
+| Lane | Requirement | Evidence |
+|---|---|---|
+| `terp-standard` | **required** | The standard's own enforcement surfaces ran and passed: the architecture gate and the frontend boundary lint, publishing their evaluated-rule inventories (check reports). |
+| `appsec-baseline` | **required** | The delegated generic AppSec baseline passed (the reference realisation: `ruff` with the flake8-bandit `S` rules). |
+| `dependency-audit` | **required** | Dependency trees were audited against known-vulnerability databases (the reference realisation: `pip-audit` and `npm audit`). |
+| `a11y` | recommended | Automated accessibility checks over the running app (e.g. axe). |
+| `blackbox-conformance` | recommended | The black-box behavioural conformance suite over the running workbench. |
+
+The claim (`ok`) is true exactly when every **required** lane passed;
+recommended lanes inform the reader but never carry the claim. Every lane of
+the vocabulary appears exactly once — a lane the toolchain does not realise is
+reported `not-run` (with no composing checks), never dropped and never counted
+as passed. Each realised lane names the verification-check ids whose verdicts
+compose it, so a consumer can trace the claim into the toolchain's own
+verification envelope.
+
+## Corpus format
+
+```text
+corpus/backend/<rule>/violation-01/  # files rooted at the app package root
+corpus/backend/<rule>/compliant-01/  #   e.g. modules/notes/service.py
+corpus/frontend/<rule>/violation-01/ # files rooted at the frontend app root
+corpus/frontend/<rule>/compliant-01/ #   e.g. src/modules/widgets/Widget.tsx
+```
+
+A case may ship an extra checker input at its root when the rule takes one:
+the `backend/escape_hatch_budget` cases carry the `escape-hatch-budget.json`
+the ratchet is verified against, and a frontend layout-contract case activates
+via a `layout-contract.json` at its root.
+
+A violation case MAY additionally ship an **`expected-findings.json`** at its
+root: the exact findings (rule + path + line, shaped by
+`findings.schema.json`) a maximally-precise checker emits for the rule under
+test. A harness may assert the manifest exactly — hardening the per-case
+contract from "flags something" to "flags the right line" — while the loose
+contract below remains the floor for cases without one (and the ceiling a
+checker must reach to conform). The spec suite holds every checked-in manifest
+to the finding shape and to the case it sits in.
+
+The contract for a checker claiming conformance for a rule is stated **per
+rule**, over the finding format above:
+
+- every `violation-*` case produces at least one finding attributed to that
+  rule's catalog id, and
+- every `compliant-*` case produces **no** findings for that rule.
+
+A compliant case is minimal, not a full application — it may legitimately be
+incomplete with respect to *other* rules, so a multi-rule checker scopes the
+corpus run to the rule under test. (The reference frontend harness happens to
+hold its compliant cases fully clean across all boundary rules — a stricter
+bar than the contract requires.)
+
+### Detector boundaries (what the corpus deliberately does not require)
+
+The executable corpus **is** the interoperability contract: a checker is
+conformant for a rule when it flags every `violation-*` case and stays silent
+on every `compliant-*` case — nothing more. The violation cases include the
+evasion shapes the rules are expected to see through (qualified/attribute
+calls, multiline constructs, values routed through a local variable or
+`.format()`/`%` building, aliased and parenthesized imports, computed
+`window["fetch"]`-style member access for the egress family), and the
+compliant cases pin the near-misses that must **not** fire (adjacent-literal
+SQL that merely looks concatenated, credential-shaped names with dynamic
+values, `*_mock`/`socketserver`-style name cousins, member calls like
+`repo.fetch(...)` / `interpreter.eval(...)` on local objects, forbidden syntax
+quoted inside comments and strings).
+
+Some statically-erased or renamed forms are **deliberately outside** the
+contract — known limits of precise, low-false-positive detection, kept out of
+the corpus so a second implementation neither over-fits nor under-claims.
+These residuals are recorded per rule in **`corpus/RESIDUALS.json`** — a
+machine-readable ratchet governed like `corpus/PENDING.json`: the list only
+shrinks, and closing a residual means seeding the corpus case that contracts
+it and deleting the entry, never silently. Today it records:
+
+- an alias-renamed symbol import (`from sqlalchemy import text as sql_text`)
+  is not required to be resolved to `text`;
+- dynamic import (`importlib.import_module("httpx")`) is not required to be
+  seen as an import;
+- a computed sink or global (`el["innerHTML"] = …`, `window["eval"]`) is not
+  required to be recognised for the *eval/DOM-sink* rules (the egress family
+  **does** contract the computed forms — its cases include them);
+- `Function("…")` called without `new`, and egress through receivers other
+  than `window`/`globalThis` (`self.fetch`), are not required.
+
+These residuals are governed the usual way: the escape-hatch contract makes
+sanctioned exceptions visible, and the paired runtime controls (where
+`runtime.applicability` is `required`) hold the invariant regardless of
+spelling. Widening a detector past the contract is always allowed — the
+corpus states the floor, not the ceiling.
+
+The reference implementations are themselves held to this contract in CI:
+`test_spec_corpus.py` runs each catalogued `terp.arch` rule over the backend
+corpus, and `corpus.test.js` runs the ESLint adapter over the frontend corpus,
+attributing findings via `catalogRuleId()`. Corpus sample files are
+intentionally violating code — they are excluded from repo-wide lint
+(`ruff` `extend-exclude`) and are never imported or executed.
+
+Coverage is governed by **`corpus/PENDING.json`**: the exact list of rules
+still without cases. Seeding a rule's corpus removes it from the list; a new
+rule shipped without corpus must be listed there explicitly — so uncovered
+rules stay visible and the list only shrinks. Every `static-portable` backend
+rule must have cases (enforced by the parity test); today every backend and
+frontend rule has cases and the pending list is empty — it exists so a *new*
+rule can ship with its gap explicit and reviewed.
+
+## Conformance levels
+
+- **Level 1 — black-box:** the app passes the runnable conformance suite
+  (`@terp/conformance`) for the capabilities it claims, including the
+  `standard:` probes the `black-box` catalog entries name.
+- **Level 2 — static rule pack:** additionally, a checker validated against
+  this corpus enforces the `static-portable` rules for the app's language(s),
+  emitting findings per `findings.schema.json`.
+- **Level 3 — full harness:** additionally, the `static-bespoke` rules, the
+  paired `runtime` controls of every rule whose `runtime.applicability` is
+  `required`, and the governed escape-hatch budget ratchet are enforced (today:
+  the `terp.arch` + `@terp/eslint-boundaries` reference harness on top of
+  `terp.core` / `@terp/react-core`).
+
+## Growing the spec
+
+- **New rule** → ship the rule and its catalog entry together (the parity test
+  fails otherwise); classify its runtime applicability deliberately (`required`
+  with the declared control, or an exemption with its rationale — a deferral
+  also names its `tracking` reference); seed corpus cases when the rule is
+  portable, or list it in `corpus/PENDING.json` explicitly; regenerate the
+  rule pages (`python tools/generate_rule_docs.py`).
+- **New corpus cases** → add `violation-*`/`compliant-*` directories, flip the
+  entry's `corpus` flag to `true`, and drop the rule from `corpus/PENDING.json`;
+  the harness picks the cases up by convention. Ship an `expected-findings.json`
+  when the violating lines are pinned. Closing a documented detector residual
+  also deletes its `corpus/RESIDUALS.json` entry.
+- **New stack** → implement the `static-portable` rules however you like; the
+  corpus is the acceptance test, findings must attribute to catalog ids, and
+  the certification summary is a scorecard (`scorecard.schema.json`).
+- **Format change** → bump `VERSION` and add the matching `CHANGELOG.md` entry
+  (the suite holds the top entry to the version). Pre-1.0, a **changed
+  contract** — a new mandatory catalog field (0.5.0's `runtime` block), a
+  changed finding shape —
+  bumps the **minor** (the strongest signal 0.x semver carries; a 0.x major
+  would claim a stability this spec does not yet promise); purely additive
+  fields and new rules also bump the minor; prose bumps the patch. From 1.0.0
+  a changed contract bumps the **major**.

package/VERSION

@@ -0,0 +1 @@
+0.14.0