hippo-memory 2.0.0 → 2.1.0

package/dist/core/physics.js

@@ -1,11 +1,20 @@
-/** 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,
+/**
+ * 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 { cosineOf } from './cosine.js';
 import { evalNow, isRecallBoostAblated, strengthAblation } from './ablation.js';
 import { calculateStrength, FALLBACK_HALF_LIFE_DAYS } from './memory.js';
 import { DAY_MS } from '../util/time.js';
 import { comparePhysicsResultsBy } from './compare.js';
+// Floors that stop a near-zero mass or a coincident pair from dividing a force by about zero.
+const MIN_MASS = 0.01;
+const MIN_COSINE_DISTANCE = 0.01;
+// Mass gained per doubling of the retrieval count.
+const RETRIEVAL_MASS_GAIN = 0.1;
+const NEAR_ZERO = 1e-10;
 export function vecDot(a, b) {
     let sum = 0;
     for (let i = 0; i < a.length; i++)
@@ -39,7 +48,7 @@ export function vecZero(dim) {
 /** Normalize to unit length. Returns zero vector if magnitude < epsilon. */
 export function vecNormalize(v) {
     const mag = vecNorm(v);
-    if (mag < 1e-10)
+    if (mag < NEAR_ZERO)
         return vecZero(v.length);
     return vecScale(v, 1 / mag);
 }
