Portable Content Package and Import/Export Architecture

When the ZIP opens but the meaning does not survive

Imagine a course that is more than a few HTML files: structured lesson nodes, media, a QTI assessment, an external-tool link, localization variants, and rights/provenance references. You ZIP it, the target LMS imports it without an error, and the screen says “Success.” Days later you discover that a MAKNOW-specific block was flattened into plain text, resource IDs were rewritten, part of the assessment capability disappeared, and nobody can prove that the re-exported content preserves the original semantics.

File portability is not semantic portability. In this lesson you will produce MCB Portable Package Manifest, Import/Export Compatibility Matrix and Round-trip Evidence Ledger v1: an auditable contract that separates canonical source from derived rendering, uses a versioned manifest and stable resource identity, binds integrity/rights/provenance evidence, evaluates target capability before import, quarantines unsupported semantics instead of silently flattening them, and proves the export→import→export result with deterministic semantic evidence.

The main lab is synthetic, offline JSON/CSV/Python. It mutates no production LMS or customer data. Recommended active time is 60 minutes. Open the learner lab and keep manifest evidence, target capability, and round-trip evidence separate.

For people designing learning-content platforms, import/export pipelines, or content architecture who need evidence of portability rather than a successful unzip.

This lesson does not implement a production importer, invent a universal standard, mutate a live LMS, or treat an external format as MAKNOW architectural authority.

Lesson boundary and entry evidence

The conceptual prerequisite is MKN-027. Entry evidence is simple: you can separate an artifact from its authority—for example, an HTML file can be a rendering while structured content elsewhere remains the source of truth. If this is fragile, create three columns for one example: canonical source / derived artifact / transport package.

MKN-030 owns auditable package and import/export architecture. It does not own the partial-regeneration outcome of the next lesson or absorb the prior mentor/escalation outcome. A correct result is not always IMPORT; it may be MIGRATE, QUARANTINED, UNKNOWN, REVIEW_REQUIRED, or HOLD.

Foundation route: canonical boundary → manifest/identity → capability matrix → migration/quarantine → round-trip evidence → bounded acceptance. Experienced learners may compress definitions but must retain stable identity, integrity, rights/provenance, typed negative states, and transfer.

Entry probe: name one canonical resource and one derived rendering for a hypothetical lesson, then explain why rendering success does not prove package integrity.

Mental model: portability is a round trip with an identity contract

Use this flow:

canonical structured source → versioned MCB manifest → stable IDs + digests + rights/provenance → adapter/export profile → target capability check → IMPORT / MIGRATE / QUARANTINE / REJECT → isolated import → re-export → deterministic semantic diff → bounded review/acceptance

Do not collapse three boundaries. The canonical boundary identifies source of truth. The transport boundary identifies resources and the manifest/profile that moves them. The target-capability boundary identifies semantics the destination actually understands. A ZIP is only the transport container.

1EdTech Common Cartridge is an open interoperability standard set for digital learning resources and platforms and supports packaging/exchange and import/export of learning materials. The current Common Cartridge page describes 1.4 with LTI 1.3/LTI Advantage and QTI 3. That FACT provides an adapter profile; it does not define MAKNOW's canonical model or prove semantic preservation on every target. Common Cartridge

MKN-030-F1 — Boundary retrieval: state the difference between a movable archive and semantic portability, then name one lesson non-goal.

Minimum data contract: a manifest is more than a file list

1EdTech Content Packaging defines structures for exchange/import/export/aggregation of content packages and describes package structure/resources through a manifest. MCB borrows the packaging idea, while the exact MCB schema and policy remain local MAKNOW design authority. 1EdTech Content Packaging

Group the critical fields into four sets:

1. Package identity: package_id, package_format_version, manifest_version, canonical_content_ref, exporter_version.
2. Resource identity/integrity: resource_id, resource_type, resource_schema_version, resource_path, content_digest, dependency_ref.
3. Rights/provenance/capability: rights_ref, provenance_ref, source_snapshot_ref, target_capability_profile, importer_version, compatibility_state, migration_rule_ref, unsupported_feature_state, quarantine_reason.
4. Round trip/review: round_trip_baseline_digest, round_trip_result_digest, semantic_diff_ref, validation_state, review_owner, audit_event_id.

resource_id is logical identity; a path is only package location. A target may rewrite paths while preserving identity and semantics. Rewriting IDs so localization/evidence references no longer resolve is a different failure. A content_digest is not proof of meaning, but it proves which bytes were evaluated when correctly bound to canonical source and snapshot.

