From 844e936b05d405a797994934d8c4b9e63abf295d Mon Sep 17 00:00:00 2001 From: Pranav Bhave <90584946+Cubits11@users.noreply.github.com> Date: Tue, 3 Nov 2026 12:09:04 -0500 Subject: [PATCH] feat(math): add the cc-kernel-v1 TypeScript port and its conformance suite src/math/ccKernel.ts implements the CC composition kernel from the vendored cc-kernel-v1 SPEC.md and case corpus, never from the Python reference. ccKernel.conformance.test.ts runs all 32 corpus cases within the declared 1e-12 tolerance and pins the vendored files' SHA-256 digests (39 tests). The corpus under src/math/conformance/cc-kernel-v1/ is a verbatim copy of cc-framework conformance/cc-kernel-v1 at bf5740c (byte-identical to cc-framework main 835b9ab today); PROVENANCE.md records the pin. Nothing in src/ imports the port yet; it is standalone and test-only. Co-Authored-By: Claude Opus 5.5 --- src/math/ccKernel.conformance.test.ts | 193 +++++++ src/math/ccKernel.ts | 239 ++++++++ .../conformance/cc-kernel-v1/PROVENANCE.md | 61 +++ src/math/conformance/cc-kernel-v1/SPEC.md | 256 +++++++++ .../conformance/cc-kernel-v1/adversarial.json | 107 ++++ .../conformance/cc-kernel-v1/composition.json | 512 ++++++++++++++++++ .../conformance/cc-kernel-v1/manifest.json | 14 + 7 files changed, 1382 insertions(+) create mode 100644 src/math/ccKernel.conformance.test.ts create mode 100644 src/math/ccKernel.ts create mode 100644 src/math/conformance/cc-kernel-v1/PROVENANCE.md create mode 100644 src/math/conformance/cc-kernel-v1/SPEC.md create mode 100644 src/math/conformance/cc-kernel-v1/adversarial.json create mode 100644 src/math/conformance/cc-kernel-v1/composition.json create mode 100644 src/math/conformance/cc-kernel-v1/manifest.json diff --git a/src/math/ccKernel.conformance.test.ts b/src/math/ccKernel.conformance.test.ts new file mode 100644 index 0000000..3f3097d --- /dev/null +++ b/src/math/ccKernel.conformance.test.ts @@ -0,0 +1,193 @@ +import { createHash } from "node:crypto"; +import { readFileSync } from "node:fs"; +import { describe, expect, it } from "vitest"; + +import { + CC_TOLERANCE, + CcRefusal, + composeCC, + type CcRefusalReason, +} from "./ccKernel"; +import { + computeClasswiseOrResult, + computeFrechetHoeffdingOrBounds, +} from "./guardrailComposition"; +import { sharedFailureRows, separatedFailureRows } from "../evidence/sampleEvaluations"; + +/** + * Step 0 — the CC ↔ visualizer conformance membrane. + * + * This runs the vendored `cc-kernel-v1` corpus against the visualizer's own + * TypeScript kernel. Passing means the two compute the same intervals on these + * cases; per the SPEC it means nothing more than that. The point is negative: + * if the visualizer ever drifts from the reference kernel's arithmetic, a case + * here fails instead of a seductive wrong number reaching a viewer. + */ + +const CORPUS_DIR = new URL("./conformance/cc-kernel-v1/", import.meta.url); + +function corpusUrl(name: string): URL { + return new URL(name, CORPUS_DIR); +} + +function rawSha256(name: string): string { + return createHash("sha256").update(readFileSync(corpusUrl(name))).digest("hex"); +} + +function loadJson(name: string): T { + return JSON.parse(readFileSync(corpusUrl(name), "utf8")) as T; +} + +/** + * Raw-byte digests of the exact vendored corpus this suite was written against, + * copied from cc-framework@bf5740c (conformance/cc-kernel-v1, clean tree) on + * 2026-10-28. See PROVENANCE.md in the corpus directory — including the note + * that cc-framework's own manifest.json digests (SHA-256 of canonical-minified + * JSON) match adversarial.json but NOT composition.json upstream. + */ +const PINNED_RAW_SHA256: Record = { + "composition.json": + "469484269d10d9b3dd90254c995bf5be486cd773f1175be74c6b3150ef8bdacf", + "adversarial.json": + "5d9ee31fc9a47e6b93da3fc1ced76c4a84a89e89593417f712ac46771842989a", +}; + +type AcceptCase = { + id: string; + description: string; + input: { marginals: Record; event: string; dependence: string }; + expect: { + binding_event: string | null; + independence_point: number; + lower: number; + understatement_factor: number | null; + upper: number; + width: number; + }; +}; + +type RejectCase = { + id: string; + description: string; + input: { marginals: Record; event: string; dependence: string }; + expect_refusal: CcRefusalReason; +}; + +type AcceptCorpus = { case_count: number; cases: AcceptCase[]; tolerance: number }; +type RejectCorpus = { case_count: number; cases: RejectCase[] }; +type Manifest = { corpus: string; total_cases: number; tolerance: number }; + +const composition = loadJson("composition.json"); +const adversarial = loadJson("adversarial.json"); +const manifest = loadJson("manifest.json"); + +/** SPEC §5: a corpus runner maps the JSON string "NaN" to real NaN before + * calling the kernel. The kernel itself never accepts a string. */ +function materializeMarginals( + marginals: Record, +): Record { + const out: Record = {}; + for (const [name, value] of Object.entries(marginals)) { + out[name] = value === "NaN" ? Number.NaN : (value as number); + } + return out; +} + +function expectClose(actual: number, expected: number): void { + expect(Math.abs(actual - expected)).toBeLessThanOrEqual(CC_TOLERANCE); +} + +describe("cc-kernel-v1 corpus is vendored at its pinned bytes", () => { + it.each(Object.keys(PINNED_RAW_SHA256))("%s is unmodified", (name) => { + expect(rawSha256(name)).toBe(PINNED_RAW_SHA256[name]); + }); + + it("covers the whole census: 24 accept + 8 reject = 32", () => { + expect(composition.cases).toHaveLength(composition.case_count); + expect(adversarial.cases).toHaveLength(adversarial.case_count); + expect(composition.case_count + adversarial.case_count).toBe(manifest.total_cases); + expect(manifest.total_cases).toBe(32); + }); + + it("uses the SPEC-declared 1e-12 tolerance", () => { + expect(composition.tolerance).toBe(CC_TOLERANCE); + expect(manifest.tolerance).toBe(CC_TOLERANCE); + }); +}); + +describe("cc-kernel-v1 accept cases reproduce every expected field", () => { + it.each(composition.cases.map((c) => [c.id, c] as const))("%s", (_id, testCase) => { + const result = composeCC({ + marginals: materializeMarginals(testCase.input.marginals), + event: testCase.input.event, + dependence: testCase.input.dependence, + }); + + expectClose(result.lower, testCase.expect.lower); + expectClose(result.upper, testCase.expect.upper); + expectClose(result.width, testCase.expect.width); + expectClose(result.independence_point, testCase.expect.independence_point); + + if (testCase.expect.understatement_factor === null) { + expect(result.understatement_factor).toBeNull(); + } else { + expect(result.understatement_factor).not.toBeNull(); + expectClose(result.understatement_factor as number, testCase.expect.understatement_factor); + } + + // binding_event is compared exactly (SPEC §8). + expect(result.binding_event).toBe(testCase.expect.binding_event); + }); +}); + +describe("cc-kernel-v1 reject cases refuse with the named reason", () => { + it.each(adversarial.cases.map((c) => [c.id, c] as const))("%s", (_id, testCase) => { + let thrown: unknown; + try { + composeCC({ + marginals: materializeMarginals(testCase.input.marginals), + event: testCase.input.event, + dependence: testCase.input.dependence, + }); + } catch (error) { + thrown = error; + } + + expect(thrown).toBeInstanceOf(CcRefusal); + expect((thrown as CcRefusal).reason).toBe(testCase.expect_refusal); + }); +}); + +describe("membrane: the visualizer OR pipeline agrees with the kernel", () => { + // The essay's two-guardrail OR pipeline (1 = block) and the CC kernel + // (1 = failure) frame the indicator differently, but the composed-event + // interval is the same union bound. These assertions are the contract: the + // visualizer presents kernel arithmetic, it does not re-derive it. + it.each([ + ["shared-failure 90/90 rows", sharedFailureRows], + ["separated-failure 90/90 rows", separatedFailureRows], + ] as const)("%s: Fréchet OR bounds match composeCC union", (_label, rows) => { + const pipeline = computeClasswiseOrResult(rows, "harmful"); + const kernel = composeCC({ + marginals: { A: pipeline.marginalA, B: pipeline.marginalB }, + event: "any", + dependence: "unconstrained", + }); + + expectClose(pipeline.fhLowerOr, kernel.lower); + expectClose(pipeline.fhUpperOr, kernel.upper); + expectClose(pipeline.fhWidthOr, kernel.width); + }); + + it("the standalone OR-bounds helper matches the kernel across a grid", () => { + const grid = [0, 0.1, 0.25, 0.5, 0.7, 0.9, 1]; + for (const a of grid) { + for (const b of grid) { + const helper = computeFrechetHoeffdingOrBounds(a, b); + const kernel = composeCC({ marginals: { A: a, B: b }, event: "any" }); + expectClose(helper.lower, kernel.lower); + expectClose(helper.upper, kernel.upper); + } + } + }); +}); diff --git a/src/math/ccKernel.ts b/src/math/ccKernel.ts new file mode 100644 index 0000000..e28311d --- /dev/null +++ b/src/math/ccKernel.ts @@ -0,0 +1,239 @@ +/** + * cc-kernel-v1 — a spec-faithful TypeScript implementation of the CC composition + * kernel: bound the probability of a composed binary event from the marginal + * probabilities of its parts, under unknown dependence. + * + * This file is deliberately NOT a second mathematical authority. The reference + * authority is the `cc-framework` Python kernel; this port exists only so the + * visualizer can render kernel-consistent numbers and *fail loudly* if it ever + * drifts from them. It was written from the normative specification vendored at + * `./conformance/cc-kernel-v1/SPEC.md`, and from the case corpus beside it — + * never from the reference Python source, exactly as the SPEC requires: + * + * "An implementer works from this document and `cases/`, never from the Python + * source. [...] agreement between it and the reference would establish nothing." + * + * It is held to the spec by `ccKernel.conformance.test.ts`, which runs the full + * vendored corpus (24 accept + 8 reject = 32 cases) within the declared 1e-12 + * tolerance. If this implementation and the corpus ever disagree, that test is + * the alarm — not something to silence by weakening a case. + * + * CC convention: a marginal is the probability that an event *occurs*, and for a + * guardrail an occurrence is a FAILURE / unsafe pass, not a success. + */ + +export const CC_KERNEL_CORPUS = "cc-kernel-v1" as const; + +/** Numeric tolerance, declared by the corpus manifest (SPEC §7). */ +export const CC_TOLERANCE = 1e-12; + +export type CcEventKind = "all" | "any"; + +export type CcDependence = + | "unconstrained" + | "independent" + | "comonotone" + | "countermonotone"; + +export type CcInput = { + /** Event name -> marginal probability of occurrence. */ + marginals: Record; + /** "all"/"any" or a documented alias (SPEC §1.3). */ + event: string; + /** SPEC §1.4. Absent is treated as the honest default "unconstrained"; an + * unrecognized *value* is refused rather than defaulted. */ + dependence?: string; +}; + +export type CcResult = { + corpus: typeof CC_KERNEL_CORPUS; + event: CcEventKind; + dependence: CcDependence; + n: number; + /** Sharp (or stipulated) interval for the composed event probability. */ + lower: number; + upper: number; + width: number; + /** Comparison baseline only — never an answer (SPEC §3). */ + independence_point: number; + independence_regret: number; + /** upper / independence_point, or null when the baseline is 0 (SPEC §3). */ + understatement_factor: number | null; + /** The event the upper bound turns on, or null (SPEC §4). */ + binding_event: string | null; +}; + +export type CcRefusalReason = + | "marginal_out_of_range" + | "marginal_not_finite" + | "no_events" + | "unknown_event_kind" + | "unknown_dependence" + | "countermonotone_undefined"; + +/** A fail-closed refusal (SPEC §5). The kernel refuses; it never defaults. */ +export class CcRefusal extends Error { + readonly reason: CcRefusalReason; + + constructor(reason: CcRefusalReason, message?: string) { + super(message ?? reason); + this.name = "CcRefusal"; + this.reason = reason; + // Keep instanceof working when compiled down to ES5-era targets. + Object.setPrototypeOf(this, CcRefusal.prototype); + } +} + +const EVENT_ALIASES: Record = { + all: "all", + and: "all", + AND: "all", + intersection: "all", + any: "any", + or: "any", + OR: "any", + union: "any", +}; + +const DEPENDENCE_VALUES: ReadonlySet = new Set([ + "unconstrained", + "independent", + "comonotone", + "countermonotone", +]); + +function clip01(value: number): number { + return Math.min(1, Math.max(0, value)); +} + +/** Product over an array with an explicit left fold, so floating-point + * association matches a plain `reduce` — the baseline is a comparison, and we + * keep it bit-stable rather than clever. */ +function product(values: number[]): number { + return values.reduce((acc, x) => acc * x, 1); +} + +/** + * Compose marginals into a bound (or a stipulated point) for the named event. + * Throws {@link CcRefusal} for any input the SPEC says must be refused. + */ +export function composeCC(input: CcInput): CcResult { + // §1.3 — event kind (checked first: it is the shape of the question). + const event = EVENT_ALIASES[input.event]; + if (!event) { + throw new CcRefusal("unknown_event_kind", `unknown event kind: ${String(input.event)}`); + } + + // §1.4 — dependence. Missing -> honest default; present-but-unknown -> refuse. + const dependenceRaw = input.dependence ?? "unconstrained"; + if (!DEPENDENCE_VALUES.has(dependenceRaw as CcDependence)) { + throw new CcRefusal("unknown_dependence", `unknown dependence: ${String(dependenceRaw)}`); + } + const dependence = dependenceRaw as CcDependence; + + // §1.2 — at least one event. + const names = Object.keys(input.marginals); + if (names.length === 0) { + throw new CcRefusal("no_events", "marginals mapping is empty"); + } + + // §1.2 / §5 — every marginal finite and in range. A non-number (e.g. the + // JSON string "NaN" that a corpus runner has not mapped) is treated as not + // finite: the kernel never accepts a string as a probability. + const p: number[] = []; + for (const name of names) { + const value = input.marginals[name]; + if (typeof value !== "number" || !Number.isFinite(value)) { + throw new CcRefusal("marginal_not_finite", `marginal "${name}" is not a finite number`); + } + if (value < 0 || value > 1) { + throw new CcRefusal("marginal_out_of_range", `marginal "${name}"=${value} outside [0, 1]`); + } + p.push(value); + } + + const n = p.length; + + // §6 — countermonotonicity is strictly bivariate. + if (dependence === "countermonotone" && n !== 2) { + throw new CcRefusal( + "countermonotone_undefined", + "countermonotone is defined only for exactly two events", + ); + } + + const sum = p.reduce((a, b) => a + b, 0); + const minP = Math.min(...p); + const maxP = Math.max(...p); + + // §3 — independence baseline, reported on every result whatever the regime. + const independence_point = + event === "all" ? product(p) : 1 - product(p.map((x) => 1 - x)); + + // The interval, by dependence regime. + let lower: number; + let upper: number; + switch (dependence) { + case "unconstrained": + // §2 — sharp Fréchet–Hoeffding bounds. + if (event === "all") { + lower = Math.max(0, sum - (n - 1)); + upper = minP; + } else { + lower = maxP; + upper = Math.min(1, sum); + } + break; + case "independent": + // §1.4 / §3 — a degenerate interval at the product baseline. + lower = independence_point; + upper = independence_point; + break; + case "comonotone": + // §1.4 / §6 — the upper Fréchet corner, as a degenerate interval. + lower = event === "all" ? minP : maxP; + upper = lower; + break; + case "countermonotone": + // §6 — bivariate only (n === 2 guaranteed above). + lower = event === "all" ? Math.max(0, sum - 1) : Math.min(1, sum); + upper = lower; + break; + } + + // §2 — clip to absorb floating-point excursions at the boundary. + lower = clip01(lower); + upper = clip01(upper); + + const width = Math.max(0, upper - lower); + const independence_regret = upper - independence_point; + const understatement_factor = + independence_point === 0 ? null : upper / independence_point; + + // §4 — binding_event: only under an unconstrained bound. + let binding_event: string | null = null; + if (dependence === "unconstrained") { + if (event === "all") { + // §4.1 / §4.3 — the argmin binds, unless two or more tie at the minimum. + const atMin = names.filter((_, i) => Math.abs(p[i] - minP) <= CC_TOLERANCE); + binding_event = atMin.length === 1 ? atMin[0] : null; + } else { + // §4.2 — a union's upper bound is a sum; only a lone event binds. + binding_event = n === 1 ? names[0] : null; + } + } + + return { + corpus: CC_KERNEL_CORPUS, + event, + dependence, + n, + lower, + upper, + width, + independence_point, + independence_regret, + understatement_factor, + binding_event, + }; +} diff --git a/src/math/conformance/cc-kernel-v1/PROVENANCE.md b/src/math/conformance/cc-kernel-v1/PROVENANCE.md new file mode 100644 index 0000000..aa17b8b --- /dev/null +++ b/src/math/conformance/cc-kernel-v1/PROVENANCE.md @@ -0,0 +1,61 @@ +# Vendored corpus: `cc-kernel-v1` + +These files are a **pinned, verbatim copy** of the CC composition kernel's +conformance corpus. The authority is `cc-framework`; this copy exists so Ghost +Visualizer is self-contained (no sibling-repo path at test time) while staying +provably faithful to a specific upstream revision. + +## Source + +| | | +|---|---| +| Repository | `cc-framework` (Cubits11) | +| Path | `conformance/cc-kernel-v1/` | +| Commit | `bf5740c266ff495319442402e0fa7d6aa23ccafa` (2026-09-07), tree clean | +| Vendored on | 2026-10-28 | +| Vendored by | Ghost Visualizer Step 0 (CC ↔ visualizer conformance membrane) | + +`SPEC.md` is the normative specification. The TypeScript kernel in +`../../ccKernel.ts` was written from `SPEC.md` and the cases below — **never from +the reference Python source** — exactly as §SPEC requires. `ccKernel.conformance.test.ts` +runs the corpus against that kernel. + +## Pinned digests (raw file bytes, SHA-256) + +The conformance test asserts these on every run; editing a vendored file breaks +the suite on purpose. + +``` +composition.json 469484269d10d9b3dd90254c995bf5be486cd773f1175be74c6b3150ef8bdacf +adversarial.json 5d9ee31fc9a47e6b93da3fc1ced76c4a84a89e89593417f712ac46771842989a +``` + +## Finding: upstream manifest digest drift (not fixed here) + +`cc-framework`'s own `manifest.json` records a digest per case file. That digest +is **SHA-256 of canonical-minified JSON** — `json.dumps(obj, sort_keys=True, +separators=(",", ":"))` — not of the raw bytes. Recomputed at the source commit: + +| File | manifest digest | recomputed canonical-minified digest | match? | +|---|---|---|---| +| `adversarial.json` | `a394f622…ff71d4` | `a394f622…ff71d4` | ✅ | +| `composition.json` | `71740d53…23b7492` | `4103169f…0b4c24d1` | ❌ | + +Full digests — manifest: `adversarial.json` `a394f6220cf04586f20ba1b504e01e51dc0810d8f1c0d79667b2a8b697ff71d4`, +`composition.json` `71740d53edd0b9e9fb297e6b84a6d1c508c1ee2c5fde27e6bf9b496e623b7492`. +Recomputed canonical-minified: `adversarial.json` `a394f6220cf04586f20ba1b504e01e51dc0810d8f1c0d79667b2a8b697ff71d4` +(matches), `composition.json` `4103169ff792a097fc281c5afeca5a4d7fe364720cb571f92922ab8c0b4c24d1` (does not). + +So `composition.json` was edited after `manifest.json` was last generated, and +the manifest was not regenerated. Per `SPEC.md` §9 a corpus change must bump the +corpus version and be recorded in the corpus changelog; regenerating the manifest +silently to match a changed file is the precise failure mode that discipline +exists to prevent. A conformance runner that honors the manifest (as the +discipline intends) would currently fail the digest check on `composition.json`. + +This is a defect in **`cc-framework`, not in this repository**, and is left for +that repo to resolve (confirm the current case values are intended, then +regenerate the manifest and record the change, or restore the prior file). It is +recorded here because the membrane's trustworthiness depends on the authority's +pinning being coherent, and because this vendored copy is pinned to the **current +bytes at the source commit**, drift and all. diff --git a/src/math/conformance/cc-kernel-v1/SPEC.md b/src/math/conformance/cc-kernel-v1/SPEC.md new file mode 100644 index 0000000..bbd8d14 --- /dev/null +++ b/src/math/conformance/cc-kernel-v1/SPEC.md @@ -0,0 +1,256 @@ +# cc-kernel-v1 — Normative Specification + +A CC composition kernel bounds the probability of a composed binary event from +the marginal probabilities of its parts, under unknown dependence. + +This document is **normative and self-contained**. An implementer works from +this document and [`cases/`](cases/), never from the Python source. That is the +point: an implementation written by reading `cc.compose` would inherit its +mistakes, and agreement between it and the reference would establish nothing. + +> **What passing establishes.** That an implementation computes the same +> intervals as the reference on the cases in this corpus. +> +> **What passing does not establish.** That either implementation is correct — +> two implementations can share a misreading of this spec. That the corpus +> covers the input space; it is a curated census whose size is an authoring +> decision. That any bound means a system is safe, a threshold is right, or a +> marginal is valid. + +--- + +## 1. Objects + +### 1.1 Event + +A named binary indicator. `1` denotes occurrence of the event being bounded — +by CC convention, a **guardrail failure or unsafe pass**, not a success. + +An event is a name and a marginal probability. It has no threshold, no +operating curve, and no false-positive rate. A deterministic refusal rule and a +tuned classifier are the same kind of input here. + +### 1.2 Marginals + +A mapping from event name to probability. + +- Names MUST be non-empty strings. +- Probabilities MUST be finite and in `[0, 1]`. +- The mapping MUST contain at least one entry. +- Order MUST NOT affect any output value. It MAY affect `binding_event` only + through the tie rule in §4.3, which is order-independent by construction. + +### 1.3 Event kind + +| Canonical | Aliases | Meaning | +|---|---|---| +| `all` | `and`, `AND`, `intersection` | `P(every event occurs)` — a conjunction | +| `any` | `or`, `OR`, `union` | `P(at least one occurs)` — a union | + +Any other value MUST be refused (§5, `unknown_event_kind`). + +### 1.4 Dependence assumption + +| Value | Meaning | +|---|---| +| `unconstrained` | Nothing assumed. Returns the sharp interval. The honest default. | +| `independent` | A point value, returned as a degenerate interval. | +| `comonotone` | The upper Fréchet corner, as a degenerate interval. | +| `countermonotone` | **Defined only for exactly two events.** See §6. | + +Any other value MUST be refused (`unknown_dependence`). An implementation MUST +NOT default an unrecognized value to `unconstrained`. + +--- + +## 2. The unconstrained interval + +For marginals `p_1 … p_n`: + +**Conjunction** (`event = "all"`): + +``` +lower = max(0, (Σ p_i) − (n − 1)) +upper = min_i p_i +``` + +**Union** (`event = "any"`): + +``` +lower = max_i p_i +upper = min(1, Σ p_i) +``` + +These are the Fréchet–Hoeffding inequalities. The mathematics is classical — +Fréchet 1935, Hoeffding 1940 — and this specification claims no novelty for it. + +Both endpoints are **pointwise sharp**: for any fixed marginals, some joint +distribution attains each. Neither can be tightened without dependence evidence. + +Both endpoints MUST be clipped to `[0, 1]` after computation, to absorb +floating-point excursions at the boundary. + +### 2.1 The finding this encodes + +Under a conjunction the upper bound is `min_i p_i`, which does **not** depend on +`n`. A conjunction of controls is no stronger than its single strongest member. +Adding a further control cannot raise the upper bound and can only lower the +floor. Case family `cliff-homogeneous-m*` pins this: ten events at `p = 0.1` +still bound to `[0, 0.1]` while independence predicts `1e-10`. + +--- + +## 3. The independence baseline + +Computed and reported on **every** result, whatever the dependence assumption: + +``` +independence_point = Π p_i (conjunction) +independence_point = 1 − Π (1 − p_i) (union) +``` + +This is a **comparison baseline, never an answer.** It exists so the gap it +understates stays visible. An implementation MUST report it even when +`dependence = "independent"`, where it coincides with the interval. + +Derived quantities: + +``` +width = max(0, upper − lower) +independence_regret = upper − independence_point +understatement_factor = upper / independence_point, undefined when the point is 0 +``` + +`understatement_factor` MUST serialize as JSON `null` when +`independence_point` is zero. JSON has no infinity, and a null here means the +ratio is *undefined*, not large. + +--- + +## 4. `binding_event` + +The name of the event whose marginal the upper bound turns on, or `null`. + +This field is the actionable part of the result: it names where effort belongs. + +### 4.1 Conjunction + +The upper bound is `min_i p_i`, so the argmin binds — improving any other event +moves the upper bound not at all. + +### 4.2 Union + +The upper bound is `min(1, Σ p_i)`, a sum rather than a single event. No event +binds, and `binding_event` MUST be `null` — **except** when exactly one event is +present, where it is that event. + +### 4.3 Ties + +If two or more events attain the minimum (within tolerance), `binding_event` +MUST be `null`. Improving either leaves the bound pinned by the other, so naming +one of them would misdirect effort. + +### 4.4 Constrained regimes + +When `dependence` is anything other than `unconstrained`, `binding_event` MUST +be `null`. The interval is then a stipulated point, not a bound turning on an +event. + +--- + +## 5. Refusals + +An implementation MUST refuse, not default, in each case below. Refusal reasons +are the identifiers used by `expect_refusal` in +[`cases/adversarial.json`](cases/adversarial.json). + +| Reason | Condition | +|---|---| +| `marginal_out_of_range` | a marginal outside `[0, 1]` | +| `marginal_not_finite` | a marginal that is NaN or infinite | +| `no_events` | an empty marginals mapping | +| `unknown_event_kind` | an event kind not in §1.3 | +| `unknown_dependence` | a dependence value not in §1.4 | +| `countermonotone_undefined` | `countermonotone` with more than two events (§6) | + +**JSON note.** JSON has no NaN literal. In `cases/adversarial.json` the +non-finite marginal is encoded as the **string** `"NaN"`. An implementation +running the corpus MUST map that string to its language's NaN before calling the +kernel — and MUST NOT accept a string as a probability in normal operation. + +--- + +## 6. Countermonotonicity is bivariate + +`dependence = "countermonotone"` with `n > 2` MUST be refused. + +Countermonotonicity is a strictly bivariate concept. Two events can be perfectly +negatively dependent — one occurs exactly when the other does not — but three +cannot all be pairwise mutually exclusive and exhaustive in that way, and there +is no `n`-dimensional countermonotonic structure for `n > 2`. + +The matching fact about the bound: the Fréchet–Hoeffding lower bound +`max(0, Σ p_i − (n−1))` **is not a copula in dimension ≥ 3**. It remains +*pointwise sharp* — for any fixed marginals some joint distribution attains it — +but no single dependence structure attains it everywhere. So there is no +countermonotone regime to tabulate beside independence and comonotonicity. + +An implementation that returns a number here is wrong. Silently offering a +"countermonotone" option for four events produces a value with the form of a +dependence regime and none of the content. + +For `n = 2`: + +``` +countermonotone value = max(0, p_1 + p_2 − 1) (conjunction) +countermonotone value = min(1, p_1 + p_2) (union) +``` + +--- + +## 7. Tolerance + +Numeric comparisons use an absolute tolerance of **1e-12**, declared in +[`manifest.json`](manifest.json). + +This sits far above the worst disagreement measured between the reference +closed form and the finite-atom LP (3.3e-16 over 600 randomized cases), and far +below any difference that would change a reported bound. An implementation +needing a looser tolerance to pass has a defect, not a rounding difference. + +--- + +## 8. Running the corpus + +``` +cases/composition.json accept cases — reproduce every field in `expect` +cases/adversarial.json reject cases — refuse with the named reason +manifest.json digests, tolerance, case count, non-claims +``` + +For each accept case: call the kernel with `input`, compare every key in +`expect` within tolerance. `binding_event` is compared exactly. + +For each reject case: call the kernel with `input` and require a refusal. An +implementation SHOULD distinguish the reason; a corpus runner MAY accept any +refusal if the implementation does not expose typed reasons, but MUST record +that it did so. + +A runner MUST report `pass/fail` counts as exact integers. **No confidence +interval may be attached to a pass rate over this corpus** — it is the whole +population, not a sample, and its size is an authoring decision. + +--- + +## 9. Versioning + +`cc-kernel-v1` is stable. Adding a case is a **new corpus version**, not an edit +to this one — a passing implementation must not start failing because the corpus +grew underneath it. + +Fixing a case whose expected value was **wrong** is a defect correction, and +MUST be recorded in the corpus changelog with the reason. Regenerating the +corpus to match a changed implementation, without such a record, is the failure +mode this discipline exists to prevent. + +**Never weaken a case to make an implementation pass.** diff --git a/src/math/conformance/cc-kernel-v1/adversarial.json b/src/math/conformance/cc-kernel-v1/adversarial.json new file mode 100644 index 0000000..7584f73 --- /dev/null +++ b/src/math/conformance/cc-kernel-v1/adversarial.json @@ -0,0 +1,107 @@ +{ + "case_count": 8, + "cases": [ + { + "description": "Countermonotonicity is strictly bivariate. The FH lower bound is not a copula in dimension >= 3, though it stays pointwise sharp. An implementation that returns a number here is wrong.", + "expect_refusal": "countermonotone_undefined", + "id": "reject-countermonotone-three-events", + "input": { + "dependence": "countermonotone", + "event": "all", + "marginals": { + "A": 0.3, + "B": 0.4, + "C": 0.5 + } + } + }, + { + "description": "Countermonotonicity is a relation between two events; with fewer than two there is nothing to be countermonotone with. Found by differential fuzz (seed 1): the Python reference raised IndexError and the Node implementation silently returned NaN. Both were wrong, differently.", + "expect_refusal": "countermonotone_undefined", + "id": "reject-countermonotone-one-event", + "input": { + "dependence": "countermonotone", + "event": "all", + "marginals": { + "A": 0.3 + } + } + }, + { + "description": "A marginal outside [0, 1] is not a probability.", + "expect_refusal": "marginal_out_of_range", + "id": "reject-marginal-above-one", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": 1.5, + "B": 0.2 + } + } + }, + { + "description": "A negative marginal is not a probability.", + "expect_refusal": "marginal_out_of_range", + "id": "reject-marginal-negative", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": -0.1, + "B": 0.2 + } + } + }, + { + "description": "A composition over zero events has no meaning.", + "expect_refusal": "no_events", + "id": "reject-empty-marginals", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": {} + } + }, + { + "description": "Only conjunction and union are defined by this corpus.", + "expect_refusal": "unknown_event_kind", + "id": "reject-unknown-event-kind", + "input": { + "dependence": "unconstrained", + "event": "xor", + "marginals": { + "A": 0.1 + } + } + }, + { + "description": "An unrecognized dependence assumption must fail closed, not default.", + "expect_refusal": "unknown_dependence", + "id": "reject-unknown-dependence", + "input": { + "dependence": "sorta-dependent", + "event": "all", + "marginals": { + "A": 0.1, + "B": 0.2 + } + } + }, + { + "description": "NaN is not a probability. Note this case is expressed as a string in JSON because JSON has no NaN literal; see the spec.", + "expect_refusal": "marginal_not_finite", + "id": "reject-non-finite-marginal", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": "NaN", + "B": 0.2 + } + } + } + ], + "corpus": "cc-kernel-v1", + "kind": "reject" +} diff --git a/src/math/conformance/cc-kernel-v1/composition.json b/src/math/conformance/cc-kernel-v1/composition.json new file mode 100644 index 0000000..ba1b7be --- /dev/null +++ b/src/math/conformance/cc-kernel-v1/composition.json @@ -0,0 +1,512 @@ +{ + "case_count": 24, + "cases": [ + { + "description": "Classical two-event conjunction. Lower is max(0, sum-1)=0; upper is min(p)=0.1.", + "expect": { + "binding_event": "A", + "independence_point": 0.020000000000000004, + "lower": 0.0, + "understatement_factor": 4.999999999999999, + "upper": 0.1, + "width": 0.1 + }, + "id": "and-two-classical", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": 0.1, + "B": 0.2 + } + } + }, + { + "description": "Marginals summing above 1 force a positive lower bound: 0.9+0.8-1 = 0.7.", + "expect": { + "binding_event": "B", + "independence_point": 0.7200000000000001, + "lower": 0.7000000000000002, + "understatement_factor": 1.111111111111111, + "upper": 0.8, + "width": 0.09999999999999987 + }, + "id": "and-two-overlap-forced", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": 0.9, + "B": 0.8 + } + } + }, + { + "description": "Tied minima: no single event binds, so binding_event is null.", + "expect": { + "binding_event": null, + "independence_point": 0.0625, + "lower": 0.0, + "understatement_factor": 4.0, + "upper": 0.25, + "width": 0.25 + }, + "id": "and-two-equal-tie", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": 0.25, + "B": 0.25 + } + } + }, + { + "description": "A narrow interval from extreme marginals. Narrowness is not evidence of validity.", + "expect": { + "binding_event": "A", + "independence_point": 0.0099, + "lower": 0.0, + "understatement_factor": 1.01010101010101, + "upper": 0.01, + "width": 0.01 + }, + "id": "and-two-extreme-asymmetry", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": 0.01, + "B": 0.99 + } + } + }, + { + "description": "Classical two-event union. Lower is max(p)=0.2; upper is min(1, sum)=0.3.", + "expect": { + "binding_event": null, + "independence_point": 0.2799999999999999, + "lower": 0.2, + "understatement_factor": 1.0714285714285718, + "upper": 0.30000000000000004, + "width": 0.10000000000000003 + }, + "id": "or-two-classical", + "input": { + "dependence": "unconstrained", + "event": "any", + "marginals": { + "A": 0.1, + "B": 0.2 + } + } + }, + { + "description": "Union upper bound clipped at 1 because the marginals sum above it.", + "expect": { + "binding_event": null, + "independence_point": 0.94, + "lower": 0.8, + "understatement_factor": 1.0638297872340425, + "upper": 1.0, + "width": 0.19999999999999996 + }, + "id": "or-two-clipped", + "input": { + "dependence": "unconstrained", + "event": "any", + "marginals": { + "A": 0.7, + "B": 0.8 + } + } + }, + { + "description": "Four deterministic controls, assumed evasion rates. Reproduces a published external result: lower 0, upper 0.01, independence 1.2e-5, factor 833.", + "expect": { + "binding_event": null, + "independence_point": 1.2e-05, + "lower": 0.0, + "understatement_factor": 833.3333333333334, + "upper": 0.01, + "width": 0.01 + }, + "id": "and-four-vinctura-small-chapter", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "IMMUTABLE": 0.01, + "SELF_REPORTED": 0.3, + "SEPARATION": 0.4, + "STALE": 0.01 + } + } + }, + { + "description": "Same four controls, optimistic assumed rates. Tied minima at 0.01.", + "expect": { + "binding_event": null, + "independence_point": 5.000000000000001e-07, + "lower": 0.0, + "understatement_factor": 19999.999999999996, + "upper": 0.01, + "width": 0.01 + }, + "id": "and-four-vinctura-optimistic", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "IMMUTABLE": 0.01, + "SELF_REPORTED": 0.05, + "SEPARATION": 0.1, + "STALE": 0.01 + } + } + }, + { + "description": "Same four controls, pessimistic assumed rates. IMMUTABLE binds at 0.05.", + "expect": { + "binding_event": "IMMUTABLE", + "independence_point": 0.0015000000000000002, + "lower": 0.0, + "understatement_factor": 33.33333333333333, + "upper": 0.05, + "width": 0.05 + }, + "id": "and-four-vinctura-pessimistic", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "IMMUTABLE": 0.05, + "SELF_REPORTED": 0.5, + "SEPARATION": 0.6, + "STALE": 0.1 + } + } + }, + { + "description": "Degenerate single-event conjunction. The interval collapses to the marginal.", + "expect": { + "binding_event": "A", + "independence_point": 0.42, + "lower": 0.42, + "understatement_factor": 1.0, + "upper": 0.42, + "width": 0.0 + }, + "id": "and-single-event", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": 0.42 + } + } + }, + { + "description": "Degenerate single-event union. The interval collapses to the marginal.", + "expect": { + "binding_event": "A", + "independence_point": 0.41999999999999993, + "lower": 0.42, + "understatement_factor": 1.0000000000000002, + "upper": 0.42, + "width": 0.0 + }, + "id": "or-single-event", + "input": { + "dependence": "unconstrained", + "event": "any", + "marginals": { + "A": 0.42 + } + } + }, + { + "description": "A zero marginal pins the conjunction to zero regardless of the other event.", + "expect": { + "binding_event": "A", + "independence_point": 0.0, + "lower": 0.0, + "understatement_factor": null, + "upper": 0.0, + "width": 0.0 + }, + "id": "and-zero-marginal", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": 0.0, + "B": 0.5 + } + } + }, + { + "description": "Certain events. The conjunction is certain.", + "expect": { + "binding_event": null, + "independence_point": 1.0, + "lower": 1.0, + "understatement_factor": 1.0, + "upper": 1.0, + "width": 0.0 + }, + "id": "and-unit-marginals", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "A": 1.0, + "B": 1.0 + } + } + }, + { + "description": "Independence returns a degenerate interval at the product. A baseline, not an answer.", + "expect": { + "binding_event": null, + "independence_point": 0.12, + "lower": 0.12, + "understatement_factor": 1.0, + "upper": 0.12, + "width": 0.0 + }, + "id": "and-two-independent", + "input": { + "dependence": "independent", + "event": "all", + "marginals": { + "A": 0.3, + "B": 0.4 + } + } + }, + { + "description": "Independent union: 1 - (1-0.3)(1-0.4) = 0.58.", + "expect": { + "binding_event": null, + "independence_point": 0.5800000000000001, + "lower": 0.5800000000000001, + "understatement_factor": 1.0, + "upper": 0.5800000000000001, + "width": 0.0 + }, + "id": "or-two-independent", + "input": { + "dependence": "independent", + "event": "any", + "marginals": { + "A": 0.3, + "B": 0.4 + } + } + }, + { + "description": "The upper Frechet corner as a degenerate interval.", + "expect": { + "binding_event": null, + "independence_point": 0.12, + "lower": 0.3, + "understatement_factor": 2.5, + "upper": 0.3, + "width": 0.0 + }, + "id": "and-two-comonotone", + "input": { + "dependence": "comonotone", + "event": "all", + "marginals": { + "A": 0.3, + "B": 0.4 + } + } + }, + { + "description": "Defined only for exactly two events: max(0, 0.3+0.4-1) = 0.", + "expect": { + "binding_event": null, + "independence_point": 0.12, + "lower": 0.0, + "understatement_factor": 0.0, + "upper": 0.0, + "width": 0.0 + }, + "id": "and-two-countermonotone", + "input": { + "dependence": "countermonotone", + "event": "all", + "marginals": { + "A": 0.3, + "B": 0.4 + } + } + }, + { + "description": "Two-event countermonotone with a positive floor: 0.7+0.8-1 = 0.5.", + "expect": { + "binding_event": null, + "independence_point": 0.5599999999999999, + "lower": 0.5, + "understatement_factor": 0.8928571428571429, + "upper": 0.5, + "width": 0.0 + }, + "id": "and-two-countermonotone-positive", + "input": { + "dependence": "countermonotone", + "event": "all", + "marginals": { + "A": 0.7, + "B": 0.8 + } + } + }, + { + "description": "Correlation cliff at m=2: independence predicts 1e-2, the sharp upper bound stays 0.1. Stacking buys nothing under adversarial dependence.", + "expect": { + "binding_event": null, + "independence_point": 0.010000000000000002, + "lower": 0.0, + "understatement_factor": 9.999999999999998, + "upper": 0.1, + "width": 0.1 + }, + "id": "cliff-homogeneous-m2", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "G0": 0.1, + "G1": 0.1 + } + } + }, + { + "description": "Correlation cliff at m=3: independence predicts 1e-3, the sharp upper bound stays 0.1. Stacking buys nothing under adversarial dependence.", + "expect": { + "binding_event": null, + "independence_point": 0.0010000000000000002, + "lower": 0.0, + "understatement_factor": 99.99999999999999, + "upper": 0.1, + "width": 0.1 + }, + "id": "cliff-homogeneous-m3", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "G0": 0.1, + "G1": 0.1, + "G2": 0.1 + } + } + }, + { + "description": "Correlation cliff at m=4: independence predicts 1e-4, the sharp upper bound stays 0.1. Stacking buys nothing under adversarial dependence.", + "expect": { + "binding_event": null, + "independence_point": 0.00010000000000000003, + "lower": 0.0, + "understatement_factor": 999.9999999999998, + "upper": 0.1, + "width": 0.1 + }, + "id": "cliff-homogeneous-m4", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "G0": 0.1, + "G1": 0.1, + "G2": 0.1, + "G3": 0.1 + } + } + }, + { + "description": "Correlation cliff at m=5: independence predicts 1e-5, the sharp upper bound stays 0.1. Stacking buys nothing under adversarial dependence.", + "expect": { + "binding_event": null, + "independence_point": 1.0000000000000004e-05, + "lower": 0.0, + "understatement_factor": 9999.999999999996, + "upper": 0.1, + "width": 0.1 + }, + "id": "cliff-homogeneous-m5", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "G0": 0.1, + "G1": 0.1, + "G2": 0.1, + "G3": 0.1, + "G4": 0.1 + } + } + }, + { + "description": "Correlation cliff at m=8: independence predicts 1e-8, the sharp upper bound stays 0.1. Stacking buys nothing under adversarial dependence.", + "expect": { + "binding_event": null, + "independence_point": 1.0000000000000005e-08, + "lower": 0.0, + "understatement_factor": 9999999.999999996, + "upper": 0.1, + "width": 0.1 + }, + "id": "cliff-homogeneous-m8", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "G0": 0.1, + "G1": 0.1, + "G2": 0.1, + "G3": 0.1, + "G4": 0.1, + "G5": 0.1, + "G6": 0.1, + "G7": 0.1 + } + } + }, + { + "description": "Correlation cliff at m=10: independence predicts 1e-10, the sharp upper bound stays 0.1. Stacking buys nothing under adversarial dependence.", + "expect": { + "binding_event": null, + "independence_point": 1.0000000000000006e-10, + "lower": 0.0, + "understatement_factor": 999999999.9999995, + "upper": 0.1, + "width": 0.1 + }, + "id": "cliff-homogeneous-m10", + "input": { + "dependence": "unconstrained", + "event": "all", + "marginals": { + "G0": 0.1, + "G1": 0.1, + "G2": 0.1, + "G3": 0.1, + "G4": 0.1, + "G5": 0.1, + "G6": 0.1, + "G7": 0.1, + "G8": 0.1, + "G9": 0.1 + } + } + } + ], + "corpus": "cc-kernel-v1", + "kind": "accept", + "tolerance": 1e-12 +} diff --git a/src/math/conformance/cc-kernel-v1/manifest.json b/src/math/conformance/cc-kernel-v1/manifest.json new file mode 100644 index 0000000..72dd3b5 --- /dev/null +++ b/src/math/conformance/cc-kernel-v1/manifest.json @@ -0,0 +1,14 @@ +{ + "corpus": "cc-kernel-v1", + "files": { + "cases/adversarial.json": "a394f6220cf04586f20ba1b504e01e51dc0810d8f1c0d79667b2a8b697ff71d4", + "cases/composition.json": "71740d53edd0b9e9fb297e6b84a6d1c508c1ee2c5fde27e6bf9b496e623b7492" + }, + "non_claims": [ + "Passing this corpus establishes that an implementation computes the same intervals as the reference on these cases. It does not establish that either implementation is correct: two implementations can share a misreading.", + "The corpus is a curated census, not a sample. Its size is an authoring decision, it carries no coverage claim, and no confidence interval may be attached to a pass rate over it.", + "Passing establishes nothing about safety, calibration, threshold choice, or whether the supplied marginals mean anything." + ], + "tolerance": 1e-12, + "total_cases": 32 +}