Merge remote-tracking branch 'origin/master' into claude/confident-ramanujan-MqHwi

Author: claude

.github/workflows/build-binaries.yml

@@ -1,4 +1,4 @@
-name: Build Binaries
+name: Build / Cross-Platform Binaries
 
 on:
   push:

.github/workflows/ci-pfs.yml

@@ -1,4 +1,4 @@
-name: CI (PFS-MS)
+name: CI / Rust (PFS-MS Reference)
 
 on:
   push:
@@ -69,7 +69,7 @@ jobs:
       - name: Inspect generated test vector
         run: |
           ls -l pfs_ms_testvector.bin
-          test "$(wc -c < pfs_ms_testvector.bin)" = "2986"
+          test "$(wc -c < pfs_ms_testvector.bin)" = "3066"
       - uses: actions/upload-artifact@v4
         with:
           name: pfs-ms-testvector

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: CI
+name: CI / Rust (PCF Reference)
 
 on:
   push:

.github/workflows/dotnet-ci.yml

@@ -1,20 +1,22 @@
-name: .NET CI
+name: CI / .NET
 
 on:
   push:
     branches: [master]
     paths:
-      - 'implementations/dotnet/**'
+      - 'implementations/dotnet/pcf/**'
+      - 'implementations/dotnet/Directory.Build.props'
       - '.github/workflows/dotnet-ci.yml'
   pull_request:
     branches: [master]
     paths:
-      - 'implementations/dotnet/**'
+      - 'implementations/dotnet/pcf/**'
+      - 'implementations/dotnet/Directory.Build.props'
       - '.github/workflows/dotnet-ci.yml'
 
 defaults:
   run:
-    working-directory: implementations/dotnet
+    working-directory: implementations/dotnet/pcf
 
 jobs:
   test:

.github/workflows/php-split.yml

@@ -1,10 +1,10 @@
-name: PHP subtree split
+name: Sync / PHP Split Repository
 
 on:
   push:
     branches: [master]
     paths:
-      - 'implementations/php/**'
+      - 'implementations/php/pcf/**'
       - '.github/workflows/php-split.yml'
   workflow_dispatch:
     inputs:
@@ -22,7 +22,7 @@ on:
 
 jobs:
   split:
-    name: split implementations/php → kduma-OSS-splits/PHP-PCF-lib
+    name: split implementations/php/pcf → kduma-OSS-splits/PHP-PCF-lib
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -78,7 +78,7 @@ jobs:
         env:
           PAT: x-access-token:${{ steps.app-token.outputs.token }}
         with:
-          package_directory: 'implementations/php'
+          package_directory: 'implementations/php/pcf'
           repository_organization: 'kduma-OSS-splits'
           repository_name: 'PHP-PCF-lib'
           branch: 'master'
@@ -92,7 +92,7 @@ jobs:
           PAT: x-access-token:${{ steps.app-token.outputs.token }}
         with:
           tag: ${{ steps.resolve-tag.outputs.tag }}
-          package_directory: 'implementations/php'
+          package_directory: 'implementations/php/pcf'
           repository_organization: 'kduma-OSS-splits'
           repository_name: 'PHP-PCF-lib'
           branch: 'master'

.github/workflows/php.yml

@@ -1,4 +1,4 @@
-name: PHP CI
+name: CI / PHP
 
 on:
   push:
@@ -8,7 +8,7 @@ on:
 
 defaults:
   run:
-    working-directory: implementations/php
+    working-directory: implementations/php/pcf
 
 jobs:
   test:
@@ -66,4 +66,4 @@ jobs:
       - uses: actions/upload-artifact@v4
         with:
           name: pcf-testvector-php
-          path: implementations/php/pcf_testvector.bin
+          path: implementations/php/pcf/pcf_testvector.bin

.github/workflows/release-prepare.yml

@@ -1,4 +1,4 @@
-name: Prepare Release (bump versions, tag, trigger release)
+name: Release / Prepare
 
 on:
   workflow_dispatch:
