carta1 1.5.0 → 1.6.0

package/docs/native.md

@@ -0,0 +1,107 @@
+# Native Carta1 CLI
+
+Carta1's native CLI compiles the JavaScript codec to machine code with Porffor.
+The executable uses the OS C runtime and does not require Node.js. JavaScript
+packages and browser bundles continue to ship separately.
+
+## Download and run
+
+GitHub Releases include `carta1-VERSION-OS-ARCH.tar.gz` and a matching `.sha256`
+file. Targets are `linux-x64`, `linux-arm64`, `darwin-x64`, and `darwin-arm64`.
+Linux builds target Ubuntu 24.04/glibc; macOS ARM64 builds target macOS 14 and
+Intel builds target macOS 15. Native Windows and musl builds are not included.
+
+Extract the archive and run its `carta1` executable:
+
+```sh
+./carta1 --encode input.wav output.aea
+./carta1 --decode input.aea output.wav
+./carta1 --json input.aea structure.json
+./carta1 --help
+```
+
+The native CLI accepts the Node CLI's encode/decode/JSON operations and its
+quiet, force, UTF-8 title, allocation bias, and fixed block mode options.
+WAV input is mono/stereo signed little-endian 16/24/32-bit integer PCM.
+Decoding writes PCM16 WAV. Input is normally 44.1 kHz; other rates trigger a
+warning and are not resampled. JSON inspection escapes non-ASCII characters
+as Unicode escapes, preserving the same parsed data as Node.
+
+The native adapter processes complete files in memory and prints a completion
+line instead of an interactive progress bar. The Node CLI remains available
+for stream-based input processing. Existing output files require `--force`.
+The archive contains the executable, build metadata, this guide, Carta1's ISC
+license, and the Porffor runtime's MIT license.
+
+## Build and verify
+
+From the repository checkout, with Node.js and a system C compiler installed:
+
+```sh
+npm ci
+node build/install-porffor.js /tmp/carta1-toolchain
+export PORFFOR=/tmp/carta1-toolchain/porf
+npm run build:native
+npm run probe:porffor
+npm run test:native
+npm run package:native
+```
+
+The installer pins Porffor alpha 19 (`0c135ce`) and verifies the downloaded
+archive against a checked-in SHA-256. It does not change shell configuration.
+`PORFFOR` can instead select an already installed copy of that exact version.
+`CC` may select a C compiler executable without arguments.
+
+`build:native` writes `dist/native/carta1` and `build-info.json`. Its optional
+argument selects another binary output path. Compilation uses a temporary
+source tree and hardcodes the package version, so the executable needs no
+adjacent JavaScript files or `package.json`. C compilation always uses
+`-fno-fast-math -ffp-contract=off`: default floating-point contraction changed
+decoded sample bits in the initial experiment. Generated native files are
+excluded from the npm package.
+
+`probe:porffor` checks exact encoded bytes and float32 reconstruction bits for
+288 channel frames, public package startup with the native host, and native
+CLI help. `test:native` runs 58 WAV/AEA cases against the actual Node CLI,
+including independent stereo state, 16/24/32-bit input, partial/empty files,
+block modes and bias, UTF-8 titles and paths, JSON data, overwrite behavior,
+invalid input, and a 20-second stereo case that exercises garbage collection.
+Encoded AEA and decoded WAV files must match byte for byte.
+
+To include external corpus files and retain hash evidence:
+
+```sh
+CARTA1_NATIVE_CORPUS=/absolute/castanets.wav:/absolute/music.wav \
+CARTA1_KEEP_NATIVE_EVIDENCE=1 npm run test:native
+```
+
+Use the root harness with a native CLI adapter and `--jobs 1` for final ODG
+comparisons. Native release jobs also run the frame and file parity gates on
+each target machine before uploading archives.
+
+## Host implementation
+
+`native/host.js` supplies argument decoding, bounded binary reads, exclusive
+output creation, the UTF-8 operations needed by AEA titles, and the byte Blob
+operations used by the existing PCM facade. Its small C bridge relies on the
+pinned Porffor runtime's ArrayBuffer layout. The native CLI imports
+`codec/index.js` and reuses the existing container, serialization, timeline,
+and PCM conversions. WAV sample conversion and JSON inspection are shared
+with the Node CLI; the codec algorithm is unchanged.
+
+Complete-file helpers use synchronous frame operations on the same stateful
+stream classes used by async callers. This avoids a Porffor alpha 19
+async-generator queue crash on longer audio without disabling garbage
+collection or duplicating priming, tail flushing, or source-length trimming.
+Their public Promise-returning API is unchanged. The host's UTF-8 and Blob
+classes implement the surface needed by Carta1, rather than a general browser
+or Node compatibility layer.
+
+## GitHub release gate
+
+The reusable Native binaries workflow builds and tests all four targets on
+native GitHub runners. It runs in CI and is required by the tag-triggered
+publishing workflow. A failed native parity check prevents publishing.
+Successful jobs package versioned archives, build metadata, licenses, and
+SHA-256 checksums; the publishing job attaches them alongside browser/WME
+assets. The existing version-bump workflow still controls versioning and tags.

package/docs/porffor.md

