feat(contract): machine-readable ACP block contract — schemaVersion + ./contract export (#368) - #369
Open
ranxianglei wants to merge 1 commit into
Open
feat(contract): machine-readable ACP block contract — schemaVersion + ./contract export (#368)#369ranxianglei wants to merge 1 commit into
ranxianglei wants to merge 1 commit into
Conversation
… ./contract export (#368) Additive-only, zero behavior change. Gives downstream tools a stable, versioned boundary for reading compressed blocks instead of globbing private sidecar fields. - R1: sidecar top-level envelope { schemaVersion, producer:{name,version} } written by SessionStateStore.save(); load() treats missing==v1 and, on an unknown-higher version, stays tolerant (loads known fields) while logging once per file so a downgrade is observable rather than silent. - R2: new billion-context-pi/contract subpath exporting BcpBlockV1, SCHEMA_VERSION, PRODUCER_NAME, createSidecarEnvelope; plus schema/bcp-block-v1.json (JSON Schema, shipped in the package). - R3: document the tmp+rename atomic-write promise in README. Tests: tests/contract.test.ts (schema<->type drift guard, envelope builder) and tests/state.test.ts (envelope written; tolerant higher-version load).
📦 Built Extension ArtifactBranch: Option A — Install from npm PR tag (recommended)pi install npm:billion-context-pi@pr-369Each push to this PR publishes a new version under the Option B — Download artifact
tar xzf billion-context-pi-pr369.tgz
pi install ./packageThis comment is automatically updated on each push. |
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
1 participant
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.
Machine-readable, versioned contract for ACP compression blocks — closes #368. Purely additive; zero behavior change (no sidecar relocation, no pi-integration change, no version bump).
Downstream tools (e.g. pi-billion-memory) today glob
~/.pi/agent/sessions/**/*.jsonl.acp.jsonand parse private fields. This gives them a stable boundary so a field rename or path move degrades loudly (version mismatch) instead of silently scanning 0 files and surfacing back as a “did bcp change the format?” issue.R1 — versioned sidecar envelope
Every
<session>.acp.jsonnow carries a top-level{ schemaVersion, producer:{name,version} }, written at the single choke pointSessionStateStore.save()(src/state.ts). Semantics:schemaVersion== v1 — legacy files keep loading unchanged;unknown-schema-versiononce per file, so a downgrade is observable rather than silent;R2 — public exports + JSON Schema
New subpath
billion-context-pi/contract:Plus
schema/bcp-block-v1.json(JSON Schema, shipped in the npm package viafiles).BcpBlockV1required stable core:blockId,summary,tier,compressedTokens,createdAt(epoch milliseconds, not ISO 8601); optionaltopic/startRef/endRef/effectiveMessageIds. Internal pruning/index fields are intentionally outside the contract (additionalProperties: true).R3 — atomic-write promise
Documented in README: the sidecar is written as temp file +
rename(), so a reader never observes a half-written file — safe to watermark on mtime/size and always replace the whole file. The file remains the source of truth across process restarts.Deferred (issue marked these optional / later)
R4 (
pi.events.emit("bcp:blocks")), R5 (boundedcompress.details), P3 (pi.appendEntry) are not included — they're behavior/event additions the issue listed as optional. Happy to follow up if wanted.Verification
Rebased onto current master (v0.1.66,
acp-kernel@0.0.63):npm run typecheck✓npm test→ 700 pass / 0 fail / 3 skipped ✓npm run build✓ — emitsdist/contract.js+dist/contract.d.ts; runtime smoke-test of the built module passes.Tests added:
tests/contract.test.ts(schema↔type drift guard + envelope builder) and two cases intests/state.test.ts(envelope written to sidecar; tolerant higher-version load).