ds4-context-engine 0.3.0-beta.2 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ bounded active context with provenance
 Pi provider
 ```
 
-> **Project status:** Stable `0.2.0` includes M0–M20 and frozen 0.2 contracts. Candidate `0.3.0-beta.2` carries forward beta.1's bounded Context Manifest storage, cooperative database leases, metadata-only storage diagnostics, and explicit offline inspect/compact/recover maintenance after successful live maintenance validation. Canonical records, SQLite schema 15, and runtime contracts remain unchanged. Until publication, npm `beta` remains `0.3.0-beta.1`, `alpha` remains `0.3.0-alpha.5`, `latest` remains `0.2.0`, and the maintenance line targets Pi `0.84.3`.
+> **Project status:** Stable `0.2.0` includes M0–M20 and frozen 0.2 contracts. Published prerelease `0.3.0-beta.2` carries forward beta.1's bounded Context Manifest storage, cooperative database leases, metadata-only storage diagnostics, and explicit offline inspect/compact/recover maintenance after successful live maintenance validation. Canonical records, SQLite schema 15, and runtime contracts remain unchanged. npm `beta` points to `0.3.0-beta.2`, `alpha` remains `0.3.0-alpha.5`, `latest` remains `0.2.0`, and the maintenance line targets Pi `0.84.3`.
 
 ## Why DS4
 
@@ -493,7 +493,7 @@ scripts             package and release-readiness checks
 
 The original M0–M13 roadmap is complete. `ds4-context-core` contains the compiled runtime-neutral implementation. M14 context-quality metrics, M15 rich symbol indexing, M16 hybrid semantic retrieval, M17 cross-session project memory, M18 learned-ranking shadow evaluation, M19's runtime adapter/conformance kit, and M20 opt-in local KV eligibility/replay are implemented on `main`. Learned active ranking remains promotion-gated, Pi reports local KV as unsupported, and static ranking/native completion stay authoritative on every failure.
 
-The [0.2.0 roadmap](docs/ROADMAP_0.2.0.md) is complete. Candidate `0.3.0-beta.2` carries forward the [context persistence tool](docs/CONTEXT_PERSISTENCE_TOOL.md), privacy-safe [compaction](docs/COMPACTION.md) hardening, bounded persisted manifests, per-profile calibration retention, cooperative client leases, storage diagnostics, and recoverable offline maintenance, with successful live maintenance evidence from beta.1. Confirmation, exact targeting, strict summary grounding, Pi fallback, and stable canonical/configuration/SQLite/runtime contracts remain unchanged. The [0.2 readiness record](docs/RELEASE_READINESS_0.2.0.md) remains the compatibility baseline. Sensitive or transport-specific behavior remains opt-in, and the 0.1 lexical planner stays available as the deterministic fallback.
+The [0.2.0 roadmap](docs/ROADMAP_0.2.0.md) is complete. Published prerelease `0.3.0-beta.2` carries forward the [context persistence tool](docs/CONTEXT_PERSISTENCE_TOOL.md), privacy-safe [compaction](docs/COMPACTION.md) hardening, bounded persisted manifests, per-profile calibration retention, cooperative client leases, storage diagnostics, and recoverable offline maintenance, with successful live maintenance evidence from beta.1. Confirmation, exact targeting, strict summary grounding, Pi fallback, and stable canonical/configuration/SQLite/runtime contracts remain unchanged. The [0.2 readiness record](docs/RELEASE_READINESS_0.2.0.md) remains the compatibility baseline. Sensitive or transport-specific behavior remains opt-in, and the 0.1 lexical planner stays available as the deterministic fallback.
 
 ## Contributing
 

package/docs/releases/0.3.0-beta.2.md

@@ -1,6 +1,6 @@
 # DS4 Context Engine 0.3.0-beta.2
 
-Status: release candidate; publication pending.
+Status: published on 2026-09-03 under the npm `beta` dist-tag.
 
 This coordinated beta carries forward beta.1 without changing canonical records, SQLite schema, runtime contracts, retention limits, privacy policy, compaction validation, or fallback semantics. It incorporates the operational evidence from a successful maintenance of the live derived SQLite projection and documents how to retain an interactive confirmation when recording a maintenance transcript.
 
@@ -55,7 +55,7 @@ ds4-context-reference-adapter
 ds4-context-engine
 ```
 
-Both adapters depend exactly on `ds4-context-core@0.3.0-beta.2`. Publication must use the explicit npm `beta` dist-tag for all three packages. npm `latest` must remain stable `0.2.0`, and GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+Both adapters depend exactly on `ds4-context-core@0.3.0-beta.2`. Publication used the explicit npm `beta` dist-tag for all three packages. npm `latest` remains stable `0.2.0`, and GitHub Actions remains validation-only with OIDC and package-write permissions denied.
 
 ## Candidate validation
 
