champollion 0.3.3

package/lib/seal.mjs

@@ -0,0 +1,464 @@
+/**
+ * seal.mjs — CLIENT-SIDE encryption for the SEALED exposure tier.
+ *
+ * This is the cryptographic front door for the zero-knowledge sovereign-eval
+ * PoC (docs/governance/OCAP_MULTISIG_PLAN.md, mechanism M1). A community that
+ * chooses to make a held-out set centrally evaluable-on-demand encrypts it
+ * **on their own machine, before a single byte leaves**, under a *threshold
+ * public key* the platform cannot decrypt alone. Champollion ever only receives
+ *
+ *   • ciphertext (an off-git, off-allowlist artifact), and
+ *   • a CONTENT-FREE metadata card (cipher id + custodian group + digest + AAD).
+ *
+ * The plaintext sentences are never read, uploaded, or hosted — exactly the L1
+ * never-host-content doctrine (the data-boundaries doctrine), strengthened: not just
+ * "no plaintext in the repo" but "no plaintext anywhere we hold, ever."
+ *
+ * ── SCHEME ────────────────────────────────────────────────────────────────
+ * A standard hybrid "sealed box" (libsodium crypto_box_seal shape), built only
+ * on Node's `node:crypto` (no third-party dep):
+ *
+ *   1. The recipient is the custodian group's THRESHOLD public key (X25519).
+ *   2. The sender (this CLI, on the author's device) generates an EPHEMERAL
+ *      X25519 keypair, does ECDH against the threshold public key, and derives
+ *      a one-time AES-256 key with HKDF-SHA256 (salt + an info string that
+ *      binds the ephemeral key, the threshold key, and the card AAD).
+ *   3. The corpus bytes are encrypted with AES-256-GCM (the AAD authenticates
+ *      the card binding). The ephemeral private key is discarded.
+ *
+ * Decryption requires the threshold PRIVATE key — which only exists as 3-of-5
+ * custodian shares. Champollion holds zero shares (M4), so it can never
+ * assemble the key and never decrypt. See the WAVE-2 SEAM notes below.
+ *
+ * ── WAVE-1 vs the shipped threshold layer (the integration seam) ──────────
+ * WAVE 1 (this module): accept/derive a PROVIDED threshold public key (a raw
+ * X25519 recipient) and encrypt to it. The matching private key is a single
+ * X25519 scalar (used by tests and the controlled-eval context to PROVE the
+ * ciphertext is real).
+ *
+ * SHIPPED (Python, arena/mt_eval_harness/sovereign/): the "threshold" is
+ * SHAMIR M-of-N secret sharing of that same X25519 scalar (shamir_gf256.py),
+ * reconstructed in the offline node's executor memory during a quorum-
+ * authorized run — NOT an aggregated FROST group key and NOT MPC/TSS (see
+ * sovereign/__init__.py HONESTY CONTRACT). This module is unchanged by that:
+ * every `WAVE-2 SEAM` marker below is a point that WOULD change only if we
+ * moved to real threshold *decryption* (partial ECDH per custodian, key never
+ * assembled) — a networked-platform upgrade that is not built. The ciphertext
+ * format and the card block do NOT change under either model; that is the
+ * whole point of the seam. Historical note: earlier docs named FROST here —
+ * FROST is threshold *signing*, the wrong primitive for this decryption path;
+ * see docs/governance/OCAP_MULTISIG_PLAN.md for the corrected framing.
+ *
+ * @module seal
+ */
+
+import crypto from 'node:crypto';
+
+/** Cipher suite id stamped into every artifact + card. */
+export const SEAL_CIPHER = 'x25519-hkdf-sha256+aes-256-gcm';
+
+/** Sealed-artifact format version (bumped only on a breaking envelope change). */
+export const SEAL_VERSION = '1';
+
+/** HKDF info-string prefix — domain-separates this use of the shared secret. */
+const HKDF_INFO_PREFIX = 'champollion-sealed-corpus';
+
+/** AES-256-GCM parameters. */
+const AES_KEY_BYTES = 32;
+const GCM_IV_BYTES = 12;
+const HKDF_SALT_BYTES = 16;
+
+// ---------------------------------------------------------------------------
+// AAD — the card binding. Additional Authenticated Data is NOT encrypted, but
+// it IS authenticated: a ciphertext sealed for card A / group A cannot be
+// silently re-presented as card B / group B without breaking the GCM tag. It
+// is metadata only (ids), never corpus content — safe to store on the card.
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic AAD string binding a ciphertext to its card + custodian group.
+ * @param {{cardId:string, custodianGroupId:string}} o
+ * @returns {string}
+ */
+export function buildAad({ cardId, custodianGroupId }) {
+  const id = String(cardId || '').trim();
+  const group = String(custodianGroupId || '').trim();
+  return `champollion-sealed:v${SEAL_VERSION}|card=${id}|group=${group}`;
+}
+
+// ---------------------------------------------------------------------------
+// Threshold key handling. WAVE-2 SEAM: in production the public key is the
+// aggregated FROST group key; here we accept a provided X25519 public key in
+// the common encodings, or generate a stand-in keypair for tests/demo.
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a stand-in threshold keypair (X25519).
+ *
+ * WAVE-2 SEAM: replaced by the custodian key ceremony, which produces the
+ * aggregated group PUBLIC key (the only part the author needs) while the
+ * matching secret exists solely as 3-of-5 shares. This helper exposes the full
+ * private key ONLY so tests and a future controlled-eval context can prove the
+ * ciphertext decrypts to the original — it must never run on Champollion infra
+ * in production.
+ *
+ * @returns {{publicKey:crypto.KeyObject, privateKey:crypto.KeyObject,
+ *            publicKeyDerB64:string, privateKeyDerB64:string, keyId:string}}
+ */
+export function generateThresholdKeypair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
+  return {
+    publicKey,
+    privateKey,
+    publicKeyDerB64: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+    privateKeyDerB64: privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64'),
+    keyId: thresholdKeyId(publicKey),
+  };
+}
+
+/**
+ * Resolve a provided threshold public key into a node KeyObject.
+ *
+ * Accepts: a KeyObject; an object with `{publicKeyDerB64}`; a PEM string
+ * (-----BEGIN PUBLIC KEY-----); or a base64-encoded DER SPKI string. Throws a
+ * plain-language error on anything that is not a usable X25519 public key.
+ *
+ * The command wrapper (lib/commands/seal-corpus.js readKeyMaterial) also
+ * accepts keygen JSON FILES directly — both the .pub.json and the .key.json
+ * (which embeds publicKeyDerB64 alongside the private half) work as a
+ * --threshold-pubkey source; the wrapper extracts the right field and hands
+ * the base64 DER string down to this function.
+ *
+ * @param {crypto.KeyObject|string|{publicKeyDerB64:string}} input
+ * @returns {crypto.KeyObject}
+ */
+export function resolveThresholdPublicKey(input) {
+  if (!input) throw new Error('A threshold public key is required to seal a corpus.');
+  if (typeof input === 'object' && input.asymmetricKeyType) return assertX25519Public(input);
+  if (typeof input === 'object' && typeof input.publicKeyDerB64 === 'string') {
+    return assertX25519Public(crypto.createPublicKey({
+      key: Buffer.from(input.publicKeyDerB64, 'base64'), format: 'der', type: 'spki',
+    }));
+  }
+  const raw = String(input).trim();
+  if (!raw) throw new Error('A threshold public key is required to seal a corpus.');
+
+  // PEM (most explicit) first.
+  if (raw.includes('-----BEGIN')) {
+    try { return assertX25519Public(crypto.createPublicKey(raw)); }
+    catch (e) { throw new Error(`Threshold public key is not a valid PEM key: ${e.message}`); }
+  }
+  // Otherwise treat as base64-encoded DER SPKI.
+  let der;
+  try { der = Buffer.from(raw, 'base64'); }
+  catch { throw new Error('Threshold public key must be a PEM string or base64 DER (SPKI).'); }
+  if (!der.length) throw new Error('Threshold public key must be a PEM string or base64 DER (SPKI).');
+  try {
+    return assertX25519Public(crypto.createPublicKey({ key: der, format: 'der', type: 'spki' }));
+  } catch (e) {
+    throw new Error(`Threshold public key could not be parsed as DER SPKI: ${e.message}`);
+  }
+}
+
+/** Guard: only X25519 public keys may receive a sealed corpus. */
+function assertX25519Public(keyObject) {
+  if (keyObject.type !== 'public') throw new Error('Expected a PUBLIC threshold key, got a private/secret key.');
+  if (keyObject.asymmetricKeyType !== 'x25519') {
+    throw new Error(`Threshold public key must be X25519 (got ${keyObject.asymmetricKeyType || 'unknown'}).`);
+  }
+  return keyObject;
+}
+
+/**
+ * Stable short id for a threshold public key — sha256 of its DER SPKI bytes,
+ * first 16 hex chars. Lets the card/artifact name *which* group key was used
+ * without embedding the key itself.
+ * @param {crypto.KeyObject} publicKeyObject
+ * @returns {string}
+ */
+export function thresholdKeyId(publicKeyObject) {
+  const der = publicKeyObject.export({ type: 'spki', format: 'der' });
+  return crypto.createHash('sha256').update(der).digest('hex').slice(0, 16);
+}
+
+// ---------------------------------------------------------------------------
+// The encrypt path — runs on the AUTHOR'S device.
+// ---------------------------------------------------------------------------
+
+/**
+ * Encrypt plaintext corpus bytes to a threshold public key (client-side).
+ *
+ * Returns a content-FREE envelope: ciphertext + the public crypto parameters
+ * needed to decrypt later (ephemeral public key, salt, IV, GCM tag) + a digest.
+ * NONE of the return value contains plaintext.
+ *
+ * @param {object} o
+ * @param {string|Buffer} o.plaintext        corpus content to seal
+ * @param {crypto.KeyObject|string|object} o.thresholdPublicKey  recipient key
+ * @param {string} o.aad                      card-binding AAD (see buildAad)
+ * @returns {{cipher:string, version:string, aad:string, thresholdKeyId:string,
+ *            envelope:{ephemeralPublicKey:string, salt:string, iv:string, authTag:string},
+ *            ciphertext:string, ciphertextDigest:string}}
+ */
+export function sealPlaintext({ plaintext, thresholdPublicKey, aad }) {
+  if (plaintext === undefined || plaintext === null) throw new Error('Nothing to seal — plaintext is empty.');
+  const pt = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(String(plaintext), 'utf-8');
+  if (!pt.length) throw new Error('Nothing to seal — plaintext is empty.');
+  if (typeof aad !== 'string' || !aad) throw new Error('A binding AAD string is required (see buildAad).');
+
+  const recipient = resolveThresholdPublicKey(thresholdPublicKey);
+
+  // Ephemeral keypair → ECDH against the threshold key → one-time AES key.
+  const ephemeral = crypto.generateKeyPairSync('x25519');
+  const sharedSecret = crypto.diffieHellman({ privateKey: ephemeral.privateKey, publicKey: recipient });
+  const ephemeralPubDer = ephemeral.publicKey.export({ type: 'spki', format: 'der' });
+  const recipientDer = recipient.export({ type: 'spki', format: 'der' });
+  const salt = crypto.randomBytes(HKDF_SALT_BYTES);
+
+  // Bind the derived key to both public keys + the card AAD so the key cannot
+  // be reused across recipients or transplanted to another card.
+  const info = Buffer.concat([
+    Buffer.from(HKDF_INFO_PREFIX, 'utf-8'),
+    ephemeralPubDer,
+    recipientDer,
+    Buffer.from(aad, 'utf-8'),
+  ]);
+  const aesKey = Buffer.from(crypto.hkdfSync('sha256', sharedSecret, salt, info, AES_KEY_BYTES));
+
+  const iv = crypto.randomBytes(GCM_IV_BYTES);
+  const cipher = crypto.createCipheriv('aes-256-gcm', aesKey, iv);
+  cipher.setAAD(Buffer.from(aad, 'utf-8'));
+  const ciphertext = Buffer.concat([cipher.update(pt), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  // Scrub the derived key from memory as soon as we're done with it.
+  aesKey.fill(0);
+
+  return {
+    cipher: SEAL_CIPHER,
+    version: SEAL_VERSION,
+    aad,
+    thresholdKeyId: thresholdKeyId(recipient),
+    envelope: {
+      ephemeralPublicKey: ephemeralPubDer.toString('base64'),
+      salt: salt.toString('base64'),
+      iv: iv.toString('base64'),
+      authTag: authTag.toString('base64'),
+    },
+    ciphertext: ciphertext.toString('base64'),
+    ciphertextDigest: crypto.createHash('sha256').update(ciphertext).digest('hex'),
+  };
+}
+
+/**
+ * Assemble the full sealed ARTIFACT — the ciphertext-only blob that would be
+ * stored in the off-git, off-allowlist object store (never the repo). It is
+ * exactly the `sealPlaintext` envelope plus the ids that route it. It contains
+ * NO plaintext.
+ *
+ * @param {object} o
+ * @param {object} o.sealed        a sealPlaintext() result
+ * @param {string} o.cardId
+ * @param {string} o.custodianGroupId
+ * @param {string} o.createdAt     ISO timestamp (injected for determinism)
+ * @returns {object} ciphertext-only artifact
+ */
+export function buildSealedArtifact({ sealed, cardId, custodianGroupId, createdAt }) {
+  return {
+    champollionSealed: SEAL_VERSION,
+    cardId,
+    custodianGroupId,
+    cipher: sealed.cipher,
+    aad: sealed.aad,
+    thresholdKeyId: sealed.thresholdKeyId,
+    envelope: sealed.envelope,
+    ciphertext: sealed.ciphertext,
+    ciphertextDigest: sealed.ciphertextDigest,
+    createdAt: createdAt || null,
+    _note:
+      'Ciphertext-only sealed corpus. Decryptable ONLY by the custodian group\'s ' +
+      'threshold key (3-of-5 in Wave 2). Champollion holds zero shares and cannot ' +
+      'decrypt this. Never tracked in git or hosted in plaintext.',
+  };
+}
+
+/**
+ * The content-free `sealed` block written onto the corpus card. This is the
+ * shape the card builder records — cipher id, custodian group, digest, AAD.
+ * (Plus the key id + qualifier reference, all metadata.)
+ *
+ * @param {object} o
+ * @param {object} o.sealed                a sealPlaintext() result
+ * @param {string} o.custodianGroupId
+ * @param {string} [o.keyScheme]           e.g. 'TSS-3-of-5' (Wave 2)
+ * @param {string|null} [o.qualifierId]    paired public qualifier card id
+ * @param {number|null} [o.qualifierThreshold]
+ * @param {string|null} [o.artifactRef]    off-git pointer to the ciphertext store
+ * @returns {{cipher:string, custodianGroupId:string, ciphertextDigest:string, aad:string,
+ *            thresholdKeyId:string, keyScheme:(string|null), qualifierId:(string|null),
+ *            qualifierThreshold:(number|null), artifactRef:(string|null)}}
+ */
+export function buildSealedCardBlock({
+  sealed, custodianGroupId, keyScheme = null,
+  qualifierId = null, qualifierThreshold = null, artifactRef = null,
+}) {
+  return {
+    cipher: sealed.cipher,
+    custodianGroupId,
+    ciphertextDigest: sealed.ciphertextDigest,
+    aad: sealed.aad,
+    thresholdKeyId: sealed.thresholdKeyId,
+    keyScheme,
+    qualifierId,
+    qualifierThreshold,
+    artifactRef,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The decrypt path. WAVE-2 SEAM: in production this runs ONLY inside the
+// controlled eval context (sandbox-evaluation-spec.md §6) after an M-of-N grant,
+// and the single private key below is replaced by a threshold ECDH over the
+// 3-of-5 shares. Here it proves a sealed corpus is genuinely recoverable —
+// i.e. the encryption is real, not a no-op.
+// ---------------------------------------------------------------------------
+
+/**
+ * Decrypt a sealed artifact (or a raw sealPlaintext envelope) with the
+ * threshold private key. Verifies the ciphertext digest and the GCM tag (which
+ * also authenticates the AAD binding).
+ *
+ * @param {object} o
+ * @param {object} o.artifact                 buildSealedArtifact()/sealPlaintext() shape
+ * @param {crypto.KeyObject|string} o.thresholdPrivateKey
+ * @param {string} [o.aad]                     expected AAD (defaults to artifact.aad)
+ * @returns {Buffer} the recovered plaintext
+ */
+export function openSealed({ artifact, thresholdPrivateKey, aad }) {
+  if (!artifact || !artifact.envelope) throw new Error('Not a sealed artifact (missing envelope).');
+  const expectAad = aad !== undefined ? aad : artifact.aad;
+  if (typeof expectAad !== 'string' || !expectAad) throw new Error('A binding AAD is required to open a sealed artifact.');
+
+  const privateKey = typeof thresholdPrivateKey === 'object' && thresholdPrivateKey.asymmetricKeyType
+    ? thresholdPrivateKey
+    : crypto.createPrivateKey(
+        typeof thresholdPrivateKey === 'string' && thresholdPrivateKey.includes('-----BEGIN')
+          ? thresholdPrivateKey
+          : { key: Buffer.from(String(thresholdPrivateKey), 'base64'), format: 'der', type: 'pkcs8' },
+      );
+
+  const ciphertext = Buffer.from(artifact.ciphertext, 'base64');
+  const digest = crypto.createHash('sha256').update(ciphertext).digest('hex');
+  if (artifact.ciphertextDigest && digest !== artifact.ciphertextDigest) {
+    throw new Error('Sealed artifact failed integrity check (ciphertext digest mismatch).');
+  }
+
+  const ephemeralPub = crypto.createPublicKey({
+    key: Buffer.from(artifact.envelope.ephemeralPublicKey, 'base64'), format: 'der', type: 'spki',
+  });
+  const sharedSecret = crypto.diffieHellman({ privateKey, publicKey: ephemeralPub });
+  const recipientDer = crypto.createPublicKey(privateKey).export({ type: 'spki', format: 'der' });
+  const ephemeralPubDer = ephemeralPub.export({ type: 'spki', format: 'der' });
+  const info = Buffer.concat([
+    Buffer.from(HKDF_INFO_PREFIX, 'utf-8'),
+    ephemeralPubDer,
+    recipientDer,
+    Buffer.from(expectAad, 'utf-8'),
+  ]);
+  const aesKey = Buffer.from(crypto.hkdfSync(
+    'sha256', sharedSecret, Buffer.from(artifact.envelope.salt, 'base64'), info, AES_KEY_BYTES,
+  ));
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', aesKey, Buffer.from(artifact.envelope.iv, 'base64'));
+  decipher.setAAD(Buffer.from(expectAad, 'utf-8'));
+  decipher.setAuthTag(Buffer.from(artifact.envelope.authTag, 'base64'));
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  aesKey.fill(0);
+  return plaintext;
+}
+
+// ---------------------------------------------------------------------------
+// Score-bundle signing (Phase B airgap transport) — Ed25519, node:crypto only.
+//
+// The AIRGAPPED scoring node signs each exported score bundle so the
+// connected relay can verify the bytes it publishes are exactly the bytes the
+// sandbox produced (arena/docs/sandbox-evaluation-spec.md §8 step 4 "audit
+// log sealed"/§9). Honesty label: this is a SINGLE node signing key — it
+// authenticates the machine's output, it is NOT the M-of-N steward custody of
+// §12 (Wave 2). The canonical signed payload is the file's exact bytes; the
+// signature block records the payload sha256 alongside so tampering is
+// doubly evident.
+// ---------------------------------------------------------------------------
+
+/** Signature scheme label stamped into every signature block. */
+export const SIGN_SCHEME = 'ed25519-single-node-wave1';
+
+/**
+ * Generate an Ed25519 signing keypair for a scoring node.
+ * @returns {{publicKeyDerB64:string, privateKeyDerB64:string, keyId:string}}
+ */
+export function generateSigningKeypair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+  return {
+    publicKeyDerB64: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+    privateKeyDerB64: privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64'),
+    keyId: thresholdKeyId(publicKey),   // same stable-id recipe: sha256(SPKI)[:16]
+  };
+}
+
+function resolveSigningKey(input, { wantPublic }) {
+  const label = wantPublic ? 'verify (public)' : 'signing (private)';
+  if (!input) throw new Error(`A ${label} key is required.`);
+  if (typeof input === 'object' && input.asymmetricKeyType) return input;
+  if (typeof input === 'object') {
+    const der = input.publicKeyDerB64 || input.privateKeyDerB64;
+    if (typeof der === 'string') {
+      return wantPublic
+        ? crypto.createPublicKey({ key: Buffer.from(der, 'base64'), format: 'der', type: 'spki' })
+        : crypto.createPrivateKey({ key: Buffer.from(der, 'base64'), format: 'der', type: 'pkcs8' });
+    }
+  }
+  const raw = String(input).trim();
+  if (raw.includes('-----BEGIN')) {
+    return wantPublic ? crypto.createPublicKey(raw) : crypto.createPrivateKey(raw);
+  }
+  const der = Buffer.from(raw, 'base64');
+  return wantPublic
+    ? crypto.createPublicKey({ key: der, format: 'der', type: 'spki' })
+    : crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+}
+
+/**
+ * Sign a payload (Buffer) with an Ed25519 private key.
+ * @returns {{scheme:string, keyId:string, payloadSha256:string, signatureB64:string}}
+ */
+export function signPayload({ payload, signingPrivateKey }) {
+  if (!Buffer.isBuffer(payload) || !payload.length) {
+    throw new Error('signPayload needs a non-empty Buffer payload.');
+  }
+  const privateKey = resolveSigningKey(signingPrivateKey, { wantPublic: false });
+  if (privateKey.asymmetricKeyType !== 'ed25519') {
+    throw new Error(`Signing key must be Ed25519 (got ${privateKey.asymmetricKeyType || 'unknown'}).`);
+  }
+  const publicKey = crypto.createPublicKey(privateKey);
+  return {
+    scheme: SIGN_SCHEME,
+    keyId: thresholdKeyId(publicKey),
+    payloadSha256: crypto.createHash('sha256').update(payload).digest('hex'),
+    signatureB64: crypto.sign(null, payload, privateKey).toString('base64'),
+  };
+}
+
+/**
+ * Verify a payload (Buffer) against a signature block and an Ed25519 public
+ * key. Returns true/false — the CALLER decides what a failure means (always
+ * a refusal; never a warning).
+ */
+export function verifyPayload({ payload, signatureB64, verifyPublicKey }) {
+  if (!Buffer.isBuffer(payload)) throw new Error('verifyPayload needs a Buffer payload.');
+  const publicKey = resolveSigningKey(verifyPublicKey, { wantPublic: true });
+  if (publicKey.asymmetricKeyType !== 'ed25519') {
+    throw new Error(`Verify key must be Ed25519 (got ${publicKey.asymmetricKeyType || 'unknown'}).`);
+  }
+  return crypto.verify(null, payload, publicKey, Buffer.from(String(signatureB64), 'base64'));
+}

package/lib/sealed-qualifier.mjs

@@ -0,0 +1,211 @@
+/**
+ * sealed-qualifier.mjs — the PUBLIC QUALIFIER paired to a sealed test set.
+ *
+ * A sealed (community-controlled secret) test set is precious: every evaluation
+ * against it leaks a little signal, and custodian approval is a real,
+ * low-frequency act (M-of-N, docs/governance/OCAP_MULTISIG_PLAN.md M2). So a
+ * method must EARN the right to even *propose* a sealed run by first clearing a
+ * disjoint, fully public twin — the **qualifier**.
+ *
+ * The qualifier is:
+ *   • PUBLIC-tier (CC-BY / CC0 / share-alike) — admitted through the SAME gate
+ *     as any public corpus (gatePublicRegistration, corpus-registration.mjs).
+ *     A non-redistributable or unconfirmed license can never be a qualifier.
+ *   • DISJOINT from the sealed set (no shared entries) — drawn from the same
+ *     distribution so clearing it is meaningful, but sharing no sentences so it
+ *     leaks nothing about the sealed content. Author-attested (we never see
+ *     either side's content to verify), recorded on the card.
+ *   • YEARLY-ROTATED (vYYYY). Each year a fresh qualifier supersedes the last;
+ *     the prior year is FROZEN for history (immutable, kept so old results stay
+ *     interpretable). A qualifier whose vintage is behind the current year is
+ *     STALE — it has been public long enough that contamination/overfitting
+ *     risk rises, so we surface a contamination-risk badge.
+ *
+ * The load-bearing rule is `isEligibleForSealedRun`: below the qualifier
+ * threshold (or no qualifier cleared at all) ⇒ NOT eligible to request a sealed
+ * run. Pure functions, no I/O — dates/years are injected so the logic is
+ * deterministic and testable.
+ *
+ * @module sealed-qualifier
+ */
+
+import { gatePublicRegistration } from './corpus-registration.mjs';
+
+/**
+ * Default qualifier clearance threshold. Expressed on the public leaderboard's
+ * composite 0–100 scale; communities/contests may override per qualifier. This
+ * is a floor placeholder, not a claim about any specific pair's difficulty —
+ * callers should set a calibrated threshold for real qualifiers.
+ */
+export const DEFAULT_QUALIFIER_THRESHOLD = 30;
+
+// ---------------------------------------------------------------------------
+// Versioning — vYYYY yearly rotation.
+// ---------------------------------------------------------------------------
+
+/** `2026` → `'v2026'`. */
+export function qualifierVersionTag(year) {
+  const y = parseInt(year, 10);
+  if (!Number.isInteger(y) || y < 2000 || y > 9999) {
+    throw new Error(`Qualifier year must be a 4-digit year (got ${year}).`);
+  }
+  return `v${y}`;
+}
+
+/** `'v2026'` (or an id ending in `-v2026`) → `2026`, else null. */
+export function parseQualifierYear(input) {
+  const m = String(input || '').match(/v(\d{4})(?:$|[^0-9])/);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+/**
+ * Derive a qualifier card id paired to a sealed set.
+ * Shape: eval-<src>-<tgt>-<slug>-qualifier-vYYYY (public-tier, runnable).
+ *
+ * @param {{source:string, target:string, slug?:string, year:number}} o
+ * @returns {string}
+ */
+export function buildQualifierId({ source, target, slug, year }) {
+  const tag = slug && String(slug).length ? slug : 'sealed';
+  return `eval-${source}-${target}-${tag}-qualifier-${qualifierVersionTag(year)}`;
+}
+
+// ---------------------------------------------------------------------------
+// The license gate — a qualifier MUST be public-eligible (it is itself public).
+// Reuses the one public-registration gate; no parallel rule.
+// ---------------------------------------------------------------------------
+
+/**
+ * May this license back a PUBLIC qualifier? (Same admission as any public
+ * corpus.) NC / ND / unconfirmed licenses are blocked.
+ *
+ * @param {object} licenseOption a resolveLicense() result
+ * @returns {{allowed:boolean, tier:string, reason:string}}
+ */
+export function gateQualifier(licenseOption) {
+  const gate = gatePublicRegistration(licenseOption);
+  if (gate.allowed) return gate;
+  return {
+    allowed: false,
+    tier: gate.tier,
+    reason: `A qualifier is public by definition, so it needs a redistribution-cleared (CC-BY/CC0/share-alike) license. ${gate.reason}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Eligibility — the gate every sealed-run proposal passes BEFORE custodians are
+// ever bothered. Fail-safe: anything unconfirmed ⇒ NOT eligible.
+// ---------------------------------------------------------------------------
+
+/**
+ * Is a method eligible to PROPOSE a run against the sealed set?
+ *
+ * Requires a paired qualifier, a recorded score on it, and that score meeting
+ * the threshold. A stale qualifier still gates (you must clear the *current*
+ * qualifier), so we also report staleness for the caller to surface.
+ *
+ * @param {object} o
+ * @param {string|null} [o.qualifierId]   the paired public qualifier (required)
+ * @param {number|null} [o.score]         the method's score on that qualifier
+ * @param {number} [o.threshold]          clearance threshold (default DEFAULT_QUALIFIER_THRESHOLD)
+ * @param {number|null} [o.qualifierYear] vintage year of the qualifier the score was earned on
+ * @param {number|null} [o.currentYear]   the active qualifier year (for staleness)
+ * @returns {{eligible:boolean, reason:string, threshold:number, score:(number|null),
+ *            stale:boolean, badge:(object|null)}}
+ */
+export function isEligibleForSealedRun({
+  qualifierId = null, score = null, threshold = DEFAULT_QUALIFIER_THRESHOLD,
+  qualifierYear = null, currentYear = null,
+} = {}) {
+  const thr = Number(threshold);
+  const badge = (qualifierYear != null && currentYear != null)
+    ? qualifierContaminationBadge({ qualifierYear, currentYear })
+    : null;
+  const stale = !!(badge && badge.stale);
+
+  if (!qualifierId) {
+    return { eligible: false, reason: 'No public qualifier is paired with this sealed set — a sealed run cannot be proposed without one.', threshold: thr, score: null, stale, badge };
+  }
+  if (score === null || score === undefined || Number.isNaN(Number(score))) {
+    return { eligible: false, reason: `Method has not cleared the public qualifier (${qualifierId}) yet — run it on the qualifier first.`, threshold: thr, score: null, stale, badge };
+  }
+  const s = Number(score);
+  if (s < thr) {
+    return { eligible: false, reason: `Method scored ${s} on the public qualifier (${qualifierId}); the sealed-run threshold is ${thr}. Not eligible to propose a sealed run.`, threshold: thr, score: s, stale, badge };
+  }
+  return { eligible: true, reason: `Method cleared the public qualifier (${qualifierId}) at ${s} ≥ ${thr} — eligible to PROPOSE a sealed run (still requires M-of-N custodian approval).`, threshold: thr, score: s, stale, badge };
+}
+
+// ---------------------------------------------------------------------------
+// Staleness → contamination-risk badge.
+// ---------------------------------------------------------------------------
+
+/**
+ * Contamination-risk badge for a qualifier given its vintage vs the active year.
+ * A current-year qualifier is fresh (no badge). Each year behind raises risk:
+ * 1 year ⇒ MEDIUM, 2+ ⇒ HIGH — it has been public long enough that training-set
+ * contamination and overfitting to the public twin become real.
+ *
+ * @param {{qualifierYear:number, currentYear:number}} o
+ * @returns {{stale:boolean, ageYears:number, risk:('NONE'|'LOW'|'MEDIUM'|'HIGH'),
+ *            badge:(string|null), reason:string}}
+ */
+export function qualifierContaminationBadge({ qualifierYear, currentYear }) {
+  const qy = parseInt(qualifierYear, 10);
+  const cy = parseInt(currentYear, 10);
+  if (!Number.isInteger(qy) || !Number.isInteger(cy)) {
+    throw new Error('qualifierContaminationBadge needs integer years.');
+  }
+  const age = cy - qy;
+  if (age <= 0) {
+    return { stale: false, ageYears: Math.max(0, age), risk: 'NONE', badge: null, reason: `Qualifier v${qy} is current — fresh.` };
+  }
+  const risk = age >= 2 ? 'HIGH' : 'MEDIUM';
+  return {
+    stale: true,
+    ageYears: age,
+    risk,
+    badge: `⚠ STALE QUALIFIER (v${qy}, ${age} yr${age === 1 ? '' : 's'} old)`,
+    reason: `Qualifier v${qy} is ${age} year${age === 1 ? '' : 's'} behind the active v${cy}; public exposure raises contamination/overfitting risk (${risk}). Rotate to v${cy}.`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Rotation — supersede with a fresh year; FREEZE the prior for history.
+// ---------------------------------------------------------------------------
+
+/**
+ * Rotate a qualifier to a new year. The previously-active qualifier is FROZEN
+ * (marked immutable, retained for history) and the new year becomes active.
+ *
+ * @param {object} o
+ * @param {{source:string, target:string, slug?:string}} o.pair
+ * @param {number} o.newYear
+ * @param {object|null} [o.current]   the currently-active qualifier descriptor (or null for first-ever)
+ * @param {object[]} [o.frozen]       already-frozen prior qualifiers
+ * @param {number} [o.threshold]
+ * @returns {{active:object, frozen:object[]}}
+ */
+export function rotateQualifier({ pair, newYear, current = null, frozen = [], threshold = DEFAULT_QUALIFIER_THRESHOLD }) {
+  const ny = parseInt(newYear, 10);
+  if (current) {
+    const currentYear = current.year ?? parseQualifierYear(current.id);
+    if (currentYear != null && ny <= currentYear) {
+      throw new Error(`Cannot rotate to v${ny}: it is not newer than the active qualifier v${currentYear}.`);
+    }
+  }
+  const nextFrozen = [...frozen];
+  if (current) {
+    nextFrozen.push({ ...current, status: 'frozen', frozen: true });
+  }
+  const active = {
+    id: buildQualifierId({ source: pair.source, target: pair.target, slug: pair.slug, year: ny }),
+    year: ny,
+    version: qualifierVersionTag(ny),
+    tier: 'public',
+    status: 'active',
+    frozen: false,
+    threshold: Number(threshold),
+  };
+  return { active, frozen: nextFrozen };
+}