From 0c92d0e45681721143d2e1101e2bdb4643dd56de Mon Sep 17 00:00:00 2001
From: EHotwagner <ehotwagner@gmail.com>
Date: Mon, 5 Oct 2026 09:08:42 +0200
Subject: [PATCH] Bind external inventory without mutating accepted seed data

---
 docs/roadmaps/barc-01-useful-play.md          | 29 ++++++
 .../helper/settings_custody.py                | 43 ++++++++-
 .../helper/test_settings_custody.py           | 95 +++++++++++++++++++
 .../run-source-controls.py                    |  2 +-
 4 files changed, 163 insertions(+), 6 deletions(-)

diff --git a/docs/roadmaps/barc-01-useful-play.md b/docs/roadmaps/barc-01-useful-play.md
index af7fdc9..89fbb2b 100644
--- a/docs/roadmaps/barc-01-useful-play.md
+++ b/docs/roadmaps/barc-01-useful-play.md
@@ -623,3 +623,32 @@ generation changes immediately and retains both the original unresolved
 generation and later hard-failure evidence. Its separately reviewed seal and
 exact admission remain prerequisites for another copy. This source correction
 grants no runtime authority; native useful play remains 0/6.
+
+### External inventory for the accepted seed data (2026-10-05)
+
+The separately admitted fifth data copy completed all 17,756 files and
+2,111,386,119 bytes with natural exit zero and clean retirement. Its original
+receipt contains the complete physical data pins, but it did not produce
+`packet-inventory.json`. The accepted data and all consumed failures remain
+unchanged.
+
+The seed settings helper now accepts an optional explicit `packetInventory`
+physical pin for a separately attributed external projection. Its digest must
+equal `packetSha256`, and its declared root must equal the existing packet root.
+The bounded read checks the original, opened, completed and current file
+identities, private directory custody and physical root stability. External
+mode requires the accepted packet root to retain its immutable mode `0500`;
+legacy mode keeps its original private root mode `0700`. External
+mode checks every packet file; an unlisted `packet-inventory.json` is refused.
+The existing in-packet inventory route keeps its original behavior.
+
+All 143 portable controls passed, including replacement during open/read,
+parent or packet-root replacement, hash and root drift, aliases, missing
+external input, complete post-use data preservation and legacy settings copy.
+The source-only projection derives from the accepted copy pins; it is not an
+output of that original copy operation. Root must separately pin its authority
+and refresh the policy helper manifest after protected source delivery.
+
+Actual native map/game checksums, loaded configuration/VFS/AI custody and seed
+attribution still require distinct exact admission. Native useful play remains
+0/6.
diff --git a/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/helper/settings_custody.py b/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/helper/settings_custody.py
index e240e1c..d2f2bb8 100644
--- a/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/helper/settings_custody.py
+++ b/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/helper/settings_custody.py
@@ -1,14 +1,47 @@
 """Root-selected immutable settings seed and attempt-scoped engine output."""
-import hashlib,os,stat
+import hashlib,json,os,stat
 from pathlib import Path
-from private_io import Refused,atomic_bytes_new,atomic_new,canonical,components,hash_artifact,need,read_bytes,read_json
+from private_io import SHA,Refused,atomic_bytes_new,atomic_new,canonical,components,hash_artifact,need,read_bytes,read_json
 MAX_SETTINGS=65536
 MAX_INVENTORY=16*1024*1024
 MAX_FILES=65536
 