Typed non-success states are part of the contract. UNSUPPORTED means the target lacks a capability. QUARANTINED preserves the payload without pretending to understand it. UNKNOWN means decisive evidence is absent. HOLD blocks the package decision. Removing those states creates false success.

Capability matrix before import, semantic diff after import

Before import, ask three questions for every resource: What is it? What capability does the target have? If direct support is absent, is there an explicit traceable migration rule, or must the resource be quarantined?

The baseline contains a QTI assessment, LTI tool link, media, localization, and a maknow_custom_block. Target A supports Common Cartridge 1.4/QTI 3/LTI 1.3 but not the custom block. The correct response is not “flatten it to text so the import passes.” Without an approved migration rule, keep it QUARANTINED and record why.

QTI enables exchange of item/test content and results between authoring tools, item banks, learning platforms, assessment delivery systems, and scoring/analytics engines. QTI presence supports the profile decision, but a successful QTI import does not by itself prove preservation of every presentation, scoring, accessibility, or extension semantic. QTI Specification Documents

After import, build round-trip evidence: re-export from the isolated target, bind results to stable IDs, compare normalized semantic representations/digests, and classify the diff. A path rewrite can be harmless when stable identity and normalized meaning remain bound. Silent flattening is not harmless even when the file opens.

migration_rule_ref is not a shortcut. Migration must be versioned, explicit, and traceable. Unsupported resource plus missing rule means QUARANTINE/HOLD, not guessed migration.

MKN-030-F2 — Negative-case diagnosis: if assessment-qti-01 is removed while lesson-core still declares a dependency on it, which evidence dimension fails and what is the smallest repair?

Worked example 1: baseline with one unsupported block

fixtures/baseline.json contains six resources: core lesson, media, QTI assessment, LTI link, Persian localization, and a custom block. The manifest binds stable ID, path, digest, rights, and provenance for each. Target A supports core/media/QTI3/LTI1.3/localization but not the custom block.

The first five resources are IMPORT_COMPATIBLE. The custom block is QUARANTINED rather than flattened and its payload remains available for review. Dependencies are complete, digests match, and imported resources preserve normalized round-trip semantics. Because one semantic capability remains quarantined and an owner must decide retention/migration, the package verdict is REVIEW_REQUIRED, not FULL_IMPORT_SUCCESS.

The machine-readable table is derived_text/tables/MKN-030-T1.csv.

Worked example 2: changed content with an old digest

In stale_digest.json, canonical bytes changed while the manifest still carries the old digest. The importer may open the file; that is irrelevant. Integrity binding is broken and the verdict is HOLD. Minimal repair: freeze the correct source snapshot, recompute the digest, version the manifest, and rebuild round-trip evidence—not disable the digest check.

Common failure modes

ZIP-success fallacy. Archive extraction and a zero exit code become proof of portability. Repair: capability matrix plus semantic round trip.

Silent flattening. Unsupported content is converted to generic text/HTML without recording semantic loss. Repair: keep the unsupported state typed and quarantine it unless an approved migration rule exists.

Dangling dependency. A required resource is removed while manifest/reference dependencies remain. Repair: validate dependency closure before import.

Stable-ID rewrite. Import creates new IDs and evidence/localization links no longer resolve. Repair: preserve identity or use an explicit mapping rule; silent identity rewrite is blocking.

Digest theater. A digest is calculated over the wrong file, stale snapshot, or derived rendering. Repair: bind digest to canonical ref and source snapshot.

Rights/provenance omission. Technical compatibility exists but permission/origin evidence is absent. Repair: keep evidence UNKNOWN and package decision HOLD; compatibility does not create rights.

Round-trip byte equality as semantics. Or the reverse: harmless transport differences are treated as semantic drift. Repair: separate normalized semantic representation from ZIP/path/timestamp noise.

Experienced bridge: treat the package as a protocol boundary

If you know API versioning, database migration, or compiler IR, use that analogy. The canonical content model resembles a domain model/IR; Common Cartridge/QTI are wire-format adapters; target capability resembles protocol negotiation; quarantine preserves an unknown payload without pretending support.

The analogy is incomplete because learning content has educational semantics. A parser can succeed while accessibility, scoring, instructional relationship, or reviewed human intent changes. Schema validation therefore cannot replace semantic diff and review.

For the fast path, compress definitions and defend the three artifacts directly: manifest, compatibility matrix, round-trip ledger. Still explain the trade-off: stable identity and explicit negative states cost modeling effort but reduce silent interoperability claims.

