Reuse publication metadata: 15.7% less complete-check time (no κ)

research/publication-metadata-reuse/PROOF.md

@@ -0,0 +1,58 @@
+# Acceptance equivalence and implementation limits
+
+Assume the same stable working tree, publication commit and ordinary successful
+Git object reads as the original check. Both implementations inventory the same
+regular committed files, compare every working byte, and complete the blob
+iterator's final Git-status check before returning success.
+
+The original check then calls `publication_sources()`, which reads the size and
+bytes of `commit:package/SOURCES.json` through two additional Git processes.
+The candidate retains that same immutable blob from the existing inventory
+comparison. It retains its bytes only when their size is at most the existing
+16 MiB metadata limit. For an oversized blob it retains only its size, then
+rejects after the complete comparison iterator finishes. A missing metadata file
+still rejects only when history checking was requested.
+
+Both paths check the missing/size conditions, parse the same JSON bytes and call
+exactly the same metadata/history validator. Therefore successful runs have
+identical complete result dictionaries and the same declared pin acceptance.
+The standalone `source_history()` still authenticates its own metadata through
+`publication_sources()`. The new internal helper is called only with JSON from
+these committed-byte boundaries.
+
+Malformed JSON is parsed after the complete byte comparison, as before. Working
+metadata drift and a final blob-reader failure still precede parsing. All
+metadata shape, row/count limits, exact commit IDs, raw ancestry, shallow history,
+replacement/graft isolation, retained Git errors and timeout checks are unchanged.
+The candidate no longer performs the two duplicate Git reads, so failures injected
+only into those removed operations have no counterpart. This is an acceptance
+argument on successful immutable reads, not an identical subprocess trace claim.
+Concurrent checkout mutation remains outside the original stable-checkout contract.
+
+Eight new tests use actual committed fixture bytes. They cover no metadata refetch,
+the standalone reader, drift before parsing, malformed committed JSON, final-reader
+failure before parsing, committed versus later working bytes, exact size bounds,
+absence of cross-call caching and explicit older publications. Existing history,
+byte, execute-mode and replacement tests remain in the registered suite. Finite
+controls corroborate the argument; they are not a proof-kernel formalization.
+
+## Code constraints
+
+The additional retained payload is at most 16 MiB, local to one call, with no new
+loop or subprocess. The original blob reader still allocates each complete blob;
+its existing allocation is outside this change. Python runtime allocation is a
+managed-runtime deviation from fixed allocation. Existing input bounds, finite
+file inventories and Git timeouts apply. The now 58-line check function is kept
+as one inventory/comparison transaction; splitting it would introduce a second
+owner for the captured metadata. No recursive call is added. Explicit `require`
+checks remain active under optimized Python.
+
+The optional benchmark loads one fixed, pinned historical Python module through
+importlib. This bounded baseline-loading exception adds no dynamic dispatch to
+the production preflight. It times complete `check()` calls and requires full
+result equality for every sample. Profile measurements are not included among
+the reported timing samples. Timing numbers do not predict a mathematical replay
+or physical multiplier speedup.
+
+No selected cold replay, Lean, Docker, physical multiplier or supplier admission
+was run. Independent human and formal proof-kernel review are unclaimed.

research/publication-metadata-reuse/README.md