+def external_inventory(config,root,root_before):
+    pin=config['packetInventory'];fields={'path','sha256','bytes','device','inode','uid','mode','nlink'}
+    need(type(pin)is dict and set(pin)==fields,'closed external inventory pin')
+    need(type(pin['sha256'])is str and SHA.fullmatch(pin['sha256']) and pin['sha256']==config['packetSha256'],'external inventory digest join')
+    need(all(type(pin[k])is int for k in fields-{'path','sha256'}),'external inventory physical pin types')
+    path=components(pin['path']);need(not path.is_relative_to(root),'external inventory outside packet root')
+    anchor=path.parent.lstat();before=path.lstat()
+    need(stat.S_ISDIR(anchor.st_mode) and anchor.st_uid==os.geteuid() and stat.S_IMODE(anchor.st_mode)==0o700,'private external inventory anchor')
+    need(stat.S_ISREG(before.st_mode) and before.st_uid==os.geteuid() and stat.S_IMODE(before.st_mode)in(0o400,0o600) and before.st_nlink==1 and 0<before.st_size<=MAX_INVENTORY,'external inventory custody/bound')
+    def matches(info):
+        return all(pin[k]==v for k,v in {'bytes':info.st_size,'device':info.st_dev,'inode':info.st_ino,'uid':info.st_uid,'mode':stat.S_IMODE(info.st_mode),'nlink':info.st_nlink}.items())
+    need(matches(before),'external inventory physical identity')
+    fd=os.open(path,os.O_RDONLY|os.O_NOFOLLOW|os.O_NONBLOCK|os.O_CLOEXEC)
+    try:
+        opened=os.fstat(fd);need(matches(opened) and stat.S_ISREG(opened.st_mode),'opened external inventory identity')
+        chunks=[];length=0
+        while length<=MAX_INVENTORY:
+            block=os.read(fd,min(65536,MAX_INVENTORY+1-length))
+            if not block:break
+            chunks.append(block);length+=len(block)
+        after=os.fstat(fd);current=components(str(path)).lstat();parent=path.parent.lstat();root_after=components(str(root)).lstat()
+        attrs=('st_dev','st_ino','st_size','st_uid','st_mode','st_nlink','st_mtime_ns','st_ctime_ns')
+        need(length==before.st_size and length<=MAX_INVENTORY and all(getattr(before,k)==getattr(opened,k)==getattr(after,k)==getattr(current,k)for k in attrs),'external inventory changed during read')
+        need(all(getattr(anchor,k)==getattr(parent,k)for k in ('st_dev','st_ino','st_uid','st_mode')) and all(getattr(root_before,k)==getattr(root_after,k)for k in ('st_dev','st_ino','st_uid','st_mode')),'external inventory directory/root generation drift')
+    finally:os.close(fd)
+    raw=b''.join(chunks);need(hashlib.sha256(raw).hexdigest()==pin['sha256'],'external inventory bytes mismatch')
+    def unique(pairs):
+        value={}
+        for key,item in pairs:need(key not in value,'duplicate external inventory JSON key');value[key]=item
+        return value
+    return json.loads(raw.decode('utf-8'),object_pairs_hook=unique,parse_constant=lambda _: (_ for _ in ()).throw(Refused('nonfinite external inventory JSON')))
+
 def inventory(config):
-    root=components(config['roots']['packetRoot']);need(root.stat().st_uid==os.geteuid() and stat.S_IMODE(root.stat().st_mode)==0o700,'private packet root')
-    value=read_json(str(root/'packet-inventory.json'),config['packetSha256'],MAX_INVENTORY)
+    root=components(config['roots']['packetRoot']);info=root.lstat();required_mode=0o500 if 'packetInventory'in config else 0o700
+    need(stat.S_ISDIR(info.st_mode) and info.st_uid==os.geteuid() and stat.S_IMODE(info.st_mode)==required_mode,'private packet root')
+    value=external_inventory(config,root,info) if 'packetInventory'in config else read_json(str(root/'packet-inventory.json'),config['packetSha256'],MAX_INVENTORY)
     need(value['root']==str(root) and isinstance(value['files'],list) and len(value['files'])<=MAX_FILES,'bounded packet census')
     need(value['fileCount']==len(value['files']),'packet census count')
     names=set()
@@ -46,7 +79,7 @@ def verify_packet_unchanged(config):
         for name in dirs:need(not (Path(base)/name).is_symlink(),'packet symlink directory')
         for name in files:
             p=Path(base)/name;need(not p.is_symlink(),'packet symlink file');rel=str(p.relative_to(root))
