DRAFT (phase 3, after T063): T095, AT-R1's HTTP half: an acceptance harness in its own CI job, with no database service (plan 034)

[brettheap]

Plan 034, task T095, slice acceptance (AT-R1, the HTTP half), phase 3. The plan is specs/034-opendox-standalone-operation/tasks.md at opensoft/openxFactory main 80217a92, § "Acceptance: AT-R1". It realizes FR-011's HTTP half.

Arc: neutral-product-standalone-operability
Lane: openxfactory-4 (openXfactory-4-openDox_extraction)

• Claim: openxFactory#656 comment 5961416730.
• Rulings: 5961364221 item 2 (T095 is drafted now and does not go READY before T063 lands); 5850003126 (R1Q10 (a), R1Q12 (a), R1Q13 (a) with (c), R1Q15 (b), R1Q16 (iii) and (iv)).
• State: DRAFT. It lands after T089 and T104 (openDox-code#84), per the holder. The holder posts READY and the landers merge; this writer does neither.

On this PR, acceptance is EXPECTED red; validate stays green

Most of the stack the harness drives has landed. main 390e2c28 (2026-10-03) carries:

• T071, 13.2 and 13.3: load_settings refuses a non-PostgreSQL DSN and a collapsed DSN pair (plan 034) #60 (T071) and T088, the lens's two seed actions are offered only where a binding answers them (R1Q19 (a)) (plan 034) #65 (T088);
• T070, 13.4-13.6: OPENDOX_INSTALL_MODE and generate-and-open --local (plan 034) #67 (T070) and T072, 13.1: the bundled PostgreSQL server, the local install's own child (plan 034) #69 (T072, the bundled server and the local extra);
• T085, the standalone doxBench defaults for T027's seams, and T058's two workbench rules move into opendox.validator (plan 034) #71 (T085), T073, 13.4a — /capabilities gains an install block, read from the serving process's own settings (plan 034) #72 (T073) and T075, 10.2 and 10.2a — an installed entry point serves all 42 bundle files; intent-feed.js is not owed (plan 034) #73 (T075);
• T081, 16.4: "no model configured" is a state, shown before any turn (plan 034) #74 (T081), Broker-path credential hardening (follows T080): a minted token keeps a built-in credential's rules (plan 034) #64, T084, 4.3: the last deferred reaches through declared seams; consumer_reach retired (plan 034) #77 (T084) and T103, every loopback route checks the Host (DNS rebinding) (plan 034) #80 (T103).

Still a draft: #84 (T104, the console token via the opened URL).

This head reads the console token the way T104 delivers it (section 6 below). At this branch (main plus the harness), the acceptance job therefore fails by design, at [a.capabilities carries no console token], until T104 lands (quoted below). Against a local integration that includes #84, the same harness passes. The validate job runs the whole suite as before, and is green.

Making acceptance a required check is a ruleset change for the repository's owner (docs/branch-protection.md). This PR does not touch the ruleset.

What changes (four files, nothing else)

file	change
acceptance/at_r1_http.py	NEW. The harness. Standard library only. Not a pytest module: it sits outside tests/ and tests_runtime/, so testpaths never collects it and #1144's F9.1 is unchanged (FR-006's "no exclusion" holds).
.github/workflows/validate.yml	A new acceptance job, appended. It has no services, runs no pytest and installs nothing itself: one step, python3 acceptance/at_r1_http.py. The validate job and its triple are untouched.
tests_runtime/test_deploy_shape.py	Required, because test_the_workflow_declares_the_required_job_and_its_steps pinned sorted(jobs) == ["validate"]. It now admits ["acceptance", "validate"]. A new case holds acceptance to no service or container, no pytest run, no pip install step, and one harness step outside testpaths. And test_every_install_of_this_package_reads_one_dependency_lock now also requires that the harness passes the lock to pip.
tests/test_at_r1_http_harness.py	NEW, from Copilot's review at b440d12b. It tests the harness's DECISIONS in process, as tests/test_smoke_signals.py tests the browser half's oracle. It loads the harness from its file, against an in-process loopback server, so nothing is installed or started. 140 cases: the lexer; import specifiers against routes; a module-graph cycle; a dynamic refusal against a static import of the same path; the media types of served modules and stylesheets; modules and stylesheets from outside the plane; bare module specifiers; nineteen catalog shapes; and T104's delivery: the opener's location and privacy (a FIFO included, which is never read); its refresh as a browser follows it; its forward, which must open the console page on a host the plane answers on, with no encoded copy of the token outside the fragment; its token as the page accepts it; its record; the token absent from /capabilities; the stop's exit status; and the after-stop checks. 64 mutants of the harness's decisions are each killed by their case (below).

The two test changes add 141 cases to SELECTED and PASSED, and none skips. The floors permit a rise, and no floor is edited, as with every phase-2 landing since T037. CI's validate at f29b4ddd printed triple: selected=3764 passed=3753 skipped=11 failures=0 errors=0.

Overlap, checked before editing: gh pr diff --name-only on every open openDox-code PR (#60, #61, #62, #63, #64, #65, #67, #69, #71, #72, #73, #74). None touches .github/workflows/validate.yml, tests_runtime/test_deploy_shape.py or acceptance/. Re-checked at 2026-10-03T16:1xZ over every open PR: #76 (T082) and #82 (T100) now edit validate.yml, but only the validate job's triple pins (around line 257). This PR only appends a job after the last line of the file (@@ -299,3 +299,40 @@), so the two never touch the same lines. No open PR touches the other three files.

The documented command, and how the harness runs it

T007 batch H's 10.3 addendum (openspec/changes/add-neutral-product-standalone-operability/tasks.md, 10.3, "AMENDED — T007 Batch H (5850003126; Ruled R1Q15 (b), R1Q16 (iii))"), verbatim:

The command the root's README.md documents is the standalone install and its one start: pip install "opendox[local]", then opendox generate-and-open --local …. The flag selects the local mode explicitly (13.4 as this batch amends it), and the local extra carries the bundled server that mode starts (13.1 as this batch amends it). After the install, that start is the single command requirement 10's second scenario has a user run. The entry point is still the code leg's console script, and no Makefile target is added, for the reason above. Carried out by T070 and T076.

The harness holds both lines as constants (DOCUMENTED_INSTALL, DOCUMENTED_START, the … being U+2026 after one space). Compared mechanically with T076's README (opensoft/openDox#17 at 7eef03b4):

DOCUMENTED_INSTALL = 'pip install "opendox[local]"' (6f63616c5d22 tail bytes): README lines [32]
DOCUMENTED_START = 'opendox generate-and-open --local …' (616c20e280a6 tail bytes): README lines [33]

• The start line. The harness runs opendox generate-and-open --local --repo-root <repo> --repository fixture --no-open --port <free port>. That is quickstart.md § 3's filled form, with --port given a port found free at run time and checked free on 127.0.0.1 and ::1 just before the start. Before it starts anything, it asserts that its argv begins with exactly the tokens of DOCUMENTED_START before the … (start.documented-command). The … is the verb's own arguments, as the README says, and every flag above is one the README names. opendox is the fresh venv's console script, resolved on the child's PATH and asserted to lie inside that venv; argv[0] stays the literal opendox.
• The install line. No release of opendox is published (PyPI answers 404 for opendox; the release-channel question is with Brett). So the harness installs the same distribution with the same extra from the checkout: pip install "<checkout>[local]", from a copy of this checkout's tracked files. That is exactly the substitution the README makes for its first line (pip install "./code[local]", run from the root). It installs through constraints-cpython312-linux.txt where the lock's own interpreter runs it (CPython 3.12 on Linux, as in the job). The lock pins versions and adds no package, so the install is still opendox[local] and nothing else (AT-R1 step 2).

What the harness asserts, in order (AT-R1 steps 1-4, and the route answers behind 5-8)

Each assertion has an id. The run stops at the first that fails and prints AT-R1 HTTP half: FAIL [<id>]: <why>, then exits 1. --keep-going reports every failure instead, and still exits 1. A harness that breaks before a verdict exits 2, never 0.

1. Install. A fresh venv, then opendox[local] (R1Q16 (iii)). Then install declares the local extra, read from the installed distribution's metadata.

2. The clean machine, ASSERTED (clean.*), in a fresh OPENDOX_STATE_DIR created empty for the run:

   • none of openxdox, ideation_dashboard, doc_health and corpus_adapter_openxfactory is importable in the venv (python -I, from an empty directory);
   • omp is not on the PATH, nor is the product's own doxbench_bridge.HARNESS_COMMAND;
   • no identity broker (openprofiler-broker) is on the PATH, and no issuer setting is set;
   • nothing listens on 127.0.0.1:5432 or [::1]:5432;
   • no PostgreSQL Unix socket answers in a shared directory. The harness reads every listening .s.PGSQL.* socket the kernel lists in /proc/net/unix, wherever it lies, plus the distribution sockets as a fallback. One in a directory other users can traverse, as libpq's defaults (/tmp, /var/run/postgresql) are, must not answer. One in a private 0700 directory (another install's own) is noted;
   • no DSN or PG* setting reaches a child;
   • neither repository holds a binding at the product's own doxbench_binding.DEFAULT_BINDINGS_RELPATH;
   • no bundled-server process exists before the start.
     Every child runs with GIT_*, XF_*, OPENDOX_*, PG*, DATABASE_URL and PYTHONPATH dropped, a fresh HOME, and TMPDIR inside the scratch directory.

3. Two plain repositories, each a fresh git init (spec.md AT-R1 step 3): (a) tests/fixtures/plain-documents, and (b) quickstart.md § 2's three notes, byte for byte, with no front matter. Each gets git config user.name/user.email, which the served actor is read from.

4. The documented start, once per repository (start.*): the port is free, the argv matches, the console script lies in the venv, the server is ready within 120 s, and the process that answered is still the one it launched.

5. Fetches.

   • / must be text/html with an <html> element.
   • /snapshot.json must be a JSON object, non-empty, and neutral per F5.3: none of #1144's fourteen declared words (5.5's falsifier list, verbatim) in any string value.
   • The grouping station, named by /capabilities' own display facet (fields.grouping.field), must be filled, so a grouping tile can open the chat pane (R1Q13 (a) with (c); this fails, and does not skip).
   • /capabilities must give install.mode == "local", and must carry no console_token. A standalone plane hands its token to no loopback caller (T104, RULED openxFactory#656 5963851934, adversarial review 2's M5).

6. The console token, as the user's browser is handed it (T104). The start prints console <file URL>, the PATH of a private opener, and never the token. The harness reads that opener itself, with the standard library, and imports nothing from the product (opendox.console_access.read_private_copy is the product's own reader, and it is not used). The checks:

   • the start printed the opener (console opener printed);
   • it is <OPENDOX_STATE_DIR>/console/<port>.html, outside the served repository;
   • it is private: this user's regular file, mode exactly 0600, one link, in a directory no one else can enter. It is opened with O_NOFOLLOW | O_NONBLOCK and read only if fstat calls it a regular file, so a FIFO can never hang the run;
   • it has exactly one meta-refresh that a browser follows (the HTML standard's declarative refresh steps: a delay that does not start with a digit or . aborts it). It goes to this plane's console page (/ or /index.html), on a loopback host the launched plane answers on (served_loopback_hosts probes 127.0.0.1 and ::1), with no backslash, whitespace or user information. #console_token=<token> is in the FRAGMENT, and never in the query or the path, raw or in any percent-decoding;
   • that token is one the page accepts ([A-Za-z0-9_-]{16,512}, T104's takeDeliveredConsoleToken);
   • its JSON record (<script type="application/json" id="opendox-console">, kind opendox-console-access v1) describes that same forward: its port, its token, its opened_url, and its page_url.

   No failure message quotes the token.

7. The model catalog. /workbench/model-catalog must refuse a caller with no token (4xx). With the opener's token in X-XF-Console-Token, it must answer 200 in the envelope the chat rail adopts (views/doxbench-chat-model.js, adoptCatalog):

   • schema_version is any JSON number equal to 1 (so 1, 1.0 and 1e0), never true and never "1";
   • kind is workbench-model-catalog;
   • models is an array, with no entry whose available is true (16.4).

   The harness also asserts that the served bundle names both this route and this kind, so neither constant can drift from the bundle.

8. Every route the panes can request answers, and none answers 5xx or drops the connection (derivation below).

9. Stop and look. The harness sends SIGTERM to the entry point alone, as kill would, never to its process group, and waits up to 90 s. Then:

   • the entry point must exit 0 (stop exits 0), as tests_runtime/test_bundled_postgres.py requires of the same stop;
   • it scans /proc for any live process whose executable lies in the venv's pixeltable_pgserver package, or whose command line names the fresh state directory, and there must be none (R1Q16 (iv)). That is checked at the operating system, not by the product's report;
   • the opener must be gone (stop removes the console opener);
   • the token must appear nowhere in either output stream of the whole serve (console token never printed).

Cleanup runs however the run ends: it stops any server it started and kills any bundled-server process the scan finds, but only AFTER the verdict is taken, so a leftover still fails the run. Then it removes the scratch and state directories.

How the route list is derived (from the served JS, not by hand)

derive_bundle reads the bundle from the running server:

1. It fetches /, then follows the page's <script type="module"> and stylesheet links.
2. In every module, a small JS lexer strips comments and regular-expression literals and yields each string literal with the code before it. That code tells an import … from "x", an export … from "x" or an import "x" from an ordinary string.
3. It follows every static specifier, every literal dynamic import("x"), and every view-binding module /capabilities declares, transitively. Each module is fetched from the server under test once, and judged once per way it is imported. A static import must answer 200, even of a path some other module imports dynamically, because a failed one is a module-load pageerror, which AT-R1 step 8 forbids and no declaration can excuse. A dynamic import may be refused, but not with a 5xx. Standalone, /views/intent-feed.js answers 404 (10.2a: not owed), and views/intent-binding.js degrades. A module the server DOES serve, statically or dynamically imported, must be served as JavaScript ([bundle.module-type <path>]: a JavaScript MIME type essence, as tests_runtime/test_served_bundle.py's JAVASCRIPT_TYPES lists them). A linked stylesheet must be text/css ([bundle.sheet-type <path>]). Both comparisons ignore parameters such as charset, and case. A BARE module specifier (import "child.js"), which a browser with no import map refuses, is [bundle.bare <specifier>]. A module or stylesheet from OUTSIDE the plane (https://…, //host/…, data:) is [bundle.external <url>], and is never fetched from loopback by its path: a clean machine with only openDox installed cannot be assumed to reach it.
4. In every module of that graph, every string literal that is a same-origin path (/ or ./ followed by a letter, with no whitespace, not a .js/.css path) is a route the bundle can request. At the integration below that is 38 modules and 18 routes.

A static read cannot tell a load-time request from an on-click one. So the harness requests ALL of them, a superset of the wheel's, the lens's and the chat rail's load-time reads; T096's browser run observes the load-time set itself. The nine /actions/… routes get a GET too. A GET there finds no handler (each answers 404), so it never executes an action.

Two kinds of route take values the panes fill from the snapshot, and the harness fills them the same way:

• A prefix ending in / (/source/). The wheel, the viewer and the workbench's source loader complete it with a document path, so it is also requested once per document the snapshot lists, both plain and keyed by the workbench's key (/source/fixture%40main/<doc>).

• The thread read (/workbench/thread). It is also requested with the exact query the chat rail sends when it opens on a document (views/staging-workbench.js:2925, loadThread, called at views/doxbench-chat.js:1276-1281):

  • repository and ref come from the workbench's key, which with no snapshot index is the snapshot's repository at main (app.js, sourceKeyFor);
  • tile_kind is cluster (a grouping tile's kind, views/wheel-model.js: "clusters -> "cluster"");
  • tile_id is the first grouping tile, and document is its first member.

  The query-less form alone would stop at the 400 parameter check, before the reach that crashes.

Every request carries the console token the opener delivered, as the doxBench transports do, so a guarded read answers from its handler and not from the console check.

Falsifier: the harness itself

At this branch, main 90ac7033 plus the harness (what this PR's own acceptance job runs): FAIL, named

== r32-r8-on-pr-tree rc=1 held=32
AT-R1 HTTP half: FAIL [a.capabilities carries no console token]: /capabilities publishes `console_token` to any loopback caller; a standalone plane delivers it only through the 0600 opener file (T104, adversarial review 2's M5)
      1 failed, 32 held

The expected red moved as the stack landed:

• at main 047bb4fa and 66ff7257, it was [install declares the local extra] (r4, r12);
• once T072, 13.1: the bundled PostgreSQL server, the local install's own child (plan 034) #69 landed (main 8e377823), it was [a.capabilities install.mode == local]. This PR's job printed that at f29b4ddd (run 37133775447, job 111233985686);
• with T073, 13.4a — /capabilities gains an install block, read from the serving process's own settings (plan 034) #72 landed, it is the token delivery above, which only T104 supplies.

Against a LOCAL integration of the stack (never pushed): PASS with T104, and without it, FAIL where T104 is missing

Both integrations live in this writer's own clone, with no upstream. The live heads were read at 2026-10-03T21:xxZ, after #77 (T084) and #80 (T103) landed:

tree	what it is
b0a8ec88, the integration WITHOUT T104	main e49b17c3 + #80 b9025b6c, #80's landed head. Its tree is exactly main 390e2c28's (git diff is empty)
d05c266e, the integration WITH T104	b0a8ec88 + #84 c979747a (git merge --no-ff, clean)

#84 at c979747a conflicts with main 390e2c28 itself in 14 files, as a history effect of #80's squash landing: the same content merges clean through #80's landed head. That main merge is #84's writer's.

The harness at 27479495, and then at this PR's head 33841d4a, whose change since only tightens the bundle walk and the opener's read:

== r40-2747-on-live8-t104-failfast rc=0 held=302
AT-R1 HTTP half: PASS (302 assertions held)
== r41-2747-on-live8-t104-keepgoing rc=0 held=302
AT-R1 HTTP half: PASS (302 assertions held)
== r42-2747-on-live8-keepgoing rc=1 held=276
== r43-r13-on-live8-t104-failfast rc=0 held=302
AT-R1 HTTP half: PASS (302 assertions held)
== r44-r13-on-live8-t104-keepgoing rc=0 held=302
AT-R1 HTTP half: PASS (302 assertions held)
== r45-r13-on-main390e-keepgoing rc=1 held=276
AT-R1 HTTP half: FAIL [a.capabilities carries no console token]: /capabilities publishes `console_token` to any loopback caller; a standalone plane delivers it only through the 0600 opener file (T104, adversarial review 2's M5)
      also FAIL [a.console opener printed]: the start printed no `console <file URL>` line naming the opener, so a user has no way to open the console page
      also FAIL [a.catalog answers]: /workbench/model-catalog with no console token to present (step 6 found none) answers HTTP 403: ...console_required...
      also FAIL [b.capabilities carries no console token]: ...
      also FAIL [b.console opener printed]: ...
      also FAIL [b.catalog answers]: ...
      6 failed, 276 held

r42 printed the same six failures as r45. r43 to r45 ran the working tree that 64dc06f5 committed; cmp is identical, and the merge of main after it changed no harness file. The same verdicts held at every earlier integration:

• 16d1053b, with DRAFT (phase 3, after T063): T104, the console token travels in the opened URL, not /capabilities (plan 034) #84 cb899546 (r34 to r39);
• a945ef01, with DRAFT (phase 3, after T063): T104, the console token travels in the opened URL, not /capabilities (plan 034) #84 6db50b03 (r29 to r31).

The pushed harness from before the token change (4dcb4221) stops at the integration with T104's first local commit, [a.capabilities console_token] (r16), which is the reason for this change.

Verdict at the integration with T104: AT-R1's HTTP half passes, with 302 assertions held in both passes. That covers:

• the install, the clean machine and both repositories;
• the documented start: ready, with the process the harness launched;
• / as HTML;
• the neutral, non-empty snapshot with a grouping tile: repository (a) has 8 documents and 2 clusters; repository (b), with no front matter, has 3 documents and 2 clusters;
• install.mode == local, and no console_token on /capabilities;
• the opener: printed, at <OPENDOX_STATE_DIR>/console/<port>.html, private, forwarding with the token in its fragment, and with a record that agrees;
• the catalog: it refuses a caller with no token, and with the token answers in the envelope the chat rail adopts, with no available entry;
• 38 modules, none bare and none from outside the plane, every one served as JavaScript and every static import 200, /views/intent-feed.js refused as 10.2a's not-owed dynamic import, and /styles.css served as text/css;
• all 18 derived routes and every parameterized form below 500;
• the stop: exit status 0 within the bound, no bundled PostgreSQL process left, the opener removed, and the token in neither output stream.

Pass (a)'s route answers at d05c266e (r44). Every answer is the same as at 16d1053b, a945ef01, 365e4e9b and 887e72f5 before it, by a diff of the runs' GET lines:

/actions/{dtn-seed,edit,notebook,refresh,staging-seed}            HTTP 404
/actions/workbench/{chat-turn,document-abstract,model-approval,model-intake}  HTTP 404
/capabilities HTTP 200         /logout HTTP 404           /snapshot-index.json HTTP 404
/snapshot.json HTTP 200        /source/ HTTP 404          /source/<each of 8 documents> HTTP 200
/source/fixture%40main/<each of 8 documents> HTTP 200
/workbench/model-catalog HTTP 200    /workbench/model-intake HTTP 200    /workbench/thread HTTP 400
/project-register.json HTTP 404
/workbench/thread?repository=fixture&ref=main&tile_kind=cluster&tile_id=grouping-compost-corner&document=grouping-compost-corner.md HTTP 403

Before T084: two product gaps, both T084's, both removed by #77

The same harness against the integration without #77 (e7187f06: main + #69 f66e5f82, #72 1b0c3a63, #73 71d24af6, #71 83213eb2, #74 9061b22a, #65 c0a97648) held 198 and failed 4. The 4 were these two gaps, each hit in both repositories:

== r6-integ-keepgoing rc=1 held=198
AT-R1 HTTP half: FAIL [a.route /project-register.json]: GET /project-register.json answers no answer (RemoteDisconnected: ...)
      also FAIL [a.route /workbench/thread?repository=fixture&ref=main&tile_kind=cluster&tile_id=grouping-compost-corner&document=grouping-compost-corner.md]: ... no answer (RemoteDisconnected: ...)
      also FAIL [b.route /project-register.json]: ... no answer (RemoteDisconnected: ...)
      also FAIL [b.route /workbench/thread?repository=fixture&ref=main&tile_kind=cluster&tile_id=budget-roadmap&document=budget.md]: ... no answer (RemoteDisconnected: ...)
      4 failed, 198 held

1. GET /project-register.json dropped the connection. src/opendox/serve_project.py:271 (at main 047bb4fa) did from openxdox.gate_console import DEFAULT_RECORDS_DIR (and :272, from openxdox.kickoff import …), so it raised ModuleNotFoundError: No module named 'openxdox'. The page requests this route on every load (app.js:1004 → views/repo-selector.js:138-139). It is batch L's named crash site (5920216845).
   Removed by T084, 4.3: the last deferred reaches through declared seams; consumer_reach retired (plan 034) #77. The handler now reads column_seams.gate and column_seams.kickoff. openDox's default discovers no register, so the route answers the existing structured 404 "no project register", and the picker hides.
2. The chat rail's thread read dropped the connection. src/opendox/serve_workbench.py:560 at the pre-T084 integration (:548 at main) did from openxdox import doxbench_scope, which is reached once the five query fields are present. The rail requests it when it opens on a document (views/staging-workbench.js:2925). It was not among batch L's three named crash sites; the holder relayed it to T084's writer.
   Removed by T084, 4.3: the last deferred reaches through declared seams; consumer_reach retired (plan 034) #77. The handler now uses openDox's own scope type. With no live session on that scope, it answers 403 with the no-live-session absence body.

No from openxdox import is left in either file at d05c266e, now that #77 has landed on main, and the runs with #77 found no new gap.

The assertions bite: eleven product mutants, four workflow mutants and sixty-four decision mutants, all killed

Product mutants, each run through the full harness: m1, m2, m4 and m5 at b4fc637f, and m3 again at b440d12b. The only harness change since b4fc637f is main()'s handling of an error while preparing. m1 and m2 were merged from main when #69 was at fedfa75d and #72 at 20032d02. m3 to m5 are working-tree edits of the integration as it was then, 8e4203d8 (before T084):

mutant	tree	killed at
m1, no T081	integration without #74 (25f1f6af)	[a.catalog offers no available entry]: "no model is configured, yet the catalog offers ['omp-local']"
m2, no T073	integration without #72 (f3957515)	[a.capabilities install.mode == local]: "the served install block is None"
m3, the server is never stopped	bundle.BundledServer.stop() returns at once, and no parent-death signal	[a.stop leaves no bundled PostgreSQL process]: "still running after the entry point stopped: pid 599656: …/pixeltable_pgserver/pginstall/bin/postgres -D …" (and the harness's cleanup then removed it)
m4, a governance word in the fixture	title: A slow leak at the rain barrel, ratified	[a.snapshot neutral (F5.3)]: "openxFactory's vocabulary leaked into the neutral snapshot: ['ratified']"
m5, a missing module	src/opendox/web/views/lens-model.js deleted	[a.bundle.module /views/lens-model.js]: "imported statically by /app.js, answers HTTP 404"

T104's delivery, each a working-tree edit of the integration WITH #84, a945ef01, run through the full harness at d53a7378 (r33):

mutant	edit	killed at
m6, a readable opener	console_access.PRIVATE_MODE = 0o644	[a.console opener is private]: "… has mode 644, not 600"
m7, the token in the query	opened_url joins with ? instead of #	[a.console opener forwards with the token in its fragment]: "the opener's forward carries the token in its QUERY …"
m8, the opener outlives the server	remove_private_copy returns at once	[a.stop removes the console opener]: "… is still there after the server stopped …"
m9, the token back on /capabilities	build_server publishes it on every plane	[a.capabilities carries no console token]
m10, the token printed	generate-and-open prints token <token>	[a.console token never printed]
m11, an unguarded catalog	the catalog's console check removed	[a.catalog refuses a caller without the console token]: "… answers HTTP 200 …"

The harness's own decisions, each mutated in acceptance/at_r1_http.py and run against tests/test_at_r1_http_harness.py, every one killed:

• at d53a7378 (evidence/decision_mutants_d53a7378.py in this writer's work directory), 25 of 25: each of T104's checks (12), the media types (5), the opener's record (6), and the catalog's number (2);
• at 5636eb8d, 6 more: the browser-divergence check, the user-information check, the guarded split of the forward, the unquoted message, the guarded split of the printed location, and the record's redaction;
• at 486e426e, 7 more: the refresh delay, the optional url keyword, the quote truncation, and the token shape (no check, no upper bound, search for fullmatch, and a lower bound of 1);
• at 142d1352, 3 more: no console-page check, an empty path refused, and / not a console page;
• at 27479495, 8 more: the origin discarded, the external module and stylesheet checks each dropped, the served-host check, localhost never served, no decoding, one decoding round, and any stop status;
• at 64dc06f5, 5 more: a bare specifier resolved, a bare one not judged, any /-containing specifier read as relative, a blocking open of the opener, and no regular-file check (killed by a FIFO that a gone writer filled with a page). Five earlier mutants (static-after-dynamic, the catalog's shapes and its envelope) were killed at f0e0ffe1 and 4dcb4221. One proposed mutant, admitting a string schema_version, is equivalent, because no string equals 1 in Python.

Workflow mutants, against the three affected cases of tests_runtime/test_deploy_shape.py:

mutant	killed by
acceptance gains a postgres service	test_the_acceptance_job_runs_the_harness_on_a_clean_machine
the harness drops -c <lock>	test_every_install_of_this_package_reads_one_dependency_lock
acceptance chains && python -m pytest -q	test_the_acceptance_job_runs_the_harness_on_a_clean_machine
acceptance gains its own pip install . step	both cases

Restored: 3 passed. Locally, tests_runtime/test_deploy_shape.py and tests/test_triple_pin.py give 115 passed.

How the harness is run, and where the bundled server's state lives

The harness takes no path and no port (only --keep and --keep-going; see the SonarCloud round below). It installs the checkout its own file is in. Its scratch space and its OPENDOX_STATE_DIR are fresh tempfile directories, so TMPDIR chooses where they go. To measure the integration and each mutant, this writer copied the harness, untracked, into that tree's acceptance/ and ran it there.

• In CI, in the runner's temporary directory (/tmp/odx-XXXXXXXX), which is sticky.
• The socket path is capped. The bundled server's socket is <OPENDOX_STATE_DIR>/postgres/run/.s.PGSQL.5432, and Linux takes at most 107 bytes (runtime/config.py, UNIX_SOCKET_PATH_MAX). So the harness's state directory is a short odx-XXXXXXXX directly under TMPDIR. A run whose socket could not fit is refused with exit 2, naming TMPDIR, before anything is installed.
• The local runs above used TMPDIR=~/.local/state/opendox-t095. This writer's work directory resolves through a world-writable, non-sticky mount, and the product rightly refuses a state directory below it: "… is writable by every user and is not sticky (mode 777) …". That directory was empty after every run, and no bundled PostgreSQL started by these runs was left running.

Review rounds

• SonarCloud (advisory; the gate failed at 1c064bb3 on Security Rating D, and passes at every head since bbdeb9ec). Fixed in bbdeb9ec:
  • pythonsecurity:S8703, S8705, S8707: the --port, --scratch, --state-base and --checkout options flowed into a socket, the server's argv and the filesystem. They are gone.
  • python:S5443: the /tmp/.s.PGSQL.5432 probe is replaced by the distribution sockets.
  • python:S3776: the lexer is a class, and the long functions are split one per step.
  • python:S9073: the acceptance job's two assertions are split.
• Copilot, fourteen rounds. Every finding was real and was fixed with evidence: each fixed head reports a named FAIL, and the reviewed head reproduces the defect. Every thread is resolved.

  • At 1c064bb3, fixed in 32ef3e8c:

    • r4170450448: a module refused as a dynamic import hid a later static import of the same path.
    • r4170450491: a malformed 200 catalog raised a harness error instead of a named failure.

  • At bbdeb9ec: r4170537382, the same static-after-dynamic case. Already covered by 32ef3e8c, and answered there.

  • At 32ef3e8c, fixed in b4fc637f:

    • r4170537350: a server on /tmp's socket alone, with TCP off, passed the fixed socket list.
    • r4170567257: a non-list documents value passed as "non-empty".
    • A "previously missed" item: a grouping value with no tile holding an id and a member document passed, and silently dropped the rail's thread read.

  • At b4fc637f, "Needs a closer look" with no new finding. It noted that the PR needs integrated verification with the dependent product changes: that is the integration above, now including T084. Its "previously missed" item, fixed in b440d12b: an OSError in prepare() escaped main() with exit 1. This head returns 2; at b4fc637f, an ENOSPC from tempfile.mkdtemp escaped.

  • At b440d12b, "Needs a closer look" with no findings. Its "previously missed" item, fixed in f0e0ffe1: the module-graph verdict had no collected regression test, and on this branch the acceptance job stops before derive_bundle. The new tests/test_at_r1_http_harness.py above answers it.

  • At f0e0ffe1, "Needs a closer look" with no findings. Its "previously missed" item, fixed in 4dcb4221: a 200 catalog of {"models": []} passed, though adoptCatalog adopts only schema_version === 1 and kind === "workbench-model-catalog", and shows any other catalog as unreadable. The envelope is now a named check, and the served bundle must name the kind. Seven refused envelopes are tested, and relaxing the int check fails the true case.

  • At 4dcb4221, "Needs a closer look" with no findings.

  • At 1c0ff975, fixed in f29b4ddd: r4173473346, the envelope check refused "schema_version": 1.0 and 1e0, which JavaScript's === 1 adopts. It now admits any JSON number equal to 1, and never true or "1".

  • At f29b4ddd ("Changes recommended"), fixed in de8b2274:

    • r4173769822: a module served 200 as text/plain or text/html passed;
    • r4173769844: so did a stylesheet.

    Both now require their type.

  • At d53a7378 ("Changes recommended"), fixed in 5636eb8d:

    • r4173842763: a forward holding a backslash or user information passed, though a browser opens another host;
    • r4173842794: a refused destination's message quoted a URL that could hold the token;
    • r4173842805 and r4173842811: an unparseable printed location or refresh URL raised a harness error instead of a named failure.

  • At 5636eb8d ("Changes recommended"), fixed in 486e426e:

    • r4173894317: a refresh whose delay a browser aborts (invalid;url=, -1;url=) still yielded a token;
    • r4173894352: a token that takeDeliveredConsoleToken discards (short) passed.

  • At 486e426e, "Needs a closer look" with no findings. Its "previously missed" item, fixed in 142d1352: with an agreeing record, a forward to /missing.html or /snapshot.json passed. The forward must now open / or /index.html.

  • At 142d1352 ("Changes recommended"), fixed in 27479495:

    • r4174355680: a percent-encoded copy of the token in the query passed;
    • previously missed: a forward to [::1] passed, though the plane listens on 127.0.0.1 alone;
    • previously missed: an import from https://… was fetched as its local path and passed;
    • previously missed: any stop exit status passed.

  • At 27479495 ("Changes recommended"), fixed in 64dc06f5:

    • r4174411680: a bare specifier (import "child.js") passed when /child.js was served;
    • previously missed: a FIFO opener hung the harness under --keep-going.

Not done here

• No ruleset change: making acceptance required is the owner's.
• No fix to any other writer's PR. The two gaps above are reported.
• No README edit: the openDox root's README is T076's (openDox#17).

🤖 Generated with Claude Code

Summary by Sourcery

Add an isolated AT-R1 HTTP acceptance check that validates standalone openDox operation and secure console access in CI.

New Features:

• Add an AT-R1 HTTP acceptance harness that installs openDox in an isolated environment, exercises standalone operation on clean plain repositories, validates served routes and console-token delivery, and verifies clean shutdown.
• Add a dedicated CI acceptance job that runs the harness without database services or pytest.

Enhancements:

• Expand deployment-shape checks to enforce the acceptance job’s isolation, single harness command, test-path exclusion, and dependency-lock usage.
• Add in-process tests covering the harness’s bundle traversal, route validation, catalog checks, console-token security, and shutdown decisions.

CI:

• Run the standalone HTTP acceptance checks in their own 20-minute GitHub Actions job alongside the existing validation suite.

Tests:

• Add comprehensive unit coverage for acceptance-harness decisions and malformed or insecure server responses.

[sourcery-ai]

Reviewer's Guide

Introduces a dedicated, intentionally database-free CI acceptance job backed by a comprehensive standard-library AT-R1 HTTP harness, while extending workflow-shape tests to enforce its isolation, execution contract, and dependency-lock usage; the existing validate suite remains unchanged.

Sequence diagram for the AT-R1 HTTP acceptance harness

sequenceDiagram
    participant CI as acceptance job
    participant H as at_r1_http.py
    participant V as Fresh venv
    participant O as opendox
    participant R as Plain Git repository
    participant S as HTTP server

    CI->>H: Run python3 acceptance/at_r1_http.py
    H->>V: Create venv and install checkout[local] with lock
    H->>H: Assert clean machine and no database service
    H->>R: Create fresh repository and commit documents
    H->>O: Start opendox generate-and-open --local
    O-->>S: Serve repository
    H->>S: Fetch /, /snapshot.json, /capabilities
    H->>S: Fetch model catalog and derived bundle routes
    H->>O: Send SIGTERM
    H->>H: Assert no bundled PostgreSQL process remains
    alt Assertion fails
        H-->>CI: Exit 1 with named failure
    else All assertions hold
        H-->>CI: Exit 0
    end

Loading

Flow diagram for AT-R1 harness assertions

flowchart TD
    START["Start harness"] --> INSTALL["Install opendox[local] in fresh venv"]
    INSTALL --> CLEAN["Assert clean machine: no sibling tools, broker, DB, or bindings"]
    CLEAN --> REPOS["Create two plain Git repositories"]
    REPOS --> STARTAPP["Run documented local start"]
    STARTAPP --> CORE["Check HTML, neutral snapshot, grouping station, and local mode"]
    CORE --> CATALOG["Check model catalog has no available model"]
    CATALOG --> DERIVE["Derive module graph and request bundle routes"]
    DERIVE --> STOP["SIGTERM entry point and scan for leftover bundled PostgreSQL"]
    STOP --> RESULT{Assertions pass?}
    RESULT -->|Yes| PASS["PASS"]
    RESULT -->|No| FAIL["FAIL with assertion id"]

Loading

File-Level Changes

Change	Details	Files
Add a standalone AT-R1 HTTP acceptance harness that installs and exercises openDox on a clean Linux environment.	Build a tracked checkout into a fresh virtual environment and install the local extra through the CPython 3.12 dependency lock. Assert isolation from sibling packages, external harnesses, identity services, database services, inherited environment settings, and model bindings. Create two plain Git repositories and run the documented local server command against each. Validate HTML, snapshot neutrality and grouping data, local install capabilities, no-model catalog behavior, derived frontend module and route availability, and clean shutdown without bundled PostgreSQL leftovers. Provide fail-fast or keep-going diagnostics, Linux/process checks, cleanup, and explicit exit codes.	acceptance/at_r1_http.py
Run the HTTP acceptance harness in a dedicated CI job isolated from the database-backed validation job.	Add an Ubuntu Python 3.12 acceptance job with checkout and setup steps. Run only the standard-library harness command, with no services, container, pytest invocation, or job-level package installation. Leave the existing validate job and its required-check behavior unchanged.	.github/workflows/validate.yml
Pin the new workflow shape and dependency-lock usage in deployment-shape tests.	Allow exactly validate and acceptance workflow jobs. Verify acceptance has no database service or container, does not run pytest or pip install, and invokes the harness once outside pytest testpaths. Verify the harness installation references and passes the CPython 3.12 Linux constraints file.	tests_runtime/test_deploy_shape.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Copilot]

Copilot review overview

🟡 Changes recommended

The harness can miss broken static imports and misclassify malformed catalog responses as internal errors.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Cache 404s without marking modules seen for static imports · New
• Validate catalog JSON shape before accessing models · New

What changed in this PR

Adds the HTTP half of standalone openDox acceptance testing, separate from the existing validation suite. Acceptance is intentionally expected to fail until dependent features land.

Changes:

• Adds a clean-install harness covering HTTP responses and shutdown.
• Runs acceptance in a separate CI job without database services.
• Extends workflow-shape tests to enforce isolation and dependency-lock usage.

File	Description
tests_runtime/​test_deploy_shape.py	Enforces acceptance-job configuration and lock usage.
acceptance/​at_r1_http.py	Implements standalone HTTP acceptance checks.
.github/​workflows/​validate.yml	Adds the isolated acceptance job.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

The harness can miss broken static imports and an existing PostgreSQL socket under /tmp.

Review effort: Balanced
Findings: 1 · 3

Open (4)

• Cache 404s without marking modules seen for static imports
• Missing PostgreSQL Unix socket in clean-machine check · New
• Dynamic import cache bypasses static dependency HTTP check · New
• Validate catalog JSON shape before accessing models

[Copilot]

Copilot review overview

🟡 Changes recommended

Snapshot checks can accept unusable document or grouping values and silently skip required HTTP requests.

Review effort: Balanced
Findings: 2

Open (2)

• Accepts non-list documents value · New
• Missing PostgreSQL Unix socket in clean-machine check

Resolved since last review (3)

• Cache 404s without marking modules seen for static imports
• Dynamic import cache bypasses static dependency HTTP check
• Validate catalog JSON shape before accessing models

Previously missed (1)

In code that hasn't changed since last review

Accepts invalid grouping without required document

acceptance/​at_r1_http.py:1038

This truthiness check accepts both a non-list grouping value and a list such as [{"id":"topic","document_edges":[]}]. In either case, thread_query() returns None, so requests_for() silently omits the parameterized thread read. The query-less request stops at parameter validation and cannot expose the handler failure this harness is intended to catch. Require a grouping tile with an id and a member document before accepting this check.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The draft needs integrated verification with dependent product changes, and preparation-error handling remains unresolved.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Accepts non-list documents value
• Missing PostgreSQL Unix socket in clean-machine check

Previously missed (1)

In code that hasn't changed since last review

Handle preparation errors with documented ERROR status 2

acceptance/​at_r1_http.py:1283

Filesystem errors from prepare() bypass this handler. For example, tempfile.mkdtemp() raising OSError(ENOSPC) escapes main() and exits with status 1, instead of the documented harness ERROR and status 2. This makes an infrastructure failure look like a product acceptance failure. Catch unexpected preparation exceptions and report status 2, as the later execution block does.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The substantial harness lacks automated graph-verdict regression coverage and a passing end-to-end result against the complete feature stack.

Review effort: Balanced
Findings: None

Previously missed (1)

In code that hasn't changed since last review

Add behavioral regression tests for module-graph verdict

acceptance/​at_r1_http.py:661

The module-graph verdict has no automated behavioral regression tests. The new deployment tests inspect configuration and source text, while this branch's acceptance run stops at the missing local extra before reaching derive_bundle. Add collected, in-process tests for traversal cycles, route extraction, and the already-fixed case where a dynamic 404 precedes a static import of the same URL. Mocking get would exercise these decisions without installing or starting the product, while keeping the harness itself outside pytest collection. tests/test_smoke_signals.py provides a similar pattern for testing acceptance decision logic.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The catalog check accepts envelopes the chat rail rejects, allowing a false acceptance result.

Review effort: Balanced
Findings: None

Previously missed (1)

In code that hasn't changed since last review

HTTP check accepts catalogs with invalid envelope metadata

acceptance/​at_r1_http.py:1106

An HTTP 200 response containing {"models": []} passes every catalog check, even if kind and schema_version are missing or incorrect. However, adoptCatalog requires schema_version === 1 and kind === "workbench-model-catalog" (src/opendox/web/views/doxbench-chat-model.js:228–235); the chat rail treats a rejected envelope as unreadable. This lets the HTTP acceptance check pass a catalog the UI cannot use. Require both envelope fields in this named check, update the successful catalog fixtures to use valid envelopes, and add missing/wrong kind and version cases.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot review overview

🟡 Changes recommended

Console-opener validation can pass delivery that the browser rejects.

Review effort: Balanced
Findings: 2

Open (2)

• Validate refresh delay before accepting destination · New
• Match browser validation for console tokens · New

Resolved since last review (4)

• Prevent rejected destination URLs from leaking console tokens
• Reject backslashes and userinfo in destination URLs
• Handle malformed refresh URLs as named delivery failures
• Handle malformed console opener URLs without harness errors

[Copilot]

Copilot review overview

🔵 Needs a closer look

The harness accepts non-console opener destinations, allowing a false acceptance result.

Review effort: Balanced
Findings: None

Resolved since last review (6)

• Match browser validation for console tokens
• Validate refresh delay before accepting destination
• Prevent rejected destination URLs from leaking console tokens
• Reject backslashes and userinfo in destination URLs
• Handle malformed refresh URLs as named delivery failures
• Handle malformed console opener URLs without harness errors

Previously missed (1)

In code that hasn't changed since last review

Destination validation accepts non-console paths

acceptance/​at_r1_http.py:1429

The destination check validates the authority but not the page path. With a matching JSON record, both /missing.html#console_token=… and /snapshot.json#console_token=… pass every opener assertion. Later checks request / and the catalog independently, so acceptance can pass while the user's browser opens a missing page or JSON instead of the console. Require / or /index.html, and add regression cases where both the forward and record name a non-console path.

[Copilot]

Copilot review overview

🟡 Changes recommended

The harness can falsely accept broken console delivery, external dependencies, unsuccessful shutdowns, and encoded token leaks.

Review effort: Balanced
Findings: 1

Open (1)

• Detect percent-encoded console tokens in forwarded URLs · New

Previously missed (3)

In code that hasn't changed since last review

Reject IPv6 opener targets when launch binds only to IPv4

acceptance/​at_r1_http.py:220

launch() uses the default IPv4-only bind (127.0.0.1), but this allows an opener targeting [::1]:<port>. With an agreeing record, that opener passes delivery validation even though it cannot reach the launched server. Later catalog and route probes use IPv4 directly, so they do not catch the broken destination. Restrict opener hosts to those supported by this launch and add an IPv6-forward regression case.

Preserve origins and reject unsupported external dependencies

acceptance/​at_r1_http.py:677

Discarding the origin makes external dependencies look local. For example, a static import of https://unreachable.invalid/app.js resolves here to /app.js. The walker can reuse the successful local response and pass, although the browser cannot load the external module. Script roots and stylesheets use the same resolver. Preserve the origin during resolution and report a named acceptance failure for unsupported external dependencies rather than fetching their paths from loopback. Add regression cases for external imports and page links.

Require zero shutdown status for a passing lifecycle test

acceptance/​at_r1_http.py:1641

Any exit status passes this check, including 1 or -SIGTERM. If shutdown fails after removing the opener and stopping PostgreSQL, the harness can still report PASS. The existing lifecycle test requires status zero (tests_runtime/test_bundled_postgres.py:440). Require rc == 0 here and add a decision test for a nonzero shutdown status.

[Copilot]

Copilot review overview

🟡 Changes recommended

The harness can accept browser-invalid imports and hang while reading a rejected FIFO opener.

Review effort: Balanced
Findings: 1

Open (1)

• Reject bare static import specifiers · New

Resolved since last review (1)

• Detect percent-encoded console tokens in forwarded URLs

Previously missed (1)

In code that hasn't changed since last review

Prevent FIFO hangs during file opening

acceptance/​at_r1_http.py:1407

With --keep-going, a FIFO opener fails the privacy check but is still passed to this blocking os.open. If it has no writer, the harness hangs instead of reporting its verdict or reaching cleanup. A bounded probe confirms the hang after the non-regular-file rejection. Open nonblocking and check that the opened descriptor is a regular file before reading; add a FIFO regression case.

[Copilot]

Copilot review overview

🟡 Changes recommended

Harness diagnostics can expose console tokens, and malformed snapshot entries can bypass document-specific acceptance checks.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Avoid echoing raw child output in diagnostics · New
• Reject malformed documents instead of skipping source requests · New

Resolved since last review (1)

• Reject bare static import specifiers

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Copilot review overview

🟡 Changes recommended

Verified false-positive acceptance checks remain in console-opener navigation and directory privacy validation.

Review effort: Balanced
Findings: 2

Open (2)

• Accepts inactive refresh elements inside template and noscript · New
• Fails to validate state directory and ancestor permissions · New

Resolved since last review (2)

• Avoid echoing raw child output in diagnostics
• Reject malformed documents instead of skipping source requests

[Copilot]

Copilot review overview

🟡 Changes recommended

Verified token exposure in diagnostics and unhandled JSON nesting errors remain unresolved.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Nested console tokens are exposed in diagnostic output · New
• Recursion errors bypass malformed-response handling · New

Resolved since last review (2)

• Fails to validate state directory and ancestor permissions
• Accepts inactive refresh elements inside template and noscript