@openparachute/vault 0.7.3-rc.4 → 0.7.3-rc.5

package/core/src/seed-packs.ts

@@ -1025,6 +1025,14 @@ export interface ApplySeedPackResult {
   pack: string;
   /** Tag names upserted (upserts are idempotent; always every declared tag). */
   tags: string[];
+  /**
+   * Subset of `tags` whose DESCRIPTION was left untouched this run because it
+   * had been hand-edited away from the pack's canonical text (see
+   * `applySeedPack`'s description-preservation rule below). `fields` /
+   * `parent_names` / `relationships` are still upserted unconditionally for
+   * these tags — only the description write was skipped.
+   */
+  preservedTagDescriptions: string[];
   /** Note paths written this run (absent ones). */
   seededNotes: string[];
   /** Note paths skipped because a note already lives there (idempotency). */
@@ -1037,6 +1045,30 @@ export interface ApplySeedPackResult {
  * rows — so a re-run can never duplicate, and never clobbers a note the
  * operator/AI has since edited or recreated.
  *
+ * **Tag description preservation** (Aaron-ratified 2026-07-17): a pack writes
+ * a tag's `description` only when (a) the tag has no prior description (new
+ * tag, or an existing bare row nothing ever described), or (b) the prior
+ * description is still byte-identical to the pack's own text — i.e. no one
+ * has touched it. The moment a description differs from the pack's current
+ * text, it's treated as a deliberate hand edit (a user-tuned "constitution")
+ * and is never overwritten by a re-apply; omitting the `description` key from
+ * the `upsertTagRecord` patch is what preserves it (the store keeps whatever
+ * is already there). `fields` / `parent_names` / `relationships` are NOT
+ * given this treatment here — they still upsert unconditionally, same as
+ * before this change; those axes are more entangled with schema-validation
+ * side effects (indexed-column lifecycle, cross-tag type agreement) to
+ * safely split out in this pass. Description-only is the ratified scope.
+ *
+ * Known, accepted tradeoff: this compares against the pack's CURRENT text
+ * only, not any prior canonical version. If a pack's canonical description
+ * changes upstream, a vault that never touched it reads as "matches the OLD
+ * text, therefore edited" from the new pack's point of view, and keeps the
+ * old text too — same outcome as a genuine hand edit. That's fine:
+ * constitutions aren't security patches that must propagate; a future
+ * doctor-style scan can surface "description drifted from the current pack
+ * text" as an informational finding without this applier needing to guess
+ * intent. See CHANGELOG.
+ *
  * Errors propagate — best-effort semantics (seed-must-never-fail-a-create)
  * belong to the caller, which knows its failure policy.
  *
@@ -1051,6 +1083,7 @@ export async function applySeedPack(
   const result: ApplySeedPackResult = {
     pack: pack.name,
     tags: [],
+    preservedTagDescriptions: [],
     seededNotes: [],
     skippedNotes: [],
   };
@@ -1058,12 +1091,19 @@ export async function applySeedPack(
   // Parents first so `parent_names` reads naturally in logs (the store accepts
   // forward references, but the order matches the conceptual model).
   for (const decl of pack.tags) {
+    const existing = await store.getTagRecord(decl.name);
+    const priorDescription = existing?.description ?? null;
+    const isUserEdited = priorDescription != null && priorDescription !== decl.description;
+
     await store.upsertTagRecord(decl.name, {
-      description: decl.description,
+      // Omitted (not `undefined`-valued) when preserving — `upsertTagRecord`
+      // treats an absent `description` key as "keep the current value".
+      ...(isUserEdited ? {} : { description: decl.description }),
       ...(decl.parent_names ? { parent_names: decl.parent_names } : {}),
       ...(decl.fields ? { fields: decl.fields } : {}),
     });
     result.tags.push(decl.name);
+    if (isUserEdited) result.preservedTagDescriptions.push(decl.name);
   }
 
   for (const note of pack.notes) {

package/package.json

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

package/src/add-pack.test.ts

@@ -140,3 +140,35 @@ describe("add-pack surface-starter", () => {
     expect(stdout).toContain("~ tag   capture (upserted)");
   });
 });
+
+describe("add-pack — tag description preservation on re-apply (Aaron-ratified 2026-07-17)", () => {
+  test("a hand-edited description survives a re-apply and is reported 'kept', not 'upserted'", () => {
+    expect(runCli(["create", "packed", "--json"], { PARACHUTE_HOME: home }).exitCode).toBe(0);
+
+    // Simulate an operator/AI hand-editing the capture tag's constitution.
+    const dbPath = join(home, "vault", "data", "packed", "vault.db");
+    const editedDescription = "Our house rules for capture — not the default text.";
+    const writeDb = new Database(dbPath);
+    writeDb.query("UPDATE tags SET description = ? WHERE name = ?").run(
+      editedDescription,
+      "capture",
+    );
+    writeDb.close();
+
+    const { exitCode, stdout } = runCli(
+      ["add-pack", "welcome", "--vault", "packed"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("~ tag   capture (kept user description)");
+    // guide wasn't edited, so it still reports the old vocabulary.
+    expect(stdout).toContain("~ tag   guide (upserted)");
+
+    const readDb = new Database(dbPath, { readonly: true });
+    const row = readDb
+      .query("SELECT description FROM tags WHERE name = ?")
+      .get("capture") as { description: string };
+    readDb.close();
+    expect(row.description).toBe(editedDescription);
+  });
+});

package/src/cli.ts

@@ -4842,7 +4842,11 @@ async function cmdAddPack(args: string[]) {
       console.log(`  = note  ${path} (already exists — left untouched)`);
     }
     for (const tag of result.tags) {
-      console.log(`  ~ tag   ${tag} (upserted)`);
+      if (result.preservedTagDescriptions.includes(tag)) {
+        console.log(`  ~ tag   ${tag} (kept user description)`);
+      } else {
+        console.log(`  ~ tag   ${tag} (upserted)`);
+      }
     }
     if (result.seededNotes.length === 0 && result.tags.length === 0) {
       console.log("  Nothing to add — everything was already in place.");

package/src/onboarding-seed.test.ts

@@ -23,14 +23,17 @@ import { BunStore } from "./vault-store.ts";
 import { seedOnboardingNotes } from "./onboarding-seed.ts";
 import {
   applySeedPack,
+  ARCHIVED_TAG,
   CAPTURE_ANYTHING_PATH,
   CONNECT_AI_PATH,
   GETTING_STARTED_PATH,
   NOTES_REQUIRED_TAGS,
+  STARTER_ONTOLOGY_PACK,
   SURFACE_STARTER_PACK,
   SURFACE_STARTER_PATH,
   TAGS_GRAPH_PATH,
   WELCOME_PATH,
+  welcomePack,
   YOURS_TO_KEEP_PATH,
 } from "../core/src/seed-packs.ts";
 import {
@@ -290,6 +293,67 @@ describe("applySeedPack — surface-starter via add-pack", () => {
   });
 });
 
+describe("applySeedPack — tag description preservation on re-apply (Aaron-ratified 2026-07-17)", () => {
+  test("fresh apply: a brand-new tag gets the pack's description, reported as touched not preserved", async () => {
+    const result = await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect(result.tags).toContain(ARCHIVED_TAG.name);
+    expect(result.preservedTagDescriptions).toEqual([]);
+
+    const record = await store.getTagRecord(ARCHIVED_TAG.name);
+    expect(record!.description).toBe(ARCHIVED_TAG.description);
+  });
+
+  test("re-apply unmodified: description is still the pack's text — upserted, not preserved", async () => {
+    await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    const rerun = await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect(rerun.preservedTagDescriptions).toEqual([]);
+
+    const record = await store.getTagRecord(ARCHIVED_TAG.name);
+    expect(record!.description).toBe(ARCHIVED_TAG.description);
+  });
+
+  test("re-apply after a user edit: the hand-tuned description survives and is reported preserved", async () => {
+    await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    const edited = "My own house rules for archiving — nothing like the default.";
+    await store.upsertTagRecord(ARCHIVED_TAG.name, { description: edited });
+
+    const rerun = await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect(rerun.preservedTagDescriptions).toContain(ARCHIVED_TAG.name);
+    // Still listed in `tags` — the tag itself was touched (fields/parent_names
+    // upsert unconditionally); only the description write was skipped.
+    expect(rerun.tags).toContain(ARCHIVED_TAG.name);
+
+    const record = await store.getTagRecord(ARCHIVED_TAG.name);
+    expect(record!.description).toBe(edited);
+  });
+
+  test("capture byte-identity anchor (NOTES_REQUIRED_TAGS) holds under either apply order", async () => {
+    // welcome, then starter-ontology.
+    await applySeedPack(store, welcomePack());
+    expect((await store.getTagRecord("capture"))!.description).toBe(
+      NOTES_REQUIRED_TAGS[0]!.description,
+    );
+    const afterOntology = await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect(afterOntology.preservedTagDescriptions).not.toContain("capture");
+    expect((await store.getTagRecord("capture"))!.description).toBe(
+      NOTES_REQUIRED_TAGS[0]!.description,
+    );
+  });
+
+  test("capture byte-identity anchor holds in the reverse order too", async () => {
+    // starter-ontology, then welcome.
+    await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect((await store.getTagRecord("capture"))!.description).toBe(
+      NOTES_REQUIRED_TAGS[0]!.description,
+    );
+    const afterWelcome = await applySeedPack(store, welcomePack());
+    expect(afterWelcome.preservedTagDescriptions).not.toContain("capture");
+    expect((await store.getTagRecord("capture"))!.description).toBe(
+      NOTES_REQUIRED_TAGS[0]!.description,
+    );
+  });
+});
+
 describe("vault-info / projection pointer (A2)", () => {
   test("projection carries getting_started when the note exists", async () => {
     // Absent before seeding → no pointer.