-            if rel=='packet-inventory.json':continue
+            if 'packetInventory'not in config and rel=='packet-inventory.json':continue
             need(len(actual)<MAX_FILES,'bounded packet file census');actual.add(rel);need(rel in expected,'unadmitted packet file')
             row=expected[rel];before=hash_artifact(str(p),row['sha256']);need(before.st_nlink==1 and before.st_uid==row['ownerUid'] and before.st_ino==row['inode'] and f'{os.major(before.st_dev)}:{os.minor(before.st_dev)}'==row['device'] and before.st_size==row['bytes'] and stat.S_IMODE(before.st_mode)==int(row['mode'],8),'packet custody changed')
     need(actual==set(expected),'packet file census changed');return len(actual)
diff --git a/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/helper/test_settings_custody.py b/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/helper/test_settings_custody.py
index edd1386..c5c035a 100644
--- a/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/helper/test_settings_custody.py
+++ b/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/helper/test_settings_custody.py
@@ -1,6 +1,7 @@
 import hashlib,json,os,pathlib,stat,sys,tempfile,unittest,shutil
 sys.path.insert(0,str(pathlib.Path(__file__).resolve().parent))
 import settings_custody as m
+from unittest.mock import patch
 class Controls(unittest.TestCase):
  def setUp(self):
   self.tmp=tempfile.TemporaryDirectory();self.r=pathlib.Path(self.tmp.name);self.r.chmod(0o700);self.p=self.r/'packet';self.a=self.r/'attempt';self.p.mkdir(mode=0o700);self.a.mkdir(mode=0o700);(self.a/'engine').mkdir(mode=0o700);self.seed=self.p/'seed.cfg';self.seed.write_bytes(b'Fullscreen=0\n');self.seed.chmod(0o400);self.output=self.a/'engine/springsettings.cfg';self.c={'roots':{'packetRoot':str(self.p),'attemptRoot':str(self.a)},'commands':{'engine':['engine','--isolation','--isolation-dir',str(self.p),'--write-dir',str(self.a/'engine'),'--config',str(self.seed),'script']}};self.pin()
