Files

525 lines
34 KiB
Python

#!/usr/bin/env python3
"""Validate reviewed figure lessons and compile deterministic web registries.
The default mechanism mode uses mechanisms/selection.json and strict author chunks.
No manuscript changes unless --enroll is explicitly supplied. Unselected figures
remain static. Run --require-complete for release coverage checks. The explicit
--legacy mode is archival and uses the pre-mechanism lesson inventory.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import re
import subprocess
from pathlib import Path
from collections import Counter
import xml.etree.ElementTree as ET
ROOT = Path(__file__).resolve().parents[3]
EXT = ROOT / 'books/_extensions/mlsysbook-ext/figure-explore'
CATALOG = ROOT / 'books/_prototypes/vol1-web-animations/animation-catalog/catalog.json'
ATTR = re.compile(r'\s+data-explore(?:-key)?="[^"]*"')
def normalized_source(text):
return ATTR.sub('', text)
def sha1(data):
return hashlib.sha1(data).hexdigest()
def structural_svg(data):
"""Ignore metadata and generated identifiers, retain geometry and labels."""
text = data.decode('utf-8')
text = re.sub(r'<metadata\b[^>]*>[\s\S]*?</metadata\s*>', '', text)
identifiers = {}
def replace_id(match):
original = match.group(2)
identifiers.setdefault(original, f'id{len(identifiers)}')
return 'id=' + match.group(1) + identifiers[original] + match.group(1)
text = re.sub(r'\bid=(["\'])([^"\']+)\1', replace_id, text)
text = re.sub(r'#([A-Za-z_][\w:.-]*)', lambda match: '#'+identifiers.get(match.group(1), match.group(1)), text)
return sha1(text.encode('utf-8'))
def validate(row, original):
key = row['key']
for field in ('figure_id', 'source'):
if row.get(field) != original[field]:
raise ValueError(f'{key}: {field} does not match catalog')
if row.get('status') not in ('ready', 'static', 'specialized', 'blocked'):
raise ValueError(f'{key}: invalid status')
if row['status'] != 'ready':
return
if row.get('artwork_reviewed') is not True:
raise ValueError(f'{key}: ready without artwork review')
if not row.get('script'):
raise ValueError(f'{key}: highlight-only tours are archived; ready lessons require a stateful implementation')
for field in ('name', 'script', 'stylesheet'):
if not row.get(field):
raise ValueError(f'{key}: missing {field}')
def figure_match(text, figure):
# Match only the wrapper's opening identifier. Captions may contain quoted
# braces (LaTeX, inline Python); a closing-brace regex is not an attribute parser.
matches = list(re.finditer(r'^:{3,}\s*\{#' + re.escape(figure) + r'(?=[\s}])', text, re.M))
if len(matches) != 1:
raise ValueError(f'{figure}: expected one exact figure wrapper, found {len(matches)}')
return matches[0]
def enrollment_attributes(text, figure):
match = figure_match(text, figure)
# Enrollment always sits immediately after the ID, before original attributes.
return re.match(r'(?:\s+data-explore(?:-key)?="[^"]*")*', text[match.end():]).group()
def compile_registry(args):
catalog = {r['key']: r for r in json.loads(CATALOG.read_text())['figures']}
artwork = json.loads(Path(args.art_index).read_text())
rows = {}
invalid = []
for path in sorted((EXT / 'lessons').glob('vol*-*.json')):
for row in json.loads(path.read_text()):
key = row['key']
if key not in catalog or key in rows:
raise ValueError(f'{path.name}: unknown or duplicate key {key}')
try:
validate(row, catalog[key])
except ValueError as error:
if args.require_complete:
raise
invalid.append({'key': key, 'file': path.name, 'error': str(error)})
continue
rows[key] = row
for path in sorted((EXT / 'lessons').glob('specialized-vol*.json')):
for row in json.loads(path.read_text()):
key = row['key']
if key not in catalog:
raise ValueError(f'{path.name}: unknown key {key}')
if key in rows and rows[key]['status'] != 'specialized':
raise ValueError(f'{key}: specialized replacement not reserved')
validate(row, catalog[key])
rows[key] = row
for key, name, script in [('vol1:fig-tensor-memory-layout', 'tensor-memory-layout', 'tensor-memory-layout'), ('vol1:fig-tiling-diagram', 'matrix-tiling', 'matrix-tiling')]:
rows[key] = {**catalog[key], 'status': 'ready', 'artwork_reviewed': True, 'name': name, 'script': script+'.js', 'stylesheet': script+'.css'}
missing = sorted(set(catalog) - set(rows))
unresolved = sorted(k for k, r in rows.items() if r['status'] == 'specialized')
if args.require_complete and (missing or unresolved):
raise ValueError(f'Incomplete coverage: missing={missing}, unresolved specialized={unresolved}')
registry, volumes, source_cache = {}, {n: {} for n in range(1,5)}, {}
for key, row in sorted(rows.items()):
if row['status'] != 'ready':
continue
original = catalog[key]
source = original['source']
path = ROOT / source
text = source_cache.setdefault(source, path.read_text())
figure_match(text, original['figure_id'])
art = artwork.get(key)
if not art or not Path(art.get('asset', '')).is_file():
raise ValueError(f'{key}: canonical art missing')
asset = Path(art['asset'])
raw = asset.read_bytes()
from PIL import Image
with Image.open(art['image']) as im:
width, height = im.size
specialized = bool(row.get('script'))
entry = dict(name=row['name'] if specialized else 'guided-figure', script=row['script'] if specialized else 'guided-figure.js', stylesheet=row['stylesheet'] if specialized else 'guided-figure.css', source=source, source_sha1=sha1(normalized_source(text).encode()), figure_id=original['figure_id'], volume=original['volume'], art_sha1=sha1(raw), art_kind=asset.suffix.lstrip('.').lower(), art_width=width, art_height=height)
if asset.suffix.lower() == '.svg':
entry['art_structural_sha1'] = structural_svg(raw)
for name in ('script', 'stylesheet'):
if specialized and not (EXT / entry[name]).is_file():
raise ValueError(f'{key}: missing {entry[name]}')
registry[key] = entry
if not specialized:
lesson = {k: v for k, v in row.items() if k not in ('review_notes',)}
lesson.update({k: v for k,v in entry.items() if k.startswith('art_')})
volumes[original['volume']][key] = lesson
outputs = {EXT/'figure-registry.json': json.dumps(registry, indent=2, ensure_ascii=False)+'\n'}
for volume, lessons in volumes.items():
outputs[EXT/f'guided-lessons-vol{volume}.js'] = '// Generated by compile_figure_explore.py; edit lessons/*.json.\nwindow.MLSysGuidedLessons = window.MLSysGuidedLessons || {};\nObject.assign(window.MLSysGuidedLessons, '+json.dumps(lessons, ensure_ascii=False, separators=(',', ':'))+');\n'
if args.enroll or args.check:
for original in catalog.values():
source = original['source']
source_cache.setdefault(source, (ROOT/source).read_text())
if args.enroll:
for source, text in source_cache.items():
updated = normalized_source(text)
for key, original in catalog.items():
if original['source'] != source:
continue
match = figure_match(updated, original['figure_id'])
wrapper = match.group()
if key in registry:
entry = registry[key]
wrapper += f' data-explore="{entry["name"]}" data-explore-key="{key}"'
updated = updated[:match.start()]+wrapper+updated[match.end():]
if normalized_source(updated) != normalized_source(text):
raise AssertionError(f'{source}: enrollment changed static content')
if updated != text:
(ROOT/source).write_text(updated)
for path, content in outputs.items():
if args.check:
if not path.is_file() or path.read_text() != content:
raise ValueError(f'Outdated generated output: {path.relative_to(ROOT)}')
else:
path.write_text(content)
if args.check:
for key, original in catalog.items():
wrapper = enrollment_attributes((ROOT/original['source']).read_text(), original['figure_id'])
if key in registry:
entry = registry[key]
if f'data-explore="{entry["name"]}"' not in wrapper or f'data-explore-key="{key}"' not in wrapper:
raise ValueError(f'{key}: missing or wrong enrollment')
elif ATTR.search(wrapper):
raise ValueError(f'{key}: unready figure has stale enrollment')
report = {'invalid': invalid, 'catalog_total': len(catalog), 'registered': len(registry), 'status_counts': dict(Counter(r['status'] for r in rows.values())), 'missing': missing, 'unresolved_specialized': unresolved, 'blocked': [k for k,r in rows.items() if r['status']=='blocked'], 'static': [k for k,r in rows.items() if r['status']=='static'], 'by_volume': dict(Counter(str(v['volume']) for v in registry.values()))}
Path(args.report).write_text(json.dumps(report, indent=2)+'\n')
print(json.dumps(report, indent=2))
def source_revision(metadata):
"""Preserve recorded provenance across commits; content hashes govern freshness."""
recorded=metadata.get('source_head')
if isinstance(recorded,str) and recorded.strip():
return recorded
return subprocess.check_output(['git','rev-parse','HEAD'],cwd=ROOT,text=True).strip()
def bind_current_build(catalog_data, registry, outputs, build_root, native_keys=()):
"""Bind only exact, complete clean-build evidence; never confer visual approval."""
import os
from bs4 import BeautifulSoup
from validate_mechanism_lessons import strict_json, require
for row in catalog_data['figures']:
row['chapter_url']=''
row['built_explore_present']=False
metadata=catalog_data['metadata']
metadata['build_root']=None
metadata['build_markers_verified']=0
metadata['build_route_count']=0
if not build_root:
return
build=Path(build_root)
if not build.is_absolute(): build=ROOT/build
build=build.resolve()
summary=strict_json(build/'summary.json')
for volume in range(1,5):
require(any(j.get('volume')==f'vol{volume}' and j.get('format')=='html' and j.get('chapter') is None and j.get('ok') is True for j in summary.get('jobs',[])),f'{build}: missing successful full vol{volume} HTML job')
output=build/f'vol{volume}-html/output'
assets = {'figure-explore.js', 'figure-views.js', 'figure-views.css'}
for entry in registry.values():
if entry['volume'] != volume:
continue
assets.update(entry[field] for field in ('script', 'stylesheet', 'bundle') if entry.get(field))
if entry.get('shared_player'):
assets.update(('original-player.js', 'original-player.css'))
for name in sorted(assets):
matches=list(output.rglob(name))
require(len(matches)==1,f'{build}: expected exactly one emitted {name}')
expected=outputs[EXT/name].encode('utf-8') if EXT/name in outputs else (EXT/name).read_bytes()
require(matches[0].read_bytes()==expected,f'{build}: stale emitted {name}')
chapters={}
for row in catalog_data['figures']:
chapter=build/f"vol{row['volume']}-html/output"/Path(row['source']).relative_to('books').with_suffix('.html')
if chapter not in chapters:
chapters[chapter]=BeautifulSoup(chapter.read_text(),'html.parser') if chapter.is_file() else None
soup=chapters[chapter]
node=soup.find(id=row['figure_id']) if soup else None
entry=registry.get(row['key'])
if entry:
require(node is not None,f"{row['key']}: figure absent from configured build")
expected={'data-mlsys-explore':entry['name'],'data-mlsys-explore-key':row['key'],'data-mlsys-art-sha1':entry.get('art_structural_sha1',entry['art_sha1']),'data-mlsys-art-kind':entry['art_kind']}
if entry.get('lesson_sha1'):
expected['data-mlsys-lesson-sha1']=entry['lesson_sha1']
require(all(node.get(k)==v for k,v in expected.items()),f"{row['key']}: missing/stale built mechanism freshness marker")
row['built_explore_present']=True
row['runtime_verification']=('Native original-art factory source/art/runtime freshness, clean four-volume HTML assets and enrollment markers verified; actual themed chapter behavior review remains separate.' if row['key'] in native_keys else 'Schema, declared invariants, companion calculations, clean four-volume HTML assets and freshness markers verified; actual themed chapter behavior review remains separate.')
if node is not None:
row['chapter_url']=os.path.relpath(chapter,CATALOG.parent)+'#'+row['figure_id']
metadata['build_root']=os.path.relpath(build,ROOT)
metadata['build_markers_verified']=sum(r['built_explore_present'] for r in catalog_data['figures'])
metadata['build_route_count']=sum(bool(r['chapter_url']) for r in catalog_data['figures'])
def apply_review_record(catalog_data, registry, lessons, outputs, build_root, review_path):
"""Apply explicit, hash-bound implementation acceptance; never infer approval."""
from validate_mechanism_lessons import strict_json, require, fields, array, string
for row in catalog_data['figures']:
row.pop('review_scope',None)
metadata=catalog_data['metadata']
metadata.pop('review_record',None)
if not review_path:
return
require(build_root,'--review-record requires --build-root')
build=Path(build_root)
if not build.is_absolute(): build=ROOT/build
build=build.resolve()
path=Path(review_path)
if not path.is_absolute(): path=ROOT/path
record=strict_json(path)
fields(record,'schema build_root registry_sha256 build_summary_sha256 lessons')
for name in ('build_root','registry_sha256','build_summary_sha256'): string(record[name],True)
require(type(record['schema']) is int and record['schema']==1,'unsupported review-record schema')
bound=Path(record['build_root'])
if not bound.is_absolute(): bound=ROOT/bound
require(bound.resolve()==build,'review record build root differs from configured build')
digest=lambda data:hashlib.sha256(data).hexdigest()
require(record['registry_sha256']==digest(outputs[EXT/'figure-registry.json'].encode('utf-8')),'review registry hash mismatch')
require(record['build_summary_sha256']==digest((build/'summary.json').read_bytes()),'review build summary hash mismatch')
require(isinstance(record['lessons'],dict) and record['lessons'],'review record needs explicit lesson acceptance')
by_key={row['key']:row for row in catalog_data['figures']}
evidence_dir=(CATALOG.parent/'evidence').resolve()
for key,review in record['lessons'].items():
require(key in registry,f'{key}: review names unregistered lesson')
fields(review,'verdict coverage evidence reviewer_type limitations')
require(review['verdict']=='accepted',f'{key}: unsupported review verdict')
string(review['reviewer_type'],True); string(review['limitations'],True)
coverage=review['coverage']; fields(coverage,'cases profiles endpoints motion controls')
array(coverage['cases'],1); array(coverage['profiles'],1)
case_ids={'base'}|{v['id'] for v in lessons.get(key,{}).get('variants',[])}
require(len(set(coverage['cases']))==len(coverage['cases']) and set(coverage['cases'])<=case_ids,f'{key}: unknown/duplicate reviewed case')
profile_ids={'desktop-light','desktop-dark','narrow-light','narrow-dark'}
require(len(set(coverage['profiles']))==len(coverage['profiles']) and set(coverage['profiles'])<=profile_ids,f'{key}: unknown/duplicate reviewed profile')
for name in ('endpoints','motion','controls'): string(coverage[name],True)
array(review['evidence'],1)
for evidence in review['evidence']:
fields(evidence,'path sha256'); string(evidence['path'],True); string(evidence['sha256'],True)
require(not Path(evidence['path']).is_absolute(),f'{key}: evidence path must be repository-relative')
report=(ROOT/evidence['path']).resolve()
require(report.is_relative_to(evidence_dir) and report.is_file(),f'{key}: evidence must be an existing public catalog/evidence report')
require(evidence['sha256']==digest(report.read_bytes()),f'{key}: review evidence hash mismatch')
row=by_key[key]
row['status']=row['actual_status']='implementation-review-passed'
row['review_scope']=review
row['actual_review_basis']='Explicit hash-bound implementation acceptance, limited to the recorded cases, profiles, evidence, and reviewer limitations.'
row['visual_verification']='Hash-bound implementation acceptance for cases '+', '.join(coverage['cases'])+'; profiles '+', '.join(coverage['profiles'])+'. Endpoints: '+coverage['endpoints']+' Motion: '+coverage['motion']+' Controls: '+coverage['controls']+' Reviewer: '+review['reviewer_type']+'. Limits: '+review['limitations']
metadata['review_record']={'path':str(path.relative_to(ROOT)) if path.is_relative_to(ROOT) else path.name,'sha256':digest(path.read_bytes()),'accepted_keys':sorted(record['lessons'])}
metadata['actual_statuses']=dict(Counter(row['actual_status'] for row in catalog_data['figures']))
metadata['review_limit']='Recorded implementation acceptance is limited to the declared cases, profiles, and evidence. Selected entries without acceptance remain pending; static figures retain their static treatment. Simulated reviews are not student testing and establish no learning gains.'
def apply_implementations(registry, manifests=None):
"""Replace selected implementations, preserving every other compiled record.
Explicit production factories retain the canonical source/artwork provenance
of their selected figure. Their own runtime/data hashes replace the generic
scene's bundle identity; an unknown or stale manifest fails the whole build.
"""
path = EXT/'mechanisms/implementations.json'
implementations = json.loads(path.read_text()) if manifests is None and path.exists() else (manifests or {})
for key, implementation in implementations.items():
if key not in registry:
raise ValueError(f'{key}: implementation must replace a selected compiled mechanism')
if set(implementation)-{'name','script','stylesheet','bundle','scope','question','shared_player'}:
raise ValueError(f'{key}: unknown implementation manifest field')
for field in ('name','script','stylesheet'):
value=implementation.get(field)
if not isinstance(value,str) or not value or '/' in value or '\\' in value:
raise ValueError(f'{key}: invalid implementation {field}')
assets=[]
for field in ('script','stylesheet','bundle'):
value=implementation.get(field)
if value is None: continue
if not isinstance(value,str) or '/' in value or '\\' in value or not (EXT/value).is_file():
raise ValueError(f'{key}: missing/invalid implementation {field}')
assets.append((EXT/value).read_bytes())
if 'shared_player' in implementation and type(implementation['shared_player']) is not bool:
raise ValueError(f'{key}: shared_player must be boolean')
if implementation.get('shared_player'):
for filename in ('original-player.js','original-player.css'):
if not (EXT/filename).is_file(): raise ValueError(f'{key}: missing shared player asset {filename}')
assets.append((EXT/filename).read_bytes())
entry=dict(registry[key])
for field in ('bundle','bundle_sha1','lesson_sha1','runtime_sha1'): entry.pop(field,None)
entry.update({field:implementation[field] for field in ('name','script','stylesheet')})
entry['runtime_sha1']=sha1(b'\x00'.join(assets))
if implementation.get('shared_player'): entry['shared_player']=True
else: entry.pop('shared_player',None)
if implementation.get('bundle'):
entry['bundle']=implementation['bundle']
entry['bundle_sha1']=sha1((EXT/entry['bundle']).read_bytes())
entry['lesson_sha1']=entry['bundle_sha1']
registry[key]=entry
return implementations
def compile_mechanisms(args):
"""Enroll only explicitly selected, validated authored mechanisms."""
import sys
import subprocess
sys.path.insert(0, str(Path(__file__).parent))
from validate_mechanism_lessons import load_chunks, strict_json, require
catalog_data = strict_json(CATALOG)
catalog = {r['key']: r for r in catalog_data['figures']}
require(len(catalog) == len(catalog_data['figures']), 'duplicate catalog key')
artwork = strict_json(args.art_index)
selection = strict_json(args.selection)
selected = {r['key']:r for r in selection}
require(len(selected) == len(selection), 'duplicate selection key')
require(set(selected) <= set(catalog), 'selection missing from current catalog')
implementation_path = EXT/'mechanisms/implementations.json'
implementations = strict_json(implementation_path) if implementation_path.is_file() else {}
require(isinstance(implementations,dict), 'implementation manifest must be an object')
require(set(implementations) <= set(selected), 'implementation outside selected roster')
mechanism_dir = EXT/'mechanisms'
require(mechanism_dir.is_dir(), f'mechanism directory does not exist: {mechanism_dir}')
lessons = load_chunks(mechanism_dir) if any(mechanism_dir.glob('vol*-*.json')) else {}
require(set(lessons) <= set(selected), 'authored lesson outside selected roster')
native = set(implementations)-set(lessons)
for key in native:
implementation = implementations[key]
require(isinstance(implementation,dict) and isinstance(implementation.get('name'),str)
and implementation['name'].startswith('original-'),
f'{key}: native implementation without a mechanism lesson must be original-*')
missing = sorted(set(selected)-set(lessons)-native)
require(not args.require_complete or not missing, f'missing selected mechanisms: {missing}')
volumes = {v:{} for v in range(1,5)}
lesson_hashes = {}
for key, lesson in sorted(lessons.items()):
canonical = json.dumps(lesson, ensure_ascii=False, sort_keys=True, separators=(',', ':'), allow_nan=False)
digest = sha1(canonical.encode('utf-8'))
lesson_hashes[key] = digest
volumes[catalog[key]['volume']][key] = {'canonical':canonical, 'sha1':digest}
outputs = {}
bundle_hashes = {}
for volume, data in volumes.items():
filename = f'mechanism-lessons-vol{volume}.js'
content = '// Generated by compile_figure_explore.py; edit mechanisms/*.json.\nwindow.MLSysMechanismLessons = window.MLSysMechanismLessons || {};\nObject.assign(window.MLSysMechanismLessons, '+json.dumps(data,ensure_ascii=False,separators=(',',':')).replace('</','<\\/')+');\n'
outputs[EXT/filename] = content
bundle_hashes[volume] = sha1(content.encode('utf-8'))
registry, source_cache = {}, {}
for key in sorted(set(lessons)|native):
original = catalog[key]; source = original['source']; volume = original['volume']
for field in ('source','figure_id','volume'):
require(selected[key].get(field) == original[field], f'{key}: selected {field} differs from catalog')
text = source_cache.setdefault(source,(ROOT/source).read_text())
figure_match(text,original['figure_id'])
art = artwork.get(key)
require(art and art.get('source') == source, f'{key}: missing/mismatched canonical artwork')
asset = Path(art.get('asset',''))
require(asset.is_file(), f'{key}: canonical asset missing')
raw = asset.read_bytes()
require(art.get('asset_sha1') == sha1(raw), f'{key}: canonical art index stale')
from PIL import Image
with Image.open(art['image']) as im: width,height = im.size
generic = key in lessons
implementation = implementations.get(key,{})
if not generic:
require(asset.suffix.lower() in ('.svg','.png'), f'{key}: unsupported original artwork format')
require(width > 0 and height > 0, f'{key}: invalid canonical artwork dimensions')
if asset.suffix.lower() == '.svg':
try:
require(ET.fromstring(raw).tag.split('}')[-1] == 'svg', f'{key}: canonical asset is not SVG')
except ET.ParseError as error:
raise ValueError(f'{key}: invalid canonical SVG') from error
else:
with Image.open(asset) as im:
require(im.format == 'PNG' and im.size == (width,height), f'{key}: canonical PNG dimensions differ from artwork index')
im.verify()
entry = dict(name='mechanism-scene' if generic else implementation.get('name'),script='mechanism-scene.js' if generic else implementation.get('script'),stylesheet='mechanism-scene.css' if generic else implementation.get('stylesheet'),source=source,source_sha1=sha1(normalized_source(text).encode()),figure_id=original['figure_id'],volume=volume,art_sha1=sha1(raw),art_kind=asset.suffix.lstrip('.').lower(),art_width=width,art_height=height)
if generic:
entry.update(lesson_sha1=lesson_hashes[key],bundle=f'mechanism-lessons-vol{volume}.js',bundle_sha1=bundle_hashes[volume])
if asset.suffix.lower()=='.svg': entry['art_structural_sha1']=structural_svg(raw)
if generic:
for field in ('script','stylesheet'): require((EXT/entry[field]).is_file(),f'{key}: runtime asset missing {entry[field]}')
entry['runtime_sha1']=sha1(((EXT/entry['script']).read_bytes()+b'\x00'+(EXT/entry['stylesheet']).read_bytes()))
registry[key]=entry
apply_implementations(registry, implementations)
outputs[EXT/'figure-registry.json'] = json.dumps(registry,indent=2,ensure_ascii=False)+'\n'
# Reconcile implementation metadata without presenting validation as visual approval.
for row in catalog_data['figures']:
key = row['key']; lesson = lessons.get(key)
registered = key in registry
row['actual_treatment'] = registry[key]['name'] if registered else 'static'
row['status'] = row['actual_status'] = 'implemented-awaiting-review' if registered else 'static'
row['first_wave'] = key in registry
row['built_explore_present'] = False
row['runtime_verification'] = 'Schema, declared invariant, and companion calculation validation passed; actual themed chapter behavior review pending.' if lesson else 'Static figure retained; no mechanism enrolled.'
row['visual_verification'] = 'Actual themed chapter state/case inspection pending; validation is not visual approval.' if lesson else 'Static figure retained.'
row['actual_review_basis'] = 'Authored mechanism passes strict schema, declared invariants, and companion calculations; current implementation inspection remains pending.' if lesson else 'Static figure retained; no mechanism is enrolled.'
row['actual_question'] = implementations.get(key,{}).get('question',(lesson or {}).get('question','')) if registered else ''
row['actual_scope'] = implementations.get(key,{}).get('scope',(lesson or {}).get('scope','')) if registered else ''
row['actual_steps'] = [{'id':step['id'],'title':step['title'],'explanation':step['explanation'],'result':step['snapshot']['result']} for step in lesson['steps']] if lesson and key not in implementations else []
if registered and not lesson:
row['runtime_verification'] = 'Explicitly selected original-art factory assets and source/artwork provenance validated; actual themed chapter behavior review pending.'
row['visual_verification'] = 'Actual themed chapter state/case inspection pending; freshness validation is not visual approval.'
row['actual_review_basis'] = 'Native original-art implementation; source/art/runtime freshness validated without a generic mechanism lesson. Current implementation inspection remains pending.'
metadata = catalog_data['metadata']
metadata.setdefault('proposal_source_head',metadata.get('source_head',''))
metadata['source_head']=source_revision(metadata)
metadata['source_head_role']='Recorded source baseline; registry source/art/runtime/lesson/bundle hashes bind the actual delivered contents.'
metadata['count'] = len(catalog)
metadata['counts_by_volume'] = dict(Counter(str(r['volume']) for r in catalog.values()))
metadata['stateful_by_volume'] = dict(Counter(str(r['volume']) for r in registry.values()))
metadata['first_wave'] = sorted(registry)
metadata['actual_treatments'] = dict(Counter(r['actual_treatment'] for r in catalog_data['figures']))
metadata['actual_statuses'] = dict(Counter(r['actual_status'] for r in catalog_data['figures']))
metadata['review_limit'] = 'Current selected mechanisms pass strict authoring/calculation validation. Actual chapter visual and behavioral review remains pending; no student testing or learning-gain claim.'
if native:
metadata['review_limit'] = 'Selected mechanism lessons pass strict authoring/calculation validation; native original-art factories pass source/art/runtime freshness validation. Actual chapter visual and behavioral review remains pending; no student testing or learning-gain claim.'
bind_current_build(catalog_data,registry,outputs,args.build_root,native_keys=native)
apply_review_record(catalog_data,registry,lessons,outputs,args.build_root,args.review_record)
outputs[CATALOG] = json.dumps(catalog_data,indent=2,ensure_ascii=False)+'\n'
if args.enroll or args.check:
for original in catalog.values(): source_cache.setdefault(original['source'],(ROOT/original['source']).read_text())
updated_sources = {}
if args.enroll:
for source,text in source_cache.items():
updated=normalized_source(text)
for key,original in catalog.items():
if original['source'] != source: continue
match=figure_match(updated,original['figure_id'])
addition=f' data-explore="{registry[key]["name"]}" data-explore-key="{key}"' if key in registry else ''
updated=updated[:match.end()]+addition+updated[match.end():]
require(normalized_source(updated)==normalized_source(text),f'{source}: static bytes changed')
if updated!=text: updated_sources[ROOT/source]=updated
if args.check:
for path,content in outputs.items(): require(path.is_file() and path.read_text()==content,f'Outdated generated output: {path.relative_to(ROOT)}')
for key,original in catalog.items():
attrs=enrollment_attributes((ROOT/original['source']).read_text(),original['figure_id'])
expected=f' data-explore="{registry[key]["name"]}" data-explore-key="{key}"' if key in registry else ''
require(attrs==expected,f'{key}: stale/missing enrollment')
else:
# No source or output mutation until every lesson/art/calculation validates.
for path,content in {**outputs,**updated_sources}.items():
if not path.is_file() or path.read_text()!=content: path.write_text(content)
report={'catalog_total':len(catalog),'selected':len(selected),'registered':len(registry),'static':len(catalog)-len(registry),'missing_selected':missing,'by_volume':dict(Counter(str(v['volume']) for v in registry.values())),'source_files_updated':len(updated_sources),'review_status':'Validated schema/calculations; actual chapter visual and behavior review required.'}
if native:
report['review_status']='Validated mechanism schemas/calculations and native original-art source/art/runtime freshness; actual chapter visual and behavior review required.'
Path(args.report).write_text(json.dumps(report,indent=2)+'\n'); print(json.dumps(report,indent=2))
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--art-index', default='/tmp/figures-animation-art-current/index.json')
parser.add_argument('--review-record', help='Explicit public hash-bound implementation acceptance; requires --build-root.')
parser.add_argument('--build-root', help='Bind exact successful clean four-volume HTML build; does not grant visual approval.')
parser.add_argument('--report', default='/tmp/figure-explore-compile-report.json')
parser.add_argument('--enroll', action='store_true')
parser.add_argument('--check', action='store_true')
parser.add_argument('--require-complete', action='store_true')
parser.add_argument('--mechanisms', action='store_true', help='Compile only selected strict authored mechanisms.')
parser.add_argument('--selection', default=str(EXT/'mechanisms/selection.json'))
parser.add_argument('--legacy', action='store_true', help='Explicit archival compiler mode for pre-mechanism lessons.')
parser.add_argument('--partial', action='store_true', help='Compile available reviewed lessons (the default).')
args = parser.parse_args()
try:
if args.legacy and args.mechanisms:
raise ValueError('--legacy and --mechanisms are mutually exclusive')
compile_registry(args) if args.legacy else compile_mechanisms(args)
except (ValueError, KeyError) as error:
parser.exit(1, str(error)+'\n')
if __name__ == '__main__':
main()