@@ -71,7 +71,25 @@ Local candidate verification on Node.js `26.5.1`:
 - `git diff --check` passed; the only pre-existing untracked path is `.serena/`, which is excluded from commits and package inventories.
 - Version, exact core dependencies, package-lock entries, extension constant, and reference-adapter constant are synchronized to `0.3.0-beta.2`.
 
-Validation-only CI on the committed candidate remains required before publication. Exact post-publication registry verification, the annotated tag, and the GitHub prerelease remain pending until the candidate and published artifacts pass their respective gates.
+Validation-only CI run [`33762010502`](https://github.com/Alucard24/ds4-context-engine/actions/runs/33762010502) passed on Node.js `22.19.0` and `24.x` for candidate commit `e1dab370ea290da601c817aa358e9c384d4b068c`.
+
+## Registry evidence
+
+Exact post-publication verification passed for all three `0.3.0-beta.2` packages. The clean registry consumer verified exact adapter/core dependencies, public core exports, compiled reference-adapter conformance, packaged quality corpus, packaged Pi extension startup, and the installed `ds4-context-storage` CLI declaration, shim, and usage probe.
+
+Published package shasums:
+
+```text
+ds4-context-core:              d9cc4d10756b984aa8a9078fcad05675b09b327e
+ds4-context-reference-adapter: 6a9a829cf072ed613a5eec0756f967da81f481b4
+ds4-context-engine:            965f65d8d350f712a0bcb0a416d1eebef46f82cd
+```
+
+For all three packages, npm `beta` resolves to `0.3.0-beta.2`, `alpha` remains `0.3.0-alpha.5`, `rc` remains `0.2.0-rc.1`, and `latest` remains `0.2.0`.
+
+npm emitted a publish-time auto-correction warning for the root `bin` entry. The exact registry smoke independently confirmed that the published manifest still declares `ds4-context-storage`, a fresh install creates its shim, and the installed command returns the expected bounded usage response. The warning did not remove the CLI from the published artifact.
+
+Annotated tag `v0.3.0-beta.2` targets verified registry-evidence commit `8323fb74fca286c512ea04efab54aa6065c8d315`. The GitHub prerelease is published at <https://github.com/Alucard24/ds4-context-engine/releases/tag/v0.3.0-beta.2>.
 
 ## Documentation
 

package/docs/releases/0.3.0-beta.3.md

@@ -0,0 +1,83 @@
+# DS4 Context Engine 0.3.0-beta.3
+
+Status: published on 2026-09-03 under the npm `beta` dist-tag.
+
+This coordinated beta fixes storage maintenance on Windows and carries forward beta.2 without changing canonical records, SQLite schema, runtime contracts, retention limits, privacy policy, compaction validation, or fallback semantics.
+
+## Fixed since beta.2
+
+- `compactStorage()` now opens stage/state/source files for the durability flush with write access (`"r+"`). `fsyncPath` previously opened them read-only, which fails on Windows with `EPERM` (`FlushFileBuffers` requires write access), aborting `compact` with `stage=compact; category=maintenance-failed` before the backup could be verified. The failure was confirmed on Windows with a minimal probe:
+
+  ```text
+  fsync-on-readonly-handle: FAIL code=EPERM
+  ```
+
+- The flush now mirrors `fsyncDirectory`'s best-effort policy for platforms that cannot flush (`EINVAL`, `ENOTSUP`, `EBADF`, `EPERM`, `EACCES`), while still flushing normally on supported platforms. No content is written by the `"r+"` open.
+
+- Coordinated package versions moved to `0.3.0-beta.3`.
+
+There are no functional storage-format or provider-path changes relative to beta.2.
+
+## Safety and compatibility
+
+Unchanged from beta.2: Pi JSONL remains canonical and append-only; SQLite remains disposable and rebuildable; physical maintenance remains explicit, offline, local-TTY-only, and unavailable to model-callable tools; every `context_persistence` write still requires a fresh positive local UI decision.
+
+Compatibility remains unchanged:
+
+- SQLite schema: `15`;
+- configuration: `ds4-context-config-v1`;
+- runtime adapter: `runtime-adapter-v1`;
+- persistence tool: `ds4-context-persistence-tool-v1`;
+- persistence result: `ds4-context-persistence-result-v1`;
+- Pi: `0.84.3`;
+- Node.js: `>=22.19.0`.
+
+## Package/version policy
+
+The coordinated version is `0.3.0-beta.3` for:
+
+```text
+ds4-context-core
+ds4-context-reference-adapter
+ds4-context-engine
+```
+
+Both adapters depend exactly on `ds4-context-core@0.3.0-beta.3`. Publication used the explicit npm `beta` dist-tag for all three packages. npm `latest` remains stable `0.2.0`, and GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+
+## Candidate validation
+
+Local candidate verification on Node.js `26.5.1`:
+
+- `npm run check`: 69 files and 341 tests passed.
+- `npm run quality:compare`: candidate quality `0.9875` versus baseline `0.808156`.
+- `npm run schema:context-persistence`: 1,266 bytes and 317 estimated tokens; below the 1,500 absolute and 320 relative limits.
+- `npm run pack:check`: verified core (223 files), reference adapter (7 files), and Pi adapter (68 files) in a clean consumer.
+- `npm pack --dry-run --json` for all three packages passed with the same inventories and no forbidden local/session/storage files.
+- `git diff --check` passed; the only pre-existing untracked path is `.serena/`, which is excluded from commits and package inventories.
+- Version, exact core dependencies, package-lock entries, extension constant, and reference-adapter constant are synchronized to `0.3.0-beta.3`.
+
+Validation-only CI run [`33771957691`](https://github.com/Alucard24/ds4-context-engine/actions/runs/33771957691) passed on Node.js `22.19.0` and `24.x` for commit `8c4abf6106b675aa1af1ee163f6ca07b5e1c0ef3`.
+
+## Registry evidence
+
+Exact post-publication verification passed for all three `0.3.0-beta.3` packages. The clean registry consumer verified exact adapter/core dependencies, public core exports, compiled reference-adapter conformance, packaged quality corpus, packaged Pi extension startup, and the installed `ds4-context-storage` CLI declaration, shim, and usage probe.
+
+Published package shasums:
+
+```text
+ds4-context-core:              0428629e03cf2d02a7033fa3e016344dff3af399
+ds4-context-reference-adapter: 53924c98d6c9672709076edb5cf70bf3f98c1915
+ds4-context-engine:            d0ae468daae4f4e4970497282fd5c18b86f847d5
+```
+
+For all three packages, npm `beta` resolves to `0.3.0-beta.3`, `alpha` remains `0.3.0-alpha.5`, `rc` remains `0.2.0-rc.1`, and `latest` remains `0.2.0`.
+
+Annotated tag `v0.3.0-beta.3` targets `8c4abf6106b675aa1af1ee163f6ca07b5e1c0ef3`. The GitHub prerelease is published at <https://github.com/Alucard24/ds4-context-engine/releases/tag/v0.3.0-beta.3>.
+
+## Documentation
+
+- [`../STORAGE_MAINTENANCE.md`](../STORAGE_MAINTENANCE.md)
+- [`../STORAGE.md`](../STORAGE.md)
+- [`../COMPACTION.md`](../COMPACTION.md)
+- [`../RELEASING.md`](../RELEASING.md)
+- [`0.3.0-beta.2.md`](0.3.0-beta.2.md)

package/docs/releases/0.3.0.md

@@ -0,0 +1,70 @@
+# DS4 Context Engine 0.3.0
+
+Status: promoted 2026-09-04 from beta.3; printed under the npm `latest` dist-tag.
+
+This is the first stable release of the 0.3 line. It carries exactly the beta.3 candidate: no canonical record format, SQLite schema, runtime contract, retention limit, privacy policy, compaction validation, or fallback semantics changed during promotion.
+
+## Promoted from
+
+- [`0.3.0-beta.3.md`](0.3.0-beta.3.md) is the exact promoted candidate; beta.3 itself fixed Windows storage-maintenance flush handling on top of beta.2.
+
+## Promotion evidence
+
+The promotion criteria in [`../DOGFOODING_0.3.0_BETA.md`](../DOGFOODING_0.3.0_BETA.md) are satisfied as follows:
+
+- Full mode matrix with synthetic data on 2026-09-03: TUI, RPC (with and without responding UI bridge), print, JSON stream, no-session, canonical append audit, branch switch, restart, projection rebuild, two concurrent client leases, untrusted RPC, isolated offline maintenance with local TTY confirmation, and online retention convergence. Evidence: `/tmp/ds4-beta-dogfood/evidence/`.
+- Configured remote provider (real): the RPC/branch/untrusted matrix ran against `openai-codex` / `gpt-5.4-mini` with real authentication on 2026-09-03; the disposable database records 21 `openai-codex` / `gpt-5.4-mini` context manifests with provider-reported usage. The same matrix covered accepted, cancelled, and provider-policy-denied persistence writes.
+- Additional real-provider TUI soak on 2026-09-04 against `deepseek` / `deepseek-v4-flash-vision-exp` (Pi 0.85.0): normal model call with provider-reported usage, `/context status`, `/context storage`, and a session pin persisted with scope `session`, status `active`, and a canonical source entry. Evidence: `/tmp/ds4-real-dogfood/evidence/` and the disposable database at `/tmp/ds4-real-agent/ds4-context/context.db` (3 real manifests, pin `b5828a50-689b-4c59-8a90-241eca30217c`).
+- Verified local provider: explicitly recorded as unavailable — no local provider (Ollama/LM Studio or equivalent) is configured in the environment; the runbook allows the missing run to remain recorded rather than inferred.
+- Live maintenance authorization: completed 2026-09-03 (2.42 GiB → 377 MiB, `quick_check=ok`, FK `0`, manifests 1,630 → 128); the fixed backup `context.db.precompact.bak` (including `-shm`/`-wal` residues) was removed 2026-09-04 after a post-removal read-only inspection confirmed `quick_check=ok`, FK `0`, 128 manifests, and `Maintenance recommended: no`.
+
+## Safety and compatibility
+
+Unchanged from beta.3: Pi JSONL remains canonical and append-only; SQLite remains disposable and rebuildable; physical maintenance remains explicit, offline, local-TTY-only, and unavailable to model-callable tools; every `context_persistence` write still requires a fresh positive local UI decision.
+
+Compatibility surface:
+
+- SQLite schema: `15`;
+- configuration: `ds4-context-config-v1`;
+- runtime adapter: `runtime-adapter-v1`;
+- persistence tool: `ds4-context-persistence-tool-v1`;
+- persistence result: `ds4-context-persistence-result-v1`;
+- Pi: `0.84.3` (validated; 0.85.0 additionally exercised by the 2026-09-04 TUI soak);
+- Node.js: `>=22.19.0`.
+
+## Package/version policy
+
+The coordinated version is `0.3.0` for:
+
+```text
+ds4-context-core
+ds4-context-reference-adapter
+ds4-context-engine
+```
+
+Both adapters depend exactly on `ds4-context-core@0.3.0`. Publication used npm's default `latest` tag for all three packages: `latest` now resolves to `0.3.0` (previously `0.2.0`), `beta` remains `0.3.0-beta.3`, `alpha` remains `0.3.0-alpha.5`, and `rc` remains `0.2.0-rc.1`. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+
+## Candidate validation
+
+Local candidate verification on Node.js `26.5.1`:
+
+- `npm run check`: 69 files and 341 tests passed on the promoted tree.
+- `npm run quality:compare`: candidate quality versus the frozen baseline passed.
+- `npm run schema:context-persistence`: within the 1,500 / 320 absolute and relative limits.
+- `npm run pack:check` and `npm pack --dry-run --json` for all three packages passed with no forbidden local/session/storage paths.
+- `git diff --check` passed; the only pre-existing untracked path is `.serena/`, which is excluded from commits and package inventories.
+- Version, exact core dependencies, package-lock entries, extension constant, and reference-adapter constant are synchronized to `0.3.0`.
+
+Validation-only CI is recorded below with the promoted commit. Exact registry verification and the annotated tag are recorded after execution.
+
+## Registry evidence
+
+To be completed after publication.
+
+## Documentation
+
+- [`../STORAGE_MAINTENANCE.md`](../STORAGE_MAINTENANCE.md)
+- [`../STORAGE.md`](../STORAGE.md)
+- [`../COMPACTION.md`](../COMPACTION.md)
+- [`../RELEASING.md`](../RELEASING.md)
+- [`0.3.0-beta.3.md`](0.3.0-beta.3.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ds4-context-engine",
-  "version": "0.3.0-beta.2",
+  "version": "0.3.0",
   "description": "Non-destructive, provider-independent context management for Pi.",
   "type": "module",
   "license": "MIT",
@@ -62,7 +62,7 @@
     ]
   },
   "dependencies": {
-    "ds4-context-core": "0.3.0-beta.2"
+    "ds4-context-core": "0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.84.3",

package/src/pi-adapter/version.ts

@@ -1,4 +1,4 @@
-export const EXTENSION_VERSION = "0.3.0-beta.2";
+export const EXTENSION_VERSION = "0.3.0";
 export const SUPPORTED_PI_VERSION = "0.84.3";
 export const OBSERVER_PLANNER_VERSION = "observer-model-aware-v1";
 export const PLANNER_VERSION = "managed-learned-ranking-v1";