@@ -0,0 +1,23 @@
+# Porffor investigation
+
+Carta1 can compile to machine code with Porffor alpha 19. The initial
+unadapted CLI failed at Node filesystem imports, and the public package failed
+at startup without TextEncoder. A native host now supplies the required
+operations; see [native builds, verification and release assets](native.md).
+
+The original frame-only test on macOS ARM64 used Carta1 1.5.0, Node 24.11.1,
+Apple Clang 16.0.0, and Porffor `alpha 19 (0c135ce 2026-10-21)`
+([compiler source](https://github.com/CanadaHonk/porffor/tree/0c135ce2f36fdd3467d5a58daa92283810705a51)).
+All 288 channel frames encoded identically under default C flags, but 8,708
+decoded float32 samples differed, with maximum absolute error about `1.19e-7`.
+Disabling C floating-point contraction restored exact sample-bit parity.
+The matched frame output SHA-256 was
+`413f72d3f2e1c7735f831e7c637b49d7757b3f76b6ff8df16fb8ee36a572a57d`.
+
+The repeatable `npm run probe:porffor` command now includes native host
+initialization and CLI help, and succeeds when those checks and strict frame
+parity pass. It keeps its binaries, complete output records, build logs and
+`report.json` in the printed temporary directory. It does not download a
+compiler or produce release assets. `npm run test:native` supplies the actual
+WAV/AEA release gate, including long-file coverage for the compiler runtime's
+async-generator limitation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carta1",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "An ATRAC1 audio codec implementation in JavaScript",
   "type": "module",
   "main": "codec/index.js",
@@ -10,7 +10,11 @@
   "files": [
     "bin/",
     "codec/",
-    "dist/",
+    "dist/*.js",
+    "dist/*.map",
+    "dist/*.wme",
+    "dist/wme/",
+    "docs/",
     "LICENSE",
     "README.md"
   ],
@@ -18,10 +22,14 @@
     "start": "node bin/cli.js",
     "test": "vitest run",
     "test:watch": "vitest",
+    "probe:porffor": "node build/porffor.js",
+    "build:native": "node build/native.js",
+    "test:native": "node --test tests/native-cli.integration.mjs",
+    "package:native": "node build/package-native.js",
     "prepare": "husky",
-    "lint": "eslint bin/ codec/ tests/",
+    "lint": "eslint bin/ build/ codec/ native/ tests/",
     "format": "prettier --write .",
-    "build": "webpack --config webpack.config.js && node bin/build-wme.js",
+    "build": "webpack --config webpack.config.js && node build/wme.js",
     "check": "npm run lint && npm test && npm run build && npm run test:wme",
     "prepublishOnly": "npm run check",
     "test:wme": "node --test tests/wme-build.integration.mjs"
@@ -70,7 +78,7 @@
     "webpack-cli": "^6.0.1"
   },
   "lint-staged": {
-    "(bin|codec|tests)/**/*.js": [
+    "(bin|build|codec|tests)/**/*.js": [
       "prettier --write",
       "eslint --fix"
     ]

package/bin/build-wme.js

@@ -1,69 +0,0 @@
-/** Package the bundled API v1 module and existing worker as a WME SAR archive.
- * Wire format: asivery/webminidisc src/services/audio/apiv1/external-archive.ts
- * (9637bed5), with big-endian lengths and metadata.json as the first entry.
- */
-import { readFile, writeFile } from 'node:fs/promises'
-import { fileURLToPath } from 'node:url'
-
-// The host imports blobs; relative source-map URLs cannot resolve there.
-function bundledScript(contents) {
-  return Buffer.from(
-    Buffer.from(contents)
-      .toString('utf8')
-      .replace(/^\/\/# sourceMappingURL=.*$/gm, '')
-  )
-}
-
-export function createWmeArchive(metadata, index, worker) {
-  const parts = [Buffer.from('SARFile')]
-  const subMagic = Buffer.from('Web MiniDisc Dynamic Encoder')
-  const length = Buffer.alloc(2)
-  length.writeUInt16BE(subMagic.length)
-  parts.push(length, subMagic)
-  for (const [name, contents] of [
-    ['metadata.json', Buffer.from(JSON.stringify(metadata))],
-    ['index.js', bundledScript(index)],
-    ['worker.js', bundledScript(worker)],
-  ]) {
-    const filename = Buffer.from(name)
-    const nameLength = Buffer.alloc(2)
-    nameLength.writeUInt16BE(filename.length)
-    const size = Buffer.alloc(4)
-    size.writeUInt32BE(contents.length)
-    parts.push(nameLength, filename, size, contents)
-  }
-  const archive = Buffer.concat(parts)
-  if (archive.length > 50 * 1024 * 1024) {
-    throw new RangeError('WME archive exceeds the host 50 MiB limit')
-  }
-  return archive
-}
-
-async function main() {
-  const root = new URL('../', import.meta.url)
-  const pkg = JSON.parse(await readFile(new URL('package.json', root), 'utf8'))
-  const [index, worker] = await Promise.all([
-    readFile(new URL('dist/wme/index.js', root)),
-    readFile(new URL(`dist/${pkg.name}-worker.min.js`, root)),
-  ])
-  const archive = createWmeArchive(
-    {
-      encoderId: pkg.name,
-      userFriendlyName: 'Carta1 (ATRAC1, experimental)',
-      description:
-        'ATRAC1 codec for standard MD SP stereo/mono. Experimental: requires host support for software ATRAC1; current Web MiniDisc API v1 is unsupported.',
-      version: pkg.version,
-      encoderDependencies: [],
-      apiVersion: '1',
-    },
-    index,
-    worker
-  )
-  const output = new URL(`dist/${pkg.name}.wme`, root)
-  await writeFile(output, archive)
-  console.log(`Built ${fileURLToPath(output)} (${archive.length} bytes)`)
-}
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-  await main()
-}