@@ -82,16 +82,16 @@ jobs:
           sed -i 's|pcf = { path = "\.\./\.\./reference/PCF-v1.0", version = "[^"]*" }|pcf = { path = "../../reference/PCF-v1.0", version = "'"$NEW"'" }|' tools/pcf-debug/Cargo.toml
           sed -i 's|pcf = { path = "\.\./\.\./reference/PCF-v1.0", version = "[^"]*" }|pcf = { path = "../../reference/PCF-v1.0", version = "'"$NEW"'" }|' tools/pcf-compact/Cargo.toml
 
-      - name: Bump TypeScript package
+      - name: Bump TypeScript packages
         shell: bash
         working-directory: implementations/ts
-        run: npm version '${{ steps.version.outputs.version }}' --no-git-tag-version --allow-same-version
+        run: npm version '${{ steps.version.outputs.version }}' -ws --no-git-tag-version --allow-same-version
 
-      - name: Bump .NET Pcf.csproj
+      - name: Bump .NET Directory.Build.props
         shell: bash
         run: |
           NEW='${{ steps.version.outputs.version }}'
-          sed -i 's|<Version>[^<]*</Version>|<Version>'"$NEW"'</Version>|' implementations/dotnet/src/Pcf/Pcf.csproj
+          sed -i 's|<Version>[^<]*</Version>|<Version>'"$NEW"'</Version>|' implementations/dotnet/Directory.Build.props
 
       - name: Show diff
         run: git --no-pager diff --stat && git --no-pager diff

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: Release
+name: Release / Publish
 
 on:
   push:
@@ -162,13 +162,13 @@ jobs:
       - name: Ensure npm >= 11.5.1 (trusted publishing support)
         run: npm install -g npm@latest
       - run: npm ci
-      - run: npm run build
+      - run: npm run build -w @kduma-oss/pcf
       - name: npm publish (OIDC trusted publishing, auto-provenance)
         run: |
           if [ "${{ needs.resolve.outputs.dry_run }}" = "true" ]; then
-            npm publish --access public --dry-run
+            npm publish -w @kduma-oss/pcf --access public --dry-run
           else
-            npm publish --access public
+            npm publish -w @kduma-oss/pcf --access public
           fi
 
   publish-nuget:
@@ -180,7 +180,7 @@ jobs:
       contents: read
     defaults:
       run:
-        working-directory: implementations/dotnet
+        working-directory: implementations/dotnet/pcf
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-dotnet@v4
@@ -212,7 +212,7 @@ jobs:
       - uses: actions/upload-artifact@v4
         with:
           name: nuget-package
