@openparachute/vault 0.6.4 → 0.6.5-rc.10

package/core/src/notes.ts

@@ -1,6 +1,7 @@
 import { Database, type SQLQueryBindings } from "bun:sqlite";
 import type { Note, NoteIndex, QueryOpts, QueryNotesPage, VaultStats } from "./types.js";
 import { normalizePath } from "./paths.js";
+import { transaction } from "./txn.js";
 import {
   buildOperatorClause,
   isOperatorObject,
@@ -20,6 +21,7 @@ import {
 } from "./cursor.js";
 import { getIndexedField, releaseField } from "./indexed-fields.js";
 import { stripTagHash } from "./tag-hierarchy.js";
+import { chunkForInClause, IN_VIA_JSON_EACH, jsonEachParam } from "./sql-in.js";
 
 let idCounter = 0;
 
@@ -177,10 +179,26 @@ export function getNoteByPath(db: Database, path: string, extension?: string): N
 
 export function getNotes(db: Database, ids: string[]): Note[] {
   if (ids.length === 0) return [];
-  const placeholders = ids.map(() => "?").join(", ");
-  const rows = db.prepare(
-    `SELECT * FROM notes WHERE id IN (${placeholders}) ORDER BY created_at`,
-  ).all(...ids) as NoteRow[];
+  // Dedupe before chunking: a duplicate id straddling two chunk boundaries
+  // would otherwise be fetched (and returned) twice, unlike the old single
+  // IN-list which returned each matching row once regardless of duplicate
+  // params. Matches getNoteTagsForNotes / getNoteSummaries.
+  const uniqueIds = [...new Set(ids)];
+  // Chunk under the DO 100-bound-param cap (see sql-in.ts). Each chunk is its
+  // own IN-list query; results are merged and re-sorted by created_at (with id
+  // as a deterministic tiebreak) to preserve the single-statement ORDER BY.
+  const rows: NoteRow[] = [];
+  for (const chunk of chunkForInClause(uniqueIds)) {
+    const placeholders = chunk.map(() => "?").join(", ");
+    rows.push(...db.prepare(
+      `SELECT * FROM notes WHERE id IN (${placeholders})`,
+    ).all(...chunk) as NoteRow[]);
+  }
+  rows.sort((a, b) =>
+    a.created_at < b.created_at ? -1
+    : a.created_at > b.created_at ? 1
+    : a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
+  );
   return notesWithTags(db, rows);
 }
 
@@ -755,9 +773,13 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
       // with an always-false condition; building `IN ()` would be a SQL error.
       conditions.push("0 = 1");
     } else {
-      const placeholders = opts.ids.map(() => "?").join(", ");
-      conditions.push(`n.id IN (${placeholders})`);
-      params.push(...opts.ids);
+      // Bind the id-set as ONE json_each param, not one `?` per id: this IN is
+      // embedded in a paginated statement (shared ORDER BY / LIMIT / OFFSET),
+      // so it can't be chunked, and `near` neighborhoods routinely exceed the
+      // DO 100-bound-param cap. json_each keeps the whole set at a single
+      // bound param. See sql-in.ts.
+      conditions.push(`n.id IN ${IN_VIA_JSON_EACH}`);
+      params.push(jsonEachParam(opts.ids));
     }
   }
 
@@ -1043,10 +1065,6 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   return fetchNotesByIdsOrdered(db, idRows.map((r) => r.id));
 }
 
