Amanuensis

Subsystem · B-04

Diff-aware materializer

Survey record for Diff-aware materializer: scope, reading path, concern review, findings, boundaries, vocabulary, and notes.

Branch  main Checked  adc4ce04aa57 As of  2026-08-29 04:56:43 No recorded stale entries Survey depth  Mapped

Status: Mapped Layer: projection

§Scope

materializer/**; read-only DB access, page planning and rendering, the typed HTML projection and its independent read-back, manifest dependency hashes, xref resolution, and clean documentation output.

§Start here

materializer/amanuensis_materializer/core.py; materializer/amanuensis_materializer/html_projection.py; materializer/amanuensis_materializer/diagrams.py

§Notes

Derived-artifact correctness boundary and the primary human reading surface. Gained html_projection.py and readback.py since onboarding, and diagrams.py replaced the runtime-boundary placeholder with extraction from registered prose. Finding B04-1 recorded in the 2026-08-27 refresh: staleness_map renders an empty result as an affirmative freshness claim, so the published HTML asserts the conspectus is fresh regardless of drift.

§File ledger

html_projection.py

Path
materializer/amanuensis_materializer/html_projection.py
Review
candidate
Revision
5694080

Why this file is in scope

HTML projection renderer; the primary human reading surface per the reporting contract.

readback.py

Path
materializer/amanuensis_materializer/readback.py
Review
candidate
Revision
5694080

Why this file is in scope

Independent read-back verification of published HTML and Markdown views.

test-readback.py

Path
materializer/test-readback.py
Review
candidate
Revision
5694080

Why this file is in scope

Test covering independent HTML and Markdown read-back verification.

uv.lock

Path
materializer/uv.lock
Review
candidate
Revision
5694080

Why this file is in scope

Pinned Python dependency set for the materializer.

.gitignore

Path
materializer/.gitignore
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

README.md

Path
materializer/README.md
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

init.py

Path
materializer/amanuensis_materializer/__init__.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

core.py

Path
materializer/amanuensis_materializer/core.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

db.py

Path
materializer/amanuensis_materializer/db.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

diagrams.py

Path
materializer/amanuensis_materializer/diagrams.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

manifest.py

Path
materializer/amanuensis_materializer/manifest.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

renderers.py

Path
materializer/amanuensis_materializer/renderers.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

slugs.py

Path
materializer/amanuensis_materializer/slugs.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

xref.py

Path
materializer/amanuensis_materializer/xref.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

materialize.py

Path
materializer/materialize.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

pyproject.toml

Path
materializer/pyproject.toml
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

test-materializer.py

Path
materializer/test-materializer.py
Review
examined
Revision
b8b566f

Why this file is in scope

Pinned A0 inventory assigns this file to B-04.

.manifest.json

Path
docs/.manifest.json
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

.projection-contract.json

Path
docs/.projection-contract.json
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

architecture.html

Path
docs/architecture.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

architecture.md

Path
docs/architecture.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

concern-checklist.html

Path
docs/concern-checklist.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

concern-checklist.md

Path
docs/concern-checklist.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

concerns.html

Path
docs/concerns.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

concerns.md

Path
docs/concerns.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

contradictions.html

Path
docs/contradictions.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

contradictions.md

Path
docs/contradictions.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

diagnosticity.html

Path
docs/diagnosticity.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

diagnosticity.md

Path
docs/diagnosticity.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

entry-point.html

Path
docs/entry-point.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

entry-point.md

Path
docs/entry-point.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

field-notes.html

Path
docs/field-notes.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

field-notes.md

Path
docs/field-notes.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

findings.html

Path
docs/findings.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

findings.md

Path
docs/findings.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

how-to-read.html

Path
docs/how-to-read.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

how-to-read.md

Path
docs/how-to-read.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

index.html

Path
docs/index.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

index.md

Path
docs/index.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

master-plan.html

Path
docs/master-plan.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

master-plan.md

Path
docs/master-plan.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

onboarding-report.html

Path
docs/onboarding-report.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

onboarding-report.md

Path
docs/onboarding-report.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

open-questions.html

Path
docs/open-questions.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

open-questions.md

Path
docs/open-questions.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

seams.html

Path
docs/seams.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

seams.md

Path
docs/seams.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b01-survey-methodology-and-agent-contracts.html

Path
docs/subsystems/b01-survey-methodology-and-agent-contracts.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b01-survey-methodology-and-agent-contracts.md

Path
docs/subsystems/b01-survey-methodology-and-agent-contracts.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b02-mcp-core-persistence-and-lifecycle.html

Path
docs/subsystems/b02-mcp-core-persistence-and-lifecycle.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b02-mcp-core-persistence-and-lifecycle.md

Path
docs/subsystems/b02-mcp-core-persistence-and-lifecycle.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b03-knowledge-tools-and-workflow-api.html

Path
docs/subsystems/b03-knowledge-tools-and-workflow-api.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b03-knowledge-tools-and-workflow-api.md

Path
docs/subsystems/b03-knowledge-tools-and-workflow-api.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b04-diff-aware-materializer.html

Path
docs/subsystems/b04-diff-aware-materializer.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b04-diff-aware-materializer.md

Path
docs/subsystems/b04-diff-aware-materializer.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b05-packaging-installer-validation-and-product-docs.html

Path
docs/subsystems/b05-packaging-installer-validation-and-product-docs.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b05-packaging-installer-validation-and-product-docs.md

Path
docs/subsystems/b05-packaging-installer-validation-and-product-docs.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b06-report-interface-design-and-validation-studies.html

Path
docs/subsystems/b06-report-interface-design-and-validation-studies.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b06-report-interface-design-and-validation-studies.md

Path
docs/subsystems/b06-report-interface-design-and-validation-studies.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b07-embedded-research-surveys-and-platform-trials.html

Path
docs/subsystems/b07-embedded-research-surveys-and-platform-trials.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b07-embedded-research-surveys-and-platform-trials.md

Path
docs/subsystems/b07-embedded-research-surveys-and-platform-trials.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b08-activation-evidence-and-release-readiness-harness.html

Path
docs/subsystems/b08-activation-evidence-and-release-readiness-harness.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

b08-activation-evidence-and-release-readiness-harness.md

Path
docs/subsystems/b08-activation-evidence-and-release-readiness-harness.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

vocabulary.html

Path
docs/vocabulary.html
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

vocabulary.md

Path
docs/vocabulary.md
Review
generated-ignore
Revision
aba6d04

Why this file is in scope

Published conspectus projection regenerated by the materializer; derived output, not authored source.

§Concern review

AT-1

Verdict
Competing explanations
Evidence
Code verified
Linchpin dependency
🔗

Rationale

Code shape makes AT-1 plausible in B-04, but runtime or domain evidence is required before confirmation.

AT-2

Verdict
Out of scope
Evidence
Code verified

Rationale

The structural and behavioral read supports out-of-scope for AT-2 in B-04.

CC-1

Verdict
Accepted behavior
Evidence
Code verified

Rationale

The structural and behavioral read supports confirmed-acceptable for CC-1 in B-04.

CR-1

Verdict
Accepted behavior
Evidence
Code verified

Rationale

The structural and behavioral read supports confirmed-acceptable for CR-1 in B-04.

EP-1

Verdict
Accepted behavior
Evidence
Code verified

Rationale

The structural and behavioral read supports confirmed-acceptable for EP-1 in B-04.

EP-2

Verdict
Out of scope
Evidence
Code verified

Rationale

The structural and behavioral read supports out-of-scope for EP-2 in B-04.

IF-1

Verdict
Accepted behavior
Evidence
Code verified

Rationale

The structural and behavioral read supports confirmed-acceptable for IF-1 in B-04.

RL-1

Verdict
Accepted behavior
Evidence
Code verified

Rationale

The structural and behavioral read supports confirmed-acceptable for RL-1 in B-04.

RL-2

Verdict
Accepted behavior
Evidence
Code verified

Rationale

The structural and behavioral read supports confirmed-acceptable for RL-2 in B-04.

SC-1

Verdict
Accepted behavior
Evidence
Code verified

Rationale

SM-03 integral contract was read from both mapped endpoints and passed at the pinned revision; residuals remain separately visible.

SC-2

Verdict
Accepted behavior
Evidence
Code verified

Rationale

SM-05 integral contract was read from both mapped endpoints and passed at the pinned revision; residuals remain separately visible.

SC-3

Verdict
Accepted behavior
Evidence
Code verified

Rationale

B-04 implements the refined B-06 coverage index with retained semantic matrix, contextual identifier definitions, and prose-flow thresholds; integration and failure/read-back gates pass.

SI-1

Verdict
Accepted behavior
Evidence
Code verified

Rationale

The structural and behavioral read supports confirmed-acceptable for SI-1 in B-04.

SI-2

Verdict
Accepted behavior
Evidence
Code verified

Rationale

The structural and behavioral read supports confirmed-acceptable for SI-2 in B-04.

TB-1

Verdict
Out of scope
Evidence
Code verified

Rationale

The structural and behavioral read supports out-of-scope for TB-1 in B-04.

TR-1

Verdict
Accepted behavior
Evidence
Code verified

Rationale

The structural and behavioral read supports confirmed-acceptable for TR-1 in B-04.

TR-2

Verdict
Out of scope
Evidence
Code verified

Rationale

The structural and behavioral read supports out-of-scope for TR-2 in B-04.

VG-1

Verdict
Confirmed defect
Evidence
Code verified

Rationale

The materializer converts an empty query result into an affirmative claim. staleness_map reads the entries table, which no server code path populates, and its empty branch emits 'No stale entries — the conspectus is fresh.' rather than reporting that no staleness data exists. The published HTML and Markdown at this SHA both carry that sentence while the conspectus was 23 commits behind HEAD. This is a projection-layer defect independent of B03-2's root cause: even once staleness is wired to a populated source, rendering absence-of-data as positive health is unsound.

§Findings

§B04-1 · Medium · fixed

Symptom: The published conspectus states 'No stale entries — the conspectus is fresh.' in both the HTML reading surface and its Markdown companion, regardless of how far behind HEAD the survey actually is. Root cause: diagrams.py:staleness_map renders an empty query result as an affirmative freshness claim. Its source, the entries table, is never populated by the server (see B03-2), so the empty branch is the only branch that ever executes — but the deeper defect is that the empty case is reported as positive health rather than as absent data.

Business context: The HTML projection is the primary human reading surface and the product's main deliverable. A reader opening it to judge whether the conspectus can be trusted is told, in the document's own voice, that it is fresh. At 5694080 that sentence was published while the survey sat 23 commits behind HEAD with 47% of tracked files unclassified. Because the claim is generated rather than authored, it carries the authority of the derived-artifact pipeline while resting on no measurement at all. This is the reader-facing endpoint of B03-2 and the reason that defect matters beyond an internal metric.

Primary files:

  • materializer/amanuensis_materializer/diagrams.py:staleness_map@5694080
related subsystems
From→ToRelationshipStrengthContext
B-03→B-04data-flowconfirmedStaleness flows from B-03's detect_changes into B-04's staleness_map projection via the entries table (seam SM-09). Because no writer inserts rows, the defect propagates from an inert internal metric (B03-2) into a published freshness claim in the primary reading surface (B04-1).

§Seams

seams
SeamShared objectOther party
SM-03materialize_docs subprocess and storage/docs projectionB-03
SM-05packaged Python materializer mirrorB-05
SM-06report projection design/component contractB-06
SM-09entries table (staleness columns: stale, stale_since, stale_reason)B-03

§Survey notes

  • Survey revision: b8b566f
  • Status: adversarial pass complete; packaging pending

§Key types

Materializer plans and renders the documentation site, PagePlan binds a page to its sources/renderer, Summary reports the run, and Manifest/PageManifest retain source and content hashes (materializer/amanuensis_materializer/core.py:Materializer@b8b566f; materializer/amanuensis_materializer/manifest.py:Manifest@b8b566f). XrefIndex resolves IDs into relative links after rendering (materializer/amanuensis_materializer/xref.py:XrefIndex@b8b566f).

§State containers

  • Read-only SQLite connection: durable survey source, one materialization run (materializer/amanuensis_materializer/db.py:open_ro@b8b566f).
  • .manifest.json: per-page source hashes, output hash, and render timestamp; persistent projection metadata (materializer/amanuensis_materializer/manifest.py:Manifest.save@b8b566f).
  • .materializer-lock: excludes concurrent writers for the output directory (materializer/amanuensis_materializer/core.py:Materializer@b8b566f).
  • docs/: derived Markdown projection; never the durable survey authority.

§Data flow

The CLI resolves storage/output, opens the database read-only, builds page plans from aggregate and subsystem renderers, compares stable source hashes to the previous manifest, renders affected pages, resolves cross-references, prunes retired pages, saves the new manifest, and prints a JSON summary (materializer/materialize.py:main@b8b566f; materializer/amanuensis_materializer/core.py:Materializer.run@b8b566f).

§Concurrency model

One process owns an output-directory lock. Database access is read-only. File updates and final manifest persistence are sequential; the manifest warns and rebuilds on corrupt JSON (materializer/amanuensis_materializer/manifest.py:Manifest.load@b8b566f).

§Seam contracts

  • SM-03 · B-03 ↔ B-04: B-03 supplies storage/output and treats process exit as the operation result; B-04 reads memory.db plus registered prose and writes only the derived output tree.
  • SM-05 · B-04 ↔ B-05: packaging copies the root materializer as the published mirror.

§Concern review

All active concerns are covered. Incremental/full parity is exercised by repeated and forced renders. Corrupt-manifest recovery is visible via warnings. Multi-file projection atomicity remains an unresolved competition: the lock prevents concurrent writers, but a killed process may leave some page files updated before the manifest is saved. It is not promoted to a confirmed defect without a kill-point control.

§Adversarial review

The pass tried to disprove diff-awareness by finding a change source absent from page plans. Tests cover unchanged runs, prose changes, disposition changes, retired pages, and forced full output (materializer/test-materializer.py:main@b8b566f). The baseline A0 clean-export checker adds independent state, coverage, and content read-back. Verdict: incremental contract upheld for the observed source classes; generator correctness still needs independent accept-corpus evidence.