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.

5.8 KB
Raw Blame
"""Build contract-shaped evidence events and snapshot locations for scripts/evidence-log.py.

Hashing, canonicalization and validation stay in evidence_validation; this module only
assembles the JSON objects that module already knows how to check.
"""
import copy
import datetime
import re

from catalog_validation import identifier, require
from evidence_validation import CANONICAL, content_hash

CHANGES = 'evidence/dataset-changes'
RUNTIME_STATUSES = ('not-run', 'passed', 'failed', 'unavailable', 'skipped')
CLAIM_STATUSES = ('verified', 'uncertain', 'rejected')
CHECK_STATUSES = ('passed', 'failed', 'not-run', 'unavailable', 'skipped')


def now():
    return datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')


def collection_of(record_id):
    require(record_id.startswith(('recipe.', 'knowledge.')), f'{record_id}: unsupported record prefix')
    return 'recipes' if record_id.startswith('recipe.') else 'knowledge'


def snapshot_path(change_id, record):
    """Repository-relative location the evidence contract expects for this exact revision."""
    return (f'{CHANGES}/{change_id}/snapshots/{collection_of(record["id"])}/{record["id"]}/'
            f'{record["revision"]}/{content_hash(record)}.json')


def find_snapshot(root, record_id, revision):
    """Locate the unique preserved snapshot of an earlier revision, in any change directory."""
    pattern = f'*/snapshots/{collection_of(record_id)}/{record_id}/{revision}/*.json'
    found = sorted((root / CHANGES).glob(pattern))
    require(found, f'{record_id}: no snapshot for revision {revision}; run the snapshot '
                   'subcommand before editing the record')
    require(len(found) == 1, f'{record_id}: ambiguous snapshots for revision {revision}')
    digest = found[0].stem
    require(re.fullmatch('[0-9a-f]{64}', digest), f'{found[0]}: snapshot filename requires SHA-256')
    return digest, found[0].relative_to(root).as_posix()


def record_ref(record):
    return {'collection': collection_of(record['id']), 'record_id': record['id'],
            'revision': record['revision']}


def event(change_id, record, actor, event_type, suffix, summary, payload):
    return {'schema_version': 1, 'change_id': change_id, 'timestamp': now(), 'actor': actor,
            'record_refs': [record_ref(record)],
            'event_id': f'{change_id}.{record["id"]}.{suffix}',
            'event_type': event_type, 'summary': summary, 'payload': payload}


def proposed_event(root, change_id, record, actor, summary):
    payload = {'before_hash': None, 'after_hash': content_hash(record)}
    if record['revision'] > 1:
        digest, path = find_snapshot(root, record['id'], record['revision'] - 1)
        payload['before_hash'] = digest
        payload['before_ref'] = {'collection': collection_of(record['id']),
                                 'record_id': record['id'], 'revision': record['revision'] - 1,
                                 'provenance_ref': f'snapshot:sha256:{digest}:{path}'}
    payload['hash_algorithm'] = 'sha256'
    payload['canonicalization'] = CANONICAL
    return event(change_id, record, actor, 'change-proposed',
                 f'revision-{record["revision"]}.proposed', summary, payload)


def curated_event(change_id, record, actor, status, rationale, runtime_status, summary,
                  artifact=None):
    """`artifact` is the repository-relative path the runtime observation was made on.

    The contract requires it whenever runtime_status is 'passed', and requires the same
    string to appear on a passing check-run of the same revision; callers must build both
    from one source (blueprint_validation.asset_ref for blueprints).
    """
    payload = {'status': status, 'rationale': rationale, 'runtime_status': runtime_status,
               'artifact_ref': artifact}
    return event(change_id, record, actor, 'record-curated',
                 f'revision-{record["revision"]}.curated', summary, payload)


def check_run_event(change_id, record, actor, check_id, method, status, artifact, output,
                    observed_by, observed_result, reason, summary):
    """One executed or unrun check. It records what was observed, never that it was right."""
    identifier(check_id, 'check-id')
    payload = {'check_id': check_id, 'method': method, 'status': status,
               'input_revision': record['revision'], 'artifact_ref': artifact,
               'output_ref': output}
    if status in {'passed', 'failed'}:
        payload.update({'observed_by': observed_by, 'observed_result': observed_result})
    else:
        payload['reason'] = reason
    return event(change_id, record, actor, 'check-run', f'{check_id}.check', summary, payload)


def source_read_event(change_id, record, actor, source_id, locator, source_version,
                      accessed_at, claim_ids, summary):
    require(claim_ids, f'{record["id"]}: at least one supported claim required')
    payload = {'source_id': source_id, 'locator': locator, 'source_version': source_version,
               'accessed_at': accessed_at, 'supported_claim_ids': list(claim_ids)}
    return event(change_id, record, actor, 'source-read', f'{claim_ids[0]}.{source_id}.read',
                 summary, payload)


def claim_of(record, claim_id):
    for claim in record.get('claims', []):
        if claim.get('id') == claim_id:
            return claim
    require(False, f'{record["id"]}: claim {claim_id} absent from the record')


def claim_checked_event(change_id, record, actor, claim_id, status, assumptions,
                        uncertainty, summary):
    claim = claim_of(record, claim_id)
    payload = {'claim_id': claim_id, 'status': status, 'assumptions': list(assumptions),
               'source_refs': copy.deepcopy(claim['source_refs']),
               'remaining_uncertainty': uncertainty}
    return event(change_id, record, actor, 'claim-checked', f'{claim_id}.checked', summary, payload)