From 51040e91c61acc3843680b9f664f09e9bbb79ffe Mon Sep 17 00:00:00 2001 From: docushell-admin Date: Tue, 23 Jun 2026 20:52:15 +0530 Subject: [PATCH] Record patch 0.1.1 readiness prep Signed-off-by: docushell-admin --- .../test_patch_0_1_1_readiness_prep.py | 138 ++++++++++++++++++ .../test_validation_record_integrity.py | 55 +++++++ .../scripts/validation_record_integrity.py | 2 +- CHANGELOG.md | 3 + docs/execution-status.md | 2 + docs/public-release-checklist.md | 8 + docs/validation/README.md | 6 + ...-1-readiness-prep-validation-2026-06-23.md | 61 ++++++++ 8 files changed, 274 insertions(+), 1 deletion(-) create mode 100644 .github/scripts/test_patch_0_1_1_readiness_prep.py create mode 100644 .github/scripts/test_validation_record_integrity.py create mode 100644 docs/validation/patch-0-1-1-readiness-prep-validation-2026-06-23.md diff --git a/.github/scripts/test_patch_0_1_1_readiness_prep.py b/.github/scripts/test_patch_0_1_1_readiness_prep.py new file mode 100644 index 00000000..cb62109b --- /dev/null +++ b/.github/scripts/test_patch_0_1_1_readiness_prep.py @@ -0,0 +1,138 @@ +#!/usr/bin/env python3 +# +# Copyright 2026 The Ethos maintainers +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +from __future__ import annotations + +import re +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] +RECORD = ROOT / "docs/validation/patch-0-1-1-readiness-prep-validation-2026-06-23.md" +VALIDATION_README = ROOT / "docs/validation/README.md" +EXECUTION_STATUS = ROOT / "docs/execution-status.md" +PUBLIC_RELEASE_CHECKLIST = ROOT / "docs/public-release-checklist.md" + +SOURCE_SHORT = "dd155e4" +SOURCE_COMMIT = "dd155e4f5e999da82043e2f53fa1ac8e84929118" +SOURCE_TREE = "ba0291a1c084f19d04935dc4af16fb7603388a19" + +CANDIDATE_CONTENTS = ( + "ethos doctor", + "Synthetic fixture golden-change rationale guard", + "2-minute PDF parse quickstart", + "fixtures/synthetic/simple-text/document.pdf", + "ethos doctor --require-pdfium", + "docs/pdfium-manual-setup.md", +) + +RETAINED_BLOCKERS = ( + "does not approve a release", + "version bump", + "npm publish", + "PyPI publish", + "crates.io publish", + "hosted surface", + "production positioning", + "Windows packaged artifact", + "bundled project-maintained PDFium build", + "public benchmark report", + "public benchmark claim", + "`ethos-doc`", + "`ethos-rag`", +) + +FORBIDDEN_APPROVALS = ( + "0.1.1 is approved", + "v0.1.1 is approved", + "publish 0.1.1", + "tag v0.1.1", + "production positioning approved", + "hosted surface approved", + "public benchmark claim approved", + "bundled pdfium approved", +) + + +def read(path: Path) -> str: + return path.read_text(encoding="utf-8") + + +def normalized(path: Path) -> str: + return re.sub(r"\s+", " ", read(path)) + + +class Patch011ReadinessPrepTests(unittest.TestCase): + def test_record_binds_source_and_candidate_contents(self) -> None: + text = normalized(RECORD) + raw = read(RECORD) + + self.assertIn(f"Validated source HEAD before this record: `{SOURCE_SHORT}`", raw) + self.assertIn(f"Patch-prep source commit: `{SOURCE_COMMIT}`", text) + self.assertIn(f"Patch-prep source tree: `{SOURCE_TREE}`", text) + for item in CANDIDATE_CONTENTS: + self.assertIn(item, text) + + def test_record_keeps_release_and_surface_boundaries_closed(self) -> None: + text = normalized(RECORD) + lower = text.lower() + + for blocker in RETAINED_BLOCKERS: + self.assertIn(blocker, text) + for phrase in FORBIDDEN_APPROVALS: + self.assertNotIn(phrase, lower) + self.assertIn("current public baseline remains `v0.1.0`", text) + self.assertIn("PDFium remains caller-provided through `ETHOS_PDFIUM_LIBRARY_PATH`", text) + self.assertIn("do not vet untrusted dynamic libraries", text) + + def test_record_lists_required_gates_before_patch_action(self) -> None: + text = normalized(RECORD) + + for phrase in ( + "Decide the exact patch version and surfaces", + "Update package and CLI versions only after that decision", + "Build and smoke any proposed artifacts from the exact candidate commit", + "public posture, claims, source snapshot, license/NOTICE, and private-path checks", + "manual operator evidence", + ): + self.assertIn(phrase, text) + + def test_record_is_indexed_and_status_docs_reference_it(self) -> None: + record_name = RECORD.name + + self.assertIn(record_name, read(VALIDATION_README)) + self.assertIn(record_name, read(EXECUTION_STATUS)) + self.assertIn(record_name, read(PUBLIC_RELEASE_CHECKLIST)) + + def test_record_avoids_local_private_paths(self) -> None: + text = read(RECORD) + + for private in ( + "/" + "Users/", + "/" + "private/tmp", + "/" + "private/var", + "/" + "var/folders", + "saumil" + "diwaker", + "Desktop/" + "Stuff", + "project/repo/" + "ethos", + ): + self.assertNotIn(private, text) + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/scripts/test_validation_record_integrity.py b/.github/scripts/test_validation_record_integrity.py new file mode 100644 index 00000000..3b5a192d --- /dev/null +++ b/.github/scripts/test_validation_record_integrity.py @@ -0,0 +1,55 @@ +#!/usr/bin/env python3 +# +# Copyright 2026 The Ethos maintainers +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +from __future__ import annotations + +import importlib.util +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parent +SCRIPT = ROOT / "validation_record_integrity.py" + + +def load_module(): + spec = importlib.util.spec_from_file_location( + "validation_record_integrity_under_test", + SCRIPT, + ) + if spec is None or spec.loader is None: + raise RuntimeError(f"could not load {SCRIPT}") + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +INTEGRITY = load_module() + + +class ValidationRecordIntegrityTests(unittest.TestCase): + def test_hex_ref_matcher_ignores_decimal_workflow_run_ids(self) -> None: + text = "workflow run `28004938177`, commit `dd155e4`, tree `ba0291a`" + + self.assertEqual( + sorted(set(INTEGRITY.HEX_REF.findall(text))), + ["ba0291a", "dd155e4"], + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/scripts/validation_record_integrity.py b/.github/scripts/validation_record_integrity.py index d478a97b..0f5a5436 100644 --- a/.github/scripts/validation_record_integrity.py +++ b/.github/scripts/validation_record_integrity.py @@ -28,7 +28,7 @@ ROOT = Path(__file__).resolve().parents[2] VALIDATION_DIR = ROOT / "docs/validation" VALIDATION_README = VALIDATION_DIR / "README.md" -HEX_REF = re.compile(r"`([0-9a-f]{7,40})`") +HEX_REF = re.compile(r"`(?=[0-9a-f]*[a-f])([0-9a-f]{7,40})`") PRIVATE_MARKERS = ( "/" + "Users/", "/" + "private/tmp", diff --git a/CHANGELOG.md b/CHANGELOG.md index ad4aff9f..50a6072d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +- boundary-exception: add patch `0.1.1` readiness-prep record for review only; no version bump, release approval, artifact approval, package publication, or support-boundary change. +- process-follow-up: record patch `0.1.1` readiness prep contents and retained blockers without approving release action or changing versions. +- process-follow-up: keep validation-record integrity from treating decimal workflow run IDs as git refs. - cli: point missing or unusable PDFium errors to `ethos doctor`, `ethos doctor --require-pdfium`, and the manual setup doc without changing exit codes. - docs: add a bounded 2-minute PDF parse quickstart using the synthetic born-digital fixture and `ethos doctor --require-pdfium`. - boundary-exception: add `ethos doctor` docs pointer for caller-provided PDFium diagnostics; no PDFium posture or support-boundary change. diff --git a/docs/execution-status.md b/docs/execution-status.md index 8a3b2252..ad8a1a45 100644 --- a/docs/execution-status.md +++ b/docs/execution-status.md @@ -251,6 +251,8 @@ The package publication public installation availability record in `docs/validat The public evaluation current-state closeout record in `docs/validation/milestone-e-public-evaluation-current-state-closeout-validation-2026-06-22.md` records current main `034881e` / tree `fb089e027641a7d2152d7d1ebd499f45bb1f6a1c` as GitHub source repository plus `ethos-doc-core`, `ethos-verify`, and `ethos-pdf` at `0.1.0` for Rust crate evaluation. Hosted surfaces, production positioning, public benchmark claims, CLI distribution, wheels, npm packages, binaries, project-maintained PDFium builds, `ethos-doc`, `ethos-rag`, and broader public wording remain blocked. +The patch `0.1.1` readiness prep record in `docs/validation/patch-0-1-1-readiness-prep-validation-2026-06-23.md` records candidate onboarding contents after `ethos doctor`, synthetic fixture golden-change guarding, the 2-minute PDF parse quickstart, and improved missing/unusable PDFium guidance landed on `main`. This is a prep record only: it does not approve a release, tag, version bump, package publish, GitHub Release artifact, hosted surface, production positioning, Windows packaged artifact, bundled project-maintained PDFium build, public benchmark report, or public benchmark claim. The current public baseline remains `v0.1.0` until a separate release decision, version update, artifact build, smoke evidence, and operator action are completed. + | Work item | Current status | Remaining blocker | | --- | --- | --- | | PDFium Phase 1 profile | Landed: pinned profile, V8/XFA-disabled state, platform hashes, runtime library hashes, and provenance are recorded | Phase 2 project-maintained builds still block Public Beta | diff --git a/docs/public-release-checklist.md b/docs/public-release-checklist.md index e62f6f57..f810506e 100644 --- a/docs/public-release-checklist.md +++ b/docs/public-release-checklist.md @@ -11,6 +11,14 @@ preflight passes and the current claim language is used. The package-name/tradem closed by ADR-0006, but public benchmark, parser-quality, table, heading, speed, footprint, and rendered-crop byte-identity claims remain blocked. +Patch `0.1.1` readiness prep is recorded in +`docs/validation/patch-0-1-1-readiness-prep-validation-2026-06-23.md` for review only. It records +candidate onboarding contents after `ethos doctor`, synthetic fixture golden-change guarding, the +2-minute PDF parse quickstart, and improved missing/unusable PDFium guidance landed on `main`. It +does not approve a release, tag, version bump, package publish, GitHub Release artifact, hosted +surface, production positioning, Windows packaged artifact, bundled project-maintained PDFium +build, public benchmark report, or public benchmark claim. + ## Required Before Public Push - Package-name and trademark decision is closed by accepted ADR-0006 in diff --git a/docs/validation/README.md b/docs/validation/README.md index 70cc9d78..1b7eb845 100644 --- a/docs/validation/README.md +++ b/docs/validation/README.md @@ -555,6 +555,12 @@ recording the exact current-main source candidate and required follow-up evidenc shasum, integrity, file count, unpacked size, npm's publish-time bin-name auto-correction warning, and retained blockers for hosted, production, Windows, bundled PDFium, `ethos-doc`, `ethos-rag`, and public benchmark surfaces. +- `patch-0-1-1-readiness-prep-validation-2026-06-23.md` - patch 0.1.1 readiness prep validation + records candidate onboarding contents after `ethos doctor`, synthetic fixture golden-change + guarding, the 2-minute PDF parse quickstart, and improved missing/unusable PDFium guidance landed + on `main`; no release, tag, version bump, package publish, GitHub Release artifact, hosted + surface, production positioning, Windows packaged artifact, bundled project-maintained PDFium + build, public benchmark report, or public benchmark claim is approved. - `milestone-e-validation-command-index-validation-2026-06-20.md` - internal Milestone E validation-command index validation passed through command-alignment checks, schema enum checks, row-record checks, public-surface posture checks, `make milestone-e-prep`, and diff hygiene; the diff --git a/docs/validation/patch-0-1-1-readiness-prep-validation-2026-06-23.md b/docs/validation/patch-0-1-1-readiness-prep-validation-2026-06-23.md new file mode 100644 index 00000000..6acb4846 --- /dev/null +++ b/docs/validation/patch-0-1-1-readiness-prep-validation-2026-06-23.md @@ -0,0 +1,61 @@ +# Patch 0.1.1 Readiness Prep Validation - 2026-06-23 + +## Purpose + +Record the candidate contents and remaining gates for a possible patch `0.1.1` review after the +post-`0.1.0` onboarding fixes landed on `main`. + +Validated source HEAD before this record: `dd155e4`. +Patch-prep source commit: `dd155e4f5e999da82043e2f53fa1ac8e84929118`. +Patch-prep source tree: `ba0291a1c084f19d04935dc4af16fb7603388a19`. + +## Candidate Contents + +The candidate patch contents are limited to user-facing setup and onboarding improvements: + +- `ethos doctor` PDFium diagnostics. +- Synthetic fixture golden-change rationale guard. +- Bounded 2-minute PDF parse quickstart using `fixtures/synthetic/simple-text/document.pdf`. +- Missing or unusable PDFium setup guidance that points to `ethos doctor`, + `ethos doctor --require-pdfium`, and `docs/pdfium-manual-setup.md`. + +## Boundary + +This prep record does not approve a release, tag, package publish, GitHub Release artifact, +version bump, npm publish, PyPI publish, crates.io publish, hosted surface, production positioning, +Windows packaged artifact, bundled project-maintained PDFium build, public benchmark report, public +benchmark claim, `ethos-doc`, or `ethos-rag`. + +The current public baseline remains `v0.1.0` until a separate release decision, version update, +artifact build, smoke evidence, and operator action are completed. + +PDFium remains caller-provided through `ETHOS_PDFIUM_LIBRARY_PATH`. The setup checks only whether +the configured PDFium is usable by Ethos; they do not vet untrusted dynamic libraries. + +## Required Before Any Patch Release Action + +- Decide the exact patch version and surfaces in a separate decider step. +- Update package and CLI versions only after that decision. +- Run the release-candidate prep gates from the exact candidate commit. +- Build and smoke any proposed artifacts from the exact candidate commit. +- Re-run public posture, claims, source snapshot, license/NOTICE, and private-path checks after + any version or public-facing wording changes. +- Record manual operator evidence for any credentialed publish or GitHub Release action. + +## Validation Commands + +The prep lane should pass at least: + +```sh +cargo fmt --check +cargo test --locked -p ethos-cli --test doctor +cargo test --locked -p ethos-pdf +PYTHONPATH=python python3 python/tests/test_cli_surface.py +python3 .github/scripts/test_pdfium_manual_setup_contract.py +python3 .github/scripts/test_release_artifact_workflow_prep.py +python3 .github/scripts/test_patch_0_1_1_readiness_prep.py +make light-check PYTHON=python3 +``` + +Manual successful PDF parse smoke remains optional unless a trusted caller-provided PDFium dynamic +library is available locally.