@openparachute/vault 0.2.4 → 0.3.0-rc.1

package/core/src/schema.ts

@@ -1,7 +1,8 @@
 import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
+import { rebuildIndexes } from "./indexed-fields.js";
 
-export const SCHEMA_VERSION = 9;
+export const SCHEMA_VERSION = 12;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record
@@ -53,11 +54,32 @@ CREATE TABLE IF NOT EXISTS tag_schemas (
   fields TEXT -- JSON: { "field_name": { "type": "string", "description": "..." }, ... }
 );
 
--- Tokens: API authentication with scoped permissions
+-- Indexed fields: SSOT for generated columns and indexes on notes derived
+-- from tag-declared fields with indexed=true. One row per indexed metadata
+-- field; declarer_tags is a JSON array of tags that currently declare it.
+-- See core/src/indexed-fields.ts.
+CREATE TABLE IF NOT EXISTS indexed_fields (
+  field TEXT PRIMARY KEY,
+  sqlite_type TEXT NOT NULL,
+  declarer_tags TEXT NOT NULL DEFAULT '[]'
+);
+
+-- Tokens: API authentication with OAuth-standard scopes.
+--
+-- scopes is a whitespace-separated list of granted scopes (OAuth 2.0 §3.3)
+-- — e.g. "vault:read vault:write". Introduced in v12 alongside enforcement;
+-- NULL rows are pre-v12 tokens which fall back to deriving scopes from the
+-- legacy permission column (see src/scopes.ts). permission is kept for the
+-- one-release-cycle back-compat window and will be dropped in a future
+-- migration.
+--
+-- scope_tag / scope_path_prefix are deprecated Phase-0 columns — never
+-- enforced at runtime, kept only for schema stability.
 CREATE TABLE IF NOT EXISTS tokens (
   token_hash TEXT PRIMARY KEY,
   label TEXT NOT NULL,
   permission TEXT NOT NULL DEFAULT 'admin',
+  scopes TEXT,
   scope_tag TEXT,
   scope_path_prefix TEXT,
   expires_at TEXT,
@@ -163,6 +185,19 @@ export function initSchema(db: Database): void {
   // Migrate v8 → v9: add vault_name column to oauth_codes
   migrateToV9(db);
 
+  // Migrate v9 → v10: indexed_fields table (created by SCHEMA_SQL above).
+  migrateToV10(db);
+
+  // Migrate v10 → v11: backfill updated_at = created_at for legacy rows.
+  migrateToV11(db);
+
+  // Migrate v11 → v12: add `scopes` column to tokens for Phase 2 enforcement.
+  migrateToV12(db);
+
+  // Rebuild any generated columns + indexes declared in indexed_fields.
+  // No-op for a fresh vault; idempotent on existing vaults.
+  rebuildIndexes(db);
+
   // Record schema version
   db.prepare("INSERT OR REPLACE INTO schema_version (version, applied_at) VALUES (?, ?)").run(
     SCHEMA_VERSION,
@@ -270,6 +305,38 @@ function migrateToV9(db: Database): void {
   }
 }
 
+function migrateToV10(db: Database): void {
+  // SCHEMA_SQL's CREATE TABLE IF NOT EXISTS covers fresh vaults; this
+  // ensures indexed_fields exists on vaults created before v10. No data
+  // migration — rebuildIndexes() downstream handles column/index creation
+  // if any rows are already present.
+}
+
+/**
+ * Migrate v10 → v11: backfill `updated_at = created_at` for notes that never
+ * received an update. Pre-v11 inserts left `updated_at` NULL, which broke
+ * optimistic concurrency for clients that fall back to `createdAt` (the
+ * common `updatedAt ?? createdAt` pattern) — the `updated_at IS ?` guard
+ * never matched. From v11 onward, `createNote` sets both columns at insert.
+ * Idempotent — safe to run on every boot.
+ */
+function migrateToV11(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+  db.exec("UPDATE notes SET updated_at = created_at WHERE updated_at IS NULL");
+}
+
+/**
+ * Migrate v11 → v12: add `scopes` column to tokens. Existing rows get NULL
+ * and fall back to legacy `permission` → scopes derivation at read time
+ * (see src/scopes.ts:legacyPermissionToScopes). New tokens minted on v12+
+ * populate the column explicitly.
+ */
+function migrateToV12(db: Database): void {
+  if (hasTable(db, "tokens") && !hasColumn(db, "tokens", "scopes")) {
+    db.exec("ALTER TABLE tokens ADD COLUMN scopes TEXT");
+  }
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/store.ts

@@ -151,6 +151,17 @@ export class BunSqliteStore implements Store {
     return noteOps.deleteTag(this.db, name);
   }
 
+  async renameTag(oldName: string, newName: string): Promise<noteOps.RenameTagResult> {
+    return noteOps.renameTag(this.db, oldName, newName);
+  }
+
+  async mergeTags(
+    sources: string[],
+    target: string,
+  ): Promise<{ merged: Record<string, number>; target: string }> {
+    return noteOps.mergeTags(this.db, sources, target);
+  }
+
   // ---- Vault Stats ----
 
   async getVaultStats(opts?: { topTagsLimit?: number }) {
@@ -291,6 +302,87 @@ export class BunSqliteStore implements Store {
       };
     });
   }
+
+  async deleteAttachment(
+    noteId: string,
+    attachmentId: string,
+  ): Promise<{ deleted: boolean; path: string | null; orphaned: boolean }> {
+    // Scope by noteId so a token authorized for note A can't delete note B's attachments.
+    const row = this.db.prepare(
+      "SELECT path FROM attachments WHERE id = ? AND note_id = ?",
+    ).get(attachmentId, noteId) as { path: string } | undefined;
+    if (!row) return { deleted: false, path: null, orphaned: false };
+
+    this.db.prepare("DELETE FROM attachments WHERE id = ? AND note_id = ?").run(attachmentId, noteId);
+
+    // Orphan check: caller uses this to decide whether to unlink the file on disk.
+    const other = this.db.prepare(
+      "SELECT 1 FROM attachments WHERE path = ? LIMIT 1",
+    ).get(row.path);
+    return { deleted: true, path: row.path, orphaned: !other };
+  }
+
+  async getAttachment(attachmentId: string): Promise<Attachment | null> {
+    const row = this.db.prepare(
+      "SELECT * FROM attachments WHERE id = ?",
+    ).get(attachmentId) as { id: string; note_id: string; path: string; mime_type: string; metadata: string | null; created_at: string } | undefined;
+    if (!row) return null;
+    let metadata: Record<string, unknown> | undefined;
+    if (row.metadata && row.metadata !== "{}") {
+      try { metadata = JSON.parse(row.metadata); } catch {}
+    }
+    return {
+      id: row.id,
+      noteId: row.note_id,
+      path: row.path,
+      mimeType: row.mime_type,
+      metadata,
+      createdAt: row.created_at,
+    };
+  }
+
+  /**
+   * Replace the attachment's metadata JSON blob. The caller passes the full
+   * merged object — this is a set, not a patch, so partial-field updates
+   * don't silently drop other keys.
+   */
+  async setAttachmentMetadata(attachmentId: string, metadata: Record<string, unknown>): Promise<void> {
+    const json = JSON.stringify(metadata);
+    this.db.prepare("UPDATE attachments SET metadata = ? WHERE id = ?").run(json, attachmentId);
+  }
+
+  /**
+   * Return attachments whose metadata.transcribe_status matches the given
+   * status, oldest first (FIFO). Used by the transcription worker to drain
+   * the queue. `status = "pending"` is the queue; `"failed"` feeds a retry
+   * sweep; `"done"` is only useful for tests and diagnostics.
+   */
+  async listAttachmentsByTranscribeStatus(
+    status: "pending" | "failed" | "done",
+    limit = 50,
+  ): Promise<Attachment[]> {
+    const rows = this.db.prepare(
+      `SELECT * FROM attachments
+       WHERE json_extract(metadata, '$.transcribe_status') = ?
+       ORDER BY created_at ASC
+       LIMIT ?`,
+    ).all(status, limit) as { id: string; note_id: string; path: string; mime_type: string; metadata: string | null; created_at: string }[];
+
+    return rows.map((r) => {
+      let metadata: Record<string, unknown> | undefined;
+      if (r.metadata && r.metadata !== "{}") {
+        try { metadata = JSON.parse(r.metadata); } catch {}
+      }
+      return {
+        id: r.id,
+        noteId: r.note_id,
+        path: r.path,
+        mimeType: r.mime_type,
+        metadata,
+        createdAt: r.created_at,
+      };
+    });
+  }
 }
 
 /** @deprecated Renamed to `BunSqliteStore` to make the runtime split explicit. Kept as an alias for backward compatibility. */

package/core/src/tag-schemas.ts

@@ -16,6 +16,11 @@ export interface TagFieldSchema {
   type: string;
   description?: string;
   enum?: string[];
+  // When true, a generated column + index are maintained on `notes` for this
+  // field, making it available for operator queries and `order_by`. Global
+  // across declarers — all tags declaring this field must agree on both
+  // `type` and `indexed`. See core/src/indexed-fields.ts for lifecycle.
+  indexed?: boolean;
 }
 
 export interface TagSchema {

package/core/src/types.ts

@@ -50,12 +50,27 @@ export interface QueryOpts {
   tags?: string[];
   tagMatch?: "all" | "any"; // "all" = must have ALL tags (default), "any" = must have ANY tag
   excludeTags?: string[];
+  // Presence filters. `true` → has at least one; `false` → has none.
+  // When `tags` is also set, `hasTags` is ignored (the tag filter already constrains the set).
+  // `hasLinks` checks both directions — inbound or outbound counts as "has links".
+  hasTags?: boolean;
+  hasLinks?: boolean;
   path?: string;        // exact path match (case-insensitive)
   pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
-  metadata?: Record<string, unknown>; // filter by metadata values (exact match on each key)
+  // Per-field metadata filter. Each value is either a primitive (exact
+  // match, today's behavior) or an operator object — `{ eq, ne, gt, gte, lt,
+  // lte, in, not_in, exists }` — which routes through the generated column
+  // for the field. Operator queries require the field to be declared
+  // `indexed: true` in a tag schema; undeclared fields error loudly.
+  metadata?: Record<string, unknown>;
   dateFrom?: string;    // ISO date
   dateTo?: string;      // ISO date
   sort?: "asc" | "desc";
+  // Sort by an indexed metadata field instead of `created_at`. Must be
+  // declared `indexed: true`; errors loudly otherwise. Direction is taken
+  // from `sort` (default "asc") and `created_at` is appended as a stable
+  // tiebreaker.
+  orderBy?: string;
   limit?: number;
   offset?: number;
 }
@@ -109,6 +124,14 @@ export interface Store {
   untagNote(noteId: string, tags: string[]): Promise<void>;
   listTags(): Promise<{ name: string; count: number }[]>;
   deleteTag(name: string): Promise<{ deleted: boolean; notes_untagged: number }>;
+  renameTag(
+    oldName: string,
+    newName: string,
+  ): Promise<{ renamed: number } | { error: "not_found" } | { error: "target_exists" }>;
+  mergeTags(
+    sources: string[],
+    target: string,
+  ): Promise<{ merged: Record<string, number>; target: string }>;
 
   // Vault stats (aggregate, read-only)
   getVaultStats(opts?: { topTagsLimit?: number }): Promise<VaultStats>;
@@ -138,4 +161,8 @@ export interface Store {
   // Attachments
   addAttachment(noteId: string, path: string, mimeType: string, metadata?: Record<string, unknown>): Promise<Attachment>;
   getAttachments(noteId: string): Promise<Attachment[]>;
+  getAttachment(attachmentId: string): Promise<Attachment | null>;
+  setAttachmentMetadata(attachmentId: string, metadata: Record<string, unknown>): Promise<void>;
+  deleteAttachment(noteId: string, attachmentId: string): Promise<{ deleted: boolean; path: string | null; orphaned: boolean }>;
+  listAttachmentsByTranscribeStatus(status: "pending" | "failed" | "done", limit?: number): Promise<Attachment[]>;
 }

package/docs/HTTP_API.md

@@ -204,11 +204,42 @@ Returns `{deleted: true}`.
 Body: `{"tags": ["a", "b"]}`.
 
 #### `POST /notes/{id}/attachments`
-Body: `{"path": "files/a.png", "mimeType": "image/png"}`.
+Body: `{"path": "files/a.png", "mimeType": "image/png", "transcribe"?: boolean}`.
+
+When `transcribe: true` and the file is audio, the server queues a
+transcription job: `attachment.metadata.transcribe_status = "pending"` is
+set, and `note.metadata.transcribe_stub = true` is written as the opt-in to
+overwrite content when the transcript lands. A background worker (enabled
+by setting `SCRIBE_URL` on the server) drains the queue FIFO, one at a
+time, calling `${SCRIBE_URL}/v1/audio/transcriptions` with the audio as
+multipart `file` and expecting `{ text: string }` back.
+
+On success:
+- If `note.metadata.transcribe_stub === true`, the worker replaces the
+  literal `_Transcript pending._` placeholder in the note body with the
+  transcript, or the whole body if the placeholder is absent. The stub
+  marker is cleared. A user edit clearing `transcribe_stub` before the
+  transcript arrives opts out of the overwrite.
+- `attachment.metadata.transcribe_status` becomes `"done"` and
+  `transcript` + `transcribe_done_at` are recorded on the attachment even
+  when the note opted out, so the transcript is always addressable.
+
+On failure, the worker retries with exponential backoff up to three
+attempts before setting `transcribe_status = "failed"` and capturing
+`transcribe_error`.
+
+The queue lives in the DB (`attachments` table), so a server restart
+resumes pending work without replay.
 
 #### `GET /notes/{id}/attachments`
 Returns `Attachment[]`.
 
+#### `DELETE /notes/{id}/attachments/{attId}`
+Returns `204 No Content`. The attachment record is removed and the underlying
+storage file is unlinked when no other attachment still references the same
+path (orphan-check). Returns `404` if the attachment doesn't exist or belongs
+to a different note. Idempotent: a second delete of the same id returns `404`.
+
 ### Links
 
 #### `GET /links`
@@ -288,11 +319,84 @@ Query params:
 #### `GET /tags`
 Returns `[{name, count}]`.
 
+#### `POST /tags/{name}/rename`
+Body: `{ "new_name": string }`. Atomically renames the tag across `tags`,
+`note_tags`, and `tag_schemas` in a single transaction.
+
+Returns `{ "renamed": number }` on success — the number of note-tag rows
+rewritten.
+
+Errors:
+- `404 { "error": "not_found" }` — source tag does not exist.
+- `409 { "error": "target_exists", "target": string, "message": "..." }` —
+  `new_name` is already a tag. The client should call `POST /tags/merge`
+  instead if combining the two tags is the intent.
+
+#### `POST /tags/merge`
+Body: `{ "sources": string[], "target": string }`. Retags every note carrying
+any of the `sources` tags with `target`, then drops the source tags (and
+their schemas) in a single transaction. `target`'s own schema is preserved.
+
+`target` is created if it doesn't exist yet. Sources that don't exist are
+recorded with count `0`. Duplicate sources are deduped; `target` appearing
+in `sources` is a no-op for that entry.
+
+Returns `{ "merged": { [source]: count }, "target": string }`.
+
 ### Vault stats
 
 You usually want `GET /vaults/{name}` which bundles stats with vault metadata.
 If you only need the stats, call `GET /vaults/{name}` and read `.stats`.
 
+### Vault config
+
+#### `GET /api/vault`
+Returns the vault's identity plus a nested `config` block for mutable
+settings.
+
+```json
+{
+  "name": "default",
+  "description": "My knowledge graph",
+  "config": {
+    "audio_retention": "keep"
+  }
+}
+```
+
+`?include_stats=true` folds the same `VaultStats` shape into the response
+under `stats`.
+
+#### `PATCH /api/vault`
+Update the description and/or nested `config` fields. Only the fields you
+pass are changed; omitted fields are left alone.
+
+```json
+{
+  "description": "new description",
+  "config": { "audio_retention": "until_transcribed" }
+}
+```
+
+Response echoes the full vault payload (same shape as `GET /api/vault`).
+
+##### `config.audio_retention`
+
+Controls what the transcription worker does with the audio file on disk
+once it reaches a terminal state. The attachment row (including any
+recorded transcript) is always preserved — only the file on disk is
+affected.
+
+| Value | Behavior |
+|---|---|
+| `"keep"` (default) | Never unlink. The original audio stays on disk indefinitely. |
+| `"until_transcribed"` | Unlink on successful transcription. On failure the file is kept so you can retry or re-upload. |
+| `"never"` | Unlink on any terminal state — **including failure**. Users who opt in accept that losing a bad transcription also loses the source audio. |
+
+Validation: `audio_retention` must be exactly one of those three strings.
+Any other value returns `400 { "error": "invalid_audio_retention" }`.
+Vaults created before this setting existed read back as `"keep"`.
+
 ### Storage
 
 #### `POST /storage/upload`

package/package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@openparachute/vault",
+  "version": "0.2.4",
+  "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
+  "module": "src/cli.ts",
+  "type": "module",
+  "bin": {
+    "parachute-vault": "src/cli.ts"
+  },
+  "scripts": {
+    "start": "bun src/server.ts",
+    "cli": "bun src/cli.ts",
+    "test": "bun test src/",
+    "test:core": "cd core && node --experimental-vm-modules node_modules/vitest/dist/cli.js run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "otpauth": "^9.5.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ParachuteComputer/parachute-vault.git"
+  },
+  "license": "AGPL-3.0"
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.2.4",
+  "version": "0.3.0-rc.1",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",
   "bin": {
-    "parachute": "src/cli.ts"
+    "parachute-vault": "src/cli.ts"
   },
   "scripts": {
     "start": "bun src/server.ts",