@@ -57,10 +66,12 @@ const CHARGE_MAP = {
     critical: -1.0,
 };
 export function computeMass(strength, retrievalCount) {
-    // 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.
+    // 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)));
+    return Math.max(MIN_MASS, strength * (1 + RETRIEVAL_MASS_GAIN * Math.log2(effectiveCount + 1)));
 }
 export function computeCharge(valence) {
     return CHARGE_MAP[valence] ?? 0;
@@ -68,7 +79,10 @@ export function computeCharge(valence) {
 export function computeTemperature(ageDays, temperatureDecay) {
     return 1 / (ageDays * temperatureDecay + 1);
 }
-/** Query gravity (retrieval-time, virtual: does not move the particle): scalar ranking magnitude F = G_Q * mass * max(0, cosine(pos, 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 = cosineOf(particle.position, queryEmbedding);
     return G_query * particle.mass * Math.pow(Math.max(0, cos), 2);
@@ -79,13 +93,17 @@ export function velocityAlignmentBonus(particle, queryEmbedding) {
         return 0;
     const velMag = vecNorm(particle.velocity);
     const qNorm = vecNorm(queryEmbedding);
-    if (velMag < 1e-10 || qNorm < 1e-10)
+    if (velMag < NEAR_ZERO || qNorm < NEAR_ZERO)
         return 0;
     const alignment = vecDot(particle.velocity, queryEmbedding) / (velMag * qNorm);
     return Math.max(0, alignment);
 }
-/** 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. */
+/**
+ * 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 = cosineOf(pi.position, pj.position);
     if (cos <= 0)
@@ -95,23 +113,29 @@ export function attractionForce(pi, pj, G_memory, out = vecZero(pi.position.leng
     for (let k = 0; k < out.length; k++)
         diff[k] = pj.position[k] - pi.position[k];
     const norm = vecNorm(diff);
-    if (norm < 1e-10)
+    if (norm < NEAR_ZERO)
         return out;
     const inv = 1 / norm;
     for (let k = 0; k < out.length; k++)
         out[k] += diff[k] * inv * magnitude;
     return out;
 }
-/** 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. */
+/**
+ * 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 = cosineOf(pi.position, pj.position);
-    const dist = Math.max(0.01, 1 - cos);
+    const dist = Math.max(MIN_COSINE_DISTANCE, 1 - cos);
     const magnitude = K_repulsion * pi.mass * pj.mass / (dist * dist);
     // Direction: away from j
     const direction = vecNormalize(vecSub(pi.position, pj.position));
     return vecScale(direction, magnitude);
 }
-/** Drag force (consolidation-time): -drag * velocity / max(1, effectiveHalfLife), with effectiveHalfLife 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);
@@ -143,7 +167,7 @@ function computeNetForce(i, particles, ctx, diff) {
 /** 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);
+    const inv = 1 / Math.max(MIN_MASS, particles[i].mass);
     for (let k = 0; k < accel.length; k++)
         accel[k] *= inv;
     return accel;
@@ -234,9 +258,13 @@ export function computeSystemEnergy(particles, G_memory) {
     }
     return { kinetic, potential, total: kinetic + potential };
 }
-/** Scores all particles against a query embedding; virtual force computation, so it does NOT modify particle positions. */
+/**
+ * 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 content, from a caller with entries in scope); without it ties fall to memoryId,
+/**
+ * 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)
@@ -252,7 +280,8 @@ tieKeyOf) {
             finalScore: gravity + momentum,
         };
     });
-    // Base-score order picks the cluster_top_k amplification SET (which mutates scores), so ties must be cross-ingest-stable
+    // 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));
@@ -293,7 +322,10 @@ function applyClusterAmplification(results, particles, config) {
         top[i].finalScore = top[i].baseScore * amplification;
     }
 }
-/** Nudges a particle toward (good outcome) or away from (bad outcome) the query embedding; new memories respond more (temperature). Mutates 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;
@@ -302,7 +334,10 @@ export function applyOutcomeFeedback(particle, queryEmbedding, good, feedbackAlp
     const nudge = vecScale(direction, sign * feedbackAlpha * particle.temperature);
     particle.position = vecNormalize(vecAdd(particle.position, nudge));
 }
-/** Initialize physics state for a memory from its embedding vector; returns the new particle without persisting (the caller must save). */
+/**
+ * Initialize physics state for a memory from its embedding vector; returns the new particle without persisting (the
+ * caller must save).
+ */
 export function initializeParticle(entry, embedding, now = evalNow()) {
     const strength = calculateStrength(entry, now, { ablation: strengthAblation() });
     const ageDays = (now.getTime() - new Date(entry.created).getTime()) / DAY_MS;

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

@@ -1,12 +1,16 @@
-/** 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). */
+/** 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). */
     root: string;
-    /** The project id rows are stamped with: the project file's id, the origin remote, or legacyName; '' outside a project. */
+    /** The project id rows are stamped with: the project file's id, the origin remote, or legacyName; '' outside a
+     * project. */
     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`. */
+    /** 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. */
@@ -22,7 +26,8 @@ export interface ResolveProjectIdentityOpts {
 }
 /** Clear the per-process identity cache and the remote switch it read (test seam). */
 export declare function clearProjectIdentityCache(): void;
-/** Resolves the project identity for a working directory (default 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. */
@@ -38,29 +43,41 @@ 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;
-/** 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. */
+/** 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 ($HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo); getGlobalRoot (sharing/global-store.ts) returns it.
+/** 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, 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. */
+/** 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;
-/** 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. */
+/** 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. */
+/** 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. */
 export declare function deriveOriginProject(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
-/** The origin for a write that names none: NULL on a shared store, whose folder is no caller's project, else the folder's project. */
+/** The origin for a write that names none: NULL on a shared store, whose folder is no caller's project, else the
+ * folder's project. */
 export declare function fallbackOrigin(hippoRoot: string): string | null;
 //# sourceMappingURL=project-identity.d.ts.map

package/dist/core/project-identity.js

@@ -5,7 +5,7 @@ import * as path from 'path';
 import { BadRequestError } from './api-errors.js';
 import { isSharedStore, loadConfig } from './config.js';
 import { MAX_ID_LEN } from '../util/limits.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { originRemoteId, projectFileId } from './project-remote.js';
 import { realpathOrResolve } from '../util/real-path.js';
 import { placeholders } from '../util/sql.js';
@@ -20,8 +20,9 @@ export function clearProjectIdentityCache() {
 // The global store's config only: a per-store switch would stamp one checkout two ways.
 function remoteRuleOn() {
     const globalRoot = resolveGlobalRootDir();
-    if (remoteSwitch?.globalRoot !== globalRoot)
+    if (remoteSwitch?.globalRoot !== globalRoot) {
         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
@@ -57,11 +58,13 @@ function isDirectoryAt(p) {
         return fs.statSync(p).isDirectory();
     }
     catch (err) {
-        log.debug(`project identity: no marker at ${p}: ${errorMessage(err)}`);
+        // Most folders on the walk up hold no marker, so a failed stat is the normal answer.
+        log.debug(`project identity: no marker at ${p}: ${errorMessage(err)}`, errorFields(err));
         return false;
     }
 }
-/** Resolves the project identity for a working directory (default 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;
@@ -180,14 +183,17 @@ 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() === '')
         throw new BadRequestError('project name must not be blank');
-    if (aliases.length > MAX_PROJECT_ALIASES)
+    if (aliases.length > MAX_PROJECT_ALIASES) {
         throw new BadRequestError(`project aliases: at most ${MAX_PROJECT_ALIASES}`);
+    }
     if ([name, ...aliases].some((n) => n.length > MAX_ID_LEN)) {
         throw new BadRequestError(`project names: at most ${MAX_ID_LEN} characters each`);
     }
@@ -199,8 +205,10 @@ export function assertCallerProject(project) {
 export function originInSql(names, column = 'origin_project') {
     return names.length === 0 ? '0' : `${column} IN (${placeholders(names.length)})`;
 }
-/** 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. */
+/** 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';
@@ -210,7 +218,8 @@ export function classifyOriginProject(origin, current) {
         return 'user-global';
     return projectNames(current).includes(origin) ? 'project' : 'cross-project';
 }
-/** The global Hippo store directory ($HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo); getGlobalRoot (sharing/global-store.ts) returns it.
+/** 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();
@@ -221,13 +230,17 @@ export function resolveGlobalRootDir() {
         return path.join(xdgData, 'hippo');
     return path.join(os.homedir(), '.hippo');
 }
-/** 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. */
+/** 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()));
 }
-/** 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. */
+/** 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;
@@ -248,12 +261,15 @@ export function originFromSource(source, homeName) {
     }
     return 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. */
+/** 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. */
 export function deriveOriginProject(cwd, opts) {
     return resolveProjectIdentity(cwd, opts).name;
 }
-/** The origin for a write that names none: NULL on a shared store, whose folder is no caller's project, else the folder's project. */
+/** The origin for a write that names none: NULL on a shared store, whose folder is no caller's project, else the
+ * folder's project. */
 export function fallbackOrigin(hippoRoot) {
     return isSharedStore(hippoRoot) ? null : deriveOriginProject(path.dirname(path.resolve(hippoRoot)));
 }

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

@@ -1,12 +1,16 @@
-/** The config file git reads for a checkout: `.git/config`, a linked worktree's `<commondir>/config`, a submodule's `<gitdir>/config`. */
+/** The config file git reads for a checkout: `.git/config`, a linked
+ * worktree's `<commondir>/config`, a submodule's `<gitdir>/config`. */
 export declare function gitConfigPath(gitRoot: string): string | null;
-/** `remote.origin.url` from a config file's text, the first value as git fetch uses; the subsection name is case-sensitive. */
+/** `remote.origin.url` from a config file's text, the first value
+ * as git fetch uses; the subsection name is case-sensitive. */
 export declare function originUrlFromConfig(text: string): string | null;
-/** `host/path` for a network remote, so ssh, scp and https forms agree; null for a local path, which would put a user path into rows. */
+/** `host/path` for a network remote, so ssh, scp and https forms agree; null for a local path, which would put a
+ * user path into rows. */
 export declare function normaliseRemote(url: string): string | null;
 /** The normalised origin of the checkout rooted at gitRoot, or null when it has none a project can be named by. */
 export declare function originRemoteId(gitRoot: string): string | null;
 export declare const PROJECT_FILE = ".hippo-project.json";
-/** The `id` a team committed in `.hippo-project.json` at root, lowercased like every project name; null when absent or unusable. */
+/** The `id` a team committed in `.hippo-project.json` at root,
+ * lowercased like every project name; null when absent or unusable. */
 export declare function projectFileId(root: string): string | null;
 //# sourceMappingURL=project-remote.d.ts.map

package/dist/core/project-remote.js

@@ -1,9 +1,11 @@
-// A checkout's `origin` remote, read from its git config file and normalised into a project id; no git process, so the prompt hook can call it.
+// A checkout's `origin` remote, read from its git config file and normalised into a project id; no git process, so the
+// prompt hook can call it.
 import * as fs from 'fs';
 import * as path from 'path';
 import { isObjectLike, isStringValue } from './capture-contract.js';
-import { errorMessage, log } from '../util/log.js';
-/** The config file git reads for a checkout: `.git/config`, a linked worktree's `<commondir>/config`, a submodule's `<gitdir>/config`. */
+import { errorMessage, log, errorFields } from '../util/log.js';
+/** The config file git reads for a checkout: `.git/config`, a linked
+ * worktree's `<commondir>/config`, a submodule's `<gitdir>/config`. */
 export function gitConfigPath(gitRoot) {
     const marker = path.join(gitRoot, '.git');
     try {
@@ -20,11 +22,13 @@ export function gitConfigPath(gitRoot) {
         return path.join(path.resolve(linkDir, fs.readFileSync(commondir, 'utf8').trim()), 'config');
     }
     catch (err) {
-        log.debug(`project remote: no git config for ${gitRoot}: ${errorMessage(err)}`);
+        // A folder with no readable .git has no remote to name a project by, so the caller falls back to the folder name.
+        log.debug(`project remote: no git config for ${gitRoot}: ${errorMessage(err)}`, errorFields(err));
         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. */
+/** 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 {
@@ -34,7 +38,8 @@ function gitFilePointer(marker) {
         fs.closeSync(fd);
     }
 }
-/** One config value with git's quoting: `"` toggles quoting, backslash escapes, and an unquoted `#` or `;` starts a comment. */
+/** One config value with git's quoting: `"` toggles quoting,
+ * backslash escapes, and an unquoted `#` or `;` starts a comment. */
 function configValue(raw) {
     let out = '';
     let quoted = false;
@@ -58,7 +63,8 @@ function configValue(raw) {
 }
 const SECTION = /^\[\s*([A-Za-z0-9.-]+)(?:\s+"((?:[^"\\]|\\.)*)")?\s*\](.*)$/;
 const ENTRY = /^([A-Za-z][A-Za-z0-9-]*)\s*(?:=(.*))?$/;
-/** `remote.origin.url` from a config file's text, the first value as git fetch uses; the subsection name is case-sensitive. */
+/** `remote.origin.url` from a config file's text, the first value
+ * as git fetch uses; the subsection name is case-sensitive. */
 export function originUrlFromConfig(text) {
     let inOrigin = false;
     for (const raw of text.split(/\r?\n/)) {
@@ -89,7 +95,8 @@ function azureDevOps(hostPath) {
     const https = legacy ? `dev.azure.com/${legacy[1]}/${legacy[2]}` : hostPath;
     return https.startsWith('dev.azure.com/') ? https.replace('/_git/', '/') : https;
 }
-/** `host/path` for a network remote, so ssh, scp and https forms agree; null for a local path, which would put a user path into rows. */
+/** `host/path` for a network remote, so ssh, scp and https forms agree; null for a local path, which would put a
+ * user path into rows. */
 export function normaliseRemote(url) {
     // A query or fragment can carry a token (`?private_token=`) and never names the repo.
     const u = url.trim().replace(/[?#].*$/, '');
@@ -107,9 +114,16 @@ export function normaliseRemote(url) {
             return null;
         hostPath = `${scp[1]}/${scp[2]}`;
     }
-    const tidy = hostPath.toLowerCase().replace(/\\/g, '/').replace(/\/{2,}/g, '/').replace(/\/+$/, '').replace(/\.git$/, '').replace(/\/+$/, '');
+    const tidy = hostPath
+        .toLowerCase()
+        .replace(/\\/g, '/')
+        .replace(/\/{2,}/g, '/')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/, '')
+        .replace(/\/+$/, '');
     const id = azureDevOps(tidy);
-    // A colon would break the `shared:<project>:` source format; whitespace means this was no URL; an `@` left in a path may be a credential.
+    // A colon would break the `shared:<project>:` source format; whitespace means this was no URL; an `@` left in a path
+    // may be a credential.
     return /^[^/]+\/./.test(id) && !/[:\s@]/.test(id) ? id : null;
 }
 /** The normalised origin of the checkout rooted at gitRoot, or null when it has none a project can be named by. */
@@ -122,12 +136,14 @@ export function originRemoteId(gitRoot) {
         return url === null ? null : normaliseRemote(url);
     }
     catch (err) {
-        log.debug(`project remote: ${file} not read: ${errorMessage(err)}`);
+        // A checkout whose .git holds no config has no origin; the project is then named by its folder.
+        log.debug(`project remote: ${file} not read: ${errorMessage(err)}`, errorFields(err));
         return null;
     }
 }
 export const PROJECT_FILE = '.hippo-project.json';
-/** The `id` a team committed in `.hippo-project.json` at root, lowercased like every project name; null when absent or unusable. */
+/** The `id` a team committed in `.hippo-project.json` at root,
+ * lowercased like every project name; null when absent or unusable. */
 export function projectFileId(root) {
     const file = path.join(root, PROJECT_FILE);
     if (!fs.existsSync(file))
@@ -139,10 +155,11 @@ export function projectFileId(root) {
         // No slash: a committed file in an untrusted clone must not claim a remote-shaped id like `github.com/acme/api`.
         if (id !== '' && id.length <= 200 && !/[:\s/\\]/.test(id))
             return id;
-        log.warn(`${file}: "id" must be a non-empty string with no colon, slash or spaces; using the remote or folder name instead`);
+        log.warn(`${file}: "id" must be a non-empty string with no colon, slash or spaces; ` +
+            'using the remote or folder name instead');
     }
     catch (err) {
-        log.warn(`${file} not read: ${errorMessage(err)}; using the remote or folder name instead`);
+        log.warn(`${file} not read: ${errorMessage(err)}; using the remote or folder name instead`, errorFields(err));
     }
     return null;
 }

package/dist/core/recall-scope.d.ts

@@ -1,14 +1,28 @@
-/** Recall-side scope predicates, in a leaf module so search-both.ts can apply the same default-deny rule to searchBothHybrid's candidate loads without an
- * import cycle. src/api/index.ts imports these and re-exports them for back-compat (`api.isPrivateScope`, tests importing `passesScopeFilterForRecall`). */
+/**
+ * Recall-side scope predicates, in a leaf module so search-both.ts can apply the same default-deny rule to
+ * searchBothHybrid's candidate loads without an
+ * import cycle. src/api/index.ts imports these and re-exports them for back-compat (`api.isPrivateScope`, tests
+ * importing `passesScopeFilterForRecall`).
+ */
 import { ForbiddenError } from './api-errors.js';
-/** Literal scopes excluded from recall by default-deny when the caller passes no `scope`; read by the SQL clause in `loadSearchRows` and by
- * `passesScopeFilterForRecall`. Invariant: never empty, or quarantine scopes would pass both paths silently (the module-load assertion below pins this). */
+/**
+ * Literal scopes excluded from recall by default-deny when the caller passes no `scope`; read by the SQL clause in
+ * `loadSearchRows` and by
+ * `passesScopeFilterForRecall`. Invariant: never empty, or quarantine scopes would pass both paths silently (the
+ * module-load assertion below pins this).
+ */
 export declare const RECALL_DEFAULT_DENY_SCOPES: readonly ["unknown:legacy"];
-/** @internal Runtime guard against blanking a load-bearing literal array; `as const` arrays widen via `readonly T[]` at the call site, so the empty case
+/**
+ * @internal Runtime guard against blanking a load-bearing literal array; `as const` arrays widen via `readonly T[]` at
+ * the call site, so the empty case
  * is reachable and testable. */
 export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void;
-/** Source-agnostic private-scope detector: private means `<lowercase-source>:private:<rest>` (`slack:private:Cabc`; not `slack:public:x`, null, '',
- * 'private:foo'). The single source of truth for api.recall, the MCP server, the CLI and search-both.ts, so connector work cannot drift. */
+/**
+ * Source-agnostic private-scope detector: private means `<lowercase-source>:private:<rest>` (`slack:private:Cabc`; not
+ * `slack:public:x`, null, '',
+ * 'private:foo'). The single source of truth for api.recall, the MCP server, the CLI and search-both.ts, so connector
+ * work cannot drift.
+ */
 export declare const PRIVATE_SCOPE_RE: RegExp;
 /** True when `scope` matches the `<source>:private:*` shape. */
 export declare function isPrivateScope(scope: string | null | undefined): boolean;
@@ -29,17 +43,25 @@ export declare function canTouchScope(actor: {
 /** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
 export declare function ownScopeTouches(ownScope: string | null, scope: string | null): boolean;
 /** JS half of the recall default-deny rule (SQL half: `loadSearchRows`). A non-empty `requested` needs an exact match;
- * otherwise `<source>:private:*` and `RECALL_DEFAULT_DENY_SCOPES` buckets are denied, while null, public scopes and the caller's `ownScope` pass. */
+ * otherwise `<source>:private:*` and `RECALL_DEFAULT_DENY_SCOPES` buckets are denied, while null, public scopes and the
+ * caller's `ownScope` pass.
+ */
 export declare function passesScopeFilterForRecall(scope: string | null, requested: string | undefined, ownScope?: string | null): boolean;
-/** CLI `--scope` variant: an explicit `--scope X` UNLOCKS scope X on top of the default-admitted set rather than narrowing to X (api.recall keeps 'exact').
- * Includes private/quarantine scopes (owner access); a named personal scope never unlocks: the CLI has no caller identity. */
+/**
+ * CLI `--scope` variant: an explicit `--scope X` UNLOCKS scope X on top of the default-admitted set rather than
+ * narrowing to X (api.recall keeps 'exact').
+ * Includes private/quarantine scopes (owner access); a named personal scope never unlocks: the CLI has no caller
+ * identity.
+ */
 export declare function passesCliRecallScopeFilter(scope: string | null, requested: string | undefined): boolean;
 /** Thrown when a caller requests a scope its role may not read; the HTTP layer maps it to 403. */
 export declare class ScopeForbiddenError extends ForbiddenError {
     readonly scope: string;
     constructor(scope: string);
 }
-/** True for scopes default-deny hides (`<source>:private:*` and the quarantine buckets); naming one explicitly unlocks it, so naming one needs
+/**
+ * True for scopes default-deny hides (`<source>:private:*` and the quarantine buckets); naming one explicitly unlocks
+ * it, so naming one needs
  * authorization. */
 export declare function isRestrictedScope(scope: string | null | undefined): boolean;
 /** The identity a scope check runs against: a role, any scope grants, and the person who owns the key. */