-/** Chunk size for IN-list queries — comfortably under SQLite's conservative
- *  999 bound-variable floor (older builds), matching getLinkCounts. */
-const IN_CHUNK = 900;
-
 /**
  * Fetch full note rows for `ids`, preserving the input order, with tags
  * hydrated via ONE batched query per chunk (not one per note). Ids not
@@ -1055,8 +1073,9 @@ const IN_CHUNK = 900;
 function fetchNotesByIdsOrdered(db: Database, ids: string[]): Note[] {
   if (ids.length === 0) return [];
   const rowsById = new Map<string, NoteRow>();
-  for (let i = 0; i < ids.length; i += IN_CHUNK) {
-    const chunk = ids.slice(i, i + IN_CHUNK);
+  // Chunk under the DO 100-bound-param cap (see sql-in.ts) — a single export
+  // page (EXPORT_BATCH_SIZE=500) or a large query result exceeds it otherwise.
+  for (const chunk of chunkForInClause(ids)) {
     const placeholders = chunk.map(() => "?").join(", ");
     const rows = db.prepare(
       `SELECT * FROM notes WHERE id IN (${placeholders})`,
@@ -1083,8 +1102,8 @@ export function getNoteTagsForNotes(db: Database, noteIds: string[]): Map<string
   if (noteIds.length === 0) return map;
   const ids = [...new Set(noteIds)];
   for (const id of ids) map.set(id, []);
-  for (let i = 0; i < ids.length; i += IN_CHUNK) {
-    const chunk = ids.slice(i, i + IN_CHUNK);
+  // Chunk under the DO 100-bound-param cap (see sql-in.ts).
+  for (const chunk of chunkForInClause(ids)) {
     const placeholders = chunk.map(() => "?").join(", ");
     const rows = db.prepare(
       `SELECT note_id, tag_name FROM note_tags WHERE note_id IN (${placeholders}) ORDER BY tag_name`,
@@ -1438,8 +1457,7 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
     return { error: "target_exists", conflicting };
   }
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  const result = transaction(db, (): RenameTagSuccess => {
     let renamedNoteTags = 0;
     let pathsRenamed = 0;
 
@@ -1600,9 +1618,7 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       }
     }
 
-    db.exec("COMMIT");
-
-    const result: RenameTagSuccess = {
+    return {
       renamed: renamedNoteTags,
       sub_tags_renamed: renames.length - 1,
       parent_refs_updated: parentRefsUpdated,
@@ -1611,21 +1627,18 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       notes_rewritten: notesRewritten,
       paths_renamed: pathsRenamed,
     };
+  });
 
-    // Audit log: single line so operators searching `[vault] tag rename`
-    // can correlate cascades after the fact. Includes the stats and the
-    // mapping for non-trivial sub-tag cases.
-    console.error(
-      `[vault] tag rename cascade: ${oldName} → ${newName}` +
-        (renames.length > 1 ? ` (+${renames.length - 1} sub-tags)` : "") +
-        ` — note_tags:${result.renamed} parent_refs:${result.parent_refs_updated} tokens:${result.tokens_updated} indexed:${result.indexed_field_declarers_updated} notes:${result.notes_rewritten} paths:${result.paths_renamed}`,
-    );
+  // Audit log: single line so operators searching `[vault] tag rename`
+  // can correlate cascades after the fact. Includes the stats and the
+  // mapping for non-trivial sub-tag cases.
+  console.error(
+    `[vault] tag rename cascade: ${oldName} → ${newName}` +
+      (renames.length > 1 ? ` (+${renames.length - 1} sub-tags)` : "") +
+      ` — note_tags:${result.renamed} parent_refs:${result.parent_refs_updated} tokens:${result.tokens_updated} indexed:${result.indexed_field_declarers_updated} notes:${result.notes_rewritten} paths:${result.paths_renamed}`,
+  );
 
-    return result;
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  return result;
 }
 
 function emptyCascadeResult(): RenameTagSuccess {
@@ -1768,8 +1781,7 @@ export function mergeTags(
 
   const merged: Record<string, number> = {};
 
-  db.exec("BEGIN");
-  try {
+  transaction(db, () => {
     // Target might not exist yet. Seed it so INSERT OR IGNORE into note_tags
     // can reference it; leave any existing schema on target untouched.
     db.prepare("INSERT OR IGNORE INTO tags (name) VALUES (?)").run(target);
@@ -1796,12 +1808,7 @@ export function mergeTags(
       deleteTagStmt.run(source);
       merged[source] = before;
     }
-
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   return { merged, target };
 }
@@ -1999,8 +2006,7 @@ export interface BulkNoteInput {
 export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
   const results: Note[] = [];
 
-  db.exec("BEGIN");
-  try {
+  transaction(db, () => {
     for (const input of inputs) {
       results.push(
         createNote(db, input.content, {
@@ -2015,11 +2021,7 @@ export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
         }),
       );
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   return results;
 }
@@ -2032,8 +2034,7 @@ export function batchTag(db: Database, noteIds: string[], tags: string[]): numbe
   const bareTags = tags.map(stripTagHash).filter((t) => t !== "");
   let count = 0;
 
-  db.exec("BEGIN");
-  try {
+  transaction(db, () => {
     for (const tag of bareTags) {
       insertTag.run(tag);
     }
@@ -2043,11 +2044,7 @@ export function batchTag(db: Database, noteIds: string[], tags: string[]): numbe
         count++;
       }
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   return count;
 }
@@ -2059,19 +2056,14 @@ export function batchUntag(db: Database, noteIds: string[], tags: string[]): num
   const bareTags = tags.map(stripTagHash).filter((t) => t !== "");
   let count = 0;
 
-  db.exec("BEGIN");
-  try {
+  transaction(db, () => {
     for (const noteId of noteIds) {
       for (const tag of bareTags) {
         stmt.run(noteId, tag);
         count++;
       }
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   return count;
 }

package/core/src/onboarding.ts

@@ -1,300 +1,18 @@
 /**
- * Onboarding doctrine — the in-vault guide a freshly-created vault seeds so a
- * connected AI can self-orient and set the vault up on the operator's behalf.
+ * DEPRECATED back-compat shim — the onboarding content moved to
+ * `seed-packs.ts` (named seed packs: `welcome` / `getting-started` /
+ * `surface-starter`, one canonical content module for both the bun and cloud
+ * runtimes).
  *
- * This module is the single source of truth for the *content* + the *paths* of
- * the seeded notes. It lives in `core` (not `src`) so both:
- *   - the seeding path (`src/onboarding-seed.ts`, called from `createVault`), and
- *   - the projection/`vault-info` pointer (`core/src/vault-projection.ts`)
- * can share the canonical note paths without a cross-layer import.
- *
- * The notes are AI-legible, practical (SKILL.md-style) guides addressed to the
- * assistant that connects to the vault. They are a starting point, not gospel —
- * Getting Started tells the AI it can adapt them as the vault matures. Seeding is
- * create-time only and idempotent (never clobbers a note the operator/AI has
- * since edited).
- *
- * See the demo-prep Workstream A (A1/A2/A3).
- */
-
-/** Canonical path of the seeded onboarding guide. Top-level, title-cased so it
- *  reads as a doc and sorts to the top of a casual file listing. */
-export const GETTING_STARTED_PATH = "Getting Started";
-
-/** Canonical path of the seeded surface-build starter, linked from Getting
- *  Started. */
-export const SURFACE_STARTER_PATH = "Surface Starter";
-
-/**
- * Body of the seeded `Getting Started` note.
- *
- * Voice: addressed to the connected AI ("you"), practical, SKILL.md-style.
- * Covers (a) what a Parachute vault is, (b) tags-vs-paths-vs-schemas design,
- * (c) importing existing notes, (d) that it's an adaptable starting point.
- */
-export const GETTING_STARTED_CONTENT = `# Getting Started
-
-This is the **start-here guide** for this Parachute vault — think of it like a
-\`SKILL.md\`: practical instructions for setting up and growing the vault. Read it
-when you're **getting the vault started** or orienting yourself to it — you don't
-need to re-read it every session. It's a **starting point, not a script**, and
-it's adaptable: edit it (see "Adapt this note") as the vault takes shape.
-
-When the operator says something like *"help me set up my parachute,"* this is
-your brief: design their structure with them, import what they already have, and
-shape the vault around how they actually think and work.
-
-## What a Parachute vault is
-
-A vault is **notes + tags + links** in one graph, reachable over MCP (you, now),
-a REST API (scripts), and any surface (a UI). It ships *blank* — no predefined
-tags or schema. You and the operator design the structure that fits *their*
-life and work. The vault is the engine; the meaning is yours to bring.
-
-Core moves you already have as MCP tools:
-- \`create-note\` / \`update-note\` / \`delete-note\` — write notes (single or batch).
-- \`query-notes\` — by id/path, by tag, full-text \`search\`, or graph \`near\` a note.
-- \`list-tags\` / \`update-tag\` / \`delete-tag\` — manage the tag vocabulary + schemas.
-- \`find-path\` — shortest link path between two notes.
-- \`vault-info\` — refresh the live schema/stats projection any time.
-
-\`[[wikilinks]]\` in note content auto-link to the note at that path — use them
-freely; they resolve even if the target is created later.
-
-## Tags vs paths vs schemas — the design vocabulary
-
-These three axes are the heart of vault design. Use the right one for the job:
-
-- **Tags = types / membership.** A tag answers *"what kind of thing is this?"*
-  (\`#person\`, \`#meeting\`, \`#project\`). Queries **expand over tags**: a tag can
-  declare \`parent_names\` so \`tag:X\` also returns its subtypes (e.g. tagging a
-  note \`#meeting/standup\` with \`parent_names: [meeting]\` means \`query-notes
-  { tag: "meeting" }\` finds it). Tags are how you ask *"show me all my people."*
-  This is the primary structure — reach for a tag first.
-
-- **Paths = organization / filing.** A path (\`Projects/Acme/Kickoff\`) is *where*
-  a note lives — a human-browsable address, unique per note. Paths are for
-  folders and named docs (like this one). They do **not** drive type queries;
-  don't encode meaning in a path that a tag should carry. A note can have a
-  path, tags, or both.
-
-- **Schemas = typed metadata fields.** Attach a schema to a tag (via
-  \`update-tag\`) to declare typed metadata fields — e.g. \`#meeting\` with a
-  \`held_on\` date, \`#person\` with an \`email\`. Each field can **optionally** be
-  marked \`indexed: true\` to make it **queryable with operators** (\`query-notes
-  { tag: "meeting", metadata: { held_on: { gte: "2026-01-01" } } }\`); indexing
-  is opt-in per field, not automatic. Add a schema (and index a field) when you
-  find yourself wanting to filter or sort on a value, not before.
-
-Rule of thumb: **type with tags, file with paths, make-it-queryable with
-schemas.** Start minimal — invent tags as real notes need them, declare a
-schema only when a query demands it. Over-designing an empty vault is the
-common mistake.
-
-Declaring a schema is one \`update-tag\` call — the \`fields\` object maps each
-field name to \`{ type, enum?, indexed? }\` (\`type\` is \`"string"\`, \`"boolean"\`,
-or \`"integer"\`):
-
-\`\`\`
-update-tag {
-  tag: "meeting",
-  description: "A meeting with notes",
-  fields: {
-    held_on: { type: "string", indexed: true },              // queryable with operators
-    status:  { type: "string", enum: ["scheduled", "done"] }, // first enum value is the default
-    rating:  { type: "integer" }
-  }
-}
-\`\`\`
-
-\`fields\` is **merged** (new keys added, existing replaced); \`parent_names\` and
-\`relationships\` are replaced wholesale when passed. Only \`indexed: true\` fields
-support operator queries (\`metadata: { held_on: { gte: "..." } }\`) and
-\`order_by\`; all tags declaring the same field must agree on its \`type\` and
-\`indexed\` flag.
-
-## Write gotchas
-
-A few behaviors worth knowing before you write at scale:
-
-- **\`update-note\` requires optimistic concurrency by default.** Pass
-  \`if_updated_at\` with the \`updated_at\` you last read; a mismatch returns a
-  conflict error (re-read, reconcile, retry). For bulk/scripted writes where
-  concurrency is known-safe, pass \`force: true\` to waive the *requirement to
-  supply* it. \`append\`/\`prepend\`-only updates are exempt (no-conflict-by-design).
-- **A schema field's default is filled in on write, so it shows up even when you
-  didn't set it.** When a note gets a tag whose schema declares a field, the
-  missing field is back-filled: an \`enum\` field → its **first listed value**, an
-  \`integer\` → \`0\`, a \`boolean\` → \`false\`, a plain string → \`""\`. So a
-  \`rating: { type: "integer" }\` reads as \`0\` on notes nobody rated — that \`0\`
-  is "unset," not "rated zero." Order an \`enum\`'s values so the first is a sane
-  default, and don't read a back-filled \`0\`/\`""\`/\`false\` as a real value.
-- **Validation is advisory, never blocking.** A type/enum mismatch comes back as
-  a \`validation_status\` warning on the write response — the write still lands.
-  Read those warnings and self-correct on the next turn.
-
-(Full design guide, with copy-paste examples: https://parachute.computer/scripting/)
-
-## Importing existing notes
-
-If the operator already keeps notes (Obsidian, Markdown, etc.), bring them in
-rather than starting cold:
-
-- **Obsidian / a Markdown folder:** \`parachute-vault import <path>\` — preserves
-  frontmatter, tags, \`[[wikilinks]]\`, and file paths.
-- **A portable Parachute export** (a dir with \`.parachute/vault.yaml\`): the same
-  \`import\` command auto-detects it and does a lossless round-trip (ids, typed
-  links, tag schemas, attachments).
-- **Ad hoc / pasted content:** just \`create-note\` it. Then help the operator tag
-  and schematize: read a sample of imported notes, propose a small tag
-  vocabulary, and apply it.
-
-After an import, orient yourself: \`vault-info\` for the new schema picture,
-\`list-tags\` to see what vocabulary arrived, \`query-notes { search: "..." }\` to
-spot-check. Then propose structure — don't impose it silently.
-
-## Later: a custom surface
-
-Building a custom UI over the vault (a dashboard, a notes app) is usually **not**
-the starting point — get the notes and structure right first. If and when the
-operator wants one, see **[[Surface Starter]]** (built with
-\`@openparachute/surface-client\` + \`@openparachute/surface-render\`).
-
-## Adapt this note
-
-This guide is a **default starting point, not gospel** — edit it to fit this
-vault. As you and the operator settle on a tag vocabulary, conventions, or a
-surface, you can record that here so a future session inherits the current shape
-of the vault instead of this blank-slate default. Useful things to capture:
-- the tag vocabulary you've settled on and what each tag means;
-- naming/path conventions for this vault;
-- which schemas exist and why;
-- anything a fresh AI would need to be immediately useful.
-
-Treat setup as a relationship, not a one-time install.
-`;
-
-/**
- * Body of the seeded `Surface Starter` note. Linked from Getting Started.
- *
- * A concise, *living* starter prompt for building a custom surface (UI) over
- * the vault using the published surface packages. Tells the AI to import the
- * packages rather than hand-roll OAuth/API/rendering.
+ * Kept so existing importers (including out-of-repo consumers of core, e.g.
+ * parachute-cloud's `file:` dep) keep resolving. New code imports from
+ * `seed-packs.ts` directly — prefer the `SeedPack` objects + `applySeedPack`
+ * over these raw constants.
  */
