Structured Content Authoring and Partial Regeneration

When changing one paragraph rewrites the whole lesson

Imagine a reviewed lesson in which one explanation is stale because an external source changed. The assessment, an owner note, translated examples, and a manually refined diagram are still valid. A request to “update this explanation” must not silently become permission to rewrite the document. Whole-document regeneration can erase reviewed human edits, change stable identities, rebuild translations from the wrong base, or hide collateral drift inside fluent prose.

Your output in this lesson is Structured Content Node Graph, Regeneration Patch Plan and Deterministic Diff/Promotion Ledger v1. Instead of treating the lesson as one blob, you pin a canonical revision, declare exact targets and protected zones, compute dependency impact before generation, produce a candidate patch, and measure what changed before promotion.

The lab is offline and synthetic, using JSON/CSV/Python only. It does not mutate production content, a live LMS, or customer data. Plan about 60 active minutes. Open the lab package and record the base revision and digest before making any decision.

For readers who understand structured content and AI-assisted authoring and need regeneration to be bounded and auditable.

This lesson does not build a live publisher, LMS importer, or general text-generation model and does not grant automatic authority to mutate canonical content.

Lesson boundary and entry evidence

The conceptual prerequisite is MKN-030. You only need to distinguish canonical content, a derived artifact, and a portable/distributed representation. If that boundary is fragile, write down one example of each—source text, a translation derived from it, and a delivered package—then continue.

MKN-031 owns bounded regeneration of structured nodes. It does not own final publication, LMS import, or the entire content factory. A correct result may be REVIEW_REQUIRED or HOLD. The objective is not to force every candidate into promotion; it is to make promotion or rejection reproducible from visible evidence.

Foundation route: mental model → field contract → baseline example → failures → guided practice → independent transfer. Experienced readers may compress definitions, but not base pinning, protected zones, dependency impact, provenance, or transfer.

Entry evidence: name one canonical node and one derived artifact, and explain why changing the derived artifact does not automatically authorize a canonical edit.

Mental model: regeneration is a bounded transaction

Use this ordered model:

canonical structured revision → target + protected zones → dependency impact → pinned source/evidence snapshot → candidate generation → bounded patch + preconditions → structural/semantic diff → rebuild affected derived artifacts → REVIEW / HOLD / PROMOTE → audit + rollback

Three principles carry most of the reasoning. Identity: every node has a stable node_id; reusing the same ID for a different semantic role is not an edit. Concurrency: a candidate must bind to the exact base revision and digest from which it was generated; if canonical state moves, the candidate is stale. Blast radius: the target is not “whatever the model thinks is nearby.” Dependency analysis may enlarge the set of derived artifacts to rebuild, but it does not grant permission to mutate protected canonical nodes.

RFC 6902 defines JSON Patch as an ordered sequence of operations and includes test, which can serve as a precondition. We use that mechanism to fail closed on the wrong base. The RFC does not decide which learning nodes are eligible for regeneration or who may promote the result. RFC 6902

MKN-031-F1 — Retrieve the boundary: Write three differences between whole-document rewriting and bounded partial regeneration, then name one out-of-scope activity.

Minimum data contract

JSON Schema Draft 2020-12 provides a current dialect for describing and validating JSON structure, references, and vocabularies. Structural validity is useful, but it does not establish semantic correctness or MAKNOW regeneration authority. JSON Schema 2020-12

The lesson contract groups fields into four families:

1. Identity and base: content_id, schema_version, node_id, node_type, base_revision_id, base_digest.
2. Request and scope: regeneration_request_id, target_node_ids, protected_node_ids, generation_policy_version.
3. Evidence and impact: source_snapshot_ref, evidence_snapshot_ref, dependency_graph_ref, affected_derived_artifacts, precondition_test, structural_validation_state, semantic_diff_ref, claim_diff_state, source_diff_state, localization_impact_state, assessment_impact_state, human_edit_preservation_state.
4. Decision and audit: candidate_revision_id, candidate_patch_ref, provenance_activity_ref, generator_ref, review_state, promotion_state, rollback_ref, audit_event_id.

Do not erase non-success states. STALE_BASE means the candidate no longer binds to current canonical state. UNKNOWN means decisive evidence is unavailable. UNSUPPORTED means the contract does not support the case. REVIEW_REQUIRED means a consequential decision remains. HOLD blocks promotion. PARTIAL can represent incomplete impact evidence.

