mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-11-14 18:24:37 -06:00
525 lines
34 KiB
Python
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()
|