-export const SURFACE_STARTER_CONTENT = `# Surface Starter
-
-A **surface** is a custom UI over this vault — a dashboard, a notes app, a
-single-purpose tool. This note is a living starter for building one *with the
-operator*. Update it as you settle on a stack, conventions, or a deployed
-surface for this vault.
-
-## ⚠️ Build a surface in your editor, not from this session
-
-A surface runs **in a browser**: it needs a real OAuth round-trip (a redirect to
-the hub's consent screen and back), a dev server to serve the app, and a CORS
-origin the hub trusts. **None of that exists in this MCP/chat session** — there's
-no browser, no redirect, no dev server. So **don't try to "run" a surface from
-the vault session.** Build it in **Claude Code (or your editor)** against a local
-dev server (\`vite\`/\`bun dev\`), sign in through the browser there, and iterate.
-From *this* session you design the vault structure the surface will consume and
-write the code — you can't exercise the OAuth/render loop here.
-
-## Don't hand-roll the plumbing
-
-Two published packages do the heavy lifting — import them instead of writing
-OAuth, the vault API client, or note rendering by hand:
-
-- **\`@openparachute/surface-client\`** — \`createVaultSurface(...)\` wires up
-  Parachute OAuth (sign-in on first connect) and a typed vault API client
-  (query/create/update notes, tags, links) so your app code just calls methods.
-- **\`@openparachute/surface-render\`** — \`<NoteRenderer>\` and friends render note
-  content (Markdown, wikilinks, embeds) the way the rest of the ecosystem does,
-  so your surface looks native without re-implementing the renderer.
-
-## Minimal end-to-end (config → sign-in → query → render)
-
-A React sketch wiring all four steps. \`createVaultSurface\` is the only required
-config (its \`clientName\` is the sole required option; \`hubUrl\` defaults to the
-page origin, \`vaultName\` to \`"default"\`, \`scope\` to \`"vault:read vault:write"\`).
-\`getClient()\` returns a \`VaultClient\` (or \`null\` until signed in) whose
-\`queryNotes()\` takes the same query grammar you use over MCP. See
-[[Getting Started]] / \`vault-info\` for this vault's NAME and hub origin.
-
-\`\`\`tsx
-import { useEffect, useState } from "react";
-import { createVaultSurface, type Note } from "@openparachute/surface-client";
-import { NoteRenderer } from "@openparachute/surface-render";
-
-// One surface per (hub, vault) config. clientName shows on the consent screen.
-const surface = createVaultSurface({
-  clientName: "My Vault Surface",
-  hubUrl: "https://your-hub.example",   // omit to default to window.location.origin
-  vaultName: "default",                 // this vault's name (see vault-info)
-});
-
-export function App() {
-  const [notes, setNotes] = useState<Note[] | null>(null);
-
-  useEffect(() => {
-    (async () => {
-      // OAuth: finish a redirect callback if we're on it, else send the browser
-      // off to sign in. handleCallback() needs BOTH code + state, so guard on
-      // both. (Real apps route /oauth/callback to its own component.)
-      const q = new URLSearchParams(location.search);
-      if (q.get("code") && q.get("state")) await surface.handleCallback();
-      // getClient() builds a FRESH VaultClient on each call — fine here (one-shot
-      // effect); in a real component keep it in state/ref, don't call it per render.
-      const client = surface.getClient(); // VaultClient | null (null = not signed in)
-      if (!client) return void surface.login();
-      setNotes(await client.queryNotes({ tag: "note", limit: 20 }));
-    })();
-  }, []);
-
-  if (!notes) return <p>Connecting…</p>;
-  return (
-    <>
-      {notes.map((n) => (
-        // resolve maps a [[wikilink]] target → { href, exists } (or null = inert).
-        // You own this href's trust boundary — keep it a fragment (or validate the
-        // target). Don't build a raw passthrough href: a vault note could carry a
-        // javascript: target.
-        <NoteRenderer
-          key={n.id}
-          note={n}
-          resolve={(target) => ({ href: \`#/n/\${encodeURIComponent(target)}\`, exists: true })}
-        />
-      ))}
-    </>
-  );
-}
-\`\`\`
-
-That's the whole spine. \`<NoteRenderer>\` also takes \`linkComponent\` (your
-router's \`<Link>\`) and \`fetchBlob\` (\`(url) => Promise<Blob>\`, for auth'd
-image/audio embeds) when you need them — both optional.
-
-## Build order
-
-1. **Auth + data first.** Stand up \`createVaultSurface\` pointed at this vault;
-   confirm you can sign in and \`queryNotes\` round-trips before any UI polish.
-2. **Render next.** Drop in \`<NoteRenderer>\` to display note content; wire
-   wikilink/embed resolution through the package, not by hand.
-3. **UX last.** Layout, navigation, and the surface's actual purpose — now that
-   auth, data, and rendering are solid.
-
-## Design it around this vault's structure
-
-A good surface is shaped by the vault's tags + schemas (see [[Getting Started]]
-for the tags-vs-paths-vs-schemas design vocabulary). Query by the tags that
-matter to the operator; surface the indexed fields they filter on. If the vault
-doesn't yet have the structure a surface wants, that's a signal to design tags +
-schemas first.
-
-## Adapt this note
-
-When you build a surface for this vault, record it here: what it's for, the
-stack, how to run it, the queries it depends on. The next session should be able
-to pick it up from this note.
 
-(More on the surface stack + examples: https://parachute.computer/scripting/)
-`;
+export {
+  GETTING_STARTED_PATH,
+  GETTING_STARTED_CONTENT,
+  SURFACE_STARTER_PATH,
+  SURFACE_STARTER_CONTENT,
+} from "./seed-packs.ts";