@@ -23,4 +24,98 @@ def test_packet_change_post_use_refuses(self):argv,r=m.prepare_engine_settings(s
  def test_new_packet_file_post_use_refuses(self):argv,r=m.prepare_engine_settings(self.c,self.a);(self.p/'unexpected').write_bytes(b'x');self.assertRaises(m.Refused,m.finish_engine_settings,self.c,self.a,r)
  def test_duplicate_census_refuses(self):p=self.p/'packet-inventory.json';v=json.loads(p.read_text());v['files']*=2;v['fileCount']=2;raw=json.dumps(v).encode();p.write_bytes(raw);self.c['packetSha256']=hashlib.sha256(raw).hexdigest();self.refused()
  def test_hardlinked_seed_refuses(self):os.link(self.seed,self.p/'hardlink');self.refused()
+
+class ExternalControls(unittest.TestCase):
+ setUp=Controls.setUp
+ pin=Controls.pin
+ tearDown=Controls.tearDown
+ refused=Controls.refused
+ def external(self):
+  self.external_root=self.r/'external';self.external_root.mkdir(mode=0o700);self.external_file=self.external_root/'projection.json';(self.p/'packet-inventory.json').rename(self.external_file);self.external_file.chmod(0o400);self.p.chmod(0o500);self.repin()
+ def repin(self):
+  s=self.external_file.lstat();self.c['packetInventory']={'path':str(self.external_file),'sha256':hashlib.sha256(self.external_file.read_bytes()).hexdigest(),'bytes':s.st_size,'device':s.st_dev,'inode':s.st_ino,'uid':s.st_uid,'mode':stat.S_IMODE(s.st_mode),'nlink':s.st_nlink};self.c['packetSha256']=self.c['packetInventory']['sha256']
+ def rewrite(self,value):
+  self.external_file.chmod(0o600);self.external_file.write_text(json.dumps(value));self.external_file.chmod(0o400);self.repin()
+ def test_exact_external_copy_and_post_use(self):
+  self.external();argv,r=m.prepare_engine_settings(self.c,self.a);self.assertEqual(argv[7],str(self.output));self.assertEqual(self.output.read_bytes(),self.seed.read_bytes());self.assertEqual(m.finish_engine_settings(self.c,self.a,r)['packetFileCount'],1);self.assertFalse((self.p/'packet-inventory.json').exists())
+ def test_external_mode0600(self):
+  self.external();self.external_file.chmod(0o600);self.repin();self.assertEqual(m.inventory(self.c)[1]['fileCount'],1)
+ def test_missing_external_no_legacy_fallback(self):
+  self.external();self.p.chmod(0o700);self.external_file.rename(self.p/'packet-inventory.json');self.p.chmod(0o500);self.refused();self.assertFalse(self.output.exists())
+ def test_digest_join(self):self.external();self.c['packetSha256']='0'*64;self.refused()
+ def test_byte_digest(self):
+  self.external();self.external_file.chmod(0o600);raw=self.external_file.read_bytes();self.external_file.write_bytes(raw.replace(b'seed.cfg',b'fake.cfg'));self.external_file.chmod(0o400);self.refused()
+ def test_closed_pin(self):self.external();self.c['packetInventory']['unreviewed']=True;self.refused()
+ def test_pin_types(self):self.external();self.c['packetInventory']['nlink']=True;self.refused()
+ def test_pin_identity(self):self.external();self.c['packetInventory']['inode']+=1;self.refused()
+ def test_root_join(self):self.external();value=json.loads(self.external_file.read_text());value['root']=str(self.r);self.rewrite(value);self.refused()
+ def test_same_bytes_replaced_inode(self):
+  self.external();old=self.external_file.with_name('retained');self.external_file.rename(old);self.external_file.write_bytes(old.read_bytes());self.external_file.chmod(0o400);self.refused()
+ def test_alias(self):
+  self.external();alias=self.r/'alias';alias.symlink_to(self.external_root);self.c['packetInventory']['path']=str(alias/'projection.json');self.refused()
+ def test_hardlinked_inventory(self):self.external();os.link(self.external_file,self.r/'hardlink');self.refused()
+ def test_inventory_inside_packet_refuses(self):
+  self.external();self.p.chmod(0o700);self.external_file.rename(self.p/'projection.json');self.p.chmod(0o500);self.external_file=self.p/'projection.json';self.repin();self.refused()
+ def test_writable_anchor(self):self.external();self.external_root.chmod(0o777);self.refused()
+ def test_unlisted_inroot_inventory_not_exempt(self):
+  self.external();argv,r=m.prepare_engine_settings(self.c,self.a);self.p.chmod(0o700);(self.p/'packet-inventory.json').write_bytes(b'unlisted');self.p.chmod(0o500);self.assertRaises(m.Refused,m.finish_engine_settings,self.c,self.a,r)
+ def test_post_use_seed_drift(self):
+  self.external();argv,r=m.prepare_engine_settings(self.c,self.a);self.seed.chmod(0o600);self.seed.write_bytes(b'changed');self.seed.chmod(0o400);self.assertRaises(m.Refused,m.finish_engine_settings,self.c,self.a,r)
+ def test_path_replacement_during_read(self):
+  self.external();read=os.read;changed=False
+  def replace(fd,size):
+   nonlocal changed
+   raw=read(fd,size)
+   if not changed:
+    changed=True;old=self.external_file.with_name('retained');self.external_file.rename(old);self.external_file.write_bytes(old.read_bytes());self.external_file.chmod(0o400)
+   return raw
+  with patch.object(m.os,'read',replace):self.refused()
+ def test_root_replacement_during_read(self):
+  self.external();read=os.read;changed=False
+  def replace(fd,size):
+   nonlocal changed
+   raw=read(fd,size)
+   if not changed:changed=True;self.p.rename(self.r/'retained-packet');self.p.mkdir(mode=0o500)
+   return raw
+  with patch.object(m.os,'read',replace):self.refused()
+ def test_external_packet_root0700_refuses(self):self.external();self.p.chmod(0o700);self.refused()
+ def test_external_packet_root_shared_writable_refuses(self):self.external();self.p.chmod(0o777);self.refused()
+ def test_root_replacement_before_external_read(self):
+  self.external();components=m.components;changed=False
+  def replace(path):
+   nonlocal changed
+   if path==str(self.external_file) and not changed:changed=True;self.p.rename(self.r/'retained-packet');self.p.mkdir(mode=0o500)
+   return components(path)
+  with patch.object(m,'components',replace):self.refused()
+ def test_duplicate_external_json(self):
+  self.external();self.external_file.chmod(0o600);self.external_file.write_text('{"root":"a","root":"b"}');self.external_file.chmod(0o400);self.repin();self.refused()
+ def test_external_file_byte_bound(self):
+  self.external();self.external_file.chmod(0o600)
+  with self.external_file.open('r+b')as stream:stream.truncate(m.MAX_INVENTORY+1)
+  self.external_file.chmod(0o400);self.c['packetInventory']['bytes']=m.MAX_INVENTORY+1;self.refused()
+ def test_opened_identity_replacement(self):
+  self.external();open_fd=os.open
+  def replace(path,*args,**kwargs):
+   if pathlib.Path(path)==self.external_file:
+    old=self.external_file.with_name('retained');self.external_file.rename(old);self.external_file.write_bytes(old.read_bytes());self.external_file.chmod(0o400)
+   return open_fd(path,*args,**kwargs)
+  with patch.object(m.os,'open',replace):self.refused()
+ def test_content_change_during_read(self):
+  self.external();read=os.read;changed=False
+  def replace(fd,size):
+   nonlocal changed
+   raw=read(fd,size)
+   if not changed:
+    changed=True;self.external_file.chmod(0o600);self.external_file.write_bytes(self.external_file.read_bytes().replace(b'seed.cfg',b'fake.cfg'));self.external_file.chmod(0o400)
+   return raw
+  with patch.object(m.os,'read',replace):self.refused()
+ def test_parent_replacement_during_read(self):
+  self.external();read=os.read;changed=False
+  def replace(fd,size):
+   nonlocal changed
+   raw=read(fd,size)
+   if not changed:
+    changed=True;old=self.r/'retained-external';self.external_root.rename(old);self.external_root.mkdir(mode=0o700);(old/'projection.json').rename(self.external_file)
+   return raw
+  with patch.object(m.os,'read',replace):self.refused()
 if __name__=='__main__':unittest.main(verbosity=2)
diff --git a/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/run-source-controls.py b/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/run-source-controls.py
index e4dbeb9..f543e70 100644
--- a/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/run-source-controls.py
+++ b/tests/Broker.NativeProof/RuntimeEvidence/fixtures/seed-attribution-helper/run-source-controls.py
@@ -17,7 +17,7 @@ def forbidden(*args,**kwargs):raise RuntimeError('portable source controls prohi
 suite=unittest.TestSuite()
 for index,name in enumerate(FILES):
  spec=importlib.util.spec_from_file_location('portable_seed_controls_'+str(index),ROOT/name);module=importlib.util.module_from_spec(spec);spec.loader.exec_module(module);suite.addTests(unittest.defaultTestLoader.loadTestsFromModule(module))
-expected=117
+expected=143
 if suite.countTestCases()!=expected:raise SystemExit('portable source control roster changed: '+str(suite.countTestCases()))
 result=unittest.TextTestRunner(verbosity=2).run(suite)
 if not result.wasSuccessful()or result.testsRun!=expected or result.skipped:raise SystemExit(1)