C7.12j Prepare DTC book conversion through the unified format

Read AGENTS.md, the listed process and architecture documents, then inspect content_sync/convert/contracts.py, documents.py, report.py, and the public kind modules. Start with the existing convert_documents pipeline and focused tests under tests/content_sync. Done means the approved book fixtures convert through the shared pipeline with complete accounting, stable dry-run/apply behavior, and the stated boundary and public-kind checks passing.

Title: C7.12j Prepare DTC book conversion through the unified format
Repository: community-base
Depends on: C7.12
Freeze required: no
State: groomed scope for existing #410; source allocation remains separate

Goal
Extend the existing document conversion owner to convert the complete immutable DTC book input into D23 YAML manifests on disposable scratch copies, with complete non-loss accounting and a validated site-owned book-kind contract. Retain book public payload semantics for a later thin DTC publisher. This is package conversion capability/preparation, not D7.2 adoption or D7.4 source publication.

Read first

• AGENTS.md; docs/PROCESS.md; docs/04-quality-gates.md; user-required protected /home/alexey/git/community-base/coding-standard.md at4d0f8ae, SHA6225deff7714bc66cd12e47138c210e125e40315d152bac6e7e1bd2d3cc6bc69 (absent at8ebb; read-only authority, no port/foreign-wave merge).
• docs/01-decisions.md D23, D21, D17, D24; docs/02-architecture.md; docs/03-playbooks.md P15/P16.
• docs/plan/phase-7.md C7.12 and D7.2/D7.4; community_base/content_sync/FORMAT.md sections3.1-3.8 and4; accepted unified-content-format-2026-09-17.md TierB book row and section5.
• Current convert/contracts.py, documents.py, document_collections.py, document_metadata.py, document_output.py, report.py; public kinds/base.py/registry.py/layouts.py, documents.py, resolution.py and check.py.
• DTC106c777 content/sync_parsers/books.py; _docs/specs/03-github-content-and-people.md; _docs/content-authoring.md; public-record/catalogue/book presentation behavior retained in the static packet.
• Original book input facts and controlling decision supplement94941886. The manifestless legacy profile recommendation is withdrawn and NONACCEPTED.

Pre-assignment disposition

1. Root reviews/freezes the concrete MAPPING-PROPOSED.md: dtc-books namespace/source-keyUUID seed;37char internalslug for the singlelongkey; typed public_slug retains the exact current publickey/route/stablePK through site-owned current publication, not a historical extra object; description as plaincore summary alongside fullprose kind metadata; exact quoted naive ISO19 strings with import-boundary calendar/roundtrip/core-date agreement validation and image-first alternatives; validated nested archive/link data; actualpersonrefs alongside exact ordered literalcredits. These are competent proposed ordinary design choices, not mandatory human rulings.
2. Bind all98actualmetadata1a68a978/ac5bf6eb. Titles fit300;74summary>500/oneslug138/image-coverdiffer98/endclocks98/literalcredits17 are addressed by the proposed mapping, not by truncated outputs or widened core. Actual read/check/resolve/media/Personresolution/renderparity remain unrun.
3. Independent released-API qualification f38365a7 proves the extension types and identifies the datetime mismatch; this draft corrects it to exact naive ISO strings with owning validation. Freeze the supported registration/read/check/resolve signatures, logical-target/physical-path map, routing closure and explicit public_slug safety admission in MAPPING-PROPOSED.md before allocation. Demonstrate a precise public seam gap before adding any API. Site-owned books stay YAML and registry-controlled. No actualnormative conflict between separate literalcredits and real authors references is established; if an owning reading requires every literal credit to resolve toPerson, name that exact conflict for owner clarification.
4. Obtain explicit current converter/helper/editorial-source file ownership; no silence or idle releases foreign384/media/person/article/425/coding/course owners. Later D7.2 explicitly amends source-authoring/spec03 and freezes the actual released tag/storage/operator/publicreader scope before adoption. D7.4 retains real conversionpublication/cutover.

Steps after root design review, independent contract verification and explicit ownership allocation

