@openparachute/vault 0.6.3 → 0.6.4-rc.2

package/core/src/attribution.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Write-attribution (vault#298) — per-identity (`*_by`) + per-interface
+ * (`*_via`) provenance at the store layer.
+ *
+ * Covers the core contract:
+ *   - create stamps BOTH axes onto created_* AND mirrors into last_updated_*
+ *   - update bumps ONLY last_updated_* (created_* is set-once)
+ *   - a `skipUpdatedAt` machine write does NOT claim authorship
+ *   - no-attribution writes leave the columns NULL (never "")
+ *   - the four query-notes filters (created_by / last_updated_by /
+ *     created_via / last_updated_via)
+ *   - legacy rows written before the v23 migration stay NULL and don't crash
+ *   - the cursor binds the attribution filters (changing them invalidates it)
+ *
+ * The auth → AuthResult → MCP/REST threading is exercised separately in
+ * src/attribution-threading.test.ts (it needs the server-side auth context).
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { initSchema, SCHEMA_VERSION } from "./schema.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+function rawRow(id: string) {
+  return db
+    .prepare(
+      "SELECT created_by, created_via, last_updated_by, last_updated_via FROM notes WHERE id = ?",
+    )
+    .get(id) as {
+    created_by: string | null;
+    created_via: string | null;
+    last_updated_by: string | null;
+    last_updated_via: string | null;
+  };
+}
+
+describe("write-attribution — schema", () => {
+  it("bumped SCHEMA_VERSION to 23", () => {
+    expect(SCHEMA_VERSION).toBe(23);
+  });
+
+  it("the four columns exist and are indexed", () => {
+    const cols = (db.prepare("PRAGMA table_info(notes)").all() as { name: string }[]).map(
+      (r) => r.name,
+    );
+    expect(cols).toContain("created_by");
+    expect(cols).toContain("created_via");
+    expect(cols).toContain("last_updated_by");
+    expect(cols).toContain("last_updated_via");
+
+    const idx = (
+      db
+        .prepare("SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='notes'")
+        .all() as { name: string }[]
+    ).map((r) => r.name);
+    expect(idx).toContain("idx_notes_created_by");
+    expect(idx).toContain("idx_notes_created_via");
+    expect(idx).toContain("idx_notes_last_updated_by");
+    expect(idx).toContain("idx_notes_last_updated_via");
+  });
+});
+
+describe("write-attribution — per-identity (WHO) + per-interface (VIA)", () => {
+  it("create captures actor + via on BOTH the created_* and last_updated_* pairs", async () => {
+    const note = await store.createNote("hi", { actor: "aaron", via: "mcp" });
+    // Read-model surfaces both axes.
+    expect(note.createdBy).toBe("aaron");
+    expect(note.createdVia).toBe("mcp");
+    // First write IS the most-recent write — mirrored.
+    expect(note.lastUpdatedBy).toBe("aaron");
+    expect(note.lastUpdatedVia).toBe("mcp");
+
+    const row = rawRow(note.id);
+    expect(row.created_by).toBe("aaron");
+    expect(row.created_via).toBe("mcp");
+    expect(row.last_updated_by).toBe("aaron");
+    expect(row.last_updated_via).toBe("mcp");
+  });
+
+  it("update bumps last_updated_* but leaves created_* untouched (set-once)", async () => {
+    const note = await store.createNote("v1", { actor: "aaron", via: "mcp" });
+    const updated = await store.updateNote(note.id, {
+      content: "v2",
+      actor: "mathilda",
+      via: "surface:meeting-ingest",
+    });
+
+    // created_* pins the ORIGINAL author/channel forever.
+    expect(updated.createdBy).toBe("aaron");
+    expect(updated.createdVia).toBe("mcp");
+    // last_updated_* reflects the most recent writer.
+    expect(updated.lastUpdatedBy).toBe("mathilda");
+    expect(updated.lastUpdatedVia).toBe("surface:meeting-ingest");
+
+    const row = rawRow(note.id);
+    expect(row.created_by).toBe("aaron");
+    expect(row.last_updated_by).toBe("mathilda");
+    expect(row.last_updated_via).toBe("surface:meeting-ingest");
+  });
+
+  it("append/prepend updates also record the most-recent author", async () => {
+    const note = await store.createNote("base", { actor: "aaron", via: "mcp" });
+    const after = await store.updateNote(note.id, {
+      append: " +more",
+      actor: "agent:nightly",
+      via: "agent:nightly",
+    });
+    expect(after.content).toBe("base +more");
+    expect(after.createdBy).toBe("aaron");
+    expect(after.lastUpdatedBy).toBe("agent:nightly");
+    expect(after.lastUpdatedVia).toBe("agent:nightly");
+  });
+
+  it("a skipUpdatedAt machine write does NOT claim authorship", async () => {
+    const note = await store.createNote("x", { actor: "aaron", via: "mcp" });
+    const before = rawRow(note.id);
+    // A hook-style marker write: passes actor/via but skipUpdatedAt — should
+    // not bump updated_at NOR rewrite last_updated_*.
+    await store.updateNote(note.id, {
+      metadata: { marker: true },
+      skipUpdatedAt: true,
+      actor: "some-hook",
+      via: "operator",
+    });
+    const after = rawRow(note.id);
+    expect(after.last_updated_by).toBe(before.last_updated_by); // still "aaron"
+    expect(after.last_updated_by).toBe("aaron");
+    expect(after.last_updated_via).toBe("mcp");
+  });
+
+  it("an attribution-less update honestly clears the most-recent author (NULL, not stale)", async () => {
+    const note = await store.createNote("x", { actor: "aaron", via: "mcp" });
+    // A real edit arriving with no attribution context — the latest writer is
+    // unknown; we must NOT leave "aaron" as the apparent last editor.
+    const after = await store.updateNote(note.id, { content: "y" });
+    expect(after.createdBy).toBe("aaron"); // original author preserved
+    expect(after.lastUpdatedBy).toBeNull();
+    expect(after.lastUpdatedVia).toBeNull();
+  });
+});
+
+describe("write-attribution — no context → NULL (never empty string)", () => {
+  it("create without actor/via leaves all four columns NULL", async () => {
+    const note = await store.createNote("anon");
+    const row = rawRow(note.id);
+    expect(row.created_by).toBeNull();
+    expect(row.created_via).toBeNull();
+    expect(row.last_updated_by).toBeNull();
+    expect(row.last_updated_via).toBeNull();
+    expect(note.createdBy).toBeNull();
+    expect(note.createdVia).toBeNull();
+  });
+
+  it("empty / whitespace-only actor/via normalize to NULL", async () => {
+    const note = await store.createNote("e", { actor: "   ", via: "" });
+    const row = rawRow(note.id);
+    expect(row.created_by).toBeNull();
+    expect(row.created_via).toBeNull();
+  });
+});
+
+describe("write-attribution — query filters", () => {
+  beforeEach(async () => {
+    await store.createNote("a", { actor: "aaron", via: "mcp" });
+    await store.createNote("b", { actor: "mathilda", via: "surface:meeting-ingest" });
+    const c = await store.createNote("c", { actor: "aaron", via: "api" });
+    // c's most-recent write is by the nightly agent via mcp.
+    await store.updateNote(c.id, { content: "c2", actor: "agent:nightly", via: "mcp" });
+    await store.createNote("legacy"); // no attribution
+  });
+
+  it("created_by selects only that principal's CREATED notes", async () => {
+    const aaron = await store.queryNotes({ createdBy: "aaron" });
+    expect(aaron.map((n) => n.content).sort()).toEqual(["a", "c2"]);
+  });
+
+  it("last_updated_by selects by MOST-RECENT author (agent's edit on c)", async () => {
+    const byAgent = await store.queryNotes({ lastUpdatedBy: "agent:nightly" });
+    expect(byAgent.map((n) => n.content)).toEqual(["c2"]);
+    // aaron created c but is no longer its last editor.
+    const aaronLatest = await store.queryNotes({ lastUpdatedBy: "aaron" });
+    expect(aaronLatest.map((n) => n.content)).toEqual(["a"]);
+  });
+
+  it("created_via / last_updated_via filter on the interface axis", async () => {
+    const viaSurface = await store.queryNotes({ createdVia: "surface:meeting-ingest" });
+    expect(viaSurface.map((n) => n.content)).toEqual(["b"]);
+    const lastViaMcp = await store.queryNotes({ lastUpdatedVia: "mcp" });
+    // "a" (created via mcp, never updated) + "c2" (last updated via mcp).
+    expect(lastViaMcp.map((n) => n.content).sort()).toEqual(["a", "c2"]);
+  });
+
+  it("an attribution filter never matches legacy/unattributed (NULL) rows", async () => {
+    const any = await store.queryNotes({ createdBy: "aaron" });
+    expect(any.some((n) => n.content === "legacy")).toBe(false);
+  });
+});
+
+describe("write-attribution — legacy backfill (v23 migration)", () => {
+  it("a pre-v23 vault: existing rows stay NULL, new rows attribute, no crash", () => {
+    // Build a v22-shaped notes table by hand (no attribution columns) +
+    // schema_version row, then run initSchema to drive the v23 migration.
+    const legacy = new Database(":memory:");
+    legacy.exec(`
+      CREATE TABLE notes (
+        id TEXT PRIMARY KEY,
+        content TEXT DEFAULT '',
+        path TEXT,
+        metadata TEXT DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        updated_at TEXT,
+        extension TEXT NOT NULL DEFAULT 'md'
+      );
+      CREATE TABLE schema_version (version INTEGER PRIMARY KEY, applied_at TEXT);
+      INSERT INTO schema_version (version, applied_at) VALUES (22, '2026-01-01T00:00:00.000Z');
+      INSERT INTO notes (id, content, created_at, updated_at)
+        VALUES ('old-1', 'pre-existing', '2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z');
+    `);
+
+    // Should migrate without throwing.
+    initSchema(legacy);
+
+    const ver = (legacy.prepare("SELECT MAX(version) AS v FROM schema_version").get() as {
+      v: number;
+    }).v;
+    expect(ver).toBe(23);
+
+    // Legacy row: attribution columns exist now but are NULL (not fabricated).
+    const old = legacy
+      .prepare("SELECT created_by, last_updated_by, created_via FROM notes WHERE id = ?")
+      .get("old-1") as { created_by: string | null; last_updated_by: string | null; created_via: string | null };
+    expect(old.created_by).toBeNull();
+    expect(old.last_updated_by).toBeNull();
+    expect(old.created_via).toBeNull();
+
+    // A NEW write on the migrated DB attributes correctly.
+    const migratedStore = new SqliteStore(legacy);
+    return migratedStore.createNote("fresh", { actor: "aaron", via: "mcp" }).then((n) => {
+      expect(n.createdBy).toBe("aaron");
+      expect(n.createdVia).toBe("mcp");
+      // The legacy row is still NULL and still queryable.
+      return migratedStore.queryNotes({ createdBy: "aaron" }).then((res) => {
+        expect(res.map((x) => x.content)).toEqual(["fresh"]);
+      });
+    });
+  });
+
+  it("re-running the v23 migration is idempotent (no duplicate-column error)", () => {
+    const again = new Database(":memory:");
+    const s = new SqliteStore(again); // runs migrations once
+    initSchema(again); // run again — must not throw
+    expect(() => s.createNote("ok", { actor: "x", via: "api" })).not.toThrow();
+  });
+});
+
+describe("write-attribution — cursor binding", () => {
+  it("changing an attribution filter between cursor polls invalidates the cursor", async () => {
+    await store.createNote("a", { actor: "aaron", via: "mcp" });
+    const page = await store.queryNotesPaged({ createdBy: "aaron" });
+    // Reusing the cursor under a DIFFERENT createdBy must be rejected, not
+    // silently continue aaron's watermark.
+    await expect(
+      store.queryNotesPaged({ createdBy: "mathilda", cursor: page.next_cursor }),
+    ).rejects.toThrow(/different query/i);
+  });
+});

