# Implementation Plan: Verified publication corrections **Branch**: `codex/verified-publication-corrections` | **Date**: 2026-10-04 | **Spec**: [spec.md](spec.md) **Input**: Prospective requirements from `specs/023-verified-publication-corrections/spec.md`. ## Summary Preserve independently verified correction knowledge so repeated publication payloads cannot regain a wrong owner through filenames, metadata or recompression. Native Mylar owns authenticated immutable evidence and final admission; worker checks are advisory until local writer/revision checks and native publication revalidation pass. Existing incorrect duplicates remain separate restore-verified operational work. ## Technical Context **Language/Version**: Existing Python native and worker runtimes; actual pinned image gates are authoritative. **Primary Dependencies**: Existing Mylar workflow/writer/catalog/tagger modules; immutable archiving-utils artifact already used by the normalizer; image-bundled libarchive reader. No runtime network dependency for payload verification. **Storage**: Existing private `workflow.sqlite`, complete correction census/revision and an owned writer-protocol binding marker; worker receipts in existing state. Native application schema is unchanged. Reviewed device recovery adds a bounded private adoption ledger within the existing writer root, preserving immutable rows and original binding bytes. Stable Btrfs identifiers support prospective device-number reconciliation without relaxing per-process physical custody. **Testing**: `unittest`, actual patched native-source branch checks, converter-backed worker fixtures, both published image build gates and `make ci-local`. **Target Platform**: Independent portable Mylar and Komga Compose examples with the existing shared media/writer protocol. **Project Type**: Native application adapters plus maintenance worker and authenticated operational APIs. **Performance Goals**: No library-wide scan per import. Skip payload scans when the validated registry is empty; otherwise stream only the candidate and any matched correct-owner evidence, with fixed bounds/timeouts. Reuse only stable source/registry-bound proofs under writer exclusion. **Constraints**: No guessed identities, archive writes during checks, automatic correction registration, false import completion, global blacklist or privilege expansion. New mounts/ports are unnecessary. **Scale/Scope**: At most 512 immutable correction attestations per v1 registry; at most eight explicit allowed/rejected owners per admission; 4,096 archive members and 4 GiB expanded bytes per bounded inventory. Oversized or unavailable evidence remains held. ## Constitution Check - Portable examples: private correction attestations remain runtime state; examples contain placeholders only. - Complete contracts: Mylar image/runtime dependency, Compose/environment/preparation/ingress comments, metadata/README and module map are reviewed together; matching worker contracts document protocol, deployment and retention. Existing ports/mounts/privileges remain sufficient. - Operations: registration and repair follow scoped consistent backup/independent restore; no privileged action while the user’s hold applies. - Generated truth: regenerate catalog/topology only if tracked metadata changes; no manual generated edits. - Validation: focused kernel/boundary/fixture checks, independent reviews, full local CI and actual native/worker image gates precede delivery. Pre-research and post-design gates pass; no constitution exception is required. ## Project Structure ```text specs/023-verified-publication-corrections/ spec.md plan.md research.md data-model.md quickstart.md tasks.md contracts/publication-corrections.md checklists/requirements.md stacks/mylar3/ Dockerfile config/publication_guard.py config/publication_api.py config/publication_identity_adoption.py config/publication_identity_maintenance.py config/publication_identity_readers.py config/publication_filesystem_binding.py config/patch_publication_guard.py config/patch_publication_startup.py config/publication_fresh.py config/publication_native.py config/publication_transaction.py config/patch_publication_processing.py config/test_publication_native.py config/test_publication_guard.py config/test_publication_api.py config/test_publication_startup.py config/apply_patches.py config/verify_image.py config/MODULES.md config/{native_writers,workflow_store,processing_guard,tagger_backend,tagger_native, tagger_service,file_identity,converted_catalog,converted_tagging, release_naming,tagger_supplement,patch_media_writers,library_metadata, tagger_adapter,tagger_nfs}.py stacks/komga/normalizer/ publication_guard.py test_publication_guard.py import_recovery.py pack_recovery.py maintenance.py normalize.py naming_worker.py writer_cycle.py test_writer_cycle.py ``` **Structure Decision**: Keep correction authority in the focused native SDK, authenticated protocol in its separate controller and checked build adapter, and the worker protocol adapter in its independent Docker build context. Integrate checks into owning modules and actual native branch patches. Preserve existing owner/recovery contracts instead of introducing a new general processing framework. ## Delivery and verification Implement and verify registration as the first independent story, then every publication boundary, then scoped repeat reconciliation. Source delivery may be split at coherent reviewed milestones; do not call prevention complete until all writer boundaries and matching images pass. Native-first rollout is coordinated and restore-verified; exact existing repeats seed only reviewed evidence. Feature 022 completion remains gated by current-library repair, final protected second pass, cleanup and worker resumption. ## Owned tagging integration T007 introduces a private typed tagging intent and internal capability under the already admitted raw Writer. Ordinary operations and public advisory routes keep their pending-state hold; only the exact current job may revalidate its own fence and payload. Bind native tagger state-directory identities before producer use. Persist source/owner/policy/census and phase-specific publication evidence with its receipt. Recheck current authority and matched correct-owner archives before publication, pack finalization, cleanup and acknowledgement. Clear only the captured fence after durable verified terminal receipt; interruptions retain the typed hold and preservation copies for explicit review. This requires shared Publisher/NFS/ handoff checkpoint work during T007; T009 subsequently covers its other direct consumers and reviewed source-to-target/derivative recovery. No generic nested fence bypass or automatic upgrade of unbound receipts is permitted. T010 must also hold a retained prepared tagging intent even when its pending marker is absent. Legacy copy/CLI/cleanup remains held before invocation in publication mode until its temporary state and fallback placement are bound to an owned adapter. An in-place producer may replace only a retained copy outside the registered correction owner paths. Bind its complete NFS before/after file and workspace facts into both the owned intent and receipt before displacement. Preserve the current registered archives and complete payload/owner observations throughout. Passive proof uses only the already-bound in-process publisher; expired capabilities and lost state grant no initialization or replay. Registered catalog paths require an explicitly adopted exact derivative relation and a typed producer; the new reviewed transition preserves original payload protection and every inherited owner claim. Unadopted SDK or automatic nested repair remains held. Keep terminal witnesses under the existing private writer state. Bind their complete retained predecessor to the receipt's canonical intent digest, and bind terminal facts to a canonical proof in that same receipt before releasing the owned marker. Revalidate witness contents through both release boundaries. An exact closed receipt may then be read by a later job without replay or a remaining disposable output. Its epoch must still match current authority, its revision cannot exceed the current revision and its census keys must remain present. The receipt binds the complete original census; changed or unbound history stays held. These witnesses grant no current media mutation or recovery permission. ## Prospective aggregate recovery dependency T020–T025 and T028 source review precede the T026 source/install milestone. One shared T026/T029 isolated forward and distinct rollback then supplies the connected criteria of feature 024 T012/T015 and isolated T027. Whole-task completion is not a circular prerequisite for that pair. Accepted connected proof and matching delivery precede the rollout milestone in T017; T027 then supplies fresh live aggregate evidence before T017 reconciliation and T018–T019 acceptance and cleanup. Original task IDs and history remain. Native `publication_negative_batch.py` owns the immutable five-source marker, complete shared-parent phase projection, exact staged reservations, rollback and terminal closure. `publication_reader_phase.py` owns stopped-reader scope, main/tasks raw restore custody, typed SQL comparison and exact forward/reverse transaction boundaries. Native/worker ordinary admission and archive PREPARE refuse the new pending marker without a generic bypass. A durable root-owned terminal successor hold must precede aggregate-marker removal and span final receipt acknowledgement, including crash and lost-response boundaries. Installers and selected image tests must verify exact classes and module provenance before use. Fresh operational reader and NFS evidence remain separate from portable source tests. ## DDL cache growth prevention — 2026-10-12 Extend the existing intake/backpressure boundary with a configurable retained-cache byte budget and processing headroom. Inventory the cache without following symlinks, count retained and temporary payloads, and refuse new admission when capacity cannot be established. Reuse existing durable capture ownership to prevent repeated downloads of an unresolved delivery. Keep import acknowledgement and source-retirement authority unchanged; neither age nor a Completed label permits deletion. Verify boundary, concurrent reservation, restart, unreadable state and retained-pack scenarios before reviewed image delivery and live acceptance. ### T028 fixed-anchor launch follow-up Reuse the source-reviewed root broker and existing enrollment/authentication protocol. A revised finite profile adds only three fixed root public-anchor read-only leaf mounts, with empty root-owned image targets. Capture host originals before reads, authenticate their hashes to the reviewed deployment and retain source/creator/namespace custody through launch. Keep legacy profiles strict and ordinary service startup unchanged. Validate success and missing/empty/ symlink/replaced/key/inventory/profile/mount refusals with disposable controls; require real image-layout smoke and configured UID1000/pipe/retained-ACK proof before operational acceptance. No new signing framework is introduced. Retained acceptance verifies a distinct fresh retained catalog event and ACK against an existing catalog target. It preserves Location and Status and grants no ordinary import ACK or source cleanup. T033 owns genuine ordinary import and later automatic-capture acceptance. A Wanted member without a catalog Location is excluded from the retained route; an eligible ordinary selected pass follows its own admission and preservation checks. The Root retained run must reserve native operations for the exact selected request before taking its paused backup. Reuse the native mode lock and active operation counter, and fence ordinary background work and raw `publicationControl` Writer routes with a durable, private reservation marker. The existing primary normal API key and POST/source checks own this finite control; do not change `API_ENABLED` or infer authority from saved JSON. Only the same live native process may admit the selected finalize/status calls. Restart, expiry, foreign request, busy acquisition and lost custody hold for review. Keep the reservation through independent terminal verification, the actual Worker release ACK, natural child exit and guarded Reader resumption. Close it only against the original nonce, actual final record and complete SQL proof, then retain the closed receipt for accepted owning cleanup. This is an implementation requirement of T028, not accepted configured execution. Completion archives independently verified pending and closed records in the original nonce's private history directory. The original pending marker remains the restart fence until both copies and final business state are verified. Its removal is the commit point; caught later failures restore a negative fence. Live custody clears only after the Writer context exits successfully. Saved history grants no authority and its nonce cannot be reused. A crash before commit holds; a crash after commit retains the already verified durable history. Reservation health reports held publication authority with current worker liveness; it does not acquire the worker-held Writer, read SQL or grant import/readiness authority. Actual configured completion remains T028 acceptance work until the Root transcript, terminal checks and guarded resume are proved. The participating worker pack stage consumes the effective native policy from the authenticated, prefetched `getHealth` reply. The snapshot binds the existing config bytes, reservation inode and physical cache roots. It is read under the shared Writer without another API call and mapped only through existing `/mylar` and `/ddl-cache` binds. Normal admitted startup initializes the native lock; health never creates it and the worker opens it existing-only through its read-only native config mount. Missing, stale or unmapped policy refuses staging without guessed defaults. Finalize and verify conversions in independent worker state, then reserve their exact output size plus block/inode overhead before copying into shared cache. Release the cache reservation before import or handoff. Existing verified output may be reused with zero growth above capacity; positive growth still refuses. Partial stages and original payloads remain retained. Independent worker state remains outside this DDL budget and requires its own storage policy. This source design does not establish the actual configured limits or live T030 acceptance. The effective policy separately binds the actual DDL directory even when it is a subtree of the aggregate CACHE_DIR. The worker checks the declared writable DDL alias against that exact original subtree and retains the aggregate roots for accounting; it never adds the writable alias as a duplicate budget root or permits growth in another aggregate root. Native config observation accepts the owning regular-file contract (root/current owner, no group/world write, at most 2 MiB), preserving its original mode and hash. Each unchanged pack member/source generation has one exclusive conversion workspace. A durable finalized receipt binds the original source path/full identity/hash, workspace identity and finalized output full identity/hash. Capacity refusal retains it; a later cycle verifies the same originals and preservation before reusing it without conversion duplication. Incomplete, changed or unknown attempts remain for owning review. Minimum positive cache admission precedes a new workspace, and exact finalized-size admission still precedes cache copy. No source cleanup, budget increase or ACK follows from this receipt. ### Restricted ongoing ordinary pack recovery FR-017 uses the existing worker entrypoint, pack-only selected executor and native `packWork` pagination. An explicit recurring CLI branch and last Compose command override leave the full default cycle unchanged. Discovery fetches health/work and the existing bounded reader observation outside Writer, then validates current scoped authority. Every selected pair gets a fresh selected preparation and owning member/cache/import/report/ACK checks. Dispatch stays outside Writer. No general maintenance, naming, catalog fallback, conversion sweep or reader scan runs. Native passive discovery rotates through at most eight completed DDL rows and eight pending captures per poll. One unknown source receives a cumulative 256 MiB actual-read allowance, reserved before the attempt and consumed on failure. Changed known identities produce separate review observations without rewriting original captures, members or acknowledgements. Pending and observed source paths remain protected across pagination. Trusted download capture keeps its existing 32 GiB bound. This does not retroactively establish legacy source birth authority or grant automatic device-change adoption. T033 follows delivered selected-path source and T032 control-state acceptance. Review source and all copied current fixtures, publish and verify the matching worker, then perform affected-state backup/restore and a selected canary before restricted activation. Prove a later capture without a second manual invocation, restart reconciliation, no uncertain replay, typed catalog-to-ACK completion and original preservation. Keep full/bulk activation and configured Parent/NFS gates separate. Capacity refusal remains a hold under FR-016. ## Explicit disposable NFS searchability Creator request v3 and geometry v2 `searchable-common-root-nfs` address daemon path traversal on root-squashed NFS without changing live storage or exports. Only the fresh supplied NFS scratch parent and newly created common G use exact UID/GID1000 mode0711. Library/retention leaves and local state stay0700, credentials 0600. Existing ancestors must already be searchable; existing failed generations are never chmodded or adopted. The single transient G bind, exact per-role L mounts, two-child namespace, full9/FD custody, mount-ID and role exclusions remain unchanged. Legacy Creator v1/v2 and geometry v1 keep their exact0700 contract. The owning source contract documents stat-visible names and the absence of non-owner enumeration/write rights. Component tests and a separate disposable bind probe do not establish full Creator, NFS lifecycle, import or ACK acceptance.