1. Freeze one reviewed conversion contract and fixtures: each original path/blob/hash/declared slug/public path -> target books/YYYY/.yaml, deterministic content_id and complete metadata mapping. YYYY comes from the approved data date; start maps to core date while start_at/end retain exact quoted naive ISO19 strings; import-boundary parsing/roundtrip/naive/core-date/target-year checks are mandatory; cover/image merge must preserve current effective image choice and asset bytes. Keep YAML, one current representation of ordered links/archive/replies/full prose and necessary unknown authored metadata. Full original data/commit/path/blob/digests remain solely scratch import/conversion evidence, never liveextra or a runtimehistorical fallback. Retire legacy_path from converted authored keys and use typed public_slug for current domain/public identity. No Markdown book conversion or discussion flattening.
2. Add the book concern to the existing convert_documents(root, Profile, apply=...) pipeline. Proposed internal policy owner convert/book_policy.py supplies book target/values; contracts.py carries the minimal profile declaration; _Conversion._convert_yaml_collection calls existing discovery, metadata and output owners. Keep one walker, staged output plan, report and filesystem writer. Reuse UUIDv5 identity conventions only after freezing the namespace/target rule. Keep existing content_id on already-converted inputs. No public runtime parser is added to the package.
3. Feed valid/refused books into existing ConversionReport accounting. Refused files retain original bytes and are named with deterministic bounded diagnostics; every original book and asset is accounted for. Target/path/identity/key collisions must reach owning controls before overwrite. The generic YAML rename collision observation is an unqualified static concern, not permission for broad converter cleanup; change only the demonstrated book conversion/composition branch and preserve all other profiles.
4. Define the site-owned book KindSpec contract as a synthetic importable fixture through released public KindSpec, KeySpec, Layout, DirNode, RawItem, Problem and register_kind. The fixture exercises FORMAT-compliant books/YYYY/.yaml and images, using Layout.walk over the supplied DirNode, never a second filesystem/YAML reader. No package built-in book registration, core-key override, allow_unknown escape, data-kind substitution or manifestless bypass. The later DTC declaration remains site-owned under TierB; it is not assigned here.
5. Convert the complete pinned current d3397ee98-book input on an independent scratch copy offline. Bootstrap e29f56 remains historical provenance/representative control, not a second mandatory full run by default. Run the shared read_repository(..., kind_modules=...), resolve_repository(...) and check.run_check(..., kind_modules=...) with the approved book schema and synthetic route/media boundaries. Verify complete original -> converted -> intended book payload equivalence, including full summary, literal archive escaping and ordered author/link/reply data. YAML metadata prose is not automatically rendered or link/asset-resolved. Explicitly use released rendering.render_markdown for prose where current reader behavior requires it; archive discussion text stays literal/escaped. Use routes(kind,target) closure over admitted logical targets and safe public_slug, with exact leading-slash canonical output. Preserve all warning/error dispositions; use required string<=2048 plus current safe HTTP(S) admission for the measured223HTTPS+3HTTP destinations; retain every exact protocol/order. Where existing package rendering cannot represent a reviewed nested prose fragment, report that precise missing public seam before adding any new API; no private helper or site sanitizer duplicate is accepted.
6. Prove dry-run makes no write, second apply makes no diff, UUID/slug/ordering/asset bytes remain stable, report.verify accounts for every original file, and unchanged non-book collections/manifests remain represented. Keep all refused/failed attempts; do not call subset success all98 acceptance.
7. Update README, CHANGELOG and the frozen conversion contract, with distinct scratch-original/converted/derived-record checksum meanings, no oldpayload mirror in liveextra, and deferred site gates. Add the reviewed phase card and sync STATUS only after root accepts scope (C7.12j is assigned to existing #410). Independent Tester and PM evaluate the exact frozen source/fixtures/corpus output and required gates. Merge verified capability normally; publish an immutable package tag through P15 before any DTC adoption pin. No release operation is authorized by this draft.

Verification after implementation

• uv run pytest tests/content_sync -> all collected tests pass, baseline/final collection counts and extras recorded; includes focused book conversion/kind contract and existing article profile compatibility.
• uv run pytest tests/test_boundaries.py -> passes, no site imports.
• The pinned current98-book scratch corpus: conversion reports98 dispositions with zero unreviewed refusal; shared check/read/resolve zero errors with explicit registered kind; each mapped payload and preserved asset/order field compared, not merely equal counts.
• Existing public CLI: uv run python -m community_base.content_sync.convert.documents --profile --dry-run -> no filesystem diff; apply twice -> zero second diff. Store exact profile/version/input/output/report hashes. This command is pending profile approval, not an existing book API claim.
• Meaningful owning negative controls: duplicate target/content_id, conflicting key map, invalid/missing approved chronology, unresolved required author key, malformed/unsafe metadata (including invalid/aware/non-roundtrip timestamps, mismatched core date/year, unsafe public_slug), wrong physical-versus-logical typed target, missing image and global manifest collision -> expected bounded refusal; output and original unconverted bytes prove no overwrite/drop. No converted fulloriginalmetadata/retiredlegacy_path/livehistorical mirror or runtimebranch selecting olddata is permitted. At least one deliberate semantic field/order loss must fail its parity assertion, not an earlier lint/import check.
• Required section1 quality gates: uv run ruff check .; uv run ruff format --check .; uv run python testproject/manage.py check; uv run python testproject/manage.py makemigrations --check --dry-run; fresh disposable SQLite migrate; touched app/boundary tests; uv run python scripts/plan.py check. No migration change is planned; adding one returns scope to review.
• Fresh worktree extras sync and provenance before gates; package capability uses synthetic fixtures/fresh stores, no donor database or provider credentials.
• Both consumer checks through unchanged P16/default branches and sole OnCall, preserving exact baseline ERROR/linked FAIL categories and only current precise exceptions. No new exclusions or skip/count relaxation.
• Required immutable tagged release proof before later site pin/adoption; actual later site own graph-derived gates/CI+Dev remain Not run here, needs: D7.2 and D7.4.

Done when

• Root-reviewed concrete mapping, completed98-value audit, independent publicAPI contract verification and explicit file ownership are frozen before source assignment.
• One existing converter pipeline converts the complete current98-book scratch input into D23 YAML with complete accounting and preserved payload/order/assets/provenance mapping.
• Public kind/read/resolve/check contract validates the approved site-owned schema without bypasses, invented Person records or private parsing; naive ISO text/calendar/core-date agreement, safe public_slug and exact logical reference/routing controls pass.
• Every actual link shape is admitted without changing its destination; all summary errors/warnings are accounted for and exact metadata prose/archive output is compared rather than assumed automatically resolved.
• Dry-run, replay identity, second-run no-diff and meaningful refusal/parity controls pass.
• Existing article/profile identities and unrelated inputs remain unchanged; required package and P16 checks actually pass within their precise qualification scope.
• Distinct Tester/PM accept the exact frozen capability, normal merge verifies, and an immutable capability tag exists before any DTC adoption.
• Deferred D7.2 storage/readers/operators/rendered public page parity and D7.4 real source conversion/cutover are explicitly open.

Docs
community_base/content_sync/README.md; CHANGELOG.md; docs/plan/evidence/dtc-book-conversion-contract.md (new reviewed contract); docs/plan/phase-7.md; generated docs/plan/STATUS.md. FORMAT amendments only if an existing rule genuinely needs clarification; a decision conflict stops work for owner disposition rather than relaxing D23.

Revision6 measured preservation controls (frozen audit bb486d31): required link string<=2048 plus unchanged current safeHTTP(S) admission preserves223HTTPS+3HTTP exactly; no shared URL validator change. Required archive names remain nonblank while optional reply text admits and retains6empty placeholders in4books, with all5415ordered records and exact normalized presence/type. Preserve196distinct image/cover asset blobs and existing public paths, including98nonselected covers regardless of absent current cover metadata. Preserve8existing archive link localizations at the thin site owner and all unchanged external prose destinations; metadata does not automatically resolve/render them. All98description values satisfy coretext without warnings/errors and full prose remains separately preserved once. These are static admission findings, not executed converter/read/resolve/render/upload/site proof. Exact naive ISO19/public_slug/logical-target/routing/replay and all other preservation criteria remain mandatory.

Final explicit Person-key import boundary

• Existing convert_documents(root, profile, *, apply=True, known_person_keys=None) gains only the named optional keyword; Profile/public return stay unchanged. Book conversion requires explicit validated set/frozenset knowledge, including empty. None is unspecified and refuses before writes; existing non-book omitted-input behavior is unchanged.
• CLI adds one --person-keys reviewed UTF-8 JSON array-of-distinct-strings input. Invalid types/duplicates/slug shapes/malformed/unreadable data refuse with bounded errors; no Person walker/DB/aliases or speculative matches. Exact unchanged literal lookup keys alone match; every credit and its order survives regardless of match. Do not fabricate donor authors=[] parity.
• Bind the key count/canonical set digest in existing scratch ConversionReport.notes and raw CLI file digest in scratch evidence, never live YAML/history payload. Same source+same knowledge binds idempotence; changed knowledge is an honest relationship change. Public reference conformance uses synthetic sets; later D7.2/D7.4 must provide an authoritative site set and prove actual Person-link/public output parity. This is not a Person migration prerequisite for capability source assignment.
• Source addition stays in existing documents.py public/CLI boundary and new book_policy.py admission/selection; no extra converter/test owners or report schema/private registry APIs. Owning pre/post checks cover None versus explicit empty, exact matches/nonmatches/literal credits/order, malformed and duplicate CLI inputs, input nonmutation, deterministic digest, unresolved references and replay; intentional matching/credit-loss mutation must reach its owning assertion.
• Preserve all196root images/books asset paths/bytes unchanged; moving/copying is not required. Existing absolute_roots=('images',), assets={} and reference rebasing serve year YAML, with actual visibility/ignores/resolver/byte/public-route gates retained. This minimal preserving design does not claim executed asset proof.