Add C# / .NET implementation of PCF (Partitioned Container Format)#1
Merged
Conversation
A faithful port of the Rust reference implementation under implementations/dotnet/, verified byte-for-byte against the spec's canonical 395-byte test vector (section 15). - Library (src/Pcf, netstandard2.0): Container reader/writer plus Constants, FileHeader, PartitionEntry, TableBlockHeader, the hash registry (SHA-1/2, MD5 via BCL; CRC-32/32C/64 self-contained; BLAKE3 via the Blake3 package), and PcfException error reporting. - xUnit tests (tests/Pcf.Tests, net8.0): spec-compliance, roundtrip and coverage suites (71 tests), including the exact 395-byte vector. - GitHub Actions workflow building and testing on Linux/macOS/Windows.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds a complete C# / .NET implementation of PCF v1.0, the first port of the Rust reference implementation. The implementation is fully spec-compliant and verified against the canonical 395-byte test vector from the specification.
Summary
Implements a production-ready PCF reader/writer library for .NET, targeting netstandard2.0 for broad compatibility. The implementation prioritizes auditability and spec compliance over performance, mirroring the design philosophy of the reference implementation.
Key Changes
Core Container API (
Container.cs): Full read/write support withCreate(),Open(),AddPartition(),UpdatePartitionData(),RemovePartition(), andVerify()operations. Implements the documented placement strategy with reserved capacity in the first block and overflow-block chaining for additional partitions.Data Structures:
FileHeader.cs: 20-byte file header with magic validation and version checkingTableBlockHeader.cs: 74-byte table-block header with partition count and chainingPartitionEntry.cs: 141-byte partition metadata with label encoding/decodingHashAlgo.cs: Registry of 9 hash algorithms (CRC-32/32C/64, MD5, SHA-1/256/512, BLAKE3)Hash Implementations:
Crc.cs: Self-contained reflected-CRC routines for all three CRC variants with canonical test vectorsSystem.Security.Cryptographyfor SHA and MD5Utility Classes:
LittleEndian.cs: Explicit little-endian integer encoding (spec section 2.3)Constants.cs: All normative on-disk constants from spec Appendix APcfError.cs/PcfException.cs: Comprehensive error handling mirroring reference implementationComprehensive Test Suite:
SpecComplianceTests.cs: 40+ tests covering every normative MUST/SHALL in the specification, organized by sectionRoundtripTests.cs: End-to-end black-box tests for create/read/update/remove/verify workflowsCoverageTests.cs: Error paths, algorithm variants, and edge casesTestSupport.cs: Canonical 395-byte test vector from spec section 15Project Configuration:
Notable Implementation Details
Block Capacity Tracking: In-memory
BlockInfoclass tracks reserved capacity per block; afterOpen(), blocks are treated as having no spare capacity, forcing new additions into overflow blocks.CompactedImage()rebuilds tightly packed files.Hash Field Encoding: Implements spec section 8.2 exactly—digests left-aligned and zero-padded to 64 bytes; CRC values stored as little-endian integers.
Overflow Chain: Supports arbitrary numbers of partitions (tested with 300+) via singly-linked table blocks, with automatic linking when blocks fill.
Spec Compliance: Validates all conformance checks (C1–C7) on read; rejects reserved type 0, nil UIDs, and invalid labels; verifies both table-block and partition-data hashes.
Cross-platform: Targets netstandard2.0 for .NET Framework 4.6.1+ and .NET Core 2.0+ compatibility.
https://claude.ai/code/session_01VVZyLAq1H1PKSFbDjTW7pa