@@ -0,0 +1,86 @@
+# Reuse authenticated publication metadata
+
+The complete publication byte/history check can avoid two duplicate Git
+processes. `check()` already reads the committed `SOURCES.json` blob and compares
+it with the working file. It now retains those immutable bytes for the subsequent
+source-history validation. The standalone `source_history()` interface and every
+source-commit resolution and ancestry query remain.
+
+This is a measured verifier improvement with a scoped equivalence argument and
+finite executable controls. It supplies no mathematical construction, supplier
+admission, complete multiplication theorem or new kappa. No predecessor
+mathematical verifier is run by this package.
+
+## Evidence
+
+On CPython 3.12.15, macOS arm64, nine alternating baseline/candidate complete
+checks per package gave:
+
+| Unchanged package | Baseline median, range | Candidate median, range | Reduction |
+| --- | --- | --- | --- |
+| `stage-zero-forced-translation` | 121.65 ms, 117.86–132.99 | 99.36 ms, 97.92–102.72 | 18.33% |
+| `p104-helper470-twin-rung-removal` | 120.33 ms, 118.24–126.17 | 101.49 ms, 98.93–103.96 | 15.66% |
+
+All 36 timed checks returned identical complete receipts within their package;
+no timed call failed. Each call checks the full package/input inventory, exact
+working/committed bytes, committed source metadata, shallow-history guard and
+all declared source-commit ancestry. These are complete `check()` function times
+in a warm Python process. Imports, baseline extraction and CLI startup are outside
+the timed region. Mathematical replay is outside the measured workload.
+
+A separate profile attributed 109 of 130 ms to synchronous Git subprocess
+calls, including 21 ms in the duplicate metadata reader. For these one-pin
+packages, history-specific Git calls fall from five to three and total Git
+processes from nine to seven. The host had 18 logical CPUs and load averages
+5.76, 3.64 and 2.80 at orientation; other work was active. Alternating samples
+have separated ranges. There is no cross-host speed claim.
+
+[PROOF.md](PROOF.md) gives the acceptance argument, bounded retention, failure
+ordering, controls and implementation limits. The registered verifier runs the
+new tests plus retained history, byte, executable-mode and replacement controls.
+Its generated stdout receipt binds all executed test files and their shared
+scripts by SHA256, including the exporter and scaffold imported by replacement
+controls. [TASK.json](TASK.json) records the scope and next question.
+
+## Reproduce
+
+From the repository root:
+
+```sh
+/Users/nick/git/integer-mult-bounds/.venv/bin/python3.12 -I -W error -B research/publication-metadata-reuse/verify.py
+/Users/nick/git/integer-mult-bounds/.venv/bin/python3.12 -I -O -W error -B research/publication-metadata-reuse/verify.py
+/Users/nick/git/integer-mult-bounds/.venv/bin/python3.12 -B scripts/research_package.py --package research/publication-metadata-reuse
+/Users/nick/git/integer-mult-bounds/.venv/bin/python3.12 -B scripts/check_research_commit.py --package research/publication-metadata-reuse --check-source-history
+```
+
+Elsewhere substitute CPython 3.12. Git and full source history are required.
+Tests create and remove only synthetic temporary repositories. They do not
+change project refs or execute predecessor mathematical packages.
+
+For optional timing, first materialize both benchmark packages and their
+`VERIFY.json` inputs. Use an existing directory outside the checkout:
+
+```sh
+/Users/nick/git/integer-mult-bounds/.venv/bin/python3.12 -I -W error -B research/publication-metadata-reuse/benchmark.py --scratch /absolute/external/scratch --repeats 9
+```
+
+The benchmark obtains the baseline from immutable Git objects at
+`721c03822c421b7f7fcbb2598993b947c4d88419`, compares complete receipts, records
+every sample and source hash, and removes its temporary baseline module.
+Timing is optional and has no CI speed threshold.
+
+## Open next questions
+
+Does the same saving remain measurable on a second operating system and Git
+implementation? Run the same complete-check benchmark on unchanged fixtures,
+with imports outside both arms. A second host and materialized inputs are
+required. Joint ancestry batching is separate open work.
+
+## Credit
+
+This contribution was produced by Nick Petalas. Credit ywz65 for the publication
+byte preflight, Nick Petalas for its original source-history check, roger-sato
+for immutable Git source isolation, Douglas Colkitt for the package runner and
+the retained source-reader contributors. Reusing immutable bytes is an ordinary
+technique; the contribution is its bounded integration, failure controls and
+measured complete-check improvement. Apache-2.0. Existing notices are unchanged.

research/publication-metadata-reuse/SOURCES.json

@@ -0,0 +1,24 @@
+{
+  "schema_version": 1,
+  "base_commit": "721c03822c421b7f7fcbb2598993b947c4d88419",
+  "files": [
+    {
+      "path": "certificates/selected-result.json",
+      "usage": "provenance",
+      "git_blob": "d59b5035e7b4cbaa9d688a1d32dd0d6eb79c466a",
+      "sha256": "9b8d0eea95b3bf0dfcb7938a732a6439b87a2685dec2a5ab9e525b3b34debbfa"
+    },
+    {
+      "path": "docs/research/agent-task-catalog.json",
+      "usage": "provenance",
+      "git_blob": "3404fbdd5e7529a0674eef26114b5071e4586cec",
+      "sha256": "ead6cdc9d0af6d58e8a49744d8ec8c7c15e13d2ba93c276c434bcf9b51b93a81"
+    },
+    {
+      "path": "scripts/check_research_commit.py",
+      "usage": "provenance",
+      "git_blob": "dc0be6c743f79b3131e674d92c81b75b069812c9",
+      "sha256": "63026ec3805f2a3236cc071fc78cf1c54bc6528c43e2f3d82548dc68bf346bce"
+    }
+  ]
+}

