D5.3c Preserve ordered cohort module/project flow in converted source

Start with content_sync.course_repository.parse_course_repository and the fixture at content_sync/tests/fixtures/course_repository/llm_zoomcamp_2026, recording the v0.5.21 refusal before changes. Read the allowed source and test paths, then run the focused source and normalization tests; done means frozen flow state, disposable idempotent normalization, preserved bytes and identities, converter compatibility, and all listed verification gates passing.

Preserve ordered cohort module/project flow in converted source

Goal

Preserve DataTalks.Club's authored cohort module/project order through a
source-only conversion contract. Add a pure typed reader for
extra.dtc_flow and a deterministic DTC pre-pass that normalizes the existing
schema-1 fixture in a disposable destination before the package converter
runs.

This issue changes no database, runtime parser, source registration, package
pin, route, template, API or visible UI.

Normative references

• _docs/specs/01-platform-architecture.md, Data ownership.
• _docs/specs/04-courses-and-cohorts.md, Curriculum ownership.
• _docs/PROCESS.md and _docs/ci/change-selective-ci.md.
• coding-standard.md from the DTC repository authority.
• courses/models/project.py:50-108 and courses/urls.py:111-151 for current
  cohort-plus-project-slug identity.
• courses/models/curriculum.py:158-229 for ordered exactly-one-target flow.
• Package FORMAT sections 3.3 and 3.8, C5.4 and C7.12d.

Dependencies

• C5.4 is done and released in community-base v0.5.18.
• C7.12d is done and released in community-base v0.5.21.
• The exact supplemental package proof uses immutable tag v0.5.21 at
  bb067c3d4bf66e9bd20d436ccf22d3402667da27.

No open runtime or migration issue is a dependency. This work must not consume
unreleased C7.12g or start D5.1, D5.3b, D7.3 or D7.4.

The tracked DTC dependency remains v0.5.10. Pure committed tests must pass with
that pin. The v0.5.21 proof is supplemental and uses the maintained local-link
workflow with dependency bytes restored afterward.

Current RED

Use the unchanged fixture at
content_sync/tests/fixtures/course_repository/llm_zoomcamp_2026.
Its 2026 flow is:

1. module content ID 21111111-1111-4111-8111-111111111111 with terminal
   homework 51111111-1111-4111-8111-111111111111;
2. project slug project-01.

Course, cohort, unit and question identities in that fixture are also retained
exactly. Direct conversion with v0.5.21 currently refuses the nonempty flow
under rule 3.8 and leaves that cohort scope unchanged. Record this actual
refusal before implementing the DTC pre-pass. A missing new-module import is
not sufficient RED evidence.

Source contract

The normalized cohort carries:

extra:
  dtc_flow:
    version: 1
    items:
      - kind: module
        content_id: "21111111-1111-4111-8111-111111111111"
      - kind: project
        id: project-01

id is the authored project slug scoped by the cohort identity. A rename is
an explicit remove/add unless a later reviewed migration maps it. Do not add a
project UUID or request a rename-identity decision.

The reader consumes package ReadResult and parsed curriculum values. It does
not open files or parse YAML. It returns frozen, slotted values and performs no
I/O, registration, model lookup, database access or mutation.

Validate:

• absent dtc_flow returns no DTC state and preserves package defaults;
• the exact version-one mapping and tagged item shapes;
• UUID module identities and bounded valid project slugs;
• all and only placed modules exactly once and in standard module order;
• unique project slugs within a cohort;
• cohort/module resolution through the parsed package graph; and
• bounded errors containing only code, repository-relative source path and
  pointer.

Do not admit Project title, deadlines, state, rubric or learner fields into
this record. Input mutation after validation must not alter returned state.

Disposable normalization

Reuse content_sync.course_repository.parse_course_repository as the sole
schema-1 parser. From its frozen graph and immutable byte snapshot, compute one
complete plan before any write.

The plan must:

1. prove each module and terminal-homework reference;
2. relocate the module subtree to the unified course tree;
3. relocate terminal homework to the standard cohort homework directory;
4. preserve course, cohort, module, unit, homework, question and option IDs;
5. write standard modules and homework values;
6. write the full original mixed order to extra.dtc_flow;
7. remove legacy flow only after collision and inventory validation;
8. preserve every unrelated file byte-for-byte; and
9. invent no Project metadata.

Apply only to an explicitly supplied disposable destination below the
repository-local .tmp. The source checkout remains unchanged. Invalid,
missing, overlapping or colliding input leaves the destination absent or
unchanged.

Then run the public v0.5.21 converter and parser. The standard graph plus DTC
state must reconstruct the original flow. A second complete run changes no
path or digest.

Allowed paths

• new content_sync/dtc_flow_source.py;
• new content_sync/dtc_flow_normalization.py;
• new content_sync/tests/test_dtc_flow_source.py;
• new content_sync/tests/test_dtc_flow_normalization.py; and
• a narrow update to
  _docs/architecture/course-platform-shared-apps-mapping.md stating that
  source representation is proven while runtime placement/storage stays open.

Read the existing fixture without changing or duplicating it. Do not check in
generated converted output.

Each new or materially changed handwritten source and test file must be at or
below 300 lines. Each new function must be at or below 30 lines. Do not use
ternary expressions or filtered/nested comprehensions. If the complete
behavior cannot fit two cohesive source modules and two cohesive test modules,
split pure validation from normalization into separate issues. The pure half
alone cannot close this issue or any adoption criterion.

