Add source attachment manifest workplan

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.