vgxness 1.5.1 → 1.5.2

package/docs/storage.md

@@ -0,0 +1,93 @@
+# Storage
+
+VGXNESS keeps all durable state in local SQLite. There is no required cloud account, no remote sync in v1.5.1, and no implicit sharing between scopes. Project data and personal/global data must not be collapsed into one scope.
+
+## Database location
+
+The default is a per-user global database. The path is resolved by `resolveMemoryDatabasePath(...)` in `src/memory/storage-paths.ts` with this precedence:
+
+1. `--db <path>` flag (`source: 'flag'`).
+2. `VGXNESS_DB_PATH` env var (`source: 'environment'`).
+3. Global default (`source: 'global-default'`).
+
+| Platform | Global default |
+|---|---|
+| macOS | `~/Library/Application Support/vgxness/memory.sqlite` |
+| Linux | `${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite` |
+| Windows | `%LOCALAPPDATA%\\vgxness\\memory.sqlite` when available; otherwise `%APPDATA%\\vgxness\\memory.sqlite` |
+
+If the global default cannot be resolved (for example, `HOME` is not set on Linux), the resolver returns a `store_unavailable` error rather than falling back to the current working directory. The fix is to pass `--db` or set `VGXNESS_DB_PATH`.
+
+The parent directory is created on demand by `prepareMemoryDatabasePath(...)`. Existing project-local databases remain compatible; opt in explicitly when needed:
+
+```bash
+vgxness memory search --project vgxness --db .vgx/memory.sqlite
+```
+
+## Runtime engine
+
+Local SQLite storage is supported through `bun:sqlite`. Node.js is not the storage runtime; it remains development/build/test tooling. The release gate `bun run verify:bun-sqlite` proves SQLite readiness on a clean database by:
+
+- Copying the source migrations into a temporary directory.
+- Applying them against a temporary database.
+- Checking foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup.
+
+## Migration layout
+
+SQL migrations live in `src/memory/sqlite/migrations/` and are applied in lexicographic order. The package build copies them into `dist/memory/sqlite/migrations` so installed bins can apply them on first use. The full list as of v1.5.1:
+
+| # | File | Adds |
+|---|---|---|
+| 001 | `001_initial.sql` | Base memory observations table. |
+| 002 | `002_observation_revisions.sql` | Observation revision history. |
+| 003 | `003_agent_registry.sql` | Agent and subagent registry. |
+| 004 | `004_run_runtime.sql` | Run records, events, checkpoints. |
+| 005 | `005_run_approvals.sql` | Approval records linked to permission-decision events. |
+| 006 | `006_run_operation_attempts.sql` | Reserved operation attempts. |
+| 007 | `007_abandoned_operation_attempts.sql` | Recovery-only `abandoned` state. |
+| 008 | `008_run_execution_plan_events.sql` | Execution isolation plan events. |
+| 009 | `009_multiple_operation_attempts.sql` | Multiple ordered attempts per approval. |
+| 010 | `010_skill_registry.sql` | Skill identity, versions, source metadata. |
+| 011 | `011_skill_usage_resolution_outcomes.sql` | Skill usage records from resolution. |
+| 012 | `012_skill_improvement_proposals.sql` | Versioned, reviewable skill proposals. |
+| 013 | `013_skill_evaluation_scenarios.sql` | Skill evaluation harness. |
+| 014 | `014_manager_profile_overlays.sql` | Manager profile overlays. |
+| 015 | `015_artifact_metadata.sql` | Artifact metadata for SDD. |
+
+## Scopes
+
+Two scopes share the database:
+
+| Scope | Purpose |
+|---|---|
+| `project` | Repo-specific memory, SDD artifacts, run history, project agents/skills, project manager profile overlay. |
+| `personal` | User preferences, reusable skills, cross-project patterns, personal manager profile overlay. |
+
+Scopes are not stored in separate databases in v1.5.1; they are columns on the relevant tables. Code that wants to read or write a scope must pass it explicitly. Memory writes default to `project`; pass `scope: "personal"` for personal/global observations.
+
+## Tables and lifecycle
+
+The schema follows a small set of conventions:
+
+- **Memory observations** are immutable for content; updates create revisions tracked by `observation_revisions`. `topicKey` is the durable upsert key: re-saving with the same key updates the existing observation rather than creating a duplicate.
+- **SDD artifacts** are stored under canonical topic keys `sdd/{change}/{phase}`. Acceptance is recorded separately on `SddArtifactAcceptanceRecord` and is not a content column.
+- **Runs** are append-only in spirit. `RunRecord.status` transitions through the lifecycle described in [Safety model](./safety.md); `RunEvent` is the audit trail; `RunCheckpoint` is the resumable JSON state. Terminal runs cannot be finalized again, and the final `outcome` must match the terminal `status`.
+- **Operation attempts** are reserved through `RunService.executeOperation(...)` and finalized in one transaction. `reserved` is exclusive; once finalized, a new attempt requires a fresh reservation and policy admission.
+- **Skills** are versioned, with `currentVersionId` pointing at the active version. Skill improvement proposals do not mutate the active skill until `applySkillImprovementProposal(...)` is called on an `approved` proposal.
+- **Manager profile overlays** are a thin layer over the canonical agent manifest; they record per-user/per-project model and prompt-contract preferences without mutating the built-in manifest.
+
+## Backup and recovery
+
+There is no automatic backup of the SQLite database in v1.5.1. The recommended pattern is to treat the database file as a normal file in the user's data directory and use OS-level snapshots if needed.
+
+Provider config (OpenCode) has its own backup/rollback path through `vgxness setup rollback --backup <path>`. That is separate from the database and is documented in the [CLI reference](./cli.md).
+
+## Wiping and migrating
+
+To reset state for a project, point `--db` at a new path; do not delete a database file that another `vgxness` process might still be using. Migrations are forward-only and idempotent within a single database version. If a downgrade is required, restore the previous database file from a snapshot — VGXNESS does not support automatic down-migrations.
+
+## Safety
+
+- The database file holds potentially sensitive content (memory observations, run transcripts, prompt excerpts). Treat it as you would any other local credential-bearing file. The redaction helpers in `src/code/reporting/redaction.ts` are applied at the prompt/report/checkpoint boundary, not at the storage boundary.
+- `--db` accepts any path the calling user can write to. VGXNESS refuses to write through symlinks that escape the parent directory of the resolved path.
+- `*.sqlite*`, `.vgx/`, and `.opencode/` are git-ignored.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {