Skip to content

Agent skill for creative 3D visualization: turn an idea into a Three.js/Blender scene worth exploring. Claude Code + Codex plugin, 223 recipes, 440 knowledge records, 22 proved kits, 37 runnable studies.

9.1 KB
Raw Blame
#!/usr/bin/env python3
"""Append contract-valid dataset-change evidence and record snapshots.

The helper writes what a contributor observed or decided; it never judges source truth,
runtime behavior or aesthetic quality. Events are appended and then validated with the
repository contract: a rejected batch is removed again and the command exits 1.
"""
import argparse
import json
from pathlib import Path
import sys

from catalog_validation import ContractError, STATUSES, identifier, load_catalog, require
from evidence_log_events import (CHECK_STATUSES, CLAIM_STATUSES, RUNTIME_STATUSES,
                                 check_run_event, claim_checked_event, curated_event,
                                 proposed_event, snapshot_path, source_read_event)
from evidence_validation import content_hash, validate_event

ROOT = Path(__file__).resolve().parents[1]


def catalog(root, change_id):
    identifier(change_id, 'change-id')
    records, sources, _ = load_catalog(root, collection='all')
    return records, sources


def pick(records, record_id):
    identifier(record_id, 'record')
    require(record_id in records, f'{record_id}: unknown record')
    return records[record_id]


def known_event_ids(root):
    ids = set()
    for path in sorted((root / 'evidence/dataset-changes').glob('*/events.jsonl')):
        for line in path.read_text(encoding='utf-8').splitlines():
            try:
                event = json.loads(line)
            except ValueError:
                continue  # validate.py reports malformed lines with their line number.
            if isinstance(event, dict) and isinstance(event.get('event_id'), str):
                ids.add(event['event_id'])
    return ids


def append(root, change_id, events, records, sources):
    """Append events, then validate them; failure restores exactly the previous file bytes."""
    known = known_event_ids(root)
    for event in events:
        require(event['event_id'] not in known, f'duplicate event_id: {event["event_id"]}')
        known.add(event['event_id'])
    path = root / 'evidence/dataset-changes' / change_id / 'events.jsonl'
    path.parent.mkdir(parents=True, exist_ok=True)
    original = path.read_bytes() if path.exists() else b''
    separator = b'' if not original or original.endswith(b'\n') else b'\n'
    lines = ''.join(json.dumps(event, ensure_ascii=False) + '\n' for event in events)
    path.write_bytes(original + separator + lines.encode('utf-8'))
    try:
        for event in events:
            validate_event(event, records, sources, root, change_id)
            print(f'OK {event["event_id"]}')
    except BaseException:
        if original:
            path.write_bytes(original)
        else:
            path.unlink()
        raise


def actor_of(args):
    return {'kind': args.actor_kind, 'name': args.actor}


def run_snapshot(args, root):
    records, _ = catalog(root, args.change_id)
    record = pick(records, args.record)
    path = root / snapshot_path(args.change_id, record)
    if not path.exists():
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(json.dumps(record, indent=2, ensure_ascii=False) + '\n', encoding='utf-8')
    print(f'{content_hash(record)} {path.relative_to(root).as_posix()}')


def run_propose(args, root):
    records, sources = catalog(root, args.change_id)
    record = pick(records, args.record)
    actor = actor_of(args)
    append(root, args.change_id,
           [proposed_event(root, args.change_id, record, actor, args.summary),
            curated_event(args.change_id, record, actor, args.status or record['status'],
                          args.rationale, args.runtime_status, args.summary,
                          args.artifact)],
           records, sources)


def run_check_run(args, root):
    records, sources = catalog(root, args.change_id)
    record = pick(records, args.record)
    append(root, args.change_id,
           [check_run_event(args.change_id, record, actor_of(args), args.check_id, args.method,
                            args.status, args.artifact, args.output, args.observed_by,
                            args.observed_result, args.reason, args.summary)],
           records, sources)


def run_source_read(args, root):
    records, sources = catalog(root, args.change_id)
    record = pick(records, args.record)
    summary = args.summary or (f'Read {args.source} at {args.locator} for '
                               f'{len(args.claims)} claim(s) of {record["id"]}.')
    append(root, args.change_id,
           [source_read_event(args.change_id, record, actor_of(args), args.source, args.locator,
                              args.source_version, args.accessed_at, args.claims, summary)],
           records, sources)