research/publication-metadata-reuse/TASK.json

@@ -0,0 +1,61 @@
+{
+  "schema_version": 1,
+  "task_id": "replay-runtime",
+  "priority_revision": 8,
+  "base_commit": "721c03822c421b7f7fcbb2598993b947c4d88419",
+  "original_card": {
+    "id": "replay-runtime",
+    "question": "Can one measured replay bottleneck be sped up without dropping coverage?",
+    "starting_points": [
+      "scripts/run_isolated_tests.py",
+      "scripts/verify_replay_coverage.py",
+      "certificates/selected-result.json"
+    ],
+    "methods": [
+      "Profile one isolated replay and optimize the measured bottleneck.",
+      "Design source-bound reuse with explicit dependency invalidation and negative controls."
+    ],
+    "acceptance_gate": "Report before/after wall time on the same fixture, retained checks and invalidation behavior.",
+    "first_step": {
+      "command": [
+        "python3",
+        "-B",
+        "scripts/research_selected_baseline.py"
+      ],
+      "expected": "PASS_RESEARCH_BASELINE_BINDINGS_ONLY",
+      "inspect": "Resolve the current selected review, separate complex/ordinary BIT/admitted BIT/outer budgets, and compare the card against live handoffs before starting. Historical ceilings require exact source/model equivalence.",
+      "scope": "Source-binding orientation only; not a scientific replay or all-size proof. Materialize selected inputs if this checkout is sparse."
+    },
+    "first_experiment": "Measure one unchanged fixture, preserve check coverage, and test one optimization with invalidation controls.",
+    "bottleneck_link": "Faster trustworthy replays increase review throughput and let mechanism candidates be checked sooner.",
+    "allowed_variations": [
+      "Profile one stage or design one source-bound cache boundary."
+    ],
+    "scope_change_triggers": [
+      "Skipping coverage or comparing different fixtures to claim speedup."
+    ],
+    "overlap_terms": [
+      "replay runtime",
+      "cache invalidation",
+      "isolated tests"
+    ]
+  },
+  "scope_status": "refined",
+  "actual_scope": "Reuse the committed SOURCES.json payload already authenticated by the complete publication byte/history check, without changing ancestry operations.",
+  "scope_change_reason": "The replay-runtime card is narrowed to duplicate publication metadata reads; it is a tooling improvement, not a mathematical replay.",
+  "bottleneck_link": "Publication preflight is required before research submission; avoiding duplicate immutable-source reads reduces that wait while preserving its evidence contract.",
+  "budget_minutes": 60,
+  "stop_rule": "Stop at the first reproducible complete-check improvement with identical receipts and passing rejection controls; otherwise publish a bounded negative finding.",
+  "outcome": "completed",
+  "evidence": "Nine alternating runs per arm on each of two real packages; all 36 complete receipts match within package. Median reductions 18.33% and 15.66%. Hash-bound controls and optional benchmark emit stdout receipts.",
+  "author": "Nick Petalas",
+  "ai_assistance": "Independent human and formal proof-kernel review are unclaimed.",
+  "open_questions": [
+    {
+      "question": "Does the same complete-check improvement remain measurable on a second operating system and Git implementation?",
+      "why_it_matters": "The local improvement does not establish cross-host timing behavior.",
+      "first_step": "Run benchmark.py on the same two unchanged package inventories, with nine alternating samples and complete receipt equality.",
+      "blocked_by": "A second host and matching materialized fixtures."
+    }
+  ]
+}

research/publication-metadata-reuse/VERIFY.json

