@cerefox/memory 1.3.0 → 1.4.0

package/dist/server-assets/_shared/partial-edits/index.ts

@@ -62,25 +62,44 @@ export type EditOperation =
       anchor_heading: string;
       scope?: "body_only" | "heading_and_body";
       section_part?: SectionPart;
+    }
+  | {
+      op: "rename_section";
+      anchor_heading: string;
+      new_heading: string;
     };
 
 /** Echo of one applied operation, for audit labels and response text. */
 export interface AppliedOperation {
-  op: "insert" | "replace_section" | "delete_section";
+  op: "insert" | "replace_section" | "delete_section" | "rename_section";
   /** Resolved anchor path (or "(document)" for end_of_document). */
   path: string;
   /** Human summary: position / scope / section_part actually used. */
   detail: string;
+  /**
+   * For destructive ops: did the targeted section run to the END of the
+   * document it was applied to? (#196 — the last section owns anything
+   * appended after it, which is the loss that surprises people.)
+   *
+   * Decided HERE, at resolution time, rather than by re-parsing the pre-batch
+   * document later. In a batch, each operation resolves against the content
+   * left by the previous one, so a `rename_section` earlier in the same call
+   * means a later op's `path` names a heading the pre-batch outline has never
+   * heard of — and a path lookup against that outline silently finds nothing.
+   * That is precisely the batch shape `rename_section` was added to enable.
+   */
+  reachedEnd?: boolean;
 }
 
 /** Anchor matched nothing. The write must never fall back to appending. */
 export class AnchorNotFoundError extends Error {
-  constructor(anchor: string, outline: OutlineNode[]) {
+  /** `reads` — see AmbiguousPositionError: a read never attempted a write. */
+  constructor(anchor: string, outline: OutlineNode[], reads = false) {
     const known = outline.length
       ? ` Known headings:\n${outline.map((n) => `  ${n.path}`).join("\n")}`
       : " The document has no headings.";
     super(
-      `Anchor not found: "${anchor}". No write was performed.${known}\n` +
+      `Anchor not found: "${anchor}".${reads ? "" : " No write was performed."}${known}\n` +
         `Anchors match a heading line exactly ("## Title") or a parent path ` +
         `("## Parent > ### Child").`,
     );
@@ -91,10 +110,11 @@ export class AnchorNotFoundError extends Error {
 /** Anchor matched more than one section. Candidates resolve the retry. */
 export class AmbiguousAnchorError extends Error {
   readonly candidates: string[];
-  constructor(anchor: string, candidates: string[]) {
+  /** `reads` — see AmbiguousPositionError: a read never attempted a write. */
+  constructor(anchor: string, candidates: string[], reads = false) {
     super(
       `Ambiguous anchor: "${anchor}" matches ${candidates.length} sections. ` +
-        `No write was performed. Disambiguate by passing one of these paths as anchor_heading:\n` +
+        `${reads ? "" : "No write was performed. "}Disambiguate by passing one of these paths as anchor_heading:\n` +
         candidates.map((c) => `  ${c}`).join("\n"),
     );
     this.name = "AmbiguousAnchorError";
@@ -108,7 +128,13 @@ export class AmbiguousAnchorError extends Error {
  */
 export class AmbiguousPositionError extends Error {
   readonly candidates: { section_part: SectionPart; description: string }[];
-  constructor(node: OutlineNode, firstChildHeading: string, opName: string) {
+  /**
+   * `reads` marks a caller that only inspects content (#198's section read).
+   * The reassurance "No write was performed" is meant to stop an agent
+   * retrying a half-applied batch — on a read it is noise at best, and at
+   * worst it implies a write was attempted when none ever could be.
+   */
+  constructor(node: OutlineNode, firstChildHeading: string, opName: string, reads = false) {
     const candidates = [
       {
         section_part: "own_body" as const,
@@ -126,7 +152,7 @@ export class AmbiguousPositionError extends Error {
     super(
       `Ambiguous position: "${node.path}" has child sections, so "the end of ` +
         `the section" could mean two different places and ${opName} will not guess. ` +
-        `No write was performed. Pass section_part to choose:\n` +
+        `${reads ? "" : "No write was performed. "}Pass section_part to choose:\n` +
         candidates.map((c) => `  section_part: "${c.section_part}" — ${c.description}`).join("\n"),
     );
     this.name = "AmbiguousPositionError";
@@ -134,6 +160,30 @@ export class AmbiguousPositionError extends Error {
   }
 }
 
+/**
+ * A rename asked to change the heading's LEVEL, not just its text.
+ *
+ * `## Q3 plan` → `### Q3 plan` re-parents everything under it: the section
+ * stops being a sibling of its neighbours and becomes a child of whichever
+ * section precedes it. That is a restructure with a different blast radius
+ * from a rename, and doing it silently under the name "rename" is exactly the
+ * kind of surprise this contract refuses (#197).
+ */
+export class HeadingLevelChangeError extends Error {
+  constructor(fromHeading: string, toHeading: string) {
+    const from = (fromHeading.match(/^#+/) ?? [""])[0].length;
+    const to = (toHeading.match(/^#+/) ?? [""])[0].length;
+    super(
+      `rename_section changes heading TEXT, not depth: "${fromHeading}" is level ` +
+        `${from} and "${toHeading}" is level ${to}. No write was performed. ` +
+        `Changing the level would re-parent every section nested under it. ` +
+        `Pass a level-${from} heading (${"#".repeat(from)} ...), or restructure ` +
+        `explicitly with delete_section + insert if that is what you meant.`,
+    );
+    this.name = "HeadingLevelChangeError";
+  }
+}
+
 /** Structural validation failure of an operations array (before any parsing). */
 export class InvalidOperationError extends Error {
   constructor(index: number, message: string) {
@@ -240,7 +290,11 @@ function canonicalHeading(text: string): string {
   return m ? `${m[1]} ${m[2].trim()}`.trim() : text.trim();
 }
 
-export function resolveAnchor(outline: OutlineNode[], anchorHeading: string): OutlineNode {
+export function resolveAnchor(
+  outline: OutlineNode[],
+  anchorHeading: string,
+  reads = false,
+): OutlineNode {
   const anchor = canonicalHeading(anchorHeading);
 
   // Try the LITERAL heading first, always — including when the anchor contains
@@ -253,7 +307,7 @@ export function resolveAnchor(outline: OutlineNode[], anchorHeading: string): Ou
   const byHeading = outline.filter((n) => n.heading === anchor);
   if (byHeading.length === 1) return byHeading[0];
   if (byHeading.length > 1) {
-    throw new AmbiguousAnchorError(anchor, byHeading.map((n) => n.path));
+    throw new AmbiguousAnchorError(anchor, byHeading.map((n) => n.path), reads);
   }
 
   // No heading matched literally: interpret it as a parent path.
@@ -262,11 +316,62 @@ export function resolveAnchor(outline: OutlineNode[], anchorHeading: string): Ou
     const byPath = outline.filter((n) => n.path === normalizedPath);
     if (byPath.length === 1) return byPath[0];
     if (byPath.length > 1) {
-      throw new AmbiguousAnchorError(anchor, byPath.map((n) => n.path));
+      throw new AmbiguousAnchorError(anchor, byPath.map((n) => n.path), reads);
     }
   }
 
-  throw new AnchorNotFoundError(anchor, outline);
+  throw new AnchorNotFoundError(anchor, outline, reads);
+}
+
+/**
+ * The text a `replace_section` would overwrite — resolved through the SAME
+ * functions the write uses (#198).
+ *
+ * v1.3.0 shipped `replace_section` with no way to see what it was about to
+ * destroy: outline mode reports a section's *size*, never its *text*, so the
+ * only safe preparation was a full `get_document` — the cost partial edits
+ * exist to remove. `cerefox_insert` is guarded structurally (it cannot remove
+ * anything); the destructive operation was guarded only by
+ * `expected_content_hash`, which protects against a *concurrent* writer, not
+ * against a writer who does not know what it is deleting.
+ *
+ * The binding requirement is that `text` is EXACTLY the extent
+ * `replace_section` targets under the same `section_part`. If a read could
+ * differ from the write it feeds, the feature would be worse than its absence:
+ * absence at least announces itself. That is why this shares `resolveAnchor`
+ * and `resolveSectionEnd` rather than reproducing their rules — including the
+ * refusal on a section with children, which is the case most likely to diverge.
+ *
+ * `heading` is returned separately because it is context, not content:
+ * `replace_section` keeps the heading, so it is not part of what would be
+ * overwritten.
+ */
+export function extractSection(
+  content: string,
+  anchorHeading: string,
+  sectionPart?: SectionPart,
+): {
+  heading: string;
+  path: string;
+  level: number;
+  text: string;
+  chars: number;
+  section_part: SectionPart | null;
+} {
+  const outline = parseOutline(content);
+  const node = resolveAnchor(outline, anchorHeading, true);
+  // Same op label the write would raise under, so an ambiguity refusal reads
+  // the same whether the caller was reading or replacing.
+  const to = resolveSectionEnd(content, outline, node, sectionPart, "the section read", true);
+  const text = content.slice(node.bodyStart, to);
+  return {
+    heading: node.heading,
+    path: node.path,
+    level: node.level,
+    text,
+    chars: text.length,
+    section_part: sectionPart ?? null,
+  };
 }
 
 function firstChild(outline: OutlineNode[], node: OutlineNode): OutlineNode | null {
@@ -288,6 +393,7 @@ function resolveSectionEnd(
   node: OutlineNode,
   sectionPart: SectionPart | undefined,
   opName: string,
+  reads = false,
 ): number {
   const child = firstChild(outline, node);
   if (!child) return node.subtreeEnd; // leaf: unambiguous
@@ -315,7 +421,7 @@ function resolveSectionEnd(
   //
   // So: no exemption. `hasOwnBody` no longer gates anything, because the
   // presence of children is what makes "the end of this section" ambiguous.
-  throw new AmbiguousPositionError(node, child.heading, opName);
+  throw new AmbiguousPositionError(node, child.heading, opName, reads);
 }
 
 /**
@@ -386,6 +492,34 @@ function applyOne(
         path: node.path,
         detail:
           "replace_section body" + (operation.section_part ? ` (${operation.section_part})` : ""),
+        reachedEnd: to >= content.trimEnd().length,
+      },
+    };
+  }
+
+  if (operation.op === "rename_section") {
+    const node = resolveAnchor(outline, operation.anchor_heading);
+    const next = canonicalHeading(operation.new_heading);
+    const m = next.match(ATX_HEADING);
+    if (!m) {
+      throw new InvalidOperationError(
+        0,
+        `new_heading must be a markdown heading line like "## Title", got ${JSON.stringify(operation.new_heading)}`,
+      );
+    }
+    if (m[1].length !== node.level) throw new HeadingLevelChangeError(node.heading, next);
+
+    // Replace the heading LINE only. Not spliceBlock: that normalises
+    // surrounding blank lines, which is right for a block of body text and
+    // wrong for a single line whose neighbours are the section's own spacing.
+    const hadNewline = content[node.bodyStart - 1] === "\n";
+    const replacement = next + (hadNewline ? "\n" : "");
+    return {
+      content: content.slice(0, node.start) + replacement + content.slice(node.bodyStart),
+      applied: {
+        op: "rename_section",
+        path: node.path,
+        detail: `rename_section to ${next}`,
       },
     };
   }
@@ -402,6 +536,7 @@ function applyOne(
       path: node.path,
       detail:
         `delete_section (${scope})` + (operation.section_part ? ` (${operation.section_part})` : ""),
+      reachedEnd: to >= content.trimEnd().length,
     },
   };
 }
@@ -453,8 +588,33 @@ export function validateOperations(operations: unknown): EditOperation[] {
       if (o.scope !== undefined && o.scope !== "body_only" && o.scope !== "heading_and_body") {
         throw new InvalidOperationError(i, "scope must be body_only or heading_and_body");
       }
+    } else if (op === "rename_section") {
+      if (typeof o.anchor_heading !== "string" || o.anchor_heading.trim() === "") {
+        throw new InvalidOperationError(i, "rename_section requires anchor_heading");
+      }
+      if (typeof o.new_heading !== "string" || o.new_heading.trim() === "") {
+        throw new InvalidOperationError(i, "rename_section requires non-empty new_heading");
+      }
+      // A rename touches the heading line and nothing else, so a caller that
+      // also passed body text has misunderstood which operation they want.
+      // Silently ignoring it would lose the text without saying so.
+      if (o.text !== undefined) {
+        throw new InvalidOperationError(
+          i,
+          "rename_section changes only the heading and takes no text — use replace_section for the body, or both operations in one call",
+        );
+      }
+      if (o.section_part !== undefined) {
+        throw new InvalidOperationError(
+          i,
+          "rename_section takes no section_part: it replaces the heading line, so no extent is involved",
+        );
+      }
     } else {
-      throw new InvalidOperationError(i, "op must be insert | replace_section | delete_section");
+      throw new InvalidOperationError(
+        i,
+        "op must be insert | replace_section | delete_section | rename_section",
+      );
     }
     if (
       o.section_part !== undefined &&

package/dist/server-assets/db/migrations/0021_rename_section_audit_op.sql

@@ -0,0 +1,36 @@
+-- 0021_rename_section_audit_op.sql — audit the rename operation (iteration 35, #197).
+--
+-- `cerefox_audit_log.operation` is CHECK-constrained, so a new partial-edit
+-- operation cannot be recorded until the constraint knows about it. Migration
+-- 0019 widened it for insert / replace-section / delete-section; this adds
+-- rename-section.
+--
+-- Why the operation exists: there was no way to change a heading's own text.
+-- `replace_section` preserves the heading by design, and delete + re-insert
+-- sacrifices the section's body and position to fix the heading — an agent hit
+-- this on real work (a heading whose date had gone stale), judged that trade
+-- wrong, and left the document stale rather than risk the body. Renaming is
+-- therefore its own operation, and one that structurally cannot touch a body.
+--
+-- Schema version 0.11.0 → 0.11.1. Additive: the constraint only widens, so an
+-- older client against this database is unaffected, and this database against
+-- an older client simply never sees the new value.
+
+ALTER TABLE cerefox_audit_log
+    DROP CONSTRAINT IF EXISTS cerefox_audit_log_operation_check;
+
+ALTER TABLE cerefox_audit_log
+    ADD CONSTRAINT cerefox_audit_log_operation_check CHECK (
+        operation IN ('create', 'update-content', 'update-metadata', 'delete',
+                      'status-change', 'archive', 'unarchive', 'restore',
+                      'relation-set', 'relation-delete',
+                      'insert', 'replace-section', 'delete-section',
+                      'rename-section')
+    );
+
+DO $$
+BEGIN
+    RAISE NOTICE
+        'Migration 0021: audit log accepts rename-section (iteration 35, #197). '
+        'Schema version 0.11.1 — re-apply rpcs.sql on this deploy.';
+END $$;

package/dist/server-assets/db/rpcs.sql

@@ -2425,10 +2425,11 @@ SET search_path = public, pg_catalog
 AS $$
     -- Keep in lockstep with the `@version:` marker in schema.sql (cut_release.ts
     -- enforces it). Bump whenever schema.sql OR rpcs.sql changes.
+    -- 0.11.1 (iteration 35, #197): audit CHECK accepts 'rename-section'.
     -- 0.11.0 supersedes 0.10.6 (v1.2.1, #191): this branch carries that fix plus
     -- the partial-edit surface, and both migrations (0019, 0020) are in the
     -- sequence, so a store deploying this gets everything from both lines.
-    SELECT '0.11.0'::TEXT;
+    SELECT '0.11.1'::TEXT;
 $$;
 
 -- ── cerefox_content_format_stats ─────────────────────────────────────────────

package/dist/server-assets/db/schema.sql

@@ -5,7 +5,7 @@
 -- Requires extensions: vector (pgvector), uuid-ossp
 -- These are enabled at the top of db_deploy.py before this file is applied.
 --
--- @version: 0.11.0
+-- @version: 0.11.1
 -- The `@version` marker above is read by the schema-version-mismatch banner
 -- (see /api/v1/schema-version). Bump it whenever schema.sql OR rpcs.sql
 -- changes in a way that requires `cerefox server deploy` to be re-run —
@@ -129,7 +129,10 @@ CREATE TABLE IF NOT EXISTS cerefox_audit_log (
                       -- iteration 33: partial edits. Distinct from 'update-content'
                       -- so the trail separates "added to" from "rewrote" from
                       -- "removed" — one entry per operation in a cerefox_edit batch.
-                      'insert', 'replace-section', 'delete-section')
+                      'insert', 'replace-section', 'delete-section',
+                      -- iteration 35 (#197): renaming a heading is neither a
+                      -- rewrite nor a removal, and the trail should say so.
+                      'rename-section')
     ),
     CONSTRAINT cerefox_audit_log_author_type_check CHECK (author_type IN ('user', 'agent'))
 );

package/docs/guides/configuration.md

@@ -273,7 +273,7 @@ cerefox document get <document-id> --version-id <version-id>
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CEREFOX_BACKUP_DIR` | `~/.cerefox/backups` | Local directory where file system backups are stored. Created automatically if it doesn't exist. **Use an absolute path** — a relative value (such as the pre-v0.3.0 `./backups`) resolves against the current working directory, so snapshots scatter depending on where you run the command; `backup create` warns when it sees one. Does **not** follow `CEREFOX_CONFIG_DIR`, so a second environment must set it explicitly. |
-| `CEREFOX_ENV_LABEL` | _(unset)_ | Names a non-production environment (e.g. `staging`). Purely cosmetic and inert when unset. When set: the web UI shows a banner on every page, `doctor` shows `[LABEL]` on its title line, `backup create` puts the label in the snapshot filename and payload, and `backup restore` warns when a snapshot's environment differs from the target's. See [`staging-env.md`](staging-env.md). |
+| `CEREFOX_ENV_LABEL` | _(unset)_ | Names a non-production environment (e.g. `staging`). Purely cosmetic and inert when unset. When set: the web UI shows a banner on every page, `doctor` shows `[LABEL]` on its title line, `backup create` puts the label in the snapshot filename and payload, and `backup restore` warns when a snapshot's environment differs from the target's, and `configure-agent` registers the MCP server as `cerefox-<label>` so a labelled environment sits alongside production instead of overwriting it (v1.4.0, #168). See [`staging-env.md`](staging-env.md). |
 | `CEREFOX_VERSION_RETENTION_HOURS` | **Retired in v1.1.0 — no longer read.** | Version retention is now a property of the store: `cerefox config set version_retention_hours <hours>`, or the **Settings** page. It moved because it used to be passed per-call from each client's environment, so the surviving history depended on which client wrote last. `cerefox doctor` reports the variable if it is still set. |
 
 ---

package/docs/guides/connect-agents.md

@@ -166,7 +166,20 @@ cerefox configure-agent --tool gemini           # ~/.gemini/settings.json
 Useful flags: `--dry-run` (print the planned write without touching any file), `--json`
 (machine-readable result), `--config-path <path>` (override the target file), `--no-backup`
 (skip the `.pre-cerefox.bak` backup). The command is idempotent and backs up any existing
-config before writing. The per-client sections below document the same entries for anyone
+config before writing.
+
+The entry is registered under the server name `cerefox`. If `CEREFOX_ENV_LABEL` is
+set — as it is for a [staging environment](staging-env.md) — the name becomes
+`cerefox-<label>` instead, so a second environment sits **alongside** your production
+entry rather than replacing it, and an agent can hold both at once (v1.4.0, #168).
+The command prints the name it used.
+
+A labelled entry additionally carries `CEREFOX_CONFIG_DIR` and `CEREFOX_ENV_LABEL`
+in its `env` block. That is what makes it actually reach the environment it is named
+after: MCP clients spawn a stdio server with the **client's** environment, not the
+shell you ran `configure-agent` in, and a desktop client launched from the dock has
+no shell environment at all. A production entry carries no `env` — unchanged from
+earlier releases. The per-client sections below document the same entries for anyone
 who prefers to edit by hand or needs the remote (`Path A-Remote`) HTTP transport instead.
 
 ### Path A MCP tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Cerefox — user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",