-          path: implementations/dotnet/out/*.nupkg
+          path: implementations/dotnet/pcf/out/*.nupkg
 
   split-php:
     name: Split PHP to packagist source repo

.github/workflows/ts-ci.yml

@@ -1,4 +1,4 @@
-name: TS CI
+name: CI / TypeScript
 
 on:
   push:
@@ -22,7 +22,7 @@ jobs:
           cache: npm
           cache-dependency-path: implementations/ts/package-lock.json
       - run: npm ci
-      - run: npm run build
+      - run: npm run build -w @kduma-oss/pcf
 
   test:
     name: test (${{ matrix.os }})
@@ -39,7 +39,7 @@ jobs:
           cache: npm
           cache-dependency-path: implementations/ts/package-lock.json
       - run: npm ci
-      - run: npm test
+      - run: npm test -w @kduma-oss/pcf
 
   test-vector:
     name: regenerate spec test vector
@@ -53,15 +53,15 @@ jobs:
           cache-dependency-path: implementations/ts/package-lock.json
       - run: npm ci
       - name: Build and run the test-vector example
-        run: npm run gen-testvector -- pcf_testvector.bin
+        run: npm run gen-testvector -w @kduma-oss/pcf -- pcf_testvector.bin
       - name: Inspect generated test vector
         run: |
-          ls -l pcf_testvector.bin
-          test "$(wc -c < pcf_testvector.bin)" = "395"
+          ls -l pcf/pcf_testvector.bin
+          test "$(wc -c < pcf/pcf_testvector.bin)" = "395"
       - uses: actions/upload-artifact@v4
         with:
           name: pcf-testvector-ts
-          path: implementations/ts/pcf_testvector.bin
+          path: implementations/ts/pcf/pcf_testvector.bin
 
   coverage:
     name: code coverage
@@ -75,8 +75,8 @@ jobs:
           cache-dependency-path: implementations/ts/package-lock.json
       - run: npm ci
       - name: Generate coverage report (enforces >=95% line / 100% function)
-        run: npm run coverage
+        run: npm run coverage -w @kduma-oss/pcf
       - uses: actions/upload-artifact@v4
         with:
           name: coverage-lcov-ts
-          path: implementations/ts/coverage/lcov.info
+          path: implementations/ts/pcf/coverage/lcov.info

implementations/README.md

@@ -0,0 +1,48 @@
+# Implementations
+
+Production implementations of the Partitioned Container Format family, one
+directory per language. Each language directory holds **one subfolder per
+library**, so that profiles built *on top of* PCF (e.g. PFS) can live next to it:
+
+```
+implementations/
+├── php/
+│   └── pcf/                     # kduma/pcf            (Packagist split)
+├── ts/
+│   ├── package.json             # npm workspace root (private)
+│   └── pcf/                     # @kduma-oss/pcf       (npm)
+└── dotnet/
+    ├── Directory.Build.props    # shared metadata + lockstep <Version>
+    └── pcf/                     # KDuma.Pcf            (NuGet)
+```
+
+The Rust reference under [`../reference/`](../reference/) is the canonical model:
+`PFS-MS-v1.0` depends on `PCF-v1.0` via a path dependency with a pinned version,
+and every package is versioned **in lockstep** by
+[`release-prepare.yml`](../../.github/workflows/release-prepare.yml).
+
+## Adding a library that depends on PCF (e.g. PFS)
+
+Drop a sibling folder (`…/pfs/`) next to `…/pcf/` and wire the dependency using
+the per-ecosystem mechanism below. Local development resolves against the
+on-disk PCF; published artifacts depend on the released PCF package.
+
+| Language | Dependency declaration in the PFS manifest | Local dev | Published |
+|----------|--------------------------------------------|-----------|-----------|
+| Rust     | `pcf = { path = "../pcf", version = "X" }` | source on disk | crates.io |
+| .NET     | `<ProjectReference Include="..\..\..\pcf\src\Pcf\Pcf.csproj" />` | project on disk | `dotnet pack` emits a NuGet dependency `KDuma.Pcf >= X` |
+| TS / npm | `"@kduma-oss/pcf": "^X"` + add `pfs` to the root `workspaces` array | workspace symlink to `../pcf` | npm registry |
+| PHP      | `repositories: [{ type: "path", url: "../pcf" }]` + `require: { "kduma/pcf": "^X" }` | path-repo symlink to `../pcf` | Packagist (path repo ignored downstream) |
+
+What each ecosystem already provides for "readiness":
+
+- **TypeScript** — `implementations/ts/package.json` is a private **npm
+  workspaces** root with a single hoisted `package-lock.json`. Add `"pfs"` to
+  `workspaces`; CI runs package scripts with `-w @kduma-oss/<pkg>`.
+- **.NET** — `implementations/dotnet/Directory.Build.props` holds the shared
+  package metadata and the single lockstep `<Version>`, auto-imported by every
+  project beneath it. A new library only declares its own `PackageId` /
+  `Description` and a `ProjectReference` to PCF.
+- **PHP** — each library is a self-contained Composer package that is mirrored to
+  its own Packagist repo by a split workflow. A new library gets its own
+  `composer.json` (with the path repo above) and a sibling split workflow.