@openparachute/vault 0.6.3 → 0.6.4-rc.10

package/core/src/notes.ts

@@ -22,6 +22,36 @@ import { getIndexedField, releaseField } from "./indexed-fields.js";
 
 let idCounter = 0;
 
+/**
+ * Write-attribution context (vault#298) — the two axes of provenance threaded
+ * from the authenticated request down into every note write.
+ *
+ *   actor — WHO: the principal the write is attributed to (a JWT `sub`, or an
+ *           operator / `token:<id>` label for non-JWT auth). Lands in
+ *           `created_by` on the first write and `last_updated_by` on every
+ *           write.
+ *   via   — VIA WHAT: the interface/channel the write arrived through
+ *           (`mcp`, `surface:<name>`, `agent:<id>`, `operator`/`cli`, `api`).
+ *           Lands in `created_via` / `last_updated_via` symmetrically.
+ *
+ * Both are independently optional — an internal/import write may carry
+ * neither, and a non-JWT operator write carries an `actor`/`via` pair without
+ * a `sub`. `undefined` (or a missing context) means "don't write this column,"
+ * so legacy callers and importers leave attribution NULL rather than
+ * fabricating it.
+ */
+export interface WriteContext {
+  actor?: string | null;
+  via?: string | null;
+}
+
+/** Normalize an attribution value: empty/whitespace → null (never store ""). */
+function attrValue(v: string | null | undefined): string | null {
+  if (typeof v !== "string") return null;
+  const t = v.trim();
+  return t.length === 0 ? null : t;
+}
+
 /** Generate a timestamp-based ID: YYYY-MM-DD-HH-MM-SS-ffffff */
 export function generateId(): string {
   const now = new Date();
@@ -41,7 +71,7 @@ export function generateId(): string {
 export function createNote(
   db: Database,
   content: string,
-  opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string },
+  opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string; actor?: string | null; via?: string | null },
 ): Note {
   const id = opts?.id ?? generateId();
   const createdAt = opts?.created_at ?? new Date().toISOString();
@@ -52,6 +82,14 @@ export function createNote(
   // whatever the caller passed; importer paths trust the export's shape.
   const extension = opts?.extension ?? "md";
 
+  // Write-attribution (vault#298). On CREATE both axes land in the
+  // `created_*` columns AND mirror into `last_updated_*` — the first write IS
+  // the most-recent write, so a never-updated note reports the same author on
+  // both. NULL when the caller passed no attribution (internal/import writes),
+  // never an empty string.
+  const actor = attrValue(opts?.actor);
+  const via = attrValue(opts?.via);
+
   // Empty content is a valid state (vault#323): skeleton notes, drafts
   // saved before content, organizing-only notes, capture-then-fill flows.
   // The earlier #213 guard rejected `content + path both absent`; we no
@@ -66,8 +104,8 @@ export function createNote(
   // "user-touched since creation."
   try {
     db.prepare(
-      `INSERT INTO notes (id, content, path, metadata, created_at, updated_at, extension) VALUES (?, ?, ?, ?, ?, ?, ?)`,
-    ).run(id, content, path, metadata, createdAt, createdAt, extension);
+      `INSERT INTO notes (id, content, path, metadata, created_at, updated_at, extension, created_by, created_via, last_updated_by, last_updated_via) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(id, content, path, metadata, createdAt, createdAt, extension, actor, via, actor, via);
   } catch (err) {
     if (path !== null && isPathUniqueError(err)) {
       throw new PathConflictError(path);
@@ -170,6 +208,50 @@ export class ConflictError extends Error {
   }
 }
 
+/**
+ * Thrown by `updateNote` when a `state_transition` precondition fails: the
+ * named metadata field's current value does not equal `from` (a missing field
+ * counts as a mismatch). Distinct from `ConflictError` (vault#299 settled lead
+ * #3) — a state-transition conflict is about a VALUE not matching, not a
+ * stale `updated_at` token, so it carries its own `transition_conflict` code
+ * and the from/to/current triple rather than the if_updated_at vocabulary.
+ *
+ * The check + set is one atomic conditional UPDATE (`... WHERE
+ * json_extract(metadata,'$.field') IS ?`), so two racing transitioners can't
+ * both observe `from` and both commit — exactly one wins, the other gets this.
+ */
+export class TransitionConflictError extends Error {
+  code = "TRANSITION_CONFLICT" as const;
+  note_id: string;
+  note_path: string | null;
+  field: string;
+  expected_from: unknown;
+  to: unknown;
+  current: unknown;
+
+  constructor(
+    noteId: string,
+    notePath: string | null,
+    field: string,
+    from: unknown,
+    to: unknown,
+    current: unknown,
+  ) {
+    super(
+      `transition_conflict: note "${noteId}" field "${field}" is ${JSON.stringify(
+        current ?? null,
+      )}, expected ${JSON.stringify(from)} to transition to ${JSON.stringify(to)}`,
+    );
+    this.name = "TransitionConflictError";
+    this.note_id = noteId;
+    this.note_path = notePath;
+    this.field = field;
+    this.expected_from = from;
+    this.to = to;
+    this.current = current;
+  }
+}
+
 /**
  * Thrown by `createNote` / `updateNote` when the requested path is already
  * taken by another note. Surfaces as 409 at the HTTP layer so clients can
@@ -321,12 +403,34 @@ export function updateNote(
     metadata?: Record<string, unknown>;
     created_at?: string;
     skipUpdatedAt?: boolean;
+    /**
+     * Write-attribution (vault#298). When set, the most-recent-write columns
+     * `last_updated_by` / `last_updated_via` are bumped to this principal /
+     * channel as part of the same UPDATE. Gated on the same condition as
+     * `updated_at` — a `skipUpdatedAt` machine write doesn't claim authorship,
+     * symmetric with not bumping the timestamp. `created_*` is never touched by
+     * an update (it's set-once at create). Omitted → attribution left as-is.
+     */
+    actor?: string | null;
+    via?: string | null;
     /**
      * Optimistic concurrency token. When provided, the UPDATE runs with an
      * additional `AND updated_at IS ?` clause; if no row is affected and the
      * note still exists, a `ConflictError` is thrown.
      */
     if_updated_at?: string;
+    /**
+     * Compare-and-set state transition (vault#299 Part B). Atomically: if the
+     * named metadata field currently equals `from`, set it to `to` and commit;
+     * otherwise throw `TransitionConflictError` (a missing field is a
+     * conflict). The check rides the same conditional UPDATE — an additional
+     * `AND json_extract(metadata,'$.<field>') IS ?` clause — so two racing
+     * transitioners can't both pass. Combinable with `metadata` (other field
+     * updates merge alongside the transition) and `if_updated_at` (both
+     * preconditions must hold). `from`/`to` are JSON scalars (string / number /
+     * boolean / null).
+     */
+    state_transition?: { field: string; from: unknown; to: unknown };
   },
 ): Note {
   if (updates.content !== undefined && (updates.append !== undefined || updates.prepend !== undefined)) {
@@ -358,6 +462,17 @@ export function updateNote(
     }
     sets.push("updated_at = ?");
     values.push(now);
+
+    // Write-attribution (vault#298): the most-recent-write columns ride the
+    // SAME gate as `updated_at`. A `skipUpdatedAt` machine write doesn't bump
+    // the timestamp, so it doesn't claim authorship either. Set unconditionally
+    // within this branch (even to NULL) so a write that arrives without
+    // attribution honestly records "unknown author for the latest edit" rather
+    // than leaving a stale prior principal — the latest writer wasn't them.
+    sets.push("last_updated_by = ?");
+    values.push(attrValue(updates.actor));
+    sets.push("last_updated_via = ?");
+    values.push(attrValue(updates.via));
   }
 
   if (updates.content !== undefined) {
@@ -404,16 +519,37 @@ export function updateNote(
     sets.push("extension = ?");
     values.push(updates.extension);
   }
+  // State-transition (vault#299 Part B). The `to` value must land in the
+  // metadata field. Two sub-cases keep the metadata write consistent:
+  //   - caller ALSO passed `metadata` (the MCP/REST layer merges before
+  //     calling): fold `to` into that object so the single `metadata = ?`
+  //     SET carries it. The transition value wins over a merged value for
+  //     the same field — the transition is the authoritative state write.
+  //   - caller passed NO `metadata`: use SQL `json_set` so the field is
+  //     updated in place without a read-merge-write (keeps it atomic).
+  // The atomic GUARD (current value == from) is appended to the WHERE below.
+  const st = updates.state_transition;
+  if (st !== undefined && updates.metadata !== undefined) {
+    (updates.metadata as Record<string, unknown>)[st.field] = st.to;
+  }
   if (updates.metadata !== undefined) {
     sets.push("metadata = ?");
     values.push(JSON.stringify(updates.metadata));
+  } else if (st !== undefined) {
+    // No metadata payload — set the single field via json_set. The path is
+    // bound as a parameter (mirrors the json_extract pattern elsewhere); the
+    // value is bound as a JSON-typed argument via `json(?)` so booleans /
+    // numbers / null land as their JSON types, not stringified text.
+    sets.push(`metadata = json_set(COALESCE(metadata, '{}'), ?, json(?))`);
+    values.push(`$.${jsonPathKey(st.field)}`, JSON.stringify(st.to));
   }
   if (updates.created_at !== undefined) {
     sets.push("created_at = ?");
     values.push(updates.created_at);
   }
 
-  // No-op: no SET fields. If a caller still passed `if_updated_at`, we
+  // No-op: no SET fields. If a caller still passed `if_updated_at` (and no
+  // state_transition — that always pushes a metadata SET above), we
   // need to validate the precondition; a conditional UPDATE that sets
   // updated_at to itself does exactly that atomically — even a no-net-
   // change UPDATE takes the write lock in WAL mode, so it still serializes
@@ -438,10 +574,23 @@ export function updateNote(
     sql += " AND updated_at IS ?";
     values.push(updates.if_updated_at);
   }
+  // State-transition guard (vault#299 Part B): the atomic compare. The UPDATE
+  // only fires when the stored field currently equals `from`; otherwise zero
+  // rows match and we raise TransitionConflictError below. `IS` (not `=`) so
+  // a `from: null` correctly matches a stored JSON null / missing field, and
+  // a non-null `from` never matches a NULL/missing field (= conflict).
+  if (st !== undefined) {
+    sql += ` AND json_extract(metadata, ?) IS json_extract(json(?), '$')`;
+    values.push(`$.${jsonPathKey(st.field)}`, JSON.stringify(st.from));
+  }
 
+  // A value-conditional WHERE (if_updated_at OR state_transition) needs
+  // RETURNING to distinguish "matched + updated" from "no match" — `.changes`
+  // is unreliable inside transactions (vault#261).
+  const conditional = updates.if_updated_at !== undefined || st !== undefined;
   let matched: { id: string } | null = null;
   try {
-    if (updates.if_updated_at !== undefined) {
+    if (conditional) {
       matched = db.prepare(`${sql} RETURNING id`).get(...values) as
         | { id: string }
         | null;
@@ -461,13 +610,47 @@ export function updateNote(
     throw err;
   }
 
-  if (updates.if_updated_at !== undefined && matched === null) {
-    throwConflictOrMissing(db, id, updates.if_updated_at);
+  if (conditional && matched === null) {
+    // No row matched. Disambiguate the cause, checking the if_updated_at
+    // precondition first (it's the cheaper, pre-existing contract), then the
+    // state-transition value, then not-found.
+    const row = db.prepare("SELECT updated_at, path, metadata FROM notes WHERE id = ?").get(id) as
+      | { updated_at: string | null; path: string | null; metadata: string | null }
+      | null;
+    if (!row) throw new Error(`Note not found: "${id}"`);
+    if (updates.if_updated_at !== undefined && row.updated_at !== updates.if_updated_at) {
+      throw new ConflictError(id, row.path, row.updated_at, updates.if_updated_at);
+    }
+    if (st !== undefined) {
+      // if_updated_at (if any) matched, so the mismatch is the transition.
+      let current: unknown;
+      try {
+        const meta = row.metadata ? JSON.parse(row.metadata) : {};
+        current = (meta as Record<string, unknown>)[st.field];
+      } catch {
+        current = undefined;
+      }
+      throw new TransitionConflictError(id, row.path, st.field, st.from, st.to, current);
+    }
+    // if_updated_at-only path that fell through (timestamp matched but row
+    // vanished mid-flight): preserve the prior contract.
+    throwConflictOrMissing(db, id, updates.if_updated_at!);
   }
 
   return getNote(db, id)!;
 }
 
+/**
+ * Build the dotted JSON-path key fragment for a metadata field name. Field
+ * names that contain characters JSON-path treats specially (`.`, `[`, `"`,
+ * etc.) are double-quoted; simple identifiers pass through bare. Mirrors the
+ * SQLite JSON1 path grammar.
+ */
+function jsonPathKey(field: string): string {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(field)) return field;
+  return `"${field.replace(/"/g, '\\"')}"`;
+}
+
 function throwConflictOrMissing(db: Database, id: string, expected: string): never {
   const row = db.prepare("SELECT updated_at, path FROM notes WHERE id = ?").get(id) as
     | { updated_at: string | null; path: string | null }
@@ -601,6 +784,29 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     }
   }
 
+  // Write-attribution filters (vault#298). Exact match on the indexed
+  // attribution columns. Each rides its own B-tree (idx_notes_<col>), so
+  // "everything Mathilda wrote" / "everything via the meeting-ingest surface"
+  // is a seek, not a scan. NULL columns never match a non-null filter value
+  // (SQL `=` is unknown against NULL), so legacy/unattributed rows are
+  // correctly excluded from an attribution query.
+  if (opts.createdBy !== undefined) {
+    conditions.push("n.created_by = ?");
+    params.push(opts.createdBy);
+  }
+  if (opts.lastUpdatedBy !== undefined) {
+    conditions.push("n.last_updated_by = ?");
+    params.push(opts.lastUpdatedBy);
+  }
+  if (opts.createdVia !== undefined) {
+    conditions.push("n.created_via = ?");
+    params.push(opts.createdVia);
+  }
+  if (opts.lastUpdatedVia !== undefined) {
+    conditions.push("n.last_updated_via = ?");
+    params.push(opts.lastUpdatedVia);
+  }
+
   // Metadata filters — operator objects route through the indexed generated
   // column (fast, loud errors on non-indexed fields); primitives keep the
   // existing JSON-scan exact-match behavior for backcompat.
@@ -898,6 +1104,10 @@ function toQueryHashInputs(opts: QueryOpts): QueryHashInputs {
     extension: opts.extension,
     ids: opts.ids,
     metadata: opts.metadata,
+    createdBy: opts.createdBy,
+    lastUpdatedBy: opts.lastUpdatedBy,
+    createdVia: opts.createdVia,
+    lastUpdatedVia: opts.lastUpdatedVia,
     dateFrom: opts.dateFrom,
     dateTo: opts.dateTo,
     dateFilter: opts.dateFilter,
@@ -1587,6 +1797,10 @@ export function toNoteIndex(note: Note): NoteIndex {
     extension: note.extension,
     createdAt: note.createdAt,
     updatedAt: note.updatedAt,
+    createdBy: note.createdBy ?? null,
+    createdVia: note.createdVia ?? null,
+    lastUpdatedBy: note.lastUpdatedBy ?? null,
+    lastUpdatedVia: note.lastUpdatedVia ?? null,
     tags: note.tags,
     metadata: note.metadata,
     byteSize,
@@ -1617,6 +1831,43 @@ export function filterMetadata(obj: any, includeMetadata: boolean | string[] | u
   return { ...obj, metadata: Object.keys(filtered).length > 0 ? filtered : undefined };
 }
 
+/**
+ * Shallow-merge an incoming metadata patch onto a note's existing metadata,
+ * with RFC 7386 (JSON Merge Patch) null-as-delete semantics — the canonical
+ * merge for every metadata write surface (REST `PATCH /api/notes`, MCP
+ * `update-note`, batch).
+ *
+ * An incoming value of `null` is a DELETE tombstone: the key is removed from
+ * the result rather than persisted as a literal JSON `null`. This is the only
+ * way to remove a metadata key through the API — under a plain
+ * `{ ...existing, ...incoming }` merge, omission can't delete (it preserves the
+ * prior value) and `null` used to persist literally, leaving no removal path.
+ * Now key renames are pure-API: `{ new_key: "v", "old-key": null }` adds the
+ * new key and drops the old one in one PATCH. See vault#478 / #479.
+ *
+ * Shallow by design — top-level keys only, matching the existing wholesale
+ * top-level merge. A nested object value replaces its key wholesale (we do not
+ * recurse), so an incoming `null` removes the whole key regardless of depth.
+ * Compat: storing a literal null is no longer possible via this path; the
+ * boulder migration confirmed zero callers relied on that (vault#478). A caller
+ * that genuinely needs an absent-vs-null distinction should model it with a
+ * sentinel string, not a JSON null.
+ */
+export function mergeMetadata(
+  existing: Record<string, unknown> | null | undefined,
+  incoming: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...(existing ?? {}) };
+  for (const [key, value] of Object.entries(incoming)) {
+    if (value === null) {
+      delete result[key];
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 // ---- Vault stats (aggregate situational awareness) ----
 
 /**
@@ -1703,6 +1954,10 @@ export interface BulkNoteInput {
   metadata?: Record<string, unknown>;
   created_at?: string;
   extension?: string;
+  /** Write-attribution (vault#298) — see WriteContext. Per-item so a batch can
+   *  carry the same actor/via on every row. */
+  actor?: string | null;
+  via?: string | null;
 }
 
 export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
@@ -1719,6 +1974,8 @@ export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
           metadata: input.metadata,
           created_at: input.created_at,
           extension: input.extension,
+          actor: input.actor,
+          via: input.via,
         }),
       );
     }
@@ -1787,6 +2044,14 @@ interface NoteRow {
   created_at: string;
   updated_at: string | null;
   extension: string | null;
+  // Write-attribution (vault#298). All four nullable — NULL on legacy rows and
+  // on writes that carried no attribution context. A v22 vault reading these
+  // before its migration runs would see them absent on the row object
+  // (`SELECT *` simply omits non-existent columns); `?? null` normalizes.
+  created_by?: string | null;
+  created_via?: string | null;
+  last_updated_by?: string | null;
+  last_updated_via?: string | null;
 }
 
 function rowToNote(row: NoteRow): Note {
@@ -1807,5 +2072,13 @@ function rowToNote(row: NoteRow): Note {
     // Legacy notes (pre-#70) may have NULL updated_at. Fall back to created_at
     // so the optimistic-concurrency contract always has a real token to echo.
     updatedAt: row.updated_at ?? row.created_at,
+    // Write-attribution (vault#298). NULL passes through verbatim — a missing
+    // author is meaningful ("pre-attribution / unknown"), so we don't coerce
+    // to a placeholder. `?? null` collapses both SQL NULL and an absent column
+    // (pre-migration read) to the same `null`.
+    createdBy: row.created_by ?? null,
+    createdVia: row.created_via ?? null,
+    lastUpdatedBy: row.last_updated_by ?? null,
+    lastUpdatedVia: row.last_updated_via ?? null,
   };
 }

package/core/src/query-operators.ts

@@ -188,3 +188,120 @@ export function buildOperatorClause(
     params,
   };
 }
