Sub-scope 02 (fileserver) control plane + record codec + recovery verifier revision=a24ece9cf797f7ea647e33bf846b115208ed1ba5 generatedAt=2026-08-30T01:11:32+00:00 === OWNED FILES === 3b5849d179406ffb6158ecd510a8e1854e497480 main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java 1470 b94e783acb752ad603fef2ee6e990af1b8702abb main/java/dev/caskeleton/adapter/outbound/fileserver/FileserverControlRecordCodec.java 855 4a43965ba0b17699aa5d0718439f1c73c29922c6 main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentRecoveryVerifier.java 210 a948982e8ab0e192b7d2087091b59f256b2bdef7 test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java 2087 8ad022d5671c15e7b7ed765b1c1e0602eb27646a test/java/dev/caskeleton/adapter/outbound/fileserver/FileserverControlRecordCodecTest.java 924 1b22d273beaa63093ba81574389a687a559de0be test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentCrashRecoveryTest.java 229 main LOC: 2535 total test LOC: 3240 total === 8.1 reachability: who constructs / calls the three types === $ git grep -rn 'new LocalPersistentControlPlane\|new FileserverControlRecordCodec\|new LocalPersistentRecoveryVerifier' -- . | grep -v '^Binary' adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/FileserverControlRecordCodec.java:429: FilePublishReceipt receipt = new FileserverControlRecordCodec().decodeReceiptSnapshot(snapshot); adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/FileserverR2Config.java:51: new LocalPersistentControlPlane(attestor, evidence); adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:67: new FileserverControlRecordCodec(), adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:81: new FileserverControlRecordCodec(), adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:111: new FileserverControlRecordCodec(), adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:128: new FileserverControlRecordCodec(), adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:139: return new LocalPersistentControlPlane( adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:142: new FileserverControlRecordCodec(), adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:904: return new LocalPersistentControlPlaneException(FailureKind.CONFLICT, message); adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:908: return new LocalPersistentControlPlaneException(FailureKind.INTEGRITY, message); adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:912: return new LocalPersistentControlPlaneException(FailureKind.INTEGRITY, message, cause); adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:916: return new LocalPersistentControlPlaneException(FailureKind.STORAGE, message); adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java:920: return new LocalPersistentControlPlaneException(FailureKind.STORAGE, message, cause); adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentPublicationProvider.java:46: new FileserverControlRecordCodec(), adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentPublicationProvider.java:47: new LocalPersistentRecoveryVerifier()); adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentRecoveryVerifier.java:27: this(new FileserverControlRecordCodec(), new R2PublishedReferenceCodec()); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/FileserverControlRecordCodecTest.java:32: private final FileserverControlRecordCodec codec = new FileserverControlRecordCodec(); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/FileserverCrashScenarioMain.java:443: new LocalPersistentControlPlane(attestor, evidence), adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:97: .contains(new LocalPersistentControlPlane.R2StoredOperationRecord(writingRecord())); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:106: .contains(new LocalPersistentControlPlane.R1StoredOperationRecord(published)); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:663: new FileserverControlRecordCodec().encodeOperation(writingRecord()), adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:674: new FileserverControlRecordCodec() adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:697: new FileserverControlRecordCodec() adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:706: new FileserverControlRecordCodec() adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1423: return new LocalPersistentControlPlane.FaultContext( adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1427: new LocalPersistentControlPlane.OperationFaultState( adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1435: return new LocalPersistentControlPlane.FaultContext(kind, FILE_ID, Optional.empty(), boundary); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1554: ? new FileserverControlRecordCodec() adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1909: return new LocalPersistentControlPlane(attestor, evidence); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1914: return new LocalPersistentControlPlane(attestor, evidence, faultCallback); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1927: return new LocalPersistentControlPlane( adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1933: return new LocalPersistentControlPlane( adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:2074: new LocalPersistentControlPlane.SecureRecordCall(topDirectory, shard, relativeFileName)); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentPublicationProviderTest.java:284: new FileserverControlRecordCodec().decodeReceiptSnapshot(operation.receiptSnapshot())) adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentPublicationProviderTest.java:401: return new LocalPersistentControlPlane(attestor, evidence); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentPublicationRecoveryTest.java:386: new FileserverControlRecordCodec() adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentPublicationRecoveryTest.java:395: new FileserverControlRecordCodec() adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentPublicationRecoveryTest.java:516: FileserverControlRecordCodec codec = new FileserverControlRecordCodec(); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentPublicationRecoveryTest.java:1003: rewriteRecord(target, new FileserverControlRecordCodec().encodeOperation(record)); exit=0 $ git grep -rln 'LocalPersistentControlPlane\|FileserverControlRecordCodec\|LocalPersistentRecoveryVerifier' -- . | grep -v "^adapter/outbound/fileserver/" | head exit=0 === 8.2 conditional siblings: the two lock scopes inside one class === $ grep -n 'scopedOperationLockKey\|operationLockRootKey +' -A 3 adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java | head -20 194: String scopedLockKey = scopedOperationLockKey(token); 195- Set heldTokens = HELD_OPERATION_TOKENS.get(); 196- if (heldTokens != null && heldTokens.contains(scopedLockKey)) { 197- storeOperationUpdate(target, record); -- 208: String scopedLockKey = scopedOperationLockKey(token); 209- Path lockPath = operationsDirectory.resolve(token.substring(0, 2)).resolve(token + ".lock"); 210- ReentrantLock jvmLock = 211- OPERATION_LOCK_STRIPES[ -- 259: return heldTokens != null && heldTokens.contains(scopedOperationLockKey(sha256(operationId))); 260- } 261- 262- boolean operationLockStripeHeldByCurrentThread(String operationId) { -- 264: String scopedLockKey = scopedOperationLockKey(sha256(operationId)); 265- return OPERATION_LOCK_STRIPES[ 266- Math.floorMod(scopedLockKey.hashCode(), OPERATION_LOCK_STRIPE_COUNT)] 267- .isHeldByCurrentThread(); -- exit=0 $ grep -n 'withImmutableLock' -A 12 adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java | head -30 300: withImmutableLock( 301- "manifest:" + manifest.fileId(), 302- () -> 303- storeImmutable( 304- target, 305- codec.encodeManifest(manifest), 306- codec::decodeManifest, 307- manifest, 308- existing -> existing.fileId().equals(manifest.fileId()))); 309- } 310- 311- Optional findManifest(String fileId) { 312- FileserverControlRecordCodec.requireFileId(fileId); -- 328: withImmutableLock( 329- "reference:" + reference.fileId(), 330- () -> 331- storeImmutable( 332- target, 333- codec.encodeReference(reference), 334- codec::decodeReference, 335- reference, 336- existing -> existing.fileId().equals(reference.fileId()))); 337- } 338- 339- Optional findReference(String fileId) { 340- FileserverControlRecordCodec.requireFileId(fileId); -- 859: private static void withImmutableLock(String key, Runnable action) { 860- ReentrantLock lock = exit=0 $ grep -n 'IMMUTABLE_LOCK_STRIPES\|OPERATION_LOCK_STRIPES' adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java 43: private static final ReentrantLock[] OPERATION_LOCK_STRIPES = createOperationLockStripes(); 44: private static final ReentrantLock[] IMMUTABLE_LOCK_STRIPES = createOperationLockStripes(); 211: OPERATION_LOCK_STRIPES[ 265: return OPERATION_LOCK_STRIPES[ 861: IMMUTABLE_LOCK_STRIPES[Math.floorMod(key.hashCode(), OPERATION_LOCK_STRIPE_COUNT)]; exit=0 === 8.2b which write primitive each path uses (why the lock shapes differ) === $ grep -n 'Files.move\|Files.createLink' -B 2 -A 2 adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java 436- verifyAttestedIdentity(); 437- if (replaceExisting) { 438: Files.move( 439- temporary, target, StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING); 440- } else { 441- try { 442: Files.createLink(target, temporary); 443- } catch (FileAlreadyExistsException collision) { 444- verifyAttestedIdentity(); exit=0 === 8.2c requireOperationLockRootHealthy: write paths vs read paths === $ grep -n 'requireOperationLockRootHealthy()' adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java 188: requireOperationLockRootHealthy(); 213: requireOperationLockRootHealthy(); 218: requireOperationLockRootHealthy(); 231: requireOperationLockRootHealthy(); 298: requireOperationLockRootHealthy(); 326: requireOperationLockRootHealthy(); 768: private void requireOperationLockRootHealthy() { exit=0 $ grep -n 'Optional findOperation\|Optional findManifest\|Optional findReference\|Optional findStoredOperation' -A 4 adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java | grep -n 'requireOperationLockRootHealthy' || echo ' (no health gate on any find* path)' (no health gate on any find* path) exit=0 $ grep -n 'poisonedRootBlocksEveryWriteIncludingHeldLockFastPathButAllowsReads' -A 12 adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java 1066: void poisonedRootBlocksEveryWriteIncludingHeldLockFastPathButAllowsReads() throws Exception { 1067- ControlFixture fixture = controlFixture(); 1068- LocalPersistentControlPlane healthy = fixture.controlPlane(); 1069- healthy.storeOperation(writingRecord()); 1070- healthy.storeManifest(manifest()); 1071- healthy.storeReference(referenceRecord()); 1072- 1073- LocalPersistentControlPlane.OperationLock held = healthy.acquireOperationLock(OPERATION_ID); 1074- RecordingLockLifecycle lifecycle = new RecordingLockLifecycle(true, true); 1075- LocalPersistentControlPlane poisoner = fixture.controlPlane(lifecycle); 1076- ExecutorService executor = Executors.newSingleThreadExecutor(); 1077- try { 1078- assertFutureFailureKind( exit=0 === 8.3 duplicate mechanism: is POISONED set ever cleared? === $ grep -n 'POISONED_OPERATION_LOCK_ROOTS' adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java 46: private static final Set POISONED_OPERATION_LOCK_ROOTS = ConcurrentHashMap.newKeySet(); 769: if (POISONED_OPERATION_LOCK_ROOTS.contains(operationLockRootKey)) { 899: POISONED_OPERATION_LOCK_ROOTS.add(operationLockRootKey); 1433: POISONED_OPERATION_LOCK_ROOTS.add(rootKey); exit=0 $ git grep -rn 'POISONED_OPERATION_LOCK_ROOTS\|poison' -- 'adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver' | head adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1018: ControlFixture poisonedRoot = controlFixture(); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1020: LocalPersistentControlPlane poisoned = poisonedRoot.controlPlane(lifecycle); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1021: LocalPersistentControlPlane.OperationLock lock = poisoned.acquireOperationLock(OPERATION_ID); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1024: assertThat(poisoned.operationLockHeldByCurrentThread(OPERATION_ID)).isFalse(); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1025: assertThat(poisoned.operationLockStripeHeldByCurrentThread(OPERATION_ID)).isFalse(); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1035: poisoned.acquireOperationLock(OPERATION_ID)) { adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1036: throw new AssertionError("poisoned root unexpectedly acquired a lock"); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1041: executor.submit(() -> poisoned.storeOperation(writingRecord()))); adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1047: poisonedRoot.controlPlane().acquireOperationLock(OPERATION_ID)) { adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java:1048: throw new AssertionError("same-root instance ignored the poison latch"); exit=0 === 8.3b the R1 fallback path inside decodeStoredOperation === $ grep -n 'decodeStoredOperation' -A 20 adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlane.java | head -26 286: find(operationPath(operationId), this::decodeStoredOperation); 287- result.ifPresent( 288- record -> { 289- if (!record.operationId().equals(operationId)) { 290- throw integrity("operation control record identity mismatch"); 291- } 292- }); 293- return result; 294- } 295- 296- void storeManifest(PrivateFileManifest manifest) { 297- Objects.requireNonNull(manifest, "manifest must be non-null"); 298- requireOperationLockRootHealthy(); 299- Path target = fileRecordPath(manifestsDirectory, manifest.fileId()); 300- withImmutableLock( 301- "manifest:" + manifest.fileId(), 302- () -> 303- storeImmutable( 304- target, 305- codec.encodeManifest(manifest), 306- codec::decodeManifest, -- 629: private StoredOperationRecord decodeStoredOperation(byte[] encoded) { 630- try { 631- return new R2StoredOperationRecord(codec.decodeOperation(encoded)); 632- } catch (RuntimeException versionTwoFailure) { exit=0 $ grep -n 'typedOperationLookupDispatchesCanonicalR2AndTerminalR1' -A 8 adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentControlPlaneTest.java 91: void typedOperationLookupDispatchesCanonicalR2AndTerminalR1FromTheSameHashedPath() 92- throws IOException { 93- ControlFixture r2Fixture = controlFixture(); 94- r2Fixture.controlPlane().storeOperation(writingRecord()); 95- 96- assertThat(r2Fixture.controlPlane().findStoredOperation(OPERATION_ID)) 97- .contains(new LocalPersistentControlPlane.R2StoredOperationRecord(writingRecord())); 98- 99- ControlFixture r1Fixture = controlFixture(); exit=0 === 8.4 doc/claim drift: what README says this layer guarantees === $ grep -n 'WRITING -> SEALED\|forced control plane\|Operation-scoped JVM and OS file locks' -A 2 adapter/outbound/fileserver/README.md 30:forces a private stage, and advances the forced control plane through: 31- 32-```text 33:WRITING -> SEALED -> DATA_PUBLISHED -> MANIFEST_PUBLISHED 34- -> REFERENCE_PUBLISHED -> PUBLISHED 35-``` exit=0 $ grep -n 'State {' -A 20 adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/DurablePublicationRecord.java | head -30 236: enum State { 237- WRITING(1), 238- SEALED(2), 239- DATA_PUBLISHED(3), 240- MANIFEST_PUBLISHED(4), 241- REFERENCE_PUBLISHED(5), 242- PUBLISHED(6), 243- QUARANTINED(2); 244- 245- private final long minimumRevision; 246- 247- State(long minimumRevision) { 248- this.minimumRevision = minimumRevision; 249- } 250- 251- long minimumRevision() { 252- return minimumRevision; 253- } 254- } 255-} exit=0 $ grep -n 'crash\|fork' adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentCrashRecoveryTest.java | head -12 39: Path root = temporaryDirectory.resolve("crash-" + boundary.name().toLowerCase(Locale.ROOT)); 41: ChildResult crashed = runChild("CRASH", root, boundary.name()); 43: assertThat(crashed.exitCode()).isEqualTo(FileserverCrashScenarioMain.CRASH_EXIT_CODE); 44: assertThat(crashed.output()).isEmpty(); 108: throw new AssertionError("forked Fileserver scenario exceeded its bounded timeout"); 156: throw new AssertionError("forked lock holder exited before its protocol marker"); 160: throw new AssertionError("forked lock holder exceeded its bounded marker timeout"); exit=0 $ git ls-files 'adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver' | xargs grep -ln 'FileserverCrashScenarioMain' | head adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/FileserverCrashScenarioMain.java adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/LocalPersistentCrashRecoveryTest.java exit=0