chainlesschain 0.166.91 → 0.166.93

package/src/lib/evolution/rrsi-statistics-simulation.js

@@ -0,0 +1,354 @@
+/** Preregistered synthetic coverage/power checks, not production calibration. */
+import {
+  computeRrsiBoundedClusterInterval,
+  computeRrsiClusterEnvelopeInterval,
+  RRSI_BOUNDED_CLUSTER_METHOD,
+  RRSI_CLUSTER_ENVELOPE_METHOD,
+} from "./rrsi-group-statistics.js";
+import {
+  snapshotRrsiData,
+  rrsiExact,
+  rrsiInteger,
+  rrsiFinite,
+  rrsiDigest,
+  rrsiHash,
+  rrsiCanonical,
+  rrsiEnvelope,
+  rrsiFail,
+} from "./rrsi-data.js";
+
+export const RRSI_STATISTICS_SIMULATION_PLAN_SCHEMA =
+  "chainlesschain.rrsi-statistics-simulation-plan/v1";
+export const RRSI_STATISTICS_SIMULATION_REPORT_SCHEMA =
+  "chainlesschain.rrsi-statistics-simulation-report/v1";
+const KEYS = [
+  "intervalMethod",
+  "bootstrapSamples",
+  "trialCount",
+  "clusterCounts",
+  "comparisonCount",
+  "familyAlpha",
+  "qualityThreshold",
+  "targetPower",
+  "randomnessSeedDigest",
+];
+const LAWS = [
+  {
+    id: "symmetric-null",
+    negative: -1,
+    positive: 1,
+    positiveProbability: 0.5,
+    mean: 0,
+  },
+  {
+    id: "rare-negative-null",
+    negative: -0.95,
+    positive: 0.05,
+    positiveProbability: 0.95,
+    mean: 0,
+  },
+  {
+    id: "moderate-positive",
+    negative: -0.25,
+    positive: 0.75,
+    positiveProbability: 0.5,
+    mean: 0.25,
+  },
+  {
+    id: "strong-positive",
+    negative: 0.6,
+    positive: 1,
+    positiveProbability: 0.5,
+    mean: 0.8,
+  },
+];
+
+export function buildRrsiStatisticsSimulationPlan(input) {
+  const value = snapshotRrsiData(input);
+  rrsiExact(value, KEYS, "statistics simulation plan");
+  rrsiInteger(value.trialCount, "Monte Carlo trials", 100, 10000);
+  rrsiInteger(value.comparisonCount, "simulation comparison family", 1, 32);
+  rrsiFinite(value.familyAlpha, "simulation family alpha", 0.0001, 0.05);
+  rrsiFinite(value.qualityThreshold, "simulation quality threshold", 0, 0.5);
+  rrsiFinite(value.targetPower, "simulation planned power", 0.8, 0.99);
+  rrsiDigest(value.randomnessSeedDigest, "simulation randomness seed");
+  if (
+    ![RRSI_BOUNDED_CLUSTER_METHOD, RRSI_CLUSTER_ENVELOPE_METHOD].includes(
+      value.intervalMethod,
+    )
+  )
+    rrsiFail("simulation must freeze the actual interval method");
+  const fullMethod = value.intervalMethod === RRSI_CLUSTER_ENVELOPE_METHOD;
+  if (fullMethod) {
+    rrsiInteger(
+      value.bootstrapSamples,
+      "simulation bootstrap samples",
+      1000,
+      1_000_000,
+    );
+    if (
+      (value.bootstrapSamples * value.familyAlpha) / value.comparisonCount / 2 <
+      25
+    )
+      rrsiFail("simulation has insufficient bootstrap tail resolution");
+  } else if (value.bootstrapSamples !== null)
+    rrsiFail("Hoeffding-only simulation must not claim bootstrap samples");
+  if (
+    !Array.isArray(value.clusterCounts) ||
+    value.clusterCounts.length < 1 ||
+    value.clusterCounts.length > 6
+  )
+    rrsiFail("simulation cluster counts must be a bounded nonempty grid");
+  value.clusterCounts.forEach((count) =>
+    rrsiInteger(count, "simulation cluster count", 20, 4000),
+  );
+  if (new Set(value.clusterCounts).size !== value.clusterCounts.length)
+    rrsiFail("simulation sample grid has duplicate counts");
+  const operations =
+    value.trialCount *
+    value.comparisonCount *
+    LAWS.length *
+    2 *
+    value.clusterCounts.reduce((sum, count) => sum + count, 0) *
+    (fullMethod ? value.bootstrapSamples : 1);
+  // Full-method simulations use the direct production primitive, not a surrogate.
+  const operationLimit = fullMethod ? 500_000_000 : 50_000_000;
+  if (operations > operationLimit)
+    rrsiFail(
+      "Monte Carlo simulation exceeds frozen operation bound",
+      "CC_RRSI_BUDGET_EXCEEDED",
+    );
+  return rrsiEnvelope(
+    RRSI_STATISTICS_SIMULATION_PLAN_SCHEMA,
+    "simulationPlanDigest",
+    {
+      ...value,
+      clusterCounts: [...value.clusterCounts].sort((a, b) => a - b),
+      laws: LAWS,
+      weightProfiles: ["equal-task-counts", "one-dominant-component"],
+      operations,
+      operationLimit,
+      bootstrapAlgorithm: fullMethod
+        ? "direct-uniform-cluster-picks-xorshift32/v1"
+        : null,
+      monteCarloIntervalMethod: "wilson-score-95/v1",
+      simultaneousMonteCarloMethod: "bonferroni-hoeffding-all-grid-rates-95/v1",
+      simultaneousRateCount: value.clusterCounts.length * LAWS.length * 2 * 4,
+      contrastJointLaw:
+        "independent-synthetic-contrast-deltas-not-three-arm-outcomes",
+      hypothesisScope: "one-synthetic-pool-and-variant-per-family",
+      bootstrapIndexCoupling: "same-stream-for-contrasts-within-each-trial",
+      stoppingRule: "run-every-preregistered-scenario-no-interim-selection",
+    },
+  );
+}
+
+function verifyPlan(input) {
+  const value = snapshotRrsiData(input);
+  const rebuilt = buildRrsiStatisticsSimulationPlan(
+    Object.fromEntries(KEYS.map((key) => [key, value[key]])),
+  );
+  if (rrsiCanonical(value) !== rrsiCanonical(rebuilt))
+    rrsiFail("simulation plan differs from frozen scenarios");
+  return rebuilt;
+}
+
+function random(digest) {
+  let state = Number.parseInt(digest.slice(7, 15), 16) || 0x6d2b79f5;
+  return () => {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    return (state >>> 0) / 0x1_0000_0000;
+  };
+}
+
+function rate(successes, trials, rateCount) {
+  const value = successes / trials,
+    z = 1.959963984540054;
+  const denominator = 1 + (z * z) / trials;
+  const center = (value + (z * z) / (2 * trials)) / denominator;
+  const margin =
+    (z *
+      Math.sqrt(
+        (value * (1 - value)) / trials + (z * z) / (4 * trials * trials),
+      )) /
+    denominator;
+  const simultaneousMargin = Math.sqrt(
+    Math.log((2 * rateCount) / 0.05) / (2 * trials),
+  );
+  return {
+    successes,
+    trials,
+    estimate: value,
+    monteCarlo95: {
+      lower: Math.max(0, center - margin),
+      upper: Math.min(1, center + margin),
+    },
+    simultaneousGrid95: {
+      lower: Math.max(0, value - simultaneousMargin),
+      upper: Math.min(1, value + simultaneousMargin),
+    },
+  };
+}
+
+export function runRrsiStatisticsSimulation(input) {
+  const plan = verifyPlan(input);
+  const scenarios = [];
+  for (const groupCount of plan.clusterCounts)
+    for (const weightProfile of plan.weightProfiles)
+      for (const law of plan.laws) {
+        const taskCounts = Array(groupCount).fill(1);
+        if (weightProfile === "one-dominant-component") taskCounts[0] = 100;
+        const generator = random(
+          rrsiHash("chainlesschain.rrsi-simulation-random/v1", {
+            seed: plan.randomnessSeedDigest,
+            groupCount,
+            weightProfile,
+            law: law.id,
+          }),
+        );
+        let coverage = 0,
+          power = 0,
+          unsupportedPositive = 0,
+          degenerateMiss = 0;
+        let effectiveGroupCount = null;
+        for (let trial = 0; trial < plan.trialCount; trial++) {
+          let familyCovered = true,
+            allAboveThreshold = true,
+            anyUnsupportedPositive = false,
+            anyDegenerateMiss = false;
+          for (
+            let comparison = 0;
+            comparison < plan.comparisonCount;
+            comparison++
+          ) {
+            const values = taskCounts.map(() =>
+              generator() < law.positiveProbability
+                ? law.positive
+                : law.negative,
+            );
+            const intervalInput = {
+              values,
+              taskCounts,
+              alpha: plan.familyAlpha / plan.comparisonCount,
+            };
+            const fullMethod =
+              plan.intervalMethod === RRSI_CLUSTER_ENVELOPE_METHOD;
+            const result = fullMethod
+              ? computeRrsiClusterEnvelopeInterval({
+                  ...intervalInput,
+                  bootstrapSamples: plan.bootstrapSamples,
+                  randomnessSeedDigest: rrsiHash(
+                    "chainlesschain.rrsi-simulation-bootstrap/v1",
+                    {
+                      seed: plan.randomnessSeedDigest,
+                      groupCount,
+                      weightProfile,
+                      law: law.id,
+                      trial,
+                    },
+                  ),
+                })
+              : computeRrsiBoundedClusterInterval(intervalInput);
+            const interval = fullMethod ? result.confidenceInterval : result;
+            effectiveGroupCount = fullMethod
+              ? result.boundedInterval.effectiveGroupCount
+              : result.effectiveGroupCount;
+            familyCovered &&=
+              interval.lower <= law.mean + 1e-12 &&
+              interval.upper >= law.mean - 1e-12;
+            allAboveThreshold &&= interval.lower >= plan.qualityThreshold;
+            anyUnsupportedPositive ||= law.mean <= 0 && interval.lower > 0;
+            anyDegenerateMiss ||=
+              values.every((value) => value === values[0]) &&
+              Math.abs(values[0] - law.mean) > 1e-12;
+          }
+          if (familyCovered) coverage++;
+          if (allAboveThreshold) power++;
+          if (anyUnsupportedPositive) unsupportedPositive++;
+          if (anyDegenerateMiss) degenerateMiss++;
+        }
+        scenarios.push({
+          groupCount,
+          weightProfile,
+          distribution: law.id,
+          trueDelta: law.mean,
+          effectiveGroupCount,
+          taskCount: taskCounts.reduce((sum, count) => sum + count, 0),
+          familyCoverage: rate(
+            coverage,
+            plan.trialCount,
+            plan.simultaneousRateCount,
+          ),
+          familyThresholdPower: rate(
+            power,
+            plan.trialCount,
+            plan.simultaneousRateCount,
+          ),
+          unsupportedPositiveFamilyRate: rate(
+            unsupportedPositive,
+            plan.trialCount,
+            plan.simultaneousRateCount,
+          ),
+          zeroSpreadDiagnosticMissRate: rate(
+            degenerateMiss,
+            plan.trialCount,
+            plan.simultaneousRateCount,
+          ),
+        });
+      }
+  const powerEstimates = plan.laws
+    .filter((law) => law.mean > plan.qualityThreshold)
+    .flatMap((law) =>
+      plan.weightProfiles.map((profile) => {
+        const eligible = scenarios.filter(
+          (row) =>
+            row.distribution === law.id &&
+            row.weightProfile === profile &&
+            row.familyThresholdPower.simultaneousGrid95.lower >=
+              plan.targetPower,
+        );
+        return {
+          distribution: law.id,
+          weightProfile: profile,
+          minimumGridGroupCountMeetingPower: eligible[0]?.groupCount ?? null,
+        };
+      }),
+    );
+  const coverageCheckedOnGrid = scenarios.every(
+    (row) =>
+      row.familyCoverage.simultaneousGrid95.lower >= 1 - plan.familyAlpha,
+  );
+  return rrsiEnvelope(
+    RRSI_STATISTICS_SIMULATION_REPORT_SCHEMA,
+    "simulationReportDigest",
+    {
+      simulationPlanDigest: plan.simulationPlanDigest,
+      scope: "preregistered-synthetic-independent-cluster-grid-only",
+      intervalMethod: plan.intervalMethod,
+      fullAnalysisMethodSimulated:
+        plan.intervalMethod === RRSI_CLUSTER_ENVELOPE_METHOD,
+      hoeffdingOnlyPowerCannotSelectFullMethodSampleSize:
+        plan.intervalMethod === RRSI_BOUNDED_CLUSTER_METHOD,
+      familyAlpha: plan.familyAlpha,
+      comparisonCount: plan.comparisonCount,
+      trialCountPerScenario: plan.trialCount,
+      status: coverageCheckedOnGrid ? "synthetic-grid-supported" : "hold",
+      scenarios,
+      powerEstimates,
+      coverageCheckedOnGrid,
+      monteCarloIntervalsAreApproximate: true,
+      pointwiseWilsonIntervalsAreNotSimultaneous: true,
+      sampleGridSelectionUsesSimultaneousBounds: true,
+      simultaneousBoundsConditionalOnIndependentMonteCarloTrials: true,
+      syntheticRngIsNotProductionEvidence: true,
+      threeArmExperimentPowerValidated: false,
+      mathematicalGuaranteeConditionalOnIndependentBoundedClusters: true,
+      productionCoverageValidated: false,
+      productionPowerValidated: false,
+      sourceIndependenceVerified: false,
+      statisticalProtocolValidated: false,
+    },
+  );
+}