package/core/src/portable-md-batching.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Batched-export coverage (Phase-1 streaming refactor). The export walk
+ * streams notes in windows of `EXPORT_BATCH_SIZE` (500) instead of one
+ * full-corpus query. These tests prove the windowing walks EVERY note across
+ * the batch boundaries — both a non-multiple remainder (1,203 = 500 + 500 +
+ * 203, so the final partial batch is exercised) and an exact multiple (1,000
+ * = 500 + 500 + a terminating empty query), with a sentinel note pinned in
+ * the final batch so an off-by-one that dropped the tail would fail loudly.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { existsSync, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import { SqliteStore } from "./store.js";
+import { exportVaultToDir } from "./portable-md.js";
+
+/** Zero-padded so lexicographic id order == numeric order (the export walks
+ *  `created_at ASC, id ASC`; fresh notes share a created_at so id breaks the
+ *  tie — this makes the batch membership of each note deterministic). */
+const pad = (i: number): string => String(i).padStart(5, "0");
+
+async function seed(store: SqliteStore, n: number): Promise<void> {
+  const inputs = [];
+  for (let i = 0; i < n; i++) {
+    inputs.push({ content: `note ${i}`, id: `n${pad(i)}`, path: `notes/n${pad(i)}` });
+  }
+  await store.createNotes(inputs);
+}
+
+describe("exportVaultToDir — batched walk across boundaries", () => {
+  let store: SqliteStore;
+  let outDir: string;
+
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+    outDir = mkdtempSync(join(tmpdir(), "portable-batch-"));
+  });
+  afterEach(() => {
+    try { rmSync(outDir, { recursive: true, force: true }); } catch {}
+  });
+
+  it("walks all 1,203 notes (2 full batches + a 203-note remainder)", async () => {
+    await seed(store, 1203);
+    const stats = await exportVaultToDir(store, { outDir, exportedAt: "2026-07-02T00:00:00.000Z" });
+
+    expect(stats.notes).toBe(1203);
+    // First note, both interior batch boundaries, and the sentinel in the
+    // final partial batch must all be on disk.
+    expect(existsSync(join(outDir, "notes/n00000.md"))).toBe(true); // batch 1 head
+    expect(existsSync(join(outDir, "notes/n00500.md"))).toBe(true); // batch 2 head
+    expect(existsSync(join(outDir, "notes/n01000.md"))).toBe(true); // batch 3 head
+    expect(existsSync(join(outDir, "notes/n01202.md"))).toBe(true); // last partial-batch sentinel
+  });
+
+  it("walks all notes on an exact multiple of the batch size (1,000 = 2×500 + terminating empty query)", async () => {
+    await seed(store, 1000);
+    const stats = await exportVaultToDir(store, { outDir, exportedAt: "2026-07-02T00:00:00.000Z" });
+
+    expect(stats.notes).toBe(1000);
+    expect(existsSync(join(outDir, "notes/n00000.md"))).toBe(true);
+    expect(existsSync(join(outDir, "notes/n00500.md"))).toBe(true);
+    expect(existsSync(join(outDir, "notes/n00999.md"))).toBe(true); // last note of the final full batch
+  });
+});