Stable identity is semantic, not merely syntactic. If node-expl-01 represented a caching explanation yesterday and is reused today for an assessment rationale, the ID has been repurposed; the audit trail can no longer treat it as the same node.

Target, protected zone, and dependency graph are different contracts

target_node_ids names canonical nodes that may receive candidate content. protected_node_ids names canonical nodes that must not change even if they are adjacent. The dependency graph answers a different question: which derived artifacts become invalid when a target changes?

If explanation-01 is the target and a Persian translation plus slide 3 depend on it, dependency analysis can mark those two artifacts for rebuild. That does not authorize a change to assessment-01. If the assessment is semantically affected, the impact state must expose that risk and scope can expand only under explicit evidence and policy.

A precondition is more than a decorative hash. The candidate binds to base_revision_id and base_digest. If canonical content moves from rev-17 to rev-18, a patch generated for rev-17 must not apply to rev-18, even if the path still exists. STALE_BASE → HOLD prevents a quiet overwrite.

Provenance answers which entities and activities produced the candidate and which generator/policy participated. W3C PROV provides a general model around entities, activities, and agents; MAKNOW policy determines what provenance is sufficient for promotion. W3C PROV Overview

MKN-031-F2 — Diagnose negative evidence: If a candidate changes a protected owner note, which fields become invalid and what is the smallest safe repair? “Generate again” alone is not sufficient.

Worked example 1: one stale explanation, two dependent artifacts

In baseline.json, revision rev-17 contains four canonical nodes. Only node-expl-01 is stale. node-assess-01, node-owner-01, and node-diagram-01 are protected. The dependency graph shows that derived-fa-expl-01 and derived-slide-03 depend on the explanation.

The candidate patch first tests revision and digest, then replaces only the target body. It records the same source/evidence snapshot and a dedicated provenance activity. Structural validation passes, protected digests are unchanged, and the affected-derived set exactly matches dependency impact. Because claim wording changed, claim_diff_state=CHANGED_REVIEW_REQUIRED. The bounded verdict is therefore REVIEW_REQUIRED with promotion HOLD_PENDING_REVIEW, not PROMOTE.

The full working table is derived_text/tables/MKN-031-T1.csv; field_map.json documents how its columns map to fixture evidence.

Worked example 2: canonical base changes after generation

In stale_base.json, the candidate still states that it was generated from rev-17, while current canonical state is rev-18. Fluent output does not rescue the candidate; the precondition fails. The minimal repair is not deleting test. Regenerate from the new base, recompute dependency impact, and create new provenance and diff evidence. The previous verdict is not an oracle.

Common failure modes

Rewriting a neighbor for fluency. The generator treats the target as permission to touch surrounding canonical nodes. Repair: changed canonical nodes must be a subset of targets; touching protected content is a blocker.

Hiding a stale base. A candidate is kept on an older base because the diff is smaller. Repair: revision+digest preconditions and fail-closed application.

Stable ID, different meaning. The same node_id is reused for another role. Repair: enforce identity invariants and perform an explicit identity migration when needed.

Incomplete rebuild. The target changes, but a dependent translation or slide is not rebuilt. Repair: compare computed dependency closure with affected_derived_artifacts; a missing artifact produces HOLD.

Structural PASS treated as semantic PASS. A valid schema becomes promotion evidence. Repair: structural validation is one gate; claim/source/assessment/localization impacts remain separate.

Decorative provenance. Only the model name is stored, while the base, source, evidence, or policy snapshot is absent. Repair: bind the generation activity to all decisive inputs.

Experienced bridge: think controlled merge, not magic rewrite

If you know version control, optimistic concurrency, or event-sourced systems, compare this contract to a base commit, conflict detection, and derived-build invalidation. The analogy is useful but incomplete: Git cannot tell you whether a learning node preserved its educational meaning or whether a consequential claim change is acceptable.

For speed, keep the field dictionary and compress introductory definitions. Then defend two trade-offs: why whole-document regeneration is risky in a review-heavy workflow, and why over-protection can also block necessary change. Wide scope increases collateral drift; overly narrow scope can miss real dependencies.