Alternatives and trade-offs

Canonical = Common Cartridge. Simple at first, but it couples internal meaning to the limits of one export profile. Here MCB stays canonical and CC/QTI remain adapters.

Export-only interoperability. Cheap and useful, but without a target round trip it cannot expose silent loss.

Lossy migration by default. Raises apparent import rate while weakening auditability and learning meaning. Quarantine is stricter but makes loss visible.

Hash everything, review nothing. Strong integrity, weak semantic assurance. Digest, schema, and review are complementary.

Platform-specific canonical. Speeds early delivery but increases portability and exit cost. This lesson does not require a universal abstraction; it requires an explicit authority boundary and adapter mapping.

Guided and independent practice

Guided practice

1. Open fixtures/baseline.json; record package_id, manifest version, and canonical ref.
2. Check digest, dependency, rights, and provenance for each resource.
3. Compare each required_capability with target capabilities.
4. Keep the custom block QUARANTINED when no migration rule exists.
5. Inspect normalized round-trip semantic digests for imported resources.
6. Fill evidence/decision.template.json and run:

python run_checks.py fixtures/baseline.json evidence/submission.baseline.json

The checker verifies deterministic structure and invariants; it does not certify the quality of your rationale.

Independent practice

Analyze transfer/transfer_fixture.json, whose target uses an older profile and rewrites paths. Do not copy the baseline verdict. Rebuild capability compatibility from the new target; separate path rewrite from identity rewrite; migrate/quarantine only with explicit rule evidence; recompute round-trip semantic evidence.

MKN-030-F3 — Transfer: explain why path rewriting is not necessarily a portability failure while resource-ID rewriting without a mapping rule can be.

What belongs in an acceptable evidence package?

At minimum: package/profile versions, canonical ref, stable resource IDs, schema versions, paths, content digests, dependencies, rights/provenance, exporter/importer versions, target capability profile, compatibility/migration/quarantine states, round-trip baseline/result digest, semantic diff, validation state, review owner, and audit event.

Producer tests independently cover missing dependency, stale digest, silent flattening, rewritten ID, missing evidence, and migration without a rule. Learners receive visible rules and fixtures; the producer evaluator is not published under the learner path.

Fail closed. Missing decisive evidence must not become a positive state. UNKNOWN at an evidence dimension and HOLD at package decision are better than fabricated confidence. QUARANTINED is also not a system failure; it is an honest state for unsupported semantics.

The round-trip ledger should separate transport noise from semantic change. ZIP timestamp or path difference alone is insufficient; stable ID, normalized semantic digest, and mapping evidence determine whether meaning remains traceable.

Summative assessment and transfer

The four summative prompts are in derived_text/assessment/questions.json:

• S1 — Retrieval: explain the Portable Content Package boundary and one non-goal.
• S2 — Application: construct the complete baseline evidence artifact.
• S3 — Diagnosis: diagnose a missing required resource with a remaining manifest dependency.
• S4 — Transfer: independently analyze the older target with path rewriting and recompute compatibility/migration/quarantine/round-trip state.

Five rubric dimensions are critical: identity/contract, exact evidence binding, negative evidence, bounded decision, and transfer. Failure in any is blocking. Strong answers record evidence pointer, state, consequence, and minimal repair—not just a verdict.

Baseline-independence test: hide the REVIEW_REQUIRED label from the worked example. You must still derive the transfer result from the changed fixture and visible rules. “The previous example said so” is not transfer reasoning.

References, claim boundaries, and freshness

Three official sources support the FACT layer:

1. 1EdTech Common Cartridge — interoperability and package/import/export; not MAKNOW canonical authority or proof that every LMS preserves all semantics.
2. 1EdTech Content Packaging — package structure and manifest/resource transport; not proof of semantic equivalence.
3. QTI Specification Documents — interchange of assessment item/test content/results; not a guarantee that every target preserves all extensions or behavior.

These sources were rechecked on 2026-09-13. The current Common Cartridge page describes 1.4 with LTI 1.3/LTI Advantage and QTI 3, while the QTI specification page presents QTI 3 resources. Practice-evolving claims must be requalified by 2027-01-15, or earlier on a material profile/spec change. An accepted lesson is not silently rewritten; updates are versioned.

Closing question: which shortcut in your current pipeline creates the most false confidence—ZIP success, silent flattening, weak digest binding, ID rewrite, or incomplete round trip—and which exact field exposes it?