@@ -0,0 +1,44 @@
+{
+  "schema_version": 1,
+  "status": "ready",
+  "python": "3.12",
+  "requirements": [],
+  "inputs": [
+    "scripts/check_research_commit.py",
+    "scripts/research_package.py",
+    "scripts/export_research_package.py",
+    "scripts/new_research_package.py",
+    "tests/test_research_publication_metadata_reuse.py",
+    "tests/test_research_source_history.py",
+    "tests/test_research_commit_bytes.py",
+    "tests/test_research_commit_modes.py",
+    "tests/test_research_git_replacements.py"
+  ],
+  "commands": [
+    {
+      "argv": [
+        "{python}",
+        "-I",
+        "-W",
+        "error",
+        "-B",
+        "{package}/verify.py"
+      ],
+      "timeout_seconds": 120,
+      "checks": "Run new immutable-metadata handoff controls and retained history, byte, mode and replacement tests; emit a hash-bound coverage receipt."
+    },
+    {
+      "argv": [
+        "{python}",
+        "-I",
+        "-O",
+        "-W",
+        "error",
+        "-B",
+        "{package}/verify.py"
+      ],
+      "timeout_seconds": 120,
+      "checks": "Repeat all same controls under optimized Python; explicit validation must remain active."
+    }
+  ]
+}

research/publication-metadata-reuse/benchmark.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Compare complete publication checks, with imports and profiling outside timing."""
+import argparse
+import hashlib
+import importlib.util
+import json
+from pathlib import Path
+import platform
+import statistics
+import subprocess
+import sys
+import tempfile
+import time
+
+ROOT = Path(__file__).resolve().parents[2]
+BASE = '721c03822c421b7f7fcbb2598993b947c4d88419'
+PACKAGES = ('research/stage-zero-forced-translation',
+            'research/p104-helper470-twin-rung-removal')
+
+
+def load_module(name, path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise ValueError('cannot load checker: ' + str(path))
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def compare(baseline, candidate, package, repeats):
+    samples = {'baseline': [], 'candidate': []}
+    receipt = None
+    for _ in range(repeats):
+        for arm, checker in (('baseline', baseline), ('candidate', candidate)):
+            start = time.perf_counter()
+            result = checker.check(ROOT, package, BASE, check_source_history=True)
+            samples[arm].append(time.perf_counter() - start)
+            if receipt is None:
+                receipt = result
+            if result != receipt:
+                raise ValueError('complete publication receipts differ')
+    summary = {}
+    for arm, values in samples.items():
+        summary[arm] = {'seconds': values, 'median_seconds': statistics.median(values),
+                        'range_seconds': [min(values), max(values)]}
+    summary['fraction_reduced'] = 1 - (summary['candidate']['median_seconds'] /
+                                       summary['baseline']['median_seconds'])
+    return {'package': package, 'complete_receipt': receipt, 'samples': summary,
+            'successful_checks': 2 * repeats, 'errors': 0}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--scratch', type=Path, required=True)
+    parser.add_argument('--repeats', type=int, default=9, choices=range(5, 32))
+    args = parser.parse_args()
+    if not args.scratch.is_dir():
+        parser.error('--scratch must name an existing external directory')
+    if args.scratch.resolve().is_relative_to(ROOT):
+        parser.error('scratch must be outside the checkout')
+    sys.path.insert(0, str(ROOT / 'scripts'))
+    import research_package as runner
+    original = subprocess.run(
+        ['git', 'show', BASE + ':scripts/check_research_commit.py'], cwd=ROOT,
+        env=runner.git_source_env(), capture_output=True, check=True, timeout=30).stdout
+    current = ROOT / 'scripts/check_research_commit.py'
+    with tempfile.TemporaryDirectory(dir=args.scratch) as temporary:
+        path = Path(temporary) / 'baseline.py'
+        path.write_bytes(original)
+        baseline = load_module('baseline_publication_checker', path)
+        candidate = load_module('candidate_publication_checker', current)
+        results = [compare(baseline, candidate, name, args.repeats) for name in PACKAGES]
+    report = {'schema': 'publication-metadata-reuse-benchmark/v1', 'base_commit': BASE,
+              'python': sys.version, 'platform': platform.platform(),
+              'baseline_sha256': hashlib.sha256(original).hexdigest(),
+              'candidate_sha256': hashlib.sha256(current.read_bytes()).hexdigest(),
+              'runner_sha256': hashlib.sha256((ROOT / 'scripts/research_package.py').read_bytes()).hexdigest(),
+              'timed_region': 'complete check(); imports and baseline extraction excluded',
+              'order': 'baseline,candidate repeated', 'results': results}
+    print(json.dumps(report, sort_keys=True))
+
+
+if __name__ == '__main__':
+    main()