diff --git a/.github/workflows/hosted-math.yml b/.github/workflows/hosted-math.yml new file mode 100644 index 0000000..347ab5f --- /dev/null +++ b/.github/workflows/hosted-math.yml @@ -0,0 +1,61 @@ +name: Hosted mathematics + +on: + pull_request: + paths: + - '**.md' + - 'verification/hosted_math/**' + - '.github/workflows/hosted-math.yml' + +permissions: + contents: read + +concurrency: + group: hosted-math-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + capture: + if: github.event.pull_request.head.repo.full_name == github.repository + runs-on: ubuntu-24.04 + timeout-minutes: 20 + env: + CAPTURE_REVISION: ${{ github.event.pull_request.head.sha }} + steps: + - name: Check out the exact proposed source + uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + with: + ref: ${{ env.CAPTURE_REVISION }} + persist-credentials: false + - name: Set up Node + uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 + with: + node-version: '22' + - name: Install the capture runtime + run: | + npm install --prefix "$RUNNER_TEMP/math-runtime" playwright@1.56.1 mathjax-full@3.2.1 + node "$RUNNER_TEMP/math-runtime/node_modules/playwright/cli.js" install --with-deps chromium + - name: Check representative inline, display and table mathematics + run: | + export NODE_PATH="$RUNNER_TEMP/math-runtime/node_modules" + node verification/hosted_math/probe_hosted_math.cjs \ + --root "$GITHUB_WORKSPACE" --repository "$GITHUB_REPOSITORY" \ + --revision "$CAPTURE_REVISION" --page README.md \ + --output "$RUNNER_TEMP/hosted-probe" + - name: Compare every hosted mathematical expression + run: | + export NODE_PATH="$RUNNER_TEMP/math-runtime/node_modules" + node verification/hosted_math/capture_hosted_math.cjs \ + --root "$GITHUB_WORKSPACE" --repository "$GITHUB_REPOSITORY" \ + --revision "$CAPTURE_REVISION" --output "$RUNNER_TEMP/hosted-math" \ + --contract verification/hosted_math/math-contract.json + - name: Retain actual captures and comparison reports + if: always() + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + with: + name: hosted-math-${{ env.CAPTURE_REVISION }} + path: | + ${{ runner.temp }}/hosted-math + ${{ runner.temp }}/hosted-probe + if-no-files-found: error + retention-days: 14 diff --git a/README.md b/README.md index aafc527..b37bcb5 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,12 @@ Joint pair readout improves the last coefficient by exactly $`d+1`$. Collective These are **fixed-dimension high-precision limits**: first fix $`d`$ and $`v`$, then let the number $`N`$ of supplied pairs grow. The formulas do not establish a dimension-uniform finite-error sample advantage or a runtime crossover. The [model and theorem](science/model.md) give the precise measurement classes, estimator and limiting order. +## What survives without correspondence? + +The sister project [Quantum Learning Correspondence](https://github.com/GoGoKo699/Quantum-Learning-Correspondence) removes the input–output matching across a whole batch of the same demonstrations. Its exact kernel gives an information ceiling. The joint result goes further: as one anonymous batch grows at fixed dimension and visibility, **separate collective measurements of the two lists preserve all surviving statistical information asymptotically**. The full experiment becomes one classical Gaussian covariance observation. + +Read the [self-contained application](science/anonymous-batches.md) here and the [authoritative general proof in Correspondence](https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/8edc63836384745aee80101722255154e562af8f/science/separate-list-readout.md). Each side may retain its full list coherently, so this is different from the per-pair separable class in the table. The result proves uniform recovery and bounded-decision equivalence; it supplies no efficient receiver, convergence rate or automatic new precision coefficient for many growing batches. + ## Read the argument Start with the [scientific route](science/README.md). The account joins sharp measurement-information budgets to a global converse that permits biased, adaptive learners, and to actual attaining designs. @@ -34,6 +40,7 @@ Start with the [scientific route](science/README.md). The account joins sharp me | What is the optimum with separate-register measurements? | [Separable readout](science/separable_readout.md) | | What does one coherent pair buy? | [Joint-pair readout](science/joint_pair_readout.md) | | Why is the collective coefficient attainable without knowing the unitary? | [Collective attainment and localization](science/collective_attainment.md) | +| What survives a growing anonymous batch? | [Separate-list collective readout](science/anonymous-batches.md) | | What do the gains mean? | [Interpretation](science/interpretation.md) | | What must preparation, storage, control and output cost? | [Resources](science/resources.md) | | Which results are inherited? | [Related work](references/related_work.md) and [bibliography](references/references.bib) | @@ -42,7 +49,7 @@ For example, at $`d=2`$ and $`v=1/2`$, the three coefficients are $`5`$, $`12.5` ## Learn the framework -The [learning route](learning/README.md) connects the selected 2020 review by Demkowicz-Dobrzański, Górecki and Guţă to this experiment. Use the [30-milestone map](learning/MILESTONES.md), [source bridge](learning/ANCHOR_BRIDGE.md) and [worked tutorial](learning/TUTORIAL.md) to move from estimation concepts to the complete three-tier result. +The common educational source with Correspondence is **Dénes Petz, *Quantum Information Theory and Quantum Statistics* (2008)**. The [learning route](learning/README.md), [30-milestone map](learning/MILESTONES.md), [Petz bridge](learning/ANCHOR_BRIDGE.md) and [worked tutorial](learning/TUTORIAL.md) connect quantum statistical estimation, conditional expectations and sufficiency to the paired precision hierarchy and its anonymous-batch application. ## Reproduce the finite checks @@ -53,7 +60,7 @@ python3 verification/run_all.py The [verification guide](verification/README.md) explains the direct matrix, derivative, covariant-seed and group identities checked, together with their limits. Finite computations support the constructions; the written proofs establish the universal and asymptotic conclusions. -Faithful separable process probes, Werner-state quantum Fisher information, and coherent-readout advantages are established foundations. The contribution here is the sharp full-unitary three-tier learning comparison with matching acquisition schemes. This is a supplied-data experiment: the learner receives neither the hidden preparation record nor active access to the unknown unitary. +Faithful separable process probes, Werner-state quantum Fisher information, and coherent-readout advantages are established foundations. The contribution here is the sharp full-unitary three-tier learning comparison with matching acquisition schemes, together with its application of Correspondence’s general anonymous-batch sufficiency theorem. Shared theorem ownership and inherited tools are stated in the [related-work account](references/related_work.md). This is a supplied-data experiment: the learner receives neither the hidden preparation record nor active access to the unknown unitary. ## Purpose and contact diff --git a/learning/ANCHOR_BRIDGE.md b/learning/ANCHOR_BRIDGE.md index 816f3ad..97d9ce0 100644 --- a/learning/ANCHOR_BRIDGE.md +++ b/learning/ANCHOR_BRIDGE.md @@ -1,104 +1,69 @@ -# From multiparameter estimation to learning readout +# From Petz to precision and surviving information -The selected educational anchor is Rafał Demkowicz-Dobrzański, Wojciech Górecki and Mădălin Guţă, *Multi-parameter estimation beyond Quantum Fisher Information*, **Journal of Physics A: Mathematical and Theoretical 53**, 363001 (2020), [arXiv:2001.11742v2](https://arxiv.org/abs/2001.11742v2), revised 1 September 2020. The section and printed-page locations below refer to that 69-page version. [Published article](https://doi.org/10.1088/1751-8121/ab8ef3). +The selected educational anchor is **Dénes Petz, _Quantum Information Theory and Quantum Statistics_, first edition, copyright 2008, Springer**, [DOI:10.1007/978-3-540-74636-2](https://doi.org/10.1007/978-3-540-74636-2). The section locators below refer to that edition. They locate educational foundations; they do not imply that the book contains this project's precision hierarchy or the sister theorem about anonymous batches. -Use the review to understand the statistical distinctions; use the repository's scientific files for the source-specific theorems and proofs. The common thread is a learner that receives native quantum data, chooses a physically permitted readout, and returns a classical description of an unknown unitary. +The continuing experiment is a native quantum demonstration of an unknown unitary. Each input specimen is correlated with an output specimen, while the source withholds its preparation record. First retain their correspondence and vary the allowed readout. Then erase correspondence across a batch and ask how the surviving information can be extracted. -## A reading map +## A common source, two statistical questions -| Review location in v2 | Reading purpose | Project connection | +| Petz location | Reading purpose | Project connection | |---|---|---| -| Section 1.2, printed pp. 4–6 | Specify states, measurements, estimates and loss. | Read [the model](../science/model.md). Identify the supplied pair, the hidden unitary, the classical output and the gate loss before comparing readouts. | -| Sections 2.1–2.2, printed pp. 8–10 | Separate classical FI from SLD QFI. | A measurement produces a likelihood and a classical FI matrix. The model's $`jI_p`$ is the SLD matrix before a readout restriction is imposed. | -| Section 2.3, beginning on printed p. 11 | Introduce the Holevo optimization. | Follow the explicit dual-SLD substitution in [collective attainment](../science/collective_attainment.md#evaluation-of-the-holevo-value). | -| Section 2.6, printed pp. 15–16, especially Eq. (40) | Distinguish two commutation conditions. | Check zero mean commutators, rather than assuming the SLD operators commute. | -| Section 3.1, especially the example on printed pp. 23–25 | See a small model before the high-dimensional one. | Interpret a gap between a one-example measurement and a collective limit without changing the input source. | -| Section 4.5, printed pp. 43–45 | Track localization and an unknown center. | Read the project's pilot, clipping and diagonal argument. A local optimum by itself is not an unknown-unitary protocol. | -| Section 5.3, printed pp. 53–54 | Use covariance. | Verify that known rotations preserve SEP, PAIR and COLL and that Haar randomization makes the risk independent of the target. | -| Section 5.5, beginning on printed p. 57 | Allow biased estimators in a lower-bound argument. | The project's [global converse](../science/global_converse.md) uses its own group embedding and Haar integration by parts. | +| §§3.3–3.5 and §5.5 | Entropy, information quantities and Holevo information | Understand why a source-level information ceiling differs from a bound for one chosen measurement. The anonymous kernel controls the whole density operator before readout. | +| §§9.1–9.2 | Coarse-grainings and conditional expectations | Model a measurement, a forgotten permutation and a classical record as physical channels. Distinguish block pinching from the scalar conditional expectation used for separate-list reconstruction. | +| §9.5 | Sufficiency and recovery | Ask whether a parameter-independent reverse channel reconstructs a statistical experiment after readout. Translate exact sufficiency into the uniform asymptotic recovery statement proved for growing anonymous batches. | +| §§10.1–10.3 | State estimation and Fisher information | Interpret actual classical Fisher information, quantum information bounds and the precision of an estimated unitary. Keep this derivative-sensitive viewpoint distinct from bounded-risk equivalence in trace norm. | -This is a targeted route through one anchor, rather than a request to read the review consecutively. The project-specific learning sequence is organized in [the learning route](README.md). +No unverified book page or theorem number is required for this route. Use the linked scientific accounts for the additional hypotheses, normalizations and proofs specific to the experiment. -## Translate the notation first +## Translate the objects before comparing them -| Review notation or role | Project notation or role | Distinction to retain | +| Statistical object | Object in the paired experiment | Object after anonymous shuffling | |---|---|---| -| $`\rho_\theta`$ | $`\sigma_{U,v}`$ or $`\rho_U(v)`$ | The unknown varies along a unitary orbit; $`d`$ and $`v`$ are known. | -| $`\theta\in\mathbb R^p`$ | Local coordinates of $`U\in\mathrm{PU}(d)`$, with $`p=d^2-1`$ | A coordinate patch is not the whole global parameter space. Global phase is absent. | -| Number of copies, often $`n`$ | $`N`$ supplied pairs | In qubit examples, $`n=\log_2d`$ instead counts qubits. | -| Classical FI $`F`$ | Classical FI $`I(U)`$ | The project's $`F`$ is also the swap operator; context matters. | -| SLD QFI $`F_Q`$ | $`J=jI_p`$, $`j=2dv^2/(d+v)`$ | It bounds all readouts, but need not be attained by one allowed pair measurement. | -| Quadratic cost matrix $`C`$ | $`W=wI_p`$, $`w=d/(d+1)`$ | The project uses Haar-average gate infidelity. | -| A local Holevo value | $`C_H(W)`$ | Its equality to a global risk coefficient needs an attainment and globalization proof. | -| Covariance matrix of an estimate | Mean local squared error | The main minimax problem also permits biased estimators. | -| A qubit Bloch radius | The project's visibility $`v`$ or risks $`r_N`$ | These symbols describe different quantities; qubit example formulas are not the project's theorem. | +| Parameter | $`U\in\mathrm{PU}(d)`$, with global phase removed | The same $`U`$, entering the correlation matrix $`T(U)`$ | +| Supplied state | $`\rho_{U,v}^{\otimes N}`$ with identified pairs | $`\Omega_{b,v}(U)`$ on two distinguishable lists, with one hidden output permutation | +| Coarse-graining | A permitted SEP, PAIR or COLL readout | The anonymous acquisition channel, then a readout of the received lists | +| Classical record | Measurement outcomes and a unitary estimate | Two local collective-measurement labels combined classically | +| Performance statement | Exact fixed-$`d,v`$ coefficient of gate-infidelity risk | Uniform reconstruction error tending to zero, hence all bounded decision risks preserved | +| Recovery | Estimation does not generally reconstruct the supplied pairs | A target-independent product preparation channel approximately reconstructs the anonymous state | -## Start with the source and the returned model +Here SEP means a separable-effect measurement on each identified pair, with classical-only memory between pairs. A separate-list measurement may couple all $`A`$ specimens coherently and all $`B`$ specimens coherently. It belongs to a different access model; the old SEP converse cannot be applied to it by changing notation. -One example is the two-register state +## Start with the paired source and loss -```math -\sigma_{U,v} -=\frac{I+vF_U}{d(d+v)}, -\qquad -F_U=(I\otimes U)F(I\otimes U^\dagger). -``` - -The source can generate it using product pure states with hidden random preparation records. Each marginal is $`I/d`$, so neither register alone identifies $`U`$. Correlations carry the parameter. The output is a reusable classical estimate $`\widehat U`$, evaluated using +One supplied example is ```math -\ell(U,\widehat U) -=\frac{d^2-|\mathrm{Tr}(\widehat U^\dagger U)|^2}{d(d+1)}. +\rho_{U,v}=\frac{I+vF_U}{d(d+v)},\qquad +F_U=(I\otimes U)F(I\otimes U^\dagger). ``` -This makes the estimation concepts concrete. There is one fixed unknown transformation, many independently prepared examples, and a specified loss for future predictions. It is not a task of returning one stored example as a quantum hypothesis. - -## Follow the three proof moves - -**First, hold the readout permission fixed.** SEP allows a separable-effect measurement on each pair, including local operations and classical communication. PAIR allows any measurement on one pair. Both retain only classical information between examples and allow adaptation to the complete earlier transcript. COLL allows a joint measurement across different examples. A causal A-before-B receiver belongs to SEP and already attains its coefficient. A measurement that stores many A registers and is separable only across the large $`A^{\otimes N}:B^{\otimes N}`$ split belongs to a different class. - -**Second, calculate the information allowed by that permission.** The separate derivations in [separable readout](../science/separable_readout.md) and [joint-pair readout](../science/joint_pair_readout.md) give sharp Fisher-trace budgets. The [global converse](../science/global_converse.md) converts those budgets into a risk bound for arbitrary biased adaptive learners. This step is necessary: inserting an unrestricted QFI matrix would erase the restriction being studied. - -**Third, establish attainability at an unknown target.** For COLL, the source has SLDs $`L_a=-iv[I\otimes T_a,F]`$ at identity and +Both local states are $`I/d`$; the parameter is in the correlations. The learner returns a classical estimate $`\widehat U`$, scored by ```math -\mathrm{Tr}(\rho L_aL_b)=j\delta_{ab}, -\qquad -\mathrm{Tr}(\rho[L_a,L_b])=0. +\ell(U,\widehat U)= +\frac{d^2-|\mathrm{Tr}(\widehat U^\dagger U)|^2}{d(d+1)}. ``` -The choice $`X_a=L_a/j`$ in the Holevo optimization has real covariance. It gives - -```math -C_H(wI_p)=\frac{wp}{j} -=\frac{p(d+v)}{2v^2(d+1)}. -``` +At fixed $`d\ge2`$ and $`0\lt v\lt1`$, the [model](../science/model.md) gives the exact precision coefficients. Petz's estimation framework helps formulate the problem, but the three sharp measurement-information budgets and their attaining designs are source-specific calculations. The [global converse](../science/global_converse.md) allows biased adaptive learners; the [collective proof](../science/collective_attainment.md) separately establishes attainment at an unknown target. -The SLDs still need not commute. The value is a collective asymptotic benchmark, not a simultaneous one-pair measurement prescription. The project's [collective proof](../science/collective_attainment.md) uses the precise local theorem in its references and then supplies the required global construction for this full-rank orbit with repeated eigenvalues. +The multiparameter review of Demkowicz-Dobrzański, Górecki and Guţă, [arXiv:2001.11742v2](https://arxiv.org/abs/2001.11742v2), remains a supplementary specialist reference for the SLD/Holevo framework. The selected common educational source is Petz. The precise local attainment theorem used by the proof is identified in the scientific account; it is not silently attributed to the book or review. -## Read the final coefficients with their quantifiers +## Then ask for recovery of the anonymous experiment -For every fixed $`d\ge2`$ and fixed known $`0\lt v\lt 1`$, +Let $`M_b=M_b^A\otimes M_b^B`$ be separate collective measurements of the two lists and $`R_b=R_b^A\otimes R_b^B`$ prepare normalized local spectral projectors from their classical labels. The [anonymous-batch application](../science/anonymous-batches.md) states ```math -\begin{aligned} -\lim_{N\to\infty}N r_N^{\mathrm{COLL}} -&=\frac{p(d+v)}{2v^2(d+1)},\\ -\lim_{N\to\infty}N r_N^{\mathrm{PAIR}} -&=\frac{p(d+v)^2}{2v^2(d+1)},\\ -\lim_{N\to\infty}N r_N^{\mathrm{SEP}} -&=\frac{p(d+v)^2}{2v^2}. -\end{aligned} +\sup_U\Vert \Omega_{b,v}(U)-R_bM_b(\Omega_{b,v}(U))\Vert _1\longrightarrow0. ``` -Haar Bayes and worst-case minimax risks agree for these classes by covariance. The coefficients show a factor $`d+1`$ from permitting joint readout within a pair and a further factor $`d+v`$ from permitting collective readout across pairs. +This is the relevant asymptotic sufficiency statement: every bounded decision rule on the original anonymous batch can be simulated from the two classical records with a vanishing score change. A coherent processor consuming the data for one later prediction is also covered by channel contractivity. One anonymous batch still has bounded information; reconstruction does not recreate the lost source correspondence. -Only after taking the fixed-dimension limit may their dimension dependence be compared. The proof does not provide a dimension-uniform threshold for reaching these precision coefficients, a polynomial-time collective learner, or a finite-accuracy runtime advantage. The [resource account](../science/resources.md) keeps source count, retention, synthesis, fitting and the classical output separate. +A joint spectral projector can have rank greater than one. Ordinary block pinching leaves a quantum state inside each block. The scalar conditional expectation replaces that block by its normalized identity and is implemented by measurement followed by preparation. This is the channel needed for a fully classical record. -## What comes from the anchor, and what must be proved here +## What the project must supply beyond the book -The review provides the estimation framework and the route among SLD, Holevo, QLAN and Bayesian viewpoints. It does not contain this supplied source's three sharp constrained coefficients, the complete adaptive-transcript converse, or its optimal readout constructions. Those are the project's specialist calculations. +The general theorem and authoritative proof are owned by Quantum Learning Correspondence. Its exact anonymous collision kernel supplies a limiting squared likelihood norm. The corresponding Gaussian covariance likelihood has exactly the same norm. Bounded local Fourier observables therefore approximate the entire likelihood rather than merely matching its covariance. Glebsky's inherited finite-family theorem then turns asymptotically commuting local Fourier operators into genuine commuting local measurements. A reference-coupling argument supplies two-way equivalence with the Gaussian covariance experiment. -It also does not remove the need to check the hypotheses of a cited attainment theorem. This source has repeated eigenvalues. The collective account identifies the local theorem actually used and distinguishes it from global results stated only for nondegenerate spectra. Likewise, a Bayesian perspective permits biased estimators, but a local-unbiased inequality alone does not establish the project's global lower bound. +These are additional proof steps. Ordinary local iid estimation results do not automatically construct a separate-list receiver for a globally indexed covariance family. Likewise, trace-norm recovery does not imply Fisher-information convergence, exact high-precision coefficients or a bound uniform in growing dimension. The [tutorial](TUTORIAL.md) works through the qubit normalization, the norm-saturation mechanism and the batch-count limit explicitly. -The bridge is complete when the same question can be followed through all three languages: the physical receiver's memory permissions, the resulting information budget, and the attained risk for a classical unitary model. +The bridge is complete when one can distinguish three resources in the same source: readout permissions while correspondence is supplied, the correspondence removed by acquisition, and coherent collective processing retained inside each anonymous list. diff --git a/learning/MILESTONES.md b/learning/MILESTONES.md index 634b115..2eca2ea 100644 --- a/learning/MILESTONES.md +++ b/learning/MILESTONES.md @@ -1,252 +1,250 @@ -# Thirty milestones for the readout hierarchy +# Thirty milestones for precision and surviving information -This is a common map of the project's scientific story. It contains exactly thirty understanding targets, M01–M30. It does not prescribe a coaching or assessment procedure. +This project-intrinsic map contains exactly thirty understanding targets, M01–M30. The selected common educational anchor is **Dénes Petz, _Quantum Information Theory and Quantum Statistics_, first edition (2008)**, [publisher record](https://doi.org/10.1007/978-3-540-74636-2). The [anchor bridge](ANCHOR_BRIDGE.md) identifies verified section connections and additional project-specific proof tools; a source pointer does not attribute a new theorem to the book. -The selected educational anchor is **Rafał Demkowicz-Dobrzański, Wojciech Górecki and Mădălin Guţă, _Multi-parameter estimation beyond Quantum Fisher Information_, arXiv:2001.11742v2 (2020)**. Its [versioned primary record](https://arxiv.org/abs/2001.11742v2) supplies the review and its 69-page PDF. Section pointers below refer to that version. The [anchor bridge](ANCHOR_BRIDGE.md) translates its notation and identifies the additional project-specific arguments. A framework pointer does not imply that the review contains this project's source construction or sharp readout laws. +The allocation is **10 background/preliminaries milestones and 20 narrative/innovation milestones**. The background builds a precise statistical experiment from specimens, access, measurements and loss. The narrative first closes the paired precision hierarchy, then changes acquisition by erasing correspondence and follows the surviving information through a complete separate-list receiver and Gaussian equivalence. Each phase progresses from local objects to the global account. The map contains no personal learner state or assessment procedure. -The allocation is **12 background/preliminaries milestones and 18 narrative/innovation milestones**. The background assembles a well-posed estimation problem from individual specimens, measurements and loss. The longer narrative follows three distinct information ceilings, their attaining measurements, and the global arguments needed to turn local precision into a complete learning theorem. Each phase moves from individual objects and mechanisms to an integrated account. +## Background/preliminaries — M01–M10 -## Background/preliminaries — M01–M12 +### M01 — Specimens and sample boundaries -### M01 — What counts as one example? +- **Central question:** What is supplied as one example? +- **Understanding target:** Distinguish one register, one identified input–output pair, and a batch of pairs; count source copies before imposing a readout restriction. +- **Dependencies and story role:** None; this fixes the physical unit used throughout. +- **Conceptual connection:** Data counts follow physical specimen boundaries. +- **Source pointers:** Petz §§10.1–10.3; [supplied examples](../science/model.md#the-supplied-examples). -- **Central question:** Which physical systems arrive together, and what does one sample count? -- **Understanding target:** Distinguish one $`d`$-dimensional register, one $`A:B`$ example pair, and a collection of independent pairs. -- **Dependencies and story role:** None. This fixes the local unit whose readout and storage will later be restricted. -- **Conceptual connection:** A statistical sample must be tied to a physical specimen boundary. -- **Source pointers:** Anchor §1.2; [supplied examples](../science/model.md#the-supplied-examples), [quantum retention](../science/resources.md#quantum-retention). +### M02 — An unknown transformation in a relation -### M02 — A unitary hidden in a relation +- **Central question:** What does a native quantum demonstration reveal without its preparation seed? +- **Understanding target:** Separate the fixed target unitary from fresh random input orientations and distinguish supplied specimens from chosen-input target queries. +- **Dependencies and story role:** M01; identifies the parameter and unavailable information. +- **Conceptual connection:** Input control and classical side information are part of the statistical model. +- **Source pointers:** [Access model](../science/model.md#the-supplied-examples); [preparation records](../science/interpretation.md#the-preparation-record-is-a-resource). -- **Central question:** What is unknown when a source supplies an input–output relation but withholds its preparation record? -- **Understanding target:** Explain the fixed target $`U`$, fresh nuisance input states, and the difference between passive copies and chosen-input unitary access. -- **Dependencies and story role:** M01. It identifies what an individual example demonstrates. -- **Conceptual connection:** Quantum learning here is estimation of a supplied state family, rather than optimization over freely chosen probes. -- **Source pointers:** Anchor §§1.1–1.2; [source and access model](../science/model.md#the-supplied-examples), [preparation record](../science/interpretation.md#the-preparation-record-is-a-resource). +### M03 — Separable preparation and hidden correlations -### M03 — Product preparation and informative correlations +- **Central question:** How can two uninformative marginals contain an informative relation? +- **Understanding target:** Verify that both marginals are maximally mixed while the pair depends on the target; distinguish separable preparation from restrictions on measurement effects. +- **Dependencies and story role:** M01–M02; locates the signal before choosing a readout. +- **Conceptual connection:** Information can reside in correlations even when neither marginal carries it. +- **Source pointers:** Petz §§3.3–3.5; [source mixture](../science/model.md#the-supplied-examples). -- **Central question:** Can unentangled examples carry information unavailable in either register separately? -- **Understanding target:** Distinguish separable preparation from a product density operator, and verify why both marginals reveal no target information. -- **Dependencies and story role:** M01–M02. It locates the signal in the relation between the two arrivals. -- **Conceptual connection:** Preparation entanglement and measurement entanglement are different resources. -- **Source pointers:** Anchor §1.2; [source mixture](../science/model.md#the-supplied-examples), [separability and readout](../science/interpretation.md#why-separability-does-not-settle-the-issue). +### M04 — Visibility and the swap model -### M04 — Visibility creates a regular state family +- **Central question:** How does the physical ensemble produce a regular state family? +- **Understanding target:** Connect the two-design second moment, swap operator, visibility and symmetric/antisymmetric eigenvalues; retain the full-rank condition for the paired precision theorem. +- **Dependencies and story role:** M02–M03; assembles the supplied density operator. +- **Conceptual connection:** Physical mixing and statistical regularity are different roles of one visibility parameter. +- **Source pointers:** [Model and spectrum](../science/model.md#the-supplied-examples); [source costs](../science/resources.md#preparing-the-native-demonstrations). -- **Central question:** How do hidden shared seeds and independent mixing produce the stated full-rank model? -- **Understanding target:** Connect the projective 2-design second moment, swap operator, visibility $`v`$, and two positive eigenvalues. -- **Dependencies and story role:** M02–M03. It combines the preparation ingredients into one density operator. -- **Conceptual connection:** A physical noise parameter can also determine which statistical regularity theorem applies. -- **Source pointers:** Anchor §1.2; [supplied examples and spectrum](../science/model.md#the-supplied-examples), [native source preparation](../science/resources.md#preparing-the-native-demonstrations). +### M05 — Unitary geometry and global phase -### M05 — Count physical unitary directions +- **Central question:** Which real directions must a complete learned unitary resolve? +- **Understanding target:** Remove global phase, obtain the dimension of the projective-unitary target, and use consistently normalized traceless Hermitian generators. +- **Dependencies and story role:** M02, M04; supplies local coordinates without replacing the global parameter space. +- **Conceptual connection:** Gauge freedom must be removed before comparing information matrices. +- **Source pointers:** Petz §§10.1–10.3; [normalizations](../science/model.md#the-constants); [adjoint embedding](../science/global_converse.md#1-a-phase-insensitive-embedding). -- **Central question:** Why does a complete unitary have $`p=d^2-1`$ relevant real directions? -- **Understanding target:** Remove global phase and track the normalization of traceless Hermitian tangent generators. -- **Dependencies and story role:** M02, M04. This provides coordinates for local calculations without changing the global target space. -- **Conceptual connection:** Gauge freedom must be removed before comparing Fisher matrices or precision constants. -- **Source pointers:** Anchor §1.2; [parameter and normalization](../science/model.md#the-constants), [phase-insensitive representation](../science/global_converse.md#1-a-phase-insensitive-embedding). +### M06 — Gate loss and the returned model -### M06 — Specify success before precision +- **Central question:** What is an accurate reusable classical estimate? +- **Understanding target:** Distinguish average gate infidelity, process loss and the local quadratic cost; tie every claimed coefficient to the same operational output and loss. +- **Dependencies and story role:** M01–M05; defines success before measuring information. +- **Conceptual connection:** The loss fixes the meaning of a precision coefficient. +- **Source pointers:** Petz §§10.1–10.3; [returned estimate and loss](../science/model.md#what-the-learner-returns). -- **Central question:** What does an accurate learned unitary mean in this task? -- **Understanding target:** Distinguish Haar-average gate infidelity, process loss, and local squared coordinate error. -- **Dependencies and story role:** M01–M05. It connects a reusable classical estimate to its operational test criterion. -- **Conceptual connection:** A cost matrix is induced by the chosen loss; it cannot be replaced by an arbitrary parameter norm. -- **Source pointers:** Anchor §1.2; [returned model and loss](../science/model.md#what-the-learner-returns), [local loss weight](../science/collective_attainment.md#the-local-information-matrix). +### M07 — Measurements and retained records -### M07 — A measurement creates a classical record +- **Central question:** How does readout change what later processing can use? +- **Understanding target:** Specify normalized POVMs, classical outcomes and quantum memory; distinguish per-pair SEP, PAIR and unrestricted collective processing. +- **Dependencies and story role:** M01–M04; gives the first three physically meaningful permissions. +- **Conceptual connection:** Quantum retention changes the permitted channel from data to record. +- **Source pointers:** Petz §§9.1–9.2; [readout classes](../science/model.md#the-readout-classes). -- **Central question:** How do POVM effects determine what is retained after quantum data are measured? -- **Understanding target:** Read outcome probabilities from the state and effects, and distinguish a normalized POVM from a postselected test. -- **Dependencies and story role:** M01–M04. It defines the local information-extraction operation. -- **Conceptual connection:** Converting a specimen into a classical outcome imposes a physical boundary on later processing. -- **Source pointers:** Anchor §1.2; [readout classes](../science/model.md#the-readout-classes), [actual normalized operations](../science/resources.md#a-normalized-povm-is-an-actual-operation). +### M08 — Classical and quantum information budgets -### M08 — Scores and simultaneous information +- **Central question:** How do simultaneous parameter directions constrain precision? +- **Understanding target:** Interpret scores, classical Fisher matrices and the SLD upper bound; explain why a trace ceiling needs an isotropic attaining design. +- **Dependencies and story role:** M05–M07; provides common quantities for the paired comparison. +- **Conceptual connection:** Simultaneous learning requires more than optimizing one parameter direction. +- **Source pointers:** Petz §§10.1–10.3; [information constants](../science/model.md#the-constants); [SLD calculation](../science/collective_attainment.md#the-local-information-matrix). -- **Central question:** How is sensitivity to many unitary directions summarized by one measurement? -- **Understanding target:** Interpret the classical score, Fisher matrix, its trace, and why trace optimality alone does not ensure isotropic precision. -- **Dependencies and story role:** M05–M07. It supplies the common language for comparing readout ceilings. -- **Conceptual connection:** Multi-parameter learning requires accounting for all relevant directions at once. -- **Source pointers:** Anchor §2.1; [SEP tangent responses](../science/separable_readout.md#2-sum-the-tangent-responses), [model constants](../science/model.md#the-constants). +### M09 — Coarse-graining and statistical sufficiency -### M09 — Quantum information is a bound on readout +- **Central question:** When does a classical record retain a whole experiment? +- **Understanding target:** Express a readout or lost permutation as a channel; define target-independent measurement and reconstruction and distinguish exact sufficiency from vanishing-error asymptotic recovery. +- **Dependencies and story role:** M07; establishes the language needed after correspondence is erased. +- **Conceptual connection:** A sufficient record preserves an experiment through a reverse physical channel. +- **Source pointers:** Petz §§9.1–9.2, 9.5; [anonymous-batch application](../science/anonymous-batches.md). -- **Central question:** What does the SLD quantum Fisher matrix say before a measurement is chosen? -- **Understanding target:** Explain the relation between an actual classical Fisher matrix and the state's SLD information. -- **Dependencies and story role:** M07–M08. It introduces the unrestricted information benchmark. -- **Conceptual connection:** State distinguishability bounds measurement performance but need not identify a simultaneous attaining measurement. -- **Source pointers:** Anchor §2.2; [local SLD matrix](../science/collective_attainment.md#the-local-information-matrix). +### M10 — Global risk and ordered limits -### M10 — Compatibility is more than operator commutation +- **Central question:** What is needed beyond a local information formula? +- **Understanding target:** Allow biased adaptive estimators; distinguish local bounds, unknown-center attainment, fixed-dimension precision limits and uniform bounded-decision comparisons. +- **Dependencies and story role:** M05–M09; prepares both branches of the scientific story. +- **Conceptual connection:** Derivative-sensitive precision and bounded-decision convergence have different quantifiers. +- **Source pointers:** Petz §§10.1–10.3; [risk and limiting order](../science/model.md#risk-and-limiting-order). -- **Central question:** Why are Holevo bounds and collective limits needed beyond QFI? -- **Understanding target:** Separate noncommuting SLD operators, zero mean commutators, equality of bounds, and physical attainability. -- **Dependencies and story role:** M08–M09. It prevents the collective benchmark from being mistaken for a single-pair protocol. -- **Conceptual connection:** A local matrix bound and an asymptotic measurement capability are distinct statements. -- **Source pointers:** Anchor §§2.3, 2.6, 2.10–2.11; [Holevo evaluation](../science/collective_attainment.md#evaluation-of-the-holevo-value). +## Narrative/innovation — M11–M30 -### M11 — Local precision and global risk +### M11 — The sharp separable-effect ceiling -- **Central question:** How do locally centered estimation, Haar Bayes risk, and worst-case risk differ? -- **Understanding target:** Recognize why a known-center bound does not by itself solve an unknown-center problem, and how symmetry can relate global criteria. -- **Dependencies and story role:** M05–M10. It assembles the statistical viewpoints needed for the final theorem. -- **Conceptual connection:** Covariance removes an arbitrary preferred target, while globalization must still be proved. -- **Source pointers:** Anchor §§4.5–4.6.4, 5.3, 5.5; [risk and limiting order](../science/model.md#risk-and-limiting-order). +- **Central question:** What limits every permitted separable measurement on one pair? +- **Understanding target:** Refine effects to product terms and use positivity, completeness and concavity to obtain the exact SEP Fisher-trace ceiling. +- **Dependencies and story role:** M03–M08; proves the first constrained converse. +- **Conceptual connection:** Completeness couples the contributions of all measurement effects. +- **Source pointers:** [Separable readout](../science/separable_readout.md#the-sharp-one-pair-ceiling). -### M12 — State the complete comparison +### M12 — A causal readout that attains SEP -- **Central question:** Which assumptions remain fixed when the three readouts are compared? -- **Understanding target:** State the same source, unitary output, loss, visibility, and sample count for SEP, PAIR and COLL, with $`N\to\infty`$ taken at fixed $`d,v`$. -- **Dependencies and story role:** M01–M11. This is the background synthesis: a complete comparison problem rather than three unrelated protocols. -- **Conceptual connection:** A resource hierarchy is meaningful only after the task and limiting convention are shared. -- **Source pointers:** Anchor §§1.2, 4.5; [complete model](../science/model.md), [interpretation](../science/interpretation.md). +- **Central question:** Can the separable ceiling be met by a complete physical protocol? +- **Understanding target:** Use a shared random basis and Fourier-related second basis, include all outcomes, and explain the diluted conditional state of the output. +- **Dependencies and story role:** M11; matches the first converse with a causal design. +- **Conceptual connection:** An attaining causal protocol can saturate a broader measurement-class converse. +- **Source pointers:** [Local attaining measurement](../science/separable_readout.md#3-a-local-product-measurement-attains-the-ceiling); [conditional state](../science/separable_readout.md#4-what-measuring-the-first-register-does). -## Narrative/innovation — M13–M30 +### M13 — Joint readout of an identified pair -### M13 — Read the response of one product effect +- **Central question:** What additional precision is available inside one pair? +- **Understanding target:** Derive the PAIR trace ceiling from the exchange sectors and explain how an entangled seed reaches it for all unitary directions. +- **Dependencies and story role:** M04, M08, M11; separates pair coherence from separable readout. +- **Conceptual connection:** Measurement entanglement and source entanglement are distinct resources. +- **Source pointers:** [Joint-pair ceiling](../science/joint_pair_readout.md#sharp-information-ceiling); [attaining seed](../science/joint_pair_readout.md#a-normalized-attaining-measurement). -- **Central question:** How does a single separable measurement effect respond to a small unitary change? -- **Understanding target:** Reduce its likelihood to a squared overlap and explain why the total tangent response is proportional to $`t(1-t)`$. -- **Dependencies and story role:** M05, M07–M08, M12. This starts the new argument with one local effect. -- **Conceptual connection:** Generator completeness converts many derivative components into one geometric overlap. -- **Source pointers:** Anchor §2.1 as framework; [product-effect refinement](../science/separable_readout.md#1-refine-to-product-effects), [response identity](../science/separable_readout.md#2-sum-the-tangent-responses). +### M14 — Count a normalized measurement -### M14 — Completeness limits every separable readout +- **Central question:** Why is a seed or selected success event insufficient? +- **Understanding target:** Normalize the covariant POVM, obtain a finite design realization, and count settings, outcomes and synthesis rather than assuming that one favorable test is free. +- **Dependencies and story role:** M12–M13; turns information saturation into an actual operation. +- **Conceptual connection:** Normalization and all-outcome accounting make a statistical design physically meaningful. +- **Source pointers:** Petz §§9.1–9.2; [finite realization](../science/joint_pair_readout.md#finite-realization-and-its-resource-meaning). -- **Central question:** Why can no rearrangement of separable effects exceed the SEP Fisher budget? -- **Understanding target:** Combine POVM completeness, its fixed mean overlap, concavity, and refinement monotonicity into the sharp ceiling. -- **Dependencies and story role:** M13. It passes from one effect to every allowed one-pair separable measurement. -- **Conceptual connection:** Normalization is an information constraint, not just a consistency check. -- **Source pointers:** Anchor §2.1 as framework; [sharp SEP proof](../science/separable_readout.md#2-sum-the-tangent-responses). +### M15 — The collective information matrix -### M15 — A simple local measurement meets the ceiling +- **Central question:** What can all the supplied pairs contain before readout? +- **Understanding target:** Differentiate the orbit state, verify the SLD equation and compute the complete complex SLD Gram matrix with the stated generator normalization. +- **Dependencies and story role:** M04–M08; supplies the unrestricted paired benchmark. +- **Conceptual connection:** The same source admits different information extraction depending on retained coherence. +- **Source pointers:** [Local SLD matrix](../science/collective_attainment.md#the-local-information-matrix). -- **Central question:** Can the SEP ceiling be attained without within-pair communication or postselection? -- **Understanding target:** Explain the shared 2-design basis and Fourier-related basis, equal overlaps, and isotropic Fisher matrix at a known center. -- **Dependencies and story role:** M14. It completes the first local optimization with an actual normalized measurement. -- **Conceptual connection:** Mutually unbiased bases meet the scalar equality condition; design symmetry distributes precision over all directions. -- **Source pointers:** Anchor §2.1 for centered estimation; [attaining product design](../science/separable_readout.md#3-a-local-product-measurement-attains-the-ceiling). +### M16 — Compatibility and the Holevo value -### M16 — Joint effects mix exchange sectors +- **Central question:** Why does a collective limit exceed every one-pair measurement? +- **Understanding target:** Distinguish operator commutation from zero mean commutators; evaluate the Holevo objective with dual SLDs without claiming a simultaneous one-pair attainer. +- **Dependencies and story role:** M10, M15; identifies the local collective optimum and its scope. +- **Conceptual connection:** Vanishing expected commutators permits a collective limit without operator commutation. +- **Source pointers:** Petz §§10.1–10.3 as estimation background; [Holevo evaluation](../science/collective_attainment.md#evaluation-of-the-holevo-value) and its specialist references. -- **Central question:** What extra response becomes available when the two registers can be measured together? -- **Understanding target:** Decompose a rank-one joint effect into symmetric and antisymmetric components and identify the cross-sector derivative. -- **Dependencies and story role:** M04–M05, M08, M15. It introduces the mechanism behind the next readout tier. -- **Conceptual connection:** Joint readout probes a coherence between exchange sectors that product effects cannot use equally well. -- **Source pointers:** Anchor §§2.1–2.2 as framework; [joint-effect decomposition](../science/joint_pair_readout.md#sharp-information-ceiling). +### M17 — A converse for biased adaptive learners -### M17 — Derive the sharp joint-pair ceiling +- **Central question:** How does a local information ceiling bound global learning risk? +- **Understanding target:** Use the phase-insensitive adjoint embedding and Haar integration by parts, then retain the Fisher budgets under complete adaptive histories and collective readout. +- **Dependencies and story role:** M10–M16; establishes a valid global lower bound for each class. +- **Conceptual connection:** A global integration identity can constrain learners without differentiating their estimates. +- **Source pointers:** [Global converse](../science/global_converse.md); [adaptive budgets](../science/global_converse.md#5-why-the-fisher-budgets-apply-to-adaptive-and-collective-protocols). -- **Central question:** What prevents an arbitrary joint-pair measurement from reaching the collective benchmark? -- **Understanding target:** Connect paired singular values of an antisymmetric coefficient matrix, the gradient norm bound, and completeness-fixed sector weights. -- **Dependencies and story role:** M16. It turns the local exchange-sector mechanism into a ceiling for every pair POVM. -- **Conceptual connection:** Matrix structure and POVM concavity impose a simultaneous-measurement tradeoff. -- **Source pointers:** Anchor §§2.3, 2.10 for the comparison framework; [antisymmetric estimate](../science/joint_pair_readout.md#the-antisymmetric-matrix-estimate), [completeness step](../science/joint_pair_readout.md#completeness-fixes-the-optimal-mixture). +### M18 — Attainment at an unknown target -### M18 — Normalize the optimal joint-pair seed +- **Central question:** How is the privileged coordinate center removed? +- **Understanding target:** Count the pilot, counterrotate by known estimated controls, and control compact local risks and pilot-error second moments with the correct local theorem hypotheses. +- **Dependencies and story role:** M12–M17; matches the global converses without knowing the unitary. +- **Conceptual connection:** An unknown-center theorem must count calibration errors and the pilot budget. +- **Source pointers:** [SEP globalization](../science/separable_readout.md#5-global-fixed-dimensional-attainability); [collective localization](../science/collective_attainment.md#a-global-pilot-with-exponential-tails). -- **Central question:** Which joint measurement attains the pair ceiling in every direction? -- **Understanding target:** Explain the two-sector seed, its covariant twirl, equality in the matrix bound, and adjoint-isotropic Fisher information. -- **Dependencies and story role:** M17. It completes the second local optimization with a normalized POVM. -- **Conceptual connection:** An orbit of locally optimal effects must also resolve the identity to define a valid measurement. -- **Source pointers:** Anchor §5.3 as a symmetry connection; [attaining covariant measurement](../science/joint_pair_readout.md#a-normalized-attaining-measurement). +### M19 — The complete paired precision hierarchy -### M19 — An attaining POVM must count all outcomes +- **Central question:** What do the three exact coefficients establish together? +- **Understanding target:** Recover the successive factors from joint-pair and cross-example coherence; explain Haar/minimax equality and the fixed-dimension order of limits. +- **Dependencies and story role:** M11–M18; closes the original paired comparison before changing acquisition. +- **Conceptual connection:** Two coherent-readout resources give two distinct precision gains. +- **Source pointers:** [The exact constants](../science/model.md#the-constants); [interpretation](../science/interpretation.md#three-different-opportunities-to-measure). -- **Central question:** How can the covariant pair measurement be a physical operation without discarding most examples? -- **Understanding target:** Distinguish a finite-design normalized frame and its Naimark realization from random binary testing followed by successful-outcome selection. -- **Dependencies and story role:** M07, M18. It connects the ideal local optimum to a complete measurement account. -- **Conceptual connection:** Sample optimality survives a normalized dilation, but does not supply cheap gate synthesis. -- **Source pointers:** Anchor §1.2 for POVM normalization; [finite realization](../science/joint_pair_readout.md#finite-realization-and-its-resource-meaning), [resource distinction](../science/resources.md#a-normalized-povm-is-an-actual-operation). +### M20 — Erase correspondence and change the class -### M20 — Compute the collective information matrix +- **Central question:** What is the receiver allowed after the shuffle? +- **Understanding target:** Define the anonymous state, withheld records and separate collective list measurements; explain why the old per-pair SEP converse does not address this class. +- **Dependencies and story role:** M07, M09, M19; opens the complementary acquisition question. +- **Conceptual connection:** Acquisition loss and readout restriction change different parts of the experiment. +- **Source pointers:** Petz §§9.1–9.2; [anonymous-batch model](../science/anonymous-batches.md#the-source-and-the-two-readout-interfaces). -- **Central question:** What information remains in the source before any pair has been converted to a classical record? -- **Understanding target:** Reconstruct the SLDs, the scalar $`j`$, and the real complex Gram matrix for all unitary tangents. -- **Dependencies and story role:** M09–M10, M16–M18. It places the two measurement ceilings beside the source's collective benchmark. -- **Conceptual connection:** A fixed separable source can retain multiparameter information inaccessible to any single-pair classical record. -- **Source pointers:** Anchor §§2.2, 2.6; [collective local matrix](../science/collective_attainment.md#the-local-information-matrix). +### M21 — The exact anonymous kernel and ceiling -### M21 — Evaluate the Holevo value and its local meaning +- **Central question:** Why does one large anonymous batch retain only bounded information? +- **Understanding target:** Understand the relative-permutation cycle kernel and strict-contraction purity bound, crediting Correspondence as its owner and distinguishing an upper bound from a receiver. +- **Dependencies and story role:** M03–M04, M20; identifies the information that might survive. +- **Conceptual connection:** A source-level ceiling limits every receiver but does not construct an optimal one. +- **Source pointers:** Petz §§3.3–3.5, 5.5; [anonymous application](../science/anonymous-batches.md); Correspondence’s versioned kernel citation there. -- **Central question:** Why does this model's Holevo value equal the SLD value, and what has that established? -- **Understanding target:** Use the dual SLD operators to evaluate the bound, then separate that calculation from the smooth-model local-attainment theorem. -- **Dependencies and story role:** M10, M20. It identifies the attainable local collective target without assuming a known global center. -- **Conceptual connection:** Weak compatibility removes the Holevo penalty; a separate theorem supplies asymptotic measurements. -- **Source pointers:** Anchor §§2.3, 2.6, 2.11, 4.6; [Holevo calculation](../science/collective_attainment.md#evaluation-of-the-holevo-value), [local theorem](../science/collective_attainment.md#the-local-theorem-used). +### M22 — A candidate Gaussian covariance experiment -### M22 — Upgrade pointwise local attainment carefully +- **Central question:** What do the collective fluctuations suggest? +- **Understanding target:** Derive the centered local fluctuation covariances and the cross-correlation matrix; recognize that each list marginal is target independent while their relation is informative. +- **Dependencies and story role:** M20–M21; proposes a limiting classical object without yet proving sufficiency. +- **Conceptual connection:** Random local records can have a target-dependent joint law. +- **Source pointers:** [Gaussian application](../science/anonymous-batches.md#application-of-the-separate-list-sufficiency-theorem); [worked Gaussian example](TUTORIAL.md#10-one-gaussian-observation-and-its-information). -- **Central question:** How does a local theorem at a dense set of shifts control all shifts in a bounded neighborhood? -- **Understanding target:** Explain clipping, fidelity-based equicontinuity, finite nets, and why bounded-loss control is required. -- **Dependencies and story role:** M21. It supplies the uniform local ingredient needed by an unknown-center procedure. -- **Conceptual connection:** Convergence in a local statistical model must be matched to the loss being averaged. -- **Source pointers:** Anchor §§4.2, 4.5–4.6; [uniform local control](../science/collective_attainment.md#uniform-local-control-after-clipping). +### M23 — Equality of the full likelihood norms -### M23 — Express global loss without a coordinate chart +- **Central question:** What rules out information hidden beyond the fluctuations? +- **Understanding target:** Match the exact quantum collision-norm limit to the Gaussian likelihood L2 norm; explain why convergence of covariances or characteristic functions alone leaves a possible remainder. +- **Dependencies and story role:** M21–M22; supplies the decisive saturation argument. +- **Conceptual connection:** Equality of complete likelihood norms excludes an unobserved statistical remainder. +- **Source pointers:** [Full-likelihood explanation](../science/anonymous-batches.md#application-of-the-separate-list-sufficiency-theorem); [norm worked example](TUTORIAL.md#11-why-matching-a-covariance-is-not-enough). + +### M24 — Bounded Fourier likelihood approximation -- **Central question:** How can a unitary estimate's loss be embedded globally while ignoring phase? -- **Understanding target:** Relate the adjoint representation's character and Frobenius distance to process loss, and identify its tangent Gram and Laplacian. -- **Dependencies and story role:** M05–M06, M11. It begins the global converse with geometry valid far from the true target. -- **Conceptual connection:** Compact-group structure replaces a potentially dimension-sensitive local chart. -- **Source pointers:** Anchor §5.3 as a covariance connection; [global embedding](../science/global_converse.md#1-a-phase-insensitive-embedding), [tangent identities](../science/global_converse.md#2-the-tangent-identities). +- **Central question:** How does norm saturation approximate the whole state family? +- **Understanding target:** Use local permutation-invariant Fourier unitaries, their limiting Gram matrix and density of finite Fourier sums; choose finite approximants uniformly over the compact target family. +- **Dependencies and story role:** M23; converts a candidate Gaussian description into full operator likelihood control. +- **Conceptual connection:** Bounded Fourier functions connect weak fluctuation limits to strong likelihood approximation. +- **Source pointers:** [Fourier worked route](TUTORIAL.md#11-why-matching-a-covariance-is-not-enough); authoritative proof cited in [the application](../science/anonymous-batches.md). + +### M25 — Almost commuting operators become a receiver -### M24 — Bound global risk without unbiasedness +- **Central question:** How can several local fluctuation coordinates be measured together? +- **Understanding target:** Show vanishing normalized-Hilbert–Schmidt commutators and apply Glebsky’s fixed-finite-family theorem separately on each list, without assuming operator-norm commutation or efficient synthesis. +- **Dependencies and story role:** M24; supplies the physical measurement missing from weak fluctuation convergence. +- **Conceptual connection:** Approximate commutation in a dimension-normalized norm can yield exact compatible measurements. +- **Source pointers:** [Receiver mechanism](TUTORIAL.md#12-a-classical-record-that-can-reconstruct-the-state); Glebsky Theorem 2 cited in [the application](../science/anonymous-batches.md). + +### M26 — Scalar conditional expectation and reconstruction -- **Central question:** How does Haar integration by parts convert a Fisher trace budget into a bound on any estimator? -- **Understanding target:** Follow the score identity and tangent projection estimate to the global risk inequality, without differentiating the estimator. -- **Dependencies and story role:** M08, M23. It extends the converse beyond locally unbiased procedures. -- **Conceptual connection:** The prior's group symmetry and the loss embedding work together to control biased estimates. -- **Source pointers:** Anchor §5.5 as methodological background; [Haar score identity](../science/global_converse.md#3-haar-integration-by-parts), [Cauchy–Schwarz step](../science/global_converse.md#4-cauchyschwarz-closes-the-argument). +- **Central question:** What exactly is retained by the two classical labels? +- **Understanding target:** Measure the common local spectral projectors and prepare their normalized identities; distinguish this scalar abelian conditional expectation from ordinary block pinching. +- **Dependencies and story role:** M09, M25; constructs a truly classical measurement-and-preparation channel. +- **Conceptual connection:** A classical block label does not retain an arbitrary state inside its subspace. +- **Source pointers:** Petz §§9.1–9.2, 9.5; [reconstruction example](TUTORIAL.md#12-a-classical-record-that-can-reconstruct-the-state). + +### M27 — Uniform recovery and bounded decisions -### M25 — Keep the converse under every permitted history +- **Central question:** Why does one receiver work without knowing the target? +- **Understanding target:** Use a compact-family finite cover and a diagonal finite-frequency schedule, then turn uniform trace reconstruction into a bound for every prior and bounded decision loss. +- **Dependencies and story role:** M24–M26; closes the operational sufficiency theorem. +- **Conceptual connection:** Uniform state recovery controls every bounded decision rule by channel contraction. +- **Source pointers:** Petz §9.5; [decision consequence](../science/anonymous-batches.md#what-the-corollary-permits). + +### M28 — Gaussian equivalence and coherent prediction -- **Central question:** Why do adaptation and collective processing obey the appropriate global information budget? -- **Understanding target:** Distinguish conditional-score additivity for SEP/PAIR from additive SLD information bounding a global collective POVM. -- **Dependencies and story role:** M14, M17, M20, M24. It applies one global converse to all three classes. -- **Conceptual connection:** Classical adaptation and quantum retention require different arguments, even when they enter the same inequality. -- **Source pointers:** Anchor §§2.1, 2.10; [adaptive and collective budgets](../science/global_converse.md#5-why-the-fisher-budgets-apply-to-adaptive-and-collective-protocols). - -### M26 — Remove the known center for pairwise readouts +- **Central question:** Does the theorem describe a complete limiting experiment? +- **Understanding target:** Understand the two parameter-independent randomizations obtained from reference couplings; apply trace-norm contractivity to a processor that consumes the data with a later quantum input. +- **Dependencies and story role:** M22–M27; relates the classical covariance experiment to every bounded prediction task, not just identification. +- **Conceptual connection:** A complete limiting experiment requires randomizations in both directions. +- **Source pointers:** [Full application](../science/anonymous-batches.md); [Gaussian and prediction explanation](TUTORIAL.md#13-limits-resources-and-the-whole-story). + +### M29 — Batch tags limits and physical costs -- **Central question:** How do the locally optimal SEP and PAIR measurements become global learning protocols? -- **Understanding target:** Explain the informationally complete pilot, model fit, counterrotation, and one-step score estimate; track why their bias and pilot costs are lower order. -- **Dependencies and story role:** M15, M18–M19, M23–M25. It matches the first two global lower bounds with unknown-center upper bounds. -- **Conceptual connection:** Calibration is charged, but fixed-dimensional regularity makes its leading precision cost vanish. -- **Source pointers:** Anchor §§2.1, 4.5; [pilot and one-step construction](../science/separable_readout.md#5-global-fixed-dimensional-attainability), [PAIR risk consequence](../science/joint_pair_readout.md#consequence-for-the-learning-risk). - -### M27 — Globalize the collective optimum +- **Central question:** What remains unproved when both batch size and batch count grow? +- **Understanding target:** State the product-error condition, charge all supplied pairs and per-list coherent memory/control, and avoid inferring Fisher-information convergence, a precision coefficient or growing-dimension efficiency. +- **Dependencies and story role:** M10, M19, M27–M28; preserves the scientific limits of both theorems. +- **Conceptual connection:** A vanishing per-batch error need not vanish after an uncontrolled number of repetitions. +- **Source pointers:** [Batch limits](../science/anonymous-batches.md#limit-order-and-charged-resources); [resource account](../science/resources.md). + +### M30 — Explain the combined scientific story -- **Central question:** How does the collective protocol handle a center learned from a finite pilot, including rare pilot failures? -- **Understanding target:** Connect the slowly growing local radius, clipped collective estimator, and second-moment tail control into a uniform global risk bound. -- **Dependencies and story role:** M21–M22, M25–M26. It closes the remaining local-to-global gap. -- **Conceptual connection:** A small failure probability alone is insufficient when the scaled loss can be large. -- **Source pointers:** Anchor §§4.5–4.6.4; [global pilot](../science/collective_attainment.md#a-global-pilot-with-exponential-tails), [radius schedule](../science/collective_attainment.md#a-slowly-growing-local-neighborhood), [failure contribution](../science/collective_attainment.md#the-pilot-failure-contribution). - -### M28 — Match the complete three-tier theorem - -- **Central question:** What remains once each global converse is paired with its attaining procedure? -- **Understanding target:** Recover the three exact coefficients for one shared loss, their two multiplicative penalties, and the equality of Haar Bayes and worst-case risks. -- **Dependencies and story role:** M12, M25–M27. This integrates the mathematical result across all readouts. -- **Conceptual connection:** Isotropy, global estimation and a common loss turn information ceilings into comparable learning precision. -- **Source pointers:** Anchor §§4.6.4, 5.3; [canonical coefficients](../science/model.md#the-constants), [global covariance](../science/collective_attainment.md#converse-and-group-covariance). - -### M29 — Price the interpretation and preserve the limits - -- **Central question:** Which physical and computational costs lie outside the exact sample coefficients? -- **Understanding target:** Account for private source seeds, retention boundaries, measurement synthesis, calibration, classical fitting and unitary output; keep the ordered limit separate from fixed-error or runtime claims. -- **Dependencies and story role:** M02–M04, M19, M28. It connects the completed theorem to an implementable learning task. -- **Conceptual connection:** Precision advantage and efficient end-to-end computation are separate outcomes. -- **Source pointers:** Anchor §4.5 for asymptotic applicability; [resource account](../science/resources.md), [dimension dependence](../science/interpretation.md#what-the-dimension-dependence-establishes). - -### M30 — Explain the whole contribution - -- **Central question:** What does this hierarchy establish after established estimation tools and earlier separable-probe results are credited? -- **Understanding target:** Give one coherent account of the same passive learning task, the two distinct readout gains, the sharp global precision law, and its scientific scope. -- **Dependencies and story role:** M01–M29. This is the narrative synthesis, joining the mechanism, proofs, attainment, attribution and limits. -- **Conceptual connection:** The consequence is a precise separation of within-example and between-example coherence, rather than a general claim that separability prevents or guarantees quantum learning advantage. -- **Source pointers:** Anchor §§1.3, 6 for the wider estimation perspective; [interpretation](../science/interpretation.md), [scientific route](../science/README.md), [related-work comparison](../references/related_work.md). +- **Central question:** How do readout and correspondence play different operational roles? +- **Understanding target:** Present the source, both acquisition interfaces, the paired hierarchy and anonymous sufficiency consequence, proof ownership, inherited tools, attained statements and remaining limits as one connected account. +- **Dependencies and story role:** M01–M29; integrates the complete project rather than adding a claim from a headline scaling. +- **Conceptual connection:** Resource assumptions, attribution and limits belong in the statement of the scientific contribution. +- **Source pointers:** [Scientific route](../science/README.md); [attribution](../references/related_work.md); [Petz bridge](ANCHOR_BRIDGE.md). diff --git a/learning/README.md b/learning/README.md index 53b8967..8d1e2ac 100644 --- a/learning/README.md +++ b/learning/README.md @@ -1,26 +1,22 @@ # Learning route -This route connects the selected 2020 multiparameter-estimation review to the project's exact learning-readout hierarchy. It uses one source and one continuing example: learning an unknown unitary from separable two-register demonstrations whose preparation records are withheld. +The selected common educational anchor is **Dénes Petz, _Quantum Information Theory and Quantum Statistics_, first edition (2008)**, [publisher record](https://doi.org/10.1007/978-3-540-74636-2). This route follows one physical source through two questions: how readout restrictions change precision while input–output correspondence is available, and how all information surviving a large anonymous shuffle can be read separately from the two coherent lists. -Start with [the anchor bridge](ANCHOR_BRIDGE.md). It gives the verified locations in Demkowicz-Dobrzański, Górecki and Guţă, *Multi-parameter estimation beyond Quantum Fisher Information*, [arXiv:2001.11742v2](https://arxiv.org/abs/2001.11742v2), and translates the review's notation into the repository's. +Start with the [Petz bridge](ANCHOR_BRIDGE.md), then the [worked tutorial](TUTORIAL.md). The [exactly 30 project milestones](MILESTONES.md) organize the whole scientific story into ten background targets and twenty narrative targets. They are a map of the project, independent of any learner's progress. -The [tutorial](TUTORIAL.md) develops the continuing example. The [30 project milestones](MILESTONES.md) organize the path from the supplied source to the complete precision hierarchy. Use the bridge when a milestone introduces an estimation concept, and follow its scientific link when the exact proof is needed. +## Read the connected argument -## A connected scientific reading order +1. Specify [the model](../science/model.md): supplied quantum pairs, hidden preparation records, target unitary, classical estimate and gate loss. +2. Compare [separable readout](../science/separable_readout.md), [joint-pair readout](../science/joint_pair_readout.md) and [collective attainment](../science/collective_attainment.md). The sharp coefficients distinguish coherence inside one pair from coherence across examples. +3. Follow [the global converse](../science/global_converse.md) and the localization constructions. A local information calculation alone is insufficient for an unknown-target risk theorem allowing biased adaptive learners. +4. Change the acquisition interface in [anonymous batches](../science/anonymous-batches.md). The permutation disappears before any learner interaction; each side may nevertheless retain its whole list coherently. Define this separate-list class before comparing it with joint readout. +5. Learn why a correlated Gaussian description becomes a complete experiment: the exact collision norm, bounded Fourier likelihood approximation, local commuting measurements and product reconstruction. The general theorem and full proof belong to [Quantum Learning Correspondence](https://github.com/GoGoKo699/Quantum-Learning-Correspondence); the Readout account supplies its self-contained application and precise measurement-class distinction. +6. Finish with [resources](../science/resources.md) and [attribution](../references/related_work.md). Preserve the order of limits and charge local quantum storage, collective control, measurement synthesis, classical fitting and output. -1. Read [the model](../science/model.md). Specify the state supplied per example, the hidden parameter, the classical output, the gate loss and the three readout classes. -2. Read [the interpretation](../science/interpretation.md). Separate the value of joint readout within one pair from the additional value of coherence between different pairs. -3. Work through [separable readout](../science/separable_readout.md) and [joint-pair readout](../science/joint_pair_readout.md). These derive different sharp Fisher-trace ceilings while leaving the source and target unchanged. -4. Follow [the global converse](../science/global_converse.md). Its group embedding turns a transcript information budget into a risk bound without assuming an unbiased learner. -5. Read [collective attainment](../science/collective_attainment.md). Keep the local Holevo calculation, the local theorem and the unknown-center globalization as distinct proof steps. -6. Finish with [resources](../science/resources.md) and [related work](../references/related_work.md). Identify the implementation costs left outside a sample coefficient and the earlier results used by the proof. +## Keep the two conclusions separate -The common destination is the same in every step: a classical estimate $`\widehat U\in\mathrm{PU}(d)`$ of an arbitrary fixed unitary. The theorem takes $`N\to\infty`$ at fixed $`d\ge2`$ and known $`0\lt v\lt 1`$. A comparison of the resulting coefficients as dimension grows preserves that order of limits. +With correspondence available, the three optimal risks have distinct coefficients in the fixed-dimension limit of $`N r_N`$. After a single growing anonymous shuffle, separate collective list measurements can reconstruct the full anonymous state with uniform trace error tending to zero. The second conclusion concerns the information that remains after the acquisition change; it does not remove the anonymous information ceiling or identify the separate-list class with the earlier per-pair SEP class. -## Three distinctions to keep visible +The common assumptions are fixed $`d\ge2`$, known $`0\lt v\lt1`$, private preparation records, and no chosen-input calls to the target. The new reconstruction proof also extends to $`v=1`$ because its correlation contraction remains strict; the original regular paired precision theorem keeps its full-rank hypothesis. -- A source being separable does not require its best readout to be separable. -- A zero mean SLD commutator does not require the SLD operators to commute. -- A local information bound does not by itself supply a global protocol for an unknown unitary. - -The route combines common definitions, the continuing example, worked proofs and the selected source connections. +Petz supplies the framework of information, statistical estimation, coarse-graining and sufficiency. The exact source-specific precision laws, anonymous kernel, Fourier norm saturation, Glebsky approximation and Gaussian randomization argument are supplied separately by the scientific accounts and their primary references. diff --git a/learning/TUTORIAL.md b/learning/TUTORIAL.md index 5c01caf..64b0b79 100644 --- a/learning/TUTORIAL.md +++ b/learning/TUTORIAL.md @@ -1,8 +1,8 @@ -# One source, three precision limits +# One source, precision limits and surviving information -The experiment begins with a pair of quantum systems whose individual states reveal nothing about an unknown unitary. Their correlations do reveal it. The learning question is how much precision survives when the receiver measures the systems separately, measures each pair jointly, or keeps several pairs coherent until a collective readout. +The experiment begins with a pair of quantum systems whose individual states reveal nothing about an unknown unitary. Their correlations do reveal it. First ask how precision changes when the receiver measures the systems separately, measures each identified pair jointly, or keeps several pairs coherent until a collective readout. Then erase the correspondence across an anonymous batch and ask whether the surviving information still needs quantum coupling between its two lists. -This worked route uses one qubit in each register, $`d=2`$, and the fixed correlation parameter $`v=1/2`$. It then connects the experiment to the general theorem. The educational anchor is Demkowicz-Dobrzański, Górecki and Guţă, *Multi-parameter estimation beyond Quantum Fisher Information*, arXiv:2001.11742v2. The [anchor bridge](ANCHOR_BRIDGE.md) gives the selected source locations; the [milestone map](MILESTONES.md) lays out the full dependency route. +This worked route uses one qubit in each register, $`d=2`$, and the fixed correlation parameter $`v=1/2`$. It connects the example to both the paired precision theorem and the separate-list sufficiency theorem. The educational anchor is Dénes Petz, *Quantum Information Theory and Quantum Statistics*, first edition (2008). The [anchor bridge](ANCHOR_BRIDGE.md) gives the selected source locations; the [milestone map](MILESTONES.md) lays out the full dependency route. ## 1. What an example contains @@ -19,7 +19,7 @@ it chooses one state $`\psi`$ and emits $`|\psi\rangle_A\otimes U|\psi\rangle_B` Every emitted pure pair is a product across $`A:B`$. Averaging the unavailable preparation record gives ```math -\sigma_{U,1/2}=\frac{I+\tfrac12 F_U}{5}, +\rho_{U,1/2}=\frac{I+\tfrac12 F_U}{5}, \qquad F_U=(I\otimes U)F(I\otimes U^\dagger), ``` @@ -39,7 +39,7 @@ F=\frac12(I\otimes I+X\otimes X+Y\otimes Y+Z\otimes Z). Consequently our example state is ```math -\sigma_{U,1/2} +\rho_{U,1/2} =\frac14\left[ I\otimes I+\frac15\sum_{P\in\{X,Y,Z\}} P\otimes UPU^\dagger @@ -117,7 +117,7 @@ This extra permission matters because the local score observables for different The many-copy limit is different. The Holevo bound incorporates simultaneous-estimation compatibility, and here it equals the SLD value. A collective local estimator can attain that value asymptotically. The [collective proof](../science/collective_attainment.md) then constructs an unknown-center global protocol; it does not assume the learner already knows where to apply the optimal measurement. -This is the point at which the anchor review's distinction between quantum Fisher information, the Holevo bound and actual attainment becomes essential. Computing a favorable QFI is one step in the argument, not the completed learning theorem. +Petz’s estimation framework helps formulate the distinction between information and an actual statistical procedure. The source-specific Holevo calculation and local attainment theorem are supplied by the scientific proof and its specialist primary references. Computing a favorable QFI is one step in the argument, not the completed learning theorem. ## 6. The qubit precision coefficients @@ -177,19 +177,159 @@ The qubit numbers are therefore asymptotic slopes, not an exact prediction for t The preparation record remains an essential part of the experiment. Disclosing a source's input description would supply information that this learner has to extract from the quantum reference register. Chosen known inputs would change the task again. The established hierarchy concerns the specified passive native-data source with unavailable records, known correlation strength, independent pairs and the same average gate-loss criterion in all three readout classes. +## 9. Remove the matching before readout + +Return to the same qubit source with $`v=1/2`$, but now supply two lists of $`b`$ registers each. The output list is uniformly shuffled once across the whole batch, before any learner action, and the matching is withheld. The learner receives the anonymous state $`\Omega_{b,1/2}(U)`$. This is an acquisition change: even an unrestricted joint measurement receives a different statistical experiment from the identified product of pairs. + +A separate-list receiver may keep all $`A`$ registers coherent, do the same on $`B`$, and perform collective measurements $`M_b^A`$ and $`M_b^B`$. It then combines the two ordinary classical records. It need never couple an $`A`$ register quantumly to a $`B`$ register. + +This is not the original SEP protocol. SEP converts each identified pair into classical information before proceeding to the next pair. A separate-list measurement can use quantum interactions between many specimens in its own list. The old coefficients $`37.5,12.5,5`$ therefore do not provide the new anonymous comparison. + +Petz's coarse-graining viewpoint asks two different questions here. First, what information did the anonymous acquisition channel remove? Second, does a later separate-list measurement lose any more information asymptotically? An upper bound for the first question does not answer the second. The [anonymous-batch account](../science/anonymous-batches.md) defines the new receiver precisely. + +## 10. One Gaussian observation and its information + +For the qubit source the correlation singular value is + +```math +t=\frac{v}{d+v}=\frac15. +``` + +Write $`T(U)`$ for the three-by-three matrix of Pauli cross-correlations. It is $`1/5`$ times an orthogonal matrix. The candidate large-batch description is one pair of three-dimensional Gaussian vectors, + +```math +(\mathbf X,\mathbf Y)\sim\mathcal N\!\left(0, +\begin{pmatrix}I_3&T(U)\\T(U)^{\mathsf T}&I_3\end{pmatrix}\right). +``` + +Neither marginal depends on $`U`$. Nevertheless, their cross-correlation does. On the same rotation slice $`U_\theta=e^{-i\theta Z}`$ used in Section 2, + +```math +\mathbb E_\theta[X_xY_y]=\frac15\sin(2\theta). +``` + +This is the continuous fluctuation counterpart of the earlier fair-sign comparison. At $`\theta=0`$ the selected components have zero covariance; at $`\theta=\pi/4`$ they have covariance $`1/5`$. The two individual records remain target-independent random variables, while their relation carries the signal. + +There is one such Gaussian observation per large anonymous batch. Increasing $`b`$ does not supply $`b`$ independent Gaussian observations. Its covariance stays strictly positive with a fixed finite correlation strength, so one observation leaves uncertainty. The Gaussian description is compatible with Correspondence's source-level information ceiling; it does not undo the shuffle. + +At $`U=I`$, $`T=tI_3`$. Relative to the reference $`\gamma`$ of independent standard vectors, the Gaussian likelihood is + +```math +\ell_t(\mathbf x,\mathbf y) +=(1-t^2)^{-3/2} +\exp\!\left[ +\frac{t\,\mathbf x\mathbin{\cdot}\mathbf y}{1-t^2} +-\frac{t^2(|\mathbf x|^2+|\mathbf y|^2)}{2(1-t^2)} +\right]. +``` + +Its squared $`L^2(\gamma)`$ norm is + +```math +\int\ell_t^2\,d\gamma=(1-t^2)^{-3} +=\left(\frac{25}{24}\right)^3. +``` + +This norm, rather than covariance alone, closes the operational proof. + +## 11. Why matching a covariance is not enough + +Suppose two large experiments have the same limiting fluctuation covariance. That statement does not rule out additional information in an observable outside the chosen fluctuation description. A valid receiver theorem needs control of the complete state family. + +Let $`D_b=2^{2b}`$, let $`\tau_b(X)=\mathrm{Tr}(X)/D_b`$, and define the anonymous likelihood operator $`L_b(U)=D_b\Omega_{b,1/2}(U)`$. Correspondence's exact collision kernel gives, for every target, + +```math +\Vert L_b(U)\Vert _{2,\tau_b}^2 +=\sum_{k=0}^b\binom{k+2}{2}25^{-k} +\longrightarrow\left(\frac{25}{24}\right)^3. +``` + +For example, the one-pair value is $`1+3/25=28/25`$. The limiting value is the Gaussian likelihood norm calculated in Section 10. The full quantum likelihood has no extra limiting squared norm left over beyond the Gaussian description. + +To turn that observation into an approximation, use bounded local Fourier operators + +```math +W_b^A(x)=\left(e^{i(x_xX+x_yY+x_zZ)/\sqrt b}\right)^{\otimes b}, +``` + +and the analogous $`W_b^B(y)`$. They are unchanged by permutations within a list. The hidden shuffle therefore disappears exactly from their expectation, reducing it to the $`b`$th power of a single-pair expectation. Taylor expansion gives the corresponding Gaussian characteristic function. Under the maximally mixed reference, the Gram matrix of any finite set of these operators also converges to the Gram matrix of Gaussian Fourier functions. + +Now choose a finite Fourier sum $`q`$ approximating the Gaussian likelihood in $`L^2(\gamma)`$, and use the same coefficients to build $`q_b`$ from $`W_b^A\otimes W_b^B`$. Expanding the squared error yields + +```math +\Vert L_b(U)-q_b\Vert _{2,\tau_b}^2 +\longrightarrow\Vert \ell_U-q\Vert _{L^2(\gamma)}^2. +``` + +This identity uses three ingredients together: the characteristic-function limit, the Fourier Gram limit, and equality of the **full** likelihood-norm limits. Fourier sums are dense, so the right side can be arbitrarily small. Compactness of the unitary orbit allows a finite collection of such approximants that works uniformly for all targets. + +The approximants may be chosen using the known source family. The actual receiver uses the union of their frequency sets and never needs to know which approximant belongs to the unknown target. The scientific proof supplies the finite-family construction and its uniform quantifiers. + +## 12. A classical record that can reconstruct the state + +The local Fourier operators do not commute exactly at finite $`b`$. Their commutators do tend to zero in **normalized Hilbert–Schmidt norm**. Glebsky's inherited theorem approximates each fixed finite family by exactly commuting unitaries with an error that vanishes independently of the Hilbert-space dimension. Apply that theorem separately to the two lists. + +The common spectral projectors of the commuting A-family are $`P_i`$, with ranks $`r_i`$; those of the B-family are $`Q_j`$, with ranks $`s_j`$. Measure these projectors locally and retain the classical labels $`(i,j)`$. A target-independent reconstruction channel prepares + +```math +\frac{P_i}{r_i}\otimes\frac{Q_j}{s_j}. +``` + +For a density operator $`\omega`$, measurement followed by this preparation is + +```math +E_b(\omega)=\sum_{i,j} +\frac{\mathrm{Tr}[(P_i\otimes Q_j)\omega]}{r_i s_j} +(P_i\otimes Q_j). +``` + +A rank-two projector illustrates a necessary distinction: its classical label specifies a subspace, not an arbitrary quantum state inside it. Ordinary block pinching would retain that internal state. The reconstruction above instead prepares the normalized identity on the subspace. It is the scalar conditional expectation onto an abelian algebra, in the language of Petz §§9.1–9.2, and it really is implemented from fully classical records. + +This conditional expectation fixes the commuting Fourier approximants. Since it is an orthogonal projection in normalized $`L^2`$, the full likelihood approximation from Section 11 controls its error. Choosing finite frequency sets increasingly slowly as $`b`$ grows gives one target-independent receiver sequence with + +```math +\varepsilon_b:=\sup_U +\Vert \Omega_{b,1/2}(U)-E_b(\Omega_{b,1/2}(U))\Vert _1 +\longrightarrow0. +``` + +The use of a diagonal sequence matters: the almost-commuting theorem is applied to a fixed finite family at each approximation level, not to an uncontrolled growing number of operators. + +For any joint decision rule on the original anonymous batch, first reconstruct $`E_b(\Omega)`$ from the separate records and apply that rule. The outcome laws differ in total variation by at most $`\varepsilon_b/2`$. Thus all losses in $`[0,1]`$ have a vanishing optimal-risk gap. This is asymptotic sufficiency in the recovery sense of Petz §9.5, with the source-specific approximation proved separately. + +## 13. Limits, resources, and the whole story + +The same finite Fourier approximation gives more than state reconstruction. Under the maximally mixed reference, the commuting spectral labels converge to the Gaussian Fourier-coordinate law. Coupling these reference laws supplies parameter-independent randomizations in both directions. Their target errors are controlled by the same full-likelihood approximation. This establishes equivalence to the Gaussian covariance experiment described in Section 10; it is not an inference from covariance convergence alone. The full proof is owned by Correspondence and versioned from [the application](../science/anonymous-batches.md). + +A coherent predictor is also covered. If a fixed processor consumes the training batch together with a later input, replacing the batch by its reconstruction changes the output by a vanishing trace error, even when the later input has a reference system. Hence its bounded average-fidelity score has no persistent advantage over what the separate records permit. All output branches still count. + +There are two different limits in the combined story: + +| Experiment | Limit and conclusion | What does not follow | +|---|---|---| +| Identified independent pairs | Fix $`d,v`$, then let $`N\to\infty`$; obtain the three exact coefficients of $`N r_N`$. | No dimension-uniform onset or efficient collective compiler. | +| One anonymous batch | Fix $`d,v`$, then let $`b\to\infty`$; obtain uniform state recovery and a bounded-risk gap tending to zero. | No Fisher-information convergence or equality of rescaled precision coefficients. | +| $`m`$ independently tagged anonymous batches | Product reconstruction error is at most $`m\varepsilon_b`$; fixed $`m`$ is covered as $`b`$ grows. | An arbitrary simultaneous growth of $`m`$ needs $`m(b)\varepsilon_b\to0`$ or further quantitative control. | + +The total source budget for the last row is $`mb`$ pairs. Before its measurement, each side retains $`b`$ specimens of dimension $`d`$, whose joint Hilbert space has logarithmic dimension $`b\log_2d`$; for $`d=2^n`$, these are $`bn`$ data qubits. It may also need entangling control across its own list, complicated spectral measurements, initialized work, large classical records and substantial computation. The proof is an existence construction. It gives no useful convergence rate, efficient synthesis, noise threshold or runtime crossover. + +The two main conclusions now fit together. With correspondence supplied, restrictive readout loses precision in two distinct stages. After correspondence is erased across one growing batch, most information is already absent from the received state, and all of what remains can be extracted separately from the two coherent lists asymptotically. The first theorem prices readout while holding acquisition fixed; the second identifies a sufficient readout for the information that survives a changed acquisition channel. Both keep the preparation and permutation records unavailable and charge the quantum memory they actually use. + ## Follow the milestone map -The tutorial develops one example in a short reading order. The milestones expand the same story into the detailed background and proof route; these links connect every settled target to its tutorial section. +The tutorial and the thirty milestones describe the same complete account at different resolutions. The links below cover every milestone once. -| Tutorial section | Corresponding milestone targets | +| Tutorial material | Milestone targets | |---|---| -| [1. What an example contains](#1-what-an-example-contains) | [M01](MILESTONES.md#m01--what-counts-as-one-example), [M02](MILESTONES.md#m02--a-unitary-hidden-in-a-relation), [M03](MILESTONES.md#m03--product-preparation-and-informative-correlations), [M04](MILESTONES.md#m04--visibility-creates-a-regular-state-family) | -| [2. Information in a comparison](#2-the-information-is-in-a-comparison) | [M05](MILESTONES.md#m05--count-physical-unitary-directions), [M07](MILESTONES.md#m07--a-measurement-creates-a-classical-record), [M08](MILESTONES.md#m08--scores-and-simultaneous-information) | -| [3. A weak classical description](#3-measuring-the-reference-produces-a-weak-classical-description) | [M13](MILESTONES.md#m13--read-the-response-of-one-product-effect), [M14](MILESTONES.md#m14--completeness-limits-every-separable-readout), [M15](MILESTONES.md#m15--a-simple-local-measurement-meets-the-ceiling) | -| [4. Joint readout within a pair](#4-waiting-for-the-second-arrival-gives-one-gain) | [M16](MILESTONES.md#m16--joint-effects-mix-exchange-sectors), [M17](MILESTONES.md#m17--derive-the-sharp-joint-pair-ceiling), [M18](MILESTONES.md#m18--normalize-the-optimal-joint-pair-seed), [M19](MILESTONES.md#m19--an-attaining-povm-must-count-all-outcomes) | -| [5. Coherence across examples](#5-keeping-different-examples-coherent-gives-another-gain) | [M09](MILESTONES.md#m09--quantum-information-is-a-bound-on-readout), [M10](MILESTONES.md#m10--compatibility-is-more-than-operator-commutation), [M20](MILESTONES.md#m20--compute-the-collective-information-matrix), [M21](MILESTONES.md#m21--evaluate-the-holevo-value-and-its-local-meaning), [M22](MILESTONES.md#m22--upgrade-pointwise-local-attainment-carefully) | -| [6. Qubit precision coefficients](#6-the-qubit-precision-coefficients) | [M06](MILESTONES.md#m06--specify-success-before-precision), [M12](MILESTONES.md#m12--state-the-complete-comparison), [M28](MILESTONES.md#m28--match-the-complete-three-tier-theorem) | -| [7. Global risk and biased learners](#7-why-these-are-global-risks-including-biased-learners) | [M11](MILESTONES.md#m11--local-precision-and-global-risk), [M23](MILESTONES.md#m23--express-global-loss-without-a-coordinate-chart), [M24](MILESTONES.md#m24--bound-global-risk-without-unbiasedness), [M25](MILESTONES.md#m25--keep-the-converse-under-every-permitted-history), [M26](MILESTONES.md#m26--remove-the-known-center-for-pairwise-readouts), [M27](MILESTONES.md#m27--globalize-the-collective-optimum) | -| [8. General dimension and limits](#8-general-dimension-and-the-meaning-of-the-limit) | [M29](MILESTONES.md#m29--price-the-interpretation-and-preserve-the-limits), [M30](MILESTONES.md#m30--explain-the-whole-contribution) | - -[Return to the anchor bridge](ANCHOR_BRIDGE.md) · [Follow the 30 milestones](MILESTONES.md) · [Read the complete scientific route](../science/README.md) +| 1–2. Source and comparison | [M01](MILESTONES.md#m01--specimens-and-sample-boundaries), [M02](MILESTONES.md#m02--an-unknown-transformation-in-a-relation), [M03](MILESTONES.md#m03--separable-preparation-and-hidden-correlations), [M04](MILESTONES.md#m04--visibility-and-the-swap-model), [M05](MILESTONES.md#m05--unitary-geometry-and-global-phase) | +| 3. Weak separate pair record | [M07](MILESTONES.md#m07--measurements-and-retained-records), [M11](MILESTONES.md#m11--the-sharp-separable-effect-ceiling), [M12](MILESTONES.md#m12--a-causal-readout-that-attains-sep) | +| 4. Joint identified-pair readout | [M13](MILESTONES.md#m13--joint-readout-of-an-identified-pair), [M14](MILESTONES.md#m14--count-a-normalized-measurement) | +| 5. Coherence across identified examples | [M08](MILESTONES.md#m08--classical-and-quantum-information-budgets), [M15](MILESTONES.md#m15--the-collective-information-matrix), [M16](MILESTONES.md#m16--compatibility-and-the-holevo-value) | +| 6–8. Loss global risk and precision limits | [M06](MILESTONES.md#m06--gate-loss-and-the-returned-model), [M10](MILESTONES.md#m10--global-risk-and-ordered-limits), [M17](MILESTONES.md#m17--a-converse-for-biased-adaptive-learners), [M18](MILESTONES.md#m18--attainment-at-an-unknown-target), [M19](MILESTONES.md#m19--the-complete-paired-precision-hierarchy) | +| 9. Anonymous acquisition and a new readout class | [M09](MILESTONES.md#m09--coarse-graining-and-statistical-sufficiency), [M20](MILESTONES.md#m20--erase-correspondence-and-change-the-class), [M21](MILESTONES.md#m21--the-exact-anonymous-kernel-and-ceiling) | +| 10. Gaussian covariance observation | [M22](MILESTONES.md#m22--a-candidate-gaussian-covariance-experiment) | +| 11. Full likelihood and Fourier saturation | [M23](MILESTONES.md#m23--equality-of-the-full-likelihood-norms), [M24](MILESTONES.md#m24--bounded-fourier-likelihood-approximation) | +| 12. Commuting measurements and reconstruction | [M25](MILESTONES.md#m25--almost-commuting-operators-become-a-receiver), [M26](MILESTONES.md#m26--scalar-conditional-expectation-and-reconstruction), [M27](MILESTONES.md#m27--uniform-recovery-and-bounded-decisions) | +| 13. Gaussian equivalence prediction and limits | [M28](MILESTONES.md#m28--gaussian-equivalence-and-coherent-prediction), [M29](MILESTONES.md#m29--batch-tags-limits-and-physical-costs), [M30](MILESTONES.md#m30--explain-the-combined-scientific-story) | + +[Return to the Petz bridge](ANCHOR_BRIDGE.md) · [Follow the 30 milestones](MILESTONES.md) · [Read the complete scientific route](../science/README.md) diff --git a/llms.txt b/llms.txt index 80b1332..34acfa5 100644 --- a/llms.txt +++ b/llms.txt @@ -8,11 +8,12 @@ Question: what do coherent acquisition resources change when learning a unitary - Sharp per-pair separable/LOCC optimum and attaining design: science/separable_readout.md - Sharp arbitrary one-pair POVM optimum and normalized covariant measurement: science/joint_pair_readout.md - SLD/Holevo coefficient and unknown-center global attainment: science/collective_attainment.md +- Growing anonymous batches, separate collective list readout and the Gaussian covariance limit: science/anonymous-batches.md - Meaning and worked examples: science/interpretation.md - Source, storage, genuine POVM, precision and output charges: science/resources.md - Primary foundations and exact-model comparisons: references/related_work.md - Bibliography: references/references.bib -- Learning entrypoint and selected 2020 review: learning/README.md +- Learning entrypoint and selected Petz textbook (first edition, 2008): learning/README.md - Exactly 30 scientific milestones: learning/MILESTONES.md - Source locations, notation and proof bridge: learning/ANCHOR_BRIDGE.md - Worked qubit example and connected argument: learning/TUTORIAL.md @@ -20,3 +21,5 @@ Question: what do coherent acquisition resources change when learning a unitary Essential qualifiers: fixed d>=2 and known0infinity; classical unitary estimate; per-pair separable and joint classes retain only classical records between examples. Supplied quantum data do not provide active unitary queries. A normalized orbit POVM is not random binary testing with free postselection. No dimension-uniform finite-error or runtime advantage is established. +For anonymous data, each list may instead retain all its specimens coherently. Separate-list collective readout is a different class from the original per-pair SEP class. At fixed dimension and visibility, a growing anonymous batch admits target-independent local measurement and product state reconstruction with vanishing trace error. The full new proof is owned by Quantum Learning Correspondence and is version-linked from science/anonymous-batches.md. This does not restore consistency from one anonymous batch or establish Fisher-information convergence. For a growing number m(b) of tagged batches, the direct reconstruction guarantee requires m(b) times the one-batch error to vanish. Measurement synthesis, local coherent storage and classical processing remain charged. + diff --git a/references/references.bib b/references/references.bib index af5744c..f405e72 100644 --- a/references/references.bib +++ b/references/references.bib @@ -112,3 +112,36 @@ @article{kim2026 journal = {Nature Communications}, volume = {17}, pages = {1822}, year = {2026}, doi = {10.1038/s41467-026-68532-y} } + +@misc{glebsky2010, + author = {Glebsky, Lev}, + title = {Almost commuting matrices with respect to normalized Hilbert--Schmidt norm}, + year = {2010}, + eprint = {1002.3082}, archivePrefix = {arXiv}, + url = {https://arxiv.org/abs/1002.3082}, + note = {Theorem 2, fixed finite families of unitaries; normalized Hilbert--Schmidt approximation.} +} + +@article{kuperberg2005, + author = {Kuperberg, Greg}, + title = {A tracial quantum central limit theorem}, + journal = {Transactions of the American Mathematical Society}, + volume = {357}, pages = {459--471}, year = {2005}, + eprint = {math-ph/0202035}, archivePrefix = {arXiv}, + url = {https://arxiv.org/abs/math-ph/0202035} +} + +@book{petz2008, + author = {Petz, D{\'e}nes}, + title = {Quantum Information Theory and Quantum Statistics}, + publisher = {Springer}, edition = {1}, year = {2008}, + doi = {10.1007/978-3-540-74636-2} +} + +@misc{quantumlearningcorrespondence, + author = {Lin, Ruge}, + title = {Quantum Learning Correspondence}, + year = {2026}, + url = {https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/8edc63836384745aee80101722255154e562af8f/science/separate-list-readout.md}, + note = {Authoritative general separate-list sufficiency and Gaussian-equivalence proof; the Readout account supplies its application.} +} diff --git a/references/related_work.md b/references/related_work.md index 3383992..f977a02 100644 --- a/references/related_work.md +++ b/references/related_work.md @@ -56,6 +56,23 @@ This is a background comparison for arbitrary-estimator information bounds, dist [Quantum Readout Rank Threshold](https://github.com/GoGoKo699/Quantum-Readout-Rank-Threshold) studies fixed coherent block size for preserving a uniform SLD-information fraction on moving-support state models. [Calibrated Quantum Readout](https://github.com/GoGoKo699/Calibrated-Quantum-Readout) studies calibrated single-copy readout on the full rank-r state tangent. The present source is full rank on a $`d^2`$-dimensional pair, but the unknown varies only along the $`d^2-1`$-dimensional unitary orbit generated on B. A restriction of the tangent model changes the estimation problem; neither generic state-readout conclusion can simply be substituted for the three coefficients above. +## Growing anonymous batches: theorem ownership and new consequence + +[Quantum Learning Correspondence](https://github.com/GoGoKo699/Quantum-Learning-Correspondence) takes the supplied source from this project and removes the matching through one hidden output permutation across the entire batch. Its [exact operator correlation kernel](https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/00d19bd0f60c6cd34ce4b77bb3268e52120efead/science/correlation-kernel.md) gives a size-independent information ceiling before measurement. That ceiling alone does not establish how much of the surviving information can be extracted through separate collective measurements of the lists. + +The general [separate-list sufficiency and Gaussian-equivalence theorem](https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/8edc63836384745aee80101722255154e562af8f/science/separate-list-readout.md) is owned by Correspondence. This repository gives its [application to the paired-learning source](../science/anonymous-batches.md), defines the readout-class boundary and supplies the original precision benchmarks and gate-loss normalization. The shared theorem is one discovery with complementary source roles, rather than independent copies of a theorem in two projects. + +At fixed local dimensions and uniformly strict correlation contraction, full quantum likelihood norms converge to the norms of a Gaussian covariance likelihood. Bounded local Fourier observables exhaust this limit. Glebsky's inherited simultaneous approximation then supplies target-independent commuting measurements separately on the two lists; local state preparation reconstructs the full anonymous state with vanishing uniform trace error. A reference-coupling argument identifies the full surviving experiment with one Gaussian covariance observation. Covariance convergence or fixed-batch estimation alone would not prove that operational conclusion. + +| Primary foundation | What is inherited | What it does not establish by itself | +| --- | --- | --- | +| [Glebsky 2010](#glebsky2010), Theorem 2 | For a fixed finite family of unitaries, small pairwise commutators in normalized Hilbert–Schmidt norm imply nearby commuting unitaries, uniformly in matrix dimension. | It supplies no anonymous-source likelihood saturation, target-independent statistical recovery, or efficient receiver compiler. The number of frequencies is fixed at each approximation level. | +| [Kuperberg 2005](#kuperberg2005) | The tracial quantum central-limit mechanism produces classical Gaussian fluctuation laws. | Convergence of polynomial distributions alone does not construct the required simultaneous local measurements or establish all-measurement sufficiency. The needed bounded Fourier expansions are proved directly in Correspondence. | +| [Yamagata–Fujiwara–Gill 2013](#yfg2013) | Local Gaussian mean-shift attainment for regular iid models, as used in the paired COLL proof. | The anonymous source is a globally indexed covariance experiment with bounded information as the batch grows. The existing local-shift theorem is not the new transfer. | +| [Petz 2008](#petz2008) | Channels, conditional expectations, statistical sufficiency, entropy and estimation provide the common educational language. | The book is not cited as proving the growing-anonymous-batch theorem. The [source bridge](../learning/ANCHOR_BRIDGE.md) supplies the project-specific steps. | + +The receiver retains coherent data and may entangle specimens within each list. It is different from the per-pair SEP class. The added conclusion controls bounded decisions and coherent bounded-score prediction at fixed dimension; no rate, efficient synthesis, dimension-growing guarantee, Fisher-information convergence, or arbitrary growing-number-of-batches coefficient follows. The [resource account](../science/resources.md) retains these costs and limits. + ## Bibliographic links ### werner1989 @@ -107,3 +124,15 @@ Marco Fanizza, Yihui Quek and Matteo Rosati, *Learning Quantum Processes Without Minsoo Kim and Changhun Oh, *On the fundamental resource for exponential advantage in quantum channel learning*, **Nature Communications 17**, 1822 (2026). [DOI](https://doi.org/10.1038/s41467-026-68532-y). The machine-readable bibliography is [references.bib](references.bib). + +### glebsky2010 + +Lev Glebsky, *Almost commuting matrices with respect to normalized Hilbert–Schmidt norm* (2010). [arXiv:1002.3082](https://arxiv.org/abs/1002.3082), Theorem 2. The paper calls its normalized Hilbert–Schmidt norm a normalized trace norm; it is distinct from the Schatten-one norm used for operational state error. + +### kuperberg2005 + +Greg Kuperberg, *A tracial quantum central limit theorem*, **Transactions of the American Mathematical Society 357**, 459–471 (2005). [arXiv:math-ph/0202035](https://arxiv.org/abs/math-ph/0202035). + +### petz2008 + +Dénes Petz, *Quantum Information Theory and Quantum Statistics*, first edition, Springer (2008). [DOI](https://doi.org/10.1007/978-3-540-74636-2). The common bridge uses §§9.1–9.2 and §9.5 for coarse-graining, conditional expectations and sufficiency; §§10.1–10.3 for estimation and Fisher information; and §§3.3–3.5 and §5.5 for entropy and Holevo information. diff --git a/science/README.md b/science/README.md index 994a6a9..bfa6a94 100644 --- a/science/README.md +++ b/science/README.md @@ -13,3 +13,9 @@ Read [the model](model.md) first. It fixes the source, gate loss, three acquisit The limiting order is part of the theorem: $`N\to\infty`$ at each fixed $`d`$ and fixed $`0\lt v\lt 1`$. The collective construction does not supply a useful uniform burn-in bound as dimension grows. The output is a classical unitary estimate, rather than an arbitrary channel hypothesis or a consumable quantum model. + +## When the correspondence is erased + +The [anonymous-batch application](anonymous-batches.md) changes the acquisition interface: one hidden output permutation removes the matching across a whole batch. At fixed dimension and visibility, separate collective measurements of the two lists preserve the full surviving experiment as that batch grows. The general sufficiency and Gaussian-equivalence theorem is owned by [Quantum Learning Correspondence](https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/8edc63836384745aee80101722255154e562af8f/science/separate-list-readout.md); this project supplies its application, the paired benchmarks and the loss normalization. + +Separate-list collective readout may preserve coherence within each list across many examples, so it is a different class from the per-pair SEP row. Its uniform vanishing reconstruction error controls bounded decisions. It supplies no convergence rate, Fisher-information limit or automatic coefficient comparison for arbitrarily many growing batches. The original three precision coefficients above retain their paired-interface hypotheses. diff --git a/science/anonymous-batches.md b/science/anonymous-batches.md new file mode 100644 index 0000000..059df87 --- /dev/null +++ b/science/anonymous-batches.md @@ -0,0 +1,112 @@ +# What survives a growing anonymous batch? + +Readout's precision hierarchy assumes that the learner knows which input specimen belongs to each output. If a single hidden permutation instead removes that correspondence across an increasingly large batch, the surviving information has a different measurement requirement. At fixed dimension and visibility, collective measurements of the input list and output list separately retain the full anonymous experiment asymptotically. Quantum coupling between the two lists supplies no persistent improvement to a bounded decision score in this limit. + +Each side may still couple all specimens in its own list. This collective local control differs from the original per-pair measurement restrictions. + +## The source and the two readout interfaces + +Fix $`d\ge2`$ and known $`0\lt v\lt1`$. Each supplied demonstration is + +```math +\rho_{U,v}=\frac{I+vF_U}{d(d+v)},\qquad +F_U=(I\otimes U)F(I\otimes U^\dagger), +``` + +with unknown $`U\in\mathrm{PU}(d)`$ and private preparation record. Both local marginals are $`I/d`$. An anonymous batch of $`b`$ pairs supplies + +```math +\Omega_{b,v}(U)=\frac1{b!}\sum_{\pi\in S_b} +(I\otimes P_\pi)\rho_{U,v}^{\otimes b} +(I\otimes P_\pi^\dagger) +``` + +in register order $`A_1\cdots A_bB_1\cdots B_b`$. The permutation, its purification and the preparation seeds are withheld. The two lists remain distinguishable. + +Unrestricted joint readout can process all $`2b`$ registers coherently. A **separate-list collective receiver** instead measures $`A^b`$ and $`B^b`$ with separate collective measurements and combines their outcomes classically. The construction below uses a product measurement $`M_b^A\otimes M_b^B`$, so even interactive classical communication during the measurements is unnecessary for sufficiency. + +The original SEP benchmark concerns separable effects within each identified pair, with classical records between pairs. It does not permit coherent processing across different pairs. Its precision coefficient cannot be substituted into this anonymous separate-list problem; the correspondence assumption and the permitted coherence both differ. + +## Application of the separate-list sufficiency theorem + +Choose a traceless Hermitian basis $`A_1,\ldots,A_p`$ with $`p=d^2-1`$ and $`\mathrm{Tr}(A_aA_c)=d\delta_{ac}`$. Then + +```math +\rho_{U,v}=\frac1{d^2} +\left(I+\sum_{a,c}T_{ac}(U)A_a\otimes A_c\right), +\qquad +T(U)=tR_U,\quad t=\frac{v}{d+v}, +``` + +Our coefficient convention is + +```math +(R_U)_{ac}=\frac1d\mathrm{Tr}(A_cUA_aU^\dagger), +\qquad +UA_aU^\dagger=\sum_c(R_U)_{ac}A_c. +``` + +Thus the row index labels the input observable and the column index the output observable. The matrix $`R_U`$ is real orthogonal, and $`T(U)`$ is exactly the cross-covariance matrix used below. The family $`\{T(U):U\in\mathrm{PU}(d)\}`$ is compact and has operator norm $`t<1`$. + +**Corollary.** There are target-independent local projective measurements $`M_b^A,M_b^B`$ and target-independent local state-preparation channels $`R_b^A,R_b^B`$. Write their product measurement-and-reconstruction channel as + +```math +E_b=(R_b^A\otimes R_b^B)(M_b^A\otimes M_b^B). +``` + +Then + +```math +\varepsilon_b:=\sup_U\left\Vert +\Omega_{b,v}(U)-E_b\bigl(\Omega_{b,v}(U)\bigr) +\right\Vert _1\longrightarrow0 +``` + +as $`b\to\infty`$, with $`d,v`$ fixed. The same measurement sequence works for every unknown $`U`$. + +The full anonymous experiment is also asymptotically equivalent, through target-independent channels, to one classical Gaussian covariance observation + +```math +(X,Y)\sim\mathcal N\!\left(0, +\begin{pmatrix}I_p&T(U)\\T(U)^{\mathsf T}&I_p\end{pmatrix}\right). +``` + +Each list's individual Gaussian marginal is independent of $`U`$; the parameter survives in their classical cross-correlation. This is one Gaussian observation per large anonymous batch, rather than a growing supply of independent observations. + +The general theorem and [complete proof](https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/8edc63836384745aee80101722255154e562af8f/science/separate-list-readout.md) belong to **Quantum Learning Correspondence**. Readout supplies the common paired learning task, loss normalization and precision benchmarks. The new implication uses Correspondence's exact operator collision kernel together with the inherited finite-family almost-commuting-unitary theorem of Glebsky. It is not an application of Readout's existing paired-copy local estimation theorem. + +The decisive proof step matches the entire normalized quantum likelihood norm to the Gaussian likelihood norm. Finite local Fourier observables then approximate the whole likelihood. Commuting approximants on each side give local spectral measurements; reconstruction prepares their normalized local spectral projectors. This proves recovery of the statistical experiment, whereas covariance convergence alone would not exclude surviving quantum information elsewhere in the batch. + +## What the corollary permits + +For any prior and any loss in $`[0,1]`$, every joint measurement-and-decision rule can be simulated from the separate-list records with a risk change of at most $`\varepsilon_b/2`$. In particular, if $`R_b^{\mathrm{joint}}`$ and $`R_b^{\mathrm{separate}}`$ denote the optimal risks on the same anonymous batch, + +```math +0\le R_b^{\mathrm{separate}}-R_b^{\mathrm{joint}} +\le\frac{\varepsilon_b}{2}\longrightarrow0. +``` + +This includes identification and average gate infidelity. The reconstruction also preserves bounded scores for a coherent processor that consumes the batch with one later input: trace-norm contractivity controls the induced channel, including reference inputs and every output branch. + +The information ceiling from one anonymous batch remains. Separate readout recovers the information that survives the shuffle; it does not restore the missing correspondence or establish consistent estimation from that single batch. + +## Limit order and charged resources + +First fix $`d`$ and $`v`$, then increase the anonymous batch size $`b`$. If $`m`$ independently shuffled batches have visible batch tags, the total supplied budget is $`mb`$ pairs and product reconstruction has error at most + +```math +m\varepsilon_b. +``` + +Every fixed $`m`$ is therefore covered as $`b\to\infty`$. A simultaneous limit with $`m=m(b)\to\infty`$ requires $`m(b)\varepsilon_b\to0`$, or an explicitly chosen diagonal schedule. No convergence rate is established. The bounded-risk comparison does not establish Fisher-information convergence, equality of high-precision coefficients, or a comparison after multiplying the loss by a diverging budget. + +The receiver retains $`b`$ specimens coherently on each side before its measurement; for $`d=2^n`$, this is $`bn`$ data qubits per list. It may use entangling control within a list, complicated collective spectral measurements, substantial classical records and computation, and initialized work. Those costs remain part of the resource account. The construction supplies no efficient circuit synthesis, storage compression, noise threshold or runtime advantage. It uses no hidden seed, matching record, chosen-input access or additional copies of a private specimen. + +A growing dimension, a contraction parameter approaching one, or parameter-dependent local marginals needs separate analysis. The existing paired precision theorem and its fixed-dimension order of limits remain unchanged. + +## Primary tools and ownership + +- The shared source and paired benchmarks are established in this project's [model](model.md) and [collective attainment](collective_attainment.md). +- The inherited anonymous model and exact collision kernel are pinned in [Quantum Learning Correspondence at `00d19bd`](https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/00d19bd0f60c6cd34ce4b77bb3268e52120efead/science/correlation-kernel.md). +- Lev Glebsky, *Almost commuting matrices with respect to normalized Hilbert–Schmidt norm*, [arXiv:1002.3082](https://arxiv.org/abs/1002.3082), Theorem 2, supplies simultaneous commuting approximation for a fixed finite family of unitaries. It is not a Schatten-one or operator-norm approximation theorem. +- The general separate-list sufficiency and Gaussian-equivalence theorem is developed in [Correspondence’s authoritative proof](https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/8edc63836384745aee80101722255154e562af8f/science/separate-list-readout.md). This page supplies its application to the paired-learning source. diff --git a/science/interpretation.md b/science/interpretation.md index 86b7473..9909ae8 100644 --- a/science/interpretation.md +++ b/science/interpretation.md @@ -47,6 +47,14 @@ The direction is specified by the learner's measurement, rather than by the sour Disclosing source preparations would therefore supply an additional classical resource and a different conditional statistical model. The present hierarchy does not give a sample bound for that disclosed-record experiment. It isolates the readout permissions when the preparation record remains private. +## What survives an anonymous shuffle + +[Quantum Learning Correspondence](https://github.com/GoGoKo699/Quantum-Learning-Correspondence) studies the same source when a hidden permutation removes which input belongs to which output across one entire batch. Its exact operator correlation kernel establishes a size-independent information ceiling. More pairs in that anonymous batch do not restore the original paired experiment. + +The [growing-batch application](anonymous-batches.md) answers a different question from that ceiling: can separate collective readouts capture everything that still survives? At fixed dimension and known visibility, they can. Target-independent measurements on each coherent list admit local reconstruction of the whole anonymous state with uniform trace-norm error tending to zero. The surviving experiment is asymptotically equivalent to one classical Gaussian covariance observation, with the unitary in its cross-correlation. Quantum coupling between the two lists therefore gives no persistent bounded-decision advantage in this limit. + +This conclusion does not contradict the paired precision hierarchy. The original SEP restriction permits no quantum memory between pairs; the anonymous receiver may keep each full list coherent. Its acquisition interface has also lost the matching. For independently tagged batches, tensorization bounds the reconstruction error by the number of batches times the one-batch error. Without a rate, bounded-decision equivalence gives neither Fisher-information convergence nor a new high-precision coefficient. The general theorem and proof are owned by [Correspondence](https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/8edc63836384745aee80101722255154e562af8f/science/separate-list-readout.md). + ## What the dimension dependence establishes The central theorem first fixes $`d`$ and $`v`$ and then takes the number of independent pairs to infinity: diff --git a/science/model.md b/science/model.md index 521290c..9137d77 100644 --- a/science/model.md +++ b/science/model.md @@ -81,7 +81,7 @@ SEP includes arbitrary local operations and classical communication within one p In SEP and PAIR, the measurement chosen for a new pair may depend on the entire previous classical transcript. Ancillas and within-pair operations are allowed subject to the displayed readout restriction. No quantum output persists into the next pair. -A joint measurement that is separable only across $`A^{\otimes N}:B^{\otimes N}`$, while storing and processing many $`A`$ registers coherently, is not the SEP class defined here. No converse for that larger class is asserted. +A joint measurement that is separable only across $`A^{\otimes N}:B^{\otimes N}`$, while storing and processing many $`A`$ registers coherently, is not the SEP class defined here. No converse for that larger class is asserted. The [growing anonymous-batch application](anonymous-batches.md) studies separate collective measurements of the two lists after a hidden shuffle has removed their pairings. It does not extend the SEP converse to that class on the paired acquisition interface. ## Risk and limiting order diff --git a/science/resources.md b/science/resources.md index 7dc6e69..486b822 100644 --- a/science/resources.md +++ b/science/resources.md @@ -36,6 +36,14 @@ The random pure state can be entangled among the qubits inside a register. The s A straightforward collective implementation stores $`2nN`$ specimen qubits, plus measurement workspace. The theorem does not prove this width necessary or optimize a memory-versus-precision frontier. A global measurement separable across $`A^N:B^N`$ with coherent storage within each side is a different class from per-pair separable readout. +## Separate collective readout after an anonymous shuffle + +The [anonymous-batch receiver](anonymous-batches.md) retains all $`b`$ input specimens coherently on one side and all $`b`$ output specimens on the other. For $`d=2^n`$, this is $`nb`$ data qubits per side before measurement, plus initialized work. It permits entangling control within each list. Its two list measurements require no quantum interaction between the lists; their records are combined classically. + +The construction uses spectral measurements of commuting approximants to finite Fourier families and a slow diagonal schedule. Charge those collective controls, measurement synthesis and accuracy, data retention time, classical records and computation. The existence theorem supplies no efficient compiler, compressed-memory realization, noise tolerance or runtime advantage. Local reconstruction prepares normalized spectral projectors from the classical records; this is a physical target-independent channel and supplies no hidden source record. + +If $`m`$ independently shuffled batches carry visible batch tags, the supplied budget is $`mb`$ pairs, including every specimen. Product reconstruction error is at most $`m\varepsilon_b`$, where $`\varepsilon_b\to0`$ at fixed $`d,v`$ as $`b\to\infty`$. This covers fixed $`m`$ and schedules with $`m\varepsilon_b\to0`$. No rate or automatically valid arbitrarily growing batch-count limit is provided. Preparation seeds, permutation records and purifications remain inaccessible, and no chosen-input calls or source replay are supplied. + ## A normalized POVM is an actual operation The [optimal joint-pair measurement](joint_pair_readout.md) is a normalized covariant POVM. Sampling a random orbit vector, testing its rank-one projector and retaining only successes implements a different experiment. Its unsuccessful attempts cannot be dropped or supplied for free. diff --git a/verification/README.md b/verification/README.md index 38a4a51..96f5914 100644 --- a/verification/README.md +++ b/verification/README.md @@ -5,10 +5,13 @@ Run with Python 3.10 or newer and the pinned NumPy dependency: ```bash python3 -m pip install -r verification/requirements.txt python3 verification/run_all.py +python3 verification/check_navigation.py ``` The deterministic script writes [results.json](results.json), including its own SHA256, environment, seed, numerical tolerances and per-check residuals. A failed inequality or residual raises an exception and the command exits unsuccessfully. The suite uses direct small density matrices and Born probabilities; its numerical derivative is formed separately from the analytical SLD formula. +The navigation script writes [structure_results.json](structure_results.json) and accepts a different JSON destination with `--output`. It checks relative Markdown destinations and heading fragments, balanced fenced blocks, and exactly thirty ordered M01–M30 headings in the learning map. This source check does not inspect external links or actual hosted rendering. + The checks cover: - Trace, positivity and maximally mixed marginal of the full-rank source at dimensions 2, 3, 4 and 5 and correlation parameters 0.1, 0.5 and 0.9. @@ -19,3 +22,11 @@ The checks cover: - The two successive asymptotic coefficient ratios. The finite checks support algebra, phases, normalization and explicit constructions. Universal separable/joint measurement bounds rest on the positivity, antisymmetric singular-value and concavity proofs. Global biased converses rest on the group integration-by-parts argument. Collective attainability rests on the cited local theorem and the written localization proof. The script neither establishes those universal statements nor certifies novelty, a useful finite-sample threshold, gate efficiency or actual hosted mathematical rendering. + +## Growing anonymous batches + +The [anonymous-batch application](../science/anonymous-batches.md) uses the general theorem owned by Quantum Learning Correspondence. Its [finite Fourier diagnostic](https://github.com/GoGoKo699/Quantum-Learning-Correspondence/blob/8edc63836384745aee80101722255154e562af8f/verification/README.md) independently checks direct anonymous density matrices against the likelihood-residual, characteristic-function, collision-kernel and Gaussian-limit formulas. It includes noncommuting qubit target hypotheses and separates direct small matrices from larger exact tensor formulas. + +Those computations check identities and normalization. They construct neither a commuting-approximant receiver nor Gaussian conversion kernels and do not prove the uniform recovery theorem. The theorem's operational step is analytical: equality of the full likelihood norm excludes a residual component, and the inherited almost-commuting-unitary theorem supplies separate local spectral measurements. This is a different argument from the original paired-copy Fisher-information tests. + +No exact finite-batch sufficiency, efficient circuit synthesis, growing-dimension guarantee, Fisher-information convergence or arbitrary simultaneous many-batch limit is inferred. For $`m`$ independently tagged batches, the stated reconstruction comparison requires control of $`m\varepsilon_b`$. A small bounded-risk difference alone cannot establish equality of precision coefficients after rescaling by a diverging sample budget. diff --git a/verification/check_navigation.py b/verification/check_navigation.py new file mode 100644 index 0000000..0b4cc80 --- /dev/null +++ b/verification/check_navigation.py @@ -0,0 +1,124 @@ +#!/usr/bin/env python3 +"""Check repository-local Markdown navigation and the thirty-milestone map. + +This source check does not establish mathematical correctness or hosted rendering. +""" +from __future__ import annotations + +import argparse +from datetime import datetime, timezone +import hashlib +import html +import json +from pathlib import Path +import re +import unicodedata +from urllib.parse import unquote, urlsplit + + +def visible_markdown(text: str) -> tuple[str, bool]: + """Remove fenced blocks while reporting an unclosed fence.""" + rows = [] + fence = None + for row in text.splitlines(): + match = re.match(r"^ {0,3}(`{3,}|~{3,})", row) + if match: + token = match.group(1) + if fence is None: + fence = token + elif token[0] == fence[0] and len(token) >= len(fence): + fence = None + rows.append("") + else: + rows.append(row if fence is None else "") + return "\n".join(rows), fence is None + + +def slug(text: str) -> str: + text = html.unescape(re.sub(r"<[^>]+>", "", text)).strip().lower() + text = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", text) + text = text.replace("`", "") + text = "".join(c for c in text + if c in "-_ " or unicodedata.category(c)[0] not in "PS") + return text.replace(" ", "-") + + +def anchors(text: str) -> set[str]: + result = set(re.findall(r' list[str]: + # The scientific account uses ordinary inline links; reference definitions + # are included as destinations too, should that notation be introduced. + plain = re.sub(r"(`+).*?\1", "", text) + inline = re.findall(r"\[[^\]]*\]\((<[^>]+>|[^\s)]+)(?:\s+[^)]*)?\)", plain) + defined = re.findall(r"^ {0,3}\[[^\]]+\]:\s*(<[^>]+>|\S+)", plain, re.MULTILINE) + return [value[1:-1] if value.startswith("<") else value for value in inline + defined] + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--output", type=Path, + default=Path(__file__).with_name("structure_results.json")) + args = parser.parse_args() + root = Path(__file__).resolve().parents[1] + files = sorted(path for path in root.rglob("*.md") if ".git" not in path.parts) + errors = [] + texts = {} + anchor_map = {} + for path in files: + text, balanced = visible_markdown(path.read_text(encoding="utf-8")) + texts[path] = text + anchor_map[path] = anchors(text) + if not balanced: + errors.append(f"{path.relative_to(root)}: unclosed fenced block") + checked = 0 + for source, text in texts.items(): + for destination in destinations(text): + parsed = urlsplit(destination) + if parsed.scheme or parsed.netloc: + continue + target = (source.parent / unquote(parsed.path)).resolve() if parsed.path else source + checked += 1 + if not target.is_relative_to(root): + errors.append(f"{source.relative_to(root)}: destination leaves repository {destination}") + continue + if not target.exists(): + errors.append(f"{source.relative_to(root)}: missing destination {destination}") + elif parsed.fragment and target.suffix.lower() == ".md": + if unquote(parsed.fragment) not in anchor_map.get(target, set()): + errors.append(f"{source.relative_to(root)}: missing heading {destination}") + map_path = root / "learning/MILESTONES.md" + milestone_ids = [] + if map_path.exists(): + milestone_ids = re.findall(r"^#{2,6}\s+(M\d{2})\b", texts[map_path], re.MULTILINE) + expected = [f"M{i:02d}" for i in range(1, 31)] + if milestone_ids != expected: + errors.append("learning/MILESTONES.md: milestone headings must be M01 through M30, once each in order") + report = { + "status": "passed" if not errors else "failed", + "generated_at_utc": datetime.now(timezone.utc).isoformat(), + "script_sha256": hashlib.sha256(Path(__file__).read_bytes()).hexdigest(), + "markdown_files": len(files), "checked_local_links": checked, + "markdown_sha256": {str(path.relative_to(root)): hashlib.sha256(path.read_bytes()).hexdigest() + for path in files}, + "milestone_headings": milestone_ids, "errors": errors, + "scope": "All current Markdown files: repository-local destinations, Markdown heading fragments, fenced-block balance, and exactly thirty ordered M01–M30 milestone headings. External links, scientific truth, pedagogical quality, and actual hosted mathematics/layout are outside this check.", + } + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8") + print(json.dumps({key: value for key, value in report.items() + if key not in ("milestone_headings", "markdown_sha256", "scope", "script_sha256", "generated_at_utc")})) + if errors: + raise SystemExit(1) + + +if __name__ == "__main__": + main() diff --git a/verification/hosted_math/README.md b/verification/hosted_math/README.md new file mode 100644 index 0000000..ed5d94d --- /dev/null +++ b/verification/hosted_math/README.md @@ -0,0 +1,18 @@ +# Hosted mathematical review + +The collector checks actual commit-pinned GitHub rendering at widths 1440 and 760 pixels. It inventories each Markdown expression, compiles reference MathML, captures the hosted MathML and compares expression counts, structure, relations, labels and display geometry. A successful automated report still requires source comparison and visual inspection of the saved screenshots. + +The same-repository pull-request workflow first probes the README, then captures every tracked Markdown page at the exact proposed commit. It uses only `contents: read`, no secret inputs, and a checkout without persisted credentials. The capture dependencies are Playwright 1.56.1 and MathJax 3.2.1. Artifacts have finite retention and do not provide permanent research preservation. + +To reproduce in an environment with Git, Python 3.10+, Node 18+, compatible Playwright/Chromium and MathJax installed: + +```bash +node verification/hosted_math/probe_hosted_math.cjs \ + --root "$PWD" --repository GoGoKo699/Quantum-Learning-Readout \ + --revision FULL_COMMIT_SHA --page README.md --output /tmp/readout-probe +node verification/hosted_math/capture_hosted_math.cjs \ + --root "$PWD" --repository GoGoKo699/Quantum-Learning-Readout \ + --revision FULL_COMMIT_SHA --output /tmp/readout-capture +``` + +Replace `FULL_COMMIT_SHA` with the exact observed commit and use new empty output directories. The supplied helper set is kept together so its capture and validation contracts agree. A local compiler pass, an early sample, an uninspected screenshot or a green workflow badge alone does not establish final rendered/source agreement. Failed attempts must remain distinguishable from later successful checks. No independent scientific proof or cross-browser rendering certification is implied. diff --git a/verification/hosted_math/capture_hosted_math.cjs b/verification/hosted_math/capture_hosted_math.cjs new file mode 100644 index 0000000..6f36ee0 --- /dev/null +++ b/verification/hosted_math/capture_hosted_math.cjs @@ -0,0 +1,549 @@ +#!/usr/bin/env node +'use strict'; +// Read-only collector for the real GitHub host. See ../references/hosted-rendering.md. +// Importing this module has no network effects; dependencies load only in run(). +const fs = require('node:fs'); +const path = require('node:path'); +const cp = require('node:child_process'); +const crypto = require('node:crypto'); +const VIEWPORTS = [{width:1440,height:1000}, {width:760,height:1000}]; +const RENDER_TIMEOUT_MS = 30000; +const sha256 = bytes => crypto.createHash('sha256').update(bytes).digest('hex'); + +function argumentsFor(argv) { + const args = {pages:[], python:'python3'}; + for (let i=0; i['.','..'].includes(p))) throw new Error('Use exact owner/name'); + if (!/^[a-f0-9]{40}$/.test(args.revision)) throw new Error('Use a full lowercase commit SHA'); + if (new Set(args.pages).size!==args.pages.length || args.pages.some(p=>!safePath(p))) throw new Error('Use unique safe page paths'); + return args; +} +function safePath(p) { + return typeof p==='string' && p.length>0 && !p.includes('\\') && !p.includes('\0') && + !p.startsWith('/') && p.split('/').every(x=>x && x!=='.' && x!=='..'); +} +function git(root, argv) { + return cp.execFileSync('git',['--no-replace-objects',...argv],{cwd:root,encoding:'utf8',maxBuffer:32*1024*1024}); +} +function pinnedPages(args) { + const commit=git(args.root,['rev-parse',args.revision+'^{commit}']).trim(); + if (commit!==args.revision) throw new Error('Revision does not identify the supplied commit'); + const files=git(args.root,['ls-tree','-r','--name-only','-z',commit]).split('\0').filter(Boolean); + const pages=args.pages.length?args.pages:files.filter(p=>/\.(md|markdown|mdown|mkdn|mkd)$/i.test(p)); + if (!pages.length || pages.some(p=>!safePath(p) || !files.includes(p))) throw new Error('No pages or a page is absent from the pinned tree'); + // Git symlinks are not rendered Markdown source and must not be followed. + for (const p of pages) { + const item=git(args.root,['ls-tree',commit,'--',p]); + if (!/^100644 blob |^100755 blob /.test(item)) throw new Error('Page must be a regular tracked file: '+p); + } + return {pages,tree:git(args.root,['rev-parse',commit+'^{tree}']).trim()}; +} +function mathCompiler() { + const {mathjax}=require('mathjax-full/js/mathjax.js'); + const {TeX}=require('mathjax-full/js/input/tex.js'); + const {SVG}=require('mathjax-full/js/output/svg.js'); + const {liteAdaptor}=require('mathjax-full/js/adaptors/liteAdaptor.js'); + const {RegisterHTMLHandler}=require('mathjax-full/js/handlers/html.js'); + const {AllPackages}=require('mathjax-full/js/input/tex/AllPackages.js'); + const {SerializedMmlVisitor}=require('mathjax-full/js/core/MmlTree/SerializedMmlVisitor.js'); + const {STATE}=require('mathjax-full/js/core/MathItem.js'); + RegisterHTMLHandler(liteAdaptor()); + const doc=mathjax.document('',{InputJax:new TeX({packages:AllPackages,tags:'none'}),OutputJax:new SVG({fontCache:'none'})}); + const visitor=new SerializedMmlVisitor(); + return (tex,display)=>visitor.visitTree(doc.convert(tex,{display,end:STATE.CONVERT})); +} + +// Self-contained function executed inside the hosted page, also exercised by the +// local-browser regression fixture. It never injects styling or renders TeX there. +function inspectArticle(root, expected) { + function canonical(e, inherited='') { + const tag=e.localName; + if (['annotation','annotation-xml','mspace'].includes(tag)) return []; + const variant=e.getAttribute('mathvariant') || inherited; + if (['mi','mo','mn','mtext','ms'].includes(tag)) { + const text=e.textContent.trim(); + return text?[[tag,text,variant]]:[]; + } + // Preserve each structural child slot: flattening numerator and denominator + // together would confuse (a+b)/c with a/(b+c), and similarly for scripts. + const children=[...e.children].filter(c=>!['annotation','annotation-xml','mspace'].includes(c.localName)) + .map(c=>canonical(c,variant)); + if (['math','mrow','mstyle','semantics'].includes(tag)) return children.flat(); + const semantic={}; + for (const name of ['notation','accent','accentunder','linethickness','bevelled','open','close','separators']) if(e.hasAttribute(name)) semantic[name]=e.getAttribute(name); + // A table cell is an inferred row (a sequence), not a fixed-arity operator. + // GitHub inserts empty mrow alignment nodes; ignore those inside the cell + // while preserving the cell and row themselves, including empty cells. + return [[tag,semantic,tag==='mtd'?children.flat():children]]; + } + function plain(math) { + const copy=math.cloneNode(true); + for (const e of copy.querySelectorAll('annotation,annotation-xml')) e.remove(); + return copy.textContent; + } + function geometry(math, host) { + const boxes=[...math.querySelectorAll('mi,mo,mn,mtext,ms')].map(e=>e.getBoundingClientRect()).filter(b=>b.width && b.height); + if (!boxes.length) return {measurable:false}; + const left=Math.min(...boxes.map(b=>b.left)),right=Math.max(...boxes.map(b=>b.right)); + const top=Math.min(...boxes.map(b=>b.top)),bottom=Math.max(...boxes.map(b=>b.bottom)); + const width=right-left,height=bottom-top; + return {measurable:true,width,height,available_width:root.clientWidth, + overflow:width>root.clientWidth+4,collapsed:height>Math.max(200,3*width),host_width:host.getBoundingClientRect().width}; + } + let hosts=[...root.querySelectorAll('math-renderer')]; + // Some host versions expose native MathML without a custom-element wrapper. + if (!hosts.length) hosts=[...root.querySelectorAll('math')].filter(e=>!e.parentElement?.closest('math,annotation,annotation-xml')); + const pageErrors=[...root.querySelectorAll('merror,[data-mjx-error],.katex-error,math-renderer .flash-error')] + .map(e=>e.textContent.trim() || 'empty renderer error'); + const math=hosts.map((host,i)=>{ + const nodes=host.localName==='math'?[host]:[...host.querySelectorAll('math')].filter(e=>!e.parentElement?.closest('math,annotation,annotation-xml')); + const errors=[]; + if(nodes.length!==1) errors.push('Expected one accessible MathML representation; found '+nodes.length); + const actual=nodes[0],want=expected[i]; + let expectedSignature=null,actualSignature=null; + if(actual) actualSignature=JSON.stringify(canonical(actual)); + if(want) { + const parsed=new DOMParser().parseFromString(want.mml,'application/xml'); + if(parsed.querySelector('parsererror,merror')) errors.push('Source compiler returned invalid/error MathML'); + else expectedSignature=JSON.stringify(canonical(parsed.documentElement)); + } + if(!want) errors.push('Unexpected extra hosted expression'); + const match=!!actual && !!expectedSignature && expectedSignature===actualSignature; + if(!match) errors.push('Source-to-host MathML structure mismatch'); + const measure=actual?geometry(actual,host):{measurable:false}; + if(want && ['math-fence','dollar-display'].includes(want.kind) && (!measure.measurable || measure.overflow || measure.collapsed)) + errors.push('Display geometry is unmeasurable, overflowing or collapsed'); + return {rendered:!!actual,errors,text_source:'mathml',text:actual?plain(actual):'', + source_sha256:want?.source_sha256,structural_match:match, + expected_signature:expectedSignature,actual_signature:actualSignature,geometry:measure}; + }); + return {errors:pageErrors,math}; +} + +// Self-contained, read-only page probe. Presence of a custom-element placeholder +// is not readiness; wait for the accessible representation used by inspection. +function hostedMathReadiness(root, expectedCount) { + const errors=[...root.querySelectorAll('merror,[data-mjx-error],.katex-error,math-renderer .flash-error')] + .map(e=>e.textContent.trim() || 'empty renderer error'); + let hosts=[...root.querySelectorAll('math-renderer')]; + if(!hosts.length) hosts=[...root.querySelectorAll('math')] + .filter(e=>!e.parentElement?.closest('math,annotation,annotation-xml')); + let usable=0; + for(const host of hosts) { + const nodes=host.localName==='math'?[host]:[...host.querySelectorAll('math')] + .filter(e=>!e.parentElement?.closest('math,annotation,annotation-xml')); + if(nodes.length!==1) continue; + const copy=nodes[0].cloneNode(true); + for(const annotation of copy.querySelectorAll('annotation,annotation-xml')) annotation.remove(); + if(copy.textContent.trim() && copy.querySelector('mi,mo,mn,mtext,ms')) usable++; + } + return {ready:errors.length===0 && hosts.length===expectedCount && usable===expectedCount, + errors,expected_hosts:expectedCount,observed_hosts:hosts.length,usable_hosts:usable}; +} + +async function waitForHostedMath(article, expectedCount, options={}) { + const timeoutMs=options.timeoutMs ?? RENDER_TIMEOUT_MS, intervalMs=options.intervalMs ?? 100; + if(!Number.isFinite(timeoutMs) || timeoutMs<=0 || timeoutMs>RENDER_TIMEOUT_MS || + !Number.isFinite(intervalMs) || intervalMs<=0 || intervalMs>timeoutMs || + !Number.isInteger(expectedCount) || expectedCount<0) + throw new Error('Invalid bounded hosted-math readiness wait'); + // Clock/delay injection is for deterministic offline adapters; production uses + // a monotonic clock and an explicitly bounded poll budget. + const now=options.now || (()=>performance.now()); + const delay=options.delay || (ms=>new Promise(resolve=>setTimeout(resolve,ms))); + const started=now(), maxPolls=Math.ceil(timeoutMs/intervalMs)+1; + let state; + for(let poll=0;poll{timer=setTimeout(()=>reject(new Error( + 'Hosted mathematics readiness evaluation exceeded its bounded budget')),evaluationBudget)}), + ]); + } finally {clearTimeout(timer);} + if(state.errors.length) throw new Error('Hosted mathematics renderer error: '+state.errors.join('; ')); + if(state.ready) return state; + const remaining=timeoutMs-(now()-started); + if(remaining<=0 || poll===maxPolls-1) break; + await delay(Math.min(intervalMs,remaining)); + } + // This is a verification failure, not evidence of a transport interruption + // eligible for blind capture resume. Missing/malformed hosts never pass. + throw new Error('Hosted mathematics readiness failed after '+timeoutMs+' ms: expected '+expectedCount+ + ' hosts; observed '+state?.observed_hosts+'; usable '+state?.usable_hosts); +} + +function classifyFailure(error) { + const message=String(error); + if (/ERR_BLOCKED_BY_ADMINISTRATOR|blocked by.*policy|URLBlocklist|policy denied/i.test(message)) return 'policy_denied'; + if (/HTTP (401|403)|redirected away|sign.in|authentication/i.test(message)) return 'access_required'; + if (/Cannot find module|Executable doesn't exist|browser executable/i.test(message)) return 'capability_unavailable'; + if (/HTTP (429|5[0-9]{2})|ERR_NAME_NOT_RESOLVED|ENOTFOUND|ERR_CONNECTION|ERR_EMPTY_RESPONSE|ERR_INTERNET_DISCONNECTED|ECONNRESET|Timeout|timed out/i.test(message)) return 'transport_failure'; + return 'verification_failure'; +} +function writeJSON(filename, value) {fs.writeFileSync(filename,JSON.stringify(value,null,2)+'\n');} +function artifact(directory, relative, kind) { + const bytes=fs.readFileSync(path.join(directory,relative)); + return {path:relative,sha256:sha256(bytes),size_bytes:bytes.length,kind}; +} +function boundReport(inventory, tree, viewports, artifacts, failures, at) { + const boundaries=inventory.pages.map(p=>{ + const counts=viewports.map(v=>v.boundaries?.find(b=>b.path===p.path)?.captured_hosts); + return {path:p.path,url:p.url,revision:inventory.revision,source_sha256:p.source_sha256, + source_expressions:p.expressions.length, + captured_hosts:counts.length===VIEWPORTS.length && counts.every(n=>Number.isInteger(n) && n===counts[0])?counts[0]:null}; + }); + const wanted=inventory.pages.reduce((n,p)=>n+p.expressions.length,0); + failures=[...failures]; + if(JSON.stringify(viewports.map(v=>({width:v.width,height:v.height})))!==JSON.stringify(VIEWPORTS)) + failures.push('Missing, duplicate or unexpected viewport coverage'); + for(const viewport of viewports) { + if(JSON.stringify((viewport.boundaries||[]).map(b=>b.path))!==JSON.stringify(inventory.pages.map(p=>p.path))) + failures.push(viewport.width+': page coverage differs from inventory'); + for(const source of inventory.pages) { + const boundary=viewport.boundaries?.find(b=>b.path===source.path); + if(!boundary || boundary.source_sha256!==source.source_sha256 || boundary.revision!==inventory.revision || + boundary.url!==source.url || boundary.source_expressions!==source.expressions.length || boundary.captured_hosts!==source.expressions.length) + failures.push(viewport.width+': incomplete source/host coverage for '+source.path); + } + } + const structural=viewports.length===VIEWPORTS.length && viewports.every(v=>v.structural_matches===wanted); + const pass=!failures.length && structural && viewports.length===VIEWPORTS.length && viewports.every(v=>v.status==='pass'); + return {schema_version:1,kind:'hosted_math',repository:inventory.repository,revision:inventory.revision,tree, + renderer_profile:'github',captured_at:at,capture_method:'playwright-github',status:pass?'pass':'fail', + required_pages:inventory.pages.map(p=>p.path),boundaries,viewports,artifacts,failures, + structural_comparison:{status:structural?'pass':'fail',expressions_checked:structural?wanted:0}, + visual_review_required:true, + limits:'Observed GitHub MathML structure, counts, labels, relations and bounded geometry only. No independent scientific proof, exhaustive pixel review, host authenticity certificate or cross-browser guarantee.'}; +} + +// Resume is an explicit new attempt against identical source and execution inputs. +// Receipts bind observations, not authenticity: the final visual review is separate. +const RESUME_MAX_AGE_MS = 24*60*60*1000; +const MAX_EVIDENCE_BYTES = 32*1024*1024; +function safeEvidenceFile(directory, relative) { + if(!safePath(relative)) throw new Error('Unsafe evidence path: '+relative); + const root=path.resolve(directory); + if(fs.lstatSync(root).isSymbolicLink() || !fs.statSync(root).isDirectory()) + throw new Error('Evidence root must be a regular directory'); + let current=root; + for(const component of relative.split('/')) { + current=path.join(current,component); + if(fs.lstatSync(current).isSymbolicLink()) throw new Error('Symlink evidence is not reusable: '+relative); + } + const stat=fs.statSync(current); + if(!stat.isFile() || stat.size>MAX_EVIDENCE_BYTES) throw new Error('Evidence must be a bounded regular file: '+relative); + return current; +} +function readBoundArtifact(directory, descriptor) { + if(!descriptor || typeof descriptor.path!=='string' || !/^[a-f0-9]{64}$/.test(descriptor.sha256) || + !Number.isInteger(descriptor.size_bytes) || descriptor.size_bytes<0) + throw new Error('Malformed evidence artifact descriptor'); + const bytes=fs.readFileSync(safeEvidenceFile(directory,descriptor.path)); + if(bytes.length!==descriptor.size_bytes || sha256(bytes)!==descriptor.sha256) + throw new Error('Evidence artifact hash/size mismatch: '+descriptor.path); + return bytes; +} +function observationTime(value, now=Date.now()) { + const parsed=typeof value==='string' && /(?:Z|[+-]\d{2}:\d{2})$/.test(value)?Date.parse(value):NaN; + if(!Number.isFinite(parsed) || parsed>now || now-parsed>RESUME_MAX_AGE_MS) + throw new Error('Capture observation is stale, future-dated or lacks a timezone'); + return parsed; +} +function pageKey(page, viewport) {return viewport.width+'x'+viewport.height+':'+page;} +function capturePassed(source, item) { + return item && item.path===source.path && item.url===source.url && + item.revision===source.revision && item.source_sha256===source.source_sha256 && + Array.isArray(item.errors) && item.errors.length===0 && Array.isArray(item.math) && + item.math.length===source.expressions.length && item.math.every((m,index)=> + m.rendered===true && Array.isArray(m.errors) && m.errors.length===0 && m.structural_match===true && + m.source_sha256===source.expressions[index].source_sha256 && + typeof m.expected_signature==='string' && m.expected_signature.length>0 && + m.expected_signature===m.actual_signature); +} +function sessionBinding(inventory, tree, expectedBytes, contractBytes, runtime, helper, diagnosticOnly=false, inventoryBytes=null) { + return {repository:inventory.repository,revision:inventory.revision,tree, + inventory_sha256:sha256(inventoryBytes || Buffer.from(JSON.stringify(inventory,null,2)+'\n')), + expected_sha256:sha256(expectedBytes),contract_sha256:sha256(contractBytes),has_contract:contractBytes.toString('utf8')!=='null', + collector_sha256:sha256(fs.readFileSync(__filename)),checker_sha256:sha256(fs.readFileSync(helper)), + runtime,viewports:VIEWPORTS,purpose:diagnosticOnly?'diagnostic':'release_verification'}; +} +function newSession(binding, at) { + return {schema_version:1,kind:'hosted_math_session',binding,started_at:at,updated_at:at, + completed:[],failures:[]}; +} +function saveSession(output, session) { + const temporary=path.join(output,'capture-state.json.tmp'); + writeJSON(temporary,session);fs.renameSync(temporary,path.join(output,'capture-state.json')); +} +function loadResume(directory, binding, inventory, now=Date.now()) { + const bytes=fs.readFileSync(safeEvidenceFile(directory,'capture-state.json')); + const session=JSON.parse(bytes.toString('utf8')); + if(session.schema_version!==1 || session.kind!=='hosted_math_session' || + JSON.stringify(session.binding)!==JSON.stringify(binding)) + throw new Error('Resume source, scope, contract, collector/checker or runtime binding differs'); + if(!Array.isArray(session.failures) || session.failures.some(f=>f.category!=='transport_failure')) + throw new Error('Resume refused after a nontransient, policy or access failure; preserve that attempt and resolve its actual cause'); + if(!Array.isArray(session.completed)) throw new Error('Malformed completed-capture receipts'); + const sourceByPath=new Map(inventory.pages.map(p=>[p.path,{...p,revision:inventory.revision}])); + const reusable=new Map(); + for(const descriptor of session.completed) { + const receiptBytes=readBoundArtifact(directory,descriptor.receipt); + const receipt=JSON.parse(receiptBytes.toString('utf8')); + const source=sourceByPath.get(receipt.path); + const viewport=VIEWPORTS.find(v=>v.width===receipt.viewport?.width && v.height===receipt.viewport?.height); + if(!source || !viewport || receipt.schema_version!==1 || receipt.kind!=='hosted_math_page' || receipt.status!=='pass' || + receipt.repository!==inventory.repository || receipt.revision!==inventory.revision || + receipt.tree!==binding.tree || receipt.source_sha256!==source.source_sha256 || + receipt.key!==pageKey(source.path,viewport) || !capturePassed(source,receipt.capture) || + receipt.capture.observed_at!==receipt.observed_at || !Array.isArray(receipt.artifacts)) + throw new Error('Invalid or mismatched passing page receipt'); + observationTime(receipt.observed_at,now); + if(descriptor.key!==receipt.key || reusable.has(receipt.key)) throw new Error('Duplicate or mismatched page receipt key'); + const prefix=String(inventory.pages.findIndex(p=>p.path===source.path)+1).padStart(4,'0')+'-'+viewport.width; + if(descriptor.receipt.path!==prefix+'-receipt.json') throw new Error('Unexpected page receipt artifact path'); + const expectedArtifacts=new Map([ + [prefix+'-source.json','page_source_inventory'],[prefix+'-capture.json','page_hosted_capture'], + [prefix+'-result.json','page_math_result'],[prefix+'.html','hosted_html'],[prefix+'.png','screenshot']]); + if(binding.has_contract) expectedArtifacts.set(prefix+'-contract.json','page_text_contract'); + const artifactPaths=new Set(); + const payloads=receipt.artifacts.map(a=>{ + if(artifactPaths.has(a.path) || expectedArtifacts.get(a.path)!==a.kind) throw new Error('Duplicate or unexpected receipt artifact path'); + artifactPaths.add(a.path);return {descriptor:a,bytes:readBoundArtifact(directory,a)}; + }); + if(artifactPaths.size!==expectedArtifacts.size) throw new Error('Incomplete page artifact set'); + const resultArtifact=payloads.find(a=>a.descriptor.kind==='page_math_result'); + const captureArtifact=payloads.find(a=>a.descriptor.kind==='page_hosted_capture'); + const sourceArtifact=payloads.find(a=>a.descriptor.kind==='page_source_inventory'); + const result=resultArtifact?JSON.parse(resultArtifact.bytes.toString('utf8')):null; + const capture=captureArtifact?JSON.parse(captureArtifact.bytes.toString('utf8')):null; + const sourceInventory=sourceArtifact?JSON.parse(sourceArtifact.bytes.toString('utf8')):null; + if(result?.status!=='pass' || !Array.isArray(result.failures) || result.failures.length || + result.repository!==inventory.repository || result.revision!==inventory.revision || + result.captured_at!==receipt.observed_at || result.boundaries?.length!==1 || + result.boundaries[0].path!==source.path || result.boundaries[0].url!==source.url || + result.boundaries[0].revision!==inventory.revision || result.boundaries[0].source_expressions!==source.expressions.length || + result.boundaries[0].source_sha256!==source.source_sha256 || + result.boundaries[0].captured_hosts!==source.expressions.length || + result.expressions_checked!==source.expressions.length || + capture?.pages?.length!==1 || JSON.stringify(capture.pages[0])!==JSON.stringify(receipt.capture) || + capture.schema_version!==1 || capture.capture_method!=='playwright-github' || capture.renderer_profile!=='github' || + capture.captured_at!==receipt.observed_at || capture.repository!==inventory.repository || + capture.revision!==inventory.revision || + JSON.stringify(sourceInventory)!==JSON.stringify({...inventory,pages:[inventory.pages.find(p=>p.path===source.path)]}) || + !payloads.some(a=>a.descriptor.path===receipt.capture.artifacts?.html && a.descriptor.kind==='hosted_html') || + !payloads.some(a=>a.descriptor.path===receipt.capture.artifacts?.screenshot && a.descriptor.kind==='screenshot')) + throw new Error('Missing or inconsistent passing page evidence'); + reusable.set(receipt.key,{receipt,descriptor,receiptBytes,payloads, + provenance:{source_directory:path.resolve(directory),session_sha256:sha256(bytes), + receipt_sha256:descriptor.receipt.sha256,observed_at:receipt.observed_at}}); + } + return {reusable,previous_attempt:{directory:path.resolve(directory),session_sha256:sha256(bytes), + started_at:session.started_at,updated_at:session.updated_at,failures:session.failures}}; +} +function runTextCheck(args, helper, output, inventoryFile, captureFile, resultFile, contractFile=null) { + const command=[helper,'check','--inventory',path.join(output,inventoryFile),'--capture',path.join(output,captureFile), + '--output',path.join(output,resultFile)]; + if(contractFile) command.push('--contract',path.join(output,contractFile)); + const check=cp.spawnSync(args.python,command,{encoding:'utf8'}); + if(check.error || !fs.existsSync(path.join(output,resultFile))) + throw new Error('Math checker did not produce a result: '+(check.error||check.stderr)); + return JSON.parse(fs.readFileSync(path.join(output,resultFile),'utf8')); +} +function savePageReceipt(args, helper, output, session, inventory, source, viewport, item, prefix, contract) { + const capture={schema_version:1,repository:args.repository,revision:args.revision,renderer_profile:'github', + captured_at:item.observed_at,capture_method:'playwright-github',pages:[item]}; + const invFile=prefix+'-source.json',captureFile=prefix+'-capture.json',resultFile=prefix+'-result.json'; + writeJSON(path.join(output,invFile),{...inventory,pages:[source]}); + writeJSON(path.join(output,captureFile),capture); + const pageContract=contract?{...contract,expressions:contract.expressions.filter(e=>e.path===source.path)}:null; + const contractFile=pageContract?prefix+'-contract.json':null; + if(pageContract) writeJSON(path.join(output,contractFile),pageContract); + const result=runTextCheck(args,helper,output,invFile,captureFile,resultFile,contractFile); + const files=[artifact(output,invFile,'page_source_inventory'),artifact(output,captureFile,'page_hosted_capture'), + artifact(output,resultFile,'page_math_result')]; + if(contractFile) files.push(artifact(output,contractFile,'page_text_contract')); + for(const [kind,name] of [['hosted_html',item.artifacts?.html],['screenshot',item.artifacts?.screenshot]]) + if(name) files.push(artifact(output,name,kind)); + if(result.status!=='pass' || !capturePassed({...source,revision:args.revision},item)) + return {passed:false,result,artifacts:files}; + const receipt={schema_version:1,kind:'hosted_math_page',status:'pass',repository:args.repository, + revision:args.revision,tree:session.binding.tree,path:source.path,source_sha256:source.source_sha256, + viewport,key:pageKey(source.path,viewport),observed_at:item.observed_at,capture:item,artifacts:files}; + const filename=prefix+'-receipt.json';writeJSON(path.join(output,filename),receipt); + const descriptor={key:receipt.key,receipt:artifact(output,filename,'page_receipt')}; + session.completed.push(descriptor);session.updated_at=new Date().toISOString();saveSession(output,session); + return {passed:true,result,artifacts:[...files,descriptor.receipt],receipt}; +} +async function captureHostedPage(context, source, expected, prefix, output, readinessOptions={}) { + const page=await context.newPage(); + const item={path:source.path,url:source.url,revision:source.revision,source_sha256:source.source_sha256,errors:[],math:[]}; + try { + const response=await page.goto(source.url,{waitUntil:'domcontentloaded',timeout:60000}); + if(response?.status()!==200) throw new Error('HTTP '+response?.status()); + if(page.url()!==source.url) throw new Error('Browser redirected away from exact pinned source URL'); + const article=page.locator('article.markdown-body').first(); + await article.waitFor({state:'visible',timeout:30000}); + await page.evaluate(async()=>{ + for(let y=0,steps=0;ysetTimeout(r,50)); + } + window.scrollTo(0,0); + }); + await waitForHostedMath(article,expected.length,readinessOptions); + Object.assign(item,await article.evaluate(inspectArticle,expected)); + const html=prefix+'.html',png=prefix+'.png'; + fs.writeFileSync(path.join(output,html),await page.content()); + await page.screenshot({path:path.join(output,png),fullPage:true,timeout:30000}); + item.artifacts={html,screenshot:png}; + item.observed_at=new Date().toISOString(); + return item; + } finally {await page.close();} +} +async function defaultRuntime() { + const {chromium}=require('playwright'); + const runtime={node:process.version,playwright:require('playwright/package.json').version, + mathjax:require('mathjax-full/package.json').version}; + const compile=mathCompiler(),browser=await chromium.launch({headless:true}); + runtime.browser=browser.version();return {browser,compile,runtime}; +} +async function run(args, adapters={}) { + const output=path.resolve(args.output); + if(fs.existsSync(output) && (fs.lstatSync(output).isSymbolicLink() || fs.readdirSync(output).length)) + throw new Error('Use an empty output directory; preserve earlier failed evidence'); + fs.mkdirSync(output,{recursive:true}); + const pinned=pinnedPages(args),helper=path.join(__dirname,'check_rendered_math.py'); + cp.execFileSync(args.python,[helper,'inventory','--root',args.root,'--repository',args.repository, + '--revision',args.revision,...pinned.pages.flatMap(p=>['--page',p]),'--output',path.join(output,'math-source.json')],{stdio:'pipe'}); + const inventory=JSON.parse(fs.readFileSync(path.join(output,'math-source.json'),'utf8')); + const at=new Date().toISOString(),failures=[],artifacts=[artifact(output,'math-source.json','source_inventory')],viewports=[]; + const contractBytes=args.contract?fs.readFileSync(path.resolve(args.contract)):Buffer.from('null'); + const contract=args.contract?JSON.parse(contractBytes.toString('utf8')):null; + if(args.contract && (!contract || !Array.isArray(contract.expressions) || contract.schema_version!==1)) throw new Error('Invalid text contract'); + if(args.contract) { + fs.writeFileSync(path.join(output,'math-contract.json'),contractBytes); + artifacts.push(artifact(output,'math-contract.json','text_contract')); + } + let browser,session,runtime={},resume={reusable:new Map()},fatal=false; + const pageProvenance=[]; + try { + // A policy/access failure is detected from the durable state before a new browser is started. + if(args.resumeFrom) { + const prior=JSON.parse(fs.readFileSync(safeEvidenceFile(args.resumeFrom,'capture-state.json'),'utf8')); + if(!Array.isArray(prior.failures) || prior.failures.some(f=>f.category!=='transport_failure')) + throw new Error('Resume refused after a nontransient, policy or access failure'); + } + const loaded=await (adapters.loadRuntime || defaultRuntime)(); + browser=loaded.browser; + runtime={...loaded.runtime,python:cp.execFileSync(args.python,['-c','import sys; print(sys.version)'],{encoding:'utf8'}).trim()}; + const expected=Object.fromEntries(inventory.pages.map(p=>[p.path,p.expressions.map(e=>({...e, + mml:loaded.compile(e.tex,['math-fence','dollar-display'].includes(e.kind))}))])); + writeJSON(path.join(output,'expected-mathml.json'),expected); + artifacts.push(artifact(output,'expected-mathml.json','expected_mathml')); + session=newSession(sessionBinding(inventory,pinned.tree,fs.readFileSync(path.join(output,'expected-mathml.json')), + contractBytes,runtime,helper,args.diagnosticOnly===true,fs.readFileSync(path.join(output,'math-source.json'))),at); + if(args.resumeFrom) { + resume=loadResume(args.resumeFrom,session.binding,inventory); + session.previous_attempt=resume.previous_attempt; + } + saveSession(output,session); + for(const viewport of VIEWPORTS) { + const context=await browser.newContext({viewport,deviceScaleFactor:1,colorScheme:'light'}); + const capture={schema_version:1,repository:args.repository,revision:args.revision,renderer_profile:'github', + captured_at:at,capture_method:'playwright-github',pages:[]}; + try { + for(let index=0;indexp.observed_at).filter(Boolean).sort((a,b)=>Date.parse(a)-Date.parse(b)); + capture.captured_at=observed[0] || at; + const captureFile='math-capture-'+viewport.width+'.json',resultFile='math-result-'+viewport.width+'.json'; + writeJSON(path.join(output,captureFile),capture);artifacts.push(artifact(output,captureFile,'hosted_capture')); + const result=runTextCheck(args,helper,output,'math-source.json',captureFile,resultFile,args.contract?'math-contract.json':null); + artifacts.push(artifact(output,resultFile,'math_result')); + failures.push(...result.failures.map(f=>viewport.width+': '+f)); + const matches=capture.pages.reduce((n,p)=>n+p.math.filter(m=>m.structural_match && !m.errors.length).length,0); + viewports.push({...viewport,status:result.status,structural_matches:matches,capture_path:captureFile,result_path:resultFile,boundaries:result.boundaries}); + if(fatal) break; + } + } catch(error) { + const category=classifyFailure(error);failures.push(category+': '+String(error)); + if(session) { + session.failures.push({category,reason:String(error),observed_at:new Date().toISOString()}); + session.updated_at=new Date().toISOString();saveSession(output,session); + } + } finally {if(browser) await browser.close();} + if(session) artifacts.push(artifact(output,'capture-state.json','capture_session')); + const observations=pageProvenance.map(p=>p.observed_at).sort((a,b)=>Date.parse(a)-Date.parse(b)); + const report={...boundReport(inventory,pinned.tree,viewports,artifacts,failures,observations[0] || at),runtime, + report_assembled_at:new Date().toISOString(),page_provenance:pageProvenance,diagnostic_only:args.diagnosticOnly===true}; + if(session?.previous_attempt) report.previous_attempt=session.previous_attempt; + writeJSON(path.join(output,'hosted-report.json'),report); + console.log(JSON.stringify({status:report.status,report:path.join(output,'hosted-report.json'),sha256:sha256(fs.readFileSync(path.join(output,'hosted-report.json'))),pages:report.required_pages.length,failures:report.failures.length,reused_pages:pageProvenance.filter(p=>p.reused).length})); + return report.status==='pass'?0:1; +} +module.exports={argumentsFor,safePath,pinnedPages,mathCompiler,inspectArticle,hostedMathReadiness,waitForHostedMath,classifyFailure,artifact,boundReport,VIEWPORTS,run, + safeEvidenceFile,readBoundArtifact,observationTime,pageKey,capturePassed,sessionBinding,newSession,saveSession,loadResume, + runTextCheck,savePageReceipt,captureHostedPage,RESUME_MAX_AGE_MS,RENDER_TIMEOUT_MS}; +if(require.main===module) { + (async()=>{ + const args=argumentsFor(process.argv.slice(2)); + if(args.help) {console.log('capture_hosted_math.cjs --root REPO --repository owner/name --revision FULLSHA --output EMPTY_DIR [--page PATH ...] [--contract JSON] [--python python3] [--resume-from PRIOR_EVIDENCE_DIR]');return;} + process.exitCode=await run(args); + })().catch(error=>{console.error(String(error));process.exitCode=2;}); +} diff --git a/verification/hosted_math/check_completion.py b/verification/hosted_math/check_completion.py new file mode 100644 index 0000000..d4b9bd2 --- /dev/null +++ b/verification/hosted_math/check_completion.py @@ -0,0 +1,545 @@ +#!/usr/bin/env python3 +"""Check completion-evidence consistency in an existing private game checkpoint. + +No network requests or mutations are made. Evidence is supplied by the launcher; +this checker cannot authenticate observations or certify scientific truth. +See --help and the companion protocol for the evidence contract. +""" +from __future__ import annotations + +import argparse +import hashlib +from datetime import datetime, timedelta, timezone +import json +from pathlib import Path, PurePosixPath +from urllib.parse import quote +import re +import sys + +CUMULATIVE_STAGES = ("integrated", "release", "cleanup") +STAGES = (*CUMULATIVE_STAGES, "preservation") +SHA256 = re.compile(r"[0-9a-f]{64}\Z") +MAX_REPORT_BYTES = 16 * 1024 * 1024 +SHA = re.compile(r"[0-9a-f]{40}\Z") +SAFE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]*\Z") +GAME_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]{0,127}\Z") +SEMANTIC_TOPICS = { + "decisions", "results", "failed_approaches", "limitations", "next_steps", "artifacts" +} + + +def timestamp(value): + if not isinstance(value, str): + raise ValueError("timestamp must be a string") + parsed = datetime.fromisoformat(value.replace("Z", "+00:00")) + if parsed.tzinfo is None: + raise ValueError("timestamp needs a timezone") + return parsed.astimezone(timezone.utc) + + +class Evidence: + def __init__(self, now, max_age_hours): + self.now = now + self.max_age = timedelta(hours=max_age_hours) + + @staticmethod + def obj(value, path, errors): + if not isinstance(value, dict): + errors.append(f"{path}: required object missing or malformed") + return {} + return value + + @staticmethod + def text(value, path, errors): + if not isinstance(value, str) or not value.strip(): + errors.append(f"{path}: required nonempty string") + return "" + return value + + @staticmethod + def sha(value, path, errors): + if not isinstance(value, str) or not SHA.fullmatch(value): + errors.append(f"{path}: required full lowercase 40-character SHA") + return "" + return value + + def observation(self, value, path, errors): + obj = self.obj(value, path, errors) + self.text(obj.get("record"), path + ".record", errors) + try: + at = timestamp(obj.get("observed_at")) + if at > self.now + timedelta(minutes=5) or self.now - at > self.max_age: + errors.append(f"{path}.observed_at: stale or future observation; inspect again") + except (ValueError, TypeError, OverflowError): + errors.append(f"{path}.observed_at: required timezone-aware ISO timestamp") + return obj + + def revision(self, value, path, revision, errors): + obj = self.observation(value, path, errors) + for field in ("commit", "tree"): + actual = self.sha(obj.get(field), path + "." + field, errors) + matches = (actual in revision.get("allowed_commits", [revision.get("commit")]) + if field == "commit" else actual == revision.get("tree")) + if not matches: + errors.append(f"{path}.{field}: does not match inspected revision") + return obj + + def merge(self, value, path, errors): + pr = self.observation(value, path, errors) + if type(pr.get("number")) is not int or pr["number"] <= 0: + errors.append(f"{path}.number: required positive PR number") + if pr.get("merged") is not True: + errors.append(f"{path}.merged: must be true; a merge hash or closed state is insufficient") + for field in ("head_sha", "head_tree", "merge_commit_sha", "merge_tree"): + self.sha(pr.get(field), path + "." + field, errors) + return pr + + def descendants(self, value, path, tree, errors): + if not isinstance(value, list): + errors.append(f"{path}: must be a list (empty is allowed)") + return [] + edges = [] + for i, raw in enumerate(value): + key = f"{path}[{i}]" + edge = self.observation(raw, key, errors) + source = self.sha(edge.get("from_commit"), key + ".from_commit", errors) + target = self.sha(edge.get("to_commit"), key + ".to_commit", errors) + if edge.get("tree") != tree or edge.get("ancestry_confirmed") is not True or edge.get("no_content_change") is not True: + errors.append(f"{key}: requires observed ancestry and unchanged checked tree") + else: + edges.append((source, target)) + return edges + + @staticmethod + def path_nodes(source, target, edges): + if (not isinstance(source, str) or not SHA.fullmatch(source) + or not isinstance(target, str) or not SHA.fullmatch(target)): + return set() + if source == target: + return {source} + + def reachable(start, directed): + seen = {start} + while True: + added = {b for a, b in directed if a in seen} - seen + if not added: + return seen + seen.update(added) + + forward = reachable(source, edges) + if target not in forward: + return set() + backward = reachable(target, [(b, a) for a, b in edges]) + return forward & backward + + +def handoff_errors(ev, value, repo, game_id, source, warnings): + """Validate the same stored handoff for ordinary completion or archival exit.""" + errors = [] + handoff = ev.obj(value, "handoff", errors) + expected_path = f"projects/{repo.split('/')[-1]}/handoffs/{game_id}/" + if handoff.get("repository") != "GoGoKo699/Camelot" or handoff.get("private") is not True: + errors.append("handoff: must identify private GoGoKo699/Camelot") + if handoff.get("path") != expected_path: + errors.append("handoff.path: must match this repository and stable game ID") + path_tree = ev.sha(handoff.get("checked_path_tree"), "handoff.checked_path_tree", errors) + semantic = ev.observation(handoff.get("semantic"), "handoff.semantic", errors) + ev.sha(semantic.get("path_tree"), "handoff.semantic.path_tree", errors) + topics = semantic.get("coverage") + if not isinstance(topics, list) or any(not isinstance(x, str) for x in topics) or not SEMANTIC_TOPICS.issubset(set(topics)): + errors.append("handoff.semantic.coverage: missing required important-information topics") + if semantic.get("complete") is not True or semantic.get("gaps") != []: + errors.append("handoff.semantic: incomplete or missing gap assessment") + if (semantic.get("source_commit") != source.get("commit") + or semantic.get("source_tree") != source.get("tree") + or semantic.get("path") != expected_path + or semantic.get("path_tree") != path_tree): + errors.append("handoff.semantic: assessment must cover this game, checked path tree and final scientific source pin") + integrity = ev.observation(handoff.get("integrity"), "handoff.integrity", errors) + if integrity.get("status") != "pass" or integrity.get("scope") != "own_game": + errors.append("handoff.integrity: passing own-game integrity check required") + hpr = ev.merge(handoff.get("pull_request"), "handoff.pull_request", errors) + remote = ev.observation(handoff.get("remote_readback"), "handoff.remote_readback", errors) + for field in ("commit", "tree", "source_commit", "source_tree"): + ev.sha(remote.get(field), "handoff.remote_readback." + field, errors) + if remote.get("path") != expected_path or remote.get("game_id") != game_id or remote.get("content_verified") is not True: + errors.append("handoff.remote_readback: own-game path, identity and content verification required") + if (integrity.get("path") != expected_path or integrity.get("path_tree") != path_tree + or remote.get("path_tree") != path_tree + or integrity.get("commit") not in (hpr.get("head_sha"), hpr.get("merge_commit_sha"), remote.get("commit"))): + errors.append("handoff.integrity: checked own-game path tree and revision must match merged remote readback") + if remote.get("source_commit") != source.get("commit") or remote.get("source_tree") != source.get("tree"): + errors.append("handoff.remote_readback: stored source pin differs from final scientific main") + # Shared-store changes are allowed after this PR: verify ancestry and unchanged + # own-game path instead of requiring the entire Camelot tree to stay frozen. + if remote.get("commit") != hpr.get("merge_commit_sha"): + continuation = ev.observation(handoff.get("later_store_revision"), "handoff.later_store_revision", errors) + if (continuation.get("from_commit") != hpr.get("merge_commit_sha") + or continuation.get("to_commit") != remote.get("commit") + or continuation.get("path") != expected_path + or continuation.get("ancestry_confirmed") is not True + or continuation.get("own_game_unchanged") is not True): + errors.append("handoff.later_store_revision: observed ancestry and unchanged own-game path required") + elif remote.get("tree") != hpr.get("merge_tree"): + errors.append("handoff.remote_readback.tree: differs from merged store tree") + if "full_store_audit" in handoff: + warnings.append("handoff.full_store_audit is informational only; own-game integrity and semantic coverage govern preservation") + return errors + + +def safe_relative_path(value): + return (isinstance(value, str) and bool(value) and "\\" not in value + and not any(ord(char) < 32 or ord(char) == 127 for char in value) + and not PurePosixPath(value).is_absolute() + and all(part not in ("", ".", "..") for part in value.split("/"))) + + +def parse_json(value): + return json.loads(value, object_pairs_hook=reject_duplicate_keys, + parse_constant=lambda x: (_ for _ in ()).throw(ValueError(f"invalid JSON constant: {x}"))) + + +def check_hosted_report(ev, value, repo, revision, required, reports, errors): + """Bind readiness to inspected report bytes, not a manually copied pass flag.""" + desc = ev.revision(value, "hosted_report", revision, errors) + path = desc.get("path") + if not safe_relative_path(path): + errors.append("hosted_report.path: requires a safe checkpoint-relative file path") + return + sha = desc.get("sha256") + if not isinstance(sha, str) or not SHA256.fullmatch(sha): + errors.append("hosted_report.sha256: requires complete lowercase SHA256") + content = reports.get(path) if isinstance(reports, dict) else None + if not isinstance(content, bytes) or len(content) > MAX_REPORT_BYTES: + errors.append("hosted_report: actual report bytes are unavailable or exceed 16 MiB") + return + if hashlib.sha256(content).hexdigest() != sha: + errors.append("hosted_report: report bytes do not match sha256") + return + try: + report = parse_json(content) + except (ValueError, UnicodeError, TypeError) as exc: + errors.append(f"hosted_report: invalid report JSON: {exc}") + return + if not isinstance(report, dict): + errors.append("hosted_report: report must be a JSON object") + return + if "diagnostic_only" in report and report["diagnostic_only"] is not False: + errors.append("hosted_report.diagnostic_only: a representative diagnostic cannot establish release readiness") + for field, expected in (("schema_version", 1), ("kind", "hosted_math"), + ("repository", repo), ("revision", desc.get("commit")), + ("tree", desc.get("tree")), ("renderer_profile", "github"), + ("capture_method", "playwright-github"), ("status", "pass"), + ("failures", []), ("visual_review_required", True)): + if (report.get(field) != expected + or (field == "schema_version" and type(report.get(field)) is not int) + or (field == "visual_review_required" and report.get(field) is not True)): + errors.append(f"hosted_report.{field}: invalid or inconsistent collector report") + ev.observation({"record": path, "observed_at": report.get("captured_at")}, "hosted_report.capture", errors) + paths = report.get("required_pages") + if (not isinstance(paths, list) or not paths or not all(safe_relative_path(p) for p in paths) + or len(paths) != len(set(paths)) or set(paths) != set(required)): + errors.append("hosted_report.required_pages: must exactly cover declared visual-review pages") + paths = [] + boundaries = report.get("boundaries") + if not isinstance(boundaries, list) or any(not isinstance(b, dict) for b in boundaries): + errors.append("hosted_report.boundaries: needs complete page/source coverage") + boundaries = [] + seen, count = [], 0 + for boundary in boundaries: + page = boundary.get("path") + seen.append(page) + source_hash = boundary.get("source_sha256") + if not isinstance(source_hash, str) or not SHA256.fullmatch(source_hash): + errors.append("hosted_report.boundaries: missing complete source SHA256") + n, actual = boundary.get("source_expressions"), boundary.get("captured_hosts") + if type(n) is not int or type(actual) is not int or n < 0 or actual != n: + errors.append("hosted_report.boundaries: missing or unequal expression/host counts") + else: + count += n + expected_url = f"https://github.com/{repo}/blob/{desc.get('commit')}/{quote(page, safe='/')}" if isinstance(page, str) else None + if boundary.get("revision") != desc.get("commit") or boundary.get("url") != expected_url: + errors.append("hosted_report.boundaries: page must identify the exact hosted revision") + if seen != paths: + errors.append("hosted_report.boundaries: missing, extra, reordered or duplicate page") + structure = report.get("structural_comparison") + if (not isinstance(structure, dict) or structure.get("status") != "pass" + or type(structure.get("expressions_checked")) is not int + or structure.get("expressions_checked") != count): + errors.append("hosted_report.structural_comparison: all source expressions must match") + views = report.get("viewports") + if not isinstance(views, list) or len(views) < 2 or any(not isinstance(v, dict) for v in views): + errors.append("hosted_report.viewports: requires wide and narrow hosted results") + views = [] + widths = [] + for view in views: + width, height = view.get("width"), view.get("height") + if type(width) is not int or type(height) is not int or width <= 0 or height <= 0: + errors.append("hosted_report.viewports: invalid dimensions") + else: + widths.append(width) + if (view.get("status") != "pass" or type(view.get("structural_matches")) is not int + or view.get("structural_matches") != count + or not safe_relative_path(view.get("result_path")) + or not safe_relative_path(view.get("capture_path"))): + errors.append("hosted_report.viewports: complete passing reports required at every viewport") + if not any(w <= 800 for w in widths) or not any(w >= 1200 for w in widths): + errors.append("hosted_report.viewports: both narrow and wide inspection required") + + +def preservation_errors(ev, data, repo, game_id, identity_errors, stages, warnings): + """A user-directed archival exit preserves incomplete work without certifying it.""" + errors = list(identity_errors) + if data.get("preservation") is None: + return errors + ["preservation.request: no explicit archival-exit request and evidence supplied"] + preserve = ev.obj(data.get("preservation"), "preservation", errors) + request = ev.observation(preserve.get("request"), "preservation.request", errors) + if (request.get("actor") != "user" or request.get("intent") not in ("preserve_and_stop", "retire_originating_chat") + or request.get("scope") != "originating_chat" or request.get("game_id") != game_id + or request.get("repository") != repo): + errors.append("preservation.request: actual user request for this game's originating chat required") + source = ev.observation(preserve.get("source"), "preservation.source", errors) + for field in ("commit", "tree"): + ev.sha(source.get(field), "preservation.source." + field, errors) + if source.get("repository") != repo: + errors.append("preservation.source: repository must match this game") + integration = data.get("integration") + if isinstance(integration, dict) and "main" in integration: + main = ev.obj(integration["main"], "integration.main", errors) + if any(main.get(k) != source.get(k) for k in ("commit", "tree")): + errors.append("preservation.source: conflicts with observed scientific main") + errors.extend(handoff_errors(ev, data.get("handoff"), repo, game_id, source, warnings)) + handoff = data.get("handoff") if isinstance(data.get("handoff"), dict) else {} + resume = ev.observation(preserve.get("resumption"), "preservation.resumption", errors) + for field, expected in (("game_id", game_id), ("repository", repo), + ("source_commit", source.get("commit")), ("source_tree", source.get("tree")), + ("path", handoff.get("path")), ("path_tree", handoff.get("checked_path_tree"))): + if resume.get(field) != expected: + errors.append(f"preservation.resumption.{field}: must match the saved game and source") + for flag, expected in (("self_contained", True), ("requires_original_chat", False), + ("artifacts_reconciled", True), ("unfinished_work_reviewed", True)): + if resume.get(flag) is not expected: + errors.append(f"preservation.resumption.{flag}: required {expected}") + ev.text(resume.get("artifact_record"), "preservation.resumption.artifact_record", errors) + if resume.get("missing_essential_artifacts") != []: + errors.append("preservation.resumption: essential artifacts remain missing or unassessed") + tasks = resume.get("unfinished_tasks") + if not isinstance(tasks, list) or any(not isinstance(t, dict) for t in tasks): + errors.append("preservation.resumption.unfinished_tasks: requires an explicit list") + tasks = [] + task_stages = set() + for i, task in enumerate(tasks): + label = f"preservation.resumption.unfinished_tasks[{i}]" + if task.get("stage") not in CUMULATIVE_STAGES: + errors.append(label + ".stage: unknown remaining stage") + else: + task_stages.add(task["stage"]) + for key in ("reason", "owner", "next_action"): + ev.text(task.get(key), label + "." + key, errors) + # A failed scientific or display review can be preserved, not silently erased. + if not stages["integrated"]["ok"] and "integrated" not in task_stages: + errors.append("preservation.resumption: unfinished integration/science needs a concrete continuation task") + if not stages["release"]["ok"] and "release" not in task_stages: + errors.append("preservation.resumption: unfinished release review needs a concrete continuation task") + block = data.get("blocker") + if isinstance(block, dict): + if block.get("stage") == "cleanup": + errors.append("preservation: own-game storage blocker remains unresolved") + elif block.get("stage") in ("integrated", "release"): + if not any(all(task.get(k) == block.get(k) for k in ("stage", "reason", "owner", "next_action")) for task in tasks): + errors.append("preservation.resumption: retain the exact unresolved blocker and permitted next action") + else: + errors.append("preservation: malformed blocker cannot be discarded") + elif block is not None: + errors.append("preservation: malformed blocker cannot be discarded") + return errors + + +def evaluate(checkpoint, *, now=None, max_age_hours=24, reports=None): + """Return cumulative completion and independent preservation evidence verdicts.""" + if now is None: + now = datetime.now(timezone.utc) + if now.tzinfo is None or not isinstance(max_age_hours, (int, float)) or isinstance(max_age_hours, bool) or not 0 < max_age_hours <= 168: + raise ValueError("now needs a timezone; max_age_hours must be in (0, 168]") + ev = Evidence(now.astimezone(timezone.utc), max_age_hours) + base, release, cleanup, warnings = [], [], [], [] + root = ev.obj(checkpoint, "checkpoint", base) + data = ev.obj(root.get("completion_evidence"), "completion_evidence", base) + if type(data.get("schema_version")) is not int or data["schema_version"] != 1: + base.append("completion_evidence.schema_version: must be 1") + game = ev.obj(data.get("game"), "game", base) + game_id = ev.text(game.get("id"), "game.id", base) + repo = ev.text(game.get("repository"), "game.repository", base) + if not GAME_ID.fullmatch(game_id): + base.append("game.id: must match Camelot's 1-128 character alphanumeric/underscore/hyphen identifier") + if len(repo.split("/")) != 2 or not all(SAFE.fullmatch(x) for x in repo.split("/")): + base.append("game.repository: must be owner/name") + ev.text(game.get("grant_record"), "game.grant_record", base) + for outer, inner in (("game_id", game_id), ("repository", repo)): + if outer in root and root[outer] != inner: + base.append(f"game: {outer} disagrees with existing checkpoint") + identity_errors = list(base) + revision = ev.obj(data.get("revision"), "revision", base) + for field in ("commit", "tree"): + ev.sha(revision.get(field), "revision." + field, base) + integration = ev.obj(data.get("integration"), "integration", base) + pr = ev.merge(integration.get("pull_request"), "integration.pull_request", base) + main = ev.observation(integration.get("main"), "integration.main", base) + for field in ("commit", "tree"): + ev.sha(main.get(field), "integration.main." + field, base) + edges = ev.descendants(integration.get("unchanged_descendants", []), "integration.unchanged_descendants", revision.get("tree"), base) + allowed_commits = set() + for label, source, target in ( + ("checked revision to PR head", revision.get("commit"), pr.get("head_sha")), + ("merged PR to current main", pr.get("merge_commit_sha"), main.get("commit")), + ): + nodes = ev.path_nodes(source, target, edges) + if not nodes: + base.append(f"integration: {label} lacks an observed no-content-change descendant path") + allowed_commits.update(nodes) + if any(x != revision.get("tree") for x in (pr.get("head_tree"), pr.get("merge_tree"), main.get("tree"))): + base.append("integration: checked, PR-head, merged and current-main trees must match") + # The PR head, actual merge and documented unchanged descendants can all be + # inspected separately. Their shared tree is what binds checks and captures. + checked_revision = {**revision, "allowed_commits": list(allowed_commits)} + policy = ev.observation(data.get("repository_policy"), "repository_policy", base) + if type(policy.get("ci_required")) is not bool: + base.append("repository_policy.ci_required: required boolean from inspected policy") + checks = data.get("checks") + if not isinstance(checks, list): + base.append("checks: required list") + checks = [] + kinds = {"science": base, "ci": base, "learning": release, "hosted": release} + found = set() + for i, raw in enumerate(checks): + path = f"checks[{i}]" + if not isinstance(raw, dict) or not isinstance(raw.get("kind"), str) or raw["kind"] not in kinds: + base.append(f"{path}: unknown or missing check kind") + continue + kind = raw["kind"] + found.add(kind) + dest = kinds[kind] + check = ev.revision(raw, path, checked_revision, dest) + ev.text(check.get("name"), path + ".name", dest) + status = check.get("status") + if status not in ("pass", "fail", "blocked"): + dest.append(f"{path}.status: must be pass, fail or blocked") + elif status != "pass": + ev.text(check.get("reason"), path + ".reason", dest) + if kind == "ci" and status == "blocked" and policy.get("ci_required") is False: + warnings.append(f"{path}: optional CI remains {status}; local checks do not change that status") + else: + dest.append(f"{path}: required {kind} check is {status}") + for kind in ("science", "learning", "hosted"): + if kind not in found: + kinds[kind].append(f"checks: missing required {kind} evidence") + if policy.get("ci_required") is True and "ci" not in found: + base.append("checks: repository policy requires CI evidence") + ev.text(game.get("anchor"), "game.anchor", release) + visual = ev.obj(data.get("visual_review"), "visual_review", release) + required = visual.get("required_pages") + if (not isinstance(required, list) or not required or not all(safe_relative_path(x) for x in required) + or len(required) != len(set(required))): + release.append("visual_review.required_pages: required nonempty unique safe page-path list") + required = [] + ev.text(visual.get("scope_record"), "visual_review.scope_record", release) + pages = visual.get("pages") + if not isinstance(pages, list): + release.append("visual_review.pages: required list of actual captures and source comparisons") + pages = [] + seen = set() + for i, raw in enumerate(pages): + path = f"visual_review.pages[{i}]" + page = ev.revision(raw, path, checked_revision, release) + name = ev.text(page.get("path"), path + ".path", release) + if not safe_relative_path(name): + release.append(f"{path}.path: requires a safe repository-relative page path") + if name not in required: + release.append(f"{path}.path: page is outside declared hosted/visual-review scope") + if name in seen: + release.append(f"{path}: duplicate page") + seen.add(name) + if page.get("source_compared") is not True or page.get("display_inspected") is not True: + release.append(f"{path}: source comparison and actual visual inspection both required") + for path in required: + if path not in seen: + release.append(f"visual_review: missing required page {path}") + check_hosted_report(ev, data.get("hosted_report"), repo, checked_revision, required, reports or {}, release) + cleanup.extend(handoff_errors(ev, data.get("handoff"), repo, game_id, main, warnings)) + blocker = data.get("blocker") + if blocker is not None: + block = ev.obj(blocker, "blocker", base) + target = block.get("stage") + if target not in CUMULATIVE_STAGES: + base.append("blocker.stage: must name integrated, release or cleanup") + else: + errors = {"integrated": base, "release": release, "cleanup": cleanup}[target] + for key in ("reason", "owner", "next_action"): + ev.text(block.get(key), "blocker." + key, errors) + errors.append(f"blocker: {block.get('reason', 'unresolved')} (owner: {block.get('owner', 'missing')}; next: {block.get('next_action', 'missing')})") + stages = {} + cumulative = [] + for name, errors in zip(CUMULATIVE_STAGES, (base, release, cleanup)): + cumulative += errors + stages[name] = {"ok": not cumulative, "errors": list(dict.fromkeys(cumulative))} + preserve = preservation_errors(ev, data, repo, game_id, identity_errors, stages, warnings) + stages["preservation"] = {"ok": not preserve, "errors": list(dict.fromkeys(preserve))} + return {"schema_version": 1, "preservation_ready": not preserve, + "science_integrated": stages["integrated"]["ok"], + "release_ready": stages["release"]["ok"], "chat_cleanup_ready": stages["cleanup"]["ok"], + "stages": stages, "warnings": warnings, + "scope": "Evidence consistency only; no authenticity, scientific-truth or exhaustive-coverage certification."} + + +def reject_duplicate_keys(pairs): + result = {} + for key, value in pairs: + if key in result: + raise ValueError(f"duplicate JSON key: {key}") + result[key] = value + return result + + +def load_report_bytes(checkpoint_path, checkpoint): + """Read only a bounded regular report inside the checkpoint's own directory.""" + data = checkpoint.get("completion_evidence") if isinstance(checkpoint, dict) else None + desc = data.get("hosted_report") if isinstance(data, dict) else None + path = desc.get("path") if isinstance(desc, dict) else None + if not safe_relative_path(path): + return {} + try: + base = checkpoint_path.resolve().parent + candidate = (base / path).resolve() + if not candidate.is_relative_to(base): + return {} + if not candidate.is_file() or candidate.stat().st_size > MAX_REPORT_BYTES: + return {} + with candidate.open("rb") as stream: + content = stream.read(MAX_REPORT_BYTES + 1) + return {path: content} if len(content) <= MAX_REPORT_BYTES else {} + except (OSError, RuntimeError, ValueError): + return {} + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("checkpoint", type=Path, help="Existing private checkpoint containing completion_evidence") + parser.add_argument("--stage", choices=STAGES, required=True) + parser.add_argument("--now", help="Timezone-aware ISO timestamp (default: current UTC)") + parser.add_argument("--max-age-hours", type=float, default=24, + help="Maximum age of supplied observations, at most 168 hours (default 24)") + args = parser.parse_args() + try: + data = parse_json(args.checkpoint.read_text(encoding="utf-8")) + reports = load_report_bytes(args.checkpoint, data) + result = evaluate(data, now=timestamp(args.now) if args.now else None, + max_age_hours=args.max_age_hours, reports=reports) + except (OSError, UnicodeError, ValueError, TypeError, OverflowError) as exc: + print(json.dumps({"ok": False, "error": str(exc)})) + return 2 + print(json.dumps(result, indent=2)) + return 0 if result["stages"][args.stage]["ok"] else 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/verification/hosted_math/check_rendered_math.py b/verification/hosted_math/check_rendered_math.py new file mode 100644 index 0000000..1d3bf98 --- /dev/null +++ b/verification/hosted_math/check_rendered_math.py @@ -0,0 +1,370 @@ +#!/usr/bin/env python3 +r"""Check captured mathematical text against pinned GitHub Markdown source. + +Usage (Python 3.10+, standard library only): + check_rendered_math.py inventory --root REPO --repository owner/name \ + --revision FULL_COMMIT --page README.md --page science/results.md \ + --output math-source.json + check_rendered_math.py check --inventory math-source.json \ + --capture math-capture.json [--contract math-contract.json] [--output result.json] + +Inventory reads Git objects at the requested commit, not the working tree. +It recognizes math fences, $`...`$, $$...$$ and single-dollar inline math, +excluding ordinary code fences/spans. This is a bounded Markdown scanner, +not the hosting renderer's parser. Inspect its inventory before capture. + +Capture schema (collect actual full accessible math text in document order): + {"schema_version": 1, "repository": "owner/name", "revision": "40 hex", + "renderer_profile": "github", "captured_at": "ISO-8601 with timezone", + "capture_method": "how the actual hosted DOM was inspected", + "pages": [{"path": "README.md", "url": "exact pinned inventory URL", + "revision": "40 hex", "source_sha256": "inventory source hash", + "errors": [], "math": [{"rendered": true, "errors": [], + "text_source": "mathml", "text": "full text, not a sample"}]}]} +Allowed text_source values: mathml, mathjax-assistive, katex-accessibility, +renderer-accessibility. Extract one accessible representation per host; +exclude TeX annotation nodes and duplicate visual/accessibility copies. +Native MathML is valid. Empty math lists are valid for math-free pages. + +Optional contract strengthens content checks without pretending to translate +arbitrary TeX. Each entry selects a path/index (1-based) and source_sha256 +(the expression hash in inventory), with expected_text and/or required_text: + {"schema_version": 1, "expressions": [{"path": "README.md", "index": 1, + "source_sha256": "expression hash", "required_text": ["d", "(C1)"], + "expected_text": "|A|", "le": "≤", "leq": "≤", "ge": "≥", "geq": "≥", + "ne": "≠", "neq": "≠", "in": "∈", "notin": "∉", "subset": "⊂", + "subseteq": "⊆", "supset": "⊃", "supseteq": "⊇", "approx": "≈", + "simeq": "≃", "equiv": "≡", "propto": "∝", "cong": "≅", "sim": "∼", + "to": "→", "rightarrow": "→", "Rightarrow": "⇒", "implies": "⇒", + "mapsto": "↦", "leftrightarrow": "↔", "Leftrightarrow": "⇔", "iff": "⇔", +} +RELATION_SYMBOLS = set("<>=") | set(RELATIONS.values()) +COMMAND = re.compile(r"\\([A-Za-z]+)") +LABEL = re.compile(r"\\tag(\*)?\{([^{}]+)\}|\\text\{\s*\(([^{}()]+)\)\s*\}") +FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})([^\n]*)\n?$") +SHA = re.compile(r"[0-9a-f]{40}") +TEXT_SOURCES = {"mathml", "mathjax-assistive", "katex-accessibility", "renderer-accessibility"} + + +def digest(text: str) -> str: + return hashlib.sha256(text.encode("utf-8")).hexdigest() + + +def compact(text: str) -> str: + return "".join(c for c in unicodedata.normalize("NFKC", text) + if not c.isspace() and unicodedata.category(c) != "Cf") + + +def escaped(text: str, index: int) -> bool: + backslashes = 0 + while index > 0 and text[index - 1] == "\\": + backslashes += 1 + index -= 1 + return bool(backslashes % 2) + + +def tex_body(text: str) -> str: + """Drop unescaped TeX comments; do not expand user macros.""" + return "\n".join(line[:next((i for i, c in enumerate(line) + if c == "%" and not escaped(line, i)), len(line))] + for line in text.splitlines()) + + +def relations(tex: str) -> dict[str, int]: + expanded = COMMAND.sub(lambda m: RELATIONS.get(m.group(1), m.group(0)), tex_body(tex)) + return dict(sorted(Counter(c for c in expanded if c in RELATION_SYMBOLS).items())) + + +def labels(tex: str) -> list[str]: + return [compact(tag if star else f"({tag or text})") + for star, tag, text in LABEL.findall(tex_body(tex))] + + +def expressions(source: str) -> list[dict]: + """Return ordered source spans; reject unterminated recognized delimiters.""" + found: list[dict] = [] + + def add(tex: str, offset: int, end: int, kind: str) -> None: + found.append({"line_start": source.count("\n", 0, offset) + 1, + "line_end": source.count("\n", 0, end) + 1, + "kind": kind, "tex": tex, "source_sha256": digest(tex), + "relations": relations(tex), "labels": labels(tex)}) + + def prose(start: int, end: int) -> None: + i = start + while i < end: + if source[i] == "$" and not escaped(source, i): + opener, closer, kind = ("$`", "`$", "github-inline") if source.startswith("$`", i) else ( + ("$$", "$$", "dollar-display") if source.startswith("$$", i) + else ("$", "$", "dollar-inline")) + j = source.find(closer, i + len(opener), end) + while j >= 0 and escaped(source, j): + j = source.find(closer, j + len(closer), end) + if j < 0 or (kind == "dollar-inline" and "\n" in source[i:j]): + raise ValueError(f"unclosed {kind} at line {source.count(chr(10), 0, i) + 1}") + add(source[i + len(opener):j], i, j + len(closer) - 1, kind) + i = j + len(closer) + elif source[i] == "`" and not escaped(source, i): + n = 1 + while i + n < end and source[i + n] == "`": + n += 1 + j = source.find("`" * n, i + n, end) + i = j + n if j >= 0 else i + n + else: + i += 1 + + lines = source.splitlines(keepends=True) + offset = start = i = 0 + while i < len(lines): + match = FENCE.match(lines[i]) + if not match: + offset += len(lines[i]) + i += 1 + continue + prose(start, offset) + marker, info = match.groups() + begin = offset + offset += len(lines[i]) + body_start = offset + i += 1 + while i < len(lines): + closing = FENCE.match(lines[i]) + if closing and closing[1][0] == marker[0] and len(closing[1]) >= len(marker) and not closing[2].strip(): + break + offset += len(lines[i]) + i += 1 + if i == len(lines): + raise ValueError(f"unclosed code fence at line {source.count(chr(10), 0, begin) + 1}") + if info.strip() == "math": + add(source[body_start:offset], begin, offset, "math-fence") + offset += len(lines[i]) + i += 1 + start = offset + prose(start, len(source)) + for index, item in enumerate(found, 1): + item["index"] = index + return found + + +def safe_path(path: str) -> bool: + return isinstance(path, str) and bool(path) and "\\" not in path and not PurePosixPath(path).is_absolute() and all( + part not in {"", ".", ".."} for part in path.split("/")) + + +def make_inventory(repository: str, revision: str, sources: dict[str, str]) -> dict: + if not isinstance(repository, str) or not isinstance(revision, str) or not re.fullmatch( + r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository) or not SHA.fullmatch(revision): + raise ValueError("use owner/name and an exact lowercase 40-character commit SHA") + if not isinstance(sources, dict) or not sources or not all( + safe_path(p) and isinstance(s, str) for p, s in sources.items()): + raise ValueError("supply at least one safe repository-relative page path") + return {"schema_version": 1, "repository": repository, "revision": revision, + "renderer_profile": "github", "pages": [ + {"path": path, "url": f"https://github.com/{repository}/blob/{revision}/{quote(path, safe='/')}", + "source_sha256": digest(source), "source_text": source, "expressions": expressions(source)} + for path, source in sources.items()]} + + +def validate(inventory: dict, capture: dict, contract: dict | None = None) -> dict: + """Return failures rather than equating a passing text check with readiness.""" + failures: list[str] = [] + boundaries: list[dict] = [] + exceptions: list[dict] = [] + if not isinstance(inventory, dict) or not isinstance(capture, dict): + raise ValueError("inventory and capture must be JSON objects") + if type(inventory.get("schema_version")) is not int or type(capture.get("schema_version")) is not int or inventory["schema_version"] != 1 or capture["schema_version"] != 1: + raise ValueError("unsupported inventory or capture schema_version") + pages = inventory.get("pages") + if not isinstance(pages, list) or not pages or any(not isinstance(p, dict) for p in pages): + raise ValueError("inventory needs a nonempty pages array") + paths = [p.get("path") for p in pages] + if any(not isinstance(p, str) for p in paths) or len(set(paths)) != len(paths): + raise ValueError("inventory page paths must be unique strings") + rebuilt = make_inventory(inventory.get("repository", ""), inventory.get("revision", ""), + {p["path"]: p["source_text"] for p in pages}) + if inventory != rebuilt: + raise ValueError("inventory does not match its embedded source bytes/expression inventory") + for field in ("repository", "revision", "renderer_profile"): + if capture.get(field) != inventory[field]: + failures.append(f"capture {field} mismatch") + try: + timestamp = datetime.fromisoformat(capture.get("captured_at", "").replace("Z", "+00:00")) + if timestamp.tzinfo is None: + raise ValueError() + except (ValueError, AttributeError, TypeError): + failures.append("capture needs captured_at with a timezone") + if not isinstance(capture.get("capture_method"), str) or not capture["capture_method"].strip(): + failures.append("capture needs a nonempty capture_method") + captured_pages = capture.get("pages") + if not isinstance(captured_pages, list) or any(not isinstance(p, dict) for p in captured_pages): + raise ValueError("capture pages must be an array of objects") + captured_paths = [p.get("path") for p in captured_pages] + if captured_paths != paths: + failures.append("capture page paths/order differ from inventory (missing, extra or duplicate page)") + + contract = {"schema_version": 1, "expressions": []} if contract is None else contract + if not isinstance(contract, dict) or type(contract.get("schema_version")) is not int or contract["schema_version"] != 1 or not isinstance(contract.get("expressions"), list): + raise ValueError("invalid text contract schema") + rules: dict[tuple, dict] = {} + known = {(p["path"], e["index"]): e for p in pages for e in p["expressions"]} + for rule in contract["expressions"]: + if not isinstance(rule, dict): + raise ValueError("contract expressions must be objects") + key = (rule.get("path"), rule.get("index")) + if not isinstance(key[0], str) or type(key[1]) is not int or key not in known or key in rules or rule.get("source_sha256") != known[key]["source_sha256"]: + raise ValueError("unknown, duplicate or stale expression contract") + allowed = {"path", "index", "source_sha256", "required_text", "expected_text", "relation_override", + "allow_html_like_inequality", "reason", "evidence"} + if set(rule) - allowed: + raise ValueError("unknown contract field (contracts cannot skip checks)") + if "expected_text" in rule and (not isinstance(rule["expected_text"], str) or not compact(rule["expected_text"])): + raise ValueError("expected_text must be nonempty text") + if not isinstance(rule.get("required_text", []), list) or any( + not isinstance(v, str) or not compact(v) for v in rule.get("required_text", [])): + raise ValueError("required_text must be an array of nonempty text") + if "expected_text" not in rule and not rule.get("required_text"): + raise ValueError("each expression contract needs expected_text or required_text") + if "allow_html_like_inequality" in rule and not isinstance(rule["allow_html_like_inequality"], bool): + raise ValueError("allow_html_like_inequality must be boolean") + if "relation_override" in rule: + override = rule["relation_override"] + if not isinstance(override, dict) or any(k not in RELATION_SYMBOLS or type(v) is not int or v < 0 + for k, v in override.items()): + raise ValueError("relation_override must map known symbols to nonnegative integer counts") + if "relation_override" in rule or rule.get("allow_html_like_inequality"): + if not all(isinstance(rule.get(k), str) and rule[k].strip() for k in ("expected_text", "reason", "evidence")): + raise ValueError("renderer exception requires expected_text, reason and evidence") + exceptions.append(rule) + rules[key] = rule + + by_path = {p.get("path"): p for p in captured_pages if isinstance(p.get("path"), str)} + checked = 0 + for page in pages: + path = page["path"] + current = by_path.get(path) + if current is None: + continue + boundaries.append({"path": path, "source_sha256": page["source_sha256"], "url": current.get("url"), + "revision": current.get("revision"), "source_expressions": len(page["expressions"]), + "source_spans": [{k: e[k] for k in ("index", "line_start", "line_end", "source_sha256")} + for e in page["expressions"]]}) + for field, expected in (("url", page["url"]), ("revision", inventory["revision"]), ("source_sha256", page["source_sha256"])): + if current.get(field) != expected: + failures.append(f"{path}: captured {field} mismatch") + if current.get("errors") != []: + failures.append(f"{path}: renderer errors present or error evidence missing") + hosts = current.get("math") + if not isinstance(hosts, list): + failures.append(f"{path}: missing math-host array") + continue + boundaries[-1]["captured_hosts"] = len(hosts) + if len(hosts) != len(page["expressions"]): + failures.append(f"{path}: {len(page['expressions'])} source expressions, {len(hosts)} captured hosts") + for expr, host in zip(page["expressions"], hosts): + label = f"{path}:{expr['line_start']} expression {expr['index']}" + rule = rules.get((path, expr["index"]), {}) + if not isinstance(host, dict) or host.get("rendered") is not True or host.get("errors") != []: + failures.append(f"{label}: missing/unrendered host or renderer-error evidence") + continue + if host.get("text_source") not in TEXT_SOURCES or not isinstance(host.get("text"), str) or not compact(host["text"]): + failures.append(f"{label}: missing full accessible mathematical text/source") + continue + checked += 1 + text = compact(host["text"]) + expected = {k: v for k, v in rule.get("relation_override", expr["relations"]).items() if v} + actual = dict(sorted(Counter(c for c in text if c in RELATION_SYMBOLS).items())) + if expected != actual: + failures.append(f"{label}: relation mismatch; expected {expected}, captured {actual}") + for equation_label in expr["labels"]: + if equation_label not in text: + failures.append(f"{label}: missing equation label {equation_label}") + if re.search(r"<\s*[A-Za-z]", tex_body(expr["tex"])) and not rule.get("allow_html_like_inequality"): + failures.append(f"{label}: GitHub HTML-like inequality hazard; use supported syntax or a traced exact-text exception") + if "expected_text" in rule and compact(rule["expected_text"]) != text: + failures.append(f"{label}: full expected_text mismatch") + for required in rule.get("required_text", []): + if compact(required) not in text: + failures.append(f"{label}: missing required_text {required!r}") + return {"schema_version": 1, "status": "fail" if failures else "pass", + "repository": inventory["repository"], "revision": inventory["revision"], + "renderer_profile": inventory["renderer_profile"], "captured_at": capture.get("captured_at"), + "capture_method": capture.get("capture_method"), "boundaries": boundaries, + "expressions_checked": checked, "text_contracts": len(rules), "renderer_exceptions": exceptions, + "failures": failures, "visual_review_required": True, + "limits": "Counts, supported relations/visible labels and explicit text contracts only. No arbitrary TeX equivalence, scientific correctness, capture authentication or visual-layout certification."} + + +def read_json(path: Path) -> dict: + return json.loads(path.read_text(encoding="utf-8")) + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + commands = parser.add_subparsers(dest="command", required=True) + inv = commands.add_parser("inventory", help="read math source from an exact local Git commit") + inv.add_argument("--root", type=Path, required=True) + inv.add_argument("--repository", required=True) + inv.add_argument("--revision", required=True) + inv.add_argument("--page", action="append", required=True) + inv.add_argument("--output", type=Path, required=True) + check = commands.add_parser("check", help="check pinned extracted capture; does not fetch or render") + check.add_argument("--inventory", type=Path, required=True) + check.add_argument("--capture", type=Path, required=True) + check.add_argument("--contract", type=Path) + check.add_argument("--output", type=Path) + args = parser.parse_args(argv) + try: + if args.command == "inventory": + if not SHA.fullmatch(args.revision) or len(set(args.page)) != len(args.page) or not all(safe_path(p) for p in args.page): + raise ValueError("use an exact commit SHA and unique safe page paths") + commit = subprocess.check_output(["git", "--no-replace-objects", "rev-parse", f"{args.revision}^{{commit}}"], cwd=args.root, text=True).strip() + if commit != args.revision: + raise ValueError("revision does not identify the supplied commit") + sources = {p: subprocess.check_output(["git", "--no-replace-objects", "show", f"{commit}:{p}"], cwd=args.root).decode("utf-8") for p in args.page} + result = make_inventory(args.repository, commit, sources) + else: + result = validate(read_json(args.inventory), read_json(args.capture), read_json(args.contract) if args.contract else None) + output = json.dumps(result, indent=2, ensure_ascii=False) + "\n" + if args.output: + args.output.write_text(output, encoding="utf-8") + else: + print(output, end="") + return 1 if result.get("status") == "fail" else 0 + except (OSError, UnicodeError, ValueError, KeyError, TypeError, subprocess.CalledProcessError) as error: + print(f"ERROR: {error}", file=sys.stderr) + return 2 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/verification/hosted_math/math-contract.json b/verification/hosted_math/math-contract.json new file mode 100644 index 0000000..1eb5bd1 --- /dev/null +++ b/verification/hosted_math/math-contract.json @@ -0,0 +1,184 @@ +{ + "schema_version": 1, + "expressions": [ + { + "path": "README.md", + "index": 1, + "source_sha256": "452701faabb4c3fea011cb48ee67e3c5dc7faec10b4090c40d7370412887458e", + "required_text": [ + "ρU,v", + "d(d+v)", + "0 crypto.createHash('sha256').update(bytes).digest('hex'); + +function argumentsFor(argv) { + if (argv.includes('--resume-from')) throw new Error('A diagnostic does not resume captures; use the full collector for that operation'); + const args = collector.argumentsFor(argv); + if (args.help) return args; + if (args.pages.length !== 1) throw new Error('Choose exactly one representative --page for the early diagnostic'); + return args; +} + +function sourceAdvisories(source, page) { + const warnings = []; + let fence = null; + for (const [index, line] of source.split(/\r?\n/).entries()) { + const mark = line.match(/^\s{0,3}(`{3,}|~{3,})/); + if (mark) { + if (!fence) fence = mark[1]; + else if (mark[1][0] === fence[0] && mark[1].length >= fence.length) fence = null; + continue; + } + if (fence) continue; + const inline = [...line.matchAll(/(? warnings.push({code, path:page, line:index+1, message}); + if (tex.includes('<')) add('raw_inline_less_than', 'Inspect raw < in inline mathematics on GitHub; use an appropriate TeX relation if the host truncates it.'); + if (/_[A-Za-z0-9]+_/.test(tex)) add('repeated_unbraced_subscript', 'Inspect a possible repeated unbraced subscript; braces may be needed to express the intended indices.'); + if (/^\s*\|/.test(line) && /(? message.includes(category) || collector.classifyFailure(message) === category)) return category; + } + return messages.length ? 'verification_failure' : null; +} + +function dependencies(args, services = {}) { + const execute = services.execFileSync || cp.execFileSync; + const resolve = services.resolve || require.resolve; + const result = {node:process.version}; + if (Number(process.versions.node.split('.')[0]) < 18) throw new Error('capability_unavailable: Node.js 18 or later is required'); + for (const [key, command, flags] of [['git','git',['--version']], ['python',args.python,['--version']]]) { + try { + result[key] = String(execute(command, flags, {encoding:'utf8',stdio:'pipe'})).trim(); + } catch (error) { + throw new Error('capability_unavailable: Cannot execute '+key+': '+String(error)); + } + } + const pythonVersion = result.python.match(/Python\s+(\d+)\.(\d+)/); + if (!pythonVersion || Number(pythonVersion[1]) < 3 || (Number(pythonVersion[1]) === 3 && Number(pythonVersion[2]) < 10)) + throw new Error('capability_unavailable: Python 3.10 or later is required; observed '+result.python); + for (const name of ['playwright','mathjax-full']) { + try { result[name] = resolve(name+'/package.json'); } + catch (error) { throw new Error('capability_unavailable: Cannot find module '+name+': '+String(error)); } + } + return result; +} + +function emptyOutput(directory) { + const resolved = path.resolve(directory); + if (fs.existsSync(resolved)) { + if (fs.lstatSync(resolved).isSymbolicLink() || !fs.statSync(resolved).isDirectory()) throw new Error('Output must be a regular directory'); + if (fs.readdirSync(resolved).length) throw new Error('Use an empty output directory; preserve earlier diagnostic evidence'); + } + return resolved; +} + +async function run(args, services = {}) { + if (args.pages?.length !== 1 || args['resume-from'] || args.resumeFrom) throw new Error('Diagnostic requires exactly one page and no resumed evidence'); + const output = emptyOutput(args.output); + const at = (services.now || (() => new Date().toISOString()))(); + const execute = services.execFileSync || cp.execFileSync; + const inspectPinned = services.pinnedPages || collector.pinnedPages; + const capture = services.capture || collector.run; + const failures = []; + let pinned, runtime = {}, sourceHash = null, advisories = [], captureReport = null, captureExit = null; + try { + runtime = dependencies(args, services); + pinned = inspectPinned(args); + if (pinned.pages.length !== 1 || pinned.pages[0] !== args.pages[0]) throw new Error('Pinned diagnostic scope differs from the requested page'); + const source = execute('git', ['--no-replace-objects','show',args.revision+':'+args.pages[0]], {cwd:args.root,encoding:'utf8',maxBuffer:32*1024*1024}); + sourceHash = sha256(source); + advisories = sourceAdvisories(String(source), args.pages[0]); + const log = console.log; + // The diagnostic emits one summary of its own; raw collector records remain on disk. + try { console.log = () => {}; captureExit = await capture({...args,output,diagnosticOnly:true}); } + finally { console.log = log; } + const filename = path.join(output,'hosted-report.json'); + if (!fs.existsSync(filename)) throw new Error('Collector did not produce its report'); + const bytes = fs.readFileSync(filename); + captureReport = JSON.parse(bytes); + if (captureReport.repository !== args.repository || captureReport.revision !== args.revision || + captureReport.tree !== pinned.tree || JSON.stringify(captureReport.required_pages) !== JSON.stringify(args.pages)) + throw new Error('Collector diagnostic report identity/scope mismatch'); + if (captureReport.diagnostic_only !== true) throw new Error('Collector did not mark its representative capture as diagnostic-only; use the matching current helper bundle'); + failures.push(...(captureReport.failures || [])); + if (captureExit !== 0 || captureReport.status !== 'pass') { + if (!failures.length) failures.push('Representative hosted comparison did not pass'); + } + } catch (error) { failures.push(String(error)); } + fs.mkdirSync(output,{recursive:true}); + const category = categoryFor(failures); + const filename = path.join(output,'hosted-report.json'); + const report = { + schema_version:1,kind:'hosted_probe',repository:args.repository,revision:args.revision, + tree:pinned?.tree || null,page:args.pages[0],source_sha256:sourceHash, + observed_at:at,status:failures.length?'fail':'pass',failure_category:category,failures, + runtime,advisories,diagnostic_only:true,release_ready:false,release_evidence:false, + capture_report:fs.existsSync(filename)?{path:'hosted-report.json',sha256:sha256(fs.readFileSync(filename))}:null, + limits:'One representative page at the collector\'s two viewports only. This early diagnostic is not full repository review, visual approval, scientific validation, or release-readiness evidence. Source advisories are heuristic and do not prove a rendering defect.', + next_action:!failures.length ? 'Continue furnishing; perform the complete final source-bound hosted and visual review later.' : + category === 'policy_denied' ? 'Record the denial and continue unaffected work; retry only after applicable access evidence changes, without routing around the denial.' : + category === 'access_required' ? 'Identify the actual missing access requirement and resolve it through an authorized flow; preserve the named grant and continue unaffected work.' : + category === 'capability_unavailable' ? 'Use or provision a permitted compatible runtime within the actual grant, then repeat the diagnostic; no access-setting change is implied.' : + category === 'transport_failure' ? 'Preserve this failed attempt and retry the same authorized operation after the transient transport condition changes.' : + 'Inspect the pinned source and captured representative page, repair demonstrated defects within scope, and repeat the diagnostic.' + }; + fs.writeFileSync(path.join(output,'probe-report.json'),JSON.stringify(report,null,2)+'\n'); + return {code:report.status==='pass'?0:1,report}; +} + +module.exports = {argumentsFor,sourceAdvisories,categoryFor,dependencies,emptyOutput,run}; +if (require.main === module) { + (async () => { + const args = argumentsFor(process.argv.slice(2)); + if (args.help) { console.log('probe_hosted_math.cjs --root REPO --repository owner/name --revision FULLSHA --page REPRESENTATIVE.md --output EMPTY_DIR [--contract JSON] [--python python3]'); return; } + const result = await run(args); + console.log(JSON.stringify({status:result.report.status,category:result.report.failure_category,report:path.join(path.resolve(args.output),'probe-report.json'),release_ready:false})); + process.exitCode = result.code; + })().catch(error => {console.error(String(error));process.exitCode=2;}); +} diff --git a/verification/structure_results.json b/verification/structure_results.json index 453715e..bbe7001 100644 --- a/verification/structure_results.json +++ b/verification/structure_results.json @@ -1,6 +1,60 @@ { - "status": "pass", - "checked_local_links": 184, + "status": "passed", + "generated_at_utc": "2026-11-16T14:46:25.029207+00:00", + "script_sha256": "4089bdcb3e575842519645d035c560e3561442efd89fe8c843df9704aba4d64a", + "markdown_files": 17, + "checked_local_links": 187, + "markdown_sha256": { + "README.md": "c358194b30142666ae81036e4fab8a3d2de1faf3d2409108140f75320b4e3859", + "learning/ANCHOR_BRIDGE.md": "54a959bdbca937c36b65529ba264c7122ba0cbbdf2a752a8f96e92c318792946", + "learning/MILESTONES.md": "79b239d22ba71cad5a6dfdda44d3613e9b09074aca1e1cae66860661b936bde6", + "learning/README.md": "3195f130e820a6a8ee96cb3fc18b1e6c5c45d3b69792c4c60104927007bfcbb6", + "learning/TUTORIAL.md": "bba86307ab436cbbb88f98af9dcf1f33dbefee3bdbb162248880b38cf04de263", + "references/related_work.md": "1b899391cd2956c78b5ad308b3a2733675f8c1a70ee0a120d228ab8b5b782ee7", + "science/README.md": "14f0818466859fed713a6f4885f556656ea93fbafdabb6dffbcdac4c4bfebdb6", + "science/anonymous-batches.md": "268afe3680b4b92d88540c10c3e33d01357899ec30bd3436ee20d8dfab6c4b4e", + "science/collective_attainment.md": "3d381a8fc102f5ba5fc28f460589e94237ccc24f74c38e66f1a32d515852eb55", + "science/global_converse.md": "f50811c352d3e377a8cedbbf317020b4ca1f3b7efe81225170408cbd96668bf1", + "science/interpretation.md": "a6dbe20748f4def361873efd62546c32a5b548ff6ca1c1efabd19f452085c4d8", + "science/joint_pair_readout.md": "7dce34e408e279d16dac66cabe966d4d38b4f531a89bcec4d0d2b7d228232040", + "science/model.md": "416790bf21e21a50ea3c9c856c3ce67de3508ec3d22b227fe39218c9161eb51e", + "science/resources.md": "b070223e43c7cbb777e8b10942f0dfe7b67cceb70da73999b9bd588d0c07586c", + "science/separable_readout.md": "3e93915d4f88d90716d27ab90fe5b189a08a9b271244e7b2944cf092b3847c2e", + "verification/README.md": "75599b9e60013bcd958ba4668cb12c047172602a1b0b6ad13f091617732a573d", + "verification/hosted_math/README.md": "bfec3b58f75f6486fcce17a58de9111699c3671ae44f680e0bc42530ee3a7169" + }, + "milestone_headings": [ + "M01", + "M02", + "M03", + "M04", + "M05", + "M06", + "M07", + "M08", + "M09", + "M10", + "M11", + "M12", + "M13", + "M14", + "M15", + "M16", + "M17", + "M18", + "M19", + "M20", + "M21", + "M22", + "M23", + "M24", + "M25", + "M26", + "M27", + "M28", + "M29", + "M30" + ], "errors": [], - "scope": "All current Markdown files; relative destination and heading-fragment existence, and fenced-block balance. This is a source check; actual hosted review has separate evidence." + "scope": "All current Markdown files: repository-local destinations, Markdown heading fragments, fenced-block balance, and exactly thirty ordered M01\u2013M30 milestone headings. External links, scientific truth, pedagogical quality, and actual hosted mathematics/layout are outside this check." }