package/src/lib/evolution/rrsi-tenant-index-anchor-contracts.js

@@ -0,0 +1,223 @@
+/** Signed anchor declarations. A valid signature is never tenant authority. */
+import { createHash, createPublicKey, verify } from "node:crypto";
+import {
+  rrsiCanonical,
+  rrsiHash,
+  rrsiExact,
+  rrsiId,
+  rrsiDigest,
+  rrsiInteger,
+  rrsiEnvelope,
+  verifyRrsiEnvelope,
+  snapshotRrsiData,
+  rrsiFail,
+} from "./rrsi-data.js";
+
+export const RRSI_TENANT_INDEX_ANCHOR_SCHEMA =
+  "chainlesschain.rrsi-tenant-index-anchor/v1";
+export const RRSI_TENANT_INDEX_ANCHOR_SIGNATURE_SCHEMA =
+  "chainlesschain.rrsi-tenant-index-anchor-signature-check/v1";
+export const RRSI_TENANT_INDEX_ANCHOR_HOLD_CODE =
+  "CC_RRSI_TENANT_INDEX_ANCHOR_HOLD";
+const SIGNATURE_DOMAIN = "chainlesschain.rrsi-tenant-index-anchor-signature/v1";
+const INPUT_KEYS = [
+  "deploymentId",
+  "tenantId",
+  "routingScope",
+  "indexId",
+  "ledgerIdentity",
+  "artifactScope",
+  "storageGraphDigest",
+  "rootPublicKeyDigest",
+  "revision",
+  "previousAnchorDigest",
+  "checkpoint",
+  "restrictionHistory",
+];
+const sha = (bytes) =>
+  `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const same = (a, b) => rrsiCanonical(a) === rrsiCanonical(b);
+function hold(message) {
+  rrsiFail(message, RRSI_TENANT_INDEX_ANCHOR_HOLD_CODE);
+}
+function ledgerId(value, label) {
+  if (
+    typeof value !== "string" ||
+    !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$/u.test(value)
+  )
+    hold(`${label} is not a Ledger identifier`);
+}
+function journalIdentity(value) {
+  rrsiExact(
+    value,
+    ["ledgerId", "identityDigest", "epoch"],
+    "anchor journal identity",
+  );
+  ledgerId(value.ledgerId, "ledgerId");
+  ledgerId(value.epoch, "epoch");
+  rrsiDigest(value.identityDigest, "identity digest");
+}
+
+export function buildRrsiTenantIndexAnchor(input) {
+  const value = snapshotRrsiData(input);
+  rrsiExact(value, INPUT_KEYS, "tenant index anchor input");
+  rrsiId(value.deploymentId, "deployment ID");
+  rrsiId(value.tenantId, "tenant ID");
+  if (!["installation", "shared-tenant-authority"].includes(value.routingScope))
+    hold("anchor routing scope must be explicit");
+  const expectedIndex = `rrsi-text.${rrsiHash("chainlesschain.rrsi-observed-text-index/v1", value.tenantId).slice(7)}`;
+  if (value.indexId !== expectedIndex)
+    hold("anchor index ID must derive only from tenant");
+  journalIdentity(value.ledgerIdentity);
+  rrsiExact(
+    value.artifactScope,
+    ["artifactTenantId", "audience", "purpose"],
+    "anchor artifact scope",
+  );
+  for (const [name, entry] of Object.entries(value.artifactScope))
+    rrsiId(entry, name);
+  if (value.artifactScope.purpose !== "evolution-ledger")
+    hold("anchor requires original Ledger retention purpose");
+  rrsiDigest(value.storageGraphDigest, "storage graph digest");
+  rrsiDigest(value.rootPublicKeyDigest, "declared root public key digest");
+  rrsiInteger(value.revision, "anchor revision", 1, 2 ** 31 - 1);
+  if (value.revision === 1) {
+    if (value.previousAnchorDigest !== null)
+      hold("first anchor must not claim a predecessor");
+  } else rrsiDigest(value.previousAnchorDigest, "previous anchor digest");
+  rrsiExact(
+    value.checkpoint,
+    ["ledgerId", "identityDigest", "epoch", "sequence", "headDigest"],
+    "anchor checkpoint",
+  );
+  const checkpointIdentity = Object.fromEntries(
+    ["ledgerId", "identityDigest", "epoch"].map((name) => [
+      name,
+      value.checkpoint[name],
+    ]),
+  );
+  if (!same(checkpointIdentity, value.ledgerIdentity))
+    hold("anchor checkpoint belongs to another journal");
+  rrsiInteger(value.checkpoint.sequence, "checkpoint sequence", 0);
+  rrsiDigest(value.checkpoint.headDigest, "checkpoint head digest");
+  rrsiExact(
+    value.restrictionHistory,
+    ["recordCount", "tailRecordDigest", "restrictionsDigest"],
+    "anchor restriction history",
+  );
+  rrsiInteger(
+    value.restrictionHistory.recordCount,
+    "restriction record count",
+    0,
+    256,
+  );
+  if (value.restrictionHistory.recordCount > value.checkpoint.sequence)
+    hold("restriction count exceeds the declared journal checkpoint");
+  if (value.restrictionHistory.recordCount === 0) {
+    if (value.restrictionHistory.tailRecordDigest !== null)
+      hold("empty restriction history must have no tail");
+  } else
+    rrsiDigest(
+      value.restrictionHistory.tailRecordDigest,
+      "restriction tail digest",
+    );
+  rrsiDigest(
+    value.restrictionHistory.restrictionsDigest,
+    "restriction set digest",
+  );
+  return rrsiEnvelope(RRSI_TENANT_INDEX_ANCHOR_SCHEMA, "anchorDigest", value);
+}
+
+export function verifyRrsiTenantIndexAnchor(input) {
+  return verifyRrsiEnvelope(
+    input,
+    RRSI_TENANT_INDEX_ANCHOR_SCHEMA,
+    "anchorDigest",
+    INPUT_KEYS,
+    buildRrsiTenantIndexAnchor,
+  );
+}
+
+/** Exact domain-separated bytes for an external signer; no signer default. */
+export function serializeRrsiTenantIndexAnchorSignatureMessage(anchor) {
+  const checked = verifyRrsiTenantIndexAnchor(anchor);
+  return Buffer.from(`${SIGNATURE_DOMAIN}\0${rrsiCanonical(checked)}`, "utf8");
+}
+
+/**
+ * Mathematical verification against an explicitly supplied public key only.
+ * This deliberately creates no trusted-root brand, pin store or routing grant.
+ */
+export function verifyRrsiTenantIndexAnchorSignature(input) {
+  const value = snapshotRrsiData(input);
+  rrsiExact(
+    value,
+    ["anchor", "publicKeySpki", "signature"],
+    "anchor signature input",
+  );
+  const anchor = verifyRrsiTenantIndexAnchor(value.anchor);
+  if (
+    typeof value.publicKeySpki !== "string" ||
+    value.publicKeySpki.length > 128
+  )
+    hold("anchor public key must be bounded canonical Ed25519 SPKI");
+  const publicBytes = Buffer.from(value.publicKeySpki, "base64url");
+  if (
+    publicBytes.length !== 44 ||
+    publicBytes.toString("base64url") !== value.publicKeySpki
+  )
+    hold("anchor public key SPKI encoding differs");
+  let publicKey;
+  try {
+    publicKey = createPublicKey({
+      key: publicBytes,
+      format: "der",
+      type: "spki",
+    });
+  } catch {
+    hold("anchor public key SPKI cannot be parsed");
+  }
+  if (
+    publicKey.asymmetricKeyType !== "ed25519" ||
+    !publicKey.export({ format: "der", type: "spki" }).equals(publicBytes)
+  )
+    hold("anchor public key must be exact Ed25519 SPKI");
+  if (sha(publicBytes) !== anchor.rootPublicKeyDigest)
+    hold("anchor public key differs from the declared root digest");
+  if (typeof value.signature !== "string" || value.signature.length !== 86)
+    hold("anchor signature must be bounded canonical Ed25519 bytes");
+  const signatureBytes = Buffer.from(value.signature, "base64url");
+  if (
+    signatureBytes.length !== 64 ||
+    signatureBytes.toString("base64url") !== value.signature
+  )
+    hold("anchor signature encoding differs");
+  if (
+    !verify(
+      null,
+      serializeRrsiTenantIndexAnchorSignatureMessage(anchor),
+      publicKey,
+      signatureBytes,
+    )
+  )
+    hold("anchor signature was rejected");
+  return rrsiEnvelope(
+    RRSI_TENANT_INDEX_ANCHOR_SIGNATURE_SCHEMA,
+    "signatureCheckDigest",
+    {
+      anchorDigest: anchor.anchorDigest,
+      publicKeyDigest: anchor.rootPublicKeyDigest,
+      declaredDeploymentId: anchor.deploymentId,
+      declaredTenantId: anchor.tenantId,
+      declaredRoutingScope: anchor.routingScope,
+      signatureVerifiedRelativeToKey: true,
+      rootAuthorityVerified: false,
+      routingPinVerified: false,
+      historyTransferVerified: false,
+      tenantWideIndexAuthorityVerified: false,
+      generationProvenanceVerified: false,
+      grantsMutationOrPromotionAuthority: false,
+      decision: "HOLD",
+    },
+  );
+}