Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
name: EdgeMech public sample browser

on:
pull_request:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: edge-pages-${{ github.ref }}
cancel-in-progress: true

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: '3.13'
- uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
with:
node-version: '22'
- run: node --test tests/browser.test.cjs
- name: Validate public input bindings
run: PYTHONPATH=src python -m edgemech.site --plan
- name: Persist and verify one real occurrence
run: PYTHONPATH=src python -m edgemech.site --canary --output build/pages
- name: Retain canary before full build
run: mv build/pages build/canary
- name: Build the complete public sample
run: PYTHONPATH=src python -m edgemech.site --output build/pages
- uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
if: github.ref == 'refs/heads/main'
with:
path: build/pages

deploy:
if: github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
- name: Deploy public sample
id: deployment
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

Release-occurrence accounting and inherited native-review eligibility for KG-Microbe.

## Public sample browser

The [static sample browser](docs/public-sample-browser.md) provides search, filters,
stable occurrence details and downloads for the committed 10,000-occurrence sample.
It keeps the 100 historical canary assessments separate from inherited rule labels
and from the dated full-population census. It does not host the complete graph or
grant scientific approval. The Pages workflow builds pull requests and publishes
only after a reviewed merge to `main` and repository Pages setup.

EdgeMech keeps bulk rows and decision histories in immutable external Parquet artifacts and queries them with DuckDB. Shared contracts are owned by CultureBotAI/culturebotai-claw. Scientific records and decisions remain in their native Mechs.

Development scope: CLAW issues #766 and #767. No live curation worker, published site, or scientific approval is implied.
Expand Down
113 changes: 113 additions & 0 deletions docs/public-sample-browser.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# Public occurrence sample browser

The static browser publishes a projection of the **10,000-occurrence sample
selected on 2026-11-12**, with 8,500 occurrences retained in the curated derivative
and 1,500 omitted. It searches the original subject, predicate, object, labels,
transform and occurrence identifier. It does not search the complete KG-Microbe
graph. Occurrence multiplicity is preserved; matching triples are not collapsed.

The two committed 50-occurrence cohorts from November 12 and 13 contribute
separate historical source-fidelity and scientific-support fields. Missing
assessment is explicit for the other 9,900 occurrences. The canaries are purposive,
their automated assessments are historical, and independent calibration is not
claimed. Open review branches are not incorporated. Inherited rule labels such as
`accurate_direct_evidence` are displayed as recorded provenance, never converted
into scientific approval. Original triples and recorded curated changes remain
distinct. Assessments retain their own recorded claim targets.

A separate dated section summarizes the November 7 native-overlap census of
17,637,435 occurrences in the September 29 snapshot. Its zero `exact_eligible`
count means no exact inherited-scope transfers in that census. It does not mean
that the graph has no valid biology. The census population is not the sample's
assessment denominator. External Parquet partitions are not hosted or advertised
as downloadable. This browser does not extend the local reader's publication
authority or imply remote access to its private artifacts.

## Publication boundary

`python -m edgemech.site` uses only seven named, committed public inputs. Every
input must be byte-identical to the full `--source-ref` Git commit (default:
`HEAD`), and the sample digest must also match its retained sampling metadata.
Unknown or duplicate occurrence IDs, mismatched original claims, overlapping
cohorts, incomplete assessment axes, and inconsistent census counts fail the
build before the destination is published. No external service is called.

The JSON/CSV projection allowlists identifiers, labels, sampling fields, recorded
states, authored rationales, model attribution, source paths and hashes. It omits
retrieved quotations, private paths, full source records, evidence packets and
bulk graph files. Original sampling metadata explicitly says full private input
SHA-256 hashes were not computed; hashes of public derivatives do not repair that
limitation. Details and the static catalogue link to the complete, pinned raw
source manifest and visibly retain its SHA-256 and the 1-based source line. They
do not use GitHub blob line anchors: GitHub cannot render this 7.85 MB JSONL file
as a line-addressable page. Original occurrence identity and tuples remain in
the browser and can be located at the stated line in the downloaded manifest.

No repository-wide license declaration was present when this browser was added.
The browser does not invent or grant one; upstream source terms still apply.
CSV cells starting with spreadsheet-formula characters (including after
whitespace) are prefixed with an apostrophe. JSON retains their exact text.

## Build and canary

The builder itself requires only the Python standard library. From this repository:

```sh
PYTHONPATH=src uv run --frozen python -m edgemech.site --plan
PYTHONPATH=src uv run --frozen python -m edgemech.site --canary --output build/pages
```

The canary traverses the same projection, file-writing, verification and staging
path as the full build, using one real assessed occurrence. It reopens the
persisted JSON and checks exact bytes and record count. The output is prominently
marked as a one-record canary. Inspect `build/pages/build-receipt.json`, verify the
nonempty JSON/CSV/catalogue outputs, and run the browser check below with `--canary`.
Then preserve the canary and use the same output path for the full build:

```sh
mv build/pages build/canary
PYTHONPATH=src uv run --frozen python -m edgemech.site --output build/pages
```

