hippo-memory 1.70.0 → 1.71.0

package/dist/core/physics.js

@@ -1,20 +1,9 @@
-/**
- * Memory-as-Physics engine for Hippo.
- *
- * Pure math module: forces, Velocity Verlet integration, physics-based scoring,
- * and cluster amplification. No I/O — all state is passed in and returned.
- *
- * Memories are particles on the unit hypersphere in embedding space (384-dim).
- * Forces act on them: query gravity (retrieval), inter-memory attraction,
- * conflict repulsion, and drag (consolidation). Nearby high-scoring memories
- * amplify each other via constructive interference.
- */
+/** Memory-as-Physics engine: pure math (forces, Velocity Verlet integration, physics-based scoring, cluster amplification), no I/O.
+ * Memories are particles on the unit hypersphere in embedding space (384-dim); query gravity, attraction, conflict repulsion and drag act on them,
+ * and nearby high-scoring memories amplify each other. */
 import { isRecallBoostAblated } from './ablation.js';
 import { FALLBACK_HALF_LIFE_DAYS } from './memory.js';
 import { comparePhysicsResultsBy } from './compare.js';
-// ---------------------------------------------------------------------------
-// Vector math (hot path — kept inline for performance)
-// ---------------------------------------------------------------------------
 export function vecDot(a, b) {
     let sum = 0;
     for (let i = 0; i < a.length; i++)
@@ -25,25 +14,25 @@ export function vecNorm(v) {
     return Math.sqrt(vecDot(v, v));
 }
 export function vecScale(v, s) {
-    const out = new Array(v.length);
+    const out = v.slice();
     for (let i = 0; i < v.length; i++)
         out[i] = v[i] * s;
     return out;
 }
 export function vecAdd(a, b) {
-    const out = new Array(a.length);
+    const out = a.slice();
     for (let i = 0; i < a.length; i++)
         out[i] = a[i] + b[i];
     return out;
 }
 export function vecSub(a, b) {
-    const out = new Array(a.length);
+    const out = a.slice();
     for (let i = 0; i < a.length; i++)
         out[i] = a[i] - b[i];
     return out;
 }
 export function vecZero(dim) {
-    return new Array(dim).fill(0);
+    return Array(dim).fill(0);
 }
 /** Normalize to unit length. Returns zero vector if magnitude < epsilon. */
 export function vecNormalize(v) {
@@ -70,9 +59,6 @@ function cosine(a, b) {
         return 0;
     return Math.min(1, Math.max(-1, dot / (na * nb)));
 }
-// ---------------------------------------------------------------------------
-// Property derivation from memory attributes
-// ---------------------------------------------------------------------------
 const CHARGE_MAP = {
     neutral: 0,
     positive: 0.3,
@@ -80,9 +66,8 @@ const CHARGE_MAP = {
     critical: -1.0,
 };
 export function computeMass(strength, retrievalCount) {
-    // EVAL-ONLY ablation (see ablation.ts): under the recall-boost flag mass ignores retrieval history, since
-    // query gravity ranks by mass and prior counts would leak strengthening into the ablated arm's
-    // physics-pool rankings. Covers both the init and refresh callers in physics-state.ts.
+    // EVAL-ONLY ablation (ablation.ts): under the recall-boost flag mass ignores retrieval history, which would otherwise leak strengthening into the ablated
+    // arm's physics-pool rankings (query gravity ranks by mass). Covers both init and refresh callers in physics-state.ts.
     const effectiveCount = isRecallBoostAblated() ? 0 : retrievalCount;
     return Math.max(0.01, strength * (1 + 0.1 * Math.log2(effectiveCount + 1)));
 }
@@ -92,23 +77,12 @@ export function computeCharge(valence) {
 export function computeTemperature(ageDays, temperatureDecay) {
     return 1 / (ageDays * temperatureDecay + 1);
 }
-// ---------------------------------------------------------------------------
-// Force computations
-// ---------------------------------------------------------------------------
-/**
- * Query gravity (retrieval-time, virtual — does not update position).
- * Returns scalar force magnitude for ranking.
- *
- * F_query(i) = G_Q * mass(i) * max(0, cosine(pos_i, query))^2
- */
+/** Query gravity (retrieval-time, virtual: does not move the particle): scalar ranking magnitude F = G_Q * mass * max(0, cosine(pos, query))^2. */
 export function queryGravityMagnitude(particle, queryEmbedding, G_query) {
     const cos = cosine(particle.position, queryEmbedding);
     return G_query * particle.mass * Math.pow(Math.max(0, cos), 2);
 }
-/**
- * Momentum bonus: how aligned is the particle's velocity with the query direction?
- * Returns a value in [0, 1].
- */
+/** Momentum bonus in [0, 1]: how aligned the particle's velocity is with the query direction. */
 export function velocityAlignmentBonus(particle, queryEmbedding) {
     if (particle.velocity.length === 0 || particle.velocity.length !== queryEmbedding.length)
         return 0;
@@ -119,31 +93,25 @@ export function velocityAlignmentBonus(particle, queryEmbedding) {
     const alignment = vecDot(particle.velocity, queryEmbedding) / (velMag * qNorm);
     return Math.max(0, alignment);
 }
-/**
- * Inter-memory attraction force vector (consolidation-time).
- * Attractive force from particle j on particle i.
- *
- * F_attract(i,j) = G_M * m_i * m_j * max(0, cosine(i,j))^3 * direction(j→i in embedding space)
- *
- * Direction is computed as the component of (pos_j - pos_i) that lies tangent to the
- * unit sphere at pos_i (since we normalize positions back to the sphere after integration).
- */
-export function attractionForce(pi, pj, G_memory) {
+/** Attraction force on particle i from j (consolidation-time): G_M m_i m_j max(0, cosine)^3, directed along (pos_j - pos_i) projected tangent to the unit
+ * sphere at pos_i (positions are re-normalized to the sphere after integration). Adds into `out` (a fresh zero vector by default) using `diff` as scratch. */
+export function attractionForce(pi, pj, G_memory, out = vecZero(pi.position.length), diff = vecZero(pi.position.length)) {
     const cos = cosine(pi.position, pj.position);
     if (cos <= 0)
-        return vecZero(pi.position.length);
+        return out;
     const magnitude = G_memory * pi.mass * pj.mass * Math.pow(cos, 3);
     // Direction: from i toward j (tangent projection handled by normalization after integration)
-    const direction = vecNormalize(vecSub(pj.position, pi.position));
-    return vecScale(direction, magnitude);
+    for (let k = 0; k < out.length; k++)
+        diff[k] = pj.position[k] - pi.position[k];
+    const norm = vecNorm(diff);
+    if (norm < 1e-10)
+        return out;
+    const inv = 1 / norm;
+    for (let k = 0; k < out.length; k++)
+        out[k] += diff[k] * inv * magnitude;
+    return out;
 }
-/**
- * Conflict repulsion force vector (consolidation-time).
- * Repulsive force pushing i away from j.
- *
- * F_repel(i,j) = K_R * m_i * m_j / max(0.01, cosine_distance(i,j))^2
- * where cosine_distance = 1 - cosine_similarity
- */
+/** Conflict repulsion on i away from j (consolidation-time): K_R * m_i * m_j / max(0.01, cosine_distance)^2, where cosine_distance = 1 - cosine_similarity. */
 export function repulsionForce(pi, pj, K_repulsion) {
     const cos = cosine(pi.position, pj.position);
     const dist = Math.max(0.01, 1 - cos);
@@ -152,46 +120,44 @@ export function repulsionForce(pi, pj, K_repulsion) {
     const direction = vecNormalize(vecSub(pi.position, pj.position));
     return vecScale(direction, magnitude);
 }
-/**
- * Drag force vector (consolidation-time).
- * F_drag(i) = -drag * velocity(i) / max(1, effective_half_life(i))
- *
- * effectiveHalfLife should be passed in from the memory's current half_life_days.
- */
+/** Drag force (consolidation-time): -drag * velocity / max(1, effectiveHalfLife), with effectiveHalfLife from the memory's current half_life_days. */
 export function dragForce(particle, drag, effectiveHalfLife) {
     const damping = drag / Math.max(1, effectiveHalfLife);
     return vecScale(particle.velocity, -damping);
 }
-/**
- * Compute net force on particle i from all other particles + drag.
- */
-function computeNetForce(i, particles, ctx) {
+function addInto(net, force) {
+    for (let k = 0; k < net.length; k++)
+        net[k] += force[k];
+}
+/** The net force on particle i, accumulated into one new array; `diff` is the caller's scratch for pair directions. */
+function computeNetForce(i, particles, ctx, diff) {
     const pi = particles[i];
     const dim = pi.position.length;
-    let net = vecZero(dim);
+    const net = vecZero(dim);
     const conflicts = ctx.conflictPairs.get(pi.memoryId);
     for (let j = 0; j < particles.length; j++) {
         if (i === j)
             continue;
         const pj = particles[j];
         // Attraction (all pairs)
-        const fa = attractionForce(pi, pj, ctx.config.G_memory);
-        net = vecAdd(net, fa);
+        attractionForce(pi, pj, ctx.config.G_memory, net, diff);
         // Repulsion (conflict pairs only)
-        if (conflicts?.has(pj.memoryId)) {
-            const fr = repulsionForce(pi, pj, ctx.config.K_repulsion);
-            net = vecAdd(net, fr);
-        }
+        if (conflicts?.has(pj.memoryId))
+            addInto(net, repulsionForce(pi, pj, ctx.config.K_repulsion));
     }
     // Drag
-    const fd = dragForce(pi, ctx.config.drag, ctx.halfLives.get(pi.memoryId) ?? FALLBACK_HALF_LIFE_DAYS);
-    net = vecAdd(net, fd);
+    addInto(net, dragForce(pi, ctx.config.drag, ctx.halfLives.get(pi.memoryId) ?? FALLBACK_HALF_LIFE_DAYS));
     return net;
 }
-/**
- * Run one Velocity Verlet integration step for all particles.
- * Mutates particles in place for performance.
- */
+/** Acceleration of particle i: its net force divided by mass, scaled in place. */
+function computeAcceleration(i, particles, ctx, diff) {
+    const accel = computeNetForce(i, particles, ctx, diff);
+    const inv = 1 / Math.max(0.01, particles[i].mass);
+    for (let k = 0; k < accel.length; k++)
+        accel[k] *= inv;
+    return accel;
+}
+/** One Velocity Verlet step for all particles; mutates in place for performance. */
 function verletStep(particles, accelerations, ctx) {
     const dt = ctx.config.dt;
     const maxVel = ctx.config.max_velocity;
@@ -203,11 +169,10 @@ function verletStep(particles, accelerations, ctx) {
         p.position = vecAdd(vecAdd(p.position, velDt), accelDt2);
     }
     // Compute new accelerations
+    const diff = vecZero(particles[0].position.length);
     const newAccelerations = [];
-    for (let i = 0; i < particles.length; i++) {
-        const force = computeNetForce(i, particles, ctx);
-        newAccelerations.push(vecScale(force, 1 / Math.max(0.01, particles[i].mass)));
-    }
+    for (let i = 0; i < particles.length; i++)
+        newAccelerations.push(computeAcceleration(i, particles, ctx, diff));
     // Velocity update: vel += 0.5*(accel_old + accel_new)*dt
     for (let i = 0; i < particles.length; i++) {
         const p = particles[i];
@@ -222,10 +187,7 @@ function verletStep(particles, accelerations, ctx) {
         accelerations[i] = newAccelerations[i];
     }
 }
-/**
- * Run the full physics simulation for one sleep cycle.
- * Mutates particles in place. Returns simulation statistics.
- */
+/** Full physics simulation for one sleep cycle; mutates particles in place and returns simulation statistics. */
 export function simulate(particles, ctx) {
     if (particles.length === 0) {
         return {
@@ -237,10 +199,8 @@ export function simulate(particles, ctx) {
         };
     }
     // Initial accelerations
-    const accelerations = particles.map((_, i) => {
-        const force = computeNetForce(i, particles, ctx);
-        return vecScale(force, 1 / Math.max(0.01, particles[i].mass));
-    });
+    const diff = vecZero(particles[0].position.length);
+    const accelerations = particles.map((_, i) => computeAcceleration(i, particles, ctx, diff));
     // Run substeps
     for (let step = 0; step < ctx.config.substeps; step++) {
         verletStep(particles, accelerations, ctx);
@@ -268,9 +228,6 @@ export function simulate(particles, ctx) {
         substepsRun: ctx.config.substeps,
     };
 }
-// ---------------------------------------------------------------------------
-// System energy (health monitoring)
-// ---------------------------------------------------------------------------
 export function computeSystemEnergy(particles, G_memory) {
     let kinetic = 0;
     let potential = 0;
@@ -286,18 +243,10 @@ export function computeSystemEnergy(particles, G_memory) {
     }
     return { kinetic, potential, total: kinetic + potential };
 }
-// ---------------------------------------------------------------------------
-// Physics-based scoring (retrieval-time)
-// ---------------------------------------------------------------------------
-/**
- * Score all particles against a query embedding using physics-based ranking.
- * Does NOT modify particle positions (virtual force computation).
- */
+/** Scores all particles against a query embedding; virtual force computation, so it does NOT modify particle positions. */
 export function physicsScore(particles, queryEmbedding, config, 
-/** Cross-ingest-stable tie key per memoryId (typically the memory's
- *  content, supplied by the caller which has entries in scope). Without
- *  it ties fall to memoryId -- per-instance only, which lets the
- *  cluster_top_k amplification set vary across fresh ingests. */
+/** Cross-ingest-stable tie key per memoryId (typically the memory content, from a caller with entries in scope); without it ties fall to memoryId,
+ *  which is per-instance only and lets the cluster_top_k amplification set vary across fresh ingests. */
 tieKeyOf) {
     if (particles.length === 0 || queryEmbedding.length === 0)
         return [];
@@ -312,10 +261,8 @@ tieKeyOf) {
             finalScore: gravity + momentum,
         };
     });
-    // Sort by base score for top-K selection: score desc -> tie key asc.
-    // The tie order here picks the cluster_top_k amplification SET (which
-    // mutates scores), so it must be cross-ingest-stable when the caller
-    // supplies a content tie key. See compare.ts comparePhysicsResultsBy.
+    // Base-score order picks the cluster_top_k amplification SET (which mutates scores), so ties must be cross-ingest-stable
+    // when the caller supplies a content tie key (see comparePhysicsResultsBy in compare.ts).
     const tie = tieKeyOf ? (r) => tieKeyOf(r.memoryId) : undefined;
     results.sort(comparePhysicsResultsBy((r) => r.baseScore, tie));
     // Pass 2: cluster amplification on top K
@@ -324,10 +271,7 @@ tieKeyOf) {
     results.sort(comparePhysicsResultsBy((r) => r.finalScore, tie));
     return results;
 }
-/**
- * Cluster amplification: nearby high-scoring memories reinforce each other.
- * Mutates results in place.
- */
+/** Cluster amplification: nearby high-scoring memories reinforce each other; mutates results in place. */
 function applyClusterAmplification(results, particles, config) {
     const topK = Math.min(config.cluster_top_k, results.length);
     if (topK < 2)
@@ -358,14 +302,7 @@ function applyClusterAmplification(results, particles, config) {
         top[i].finalScore = top[i].baseScore * amplification;
     }
 }
-// ---------------------------------------------------------------------------
-// Outcome feedback (micro-nudge)
-// ---------------------------------------------------------------------------
-/**
- * Nudge a particle's position toward (good outcome) or away from (bad outcome)
- * the query embedding. Respects temperature: new memories respond more.
- * Mutates particle in place.
- */
+/** Nudges a particle toward (good outcome) or away from (bad outcome) the query embedding; new memories respond more (temperature). Mutates in place. */
 export function applyOutcomeFeedback(particle, queryEmbedding, good, feedbackAlpha) {
     if (particle.position.length === 0 || particle.position.length !== queryEmbedding.length)
         return;

package/dist/core/project-identity.d.ts

@@ -1,22 +1,5 @@
-/**
- * Project identity resolution for memory scope isolation.
- *
- * Resolution rules:
- * - The nearest ancestor of cwd (including cwd itself) containing a `.hippo`
- *   directory is the project root; if none exists, the nearest ancestor
- *   containing `.git` (directory or worktree file).
- * - The user home directory is NEVER a project, even though it contains the
- *   global store at `~/.hippo`. Reaching home or the temp root (inside home on Windows) ends the walk.
- * - A directory with no marker anywhere up the walk is NOT a project: it
- *   resolves to the user-global identity (empty name), so memories written
- *   there stay injectable everywhere (matches pre-isolation behavior).
- * - A project's name is its id: `.hippo-project.json` at the root, else the
- *   checkout's normalised `origin` remote, else the folder rule (legacyName),
- *   so two repos in folders of one name stay apart.
- *
- * NOTE: this module must stay free of imports from shared.ts / store.ts /
- * api.ts so any of them can import it without creating a cycle.
- */
+/** Project = nearest ancestor of cwd with `.hippo` (else `.git`); home and the temp root never are, and no marker means user-global (empty name).
+ * Name: `.hippo-project.json`, else the normalised `origin`, else the folder name. Must not import shared.ts / store.ts / api/index.ts (cycle). */
 /** The project a working directory belongs to. */
 export interface ProjectIdentity {
     /** Realpath-resolved root directory of the project (the start dir when not in a project). */
@@ -25,26 +8,21 @@ export interface ProjectIdentity {
     name: string;
     /** The folder rule rows written before ids carry: the root's lowercased basename, or its repo's for a linked worktree with no `.hippo`. */
     legacyName: string;
-    /** Every other name this root resolves to (the project file id, the origin remote even with the rule off, legacyName), so rows written under an earlier id stay readable. */
+    /** Every other name this root resolves to (the project file id, the origin remote even
+     * with the rule off, legacyName), so rows written under an earlier id stay readable. */
     aliases?: readonly string[];
     /** True when the directory resolves to the user home working set. */
     isHome: boolean;
 }
-/**
- * Options for resolveProjectIdentity. Both fields are test seams; results are
- * not cached when either is set. stopDir bounds the upward walk so tests in a
- * temp sandbox never escape it and hit the host machine's real markers.
- */
+/** Options for resolveProjectIdentity. Both fields are test seams and disable caching;
+ * stopDir bounds the upward walk so tests in a temp sandbox never reach the host's real markers. */
 export interface ResolveProjectIdentityOpts {
     homeDir?: string;
     stopDir?: string;
 }
 /** Clear the per-process identity cache and the remote switch it read (test seam). */
 export declare function clearProjectIdentityCache(): void;
-/**
- * Resolve the project identity for a working directory.
- * Defaults to process.cwd(). Results are cached per resolved input path.
- */
+/** Resolves the project identity for a working directory (default process.cwd()); results are cached per resolved input path. */
 export declare function resolveProjectIdentity(cwd?: string, opts?: ResolveProjectIdentityOpts): ProjectIdentity;
 /** Nearest ancestor `.hippo` below home and the temp root (never projects; on Windows the temp root sits inside home).
  *  Everything is realpath'd so a symlinked temp root or cwd still matches its bound. */
@@ -57,44 +35,25 @@ export declare function projectId(project: ProjectRef): string;
 export declare function projectNames(project: ProjectRef): readonly string[];
 export declare const MAX_PROJECT_ALIASES = 10;
 export declare const MCP_PROJECT_SCOPED_HEADER = "X-Hippo-Project-Scoped";
-/** Refuses a caller's project that is blank (it would stamp user-global), past the caps, or unlike the resolver's ids: rows match verbatim, so a rewrite would split a project. Inner spaces pass, since a checkout with no remote is named by its folder. */
+/** Refuses a caller's project that is blank (it would stamp user-global), past the caps, or unlike the resolver's ids: rows match
+ * verbatim, so a rewrite would split a project. Inner spaces pass, since a checkout with no remote is named by its folder. */
 export declare function assertCallerProject(project: {
     readonly name: string;
     readonly aliases?: readonly string[];
 }): void;
 /** `origin_project IN (?, ...)` with one placeholder per name; an empty list matches nothing. */
 export declare function originInSql(names: readonly string[], column?: string): string;
-/**
- * v39 memory scope isolation: classify a memory's origin_project against the
- * active project. An empty current id means the session is not in a project
- * (home dir or markerless cwd) - everything is in scope there, matching
- * pre-isolation behavior. NULL/undefined origin means no known project (a legacy
- * row, or a shared-store write that named none) and is treated as cross-project
- * (deny by default) - the safe direction for a security partition.
- */
+/** Classifies a memory's origin_project against the active project. An empty current id (home or markerless cwd) puts everything in scope;
+ * NULL/undefined origin (legacy row, or a shared-store write naming none) counts as cross-project: deny by default for a security partition. */
 export declare function classifyOriginProject(origin: string | null | undefined, current: ProjectRef): 'project' | 'user-global' | 'cross-project';
-/**
- * The global Hippo store directory, resolved the same way shared.ts does:
- * $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo. Lives here (leaf module) so
- * db.ts migrations can use it without importing shared.ts (store.ts cycle);
- * shared.getGlobalRoot delegates to this.
- */
+/** The global Hippo store directory ($HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo); getGlobalRoot (sharing/global-store.ts) returns it.
+ * Leaf module so store migrations can use it without importing sharing/ (store cycle). */
 export declare function resolveGlobalRootDir(): string;
-/**
- * True when `p` IS the global store root. Used by the v39 migration so a
- * global store whose parent chain happens to contain `.git`/`.hippo`
- * (git-managed HIPPO_HOME, dotfiles setups) still backfills as user-global
- * ('') instead of being stamped with the surrounding repo's name - which
- * would hide the user's entire global corpus from every project.
- */
+/** True when `p` IS the global store root, so a global store whose parent chain contains `.git`/`.hippo` (git-managed HIPPO_HOME) still backfills as
+ * user-global ('') instead of being stamped with the surrounding repo's name, which would hide the global corpus from every project. */
 export declare function isGlobalStoreRoot(p: string): boolean;
-/**
- * Parse a memory's origin from its provenance `source` string, mirroring the
- * v39 migration's evidence rules: `shared:<project>:<ts>` and
- * `promoted:<localRoot>` identify the owning project; the user home dir's
- * basename maps to '' (user-global). Returns null when the source carries no
- * origin evidence. Pure string logic - recorded paths may no longer exist.
- */
+/** Parses a memory's origin from its provenance `source`: `shared:<project>:<ts>` and `promoted:<localRoot>` name the owning project; the home dir basename
+ * maps to '' (user-global). Returns null without origin evidence. Pure string logic, since recorded paths may no longer exist. */
 export declare function originFromSource(source: string | null | undefined, homeName?: string): string | null;
 /** The origin to stamp on a memory written from cwd: its project name, or '' (user-global, injectable everywhere) outside a project.
  *  NULL means no known project: a legacy row with no evidence, or a write to a shared store that named none; ambient context treats it as deny. */

package/dist/core/project-identity.js

@@ -23,7 +23,8 @@ function remoteRuleOn() {
         remoteSwitch = { globalRoot, on: loadConfig(globalRoot).projectIdentity.remote };
     return remoteSwitch.on;
 }
-/** The id a root names itself by plus every rung that resolves; only the root's own `.git` is read, so a store nested in another checkout keeps its folder name. */
+/** The id a root names itself by plus every rung that resolves; only the root's own
+ * `.git` is read, so a store nested in another checkout keeps its folder name. */
 function namesAt(root, legacyName) {
     const fileId = projectFileId(root);
     const remoteId = originRemoteId(root);
@@ -48,9 +49,8 @@ function isUnder(child, parent) {
     }
     return false;
 }
-/** A `.hippo` marker must be a DIRECTORY (a store) - a stray file named
- *  `.hippo` must not turn its parent into a project. `.git` stays existsSync
- *  because worktrees legitimately use a `.git` FILE. */
+/** A `.hippo` marker must be a DIRECTORY (a store), so a stray file named `.hippo` cannot make its parent a project;
+ *  `.git` stays existsSync because worktrees use a `.git` FILE. */
 function isDirectoryAt(p) {
     try {
         return fs.statSync(p).isDirectory();
@@ -60,10 +60,7 @@ function isDirectoryAt(p) {
         return false;
     }
 }
-/**
- * Resolve the project identity for a working directory.
- * Defaults to process.cwd(). Results are cached per resolved input path.
- */
+/** Resolves the project identity for a working directory (default process.cwd()); results are cached per resolved input path. */
 export function resolveProjectIdentity(cwd, opts) {
     const startInput = path.resolve(cwd ?? process.cwd());
     const cacheable = !opts?.homeDir && !opts?.stopDir;
@@ -96,7 +93,8 @@ export function resolveProjectIdentity(cwd, opts) {
         identityCache.set(startInput, identity);
     return identity;
 }
-/** The repo name a linked worktree shares with its main checkout (`repo.git` or `repo/.bare` for a bare repo), so one repo is one project; null for any other checkout. */
+/** The repo name a linked worktree shares with its main checkout (`repo.git` or
+ * `repo/.bare` for a bare repo), so one repo is one project; null for any other checkout. */
 function linkedWorktreeRepoName(gitRoot, home) {
     const marker = path.join(gitRoot, '.git');
     if (!fs.existsSync(marker) || isDirectoryAt(marker))
@@ -172,7 +170,8 @@ export function projectNames(project) {
 // Each project name is matched against every candidate row, so the caller's list stays short.
 export const MAX_PROJECT_ALIASES = 10;
 export const MCP_PROJECT_SCOPED_HEADER = 'X-Hippo-Project-Scoped';
-/** Refuses a caller's project that is blank (it would stamp user-global), past the caps, or unlike the resolver's ids: rows match verbatim, so a rewrite would split a project. Inner spaces pass, since a checkout with no remote is named by its folder. */
+/** Refuses a caller's project that is blank (it would stamp user-global), past the caps, or unlike the resolver's ids: rows match
+ * verbatim, so a rewrite would split a project. Inner spaces pass, since a checkout with no remote is named by its folder. */
 export function assertCallerProject(project) {
     const { name, aliases = [] } = project;
     if (name.trim() === '')
@@ -190,14 +189,8 @@ export function assertCallerProject(project) {
 export function originInSql(names, column = 'origin_project') {
     return names.length === 0 ? '0' : `${column} IN (${names.map(() => '?').join(', ')})`;
 }
-/**
- * v39 memory scope isolation: classify a memory's origin_project against the
- * active project. An empty current id means the session is not in a project
- * (home dir or markerless cwd) - everything is in scope there, matching
- * pre-isolation behavior. NULL/undefined origin means no known project (a legacy
- * row, or a shared-store write that named none) and is treated as cross-project
- * (deny by default) - the safe direction for a security partition.
- */
+/** Classifies a memory's origin_project against the active project. An empty current id (home or markerless cwd) puts everything in scope;
+ * NULL/undefined origin (legacy row, or a shared-store write naming none) counts as cross-project: deny by default for a security partition. */
 export function classifyOriginProject(origin, current) {
     if (projectId(current) === '')
         return 'project';
@@ -207,12 +200,8 @@ export function classifyOriginProject(origin, current) {
         return 'user-global';
     return projectNames(current).includes(origin) ? 'project' : 'cross-project';
 }
-/**
- * The global Hippo store directory, resolved the same way shared.ts does:
- * $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo. Lives here (leaf module) so
- * db.ts migrations can use it without importing shared.ts (store.ts cycle);
- * shared.getGlobalRoot delegates to this.
- */
+/** The global Hippo store directory ($HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo); getGlobalRoot (sharing/global-store.ts) returns it.
+ * Leaf module so store migrations can use it without importing sharing/ (store cycle). */
 export function resolveGlobalRootDir() {
     const hippoHome = envHippoHome();
     if (hippoHome)
@@ -222,23 +211,13 @@ export function resolveGlobalRootDir() {
         return path.join(xdgData, 'hippo');
     return path.join(os.homedir(), '.hippo');
 }
-/**
- * True when `p` IS the global store root. Used by the v39 migration so a
- * global store whose parent chain happens to contain `.git`/`.hippo`
- * (git-managed HIPPO_HOME, dotfiles setups) still backfills as user-global
- * ('') instead of being stamped with the surrounding repo's name - which
- * would hide the user's entire global corpus from every project.
- */
+/** True when `p` IS the global store root, so a global store whose parent chain contains `.git`/`.hippo` (git-managed HIPPO_HOME) still backfills as
+ * user-global ('') instead of being stamped with the surrounding repo's name, which would hide the global corpus from every project. */
 export function isGlobalStoreRoot(p) {
     return samePath(realpathOrResolve(path.resolve(p)), realpathOrResolve(resolveGlobalRootDir()));
 }
-/**
- * Parse a memory's origin from its provenance `source` string, mirroring the
- * v39 migration's evidence rules: `shared:<project>:<ts>` and
- * `promoted:<localRoot>` identify the owning project; the user home dir's
- * basename maps to '' (user-global). Returns null when the source carries no
- * origin evidence. Pure string logic - recorded paths may no longer exist.
- */
+/** Parses a memory's origin from its provenance `source`: `shared:<project>:<ts>` and `promoted:<localRoot>` name the owning project; the home dir basename
+ * maps to '' (user-global). Returns null without origin evidence. Pure string logic, since recorded paths may no longer exist. */
 export function originFromSource(source, homeName) {
     if (!source)
         return null;

package/dist/core/project-remote.js

@@ -7,9 +7,10 @@ import { errorMessage, log } from '../util/log.js';
 export function gitConfigPath(gitRoot) {
     const marker = path.join(gitRoot, '.git');
     try {
-        if (fs.statSync(marker).isDirectory())
+        const pointer = gitFilePointer(marker);
+        if (pointer === null)
             return path.join(marker, 'config');
-        const gitDir = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(marker, 'utf8'))?.[1]?.trim();
+        const gitDir = /^gitdir:\s*(.+)$/m.exec(pointer)?.[1]?.trim();
         if (!gitDir)
             return null;
         const linkDir = path.resolve(gitRoot, gitDir);
@@ -23,6 +24,16 @@ export function gitConfigPath(gitRoot) {
         return null;
     }
 }
+/** The text of a `.git` file, or null when `.git` is a folder; one descriptor answers both, so the path cannot change in between. */
+function gitFilePointer(marker) {
+    const fd = fs.openSync(marker, 'r');
+    try {
+        return fs.fstatSync(fd).isDirectory() ? null : fs.readFileSync(fd, 'utf8');
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /** One config value with git's quoting: `"` toggles quoting, backslash escapes, and an unquoted `#` or `;` starts a comment. */
 function configValue(raw) {
     let out = '';

package/dist/core/raw-append-only.d.ts

@@ -0,0 +1,5 @@
+/** The refusal a delete of a raw row gets; a plain Error subclass, so it joins no HTTP status family. */
+export declare class RawAppendOnlyError extends Error {
+    constructor(cause: Error);
+}
+//# sourceMappingURL=raw-append-only.d.ts.map

package/dist/core/raw-append-only.js

@@ -0,0 +1,7 @@
+/** The refusal a delete of a raw row gets; a plain Error subclass, so it joins no HTTP status family. */
+export class RawAppendOnlyError extends Error {
+    constructor(cause) {
+        super('raw is append-only', { cause });
+    }
+}
+//# sourceMappingURL=raw-append-only.js.map

package/dist/core/salience.d.ts

@@ -1,10 +1,4 @@
-/**
- * Salience gate — decides at memory creation time whether content is worth
- * storing at full strength, should start weakened, or should be skipped.
- *
- * Inspired by the biological salience network (anterior insula + dACC):
- * not everything that enters working memory deserves long-term storage.
- */
+/** Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped. */
 import type { MemoryEntry } from './memory.js';
 export type SalienceDecision = 'store' | 'skip' | 'start_weak';
 export interface SalienceResult {

package/dist/core/salience.js

@@ -1,10 +1,4 @@
-/**
- * Salience gate — decides at memory creation time whether content is worth
- * storing at full strength, should start weakened, or should be skipped.
- *
- * Inspired by the biological salience network (anterior insula + dACC):
- * not everything that enters working memory deserves long-term storage.
- */
+/** Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped. */
 import { textOverlap } from '../util/tokenize.js';
 import { duplicateKey, heldTextKeys } from '../util/same-text.js';
 // Each store or skip reason carries a score; a novel memory adds bonuses for structure and length.

package/dist/dashboard/dashboard-actions.js

@@ -1,6 +1,7 @@
 // The four dashboard writes, each a thin call into an existing store or api function; the router owns HTTP and the cache.
 import * as api from '../api/index.js';
 import { NotFoundError } from '../core/api-errors.js';
+import { RawAppendOnlyError } from '../core/raw-append-only.js';
 import { listTouchableConflicts, resolveConflict } from '../store/conflicts.js';
 import { readEntry } from '../store/entry-reads.js';
 import { writeEntry } from '../store/entry-writes.js';
@@ -52,8 +53,7 @@ export function forgetMemory(hippoRoot, tenantId, rawId) {
     catch (err) {
         if (err instanceof NotFoundError)
             return notFound();
-        // Same match as cmdForget: the append-only trigger names itself in the message.
-        if (err instanceof Error && /append-only/i.test(err.message)) {
+        if (err instanceof RawAppendOnlyError) {
             const error = `Cannot forget ${id}: it is a raw, append-only memory. Archive it instead: hippo forget ${id} --archive --reason "<why>"`;
             return { status: 409, body: { error }, changed: false };
         }