object-log 0.4.0

A buffered, multiplexing append log over pluggable object storage, with a sequencing seam (opaque payloads, durable-on-return writes, group-commit).
Documentation
#!/usr/bin/env python3
"""Captured-model execution and failure-safe, target-owned authority evidence."""
from pathlib import Path
import argparse
import hashlib
import json
import os
import subprocess
import sys
import tempfile
import types

ROOT = Path(__file__).resolve().parents[2]
MODEL = ROOT / 'scripts/formal/native_head_model.py'
DEFAULT = ROOT / 'target/native-head-model.json'
SOURCES = (
    'Cargo.toml', 'Cargo.lock', 'src/lib.rs', 'src/error.rs', 'src/blob.rs', 'src/blob/authority.rs',
    'src/s3.rs', 'src/s3/runtime_tests.rs', 'src/s3/owned_client.rs', 'src/s3/owned_client/tests.rs', 'src/s3/authority.rs', 'src/sequencer.rs', 'src/native_v2/head.rs',
    'src/native_v2/mod.rs', 'src/native_v2/data.rs', 'src/native_v2/codec.rs', 'src/native_v2/operation.rs',
    'src/native_v2/facade.rs', 'tests/native_facade.rs', 'src/native_v2/page_store.rs', 'src/native_v2/page_store/immutable.rs', 'src/native_v2/index.rs', 'src/native_v2/provision.rs', 'src/native_v2/submission.rs',
    'src/native_v2/head/tests.rs', 'src/native_v2/head/tests/s3.rs',
    'src/native_v2/head/tests/coupled.rs',
    'src/native_v2/facade/read_requirements.rs',
    'src/native_v2/facade/read_requirements/tests.rs',
    'src/native_v2/facade/semantic.rs',
    'src/native_v2/facade/semantic/scan.rs',
    'src/native_v2/facade/semantic/tests.rs',
    'tests/native_semantic.rs',
    'src/native_v2/page_store/scoped_bytes.rs', 'src/native_v2/semantic_map/mod.rs',
    'src/native_v2/page_store/transition_key.rs',
    'src/native_v2/semantic_map/manifest.rs',
    'src/native_v2/semantic_map/publication.rs',
    'src/native_v2/semantic_map/seal.rs',
    'src/native_v2/data/coupled.rs',
    'src/native_v2/semantic_map/codec.rs', 'src/native_v2/semantic_map/bytes.rs',
    'src/native_v2/semantic_map/read.rs', 'src/native_v2/semantic_map/range.rs',
    'src/native_v2/semantic_map/tests.rs',
    'src/native_v2/semantic_map/test_support.rs', 'src/native_v2/semantic_map/edit.rs',
    'src/native_v2/semantic_map/edit/tests.rs',
    'src/native_v2/semantic_map/test_support/gated_store.rs',
    'scripts/formal/native_cow_model.py', 'scripts/formal/check_native_cow.py',
    'scripts/formal/native_semantic_model.py', 'scripts/formal/check_native_semantic.py',
    'scripts/formal/native_provision_model.py', 'scripts/formal/check_native_provision.py',
    'scripts/formal/native_head_model.py', 'scripts/formal/check_native_head.py',
    'docs/helix/02-design/contracts/CONTRACT-002-object-store-api.md',
    'docs/helix/02-design/contracts/CONTRACT-001-core-log-api.md',
    '.github/workflows/ci.yml', 'scripts/ci/native_s3.py', 'scripts/ci/native_s3_controls.py', 'deny.toml',
)
CODE_MAPPING = {
    'scope': 'MetadataSnapshot::validate provider/key tokens',
    'budget': 'Local read_local; S3 MetadataResponse/read_metadata_inner (physical read bounds are tested separately)',
    'root_preservation': 'test-internal Owner::execute epoch-only encoding',
    'ambiguous_retry': 'S3 one-attempt conditional PUT; head errors propagate',
    'physical_cancel': 'AppendOwner in Local blocking closures',
    'source_lifetime': 'MetadataSnapshot last owner field; OwnedMetadataBody carrier',
    'notify_order': 'PhysicalOwner permit release precedes owned/notify',
    'conflict_floor': 'Owner::execute retains prior head across conflict',
}

def owned_output(raw):
    path = Path(raw)
    if not path.is_absolute():
        path = ROOT / path
    target = ROOT / 'target'
    if not path.is_relative_to(target) or path.suffix != '.json':
        raise ValueError('evidence output must be a JSON file inside this checkout target/')
    relative = path.relative_to(ROOT)
    current = ROOT
    for component in relative.parts:
        if component in {'.', '..'}:
            raise ValueError('evidence path must not traverse directories')
        current = current / component
        if current.is_symlink():
            raise ValueError('evidence path must not contain symlinks')
    if not path.resolve().is_relative_to(target.resolve()):
        raise ValueError('evidence path escapes target/')
    return path

def atomic_report(path, value):
    owned_output(str(path))
    path.parent.mkdir(parents=True, exist_ok=True)
    owned_output(str(path))
    descriptor, temporary = tempfile.mkstemp(prefix=path.name + '.', dir=path.parent)
    try:
        with os.fdopen(descriptor, 'w') as output:
            json.dump(value, output, indent=2)
            output.write('\n')
            output.flush()
            os.fsync(output.fileno())
        os.replace(temporary, path)
    finally:
        if os.path.exists(temporary):
            os.unlink(temporary)

def capture():
    return {
        'head': subprocess.check_output(['git', 'rev-parse', 'HEAD'], cwd=ROOT, text=True).strip(),
        'status': subprocess.check_output(['git', 'status', '--porcelain=v1', '-uall'], cwd=ROOT, text=True),
        'source_sha256': {name: hashlib.sha256((ROOT / name).read_bytes()).hexdigest() for name in SOURCES},
    }

def loaded_model(raw):
    module = types.ModuleType('native_head_captured_model')
    module.__file__ = str(MODEL)
    sys.modules[module.__name__] = module
    exec(compile(raw, str(MODEL), 'exec'), module.__dict__)
    return module

def failure_controls():
    DEFAULT.parent.mkdir(parents=True, exist_ok=True)
    with tempfile.TemporaryDirectory(prefix='native-head-gate-controls-', dir=DEFAULT.parent) as folder:
        report = Path(folder) / 'report.json'
        def run(extra=()):
            return subprocess.run([sys.executable, str(Path(__file__).resolve()), '--output', str(report), *extra], cwd=ROOT, capture_output=True, text=True)
        controls = []
        for label, extra in [('failed-model', ('--negative-control', 'conflict_floor')), ('bad-cli', ('--invalid-option',)), ('abbreviated-output', ('--out', str(report)))]:
            assert run().returncode == 0
            prior = json.loads(report.read_text())
            assert prior['status'] == 'PASS' and prior['passed']
            failed = run(extra)
            terminal = json.loads(report.read_text())
            assert failed.returncode != 0 and terminal['status'] == 'FAIL' and not terminal['passed']
            controls.append({'control': label, 'prior_genuine_pass': True, 'failed_run_exit': failed.returncode, 'terminal': terminal['status']})
        sentinel = Path(folder) / 'sentinel.txt'
        sentinel.write_text('unchanged')
        invalid = subprocess.run([sys.executable, str(Path(__file__).resolve()), '--output', str(sentinel)], cwd=ROOT, capture_output=True, text=True)
        assert invalid.returncode != 0 and sentinel.read_text() == 'unchanged'
        link = Path(folder) / 'link.json'
        link.symlink_to(sentinel)
        invalid = subprocess.run([sys.executable, str(Path(__file__).resolve()), '--output', str(link)], cwd=ROOT, capture_output=True, text=True)
        assert invalid.returncode != 0 and sentinel.read_text() == 'unchanged'
        controls.append({'control': 'non-json-and-symlink-rejection', 'sentinel_unchanged': True})
        with tempfile.TemporaryDirectory(prefix='native-head-external-control-') as external:
            outside = Path(external) / 'sentinel.json'
            outside.write_text('{"sentinel":"unchanged"}')
            digest = hashlib.sha256(outside.read_bytes()).hexdigest()
            invalid = subprocess.run([sys.executable, str(Path(__file__).resolve()), '--output', str(outside)], cwd=ROOT, capture_output=True, text=True)
            assert invalid.returncode != 0 and hashlib.sha256(outside.read_bytes()).hexdigest() == digest
        controls.append({'control': 'outside-target-rejection', 'sentinel_unchanged': True})
        return controls

def main(argv=None):
    arguments = list(sys.argv[1:] if argv is None else argv)
    output = DEFAULT
    try:
        raw = str(DEFAULT)
        for index, argument in enumerate(arguments):
            if argument == '--output' and index + 1 < len(arguments):
                raw = arguments[index + 1]
                break
            if argument.startswith('--output='):
                raw = argument.split('=', 1)[1]
                break
        output = owned_output(raw)
        atomic_report(output, {'status': 'INCOMPLETE', 'passed': False})
        parser = argparse.ArgumentParser(allow_abbrev=False)
        parser.add_argument('--output', default=str(DEFAULT))
        parser.add_argument('--self-test', action='store_true')
        parser.add_argument('--negative-control', choices=tuple(CODE_MAPPING))
        args = parser.parse_args(arguments)
        if owned_output(args.output) != output:
            raise ValueError('duplicate evidence output options are not accepted')
        source = capture()
        model_bytes = MODEL.read_bytes()
        digest = hashlib.sha256(model_bytes).hexdigest()
        assert digest == source['source_sha256']['scripts/formal/native_head_model.py']
        model = loaded_model(model_bytes)
        positive = model.explore(args.negative_control)
        assert positive['passed'], positive
        assert len(positive['witnesses']) == 6, positive
        for witness in positive['witnesses'].values():
            assert model.replay(witness) is None
        controls = {name: model.explore(name) for name in model.MUTANTS}
        for name, control in controls.items():
            assert not control['passed'] and control['violation'] == model.EXPECTED[name], control
            assert model.replay(control['trace'], name) == model.EXPECTED[name]
        gate_controls = failure_controls() if args.self_test else []
        assert capture() == source, 'source changed during model execution'
        report = {
            'status': 'PASS', 'passed': True,
            'scope': 'finite CAS/ownership model; documentary mapping, not refinement/provider/transport/heap proof',
            'bounds': '24 starting cases; two writer observations; floor2/current1-or3; at most2conditional PUTs; cancellation at every dispatched cut',
            'assumptions': ['linearizable provider CAS', 'immutable committed bytes/identity', 'epoch-only acquisition; roots opaque', 'source ownership excludes copied transport buffers and remote effects', 'read-allocation limits are physical-test obligations, not modeled zero reads'],
            'source': source, 'executed_model_sha256': digest, 'code_mapping': CODE_MAPPING,
            'model': positive, 'negative_controls': controls, 'failure_report_controls': gate_controls,
        }
        atomic_report(output, report)
        print(json.dumps({'passed': True, 'states': positive['states'], 'edges': positive['edges'], 'witnesses': len(positive['witnesses']), 'negative_controls': len(controls), 'failure_report_controls': len(gate_controls)}))
    except BaseException as error:
        atomic_report(output, {'status': 'FAIL', 'passed': False, 'error_type': type(error).__name__, 'error': str(error)[:4096]})
        raise

if __name__ == '__main__':
    main()