+
+// ---------------------------------------------------------------------------
+// In-memory operator evaluation (vault#299 — value-matched triggers)
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate an operator object against a single in-memory value — the
+ * non-SQL twin of {@link buildOperatorClause}. The trigger engine fires on a
+ * live `note.metadata` object (not a DB row), so it can't route through the
+ * indexed generated columns; this gives it the SAME operator vocabulary +
+ * semantics without re-implementing them. An object with multiple operators
+ * is AND-composed (`{ gt: 5, lt: 10 }`), matching the SQL clause builder.
+ *
+ * `value` is the field's current value (`undefined` when the field is
+ * absent). Semantics mirror the SQL builder, including the NULL/missing
+ * handling: `ne`/`not_in` treat an absent/null value as "matches" (the SQL
+ * `(col IS NULL OR ...)` shape); `eq: null` matches an absent/null value.
+ *
+ * Throws `QueryError` on an unknown operator or a malformed operand — the
+ * trigger validator surfaces it as a 400 at registration time.
+ */
+export function matchesOperator(
+  field: string,
+  value: unknown,
+  opObj: Record<string, unknown>,
+): boolean {
+  validateOperatorObject(field, opObj);
+  const absent = value === undefined || value === null;
+
+  for (const [op, operand] of Object.entries(opObj)) {
+    switch (op as QueryOp) {
+      case "eq":
+        if (operand === null) {
+          if (!absent) return false;
+        } else if (absent || !looseEquals(value, operand)) {
+          return false;
+        }
+        break;
+      case "ne":
+        if (operand === null) {
+          if (absent) return false;
+        } else if (!absent && looseEquals(value, operand)) {
+          return false;
+        }
+        break;
+      case "gt":
+      case "gte":
+      case "lt":
+      case "lte": {
+        if (absent) return false;
+        const cmp = compareScalar(value, operand);
+        if (cmp === null) return false;
+        if (op === "gt" && !(cmp > 0)) return false;
+        if (op === "gte" && !(cmp >= 0)) return false;
+        if (op === "lt" && !(cmp < 0)) return false;
+        if (op === "lte" && !(cmp <= 0)) return false;
+        break;
+      }
+      case "in":
+      case "not_in": {
+        if (!Array.isArray(operand)) {
+          throw new QueryError(
+            `operator "${op}" on metadata field "${field}" expects an array`,
+            "INVALID_OPERATOR_VALUE",
+          );
+        }
+        const present = !absent && operand.some((o) => looseEquals(value, o));
+        if (op === "in" && !present) return false;
+        // not_in: absent/null matches (mirrors SQL `col IS NULL OR ...`).
+        if (op === "not_in" && present) return false;
+        break;
+      }
+      case "exists":
+        if (typeof operand !== "boolean") {
+          throw new QueryError(
+            `operator "exists" on metadata field "${field}" expects a boolean`,
+            "INVALID_OPERATOR_VALUE",
+          );
+        }
+        if (operand === !absent) break;
+        return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Loose scalar equality used by in-memory `eq`/`ne`/`in`. Matches SQLite's
+ * affinity-tolerant comparison closely enough for trigger value-matching:
+ * exact for same-type scalars; cross-type number/string compares by string
+ * form (`5` matches `"5"`), since metadata round-trips through JSON and a
+ * note may carry either shape.
+ */
+function looseEquals(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (
+    (typeof a === "number" || typeof a === "string") &&
+    (typeof b === "number" || typeof b === "string")
+  ) {
+    return String(a) === String(b);
+  }
+  return false;
+}
+
+/**
+ * Three-way comparison for ordered operators (gt/gte/lt/lte). Returns a
+ * negative/zero/positive number, or `null` when the operands aren't
+ * order-comparable (so the caller treats it as "no match"). Numbers compare
+ * numerically; strings lexicographically; mixed types don't compare.
+ */
+function compareScalar(a: unknown, b: unknown): number | null {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  return null;
+}