odysseus/docs/frontend-architecture/notes-validation.md

Notes implementation validation and checkpoint receipts

Implementation baseline: 1cc56cb9d78f3e2399d1d61155b71d771a17b85b, updated via non-destructive fast-forward to latest official upstream/dev at 86b886c611338282af6d4a717246ea4e256f58df (incorporating PRs #6704 and #6693). Independent AGY audit returned CONDITIONAL PASS. Pre-publication corrective pass verified issue template, PR template, visual evidence paths, and em-dash removal. The official integration branch is dev. Tracking issue #6712; PR #6713.

Final executed evidence

Check	Result
Notes Python tests, discovered by filename, plus F1 publication/graph/offline/loader tests	172 passed, one release-smoke skip without APP_PORT
Node architecture, Notes oracle, domain, infrastructure, application, reminders, drafts, selection and workflow tests	46 passed
Native Python lifespan/static distribution probe	Passed for every mapped output, with source/Node absent
Existing Docker image distribution probe	Passed with networking disabled and candidate files mounted read-only
Real authenticated native app, desktop and touch-mobile	Passed CRUD persistence, owner identity, actual Chat selected-context indicator/reset and the original release smoke scenario
Real Chromium first evaluation of Notes offline	Passed; every maintained output cached, facade/canonical API identity shared
Source/output parity and F1 boundaries	Passed, 43 maintained modules and nine composition-only legacy exceptions
Foundation-based full pytest execution	13 failed, 13,909 passed, 60 skipped, six subtests passed, 192 warnings, 517.04 seconds
Targeted unchanged F1 baseline reproduction	Same 13 failures, 77 passed, six warnings
Targeted untouched latest dev reproduction	Three inherited failures, 87 passed, six warnings
Final indexed latest dev plus Notes overlay, full pytest	Three same-environment baseline failures, 13,923 passed, 60 skipped, six subtests passed, 192 warnings, 512.09 seconds
Untouched latest dev readiness checks, without the prewarm override	Five passed

The foundation-based full repository result is not green. Its failures reproduce against the unchanged foundation in a disposable archive, with the same interpreter and closed Chroma port. None was disabled, relabeled or fixed in this Notes change. The focused Notes suite and required source/deployment gates are green. The final code/test overlay is fingerprinted in implementation.sha256. The only post-full-suite test-source edit removes a terminal blank line from the browser wrapper; its content was compared ignoring terminal whitespace and all three focused contract/browser checks passed again. Raw command outputs are kept out of the repository; the counts above are the record.

The first full run reported 19 failures. Six were introduced validation issues: the SW cache name did not follow the existing numeric convention; a temporary probe environment input was not registered by the configuration-reference checker; and a Notes source assertion still expected the original default object spelling. The cache name now follows the convention, the probe passes its output list as a command argument, and the assertion verifies the new public binding. All 58 tests in those affected files passed after correction. The foundation-based full run has only the 13 reproduced baseline failures below.

Reproduced baseline failures

• tests/test_aux_llm_owner_scope.py::test_auto_compaction_utility_endpoint_keeps_chat_owner
• tests/test_chatgpt_reasoning_and_grouping.py::test_history_and_chat_routes_support_reasoning_effort
• tests/test_containment_enforcement.py::test_namespace_handshake_closes_model_stdin
• tests/test_containment_enforcement.py::test_execution_environment_cannot_replace_probed_bwrap[False]
• tests/test_context_compactor.py::TestMaybeCompactFourthMessage::test_does_not_crash_on_none_content_turn
• tests/test_context_compactor.py::TestMaybeCompactFourthMessage::test_handles_multimodal_list_content
• tests/test_css_computed_style_snapshot.py::test_computed_styles_match_the_committed_baseline
• tests/test_history_compact_tool_calls.py::test_manual_compact_tolerates_chatmessage_with_none_content
• tests/test_history_compact_tool_calls.py::test_manual_compact_tolerates_dict_message_with_none_content
• tests/test_history_compact_tool_calls.py::test_registered_manual_compact_route_tolerates_none_content
• tests/test_history_compact_tool_calls.py::test_registered_manual_compact_route_uses_session_owner
• tests/test_model_helper_owner_scope.py::test_history_compact_resolves_with_owner_scope
• tests/test_readiness.py::test_tool_index_is_reported_but_not_critical_by_default

These cover existing compaction fixtures/source assertions, namespace containment, settings-row CSS baseline drift and readiness expectations. The baseline reproduction used git archive into /tmp/odysseus-notes-baseline-OitxsU, not another branch/worktree.

Reproducible commands

Latest integration target

Final upstream inspection found 86b886c611338282af6d4a717246ea4e256f58df. PR #6704 repairs ten of the foundation's reproduced failures; PR #6693 adds remote-only skill gating. Neither changes a file owned by the Notes diff. The branch remains on the requested foundation, with no merge or rebase. An archive of that latest target plus the exact final Notes code/test overlay is validated in /tmp/odysseus-notes-latest-VmZrgC using the same full-suite command. The fixture has a local Git index, initialized from the latest target and updated with the review files, but no commit. This enables the tracked-publication checks. The first archive-only attempt had one Git-metadata failure and seven checkout-only skips. Both affected files subsequently passed all 19 tests with metadata present; the complete suite was then rerun in that indexed fixture. An untouched archive at /tmp/odysseus-notes-latest-baseline-mfE4ss reproduced the remaining two containment failures and the readiness failure: three failed, 87 passed.

These are reproduced local-environment failures, not a claim that official CI is currently failing. The readiness assertion expects prewarming enabled, whereas the full-run safety command explicitly sets ODYSSEUS_TOOL_INDEX_PREWARM=0. With that override absent, all five readiness tests pass on untouched latest dev. The two namespace tests receive extra Failed to create stream fd stderr in this host's contained process output. That same output occurs without the Notes overlay; no backend containment code was changed or a failing assertion weakened. Reproduce those two checks on the supported CI runner before claiming a green full-suite certification.

In the final indexed full-suite run the only failures are test_namespace_handshake_closes_model_stdin, test_execution_environment_cannot_replace_probed_bwrap[False], and test_tool_index_is_reported_but_not_critical_by_default. The missing-Git-metadata publication failure and the seven checkout-only skips are absent from this run. No Notes regression was reported. Feature code matched N6 at publication. Later commits on the PR changed ui/reminderPicker.js (date input value assigned through the DOM property) and, after review, index.js, ui/layout.js and application/state.js; implementation.sha256 covers the current files.

To reproduce the integration rehearsal, extract the latest target with git archive into a fresh fixture and copy only files in the changed-file inventory on top. Do not overlay foundation files that are unchanged in this PR. Install the locked development dependencies in the fixture, then run the commands below there.

While this review diff is uncommitted, this prepares an equivalent Linux fixture without changing either task worktree:

notes_fixture=$(mktemp -d /tmp/ody-notes-integration-XXXXXX)
git archive 86b886c611338282af6d4a717246ea4e256f58df | tar -x -C "$notes_fixture"
{ git diff --name-only -z; git ls-files --others --exclude-standard -z; } |
  tar --null -T - -cf - | tar -xf - -C "$notes_fixture"
git -C "$notes_fixture" init -q
git -C "$notes_fixture" fetch --no-write-fetch-head "$PWD" 86b886c611338282af6d4a717246ea4e256f58df
git -C "$notes_fixture" read-tree 86b886c611338282af6d4a717246ea4e256f58df
(cd "$notes_fixture" && npm ci --ignore-scripts --no-audit --no-fund && git add --all)
# Run the validation commands below from notes_fixture, using an isolated Python environment.

Use a real dependency directory for this recipe; a symlink named node_modules can bypass the repository's directory-only ignore pattern. No checkpoint or fixture commit is needed. After integration, validate the actual integrated checkout directly, rather than relying on the uncommitted-diff recipe.

Commands

Use the actual tested interpreter, or install the repository requirements in your own isolated virtualenv. Node development dependencies were installed with the existing lockfile and npm ci --ignore-scripts --no-audit --no-fund.

python3 scripts/build_frontend.py
python3 scripts/build_frontend.py --check
node scripts/check_frontend.mjs
node scripts/check_frontend.mjs --inventory

ENDPOINT_URL=http://127.0.0.1:1 node --test \
  tests/frontendArchitecture.test.mjs tests/noteTestOracle.test.mjs \
  tests/notesDraftAutosave.test.mjs tests/selectedNotesContext.test.mjs \
  tests/notesCharacterization.test.mjs tests/notesRecurrence.test.mjs \
  tests/notesInfrastructure.test.mjs tests/notesApplication.test.mjs \
  tests/notesReminders.test.mjs tests/notesWorkflows.test.mjs

CHROMADB_HOST=127.0.0.1 CHROMADB_PORT=1 \
  python -m pytest -q -rs \
  $(rg --files tests -g 'test_*note*.py') \
  tests/test_frontend_build.py tests/test_frontend_foundation_offline_js.py \
  tests/test_frontend_module_graph.py tests/test_frontend_module_version_parity.py \
  tests/test_panel_loader_js.py

python scripts/verify_frontend_runtime.py
python scripts/verify_notes_browser_runtime.py

docker run --rm --network none \
  --mount type=bind,src="$PWD",dst=/candidate,readonly \
  --workdir /candidate --entrypoint python \
  <existing-odysseus-image> scripts/verify_frontend_runtime.py

CHROMADB_HOST=127.0.0.1 CHROMADB_PORT=1 \
  ODYSSEUS_STARTUP_WARMUPS=0 ODYSSEUS_TOOL_INDEX_PREWARM=0 \
  python -m pytest -q -rfs

git diff --check

ENDPOINT_URL satisfies the existing oracle's import configuration; its endpoint- driving main does not run in these unit tests. Port 1 is the closed loopback target used for pytest; the two runtime scripts reserve their own non-listening Chroma port. The native browser script creates a private distribution/database and a temporary authenticated user, then terminates the server and removes that fixture. It uses the real application and Notes API rather than mocked browser routes.

The deterministic browser harness uses stub API responses and the real Notes ESM, DOM and stylesheet graph. It verifies namespace/default methods and arities, aliases, remount/search reset, rejected/accepted attachments, draft persistence, drawing/undo and listener/portal cleanup. It also checks larger-touch reorder after re-render, active-drag close cleanup and cancellation of a mobile selection hold. It includes the mobile viewport meta tag, tap-to-read/edit behavior and the existing selection jiggle. The original monolith can be replayed with NOTES_BASELINE=1; it is read from the frozen F1 revision.

Browser and packaging evidence

Actual app screenshots: desktop and mobile. These are Chromium screenshots of the disposable authenticated app at 1440 x 1000 and 390 x 844, not rendered mockups. The deterministic before/after fixture had an identical mobile PNG and only 14 changed desktop pixels in the header region; no layout/style change was observed. CSS, app bootstrap and HTML have no implementation diff.

The native and Docker distribution probe serves all manifest outputs without frontend/, node_modules/ or Node on the server path. It checks response bytes, JS MIME, revalidation, CSP, shell startup, static confinement and source-tree 404. Docker used existing image sha256:cc2d47e2327d573af01c6b027f23d2ab0f2ee9b85d658e9eb8065bd02b9c3515. This is not a fresh Dockerfile build or deployment.

Tested locally: Linux, Python 3.14.4, Node 22.23.1 and Playwright/Chromium 1.62.1. CI's exact Python 3.11/Node 20 pair, Firefox/WebKit, macOS/Windows executable builds, live model/email notification delivery and full root offline reload were not run. The Docker runtime uses its own existing dependency versions. Shared active-window gesture interleavings are not exhaustively covered. No broader platform certification is claimed.

The full-run safety overrides differ from official CI's plain pytest command. For the readiness default-contract check, use env -u ODYSSEUS_TOOL_INDEX_PREWARM python -m pytest -q tests/test_readiness.py. Keep explicit warmup/storage isolation on the disposable live-app probes.

Internal checkpoints

Checkpoint snapshots are kept with the maintainer handoff, not in the repository. The hashes below identify them. They contain scoped source/output/facade/manifest/test overlays, not secrets or user data. Each starts from the same frozen baseline; they are not separate PRs or release candidates.

Stage	Boundary and executed exit evidence	Snapshot SHA-256
N0	Public/consumer/state/lifecycle map; 95 baseline Python and 11 Node passes; four new characterization tests; desktop/touch harness; 33 F1 publication/graph checks	db0a2e6e68fec3442ce350ffb0acf47bcdf2a5266f7c64c2bf910a1c41c4fb62
N1	Pure recurrence/date rules; eight Node and nine focused Python passes; differential oracle in four time zones; parity/boundaries	fd0638470744706fbbd5787cb47bd2078a93c9b854139f89f8fdc169c1f353c6
N2	HTTP/storage adapters; fourteen Node and seven focused Python passes; exact requests, keys and fallback contracts	30826fb7972d1b9e3a790f97ee81f66dcb3dc58eb7d23e24d4f46e6d841b7c73
N3	Single state owner and CRUD/undo boundary; ten Node and seven focused Python passes; read-only state and archive rollback	4bc5293519b8438d0126a61887bea64195dcdb7d59bcfaaba8ed4ae8c38be439
N4	Page-owned reminder workflow; four reminder contract tests and seven focused Python passes; singleton interval, catch-up, markers and fallback	febb835c4958c8758e4b7c23ce89f3ec8d103c2cc28f89817d258b3791a9fcdf
N5	Complete UI/application integration; 44 Node passes, targeted source guards and actual browser checks; drawing binding correction, read-only state and disposal	e147f645bdb2161a4b1dc6cf10c36ba6d0c214d8e12fccb478835043eaaf3e94
N6	Final facade, identity, exact offline graph, native/Docker checks, final editor-deletion/reorder ownership review, touch cleanup regression checks and maintainer review package	c450e91f9fbfe5f0cd805e596b92a76383f22a74e9515ca3e3f6154aebf5f61f

The N6 overlay contained the final code, tests, manifest and attributes at publication, not the evidence directory itself. From the repository root, run sha256sum -c docs/frontend-architecture/evidence/notes/implementation.sha256 to verify the current implementation files.

No checkpoint commits were made. To reproduce an overlay, create a fresh temporary directory, extract git archive 1cc56cb9... there, then extract the desired snapshot from the handoff on top. Install the locked test dependencies in that fixture and run its relevant commands. Begin from the baseline rather than overlaying snapshots onto a later dirty tree. For live rollback, release a complete matching artifact through the authorized release workflow.

Temporary mechanical extraction scripts are not part of the supported deliverable. They were archived locally, then removed. The first generated patch accidentally targeted the separate foundation worktree; only those edits were reversed, absolute paths were adopted, and that worktree's clean state was verified afterward.

Open PR overlaps and handoff limits

The following remained open at the read-only GitHub refresh:

• #6585: optional Notes field removal in the backend. Existing null-field behavior is retained here.
• #6647: read-only Notes intent routing.
• #6652: manage_notes registry dispatch.
• #6470: shared theme, typography, sidebar and modal changes.
• #6695: extension system/platform integration.

Their changes were not merged or reimplemented. Shared UI exceptions, root-SW scope, the original last-completion fetch race, temporary-note correlation and canvas-draft limits are documented in the case study. Backend owner checks and PR #6495 contracts remain authoritative.