@aicent/iqa 1.2.6 → 1.2.8

package/README.md

@@ -1,14 +1,14 @@
 # @aicent/iqa
 
 **IQA for JavaScript: `iqa://` subject-attestation addressing, `IQA_ROUTE`
-derivation, action safety classes — and the published conformance vectors that
+derivation, action safety classes -- and the published conformance vectors that
 prove an implementation is right.**
 
-[RFC-009 §10](https://iqa.org/RFC-009/) · §11 · v1.2.6 · zero dependencies · no build step
+[RFC-009 sec. 10](https://iqa.org/RFC-009/) - sec. 11 - stack v1.2.6 - zero dependencies - no build step
 
 ---
 
-## Verify it in one command — no trust required
+## Verify it in one command -- no trust required
 
 ```console
 $ npx @aicent/iqa
@@ -18,22 +18,27 @@ $ npx @aicent/iqa
 That is the point of this package. A specification is worth exactly what an
 independent implementation can reproduce from it, so instead of asking you to
 believe a table of numbers, the vectors ship inside the package and replay
-locally — offline, no account, no network. `[PASS]` or it is not.
+locally -- offline, no account, no network. `[PASS]` or it is not. Every vector file shipped here is listed in `vectors.manifest.json` with its byte count and SHA-256, produced by a generator rather than typed by hand - recompute the hash yourself if you prefer.
 
-The vectors cover the `iqa://` grammar (RFC-009 §10.2), the **closed sets**
-(`organ` and `action` — the deliberate difference from `rttp`, whose verb set
-is open), the §11.3 action safety classes, the `IQA_ROUTE` derivation, **and**
-the deterministic Ed25519 attestation envelope — replayed by both
+The vectors cover the `iqa://` grammar (RFC-009 sec. 10.2), the **closed sets**
+(`organ` and `action` -- the deliberate difference from `rttp`, whose verb set
+is open), the sec. 11.3 action safety classes, the `IQA_ROUTE` derivation, **and**
+the deterministic Ed25519 attestation envelope -- replayed by both
 implementations.
 
-### The other half — Python, on PyPI
+### The other half -- Python, on PyPI
 
 ```console
 $ pip install iqa-org
 $ python -m iqa.selftest
+[PASS] all 75 checks passed (3 skipped)   # default install
+
+$ pip install iqa-org[ed25519]
+$ python -m iqa.selftest
+[PASS] all 78 checks passed               # with the optional Ed25519 backend
 ```
 
-Published as **`@aicent/iqa`** — the bare `iqa` name is unregistered on npm but
+Published as **`@aicent/iqa`** -- the bare `iqa` name is unregistered on npm but
 blocked by its typosquatting protection, so the JavaScript side lives under
 this project's organization, as `@aicent/rttp` already does. PyPI applies the
 same class of guard: the Python package is therefore **`iqa-org`** (same name
@@ -62,10 +67,10 @@ import { parse } from '@aicent/iqa';
 
 const r = parse('iqa://3f9a1b2c.gateway.iqa');
 
-r.subject        // '3f9a1b2c'   — 8-hex routing short form of the AID
-r.organ          // 'gateway'    — closed set: forge | tss | gateway
-r.action         // null         — omitted = standing read (§11.1)
-r.action_safe    // true         — §11.3: omitted and verify are SAFE
+r.subject        // '3f9a1b2c'   -- 8-hex routing short form of the AID
+r.organ          // 'gateway'    -- closed set: forge | tss | gateway
+r.action         // null         -- omitted = standing read (sec. 11.1)
+r.action_safe    // true         -- sec. 11.3: omitted and verify are SAFE
 r.canonical_uri  // 'iqa://3f9a1b2c.gateway.iqa'
 r.route_hex      // '5c378581'   <- pure computation, pinned by the vectors
 ```
@@ -80,28 +85,28 @@ $ node examples/quickstart.mjs
 Its expected output is the route fingerprint the published conformance vectors
 pin for that address, so the example can be **checked** rather than believed.
 
-Addressing is **DNS-free** (RFC-009 §12 #9): the route fingerprint is derived
+Addressing is **DNS-free** (RFC-009 sec. 12 #9): the route fingerprint is derived
 from the authority by SHA-256, so no registry, resolver or network is
-involved. A URI either yields its fields or throws — there is no fallback, no
+involved. A URI either yields its fields or throws -- there is no fallback, no
 `iqas`, and no rewriting to `https`.
 
 ---
 
-## The two closed sets — the deliberate difference from `rttp`
+## The two closed sets -- the deliberate difference from `rttp`
 
-`rttp` accepts any well-formed action verb. **`iqa` does not.** RFC-009 §10.1
+`rttp` accepts any well-formed action verb. **`iqa` does not.** RFC-009 sec. 10.1
 marks *both* segments "Closed set", and this package enforces exactly that:
 
 ```js
-parse('iqa://3f9a1b2c.gateway.iqa/pulse')  // throws — 'pulse' is an rttp verb
-parse('iqa://3f9a1b2c.forgery.iqa')        // throws — organ is forge|tss|gateway
+parse('iqa://3f9a1b2c.gateway.iqa/pulse')  // throws -- 'pulse' is an rttp verb
+parse('iqa://3f9a1b2c.forgery.iqa')        // throws -- organ is forge|tss|gateway
 ```
 
 ### The one rule that surprises people
 
-**Malformed input is rejected, not normalised.** `iqa://…/AUDIT`,
-`iqa://3F9A1B2C.…` and `IQA://…` all throw: the canonical form is lowercase
-US-ASCII (RFC-009 §10.3), a case variant is not a spelling difference, and
+**Malformed input is rejected, not normalised.** `iqa://.../AUDIT`,
+`iqa://3F9A1B2C....` and `IQA://...` all throw: the canonical form is lowercase
+US-ASCII (RFC-009 sec. 10.3), a case variant is not a spelling difference, and
 nothing is ever accepted because a check could not be performed.
 
 ### One honest quirk of the grammar
@@ -113,36 +118,36 @@ implementation agrees on it.
 
 ---
 
-## Action safety classes (RFC-009 §11.3)
+## Action safety classes (RFC-009 sec. 11.3)
 
 | `action` | Class | `action_safe` |
 |:---|:---|:---|
-| *(omitted)* | SAFE — standing read | `true` |
-| `verify` | SAFE — read-only comparison | `true` |
-| `audit` | NOT SAFE — can trigger Authority Ischemia | `false` |
-| `attest` | NOT SAFE — state transition | `false` |
-| `revoke` | NOT SAFE — state transition | `false` |
+| *(omitted)* | SAFE -- standing read | `true` |
+| `verify` | SAFE -- read-only comparison | `true` |
+| `audit` | NOT SAFE -- can trigger Authority Ischemia | `false` |
+| `attest` | NOT SAFE -- state transition | `false` |
+| `revoke` | NOT SAFE -- state transition | `false` |
 
-Per §11.2, dereferencing an `iqa` URI MUST NOT transition any subject's
+Per sec. 11.2, dereferencing an `iqa` URI MUST NOT transition any subject's
 standing. Tooling built on this package MUST gate the three NOT-SAFE verbs
-behind an explicit user action — parsing one is not requesting one.
+behind an explicit user action -- parsing one is not requesting one.
 
 ---
 
-## API — main entry
+## API -- main entry
 
 | Export | What it does |
 |:---|:---|
 | `parse(uri)` | Validate, canonicalise, classify, derive. Throws `IqaUriError`. |
 | `deriveRoute(authority)` | `Uint8Array(4)` = `SHA-256(ASCII(authority))[0:4]`. |
 | `deriveRouteHex(authority)` | The same, as 8 lowercase hex characters. |
-| `isValidAction(value)` | §10.1 closed-set test. |
+| `isValidAction(value)` | sec. 10.1 closed-set test. |
 | `IqaUriError` | The only error type thrown. |
 | `SCHEME`, `ORGANS`, `ACTIONS`, `STANDINGS`, `HASH_LENGTHS` | Constants. |
 
-### The attestation envelope — `@aicent/iqa/conformance`
+### The attestation envelope -- `@aicent/iqa/conformance`
 
-The deterministic Ed25519 envelope (SPEC/IQA-URI-ATTEST-v1.2.6 §5: domain
+The deterministic Ed25519 envelope (SPEC/IQA-URI-ATTEST-v1.2.6 sec. 5: domain
 prefix `iqa-attest-v1`, `AID = SHA-256(pub)`, `ts`/`nonce` inside the
 signature, 120-second freshness) is part of the shared vector set and is
 replayed by this package's conformance run. `buildSigningInput` is exported
@@ -174,9 +179,9 @@ In CI:
 
 | Group | Count | What it proves |
 |:---|---:|:---|
-| `positive_uris` | 8 | Accept, classify and derive — §10.3's own examples, the 256-bit form, the all-zero boundary, the name-subject fall-through |
-| `negative_uris` | 18 | Reject — uppercase anywhere, `iqas://`, userinfo, port, query, fragment, wrong authority shape, closed-set violations on both segments |
-| `action_safety` | 5 | §11.3 classes as data |
+| `positive_uris` | 8 | Accept, classify and derive -- sec. 10.3's own examples, the 256-bit form, the all-zero boundary, the name-subject fall-through |
+| `negative_uris` | 18 | Reject -- uppercase anywhere, `iqas://`, userinfo, port, query, fragment, wrong authority shape, closed-set violations on both segments |
+| `action_safety` | 5 | sec. 11.3 classes as data |
 | `attest_envelope_vector` | 1 | Deterministic Ed25519 envelope, verified through `node:crypto` |
 
 `vectors.json` is plain JSON and ships inside the package, also reachable as
@@ -185,10 +190,10 @@ is what it is for.
 
 ### Why the checker lives in this package, and why that is still honest
 
-`src/conformance.mjs` is written from RFC-009 §10 alone and **must never
+`src/conformance.mjs` is written from RFC-009 sec. 10 alone and **must never
 import `src/iqa-uri.mjs`**. A conformance suite that reuses the code under
-test only proves the code equals itself. The two files share no code — one is
-a streaming charset scanner, the other a single full-match grammar check — so
+test only proves the code equals itself. The two files share no code -- one is
+a streaming charset scanner, the other a single full-match grammar check -- so
 the rule is checkable by reading them.
 
 The vectors are **generated, not written**. `generated_by` in the JSON names
@@ -198,20 +203,20 @@ starts agreeing with its own bugs.
 
 ---
 
-## Scope — what this package is not
+## Scope -- what this package is not
 
 | | |
 |:---|:---|
-| ✅ **Validation / canonicalisation** | Real, and specified (RFC-009 §10.2 / §10.3). |
-| ✅ **Closed-set enforcement** | Real, and specified (§10.1). |
-| ✅ **IQA_ROUTE derivation** | Real (SPEC §3, decision D1). |
-| ✅ **Action safety classes** | Real, and specified (§11.3). |
-| ✅ **Conformance vectors + independent replay** | Published and generated. |
-| ❌ **Dereferencing / resolver service** | Not here. The codec computes; *answering* a standing read is an Organ's job (RFC-009-C §3). |
-| ❌ **Staking, tiers, vitality** | Operator economics and telemetry — RFC-009 narrative, no cryptographic object in this package. |
-| ❌ **Post-quantum Lattice Guard** | RFC-009 §12 #11 schedules it for v1.4.0; no implementation exists. |
-| ❌ **Revocation transport** | §11.3 defines the verb; executing it is not the codec's job. |
-| ❌ **Confidentiality** | Signing is not encryption. |
+| OK **Validation / canonicalisation** | Real, and specified (RFC-009 sec. 10.2 / sec. 10.3). |
+| OK **Closed-set enforcement** | Real, and specified (sec. 10.1). |
+| OK **IQA_ROUTE derivation** | Real (SPEC sec. 3, decision D1). |
+| OK **Action safety classes** | Real, and specified (sec. 11.3). |
+| OK **Conformance vectors + independent replay** | Published and generated. |
+| NO **Dereferencing / resolver service** | Not here. The codec computes; *answering* a standing read is an Organ's job (RFC-009-C sec. 3). |
+| NO **Staking, tiers, vitality** | Operator economics and telemetry -- RFC-009 narrative, no cryptographic object in this package. |
+| NO **Post-quantum Lattice Guard** | RFC-009 sec. 12 #11 schedules it for v1.4.0; no implementation exists. |
+| NO **Revocation transport** | sec. 11.3 defines the verb; executing it is not the codec's job. |
+| NO **Confidentiality** | Signing is not encryption. |
 
 ---
 
@@ -219,21 +224,27 @@ starts agreeing with its own bugs.
 
 | Ecosystem | Name | Status |
 |:---|:---|:---|
-| crates.io | `iqa-org` | held by this project (Shipyard Rust crate) |
-| PyPI | **`iqa-org`** | **published** — the Python reference implementation; `pip install iqa-org` (bare `iqa` blocked by PyPI's typosquatting protection, same class of guard as npm) |
-| npm | **`@aicent/iqa`** | the bare `iqa` name is unregistered but **blocked by npm's typosquatting protection** (too similar to existing short names) — so this package is published under the organization this project controls, as `@aicent/rttp` already is. The package name itself is still just `iqa`. |
+| crates.io | **`iqa-org`** | **published** -- `1.2.8-alpha`. Every published version of this crate is a pre-release, so Cargo will not select it from a plain `iqa-org` requirement: write `cargo add iqa-org@1.2.8-alpha`. |
+| PyPI | **`iqa-org`** | **published** -- the Python reference implementation; `pip install iqa-org` (bare `iqa` blocked by PyPI's typosquatting protection, same class of guard as npm) |
+| npm | **`@aicent/iqa`** | the bare `iqa` name is unregistered but **blocked by npm's typosquatting protection** (too similar to existing short names) -- so this package is published under the organization this project controls, as `@aicent/rttp` already is. The package name itself is still just `iqa`. |
 
 ---
 
 ## Specification status
 
-* **`iqa` URI scheme** — submitted to IANA under RFC 7595, ticket **#1459963**,
-  Provisional, **under review**. It is **not yet registered** — as of
-  2026-09-18 the IANA "URI Schemes" registry contains no `iqa` entry. Please
+* **`iqa` URI scheme** -- submitted to IANA under RFC 7595, ticket **#1459963**,
+  Provisional, **under review**. It is **not yet registered** -- as of
+  2026-09-20 the IANA "URI Schemes" registry contains no `iqa` entry. Please
   describe it that way.
-* **URI grammar** — RFC-009 §10.2 (frozen; this package adds no syntax).
-* **Dereference safety** — RFC-009 §11 (closed sets and safety classes).
-* **Attestation envelope** — `SPEC/IQA-URI-ATTEST-v1.2.6.md` §5, a **draft**:
+* **Internet-Draft (IETF)** -- under IETF review as the Individual Submission
+  Internet-Draft `draft-li-iqa-subject-attestation` (revision -00, posted
+  2026-09-20, informational):
+  https://datatracker.ietf.org/doc/draft-li-iqa-subject-attestation/ .
+  An Internet-Draft is a working document -- it is not an IETF standard and
+  carries no IETF endorsement.
+* **URI grammar** -- RFC-009 sec. 10.2 (frozen; this package adds no syntax).
+* **Dereference safety** -- RFC-009 sec. 11 (closed sets and safety classes).
+* **Attestation envelope** -- `SPEC/IQA-URI-ATTEST-v1.2.6.md` sec. 5, a **draft**:
   the format is implemented and vector-tested, but it is not yet a numbered
   RFC-009 section.
 

package/bin/iqa.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// iqa — replay the published conformance vectors. [PASS] or it is not.
+// iqa -- replay the published conformance vectors. [PASS] or it is not.
 //
 //   npx @aicent/iqa                       # replay the shipped vectors
 //   npx @aicent/iqa --vectors ./new.json  # replay a different vector set
@@ -22,7 +22,7 @@ for (let i = 0; i < args.length; i++) {
   } else if (args[i] === '--json') {
     json = true;
   } else if (args[i] === '--help' || args[i] === '-h') {
-    console.log('@aicent/iqa — replay the published conformance vectors (RFC-009 §10/§11)');
+    console.log('@aicent/iqa -- replay the published conformance vectors (RFC-009 sec. 10/sec. 11)');
     console.log('  npx @aicent/iqa                       replay the shipped vectors');
     console.log('  npx @aicent/iqa --vectors ./new.json  replay a different vector set');
     console.log('  npx @aicent/iqa --json                machine-readable output');
@@ -51,7 +51,7 @@ if (json) {
     vectors: vectorsPath,
   }, null, 2));
 } else {
-  console.log(`iqa conformance replay — spec ${vectors.spec ?? '(unlabeled)'}`);
+  console.log(`iqa conformance replay -- spec ${vectors.spec ?? '(unlabeled)'}`);
   for (const f of result.failures) console.log(`[FAIL] ${f}`);
   console.log(`[PASS] all ${result.checked} checks passed`);
 }

package/examples/quickstart.mjs

@@ -1,4 +1,4 @@
-// The same three lines as the README quickstart — runnable, so the example can
+// The same three lines as the README quickstart -- runnable, so the example can
 // be CHECKED rather than believed. Its expected output is the route fingerprint
 // the published conformance vectors pin for that address.
 //

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@aicent/iqa",
-  "version": "1.2.6",
-  "description": "IQA for JavaScript: iqa:// subject-attestation addressing, IQA_ROUTE derivation, action safety classes — and the published conformance vectors that prove an implementation is right.",
+  "version": "1.2.8",
+  "description": "IQA for JavaScript: iqa:// subject-attestation addressing, IQA_ROUTE derivation, action safety classes -- and the published conformance vectors that prove an implementation is right.",
   "author": "IQA.ORG Organization",
   "license": "Apache-2.0",
+  "homepage": "https://iqa.org/",
   "type": "module",
   "main": "./src/iqa-uri.mjs",
   "types": "./src/iqa-uri.d.mts",
@@ -42,7 +43,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Aicent-Stack/aicent-stack.git"
+    "url": "git+https://github.com/Aicent-Stack/iqa-org.git"
   },
   "publishConfig": {
     "access": "public"

package/src/conformance.d.mts

@@ -13,9 +13,9 @@ export interface ParsedForConformance {
 }
 
 /**
- * The independent RFC-009 §10 implementation used by the checker.
- * `buildFrame`-style helpers do not exist here: IQA v1.2.6 has no frame —
- * the derivation chain is URI → IQA_ROUTE (4 bytes).
+ * The independent RFC-009 sec. 10 implementation used by the checker.
+ * `buildFrame`-style helpers do not exist here: IQA v1.2.6 has no frame --
+ * the derivation chain is URI -> IQA_ROUTE (4 bytes).
  */
 export declare function parseUri(uri: string): ParsedForConformance;
 

package/src/conformance.mjs

@@ -1,13 +1,13 @@
-// IQA conformance replay — an INDEPENDENT implementation of RFC-009 §10.
+// IQA conformance replay -- an INDEPENDENT implementation of RFC-009 sec. 10.
 //
-// This file is written from RFC-009 §10/§11 alone and MUST NEVER import
+// This file is written from RFC-009 sec. 10/sec. 11 alone and MUST NEVER import
 // ./iqa-uri.mjs. A conformance suite that reuses the code under test only
 // proves the code equals itself. The two files share no code, so the rule is
 // checkable by reading them.
 //
 // They ship together for the same reason the Python wheel ships its self-test:
 // so a stranger can verify an installed package offline, with no repository
-// checkout. Zero dependencies — node:crypto and node:fs only.
+// checkout. Zero dependencies -- node:crypto and node:fs only.
 
 import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
 import { readFileSync } from 'node:fs';
@@ -17,7 +17,7 @@ import { dirname, join } from 'node:path';
 const DOMAIN = Buffer.from('iqa-attest-v1\n', 'utf8');
 
 // ---------------------------------------------------------------------------
-// Independent parse — single full-match grammar check, deliberately different
+// Independent parse -- single full-match grammar check, deliberately different
 // in structure from the streaming charset scanner in iqa-uri.mjs.
 // ---------------------------------------------------------------------------
 
@@ -27,9 +27,9 @@ const DOMAIN = Buffer.from('iqa-attest-v1\n', 'utf8');
 // so uppercase, '@', ':', '?', '#', whitespace and all foreign bytes fail.
 const GRAMMAR = /^iqa:\/\/([a-z0-9-]+)\.([a-z0-9-]+)\.([a-z0-9-]+)(?:\/([a-z0-9-]+))?$/;
 
-const ORGANS = ['forge', 'tss', 'gateway'];         // §10.1 closed set
-const ACTIONS = ['verify', 'audit', 'attest', 'revoke']; // §10.1 closed set
-const HASH_LENGTHS = [8, 32, 64];                   // §10.2 hash-subject
+const ORGANS = ['forge', 'tss', 'gateway'];         // sec. 10.1 closed set
+const ACTIONS = ['verify', 'audit', 'attest', 'revoke']; // sec. 10.1 closed set
+const HASH_LENGTHS = [8, 32, 64];                   // sec. 10.2 hash-subject
 
 export function parseUri(uri) {
   const m = GRAMMAR.exec(uri);
@@ -58,7 +58,7 @@ export function parseUri(uri) {
     authority: `${subject}.${organ}.${root}`,
     action,
     action_omitted: action === null,
-    action_safe: action === null || action === 'verify', // §11.3
+    action_safe: action === null || action === 'verify', // sec. 11.3
     canonical_uri: 'iqa://' + `${subject}.${organ}.${root}` + (action ? '/' + action : ''),
     route_hex: createHash('sha256').update(`${subject}.${organ}.${root}`, 'ascii')
       .digest().subarray(0, 4).toString('hex'),
@@ -66,7 +66,7 @@ export function parseUri(uri) {
 }
 
 // ---------------------------------------------------------------------------
-// Envelope — canonical JSON + Ed25519 over the domain-separated input.
+// Envelope -- canonical JSON + Ed25519 over the domain-separated input.
 // ---------------------------------------------------------------------------
 
 function canonicalize(value) {
@@ -120,7 +120,7 @@ export function loadVectors(path = DEFAULT_VECTORS_PATH) {
 }
 
 /**
- * Replay a vector set → { checked, failures, passed }.
+ * Replay a vector set -> { checked, failures, passed }.
  * The checker accepts any object with the documented groups, so a different
  * vector set (e.g. a candidate next revision) can be replayed the same way.
  */

package/src/iqa-uri.d.mts

@@ -1,5 +1,5 @@
 /**
- * iqa — RFC-009 §10/§11 codec for JavaScript.
+ * iqa -- RFC-009 sec. 10/sec. 11 codec for JavaScript.
  * Zero dependencies. Field names are snake_case on purpose: they match the
  * published conformance vectors (and the Python implementation) field for field.
  */
@@ -12,12 +12,12 @@ export declare const HASH_LENGTHS: readonly [8, 32, 64];
 
 export declare class IqaUriError extends Error {}
 
-/** True only for the closed four-verb set (RFC-009 §10.1). */
+/** True only for the closed four-verb set (RFC-009 sec. 10.1). */
 export declare function isValidAction(value: string): boolean;
 
 /**
- * IQA_ROUTE = SHA-256(ASCII(canonical_authority))[0:4]  (SPEC §3).
- * The address fingerprint — not the subject hash (which hints the AID).
+ * IQA_ROUTE = SHA-256(ASCII(canonical_authority))[0:4]  (SPEC sec. 3).
+ * The address fingerprint -- not the subject hash (which hints the AID).
  */
 export declare function deriveRoute(authority: string): Uint8Array;
 export declare function deriveRouteHex(authority: string): string;
@@ -32,7 +32,7 @@ export interface ParsedUri {
   authority: string;
   action: string | null;
   action_omitted: boolean;
-  /** RFC-009 §11.3 — true for omitted and `verify`, false for audit/attest/revoke. */
+  /** RFC-009 sec. 11.3 -- true for omitted and `verify`, false for audit/attest/revoke. */
   action_safe: boolean;
   canonical_uri: string;
   route_hex: string;

package/src/iqa-uri.mjs

@@ -1,35 +1,35 @@
-// iqa:// URI codec — validate, canonicalise, derive (RFC-009 §10/§11).
+// iqa:// URI codec -- validate, canonicalise, derive (RFC-009 sec. 10/sec. 11).
 //
 // Authority boundaries:
-//   Grammar ......... RFC-009 §10.2 ABNF (sole authority)
-//   Closed sets ..... §10.1 (organ and action are CLOSED sets)
-//   Case discipline . §10.3 (lowercase US-ASCII only) + §12 #8 (fail closed)
-//   Deref safety .... §11.3 (action safety classes)
-//   Route derivation  SPEC/IQA-URI-ATTEST-v1.2.6.md §3 (IQA_ROUTE)
+//   Grammar ......... RFC-009 sec. 10.2 ABNF (sole authority)
+//   Closed sets ..... sec. 10.1 (organ and action are CLOSED sets)
+//   Case discipline . sec. 10.3 (lowercase US-ASCII only) + sec. 12 #8 (fail closed)
+//   Deref safety .... sec. 11.3 (action safety classes)
+//   Route derivation  SPEC/IQA-URI-ATTEST-v1.2.6.md sec. 3 (IQA_ROUTE)
 //
-// Zero dependencies. Node 18+. No build step — the published src/ is what runs.
+// Zero dependencies. Node 18+. No build step -- the published src/ is what runs.
 
 import { createHash } from 'node:crypto';
 
 export const SCHEME = 'iqa';
 
-/** RFC-009 §10.1 — organ is a CLOSED set (RFC-009-A/-B/-C). */
+/** RFC-009 sec. 10.1 -- organ is a CLOSED set (RFC-009-A/-B/-C). */
 export const ORGANS = Object.freeze(['forge', 'tss', 'gateway']);
 
 /**
- * RFC-009 §10.1 — action is a CLOSED set. This is the deliberate difference
+ * RFC-009 sec. 10.1 -- action is a CLOSED set. This is the deliberate difference
  * from `rttp`, whose verb set is open: here anything outside the four verbs
  * is rejected.
  */
 export const ACTIONS = Object.freeze(['verify', 'audit', 'attest', 'revoke']);
 
-/** RFC-009-C §3 — standings an Organ may render (closed set, lowercase). */
+/** RFC-009-C sec. 3 -- standings an Organ may render (closed set, lowercase). */
 export const STANDINGS = Object.freeze(['ghost', 'probation', 'radiant', 'genesis']);
 
-/** RFC-009 §10.2 — hash-subject lengths: routing short form / 128-bit / 256-bit. */
+/** RFC-009 sec. 10.2 -- hash-subject lengths: routing short form / 128-bit / 256-bit. */
 export const HASH_LENGTHS = Object.freeze([8, 32, 64]);
 
-const SAFE = new Set([null, 'verify']); // §11.3: omitted = standing read; verify = read-only
+const SAFE = new Set([null, 'verify']); // sec. 11.3: omitted = standing read; verify = read-only
 const LOWHEX = new Set('0123456789abcdef');
 const NAME_CHARS = new Set('abcdefghijklmnopqrstuvwxyz0123456789-');
 const ALLOWED = new Set([...LOWHEX, ...NAME_CHARS, '.', '/']);
@@ -44,17 +44,17 @@ export class IqaUriError extends Error {
 
 const fail = (uri, reason) => new IqaUriError(`${JSON.stringify(uri)}: ${reason}`);
 
-/** §10.2 action test — true only for the closed four-verb set. */
+/** sec. 10.2 action test -- true only for the closed four-verb set. */
 export function isValidAction(value) {
   return ACTIONS.includes(value);
 }
 
 /**
- * IQA_ROUTE = SHA-256(ASCII(canonical_authority))[0:4]  (SPEC §3, decision D1).
+ * IQA_ROUTE = SHA-256(ASCII(canonical_authority))[0:4]  (SPEC sec. 3, decision D1).
  *
- * Pure computation, DNS-free (RFC-009 §12 #9). Mirrors the RTTP ROUTE_SHARD
+ * Pure computation, DNS-free (RFC-009 sec. 12 #9). Mirrors the RTTP ROUTE_SHARD
  * rule so both schemes of the same addressing family derive the same way.
- * NOTE: this is the *address* fingerprint — NOT the subject hash, which is a
+ * NOTE: this is the *address* fingerprint -- NOT the subject hash, which is a
  * routing hint for the *AID*. Different numbers about different things.
  */
 export function deriveRoute(authority) {
@@ -71,7 +71,7 @@ export function deriveRouteHex(authority) {
  * Validate, canonicalise and derive. Throws IqaUriError on any violation.
  *
  * Returned fields are snake_case ON PURPOSE so this output and the Python
- * package's output compare directly against the published vectors — field
+ * package's output compare directly against the published vectors -- field
  * for field, byte for byte.
  */
 export function parse(uri) {
@@ -80,20 +80,20 @@ export function parse(uri) {
   const prefix = SCHEME + '://';
   if (!uri.startsWith(prefix)) {
     throw fail(uri, `scheme must be exactly ${JSON.stringify(prefix)} - no other `
-      + 'scheme, no case variant, no fallback (RFC-009 §10.3, §12 #8)');
+      + 'scheme, no case variant, no fallback (RFC-009 sec. 10.3, sec. 12 #8)');
   }
   const rest = uri.slice(prefix.length);
 
-  // Charset gate: lowercase US-ASCII only (§10.3). One scan rejects uppercase
+  // Charset gate: lowercase US-ASCII only (sec. 10.3). One scan rejects uppercase
   // anywhere, userinfo '@', port ':', query '?', fragment '#', whitespace and
   // every other foreign byte.
   for (const ch of rest) {
     if (!ALLOWED.has(ch)) {
       if (FORBIDDEN.has(ch)) {
-        throw fail(uri, `${JSON.stringify(ch)} is not defined by the scheme (RFC-009 §10.3)`);
+        throw fail(uri, `${JSON.stringify(ch)} is not defined by the scheme (RFC-009 sec. 10.3)`);
       }
       if (/\s/.test(ch)) {
-        throw fail(uri, 'whitespace is not allowed (RFC-009 §10.3 lowercase US-ASCII only)');
+        throw fail(uri, 'whitespace is not allowed (RFC-009 sec. 10.3 lowercase US-ASCII only)');
       }
       throw fail(uri, `character ${JSON.stringify(ch)} is outside the allowed set `
         + "(lowercase US-ASCII, digits, '-', '.', '/')");
@@ -109,10 +109,10 @@ export function parse(uri) {
     action = rest.slice(slash + 1);
     if (action === '') {
       throw fail(uri, "trailing '/' with empty action - action is a closed-set "
-        + 'verb, not omissible by empty string (§10.2)');
+        + 'verb, not omissible by empty string (sec. 10.2)');
     }
     if (action.includes('/')) {
-      throw fail(uri, "second path segment - path is a single '/<action>' (§10.2)");
+      throw fail(uri, "second path segment - path is a single '/<action>' (sec. 10.2)");
     }
   }
 
@@ -120,11 +120,11 @@ export function parse(uri) {
   const segments = authority.split('.');
   if (segments.length !== 3) {
     throw fail(uri, `authority has ${segments.length} segment(s), must be `
-      + '<subject>.<organ>.<root> (RFC-009 §10.2)');
+      + '<subject>.<organ>.<root> (RFC-009 sec. 10.2)');
   }
   const [subject, organ, root] = segments;
   if (subject === '' || root === '') {
-    throw fail(uri, 'authority segments must be non-empty (RFC-009 §10.2)');
+    throw fail(uri, 'authority segments must be non-empty (RFC-009 sec. 10.2)');
   }
 
   // Subject: hash form (8/32/64 lowercase hex) or name form. Ordered choice
@@ -138,16 +138,16 @@ export function parse(uri) {
     subjectHex = subject;
   }
 
-  // Organ — CLOSED set, case-sensitive (§10.1). 'Forge', 'forgery', '' all fail.
+  // Organ -- CLOSED set, case-sensitive (sec. 10.1). 'Forge', 'forgery', '' all fail.
   if (!ORGANS.includes(organ)) {
     throw fail(uri, `organ ${JSON.stringify(organ)} is outside the closed set `
-      + `[${ORGANS.join(', ')}] (RFC-009 §10.1/§10.3)`);
+      + `[${ORGANS.join(', ')}] (RFC-009 sec. 10.1/sec. 10.3)`);
   }
 
-  // Action — CLOSED set (§10.1). The deliberate difference from rttp.
+  // Action -- CLOSED set (sec. 10.1). The deliberate difference from rttp.
   if (action !== null && !ACTIONS.includes(action)) {
     throw fail(uri, `action ${JSON.stringify(action)} is outside the closed set `
-      + `[${ACTIONS.join(', ')}] (RFC-009 §10.1)`);
+      + `[${ACTIONS.join(', ')}] (RFC-009 sec. 10.1)`);
   }
 
   const canonicalUri = SCHEME + '://' + authority + (action ? '/' + action : '');
@@ -162,8 +162,8 @@ export function parse(uri) {
     authority,
     action,
     action_omitted: action === null,
-    action_safe: SAFE.has(action),           // §11.3
+    action_safe: SAFE.has(action),           // sec. 11.3
     canonical_uri: canonicalUri,
-    route_hex: deriveRouteHex(authority),    // SPEC §3
+    route_hex: deriveRouteHex(authority),    // SPEC sec. 3
   };
 }

package/src/vectors.json

@@ -1,8 +1,8 @@
 {
   "spec": "IQA-URI-ATTEST-v1.2.6",
   "applies_to": [
-    "RFC-009 §10",
-    "RFC-009 §11"
+    "RFC-009 sec. 10",
+    "RFC-009 sec. 11"
   ],
   "generated_by": "SPEC/tools/iqa_conformance.py",
   "note": "Generated file - do not edit by hand. Change the cases in iqa_conformance.py instead.",
@@ -135,77 +135,77 @@
       "action_omitted": false,
       "action_safe": true,
       "route_hex": "acee0323",
-      "note": "note - 9 hex digits is not a hash length (8/32/64), so the subject parses as a name-subject per the ABNF ordered choice (RFC-009 §10.2)"
+      "note": "note - 9 hex digits is not a hash length (8/32/64), so the subject parses as a name-subject per the ABNF ordered choice (RFC-009 sec. 10.2)"
     }
   ],
   "negative_uris": [
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/AUDIT",
-      "reason": "uppercase action - lowercase only (RFC-009 §10.3)"
+      "reason": "uppercase action - lowercase only (RFC-009 sec. 10.3)"
     },
     {
       "uri": "iqa://3F9A1B2C.gateway.iqa/audit",
-      "reason": "uppercase hex subject - lowercase only (RFC-009 §10.3)"
+      "reason": "uppercase hex subject - lowercase only (RFC-009 sec. 10.3)"
     },
     {
       "uri": "IQA://3f9a1b2c.gateway.iqa/audit",
-      "reason": "uppercase scheme prefix - canonical form is lowercase (RFC-009 §10.3)"
+      "reason": "uppercase scheme prefix - canonical form is lowercase (RFC-009 sec. 10.3)"
     },
     {
       "uri": "iqas://3f9a1b2c.gateway.iqa/audit",
-      "reason": "no iqas variant exists and no fallback is defined - fail closed (RFC-009 §12 #8)"
+      "reason": "no iqas variant exists and no fallback is defined - fail closed (RFC-009 sec. 12 #8)"
     },
     {
       "uri": "iqa://subject@iqa.org",
-      "reason": "userinfo is not defined (RFC-009 §10.3)"
+      "reason": "userinfo is not defined (RFC-009 sec. 10.3)"
     },
     {
       "uri": "iqa://iqa.org/RFC-009/",
-      "reason": "no organ, second path segment - this is an https matter (RFC-009 §10.3)"
+      "reason": "no organ, second path segment - this is an https matter (RFC-009 sec. 10.3)"
     },
     {
       "uri": "iqa://3f9a1b2c.forgery.iqa",
-      "reason": "organ is a closed set (RFC-009 §10.1/§10.3)"
+      "reason": "organ is a closed set (RFC-009 sec. 10.1/sec. 10.3)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/pulse",
-      "reason": "action is a closed set - 'pulse' is not one of the four verbs (RFC-009 §10.1)"
+      "reason": "action is a closed set - 'pulse' is not one of the four verbs (RFC-009 sec. 10.1)"
     },
     {
       "uri": "iqa://3f9a1b2c.Gateway.iqa/verify",
-      "reason": "organ is case-sensitive within the closed set (RFC-009 §10.3)"
+      "reason": "organ is case-sensitive within the closed set (RFC-009 sec. 10.3)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/audit?x=1",
-      "reason": "query is not defined (RFC-009 §10.3)"
+      "reason": "query is not defined (RFC-009 sec. 10.3)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/audit#f",
-      "reason": "fragment is not defined (RFC-009 §10.3)"
+      "reason": "fragment is not defined (RFC-009 sec. 10.3)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa:443/audit",
-      "reason": "port is not defined (RFC-009 §10.3)"
+      "reason": "port is not defined (RFC-009 sec. 10.3)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/a/b",
-      "reason": "second path segment - path is a single '/<action>' (RFC-009 §10.2)"
+      "reason": "second path segment - path is a single '/<action>' (RFC-009 sec. 10.2)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/",
-      "reason": "trailing '/' with empty action - the closed set has no empty verb (RFC-009 §10.2)"
+      "reason": "trailing '/' with empty action - the closed set has no empty verb (RFC-009 sec. 10.2)"
     },
     {
       "uri": "iqa://a.b",
-      "reason": "authority has two segments, must be <subject>.<organ>.<root> (RFC-009 §10.2)"
+      "reason": "authority has two segments, must be <subject>.<organ>.<root> (RFC-009 sec. 10.2)"
     },
     {
       "uri": "iqa://a.b.c.d/audit",
-      "reason": "authority has four segments, must be <subject>.<organ>.<root> (RFC-009 §10.2)"
+      "reason": "authority has four segments, must be <subject>.<organ>.<root> (RFC-009 sec. 10.2)"
     },
     {
       "uri": "https://3f9a1b2c.gateway.iqa/audit",
-      "reason": "not an iqa scheme - there is no fallback (RFC-009 §10.3, §12 #8)"
+      "reason": "not an iqa scheme - there is no fallback (RFC-009 sec. 10.3, sec. 12 #8)"
     },
     {
       "uri": "iqa://3f9a1b2c.gateway.iqa/audit ",
@@ -216,27 +216,27 @@
     {
       "action": null,
       "safe": true,
-      "why": "omitted - standing read (RFC-009 §11.1/§11.3)"
+      "why": "omitted - standing read (RFC-009 sec. 11.1/sec. 11.3)"
     },
     {
       "action": "verify",
       "safe": true,
-      "why": "read-only comparison, no state written (RFC-009 §11.3)"
+      "why": "read-only comparison, no state written (RFC-009 sec. 11.3)"
     },
     {
       "action": "audit",
       "safe": false,
-      "why": "a failing measurement triggers Authority Ischemia (RFC-009 §11.3/§11.4)"
+      "why": "a failing measurement triggers Authority Ischemia (RFC-009 sec. 11.3/sec. 11.4)"
     },
     {
       "action": "attest",
       "safe": false,
-      "why": "state transition - Seal issuance (RFC-009 §11.3)"
+      "why": "state transition - Seal issuance (RFC-009 sec. 11.3)"
     },
     {
       "action": "revoke",
       "safe": false,
-      "why": "state transition - standing withdrawal (RFC-009 §11.3)"
+      "why": "state transition - standing withdrawal (RFC-009 sec. 11.3)"
     }
   ],
   "attest_envelope_vector": {