chainlesschain 0.166.91 → 0.166.93

package/src/lib/evolution/rrsi-native-quality-receipt-contracts.js

@@ -0,0 +1,321 @@
+/** Historical assessment integrity only. This verifier never grants live authority. */
+import { isProxy } from "node:util/types";
+import {
+  buildRrsiEvalCampaignPlan,
+  buildRrsiNativeStatisticsRegistrationBindings,
+} from "./rrsi-cohort-registration.js";
+import { verifyRrsiNativeGroupStatisticsPlan } from "./rrsi-native-group-statistics-plan.js";
+import {
+  snapshotRrsiData,
+  rrsiExact,
+  rrsiDigest,
+  rrsiInteger,
+  rrsiBoolean,
+  rrsiCanonical,
+  rrsiEnvelope,
+  rrsiFail,
+} from "./rrsi-data.js";
+
+export const RRSI_NATIVE_QUALITY_RECEIPT_SCHEMA =
+  "chainlesschain.rrsi-native-required-quality-receipt/v1";
+export const RRSI_NATIVE_QUALITY_UNVERIFIED_PREREQUISITES = Object.freeze({
+  sourceIndependenceVerified: false,
+  sourceProvenanceVerified: false,
+  underlyingObservationTimeVerified: false,
+  underlyingExecutionReceiptsReverified: false,
+  nativeContentDerivationVerified: false,
+  armLifecycleVerified: false,
+  recipeExecutionVerified: false,
+  requestCostGraphVerified: false,
+  billingComplete: false,
+  completeLifecycleCostVerified: false,
+  cleanupVerified: false,
+  statisticalProtocolValidated: false,
+  calibrationVerified: false,
+  crossSelectionQueryErrorRateControlled: false,
+  manualRemediationMeasured: false,
+  productionParentReadbackVerified: false,
+});
+export const RRSI_NATIVE_QUALITY_REQUIRED_REASONS = Object.freeze([
+  "SOURCE_INDEPENDENCE_UNVERIFIED",
+  "SOURCE_PROVENANCE_UNVERIFIED",
+  "UNDERLYING_OBSERVATION_TIME_UNVERIFIED",
+  "UNDERLYING_EXECUTION_RECEIPTS_UNVERIFIED",
+  "NATIVE_CONTENT_DERIVATION_UNVERIFIED",
+  "ARM_LIFECYCLE_UNVERIFIED",
+  "RECIPE_EXECUTION_UNVERIFIED",
+  "REQUEST_COST_GRAPH_UNVERIFIED",
+  "BILLING_INCOMPLETE",
+  "LIFECYCLE_COST_UNVERIFIED",
+  "CLEANUP_UNVERIFIED",
+  "STATISTICAL_PROTOCOL_UNVALIDATED",
+  "CALIBRATION_UNVERIFIED",
+  "CROSS_SELECTION_ERROR_RATE_UNCONTROLLED",
+  "MANUAL_REMEDIATION_UNMEASURED",
+  "PRODUCTION_PARENT_READBACK_UNVERIFIED",
+]);
+const FIELDS = [
+  "assessmentKind",
+  "stage",
+  "tenantId",
+  "goalId",
+  "historyDescriptor",
+  "auditHead",
+  "campaignDigest",
+  "campaignRootDigest",
+  "batchDigest",
+  "queryId",
+  "candidate",
+  "versions",
+  "nativeCandidateContents",
+  "parentIdentity",
+  "targetIdentity",
+  "lifecycleDigests",
+  "nativeEvaluationPlanDigest",
+  "evaluationMappingDigest",
+  "nativeBatchEvidenceDigest",
+  "statisticsPlanDigest",
+  "statisticsReportDigest",
+  "statisticsRegistration",
+  "reservationRecord",
+  "fullRowCensusDigest",
+  "statisticalRowSetDigest",
+  "plannedActorObservations",
+  "observedRowClaims",
+  "missingActorObservations",
+  "originalNativeGateVetoChildIds",
+  "budget",
+  "verifiedControlEvidence",
+  "unverifiedProductionPrerequisites",
+  "blockingReasons",
+  "decision",
+  "qualityVerdictVerified",
+  "grantsFinalEvaluationAuthority",
+  "grantsMutationOrDispatchAuthority",
+];
+const CONTROL_FIELDS = [
+  "originalHistoryJournalBound",
+  "originalHistoryHeadReverified",
+  "originalReceiptInventoryReverified",
+  "signedReceiptFreshnessReverified",
+  "allCohortInventoriesAuthenticated",
+  "presentedFinalReceiptRowsAuthenticated",
+  "completeSignedRows",
+  "fullTriangleDenominatorRetained",
+  "fullTriangleRowsPresent",
+  "controlledHistoryRegistrationOrderVerified",
+];
+function same(left, right, label) {
+  if (rrsiCanonical(left) !== rrsiCanonical(right))
+    rrsiFail(`recorded quality ${label} differs`, "CC_RRSI_HISTORY_CORRUPT");
+}
+
+/** Context must come from the actual applied History state, never receipt claims. */
+export function verifyRecordedRrsiNativeQualityReceipt(input, contextInput) {
+  const value = snapshotRrsiData(input);
+  const names = [
+    "descriptor",
+    "rootResolution",
+    "batchResolution",
+    "statisticsPlan",
+    "observedHead",
+  ];
+  if (
+    !contextInput ||
+    isProxy(contextInput) ||
+    Object.getPrototypeOf(contextInput) !== Object.prototype ||
+    Reflect.ownKeys(contextInput).length !== names.length
+  )
+    rrsiFail("recorded quality context requires plain own fields");
+  // The independently bounded root, batch resolution and plan must not be
+  // combined into one artificial two-MiB input document.
+  const context = Object.fromEntries(
+    names.map((name) => {
+      const field = Object.getOwnPropertyDescriptor(contextInput, name);
+      if (!field?.enumerable || !("value" in field))
+        rrsiFail("recorded quality context cannot use accessors");
+      return [name, snapshotRrsiData(field.value)];
+    }),
+  );
+  rrsiExact(
+    value,
+    [
+      "schema",
+      ...FIELDS,
+      "structuralOnly",
+      "authenticated",
+      "readyForExecution",
+      "qualifiesForPromotion",
+      "qualityReceiptDigest",
+    ],
+    "recorded quality receipt",
+  );
+  const core = Object.fromEntries(FIELDS.map((field) => [field, value[field]]));
+  same(
+    value,
+    rrsiEnvelope(
+      RRSI_NATIVE_QUALITY_RECEIPT_SCHEMA,
+      "qualityReceiptDigest",
+      core,
+    ),
+    "envelope",
+  );
+  const resolution = context.batchResolution,
+    { batch, campaign } = resolution;
+  if (!["selection", "generalization"].includes(batch.stage))
+    rrsiFail("recorded quality stage is invalid");
+  const plan = verifyRrsiNativeGroupStatisticsPlan(context.statisticsPlan, {
+    campaign,
+    batch,
+  });
+  const root = buildRrsiEvalCampaignPlan(context.rootResolution);
+  const registration = resolution.statisticsRegistration
+    ? buildRrsiNativeStatisticsRegistrationBindings(
+        resolution.statisticsRegistration,
+        resolution.reservationRecord,
+      )
+    : null;
+  const expected = {
+    assessmentKind: `${batch.stage}-required-quality`,
+    stage: batch.stage,
+    tenantId: campaign.tenantId,
+    goalId: campaign.goalId,
+    historyDescriptor: context.descriptor,
+    auditHead: context.observedHead,
+    campaignDigest: campaign.campaignDigest,
+    campaignRootDigest: root.campaignRootDigest,
+    batchDigest: batch.batchDigest,
+    queryId: batch.queryId,
+    candidate: batch.candidate,
+    versions: batch.versions,
+    nativeCandidateContents: batch.nativeCandidateContents,
+    parentIdentity: batch.parentIdentity,
+    targetIdentity: batch.targetIdentity,
+    lifecycleDigests: batch.lifecycleDigests,
+    nativeEvaluationPlanDigest: batch.nativeEvaluationPlanDigest,
+    evaluationMappingDigest: batch.evaluationMappingDigest,
+    statisticsPlanDigest: plan.statisticsPlanDigest,
+    statisticsRegistration: registration,
+    reservationRecord: resolution.reservationRecord,
+    unverifiedProductionPrerequisites:
+      RRSI_NATIVE_QUALITY_UNVERIFIED_PREREQUISITES,
+    decision: "HOLD",
+    qualityVerdictVerified: false,
+    grantsFinalEvaluationAuthority: false,
+    grantsMutationOrDispatchAuthority: false,
+  };
+  for (const [field, expectedValue] of Object.entries(expected))
+    same(value[field], expectedValue, field);
+  for (const field of [
+    "nativeBatchEvidenceDigest",
+    "statisticsReportDigest",
+    "fullRowCensusDigest",
+    "statisticalRowSetDigest",
+  ])
+    rrsiDigest(value[field], `quality ${field}`);
+  const planned = batch.children.reduce(
+    (sum, child) =>
+      sum +
+      Object.keys(child.byArm).length *
+        Object.values(child.plannedObservationsPerArmByPartition).reduce(
+          (total, count) => total + count,
+          0,
+        ),
+    0,
+  );
+  same(value.plannedActorObservations, planned, "planned denominator");
+  rrsiInteger(value.observedRowClaims, "quality observed rows", 0, planned);
+  same(
+    value.missingActorObservations,
+    planned - value.observedRowClaims,
+    "missing denominator",
+  );
+  same(
+    value.budget,
+    {
+      declaredBudgetSettlementComplete: resolution.children.every((child) =>
+        child.states.every((arm) => arm.status === "settled"),
+      ),
+      budgetOverrun: resolution.budgetOverrun,
+      allocationBinding: batch.batchDigest,
+      declaredAccountingOnly: true,
+    },
+    "budget snapshot",
+  );
+  rrsiExact(
+    value.verifiedControlEvidence,
+    CONTROL_FIELDS,
+    "recorded quality controls",
+  );
+  for (const field of CONTROL_FIELDS)
+    rrsiBoolean(
+      value.verifiedControlEvidence[field],
+      `quality control ${field}`,
+    );
+  for (const field of [
+    "originalHistoryJournalBound",
+    "originalHistoryHeadReverified",
+    "originalReceiptInventoryReverified",
+    "signedReceiptFreshnessReverified",
+    "presentedFinalReceiptRowsAuthenticated",
+    "fullTriangleDenominatorRetained",
+  ])
+    same(value.verifiedControlEvidence[field], true, field);
+  same(
+    value.verifiedControlEvidence.controlledHistoryRegistrationOrderVerified,
+    registration !== null,
+    "registration control",
+  );
+  same(
+    value.verifiedControlEvidence.fullTriangleRowsPresent,
+    value.missingActorObservations === 0,
+    "row completeness",
+  );
+  if (
+    value.verifiedControlEvidence.completeSignedRows &&
+    !value.verifiedControlEvidence.fullTriangleRowsPresent
+  )
+    rrsiFail("recorded quality complete rows contradict denominator");
+  if (
+    !Array.isArray(value.originalNativeGateVetoChildIds) ||
+    new Set(value.originalNativeGateVetoChildIds).size !==
+      value.originalNativeGateVetoChildIds.length ||
+    value.originalNativeGateVetoChildIds.some(
+      (id) => !batch.children.some((child) => child.childId === id),
+    )
+  )
+    rrsiFail("recorded quality Gate veto inventory differs");
+  if (
+    !Array.isArray(value.blockingReasons) ||
+    value.blockingReasons.some(
+      (reason) =>
+        typeof reason !== "string" || !/^[A-Z][A-Z0-9_]{0,127}$/u.test(reason),
+    )
+  )
+    rrsiFail("recorded quality blocking reasons are invalid");
+  same(
+    value.blockingReasons,
+    [...new Set(value.blockingReasons)].sort(),
+    "blocking reason order",
+  );
+  const reasons = [...RRSI_NATIVE_QUALITY_REQUIRED_REASONS];
+  if (!value.verifiedControlEvidence.allCohortInventoriesAuthenticated)
+    reasons.push("MISSING_COHORT_EVIDENCE");
+  if (!registration) reasons.push("STATISTICAL_PROTOCOL_NOT_PREREGISTERED");
+  if (value.missingActorObservations)
+    reasons.push("INCOMPLETE_TRIANGLE_DENOMINATOR");
+  if (!value.verifiedControlEvidence.completeSignedRows)
+    reasons.push("MISSING_SIGNED_ROWS");
+  if (value.originalNativeGateVetoChildIds.length)
+    reasons.push("NATIVE_GATE_VETO");
+  if (!value.budget.declaredBudgetSettlementComplete)
+    reasons.push("UNSETTLED_NATIVE_BUDGET");
+  if (value.budget.budgetOverrun) reasons.push("BUDGET_EXCEEDED");
+  if (reasons.some((reason) => !value.blockingReasons.includes(reason)))
+    rrsiFail("recorded quality drops required HOLD reasons");
+  return rrsiEnvelope(
+    RRSI_NATIVE_QUALITY_RECEIPT_SCHEMA,
+    "qualityReceiptDigest",
+    core,
+  );
+}