Non-goals

• No changes to the existing schema-1 parser without a separate authoritative
  parser defect.
• No new YAML parser, generic converter, operator CLI or runtime source reader.
• No model, migration, database import, package pin, lock, webhook, job,
  source registration, route, API, template, static or browser change.
• No live course-repository mutation, deployment or production data access.
• No Project metadata synthesis and no claim of learner-record preservation.
• No D5.1, D5.3, D5.3b, D7.3 or D7.4 completion.

Acceptance criteria

• Exact current fixture identities and mixed module/project order are
  represented by frozen typed DTC state.
• Absent extension data leaves the package default course path unchanged.
• Invalid version, shape, identity, coverage and order fail before mutation
  with bounded code/path/pointer evidence and no source-value leakage.
• The existing schema-1 parser remains the sole legacy parser.
• Normalization writes only to a disposable destination and preserves the
  source checkout.
• Every stable fixture ID survives normalization and generic conversion.
• Standard module/homework bindings plus extra.dtc_flow reconstruct the
  original complete sequence.
• Project slug is preserved and no Project metadata is invented.
• Every source path is classified as unchanged, moved, rewritten or
  intentionally removed; unrelated bytes remain equal.
• Missing or colliding input writes nothing.
• A second complete run produces zero changes and identical path digests.
• Direct unpreprocessed generic conversion still receives C7.12d's refusal.
• Committed tests pass with tracked v0.5.10 and no dependency-file diff.
• Supplemental v0.5.21 proof records exact installed provenance and restores
  pyproject.toml and uv.lock byte-for-byte.
• No model, migration, runtime, route, API, template, static or UI diff is
  present.
• All new source and test files/functions satisfy the coding-standard size
  and control-flow limits without an exception.
• The mapping document keeps runtime integration, storage, migration,
  deployment and live conversion explicitly open.
• The generated verification plan and every required component pass,
  followed by independent Tester PASS and separate PM acceptance.

Focused behavior tests

• test_current_fixture_flow_builds_frozen_typed_state
• test_flow_contract_rejects_shape_identity_and_order_errors
• test_absent_dtc_flow_leaves_default_package_course_unchanged
• test_normalization_plan_preserves_current_fixture_identity_and_bytes
• test_invalid_or_colliding_normalization_writes_nothing
• test_normalized_fixture_passes_v021_converter_parser_and_flow_contract
• test_normalization_and_conversion_are_byte_idempotent
• test_generic_converter_still_refuses_unpreprocessed_nonempty_flow

Assertions must fail when order, identity, file disposition, mutation safety or
package provenance is broken. Do not substitute database rows or copied parser
logic for the real source contracts.

Verification

Run focused tests with the tracked pin:

uv run --frozen pytest content_sync/tests/test_dtc_flow_source.py content_sync/tests/test_dtc_flow_normalization.py -q
uv run --frozen pytest content_sync/tests/test_course_repository.py -q
uv run --frozen python scripts/ci.py lint
uv run --frozen python scripts/ci.py format-check
wc -l content_sync/dtc_flow_source.py content_sync/dtc_flow_normalization.py content_sync/tests/test_dtc_flow_source.py content_sync/tests/test_dtc_flow_normalization.py

Every listed file must report at most 300 lines. Engineer and Tester inspect
the changed functions and record that each is at most 30 lines and that no
forbidden expression was introduced.

Generate and run the maintained plan with the actual current commands:

uv run --frozen python scripts/ci.py verification-plan
uv run --frozen python scripts/ci.py verification-run
uv run --frozen python scripts/ci.py verification-evidence-check
uv run --frozen python scripts/ci.py verification-report-check

The expected impact is backend-only content_sync, with screenshots and
migration evidence not applicable. This is an expectation, not an override;
run every component the plan selects. Do not edit ownership or CI policy to
narrow the plan.

For the supplemental exact-package proof:

1. Record SHA-256 for tracked pyproject.toml and uv.lock.
2. Use scripts/community_base_link.py link --sibling <clean detached v0.5.21 checkout>.
3. Verify installed version/source resolves to tag commit
   bb067c3d4bf66e9bd20d436ccf22d3402667da27.
4. Run the two focused test modules with uv run --no-sync pytest ... -q.
5. Run scripts/community_base_link.py unlink through the linked environment.
6. Rehash dependency files and prove the original bytes and tracked status are
   restored.

The independent Tester uses:

VERIFY_CONSUMER=tester uv run --frozen python scripts/ci.py verification-plan
VERIFY_CONSUMER=tester VERIFY_PRODUCER_ROLE=tester VERIFY_PHASE=tester uv run --frozen python scripts/ci.py verification-run

The Tester independently checks all criteria and the exact v0.5.21 link
restoration. Screenshots and database checks are reported as not applicable.
A separate Product Manager reviews the frozen diff and Tester evidence before
acceptance.

Browser and deployment scenarios

Not applicable. This issue changes no rendered or runtime path. Browser smoke
still runs if selected by the verification plan. No deployment or visible-page
claim is accepted here.

Done when

• The complete source contract and disposable normalization proof pass.
• Tracked-pin and exact v0.5.21 evidence pass with dependency bytes restored.
• Independent Tester and PM gates pass under _docs/PROCESS.md.
• Runtime integration, data adoption, deployment and live source conversion
  remain open for their owning issues.