[Frankie-Xu]

Summary

Implement the parsed-result ZIP contract from #45. New successful packages add schema_version: 1 to chunks.json, doc_nav.json and manifest.json and validate all three artifacts before upload and job completion. Existing version strings, chunk content and enriched navigation extensions are preserved.

Pydantic models generate SDK-discoverable JSON Schema with a CI drift check. The compatibility reader warns on legacy unversioned artifacts. Shape/version/count/asset/ZIP violations fail with sanitized structured details. Repeated asset paths store one member for equal content and reject conflicting content.

Draft design choices, not yet accepted by maintainers: models in shared-python plus generated language-neutral schemas, hard failure for malformed output, required navigation in new packages, integer versioning with additive optional fields unchanged, and retained legacy compatibility. Standalone SDKs are not modified.

Verification

• 28 synthetic Pydantic/JSON Schema/archive/logging cases and 6 actual ZIP writer cases passed.

• Reproduced an unsafe raw NUL member name being hidden by Python ZIP normalization; the actual archive regression passes.

• Reproduced upstream repeated-image duplicate ZIP members; repeated-reference and conflicting-content regressions pass.

• Reproduced diagnostic traceback locals leaking a synthetic document value; the canonical exception logging regression passes after the scoped fix.

• Ruff across apps/packages, targeted Pyright, generated schema drift check and diff check passed. Independent follow-up review found no actionable issues.

• Four isolated actual-source navigation loader cases verified that unsupported future section layouts fail instead of silently rebuilding to v1; existing known/legacy rebuild fallback is retained.

• 11 actual ZIP service/manifest cases passed, including all three unsupported-navigation layouts and pre-write rejection; 2 real worker PostgreSQL/filesystem contracts passed, covering successful upload and malformed-contract failure before upload. Initial collection missed pandas; an isolated evidence-directory runtime overlay resolved it without modifying the API environment. No external accounts or model calls are used.

• Full API/worker/shared Pyright in the API-only environment did not pass: 57 missing worker/optional import errors and 2 diagnostics in unchanged worker files. Scoped checks for the modified contract boundary passed; full worker dependency validation remains outside this local acceptance.

• Current-head GitHub PR CI, Secret Scan and CodeQL workflows report action_required; the PR has no reported check rollup. Remote CI has not passed.

Deployment Notes

• No migrations, new runtime dependencies or environment variables.
• Existing consumers ignoring additive root keys remain compatible. Malformed output/navigation generation failure now fails the job instead of uploading an incomplete result.
• Consumer helper reads legacy roots and optional legacy navigation with warnings; new producers require all three versioned artifacts.
• Rollback is reverting this PR; stored ZIPs remain readable by existing tolerant consumers.

Checklist

• Tests were added or updated when behavior changed
• Public docs, examples, or OpenAPI contracts were updated when needed
• Database migrations are idempotent and safe to deploy (none)
• Logs, errors, and validation paths avoid leaking secrets or user data
• The pull request description explains any breaking or user-visible change