@openparachute/vault 0.6.3 → 0.6.4-rc.2

package/core/src/schema.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
 
-export const SCHEMA_VERSION = 22;
+export const SCHEMA_VERSION = 23;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record.
@@ -13,6 +13,17 @@ export const SCHEMA_SQL = `
 -- column; on-disk uniqueness key is (path, extension). See
 -- core/src/portable-md.ts:supportsInlineFrontmatter for the
 -- frontmatter-vs-sidecar split.
+--
+-- Write-attribution (v23, vault#298) — two axes of provenance, both nullable:
+--   created_by / created_via        — the principal + interface of the FIRST
+--                                     write (set once at create; never rewritten).
+--   last_updated_by / last_updated_via — the principal + interface of the MOST
+--                                     RECENT write (set on every mutating update).
+-- The *_by columns are the actor (a JWT sub, or an operator/token label for
+-- non-JWT auth); the *_via columns are the channel the write arrived through
+-- (mcp, surface:NAME, agent:ID, operator/cli, api). Legacy rows stay NULL —
+-- we don't fabricate authors for writes that predate attribution. See
+-- migrateToV23.
 CREATE TABLE IF NOT EXISTS notes (
   id TEXT PRIMARY KEY,
   content TEXT DEFAULT '',
@@ -20,7 +31,11 @@ CREATE TABLE IF NOT EXISTS notes (
   metadata TEXT DEFAULT '{}',
   created_at TEXT NOT NULL,
   updated_at TEXT,
-  extension TEXT NOT NULL DEFAULT 'md'
+  extension TEXT NOT NULL DEFAULT 'md',
+  created_by TEXT,
+  created_via TEXT,
+  last_updated_by TEXT,
+  last_updated_via TEXT
 );
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
@@ -479,6 +494,13 @@ export function initSchema(db: Database): void {
   // scans. See the 2026-06-10 query-perf measurements.
   migrateToV22(db);
 
+  // Migrate v22 → v23: write-attribution columns on `notes`
+  // (created_by/created_via/last_updated_by/last_updated_via) + their indexes.
+  // All four nullable; existing rows backfill to NULL ("written before
+  // attribution" — we don't fabricate authors for legacy writes). See
+  // vault#298.
+  migrateToV23(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1150,6 +1172,43 @@ function migrateToV22(db: Database): void {
   db.exec("CREATE INDEX IF NOT EXISTS idx_notes_updated ON notes(updated_at, id)");
 }
 
+/**
+ * Migrate v22 → v23: per-identity + per-interface write attribution
+ * (vault#298). Adds four nullable columns to `notes` and an index on each so
+ * "what did Mathilda write" / "what came in via the meeting-ingest surface"
+ * are indexed lookups, not scans:
+ *
+ *   created_by        — principal (actor) of the first write
+ *   created_via       — interface/channel of the first write
+ *   last_updated_by   — principal of the most recent write
+ *   last_updated_via  — interface/channel of the most recent write
+ *
+ * `*_by` is the JWT `sub` (or an operator / `token:<id>` label for non-JWT
+ * auth); `*_via` is the channel (`mcp`, `surface:<name>`, `agent:<id>`,
+ * `operator`/`cli`, `api`). All four NULL on legacy rows — we deliberately do
+ * NOT backfill an author for writes that predate attribution; NULL reads as
+ * "unknown / pre-attribution," distinct from any real principal.
+ *
+ * Columns live here (not SCHEMA_SQL's index block) following the
+ * idx_tokens_vault_name / idx_notes_updated precedent: SCHEMA_SQL runs before
+ * the migration steps, so an upgrading v22 vault doesn't yet have the columns
+ * when that block evaluates. Fresh vaults get the columns from the CREATE
+ * TABLE above and the indexes from this same path. All idempotent — the
+ * column-existence guard + CREATE INDEX IF NOT EXISTS make re-runs no-ops.
+ */
+function migrateToV23(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+  const cols = ["created_by", "created_via", "last_updated_by", "last_updated_via"];
+  for (const col of cols) {
+    if (!hasColumn(db, "notes", col)) {
+      db.exec(`ALTER TABLE notes ADD COLUMN ${col} TEXT`);
+    }
+  }
+  for (const col of cols) {
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_notes_${col} ON notes(${col})`);
+  }
+}
+
 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