package/core/src/cursor.ts

@@ -160,6 +160,14 @@ export interface QueryHashInputs {
   extension?: string | string[];
   ids?: string[];
   metadata?: Record<string, unknown>;
+  // Write-attribution filters (vault#298) — part of the result-set-affecting
+  // opts, so they're bound into the cursor: changing "who/via" between polls
+  // invalidates the cursor with cursor_query_mismatch rather than silently
+  // continuing the prior filter's watermark.
+  createdBy?: string;
+  lastUpdatedBy?: string;
+  createdVia?: string;
+  lastUpdatedVia?: string;
   dateFrom?: string;
   dateTo?: string;
   dateFilter?: { field?: string; from?: string; to?: string };

package/core/src/mcp.ts

@@ -120,6 +120,16 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
  * expansion behaves exactly as before.
  */
 export interface GenerateMcpToolsOpts {
+  /**
+   * Write-attribution context (vault#298) stamped onto every note written
+   * through these tools. `actor` is the principal (JWT `sub` / operator
+   * label); `via` is the interface the write arrived through (here, always an
+   * MCP session — the server-side wrapper derives `mcp` or a more specific
+   * `agent:<id>` / `surface:<name>` when the token's claims reveal it). The
+   * core tools pass it straight into `store.createNote` / `store.updateNote`.
+   * Omitted (internal / unattributed callers) → writes leave attribution NULL.
+   */
+  writeContext?: { actor?: string | null; via?: string | null };
   expandVisibility?: (note: Note) => boolean;
   /**
    * `nearTraversable` (vault#439) is an OPTIONAL per-note predicate threaded
@@ -141,6 +151,11 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
   const db: Database = store.db;
   const expandVisibility = opts?.expandVisibility;
   const nearTraversable = opts?.nearTraversable;
+  // Write-attribution (vault#298) — captured once at tool-generation time
+  // (a fresh tool set is generated per MCP request, so this is request-scoped)
+  // and folded into every create/update the tools perform.
+  const writeActor = opts?.writeContext?.actor ?? null;
+  const writeVia = opts?.writeContext?.via ?? null;
 
   return [
 
@@ -220,6 +235,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             type: "object",
             description: "Filter by metadata values. Each value is either a primitive (exact match, scans JSON) or an operator object: `{eq|ne|gt|gte|lt|lte|in|not_in|exists: value}`. Operator objects require the field to be declared `indexed: true` in a tag schema — they route through the backing B-tree index. Multiple operators on one field AND together (e.g. `{gt: 5, lt: 10}`). `in`/`not_in` take arrays; `exists` takes a boolean.",
           },
+          created_by: { type: "string", description: "Write-attribution filter (vault#298): only notes whose FIRST write was attributed to this principal (a JWT subject, or an operator/token label). Exact match; indexed. Legacy/unattributed notes (NULL) never match." },
+          last_updated_by: { type: "string", description: "Write-attribution filter (vault#298): only notes whose MOST RECENT write was attributed to this principal. Exact match; indexed." },
+          created_via: { type: "string", description: "Write-attribution filter (vault#298): only notes FIRST written through this interface/channel — e.g. `mcp`, `surface:<name>`, `agent:<id>`, `operator`, `api`. Exact match; indexed." },
+          last_updated_via: { type: "string", description: "Write-attribution filter (vault#298): only notes whose MOST RECENT write came through this interface/channel. Exact match; indexed." },
           order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. The special value `link_count` sorts by link DEGREE (both-directions raw row count) — no declaration needed — matching the `include_link_count` field for every note. Direction is taken from `sort` (default 'asc'); `created_at` is appended as a stable tiebreaker." },
           date_from: { type: "string", description: "Start date (ISO, inclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', from }`." },
           date_to: { type: "string", description: "End date (ISO, exclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', to }`." },
@@ -460,6 +479,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             // result whenever the neighborhood lies outside that prefix.
             ids: nearScope ? [...nearScope] : undefined,
             metadata: params.metadata as Record<string, unknown> | undefined,
+            // Write-attribution filters (vault#298): "who wrote / via what."
+            createdBy: params.created_by as string | undefined,
+            lastUpdatedBy: params.last_updated_by as string | undefined,
+            createdVia: params.created_via as string | undefined,
+            lastUpdatedVia: params.last_updated_via as string | undefined,
             dateFrom: params.date_from as string | undefined,
             dateTo: params.date_to as string | undefined,
             dateFilter: params.date_filter as
@@ -643,6 +667,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               metadata: item.metadata as Record<string, unknown> | undefined,
               created_at: item.created_at as string | undefined,
               ...(extension !== undefined ? { extension } : {}),
+              // Write-attribution (vault#298) — same actor/via for every item
+              // in a batch (the whole call came from one authenticated session).
+              actor: writeActor,
+              via: writeVia,
             });
 
             // Create explicit links (not wikilinks — those are automatic)
@@ -714,7 +742,9 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 - For batch: pass a \`notes\` array, each with an \`id\` field.
 - **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
-- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.`,
+- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.
+
+Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\` (the principal + interface of the first write) and \`lastUpdatedBy\`/\`lastUpdatedVia\` (the most recent write). NULL on notes written before attribution existed. Filter on them with \`created_by\`/\`last_updated_by\`/\`created_via\`/\`last_updated_via\`.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -913,6 +943,12 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                 ...(item.metadata !== undefined ? { metadata: item.metadata as Record<string, unknown> } : {}),
                 ...(item.created_at !== undefined ? { created_at: item.created_at as string } : {}),
                 ...(createExt !== undefined ? { extension: createExt } : {}),
+                // Write-attribution (vault#298) — the if_missing:"create" upsert
+                // branch is still a CREATE, so it must stamp the same actor/via
+                // as the create-note tool + the REST upsert-create path. Without
+                // this an MCP-driven upsert-create wrote NULL attribution.
+                actor: writeActor,
+                via: writeVia,
               };
               const content = (item.content as string | undefined) ?? "";
               const created = await store.createNote(content, createOpts);
@@ -1060,6 +1096,13 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
           let result: Note;
           if (Object.keys(updates).length > 0) {
+            // Write-attribution (vault#298): stamp the most-recent-write
+            // columns on the same UPDATE that bumps `updated_at`. Only set when
+            // there's a real change to write (the empty-updates branch below
+            // leaves attribution untouched, symmetric with not bumping
+            // updated_at on a no-op).
+            updates.actor = writeActor;
+            updates.via = writeVia;
             // store.updateNote routes through noteOps.updateNote, which runs
             // the UPDATE (with optional `AND updated_at IS ?`) atomically and
             // throws ConflictError on mismatch. No mutations have happened

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);
@@ -321,6 +359,16 @@ 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
@@ -358,6 +406,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) {
@@ -601,6 +660,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 +980,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 +1673,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,
@@ -1703,6 +1793,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 +1813,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 +1883,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 +1911,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,
   };
 }