An existing output destination is refused; archive it under a new name before
rebuilding. Staging is private to the new build and published by a directory
rename after validation. Generated site files stay under ignored `build/`.
`sample.json`, `sample.csv`, `build-receipt.json`, and the paginated static
catalogue are deterministic for the same input revision and builder sources.
The site uses no CDN, remote JavaScript, analytics, embeddings or graph API.

The optional render check needs Playwright and an installed Chromium/Chrome.
Use the same Python launcher, browser and output path for canary and full checks:

```sh
python scripts/adhoc/check_browser_20261119.py --site build/pages \
--output .temp/browser-qa --canary --browser /path/to/chrome
# Archive the canary receipt/screenshots before the full check.
python scripts/adhoc/check_browser_20261119.py --site build/pages \
--output .temp/browser-qa --browser /path/to/chrome
uv run --frozen pytest -q
uv run --frozen ruff check src/edgemech tests scripts/adhoc
node --test tests/browser.test.cjs
```

The render check verifies desktop and 390px mobile layouts, detail permalink
reload, filter counts, independent assessment axes, empty/reset behavior, literal
markup queries, keyboard movement, CSV persistence, no-JavaScript catalogue,
asset-load failure, and every generated output hash. It writes screenshots and a
JSON receipt. The one-record canary does not exercise full-corpus filter counts or
pagination; the full check does.

## GitHub Pages

The Pages workflow checks PR builds and publishes **only from `main`** after a
reviewed merge. Repository Settings → Pages must select **GitHub Actions** before
the first deployment. This PR does not itself enable Pages or authorize a merge.
The intended URL after a successful deployment is
`https://culturebotai.github.io/EdgeMech/`. Do not advertise it as live before
verifying the actual deployment and served page. The workflow deploys only
`build/pages`, never the source checkout or `workspace/`.

Query parameters preserve search/filter/page state. `?id=<occurrence_id>#detail`
opens a stable detail within this fixed sample. Every table and detail value is
rendered as text; no content becomes HTML. A paginated catalogue, source links,
and downloads remain available with JavaScript disabled.
64 changes: 64 additions & 0 deletions docs/validation/public-browser-20261119/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Public browser validation — 2026-11-19

Public inputs were read from commit
`f841b1dff874e78d1a14075413be6a92c90f1378`. The builder and generated output hashes
are recorded in `build-receipt.json`; this source commit identifies the retained
data, not the later browser implementation commit.

The one-record canary used the first real retained occurrence, including both
historical assessment axes, through the same Python launcher, builder, output
path (`build/pages`), local HTTP server, installed Chrome and browser-check output
path (`.temp/browser-qa`) as the full run. Canary output and its render evidence
were archived before the full run. Persisted bytes, output hashes, record count,
stable detail reload, literal markup search, empty/reset behavior, keyboard
navigation, mobile containment, the no-JavaScript catalogue and load failure
passed. The full run additionally checked 100 assessed / 9,900 unassessed cohort
filter counts, independent science filtering, a persisted filtered CSV download,
and pagination restored by URL.

The full payload has 10,000 occurrences; 100 retain historical assessments.
The JSON is 7,772,380 bytes, or 1,225,174 bytes under deterministic gzip.
The 106 generated files total 18,727,800 bytes before the receipt itself.
The site includes 100 static catalogue pages. No external graph, model or
scientific API calls were made. There were no browser JavaScript errors.

Receipts:

- `canary-browser.json`: one-record persisted/rendered canary.
- `full-browser.json`: complete sample and render verification.
- `build-receipt.json`: exact public inputs and every generated output hash.
- `source-link-227.json`: one real HTTP download of the pinned source manifest,
verified against the byte count, hash and canary occurrence's source line.
- `review-resolution-227.md`: independent review finding and its resolution.

Desktop and mobile screenshots remain in the isolated clone under
`.temp/browser-qa/`; they were visually inspected. The retained checker is
`scripts/adhoc/check_browser_20261119.py`. It accepts an explicit installed
`--browser` executable and does not modify the shared EdgeMech checkout or Python environment.
It opens the local built site only.

Validation commands used the existing EdgeMech Python environment with
`PYTHONDONTWRITEBYTECODE=1` and `PYTHONPATH=src`, without modifying that environment:

```sh
python -m edgemech.site --plan
python -m edgemech.site --canary --output build/pages
# Run the browser checker with --canary and archive its outputs.
python -m edgemech.site --output build/pages
python scripts/adhoc/check_browser_20261119.py --site build/pages \
--output .temp/browser-qa --browser /path/to/installed/chrome
python -m pytest -q -p no:cacheprovider
ruff check src/edgemech tests scripts/adhoc --no-cache
python -m edgemech check-contracts
node --test tests/browser.test.cjs
UV_CACHE_DIR=.temp/uv-cache uv build --offline --no-build-isolation --python /path/to/python
```

The complete suite passed 712 tests (14 browser-publication tests included),
all four Node behavior tests passed, Ruff passed, and all 16 pinned CLAW contract
files verified. Source and wheel distributions built offline; the wheel contains
the builder and all three HTML/CSS/JavaScript assets. Existing-output rejection
and deterministic two-build canary reproduction are covered by the Python tests.

This validates a local build. It does not claim a successful GitHub Pages
deployment or authorize merging the browser PR.
Loading