@@ -100,7 +100,7 @@ export class BunSqliteStore implements Store {
 
   // ---- Notes ----
 
-  async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note> {
+  async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string; actor?: string | null; via?: string | null }): Promise<Note> {
     const note = noteOps.createNote(this.db, content, opts);
 
     if (content) {
@@ -140,6 +140,9 @@ export class BunSqliteStore implements Store {
       metadata?: Record<string, unknown>;
       created_at?: string;
       skipUpdatedAt?: boolean;
+      // Write-attribution (vault#298) — principal + interface of this edit.
+      actor?: string | null;
+      via?: string | null;
       if_updated_at?: string;
     },
   ): Promise<Note> {

package/core/src/types.ts

@@ -26,6 +26,19 @@ export interface Note {
   metadata?: Record<string, unknown>;
   createdAt: string; // ISO-8601
   updatedAt?: string;
+  /**
+   * Write-attribution (vault#298) — two axes of provenance, both nullable.
+   * `*By` is the principal (a JWT `sub`, or an operator / `token:<id>` label);
+   * `*Via` is the interface the write arrived through (`mcp`, `surface:<name>`,
+   * `agent:<id>`, `operator`/`cli`, `api`). The `created*` pair is set once at
+   * create; the `lastUpdated*` pair tracks the most recent mutating write. NULL
+   * = unknown / written before attribution existed (legacy rows) or by a path
+   * that carried no context — distinct from any real principal.
+   */
+  createdBy?: string | null;
+  createdVia?: string | null;
+  lastUpdatedBy?: string | null;
+  lastUpdatedVia?: string | null;
   tags?: string[];
   links?: Link[];
   /**
@@ -125,6 +138,15 @@ export interface QueryOpts {
   // 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>;
+  // Write-attribution filters (vault#298). Exact-match on the indexed
+  // attribution columns — "what did Mathilda write" (`createdBy`/`lastUpdatedBy`)
+  // or "what came in via the meeting-ingest surface"
+  // (`createdVia`/`lastUpdatedVia`). Each is an exact string match; multiple
+  // AND together with the rest of the filter set.
+  createdBy?: string;
+  lastUpdatedBy?: string;
+  createdVia?: string;
+  lastUpdatedVia?: string;
   // Legacy shorthand: filters on `n.created_at` (vault ingestion time).
   // Equivalent to `dateFilter: { field: "created_at", from, to }`. Kept
   // as the common path; specifying both this and `dateFilter` rejects.
@@ -206,6 +228,12 @@ export interface NoteIndex {
   extension?: string;
   createdAt: string;
   updatedAt?: string;
+  /** Write-attribution (vault#298) — carried on the lean shape too so "who
+   *  touched what" is answerable without re-fetching full content. See `Note`. */
+  createdBy?: string | null;
+  createdVia?: string | null;
+  lastUpdatedBy?: string | null;
+  lastUpdatedVia?: string | null;
   tags?: string[];
   metadata?: Record<string, unknown>;
   byteSize: number;
@@ -232,8 +260,10 @@ export interface Store {
    */
   readonly db: Database;
 
-  // Notes
-  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note>;
+  // Notes. `actor` / `via` carry write-attribution (vault#298) — the
+  // principal + interface stamped onto created_by/created_via (and mirrored
+  // into the last_updated_* pair on create). Omitted → attribution NULL.
+  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string; actor?: string | null; via?: string | null }): Promise<Note>;
   getNote(id: string): Promise<Note | null>;
   /**
    * Look up a note by path. Pass `extension` to disambiguate when
@@ -244,7 +274,7 @@ export interface Store {
    */
   getNoteByPath(path: string, extension?: string): Promise<Note | null>;
   getNotes(ids: string[]): Promise<Note[]>;
-  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; if_updated_at?: string }): Promise<Note>;
+  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; actor?: string | null; via?: string | null; if_updated_at?: string }): Promise<Note>;
   /**
    * Set a note's `created_at` and `updated_at` explicitly. Import-only:
    * used by the portable-md round-trip path to restore timestamps from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.3",
+  "version": "0.6.4-rc.2",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/admin-spa.test.ts

@@ -38,9 +38,22 @@ describe("isAdminSpaPath", () => {
     expect(isAdminSpaPath("/vault/work/admin/")).toBe(true);
     expect(isAdminSpaPath("/vault/work/admin/tokens")).toBe(true);
     expect(isAdminSpaPath("/vault/boulder/admin/assets/index.js")).toBe(true);
-    // Vault names with URL-safe punctuation should still match — the regex
-    // captures up to the next "/" so dashes / dots / digits all pass.
-    expect(isAdminSpaPath("/vault/my-vault.2/admin")).toBe(true);
+    // Canonical-charset names (lowercase alphanumerics + hyphen / underscore)
+    // match; dots are NOT canonical (see the vault#253 reject test below).
+    expect(isAdminSpaPath("/vault/my-vault_2/admin")).toBe(true);
+  });
+
+  test("vault#253: names outside the canonical charset do NOT match the mount", () => {
+    // The mount used to capture `[^/]+`, so a name hub can never manage
+    // (dots, @, unicode) still served the admin SPA. Aligning the mount to
+    // hub's VAULT_NAME_CHARSET_RE (`/^[a-z0-9_-]+$/`) makes a non-canonical
+    // name 404 — the same answer hub gives. No legitimately-created vault can
+    // carry these characters (cmdCreate / init / the env var all reject them
+    // via validateVaultName), so nothing reachable regresses.
+    expect(isAdminSpaPath("/vault/my.vault/admin")).toBe(false);
+    expect(isAdminSpaPath("/vault/vault@v2/admin")).toBe(false);
+    expect(isAdminSpaPath("/vault/Work/admin")).toBe(false); // uppercase isn't canonical
+    expect(isAdminSpaPath("/vault/🦑/admin")).toBe(false);
   });
 
   test("does not match adjacent paths under the same vault", () => {
@@ -111,8 +124,8 @@ describe("serveAdminSpa", () => {
     expect(cssRes.headers.get("content-type")).toContain("text/css");
   });
 
-  test("vault names with URL-safe punctuation strip cleanly", async () => {
-    const res = await serveAdminSpa(fixtureDir, "/vault/my-vault.2/admin/assets/index-abc.js");
+  test("canonical-charset vault names strip cleanly", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/my-vault_2/admin/assets/index-abc.js");
     expect(res.status).toBe(200);
     expect(res.headers.get("content-type")).toContain("application/javascript");
   });

package/src/admin-spa.ts

@@ -21,12 +21,33 @@ import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/**
+ * The canonical vault-name charset, kept byte-identical with hub's
+ * `VAULT_NAME_CHARSET_RE` (`parachute-hub/src/vault-name.ts`) and vault's own
+ * `validateVaultName` (`src/vault-name.ts`): lowercase alphanumerics plus
+ * hyphen / underscore. Embedded here (not imported) because this regex is
+ * spliced into the mount-matching patterns below, and a charset class is the
+ * only piece they share.
+ *
+ * vault#253: the mount regexes used to capture `[^/]+` (anything-but-slash),
+ * so a name like `my.vault` / `vault@v2` / `🦑` matched the admin mount and
+ * served the SPA — even though hub rejects those names at every name-minting
+ * edge and can never render a "Manage Vault" link for them. A vault that can't
+ * be created (cmdCreate / init / the env var all run `validateVaultName`, which
+ * rejects out-of-charset names) shouldn't have a reachable admin mount either.
+ * Pinning the mount to THIS charset closes the boundary drift: a dotted name
+ * no longer matches → 404, the same answer hub gives.
+ */
+const VAULT_NAME_CHARSET = "a-z0-9_-";
+
 /**
  * Regex anchoring the per-vault SPA mount. Matches `/vault/<name>/admin`
- * exactly and any subpath under it. The `<name>` capture is reused by the
- * prefix-strip below — keep the two in sync if this regex moves.
+ * exactly and any subpath under it, where `<name>` is a canonical vault name
+ * (lowercase alphanumerics + hyphen / underscore — see `VAULT_NAME_CHARSET`).
+ * The `<name>` capture is reused by the prefix-strip below — keep the two in
+ * sync if this regex moves.
  */