package/core/src/portable-md-golden.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Golden-bytes regression for the portable-md streaming export refactor
+ * (Phase-1 shared-core, vault cloud design §4).
+ *
+ * `core/src/__fixtures__/portable-export-golden.json` was captured from the
+ * PRE-refactor (full-corpus, sync-fs) exporter by
+ * `scripts/capture-portable-golden.ts`. This test builds the SAME
+ * deterministic vault and asserts the CURRENT exporter reproduces those
+ * bytes exactly — the streaming/source-sink rewrite must be byte-for-byte
+ * indistinguishable on the fs backend. A diff here is a real format drift,
+ * not test flake (both sides share `buildGoldenVault` + `serializeExportTree`
+ * from the fixture module, so a fixture-vs-test mismatch is impossible).
+ *
+ * If a format change is ever intentional, re-run the capture script against
+ * the new code, review the JSON diff, and commit both together.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import { SqliteStore } from "./store.js";
+import { exportVaultToDir } from "./portable-md.js";
+import {
+  buildGoldenVault,
+  serializeExportTree,
+  GOLDEN_EXPORTED_AT,
+} from "./__fixtures__/golden-vault.js";
+import goldenTree from "./__fixtures__/portable-export-golden.json";
+
+describe("portable-md golden bytes — new exporter == old-exporter fixture", () => {
+  it("reproduces the captured export tree byte-for-byte", async () => {
+    const store = new SqliteStore(new Database(":memory:"));
+    await buildGoldenVault(store);
+
+    const outDir = mkdtempSync(join(tmpdir(), "portable-golden-test-"));
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "golden",
+        vaultDescription: "portable-md byte-stability fixture",
+        exportedAt: GOLDEN_EXPORTED_AT,
+        caseSensitiveOverride: true,
+      });
+      const tree = serializeExportTree(outDir);
+      // Compare as objects (per-file byte equality) — a keyed diff points
+      // straight at the drifting file if this ever fails.
+      expect(tree).toEqual(goldenTree as Record<string, string>);
+    } finally {
+      rmSync(outDir, { recursive: true, force: true });
+    }
+  });
+});