def run_claim_checked(args, root):
    records, sources = catalog(root, args.change_id)
    record = pick(records, args.record)
    summary = args.summary or f'Checked {args.claim} of {record["id"]}: {args.status}.'
    append(root, args.change_id,
           [claim_checked_event(args.change_id, record, actor_of(args), args.claim, args.status,
                                args.assumptions, args.uncertainty, summary)],
           records, sources)


HANDLERS = {'snapshot': run_snapshot, 'propose': run_propose, 'check-run': run_check_run,
            'source-read': run_source_read, 'claim-checked': run_claim_checked}


def build_parser():
    parser = argparse.ArgumentParser(description=__doc__,
                                     formatter_class=argparse.RawDescriptionHelpFormatter)
    common = argparse.ArgumentParser(add_help=False)
    common.add_argument('--root', type=Path, default=ROOT, help='repository root')
    common.add_argument('--change-id', required=True, help='evidence/dataset-changes/<change-id>')
    common.add_argument('--record', required=True, help='recipe.* or knowledge.* record ID')
    logged = argparse.ArgumentParser(add_help=False)
    logged.add_argument('--actor', required=True, help='actor name recorded in the event')
    logged.add_argument('--actor-kind', choices=('agent', 'human', 'tool'), default='agent')
    subs = parser.add_subparsers(dest='command', required=True)
    subs.add_parser('snapshot', parents=[common],
                    help='preserve the current record revision before editing it')
    propose = subs.add_parser('propose', parents=[common, logged],
                              help='log change-proposed and record-curated for the edited record')
    propose.add_argument('--summary', required=True)
    propose.add_argument('--rationale', required=True, help='why the curated content is acceptable')
    propose.add_argument('--status', choices=sorted(STATUSES), help='defaults to the record status')
    propose.add_argument('--runtime-status', choices=RUNTIME_STATUSES, default='not-run')
    propose.add_argument('--artifact', help='repository-relative artifact the runtime status '
                                            'was observed on; required by --runtime-status passed')
    check = subs.add_parser('check-run', parents=[common, logged],
                            help='log one executed or unrun check against this record revision')
    check.add_argument('--check-id', required=True, help='stable ID of this check')
    check.add_argument('--method', required=True, help='how the check was made, e.g. visual')
    check.add_argument('--status', choices=CHECK_STATUSES, required=True)
    check.add_argument('--artifact', help='repository-relative artifact the check ran against')
    check.add_argument('--output', help='repository-relative output of the check')
    check.add_argument('--observed-by', help='observer; required for passed or failed')
    check.add_argument('--observed-result', help='what was observed; required for passed or failed')
    check.add_argument('--reason', help='why an unrun check was not run')
    check.add_argument('--summary', required=True)
    read = subs.add_parser('source-read', parents=[common, logged],
                           help='log one source read supporting claims of the record')
    read.add_argument('--source', required=True)
    read.add_argument('--locator', required=True)
    read.add_argument('--source-version', required=True)
    read.add_argument('--accessed-at', required=True, help='YYYY-MM-DD')
    read.add_argument('--claim', action='append', dest='claims', default=[], required=True)
    read.add_argument('--summary')
    checked = subs.add_parser('claim-checked', parents=[common, logged],
                              help='log one claim check with its assumptions and uncertainty')
    checked.add_argument('--claim', required=True)
    checked.add_argument('--status', choices=CLAIM_STATUSES, required=True)
    checked.add_argument('--assumption', action='append', dest='assumptions', default=[])
    checked.add_argument('--uncertainty', required=True)
    checked.add_argument('--summary')
    return parser


def main(argv=None):
    args = build_parser().parse_args(argv)
    try:
        HANDLERS[args.command](args, args.root.resolve())
    except (ContractError, OSError, TypeError, KeyError) as error:
        print(f'Evidence log failed: {error}', file=sys.stderr)
        return 1
    return 0


if __name__ == '__main__':
    raise SystemExit(main())