hippo-memory 1.72.0 → 2.1.0

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,9 +5,10 @@ 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';
 const MAX_WALK_DEPTH = 64;
 const identityCache = new Map();
 let remoteSwitch = null;
@@ -19,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
@@ -56,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;
@@ -179,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`);
     }
@@ -196,10 +203,12 @@ export function assertCallerProject(project) {
 }
 /** `origin_project IN (?, ...)` with one placeholder per name; an empty list matches nothing. */
 export function originInSql(names, column = 'origin_project') {
-    return names.length === 0 ? '0' : `${column} IN (${names.map(() => '?').join(', ')})`;
+    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';
@@ -209,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();
@@ -220,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;
@@ -247,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. */

package/dist/core/recall-scope.js

@@ -1,11 +1,21 @@
-/** 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 { BadRequestError, ForbiddenError } from './api-errors.js';
 import { MAX_ID_LEN } from '../util/limits.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 const RECALL_DEFAULT_DENY_SCOPES = ['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 function assertNonEmpty(arr, name) {
     if (arr.length === 0) {
@@ -13,8 +23,12 @@ export function assertNonEmpty(arr, name) {
     }
 }
 assertNonEmpty(RECALL_DEFAULT_DENY_SCOPES, 'RECALL_DEFAULT_DENY_SCOPES');
-/** 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 const PRIVATE_SCOPE_RE = /^[a-z][a-z0-9_-]*:private:/;
 function isScopeString(value) {
     return typeof value === 'string';
@@ -56,15 +70,21 @@ export function ownScopeTouches(ownScope, scope) {
     return !isPersonalScope(scope) || scope === ownScope;
 }
 /** 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 function passesScopeFilterForRecall(scope, requested, ownScope) {
     if (requested !== undefined && requested !== '') {
         return scope === requested;
     }
     return !isRestrictedScope(scope) || (ownScope != null && scope === ownScope);
 }
-/** 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 function passesCliRecallScopeFilter(scope, requested) {
     if (requested !== undefined && requested !== '' && !isPersonalScope(requested) && scope === requested) {
         return true;
@@ -80,14 +100,20 @@ export class ScopeForbiddenError extends ForbiddenError {
         this.scope = scope;
     }
 }
-/** 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 function isRestrictedScope(scope) {
     if (!isScopeString(scope))
         return false;
-    // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string literals; widening the array lets .includes() take any scope.
-    // `:private:` anywhere, any case, matches the SQL default-deny in src/store/search-rows.ts so JS never admits what SQL hides.
-    return isPrivateScope(scope) || /:private:/i.test(scope) || RECALL_DEFAULT_DENY_SCOPES.includes(scope);
+    // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string literals; widening the array lets .includes() take
+    // any scope.
+    // `:private:` anywhere, any case, matches the SQL default-deny in src/store/search-rows.ts so JS never admits what
+    // SQL hides.
+    return (isPrivateScope(scope) ||
+        /:private:/i.test(scope) ||
+        RECALL_DEFAULT_DENY_SCOPES.includes(scope));
 }
 /** Personal rows answer to their owner alone: role, key grants and resolver scopes never
  * open one. Else admin reads all; a member needs an exact grant on a restricted scope. */
@@ -132,7 +158,8 @@ export function commonDerivationScope(scopes) {
 /** Map-partition key for consolidate/dag/dedup producers: tenant + derivation scope + origin project,
  *  so a derived row never blends two restricted scopes, a mixed pair, or two projects. */
 export function derivationPartitionKey(tenantId, scope, origin) {
-    const project = origin === undefined ? '\u0002' : origin ?? '\u0001'; // unstamped, unknown and named never share a bucket
+    // unstamped, unknown and named never share a bucket
+    const project = origin === undefined ? '\u0002' : (origin ?? '\u0001');
     return `${tenantId}\u0000${derivationScope(scope) ?? ''}\u0000${project}`;
 }
 //# sourceMappingURL=recall-scope.js.map

package/dist/core/rejection-digest.d.ts

@@ -0,0 +1,7 @@
+/** Normalize content for rejection digests: NFC, lowercase, collapse whitespace runs, trim. No punctuation stripping:
+ * over-normalizing causes false refusals, worse than misses. */
+export declare function normalizeValueForRejection(content: string): string;
+/** Full 64-char sha256 hex of the normalized content: a tombstone key needs collision resistance, not the 16-char
+ * redaction hash used for query hashing. */
+export declare function rejectionDigest(content: string): string;
+//# sourceMappingURL=rejection-digest.d.ts.map

package/dist/core/rejection-digest.js

@@ -0,0 +1,13 @@
+// Tombstone keys are a pure hash of the normalized value, so the domain computes them without reaching the store.
+import { createHash } from 'node:crypto';
+/** Normalize content for rejection digests: NFC, lowercase, collapse whitespace runs, trim. No punctuation stripping:
+ * over-normalizing causes false refusals, worse than misses. */
+export function normalizeValueForRejection(content) {
+    return content.normalize('NFC').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+/** Full 64-char sha256 hex of the normalized content: a tombstone key needs collision resistance, not the 16-char
+ * redaction hash used for query hashing. */
+export function rejectionDigest(content) {
+    return createHash('sha256').update(normalizeValueForRejection(content)).digest('hex');
+}
+//# sourceMappingURL=rejection-digest.js.map

package/dist/core/salience.d.ts

@@ -1,4 +1,6 @@
-/** Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped. */
+/**
+ * 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,4 +1,6 @@
-/** Salience gate: decides at memory creation whether content is stored at full strength, starts weakened, or is skipped. */
+/**
+ * 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.
@@ -10,6 +12,9 @@ const NOVEL_ERROR_SCORE = 0.9;
 const NOVEL_BASE_SCORE = 0.5;
 const STRUCTURED_TAGS_BONUS = 0.15;
 const LENGTH_BONUS = 0.1;
+// A novel memory earns LENGTH_BONUS past each of these lengths in characters.
+const LONG_CONTENT_CHARS = 100;
+const VERY_LONG_CONTENT_CHARS = 300;
 const DEFAULTS = {
     recentWindow: 20,
     overlapThreshold: 0.6,
@@ -35,7 +40,8 @@ export function computeSalience(content, tags, recentMemories, options = {}) {
             if (recentErrors >= opts.maxRepeatErrors) {
                 return {
                     decision: 'start_weak',
-                    reason: `repeat_error (${recentErrors} recent errors, overlap ${(duplicateMatch.overlap * 100).toFixed(0)}% with ${duplicateMatch.matchId})`,
+                    reason: `repeat_error (${recentErrors} recent errors, overlap ` +
+                        `${(duplicateMatch.overlap * 100).toFixed(0)}% with ${duplicateMatch.matchId})`,
                     score: REPEAT_ERROR_SCORE,
                 };
             }
@@ -66,9 +72,9 @@ function scoreNovel(trimmed, tags) {
     let score = NOVEL_BASE_SCORE;
     if (hasStructuredTags)
         score += STRUCTURED_TAGS_BONUS;
-    if (trimmed.length > 100)
+    if (trimmed.length > LONG_CONTENT_CHARS)
         score += LENGTH_BONUS;
-    if (trimmed.length > 300)
+    if (trimmed.length > VERY_LONG_CONTENT_CHARS)
         score += LENGTH_BONUS;
     return { decision: 'store', reason: 'novel', score: Math.min(score, 1.0) };
 }

package/dist/core/search-types.d.ts

@@ -1,7 +1,17 @@
 import type { MemoryEntry } from './memory.js';
 export declare const DEFAULT_RECALL_BUDGET = 4000;
 export declare const DEFAULT_LOCAL_BUMP = 1.2;
-/** One score mutation applied after candidate generation; allocated only under `recall --why` or `RecallOpts.explain`. */
+export declare const DEFAULT_MMR_LAMBDA = 0.7;
+export declare const CONFLICT_PEER_MULTIPLIER = 0.3;
+export declare const VALUE_MULT_SLOPE = 0.3;
+export declare const VALUE_MULT_MIN = 0.7;
+export declare const VALUE_MULT_MAX = 1.3;
+export declare const UTILITY_LENGTH_PENALTY_CAP = 0.3;
+export declare const UTILITY_LENGTH_TOKENS = 10000;
+export declare const SALIENCE_MIN_MULTIPLIER = 0.5;
+/**
+ * One score mutation applied after candidate generation; allocated only under `recall --why` or `RecallOpts.explain`.
+ */
 export interface RerankStep {
     /** One of: interference, value, utility, reranker, goal-boost, retrieval-count-downweight. */
     stage: string;
@@ -63,7 +73,10 @@ export interface ScoreBreakdown {
     scopeBoost: number;
     /** Extra multiplier applied post-hybrid (e.g. 1.2x for local hits in a local+global merge); 1.0 otherwise. */
     sourceBump: number;
-    /** Immediate outcome nudge, 1 + 0.15*tanh(pos - neg) clipped to [0.85, 1.15]; separate from the slow strength path. */
+    /**
+     * Immediate outcome nudge, 1 + 0.15*tanh((pos - neg) / 2) clipped to [0.85, 1.15]; separate from the slow strength
+     * path.
+     */
     outcomeBoost: number;
     /** CHURN_STALE_RANK_MULTIPLIER if tagged 'churn-stale', else 1.0. */
     churnStaleMultiplier: number;