package/src/lib/evolution/rrsi-native-quality-receipt.js

@@ -0,0 +1,256 @@
+/** Live native quality assessment. No current assessment grants final or promotion authority. */
+import { isProxy } from "node:util/types";
+import { captureRrsiNativeBatchEvidence } from "./rrsi-native-batch-evidence.js";
+import { captureRrsiHistoryLedgerAdapter } from "./rrsi-history-ledger-adapter.js";
+import { analyzeRrsiNativeBatchGroupStatistics } from "./rrsi-native-group-statistics.js";
+import { verifyRrsiNativeGroupStatisticsPlan } from "./rrsi-native-group-statistics-plan.js";
+import {
+  RRSI_NATIVE_QUALITY_RECEIPT_SCHEMA,
+  RRSI_NATIVE_QUALITY_UNVERIFIED_PREREQUISITES as UNVERIFIED,
+  RRSI_NATIVE_QUALITY_REQUIRED_REASONS as REQUIRED_REASONS,
+} from "./rrsi-native-quality-receipt-contracts.js";
+import {
+  snapshotRrsiData,
+  rrsiCanonical,
+  rrsiEnvelope,
+  rrsiHash,
+  rrsiFail,
+} from "./rrsi-data.js";
+
+export { RRSI_NATIVE_QUALITY_RECEIPT_SCHEMA } from "./rrsi-native-quality-receipt-contracts.js";
+const RECEIPTS = new WeakMap();
+const ROW_CENSUS_DOMAIN = "chainlesschain.rrsi-native-quality-row-census/v1";
+const FULL_ROWS_DOMAIN = "chainlesschain.rrsi-native-quality-full-rows/v1";
+
+function ownOptions(input) {
+  const names = ["batchEvidence", "plan"];
+  if (
+    !input ||
+    isProxy(input) ||
+    Object.getPrototypeOf(input) !== Object.prototype ||
+    Reflect.ownKeys(input).length !== names.length
+  )
+    rrsiFail("native quality requires only a live batch census and plan");
+  return Object.fromEntries(
+    names.map((name) => {
+      const field = Object.getOwnPropertyDescriptor(input, name);
+      if (!field?.enumerable || !("value" in field))
+        rrsiFail("native quality options cannot use accessors");
+      return [name, field.value];
+    }),
+  );
+}
+
+function same(left, right, label) {
+  if (rrsiCanonical(left) !== rrsiCanonical(right))
+    rrsiFail(`${label} changed`, "CC_RRSI_QUALITY_STALE");
+}
+
+// Hash every retained row field, including fields not used by the numerical
+// analysis. Missing children stay in the original authoritative denominator.
+function rowCensus(census) {
+  return census.batch.children.map((child) => {
+    const block = census.childEvidence(child.childId);
+    return {
+      childId: child.childId,
+      rowEvidenceDigest: block?.rowEvidenceDigest ?? null,
+      finalReceiptDigest: block?.finalReceiptDigest ?? null,
+      rowCount: block?.rows?.length ?? 0,
+      fullRowsDigest: block?.rows
+        ? rrsiHash(FULL_ROWS_DOMAIN, block.rows)
+        : null,
+    };
+  });
+}
+
+function makeReceipt(census, history, plan, report) {
+  const { batch, campaign, evidence } = census;
+  const receipt = rrsiEnvelope(
+    RRSI_NATIVE_QUALITY_RECEIPT_SCHEMA,
+    "qualityReceiptDigest",
+    {
+      assessmentKind: `${batch.stage}-required-quality`,
+      stage: batch.stage,
+      tenantId: campaign.tenantId,
+      goalId: campaign.goalId,
+      historyDescriptor: history.descriptor,
+      auditHead: evidence.auditHead,
+      campaignDigest: campaign.campaignDigest,
+      campaignRootDigest: evidence.campaignRootDigest,
+      batchDigest: batch.batchDigest,
+      queryId: batch.queryId,
+      candidate: batch.candidate,
+      versions: batch.versions,
+      nativeCandidateContents: batch.nativeCandidateContents,
+      parentIdentity: batch.parentIdentity,
+      targetIdentity: batch.targetIdentity,
+      lifecycleDigests: batch.lifecycleDigests,
+      nativeEvaluationPlanDigest: batch.nativeEvaluationPlanDigest,
+      evaluationMappingDigest: batch.evaluationMappingDigest,
+      nativeBatchEvidenceDigest: evidence.batchEvidenceDigest,
+      statisticsPlanDigest: plan.statisticsPlanDigest,
+      statisticsReportDigest: report.statisticsReportDigest,
+      statisticsRegistration: evidence.statisticsRegistration ?? null,
+      reservationRecord: evidence.reservationRecord,
+      fullRowCensusDigest: rrsiHash(ROW_CENSUS_DOMAIN, rowCensus(census)),
+      statisticalRowSetDigest: report.rowSetDigest,
+      plannedActorObservations: report.plannedActorObservations,
+      observedRowClaims: report.observedRowClaims,
+      missingActorObservations: report.missingActorObservations,
+      originalNativeGateVetoChildIds: evidence.nativeGateVetoChildIds,
+      budget: {
+        declaredBudgetSettlementComplete:
+          evidence.declaredBudgetSettlementComplete,
+        budgetOverrun: evidence.budgetOverrun,
+        allocationBinding: batch.batchDigest,
+        declaredAccountingOnly: true,
+      },
+      verifiedControlEvidence: {
+        originalHistoryJournalBound: true,
+        originalHistoryHeadReverified: true,
+        originalReceiptInventoryReverified: true,
+        signedReceiptFreshnessReverified: true,
+        allCohortInventoriesAuthenticated:
+          evidence.allCohortInventoriesAuthenticated,
+        presentedFinalReceiptRowsAuthenticated:
+          report.presentedFinalReceiptRowsAuthenticated,
+        completeSignedRows: evidence.completeSignedRows,
+        fullTriangleDenominatorRetained:
+          evidence.fullTriangleDenominatorRetained,
+        fullTriangleRowsPresent: report.fullTriangleRowsPresent,
+        controlledHistoryRegistrationOrderVerified:
+          report.controlledHistoryRegistrationOrderVerified === true,
+      },
+      unverifiedProductionPrerequisites: UNVERIFIED,
+      blockingReasons: [
+        ...new Set([...report.blockingReasons, ...REQUIRED_REASONS]),
+      ].sort(),
+      decision: "HOLD",
+      qualityVerdictVerified: false,
+      grantsFinalEvaluationAuthority: false,
+      grantsMutationOrDispatchAuthority: false,
+    },
+  );
+  snapshotRrsiData(receipt);
+  return receipt;
+}
+
+/** No report, verdict, verifier callback, or caller-supplied clock is accepted. */
+export async function buildRrsiNativeQualityReceipt(input) {
+  const options = ownOptions(input);
+  const census = captureRrsiNativeBatchEvidence(options.batchEvidence);
+  if (
+    !census.historyAdapter ||
+    typeof census.assertCurrentHistory !== "function"
+  )
+    rrsiFail("native quality requires census original History revalidation");
+  const history = captureRrsiHistoryLedgerAdapter(census.historyAdapter);
+  const assertHistory = census.assertCurrentHistory;
+  const plan = verifyRrsiNativeGroupStatisticsPlan(
+    snapshotRrsiData(options.plan),
+    { campaign: census.campaign, batch: census.batch },
+  );
+  if (!["selection", "generalization"].includes(census.batch.stage))
+    rrsiFail("native quality requires a selection or generalization batch");
+  await assertHistory(census.historyAdapter);
+  const rootResolution = history.resolveCampaignRoot();
+  const batchResolution = history.resolveNativeBatch({
+    batchDigest: census.batch.batchDigest,
+  });
+  const report = analyzeRrsiNativeBatchGroupStatistics({
+    batchEvidence: options.batchEvidence,
+    plan,
+  });
+  const receipt = makeReceipt(census, history, plan, report);
+  const receiptBytes = rrsiCanonical(receipt);
+  const reportBytes = rrsiCanonical(report);
+  await assertHistory(census.historyAdapter);
+  same(history.resolveCampaignRoot(), rootResolution, "quality History root");
+  same(
+    history.resolveNativeBatch({ batchDigest: census.batch.batchDigest }),
+    batchResolution,
+    "quality History batch",
+  );
+  census.assertCurrentFreshness();
+
+  let invalidated = false;
+  const captured = Object.freeze({
+    receipt,
+    receiptBytes,
+    statisticsReport: report,
+    statisticsReportBytes: reportBytes,
+    batchEvidence: options.batchEvidence,
+    plan,
+    campaign: census.campaign,
+    batch: census.batch,
+    historyLedger: history.ledger,
+    historyDescriptor: history.descriptor,
+    rootResolution,
+    batchResolution,
+    auditHead: receipt.auditHead,
+    // History calls this again under its write lock, after any expensive
+    // revalidation. A failed validity check cannot revive this live receipt.
+    assertCurrentFreshness() {
+      if (invalidated)
+        rrsiFail("quality receipt was invalidated", "CC_RRSI_QUALITY_STALE");
+      try {
+        return census.assertCurrentFreshness();
+      } catch (error) {
+        invalidated = true;
+        throw error;
+      }
+    },
+    async assertCurrentHistory(historyAdapter) {
+      const current = captureRrsiHistoryLedgerAdapter(historyAdapter);
+      if (current.ledger !== history.ledger)
+        rrsiFail("quality receipt belongs to another genuine History journal");
+      same(
+        current.descriptor,
+        history.descriptor,
+        "quality History descriptor",
+      );
+      if (invalidated)
+        rrsiFail("quality receipt was invalidated", "CC_RRSI_QUALITY_STALE");
+      try {
+        await assertHistory(historyAdapter);
+        same(
+          current.resolveCampaignRoot(),
+          rootResolution,
+          "quality History root",
+        );
+        same(
+          current.resolveNativeBatch({ batchDigest: census.batch.batchDigest }),
+          batchResolution,
+          "quality History batch",
+        );
+        const recheckedReport = analyzeRrsiNativeBatchGroupStatistics({
+          batchEvidence: options.batchEvidence,
+          plan,
+        });
+        if (rrsiCanonical(recheckedReport) !== reportBytes)
+          rrsiFail("quality original statistical report changed");
+        if (
+          rrsiCanonical(makeReceipt(census, current, plan, recheckedReport)) !==
+          receiptBytes
+        )
+          rrsiFail("quality original census or receipt changed");
+        await assertHistory(historyAdapter);
+        census.assertCurrentFreshness();
+        return receipt;
+      } catch (error) {
+        invalidated = true;
+        throw error;
+      }
+    },
+  });
+  RECEIPTS.set(receipt, captured);
+  return receipt;
+}
+
+/** JSON copies remain observations and cannot recover this live capability. */
+export function captureRrsiNativeQualityReceipt(receipt) {
+  const captured = RECEIPTS.get(receipt);
+  if (!captured)
+    rrsiFail("a live branded native required-quality receipt is required");
+  return captured;
+}