-const ADMIN_SPA_MOUNT_RE = /^\/vault\/([^/]+)\/admin(?=\/|$)/;
+const ADMIN_SPA_MOUNT_RE = new RegExp(`^/vault/([${VAULT_NAME_CHARSET}]+)/admin(?=/|$)`);
 
 /**
  * Regex anchoring the DAEMON-LEVEL multi-vault SPA mount at `/vault/admin`

package/src/attribution-threading.test.ts

@@ -0,0 +1,350 @@
+/**
+ * Write-attribution threading (vault#298) — the server-side half: how the
+ * authenticated request resolves the two provenance axes onto `AuthResult`,
+ * and how the MCP layer refines the `via` channel.
+ *
+ *   - WHO  (`actor`): JWT `sub` on the hub path; `operator` for the env-var
+ *     bearer; `token:<id>` for legacy YAML keys.
+ *   - VIA  (`via`):  `api` (credential class) on the REST path; `operator` for
+ *     the env-var bearer; refined to `mcp` by the MCP handler.
+ *
+ * The store-layer column behavior + query filters live in
+ * core/src/attribution.test.ts. This file pins the AUTH → AuthResult mapping
+ * and the MCP via-refinement end-to-end (an MCP create lands attribution in
+ * the row).
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { generateKeyPair, exportJWK, SignJWT } from "jose";
+import {
+  writeVaultConfig,
+  writeGlobalConfig,
+  readVaultConfig,
+  readGlobalConfig,
+  generateApiKey,
+  hashKey,
+} from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { authenticateVaultRequest } from "./auth.ts";
+import { resetJwksCache, resetRevocationCache } from "./hub-jwt.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import { parseNotesQueryOpts } from "./routes.ts";
+import type { AuthResult } from "./auth.ts";
+
+// ---------------------------------------------------------------------------
+// Hub-JWT fixture (mirrors auth-hub-jwt.test.ts)
+// ---------------------------------------------------------------------------
+interface Keypair {
+  privateKey: CryptoKey;
+  publicJwk: { kty: string; n: string; e: string; kid: string; alg: string; use: string };
+  kid: string;
+}
+async function makeKeypair(kid: string): Promise<Keypair> {
+  const { privateKey, publicKey } = await generateKeyPair("RS256", { extractable: true });
+  const jwk = await exportJWK(publicKey);
+  return {
+    privateKey,
+    publicJwk: { kty: "RSA", n: jwk.n!, e: jwk.e!, kid, alg: "RS256", use: "sig" },
+    kid,
+  };
+}
+function startHubFixture(keys: Keypair[]): { origin: string; stop: () => void } {
+  const server = Bun.serve({
+    port: 0,
+    async fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === "/.well-known/jwks.json") {
+        return Response.json({ keys: keys.map((k) => k.publicJwk) });
+      }
+      if (url.pathname === "/.well-known/parachute-revocation.json") {
+        return Response.json({ generated_at: new Date().toISOString(), jtis: [] });
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+  return { origin: `http://127.0.0.1:${server.port}`, stop: () => server.stop(true) };
+}
+async function signJwt(
+  kp: Keypair,
+  opts: { iss: string; aud: string; scope: string; sub?: string },
+): Promise<string> {
+  const iat = Math.floor(Date.now() / 1000);
+  return await new SignJWT({ scope: opts.scope, client_id: "test-client" })
+    .setProtectedHeader({ alg: "RS256", kid: kp.kid })
+    .setIssuer(opts.iss)
+    .setSubject(opts.sub ?? "user-1")
+    .setAudience(opts.aud)
+    .setIssuedAt(iat)
+    .setExpirationTime(iat + 60)
+    .setJti(`jti-${Math.random().toString(36).slice(2)}`)
+    .sign(kp.privateKey);
+}
+function bearer(token: string): Request {
+  return new Request("https://vault.test/x", { headers: { Authorization: `Bearer ${token}` } });
+}
+
+let tmpHome: string;
+let prevHome: string | undefined;
+let prevHubOrigin: string | undefined;
+let prevJwksOrigin: string | undefined;
+let prevAuthToken: string | undefined;
+let fixture: { origin: string; stop: () => void };
+let kp: Keypair;
+
+beforeEach(async () => {
+  tmpHome = join(tmpdir(), `vault-attr-thread-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+
+  kp = await makeKeypair("k1");
+  fixture = startHubFixture([kp]);
+  prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  prevJwksOrigin = process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+  prevAuthToken = process.env.VAULT_AUTH_TOKEN;
+  process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+  process.env.PARACHUTE_HUB_JWKS_ORIGIN = fixture.origin;
+  delete process.env.VAULT_AUTH_TOKEN;
+  resetJwksCache();
+  resetRevocationCache();
+});
+
+afterEach(() => {
+  fixture.stop();
+  clearVaultStoreCache();
+  const restore = (k: string, v: string | undefined) => {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  };
+  restore("PARACHUTE_HOME", prevHome);
+  restore("PARACHUTE_HUB_ORIGIN", prevHubOrigin);
+  restore("PARACHUTE_HUB_JWKS_ORIGIN", prevJwksOrigin);
+  restore("VAULT_AUTH_TOKEN", prevAuthToken);
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVaultWithKey(name: string): string {
+  const { fullKey, keyId } = generateApiKey();
+  writeVaultConfig({
+    name,
+    api_keys: [
+      {
+        id: keyId,
+        label: "bootstrap",
+        scope: "write",
+        key_hash: hashKey(fullKey),
+        created_at: new Date().toISOString(),
+      },
+    ],
+    created_at: new Date().toISOString(),
+  });
+  getVaultStore(name);
+  return fullKey;
+}
+
+function seedVaultNoKey(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  getVaultStore(name);
+}
+
+describe("attribution threading — AuthResult actor/via derivation", () => {
+  test("hub JWT → actor = sub, via = 'api' (the REST credential class)", async () => {
+    seedVaultNoKey("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      sub: "mathilda",
+    });
+    const result = await authenticateVaultRequest(bearer(token), readVaultConfig("journal")!);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.actor).toBe("mathilda");
+      expect(result.via).toBe("api");
+    }
+  });
+
+  test("VAULT_AUTH_TOKEN operator bearer → actor = via = 'operator'", async () => {
+    seedVaultNoKey("journal");
+    process.env.VAULT_AUTH_TOKEN = "super-secret-operator-bearer";
+    const result = await authenticateVaultRequest(
+      bearer("super-secret-operator-bearer"),
+      readVaultConfig("journal")!,
+    );
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.actor).toBe("operator");
+      expect(result.via).toBe("operator");
+    }
+  });
+
+  test("legacy YAML api_key → actor = 'token:<id>', via = 'api' (never crashes)", async () => {
+    const fullKey = seedVaultWithKey("journal");
+    const result = await authenticateVaultRequest(bearer(fullKey), readVaultConfig("journal")!);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.actor).toMatch(/^token:[0-9a-f]{1,}$/i);
+      expect(result.via).toBe("api");
+      expect(result.legacyDerived).toBe(true);
+    }
+  });
+});
+
+describe("attribution threading — MCP refines via to 'mcp' and stamps the write", () => {
+  function authFor(sub: string, vaultName: string): AuthResult {
+    return {
+      permission: "full",
+      scopes: [`vault:${vaultName}:write`, `vault:${vaultName}:read`],
+      legacyDerived: false,
+      scoped_tags: null,
+      vault_name: null,
+      caller_jti: null,
+      actor: sub,
+      via: "api", // base class from auth; the MCP layer should refine to "mcp"
+    };
+  }
+
+  test("a create-note through the MCP tools lands actor=sub + via='mcp'", async () => {
+    seedVaultNoKey("journal");
+    const auth = authFor("aaron", "journal");
+    const tools = generateScopedMcpTools("journal", auth, null);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const created = (await create.execute({ content: "via mcp" })) as {
+      id: string;
+      createdBy?: string | null;
+      createdVia?: string | null;
+      lastUpdatedVia?: string | null;
+    };
+    expect(created.createdBy).toBe("aaron");
+    expect(created.createdVia).toBe("mcp");
+    expect(created.lastUpdatedVia).toBe("mcp");
+
+    // Confirm it persisted to the row, not just the response shape.
+    const store = getVaultStore("journal");
+    const row = store.db
+      .prepare("SELECT created_by, created_via FROM notes WHERE id = ?")
+      .get(created.id) as { created_by: string | null; created_via: string | null };
+    expect(row.created_by).toBe("aaron");
+    expect(row.created_via).toBe("mcp");
+  });
+
+  test("an update-note through the MCP tools bumps last_updated_via='mcp'", async () => {
+    seedVaultNoKey("journal");
+    const store = getVaultStore("journal");
+    const seed = await store.createNote("seed", { actor: "aaron", via: "api" });
+
+    const auth = authFor("aaron", "journal");
+    const tools = generateScopedMcpTools("journal", auth, null);
+    const update = tools.find((t) => t.name === "update-note")!;
+    // `force: true` waives the optimistic-concurrency precondition (we don't
+    // echo updated_at in this focused test).
+    await update.execute({ id: seed.id, content: "edited via mcp", force: true });
+
+    const after = await store.getNote(seed.id);
+    expect(after?.createdVia).toBe("api"); // set-once original channel
+    expect(after?.lastUpdatedBy).toBe("aaron");
+    expect(after?.lastUpdatedVia).toBe("mcp"); // refined channel of the latest edit
+  });
+
+  test("update-note with if_missing:'create' on a MISSING note attributes the created row", async () => {
+    // Regression: the upsert-create branch built createOpts without actor/via,
+    // so an MCP-driven upsert that CREATES a note wrote NULL attribution while
+    // create-note + REST upsert-create did it right. (vault#298 review.)
+    seedVaultNoKey("journal");
+    const store = getVaultStore("journal");
+
+    const tools = generateScopedMcpTools("journal", authFor("aaron", "journal"), null);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const created = (await update.execute({
+      id: "Projects/Brand New",
+      content: "born via upsert",
+      if_missing: "create",
+    })) as { id: string; createdBy?: string | null; createdVia?: string | null };
+
+    // The note did not exist → this is a create; attribution must be set.
+    expect(created.createdBy).toBe("aaron");
+    expect(created.createdVia).toBe("mcp"); // refined channel, not NULL
+
+    // Confirm it persisted to the row, not just the echoed shape.
+    const row = store.db
+      .prepare(
+        "SELECT created_by, created_via, last_updated_by, last_updated_via FROM notes WHERE id = ?",
+      )
+      .get(created.id) as {
+      created_by: string | null;
+      created_via: string | null;
+      last_updated_by: string | null;
+      last_updated_via: string | null;
+    };
+    expect(row.created_by).toBe("aaron");
+    expect(row.created_via).toBe("mcp");
+    // First write IS the latest write — the last_updated_* pair mirrors it.
+    expect(row.last_updated_by).toBe("aaron");
+    expect(row.last_updated_via).toBe("mcp");
+  });
+
+  test("the operator bearer keeps via='operator' even on the MCP channel", async () => {
+    seedVaultNoKey("journal");
+    const auth: AuthResult = {
+      permission: "full",
+      scopes: ["vault:admin", "vault:write", "vault:read"],
+      legacyDerived: false,
+      scoped_tags: null,
+      vault_name: null,
+      caller_jti: null,
+      actor: "operator",
+      via: "operator",
+    };
+    const tools = generateScopedMcpTools("journal", auth, null);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const created = (await create.execute({ content: "op write" })) as {
+      createdVia?: string | null;
+    };
+    expect(created.createdVia).toBe("operator");
+  });
+
+  test("content_edit (surgical find-and-replace) also attributes the latest edit", async () => {
+    seedVaultNoKey("journal");
+    const store = getVaultStore("journal");
+    const seed = await store.createNote("hello WORLD", { actor: "aaron", via: "api" });
+
+    const tools = generateScopedMcpTools("journal", authFor("mathilda", "journal"), null);
+    const update = tools.find((t) => t.name === "update-note")!;
+    await update.execute({
+      id: seed.id,
+      content_edit: { old_text: "WORLD", new_text: "there" },
+      force: true,
+    });
+
+    const after = await store.getNote(seed.id);
+    expect(after?.content).toBe("hello there");
+    expect(after?.createdBy).toBe("aaron"); // set-once
+    expect(after?.lastUpdatedBy).toBe("mathilda"); // content_edit flows through updateNote
+    expect(after?.lastUpdatedVia).toBe("mcp");
+  });
+});
+
+describe("attribution threading — REST query filters (symmetric with MCP)", () => {
+  test("parseNotesQueryOpts wires the four attribution filter params", () => {
+    const url = new URL(
+      "http://localhost:1940/vault/journal/api/notes" +
+        "?created_by=aaron&last_updated_by=agent:nightly" +
+        "&created_via=surface:meeting-ingest&last_updated_via=mcp",
+    );
+    const { queryOpts } = parseNotesQueryOpts(url);
+    expect(queryOpts?.createdBy).toBe("aaron");
+    expect(queryOpts?.lastUpdatedBy).toBe("agent:nightly");
+    expect(queryOpts?.createdVia).toBe("surface:meeting-ingest");
+    expect(queryOpts?.lastUpdatedVia).toBe("mcp");
+  });
+
+  test("absent attribution params leave the filters undefined (no spurious filtering)", () => {
+    const url = new URL("http://localhost:1940/vault/journal/api/notes?tag=daily");
+    const { queryOpts } = parseNotesQueryOpts(url);
+    expect(queryOpts?.createdBy).toBeUndefined();
+    expect(queryOpts?.lastUpdatedVia).toBeUndefined();
+  });
+});