@brandry/claude-jsonl-compressor 1.0.0-rc.1 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 Notable public changes are recorded here. This project follows Semantic Versioning.
 
+## [Unreleased]
+
+## [1.0.0] - 2026-08-11
+
+### Added
+
+- Simplified Chinese and Japanese documentation for the public project.
+- Stable machine-readable `reasonCode` values for resume-path rejection.
+
+### Fixed
+
+- Enumerate Claude project sessions correctly beneath Windows 8.3 short-name roots.
+- Bound public diagnostics for malformed JSONL metadata without changing the
+  underlying validation or compression decisions.
+- Preflight file hard-link capability in the target directory and any explicit
+  backup directory before a live session is staged, backed up, or moved.
+- Retain and report live-transaction temporary paths whose observed identity or
+  bytes change before cleanup, including cleanup residue after an earlier
+  transaction failure.
+
+### Changed
+
+- Run the hard-link and transaction suite on Windows, Linux, and macOS CI
+  runner volumes and print their filesystem type as diagnostic evidence.
+- Promote the public npm package from release candidate to stable `1.0.0` on
+  the `latest` dist-tag.
+
 ## [1.0.0-rc.1] - 2026-07-28
 
 Initial public release candidate.
@@ -24,4 +51,6 @@ Initial public release candidate.
 - Live replacement handles one closed session at a time and requires Python 3.10 or newer.
 - Parent-directory durability is best effort where the platform does not support directory fsync.
 
+[Unreleased]: https://github.com/brandrylabs/claude-jsonl-compressor/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/brandrylabs/claude-jsonl-compressor/releases/tag/v1.0.0
 [1.0.0-rc.1]: https://github.com/brandrylabs/claude-jsonl-compressor/releases/tag/v1.0.0-rc.1

package/README.md

@@ -1,8 +1,10 @@
 # Claude JSONL Compressor
 
