diff --git a/workplans/MKTF-WP-0003-source-attachment-manifest-compatibility.md b/workplans/MKTF-WP-0003-source-attachment-manifest-compatibility.md new file mode 100644 index 0000000..75aaf4a --- /dev/null +++ b/workplans/MKTF-WP-0003-source-attachment-manifest-compatibility.md @@ -0,0 +1,147 @@ +--- +id: MKTF-WP-0003 +type: workplan +title: "Source Attachment Manifest Compatibility" +domain: markitect +status: todo +owner: markitect-filter +topic_slug: markitect +planning_priority: P2 +planning_order: 30 +depends_on_workplans: + - MKTF-WP-0001 + - MKTF-WP-0002 +related_workplans: + - MKTT-WP-0018 + - MKTT-WP-0021 + - MKTT-WP-0020 +created: "2026-05-15" +updated: "2026-05-15" +state_hub_workstream_id: "16e5c830-31e3-4070-9e27-65d28ed06595" +--- + +# MKTF-WP-0003: Source Attachment Manifest Compatibility + +## Purpose + +Provide the read-side source attachment and asset metadata needed by the +Markitect render reference and asset manifest contract without making +`markitect-filter` a renderer or export pipeline. + +`markitect-filter` owns concrete source-format normalization. It should expose +attachments, embedded media, package resources, and related provenance as +normalized source metadata that `markitect-tool` can consume when building a +render asset manifest. + +## Boundary + +`markitect-filter` owns: + +- source-format-specific attachment discovery +- read-side source asset metadata +- media type, extension, size, and digest capture where available +- provenance back to package paths, pages, anchors, or source members +- diagnostics for skipped or unsupported embedded resources +- fixtures proving EPUB3 and PDF adapters preserve read-side asset metadata + +`markitect-filter` does not own: + +- write/export adapters +- renderer execution +- output asset copying +- final render artifact paths +- publication lifecycle or durable artifact storage +- Quarkdown invocation + +Those responsibilities belong to `markitect-tool` contracts, +`markitect-quarkdown` render integration, or later runtime/publication systems. + +## P3.1 - Align attachment metadata with Markitect source contracts + +```task +id: MKTF-WP-0003-T001 +status: todo +priority: high +state_hub_task_id: "d119daca-8141-4662-8ad7-ce43ccd79044" +``` + +Confirm how existing `markitect_tool.source.SourceAsset` and +`NormalizedMarkdownDocument.attachments` should be populated by concrete read +adapters. + +Output: compatibility note, adapter metadata conventions, and tests that can be +run with `markitect-tool` on `PYTHONPATH`. + +## P3.2 - Add EPUB3 embedded resource metadata + +```task +id: MKTF-WP-0003-T002 +status: todo +priority: medium +state_hub_task_id: "ebcbf480-210d-46e7-a4e4-fbe7e9baa39a" +``` + +Extend the EPUB3 adapter to report package resources that are relevant to +future render manifests, such as images, stylesheets, fonts, and media where +safe and cheap to inspect. + +Output: EPUB3 attachment metadata, provenance, diagnostics, and fixtures. + +## P3.3 - Add PDF attachment and image-signal metadata + +```task +id: MKTF-WP-0003-T003 +status: todo +priority: medium +state_hub_task_id: "d8b7b820-387f-4d45-bf22-296b227f917a" +``` + +Extend the PDF adapter with read-side metadata for attachments or embedded +resource signals where the current dependency profile can expose them +reliably. + +Do not add OCR, layout reconstruction, or renderer behavior. + +Output: PDF metadata conventions, diagnostics, and tests. + +## P3.4 - Preserve checksums and provenance + +```task +id: MKTF-WP-0003-T004 +status: todo +priority: high +state_hub_task_id: "ca539c01-c272-4635-8f60-86f870bbef0c" +``` + +For each attachment or source asset, preserve stable identity fields: + +- source URI or package member path +- media type and extension +- byte size where available +- digest/checksum where feasible +- page, anchor, section, or package path provenance +- extraction diagnostics and quality notes + +Output: deterministic digest/provenance tests. + +## P3.5 - Provide handoff fixtures for render manifests + +```task +id: MKTF-WP-0003-T005 +status: todo +priority: medium +state_hub_task_id: "f2213a20-ce6f-4e16-9b9b-557b99f8b4d1" +``` + +Add fixtures that `MKTT-WP-0021` can use to prove source attachments flow into +render asset manifests without renderer execution. + +Output: fixture files, README/docs update, and cross-repo validation command. + +## Exit Criteria + +- EPUB3 and PDF read adapters can expose read-side asset metadata when present. +- Unsupported or skipped resources produce structured diagnostics. +- `markitect-filter` remains read-only and does not implement export/render + behavior. +- `markitect-tool` can consume the metadata for passive render asset manifests.