A production system may use JSON Patch, domain operations, or an internal transaction engine. This lesson does not lock the implementation syntax. It locks the invariants: pinned base, explicit scope, stable identity, visible impact, governed promotion.

Alternatives and trade-offs

Whole-document regeneration has simple orchestration but expensive preservation and review. It can be reasonable for disposable documents under full rereview; this lesson does not assume that condition.

Text-range patching by offset or line is quick but fragile under movement and gives weak semantic identity. Stable node IDs cost more modeling effort but make diff and dependency tracking more resilient.

Manual editing only reduces model-driven drift but does not eliminate the need for versioning, evidence, and provenance. Partial regeneration is not about removing humans; it is about shrinking the change surface and making accountability explicit.

Semantic similarity scores may be advisory but are not sufficient promotion gates. A high score does not prove that a protected owner edit survived or that the correct source snapshot was used. The lesson intentionally keeps evidence dimensions separate instead of inventing a single weighted score.

Guided and independent practice

Guided practice

1. Open fixtures/baseline.json and extract base revision/digest, targets, and protected set.
2. Traverse the dependency graph from the target and list affected derived artifacts.
3. Inspect the patch and confirm that revision/digest test operations precede replace.
4. Fill evidence/decision.template.json with states, evidence refs, rationale, and minimal repair.
5. Run:

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

The checker validates structure, binding, and deterministic invariants. It does not certify the quality of your rationale.

Independent practice

Analyze transfer/transfer_fixture.json without using the baseline verdict. The new target is an assessment rationale; the dependency graph shows that a translation and slide become invalid. Expand the affected set only where evidence requires it. If the base is stale or a protected node changes, choose HOLD.

MKN-031-F3 — Transfer: Build the transfer decision from scratch and explain why copying the baseline result would be invalid.

What belongs in an acceptable evidence package?

An auditable decision exposes canonical identity and schema version; base revision/digest; source and evidence snapshots; request ID; target/protected sets; dependency graph; candidate revision and patch; precondition result; structural state; semantic/claim/source/localization/assessment impact; preservation state; provenance activity and generator/policy; review/promotion state; rollback ref; and audit event.

The producer's reference_evaluator.py lives under internal verification and is not learner-publishable. Learners must derive the result from visible fixtures and rules. Producer tests cover baseline, stale base, protected-node mutation, missing decisive evidence, reused node identity, and missed dependent rebuild.

Fail closed: missing or malformed decisive evidence does not become success. UNKNOWN/PARTIAL at the evidence dimension and HOLD at promotion are preferable to fabricated certainty.

Rollback is also evidence. rollback_ref must identify a valid immutable prior revision, and the audit event must record which candidate was promoted or rejected and why.

Summative assessment and transfer

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

• S1 — Retrieval: explain the boundary of partial regeneration and one non-goal.
• S2 — Application: construct the complete baseline artifact and bind all critical dimensions.
• S3 — Diagnosis: diagnose the stale-base mutation, consequence, and minimal repair.
• S4 — Transfer: analyze the new assessment-rationale request and independently recompute dependency impact.

Five rubric dimensions are critical: identity/contract, exact evidence binding, negative evidence, bounded decision, and transfer. Failure in any is blocking. A strong answer gives evidence pointers, state, consequence, and future review trigger—not merely a verdict.

Independence test: if the worked-example verdict label is hidden, you should still reconstruct the boundary from fixture values and rules. “Because the previous example was REVIEW_REQUIRED” is not transfer reasoning.

References, claim boundaries, and freshness

Three external sources support the factual layer:

1. JSON Schema Specification — JSON structure and validation; not regeneration authority or semantic correctness.
2. RFC 6902 — JSON Patch — ordered partial modification and test preconditions; not learning-node eligibility or promotion authority.
3. W3C PROV Overview — a general provenance model; review and promotion thresholds here remain local design choices.

The sources were rechecked on 2026-09-13. The frozen Bible calls for review of practice-evolving claims around early 2027, with a local trigger no later than 2027-01-15 or earlier if a cited specification materially changes. A frozen lesson is not silently rewritten on source change; requalification is versioned.

Closing question: which shortcut in your workflow is most likely to create false confidence—whole rewrite, stale base, hidden dependency, or weak provenance—and which exact evidence field would expose it?