+[English](https://github.com/brandrylabs/claude-jsonl-compressor/blob/v1.0.0/README.md) | [简体中文](https://github.com/brandrylabs/claude-jsonl-compressor/blob/v1.0.0/docs/README.zh-CN.md) | [日本語](https://github.com/brandrylabs/claude-jsonl-compressor/blob/v1.0.0/docs/README.ja.md)
+
 Strict, model-assisted compression for one Claude Code session transcript, plus an independent byte-preserving compatibility repair for historical `Read.pages` records.
 
-**Release:** [`1.0.0-rc.1`](CHANGELOG.md)<br>
+**Release:** [`1.0.0`](CHANGELOG.md)<br>
 **Engine:** `v10`<br>
 **Model-pack schema:** `v11`<br>
 **License:** GPL-3.0-only<br>
@@ -94,9 +96,22 @@ Excluded records appear in reports only as counts and digests. Their text is not
 - Python 3.10 or newer
 - Node.js 22 or newer only when using the npm command wrappers
 - Claude Code is optional; it is needed only for an explicitly requested runtime `/resume` or `/context` smoke test
+- Hard-link support on the volume holding the target file, and on an explicitly configured backup directory, for `--replace-original` only
 
 No Python package installation is required.
 
+### Hard-link requirement for live replacement
+
+`--replace-original` publishes the candidate with `os.link` so that it never overwrites a concurrent claimant, and the rollback path restores the captured original the same way. The target directory must therefore support file hard links. An explicitly supplied `--backup-dir` also publishes numbered backups with a hard link and must support the same operation.
+
+Before live replacement staging, backup payload publication, or target movement, the compressor runs a unique, same-directory hard-link probe on the target volume. The probe briefly creates two dot-prefixed temporary files and removes them; a cleanup failure is reported with the retained probe name and stops the live operation. If the capability probe fails, the target remains at its original path and byte content, and no live replacement stage, backup payload, or target move has started. This probe is a capability check, not a guarantee against a later permission, quota, network, or concurrency failure; late publication, rollback, and cleanup failures are reported with their transaction state and verified recovery assets.
+
+Each unique live-transaction temporary path is checked against its recorded filesystem identity and frozen bytes before cleanup. A detected mismatch is retained and reported as `committed-cleanup-failed` after a committed candidate, or alongside the primary failure before commit. Portable Python cannot bind the final pathname `unlink` atomically to that earlier identity check across Windows, Linux, and macOS. Run live replacement only with the session closed and no other writer; hostile same-account directory manipulation is outside this guarantee.
+
+NTFS, APFS, ext4, XFS, and btrfs commonly support file hard links, while FAT/exFAT, some network shares, overlay or bind-mounted filesystems, and Windows ReFS may reject them. The probe is authoritative for the actual directory and account; the filesystem name alone is not treated as a guarantee. The repository CI runs the probe and transaction tests on Windows, Linux, and macOS runner volumes.
+
+Candidate output is unaffected: it publishes through `os.replace` and has no hard-link dependency.
+
 ## Installation
 
 ### Install As A Codex Skill
@@ -134,10 +149,10 @@ The installed directory must contain `SKILL.md`, `scripts/`, `config/`, `templat
 
 ### Install The npm CLI
 
-After the RC is published:
+After version 1.0.0 is published:
 
 ```bash
-npm install --global @brandry/claude-jsonl-compressor@rc
+npm install --global @brandry/claude-jsonl-compressor
 ```
 
 This installs two commands:
@@ -152,7 +167,7 @@ The npm package is a zero-dependency Node shim over the bundled Python implement
 Upgrade or uninstall the global CLI:
 
 ```bash
-npm install --global @brandry/claude-jsonl-compressor@rc
+npm install --global @brandry/claude-jsonl-compressor
 npm update --global @brandry/claude-jsonl-compressor
 npm uninstall --global @brandry/claude-jsonl-compressor
 ```
@@ -160,7 +175,7 @@ npm uninstall --global @brandry/claude-jsonl-compressor
 Local development install and invocation:
 
 ```bash
-npm install --save-dev @brandry/claude-jsonl-compressor@rc
+npm install --save-dev @brandry/claude-jsonl-compressor
 npm update @brandry/claude-jsonl-compressor
 npm exec -- claude-jsonl-compressor --version
 npm exec -- claude-jsonl-repair-read-pages --version
@@ -170,15 +185,15 @@ npm uninstall @brandry/claude-jsonl-compressor
 Run without retaining an installation:
 
 ```bash
-npx --yes --package @brandry/claude-jsonl-compressor@rc claude-jsonl-compressor --version
-npx --yes --package @brandry/claude-jsonl-compressor@rc claude-jsonl-repair-read-pages --version
+npx --yes --package @brandry/claude-jsonl-compressor claude-jsonl-compressor --version
+npx --yes --package @brandry/claude-jsonl-compressor claude-jsonl-repair-read-pages --version
 ```
 
 Actual npm/npx operations use the same Python CLI options:
 
 ```bash
-npx --yes --package @brandry/claude-jsonl-compressor@rc claude-jsonl-compressor --input session.jsonl --write-model-pack run/session.model-pack.md
-npx --yes --package @brandry/claude-jsonl-compressor@rc claude-jsonl-repair-read-pages --input session.jsonl --scan-only
+npx --yes --package @brandry/claude-jsonl-compressor claude-jsonl-compressor --input session.jsonl --write-model-pack run/session.model-pack.md
+npx --yes --package @brandry/claude-jsonl-compressor claude-jsonl-repair-read-pages --input session.jsonl --scan-only
 ```
 
 ### Use From Source Without Installing
@@ -209,6 +224,9 @@ python "$skill\scripts\compress_claude_jsonl.py" `
 ```
 
 This is read-only. A nonzero result must be resolved before model-pack generation.
+Use `reasonCode` for the exact machine-readable cause; `status` is only the
+coarse category. The stable value table is in
+[`references/claude-jsonl-compression-format.md`](references/claude-jsonl-compression-format.md#authoritative-last-prompt).
 
 ### 2. Generate A Model Evidence Pack
 
@@ -541,24 +559,24 @@ python -B -I -S scripts/compress_claude_jsonl.py --version
 python -B -I -S scripts/repair_claude_jsonl.py --version
 npm test
 npm pack --dry-run --json
-npm publish --dry-run --access public --tag rc
+npm publish --dry-run --access public --tag latest
 ```
 
 The release suite covers active/dead branch partitioning, fixed-seed topology transformations, strict pointer failures, dual model-pack budgets, complete structured token accounting, multilingual semantic ledgers and thinking, handoffs, request/claim digests, mandatory support excerpts, tool pairs, repeated compression, checkpoint policies, transaction races and committed-report states, exact byte repair, BOM/CRLF, npm tarball allowlisting and offline tarball installation.
 
-### Maintainer RC Release Checklist
+### Maintainer Stable Release Checklist
 
-1. Confirm a clean public tree and matching `1.0.0-rc.1` values in `package.json`, Python version output, docs, and tests.
+1. Confirm a clean public tree and matching `1.0.0` values in `package.json`, Python version output, docs, and tests.
 2. Run the Python, npm, isolated-Python, tarball, privacy, and offline-install gates above.
 3. Inspect `npm pack --dry-run --json`; publish only the allowlisted files.
-4. Require a clean worktree, create annotated tag `v1.0.0-rc.1`, and push the commit and tag.
-5. For the first manual RC, publish from an authenticated maintainer machine with npm 2FA:
+4. Require a clean worktree, create annotated tag `v1.0.0`, and push the commit and tag.
+5. Publish from an authenticated maintainer environment with permission to publish this package:
 
 ```bash
-npm publish --access public --tag rc
+npm publish --access public --tag latest
 ```
 
-6. Verify the npm version and `rc` dist-tag, then create the GitHub prerelease from the already-pushed tag.
+6. Verify npm version `1.0.0` and the `latest` dist-tag, then create a GitHub release (not a prerelease) from the already-pushed tag.
 
 Do not append `--provenance` to a local publish. npm provenance requires a supported cloud CI runner. For later releases, prefer npm trusted publishing from a public GitHub repository on a GitHub-hosted runner with `id-token: write`, a protected release tag, and a matching protected environment; trusted publishing generates provenance automatically.
 

package/SKILL.md

@@ -7,7 +7,7 @@ description: Compress one Claude Code JSONL session with strict active-branch is
 
 Operate on exactly one authoritative JSONL. Never merge another branch or session automatically.
 
-Public package: `1.0.0-rc.1`. Internal engine: `v10`. Model-pack schema: `v11`.
+Public package: `1.0.0`. Internal engine: `v10`. Model-pack schema: `v11`.
 
 ## Safety Invariants
 
@@ -73,6 +73,10 @@ python "$skill\scripts\compress_claude_jsonl.py" `
   --analyze-resume-path
 ```
 
+Use `reasonCode` as the exact machine-readable outcome and `status` only as its
+coarse category. The stable pairs are documented in
+`references/claude-jsonl-compression-format.md`.
+
 Strict active mode stops before writing any pack, candidate, sidecar or backup when the authority is absent, malformed, dangling, cyclic, has unsafe/recurring session lineage, has ordinary-message physical parent inversion, contains a malformed `parentUuid`, or is UUID-ambiguous.
 
 After partitioning, run the shared validator on the authoritative logical active chain plus its projected pointer. Old malformed tool exchanges, duplicate tool IDs, or compact-pair metadata on that chain must stop before semantic evidence generation; damage confined to excluded inactive branches remains excluded and does not become summary text.
@@ -336,5 +340,6 @@ Use `--scan-titles` only when the user supplies a title and permits title scanni
 - A source hash change aborts live replacement.
 - Live replacement requires the Claude process for that session to be closed. The transaction validates immutable candidate bytes, exclusively creates and verifies a numbered backup, captures the actual old target, verifies its full SHA-256, installs the candidate, and verifies the published bytes and structure. If another process recreates the target during capture, preserve the external target and recovery backups and fail without publishing. Parent-directory fsync is best effort and reported because platform support differs.
 - A write/fsync/validation/replace failure returns nonzero. The transaction restores the captured original bytes when replacement began; if restoration itself fails, it raises a high-priority error and retains the numbered backup for recovery.
+- Each unique live-transaction temporary path is checked against its recorded filesystem identity and frozen bytes before cleanup. A detected mismatch is retained and reported; a pre-commit failure also includes any cleanup residue in its error. Portable pathname cleanup cannot atomically bind that final delete to the earlier identity check across Windows, Linux, and macOS, so require a closed session and no other writer. Do not claim protection from hostile same-account directory manipulation.
 - If a valid live replacement commits but final sidecar/report publication fails, return exit code 3 with `committed-report-failed` and the committed hashes/backup labels. Do not rerun blindly or describe that state as an uncommitted failure.
 - Keep reports and temporary work outside `.claude`; do not leave ad hoc files in live session directories.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brandry/claude-jsonl-compressor",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0",
   "description": "Strict, model-assisted compression and byte-preserving compatibility repair for one Claude Code JSONL session.",
   "keywords": [
     "claude-code",
@@ -55,6 +55,6 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "rc"
+    "tag": "latest"
   }
 }

package/references/claude-jsonl-compression-format.md

@@ -1,7 +1,7 @@
 # Claude Code JSONL Compression Format Notes
 
 This document describes the empirical format handled by
-`@brandry/claude-jsonl-compressor` package `1.0.0-rc.1` and engine `v10`.
+`@brandry/claude-jsonl-compressor` package `1.0.0` and engine `v10`.
 
 Claude Code transcript JSONL is an observed internal format, not a published
 stable storage API. The rules below are deliberately strict where ambiguity
@@ -14,7 +14,7 @@ The project keeps four independent version domains:
 
 | Domain | Current value | Meaning |
 | --- | --- | --- |
-| Package | `1.0.0-rc.1` | GitHub/npm release version |
+| Package | `1.0.0` | GitHub/npm release version |
 | Compression engine | `v10` | Topology, partition, and rewrite behavior |
 | Model-pack schema | `v11` | Evidence-pack and model-summary binding protocol |
 | Report schema | `1` | Compression and repair report fields |
@@ -39,6 +39,38 @@ A transcript can contain records that play very different roles:
 
 Physical line order alone is therefore not a definition of current context.
 
+### Physical line accounting
+
+The JSONL framer recognizes records only at physical LF boundaries, removes a
+single CR before each LF, and skips blank physical lines. The parser keeps a
+trusted side map from each parsed record to its original 1-based physical line
+number. `validate_jsonl` and the `Read.pages` repair report use that map, so a
+blank line or an excluded branch cannot make an error point at the wrong file
+line. Input `_line`, `_mergedLines`, `_mergedUuids`, and
+`_validationContentLines` fields are untrusted and ignored; validation rebuilds
+record- and content-block provenance in an isolated projection.
+
+The model evidence pack uses its own `L<number>` logical nonblank-record
+coordinates because it is a reserialized evidence view; those anchors are not
+claims about physical source-file line numbers. Repair `recordLine`, validator
+diagnostic `line` fields, and the source active-chain preflight used by
+compression/model-pack generation, in contrast, refer to the original file's
+physical lines. The active-chain preflight is a logical projection, so it
+carries source-line provenance separately rather than renumbering the chain.
+
+Validation/report counters and `type`/`sessionId`/`subtype` metadata carried
+by validator or system-error diagnostics preserve ordinary short strings.
+Synthetic keys use the collision-safe angle-bracket namespace: `<missing>`,
+`<null>`, and `<invalid:json-type>`. A real string beginning with `<` is
+escaped by adding a second leading `<`; an unusually long real string is
+represented by a bounded `<string:length=...;sha256=...>` label that contains
+no original characters. Complex
+malformed values are labeled by JSON type rather than copied into diagnostics
+or model evidence. The same bound is applied recursively to public validator
+samples, nested diagnostic metadata, identifier-valued dictionary keys, and
+oversized source values embedded in error text. Ordinary error wording and
+physical-line locations remain readable when they contain only normal values.
+
 ## Common Observed Record Types
 
 | `type` | Observed purpose |
@@ -107,6 +139,39 @@ Strict topology statuses include:
 - `extension-unsafe`
 - `valid`
 
+`status` is the coarse category. `reasonCode` is the stable, machine-readable
+cause. Current producers emit exactly one of these pairs:
+
+| `status` | `reasonCode` | Meaning |
+| --- | --- | --- |
+| `absent` | `last-prompt-absent` | No authoritative `last-prompt` exists |
+| `duplicate-uuid` | `duplicate-uuid` | At least one UUID is ambiguous |
+| `malformed` | `leaf-uuid-malformed` | The authoritative `leafUuid` is absent, empty or not a string |
+| `dangling` | `chain-missing-uuid` | The selected chain references an unknown UUID |
+| `loop` | `chain-loop` | The selected chain contains a parent loop |
+| `malformed-parent` | `chain-malformed-parent` | A selected record has an invalid non-null `parentUuid` |
+| `dangling` | `chain-empty` | Defensive outcome when tracing returns no chain and no more specific error |
+| `non-monotonic` | `chain-non-monotonic` | Physical parent order violates the accepted compatibility rule |
+| `session-mismatch` | `lineage-unsafe` | Session ancestry is not an accepted one-way lineage |
+| `extension-limit` | `extension-limit-exceeded` | Post-pointer records exceed the explicit closure limit |
+| `session-mismatch` | `extension-authority-session-missing` | A requested closure has no usable authority session |
+| `extension-unsafe` | `extension-record-missing-uuid` | A closure record has no usable UUID |
+| `extension-branch` | `extension-record-not-linear-descendant` | A closure record is not the next direct child |
+| `session-mismatch` | `extension-record-session-mismatch` | A closure record does not match the authority session |
+| `extension-unsafe` | `extension-record-not-safe-closure` | A closure record is not a tool-result-only safe closure |
+| `extension-unsafe` | `extension-pending-tool-ids` | The requested closure leaves tool calls unresolved |
+| `valid` | `ok` | Strict topology validation succeeded |
+
+For `lineage-unsafe`, `lineageReason` carries the lower-level lineage diagnosis.
+Human-readable `errors` text is diagnostic and is not an enum. Normal
+compression/model-pack/repair failures also include `reasonCode=<value>` in the
+raised CLI error.
+
+Report-schema v1 objects and `compactMetadata` are open, additive objects:
+consumers must ignore unknown fields. Stable producers include `reasonCode` on
+every strict topology result. A pre-stable v1 artifact may lack it; readers
+should treat that as legacy/unknown rather than infer `ok`.
+
 `--resume-leaf UUID` is an explicit recovery override. It is reported as
 `active-chain-manual-override`, distinct from default strict `active-chain`.
 `--preserve-physical-tail` is a separate legacy compatibility
@@ -175,7 +240,7 @@ The engine emits exactly one current Codex-created compact pair:
 Simplified synthetic shape:
 
 ```json
-{"type":"system","subtype":"compact_boundary","uuid":"BOUNDARY_UUID","parentUuid":null,"compactMetadata":{"codexOfflineCompression":true,"codexOfflineCompressionVersion":"v10","modelPackSchemaVersion":11,"reportSchemaVersion":1,"summaryUuid":"SUMMARY_UUID","preserveMode":"active-chain","resumeLeafInfo":{"status":"valid","selectedLeafUuid":"ACTIVE_LEAF"}}}
+{"type":"system","subtype":"compact_boundary","uuid":"BOUNDARY_UUID","parentUuid":null,"compactMetadata":{"codexOfflineCompression":true,"codexOfflineCompressionVersion":"v10","modelPackSchemaVersion":11,"reportSchemaVersion":1,"summaryUuid":"SUMMARY_UUID","preserveMode":"active-chain","resumeLeafInfo":{"status":"valid","reasonCode":"ok","selectedLeafUuid":"ACTIVE_LEAF"}}}
 {"type":"user","uuid":"SUMMARY_UUID","parentUuid":"BOUNDARY_UUID","isCompactSummary":true,"message":{"role":"user","content":"SUMMARY_TEXT"}}
 ```
 
@@ -460,6 +525,19 @@ does not overwrite the external target. It preserves the verified numbered
 backup and, when necessary, places the captured original in another numbered
 backup, then fails without publishing the candidate.
 
+Before any live staging, backup payload publication, or target move, the
+implementation probes file hard-link support in the target directory and, when
+configured, the external backup directory. The probe itself briefly creates
+and removes unique dot-prefixed temporary files. Every unique live-transaction
+temporary path records its observed filesystem identity and frozen bytes.
+Cleanup rechecks both and retains a detected mismatch. A mismatch after commit is reported as
+`committed-cleanup-failed`; a mismatch while an earlier transaction failure is
+already active is appended to that failure. This is a best-effort race check,
+not a portable atomic identity-bound delete: standard Python pathname cleanup
+cannot eliminate a replacement between its final check and `unlink()` across
+Windows, Linux, and macOS. Live operation assumes Claude Code is closed and no
+other writer is manipulating the session directory.
+
 Candidate-mode reports are written with the candidate. Live compression delays
 its final sidecar/report until replacement metadata is available, so it does not
 leave a stale pre-commit report. If the JSONL commits and validates but final

package/scripts/claude_session_tools.py

@@ -36,6 +36,25 @@ def eprint(*parts: object) -> None:
 
 configure_stdio()
 
+MIN_SUPPORTED_PYTHON = (3, 10)
+
+
+def warn_if_python_too_old() -> Optional[str]:
+    """Warn on an unsupported interpreter without blocking the run."""
+    if sys.version_info >= MIN_SUPPORTED_PYTHON:
+        return None
+    running = ".".join(str(part) for part in sys.version_info[:3])
+    required = ".".join(str(part) for part in MIN_SUPPORTED_PYTHON)
+    message = (
+        f"WARNING: running on Python {running}; this project documents Python {required} or newer. "
+        "Continuing anyway. Unexpected errors may be caused by the interpreter version."
+    )
+    eprint(message)
+    return message
+
+
+warn_if_python_too_old()
+
 
 def read_jsonl_records(path: pathlib.Path) -> List[Dict[str, Any]]:
     records: List[Dict[str, Any]] = []
@@ -57,13 +76,25 @@ def list_session_files(root: pathlib.Path) -> List[pathlib.Path]:
     found: List[pathlib.Path] = []
     for dir_path, dir_names, file_names in os.walk(root, topdown=True, followlinks=False):
         directory = pathlib.Path(dir_path)
+        # Resolve the containing directory once and compare each child against
+        # `resolved_directory / name`. Comparing child.resolve() against
+        # os.path.abspath(child) instead would reject every entry whenever any
+        # component of the root is a Windows 8.3 short name, because resolve()
+        # expands short names to their long form and abspath() leaves them as
+        # written. A symlink or junction that leaves the directory still
+        # resolves somewhere other than resolved_directory / name, so the
+        # escape guard is unchanged.
+        try:
+            resolved_directory = directory.resolve()
+        except OSError:
+            dir_names[:] = []
+            continue
         safe_dirs: List[str] = []
         for name in dir_names:
             child = directory / name
             try:
                 resolved = child.resolve()
-                lexical = pathlib.Path(os.path.abspath(str(child)))
-                if resolved != lexical or not is_same_or_inside(resolved, root_resolved):
+                if resolved != resolved_directory / name or not is_same_or_inside(resolved, root_resolved):
                     continue
             except OSError:
                 continue
@@ -75,8 +106,7 @@ def list_session_files(root: pathlib.Path) -> List[pathlib.Path]:
             candidate = directory / name
             try:
                 resolved = candidate.resolve()
-                lexical = pathlib.Path(os.path.abspath(str(candidate)))
-                if resolved != lexical or not is_same_or_inside(resolved, root_resolved):
+                if resolved != resolved_directory / name or not is_same_or_inside(resolved, root_resolved):
                     continue
                 if not candidate.is_file():
                     continue