hippo-memory 1.72.0 → 2.0.0

package/dist/consolidate/merge.js

@@ -23,7 +23,7 @@ export function retireHeldTexts(run) {
     const rejectedIn = (tenantId) => (text) => run.tombstones.find(tenantId, rejectionDigest(text)) !== null;
     for (let i = survivors.length - 1; i >= 0; i--) {
         const row = survivors[i];
-        const successor = run.retirable(row) ? successorAfterRetirement(row, byId, rejectedIn(row.tenantId)) : undefined;
+        const successor = run.retirable(row) ? successorAfterRetirement(row, byId, rejectedIn(row.tenant_id)) : undefined;
         if (successor === undefined)
             continue;
         run.result.details.push(`  ✂️  ${row.id} held a retired text${successor ? `, ${successor.id} holds the rest` : ''}`);
@@ -51,7 +51,7 @@ function partitionMergeCandidates(survivors) {
     // Map keeps insertion order, so a single-tenant store gets one partition in the original order.
     const mergeCandidatesByTenant = new Map();
     for (const entry of mergeCandidates) {
-        const key = derivationPartitionKey(entry.tenantId, entry.scope, entry.origin_project);
+        const key = derivationPartitionKey(entry.tenant_id, entry.scope, entry.origin_project);
         const bucket = mergeCandidatesByTenant.get(key);
         if (bucket)
             bucket.push(entry);
@@ -70,7 +70,7 @@ export function mergePass(run) {
     let mergesSkippedRejected = 0;
     for (const [, tenantCandidates] of mergeCandidatesByTenant) {
         const partition = {
-            tenantId: tenantCandidates[0].tenantId,
+            tenantId: tenantCandidates[0].tenant_id,
             scope: derivationScope(tenantCandidates[0].scope),
             origin: tenantCandidates[0].origin_project,
         };
@@ -156,8 +156,8 @@ function mergeRejected(run, semantic, cluster, related, used) {
     const { tombstones } = run;
     const newDigest = rejectionDigest(semantic.content);
     const oldDigest = rejectionDigest(legacyMergeContents(related)); // tombstones from older releases hold this format's digest
-    const newHit = tombstones.find(semantic.tenantId, newDigest);
-    const tombstone = newHit ?? tombstones.find(semantic.tenantId, oldDigest);
+    const newHit = tombstones.find(semantic.tenant_id, newDigest);
+    const tombstone = newHit ?? tombstones.find(semantic.tenant_id, oldDigest);
     const mergeDigest = newHit ? newDigest : oldDigest;
     if (!tombstone)
         return false;
@@ -167,7 +167,7 @@ function mergeRejected(run, semantic, cluster, related, used) {
         used.add(e.id);
     try {
         tombstones.audit({
-            tenantId: semantic.tenantId,
+            tenantId: semantic.tenant_id,
             actor: 'sleep',
             op: 'reject_refusal',
             metadata: {

package/dist/consolidate/sleep.js

@@ -156,7 +156,7 @@ function auditRescues(run, { rescuedEntries, rankById }) {
     const rescueEvent = (entry) => {
         const rank = rankById.get(entry.id);
         return {
-            tenantId: entry.tenantId,
+            tenantId: entry.tenant_id,
             actor: 'sleep',
             op: 'mv_rescue',
             targetId: entry.id,

package/dist/consolidate/traces.js

@@ -103,12 +103,12 @@ function sessionEnding(events) {
 // sleep; check the tombstone under the entry's own stamped tenantId, never a guessed one.
 function traceRejected(run, trace, sessionId) {
     const traceDigest = rejectionDigest(trace.content);
-    const tombstone = run.tombstones.find(trace.tenantId, traceDigest);
+    const tombstone = run.tombstones.find(trace.tenant_id, traceDigest);
     if (!tombstone)
         return false;
     try {
         run.tombstones.audit({
-            tenantId: trace.tenantId,
+            tenantId: trace.tenant_id,
             actor: 'sleep',
             op: 'reject_refusal',
             metadata: {

package/dist/core/config.js

@@ -252,17 +252,23 @@ function fileStamp(file) {
         return null;
     }
 }
-function parseConfigFile(configPath) {
+/** A config.json that exists must load: running on defaults would silently drop the user's settings, such as `sharedStore`. */
+function readConfigFile(configPath) {
+    let raw;
     try {
-        const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-        return configOverDefaults(raw);
+        raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
     }
     catch (err) {
-        if (fs.existsSync(configPath)) {
-            log.warn(`failed to parse ${configPath}: ${errorMessage(err)}`);
-        }
-        return { ...DEFAULT_CONFIG };
+        throw new Error(`${configPath} could not be loaded: ${errorMessage(err)}. Fix the file or delete it to use the defaults.`, { cause: err });
     }
+    if (!isJsonObject(raw)) {
+        throw new Error(`${configPath} must hold a JSON object. Fix the file or delete it to use the defaults.`);
+    }
+    // SAFETY: an object is all the shape check proves; configOverDefaults validates each key it reads.
+    return raw;
+}
+function parseConfigFile(configPath) {
+    return configOverDefaults(readConfigFile(configPath));
 }
 function configOverDefaults(raw) {
     const basis = raw.decayBasis;
@@ -334,15 +340,8 @@ export function isSharedStore(hippoRoot) {
     const stamp = fileStamp(configPath);
     if (stamp === null || notSharedStamps.get(configPath) === stamp)
         return false;
-    let raw;
-    try {
-        raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    }
-    catch (err) {
-        log.warn(`failed to read ${configPath}: ${errorMessage(err)} - sharedStore read as false.`);
-        return false;
-    }
-    if (raw?.sharedStore !== true) {
+    const raw = readConfigFile(configPath);
+    if (raw.sharedStore !== true) {
         if (notSharedStamps.size >= PARSED_CONFIGS_MAX)
             notSharedStamps.clear();
         notSharedStamps.set(configPath, stamp);

package/dist/core/markdown.js

@@ -42,7 +42,7 @@ export function serializeEntry(entry) {
     const frontmatter = entryFrontmatter(entry);
     // Emit tenant_id only when not 'default' to keep diffs clean for the dominant
     // single-tenant case (mirrors the plan's task 7 guidance).
-    const tenantId = entry.tenantId ?? DEFAULT_TENANT_ID;
+    const tenantId = entry.tenant_id ?? DEFAULT_TENANT_ID;
     if (tenantId !== DEFAULT_TENANT_ID) {
         frontmatter['tenant_id'] = tenantId;
     }
@@ -98,7 +98,7 @@ export function deserializeEntry(raw) {
         scope: data['scope'] === null || data['scope'] === undefined ? null : String(data['scope']),
         owner: data['owner'] === null || data['owner'] === undefined ? null : String(data['owner']),
         artifact_ref: data['artifact_ref'] === null || data['artifact_ref'] === undefined ? null : String(data['artifact_ref']),
-        tenantId: data['tenant_id'] === null || data['tenant_id'] === undefined ? DEFAULT_TENANT_ID : String(data['tenant_id']),
+        tenant_id: data['tenant_id'] === null || data['tenant_id'] === undefined ? DEFAULT_TENANT_ID : String(data['tenant_id']),
         origin_project: !('origin_project' in data) ? undefined : data['origin_project'] === null ? null : String(data['origin_project']),
     };
 }

package/dist/core/memory.d.ts

@@ -44,8 +44,8 @@ export interface MemoryEntry {
     descendant_count?: number;
     earliest_at?: string | null;
     latest_at?: string | null;
-    /** 1 when a child was invalidated, superseded, forgotten or archived since the last rebuild; sleep clears it. Always 0 below level 2. */
-    summary_dirty?: 0 | 1;
+    /** True when a child was invalidated, superseded, forgotten or archived since the last rebuild; sleep clears it. Always false below level 2. */
+    summary_dirty?: boolean;
     /** ISO 8601 time of the last successful rebuild, or null if never rebuilt. */
     last_rebuilt_at?: string | null;
     /** Count of successful rebuilds: 0 at the first buildDag write, bumped by each rebuild. */
@@ -56,7 +56,7 @@ export interface MemoryEntry {
     scope: string | null;
     owner: string | null;
     artifact_ref: string | null;
-    tenantId: string;
+    tenant_id: string;
     /** Owning project, lowercased; '' = user-global (injectable everywhere), null = none known (legacy or unnamed write), denied by ambient context.
      *  Stamped at write time by stampOriginProject (src/store/entry-row.ts); undefined only before the first write. */
     origin_project?: string | null;
@@ -114,7 +114,7 @@ export interface ConfidenceFacets {
     tier: ConfidenceLevel;
     agedOut: boolean;
 }
-export declare function confidenceFacets(entry: MemoryEntry, now?: Date): ConfidenceFacets;
+export declare function confidenceFacets(entry: ConfidenceInputs, now?: Date): ConfidenceFacets;
 export declare function facetsOf(entry: ConfidenceInputs, now: Date): ConfidenceFacets;
 export declare function confidenceLabel(entry: MemoryEntry, now?: Date): {
     text: string;

package/dist/core/memory.js

@@ -261,7 +261,7 @@ export function createMemory(content, options = {}) {
         scope: options.scope ?? null,
         owner: options.owner ?? null,
         artifact_ref: options.artifact_ref ?? null,
-        tenantId: options.tenantId ?? DEFAULT_TENANT_ID,
+        tenant_id: options.tenantId ?? DEFAULT_TENANT_ID,
     };
     entry.strength = calculateStrength(entry);
     return entry;
@@ -310,8 +310,14 @@ export function schemaFitSourceOf(entries) {
     }
     return { rows: entries.length, tagCounts, contents: entries.map((e) => e.content) };
 }
+// Tokens of this length or shorter are filler for schema fit.
+const FILLER_TOKEN_MAX_LENGTH = 3;
+// Matching half the tags at average weight scores about 0.5, so the raw overlap ratio is doubled.
+const TAG_OVERLAP_SCALE = 2;
+// Floor on the matches that saturate the content score, so a tiny store cannot saturate it on one hit.
+const CONTENT_ENOUGH_MIN_MATCHES = 5;
 function significantTokens(text) {
-    return new Set(text.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter((t) => t.length > 3));
+    return new Set(text.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter((t) => t.length > FILLER_TOKEN_MAX_LENGTH));
 }
 /** computeSchemaFit against `source`, for a caller that holds counts and texts but no rows. */
 export function schemaFitFrom(content, tags, source) {
@@ -331,13 +337,12 @@ export function schemaFitFrom(content, tags, source) {
             weightedOverlap += Math.log(N / freq) + 1;
         totalWeight += maxIdf;
     }
-    // Scaled so that matching half the tags at average weight gives about 0.5.
-    const tagScore = totalWeight > 0 ? Math.min(1, (weightedOverlap / totalWeight) * 2) : 0;
+    const tagScore = totalWeight > 0 ? Math.min(1, (weightedOverlap / totalWeight) * TAG_OVERLAP_SCALE) : 0;
     const newTokens = significantTokens(content);
     if (newTokens.size === 0)
         return Math.min(1, Math.max(0, tagScore));
     // The content score is capped at 1, which this many matching memories reach.
-    const enough = Math.max(5, N * CONTENT_ENOUGH_FRACTION);
+    const enough = Math.max(CONTENT_ENOUGH_MIN_MATCHES, N * CONTENT_ENOUGH_FRACTION);
     let contentMatches = 0;
     for (const text of source.contents) {
         const entryTokens = significantTokens(text);

package/dist/core/physics.d.ts

@@ -1,7 +1,7 @@
 /** 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 { type EmotionalValence } from './memory.js';
+import { type EmotionalValence, type MemoryEntry } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
 export interface PhysicsParticle {
     memoryId: string;
@@ -71,4 +71,6 @@ export declare function physicsScore(particles: PhysicsParticle[], queryEmbeddin
 tieKeyOf?: (memoryId: string) => string): ScoredPhysicsResult[];
 /** Nudges a particle toward (good outcome) or away from (bad outcome) the query embedding; new memories respond more (temperature). Mutates in place. */
 export declare function applyOutcomeFeedback(particle: PhysicsParticle, queryEmbedding: number[], good: boolean, feedbackAlpha: number): void;
+/** Initialize physics state for a memory from its embedding vector; returns the new particle without persisting (the caller must save). */
+export declare function initializeParticle(entry: MemoryEntry, embedding: number[], now?: Date): PhysicsParticle;
 //# sourceMappingURL=physics.d.ts.map

package/dist/core/physics.js

@@ -2,8 +2,9 @@
  * 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 { isRecallBoostAblated } from './ablation.js';
-import { FALLBACK_HALF_LIFE_DAYS } from './memory.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';
 export function vecDot(a, b) {
     let sum = 0;
@@ -301,4 +302,18 @@ 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). */
+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;
+    return {
+        memoryId: entry.id,
+        position: [...embedding], // copy: position will diverge from original embedding
+        velocity: vecZero(embedding.length),
+        mass: computeMass(strength, entry.retrieval_count),
+        charge: computeCharge(entry.emotional_valence),
+        temperature: computeTemperature(ageDays, 1.0),
+        lastSimulation: now.toISOString(),
+    };
+}
 //# sourceMappingURL=physics.js.map

package/dist/core/project-identity.js

@@ -8,6 +8,7 @@ import { MAX_ID_LEN } from '../util/limits.js';
 import { errorMessage, log } 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;
@@ -196,7 +197,7 @@ 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. */

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

@@ -63,7 +63,7 @@ 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;

package/dist/dashboard/dashboard-actions.d.ts

@@ -12,9 +12,9 @@ export interface ActionResult {
 /** Sets `pinned`; the audit row says `remember` with actor `dashboard`, the same op the old star toggle wrote. */
 export declare function pinMemory(hippoRoot: string, tenantId: string, rawId: string, body: ActionBody): ActionResult;
 /** Marks a memory wrong, the same signal as `hippo outcome --bad`. */
-export declare function markWrong(hippoRoot: string, tenantId: string, rawId: string): ActionResult;
+export declare function markWrong(hippoRoot: string, tenantId: string, rawId: string): Promise<ActionResult>;
 /** Deletes a memory like `hippo forget`; a raw receipt is append-only and answers 409 with the archive hint. */
-export declare function forgetMemory(hippoRoot: string, tenantId: string, rawId: string): ActionResult;
+export declare function forgetMemory(hippoRoot: string, tenantId: string, rawId: string): Promise<ActionResult>;
 /** Keeps one side of an open conflict and weakens the other; every refusal maps to its own status. */
 export declare function resolveOpenConflict(hippoRoot: string, tenantId: string, conflictId: number, body: ActionBody): ActionResult;
 //# sourceMappingURL=dashboard-actions.d.ts.map

package/dist/dashboard/dashboard-actions.js

@@ -29,25 +29,25 @@ export function pinMemory(hippoRoot, tenantId, rawId, body) {
     return { status: 200, body: null, changed: true, entry: next };
 }
 /** Marks a memory wrong, the same signal as `hippo outcome --bad`. */
-export function markWrong(hippoRoot, tenantId, rawId) {
+export async function markWrong(hippoRoot, tenantId, rawId) {
     const id = parseMemoryId(rawId);
     if (liveEntry(hippoRoot, tenantId, id) === null)
         return notFound();
     const ctx = { hippoRoot, tenantId, actor: api.adminActor(ACTOR) };
     // outcome() answers `applied: 0` for a missing or other-tenant id instead of throwing.
-    if (api.outcome(ctx, [id], false).applied === 0)
+    if ((await api.outcome(ctx, [id], false)).applied === 0)
         return notFound();
     const entry = readEntry(hippoRoot, id, tenantId);
     return entry === null ? notFound() : { status: 200, body: null, changed: true, entry };
 }
 /** Deletes a memory like `hippo forget`; a raw receipt is append-only and answers 409 with the archive hint. */
-export function forgetMemory(hippoRoot, tenantId, rawId) {
+export async function forgetMemory(hippoRoot, tenantId, rawId) {
     const id = parseMemoryId(rawId);
     if (liveEntry(hippoRoot, tenantId, id) === null)
         return notFound();
     const ctx = { hippoRoot, tenantId, actor: api.adminActor(ACTOR) };
     try {
-        const done = api.forget(ctx, id);
+        const done = await api.forget(ctx, id);
         return { status: 200, body: done, changed: true };
     }
     catch (err) {
@@ -79,7 +79,7 @@ export function resolveOpenConflict(hippoRoot, tenantId, conflictId, body) {
     if (liveEntry(hippoRoot, tenantId, conflict.memory_a_id) === null || liveEntry(hippoRoot, tenantId, conflict.memory_b_id) === null) {
         return notFound();
     }
-    const resolved = resolveConflict(hippoRoot, conflictId, keep, false, tenantId, { rejectedBy: ACTOR });
+    const resolved = resolveConflict(hippoRoot, { conflictId, keepId: keep, tenantId }, { rejectedBy: ACTOR });
     // Both guards passed above, so null here is a race with another resolver.
     if (resolved === null)
         return already();

package/dist/dashboard/dashboard-queries.js

@@ -2,6 +2,7 @@
 import { calculateStrength } from '../core/memory.js';
 import { loadOpenConflictsOf } from '../store/conflicts.js';
 import { BANDS, DAY_MS, LAYERS, isLiveMemory, memoryFacts, projectIdentity, } from './dashboard-snapshot.js';
+import { pct, round1 } from '../util/format.js';
 const SERIES_DAYS = 90;
 /** The server words each delta for this range; the client re-slices the series for 7d and 90d. */
 const DELTA_DAYS = 30;
@@ -9,9 +10,6 @@ const POINTS_MAX = 4_000;
 const GRID_COLS = 64;
 const GRID_ROWS = 32;
 const NAME_MATCHES = 3;
-function round1(value) {
-    return Math.round(value * 10) / 10;
-}
 function round3(value) {
     return Math.round(value * 1000) / 1000;
 }
@@ -32,9 +30,6 @@ function cumulativeSeries(times, nowMs) {
 function addedWithin(series) {
     return series[SERIES_DAYS] - series[SERIES_DAYS - DELTA_DAYS];
 }
-function pct(share) {
-    return `${(share * 100).toFixed(1)}%`;
-}
 function plural(n, one, many) {
     return `${n} ${n === 1 ? one : many}`;
 }
@@ -342,7 +337,7 @@ export function buildMemoryDetail(hippoRoot, tenantId, entry, options) {
         projectKey: project.key,
         projectName: project.name,
         scope: entry.scope,
-        tenant: entry.tenantId,
+        tenant: entry.tenant_id,
         kind: entry.kind,
         embedded,
         conflicts: openConflictsOf(hippoRoot, tenantId, entry, nowMs),

package/dist/dashboard/dashboard-snapshot.js

@@ -5,6 +5,7 @@ import { isQuarantineScope } from '../trust/quarantine.js';
 import { listMemoryConflicts } from '../store/conflicts.js';
 import { DashboardConnection, loadDashboardRows } from '../store/dashboard-reads.js';
 import { DAY_MS } from '../util/time.js';
+import { round1 } from '../util/format.js';
 export { DAY_MS };
 export const LAYERS = ['buffer', 'episodic', 'semantic', 'trace'];
 // Wire order of `Band`, and the order the mockup sorts bands in.
@@ -99,9 +100,6 @@ function cutHead(content) {
         end -= 1;
     return { head: content.slice(0, end), truncated: true };
 }
-function round1(value) {
-    return Math.round(value * 10) / 10;
-}
 function newDraft(identity) {
     return {
         summary: {

package/dist/dashboard/dashboard.js

@@ -179,7 +179,7 @@ async function handlePost(ctx, segments) {
     }
     const body = await readActionBody(req);
     const tenantId = resolveTenantId({});
-    const result = action(hippoRoot, tenantId, body);
+    const result = await action(hippoRoot, tenantId, body);
     if (result.changed)
         snapshots.invalidate();
     if (result.entry) {
@@ -300,7 +300,7 @@ function answerDashboardFailure(req, res, err) {
     const clientFault = err instanceof ParamError || err instanceof URIError || err instanceof BodyTimeoutError;
     // A cut-short response is logged even for a client fault; a bare 400 is not.
     if (res.headersSent || !clientFault) {
-        log.error('dashboard request failed', { ...errorFields(err), error: errorMessage(err), path: req.url });
+        log.error('dashboard request failed', { ...errorFields(err), error: errorMessage(err), path: (req.url ?? '/').split('?')[0] });
     }
     if (res.headersSent) {
         res.end();
@@ -318,9 +318,20 @@ function answerDashboardFailure(req, res, err) {
         return jsonResponse(res, { error: 'Malformed URL path' }, 400);
     jsonResponse(res, { error: 'Internal error' }, 500);
 }
-function printDashboardBanner(boundPort, token, distUiDir) {
+const DASHBOARD_URL_FILE = 'dashboard.url';
+function printDashboardBanner(hippoRoot, boundPort, token, distUiDir) {
     // The banner is the `hippo dashboard` command's printed result, so it stays on stdout.
-    console.log(`Hippo Dashboard running at http://localhost:${boundPort}/?token=${token}`);
+    const url = `http://localhost:${boundPort}/?token=${token}`;
+    if (process.stdout.isTTY) {
+        console.log(`Hippo Dashboard running at ${url}`);
+    }
+    else {
+        // Captured stdout lands in logs, so the token goes to an owner-only file, created fresh so its mode holds.
+        const file = path.join(hippoRoot, DASHBOARD_URL_FILE);
+        fs.rmSync(file, { force: true });
+        fs.writeFileSync(file, `${url}\n`, { flag: 'wx', mode: 0o600 });
+        console.log(`Hippo Dashboard running at http://localhost:${boundPort}/ (open the URL with its token from ${file})`);
+    }
     if (distUiDir !== null)
         console.log(`Serving React UI from ${distUiDir}`);
     console.log('Press Ctrl+C to stop.');
@@ -406,7 +417,7 @@ export function serveDashboard(hippoRoot, port = 3333, token = randomBytes(32).t
     server.listen(port, '127.0.0.1', () => {
         // SAFETY: listen() was given a TCP port, so address() is AddressInfo, never a pipe name.
         const boundPort = server.address().port;
-        printDashboardBanner(boundPort, token, hasDistUi ? distUiDir : null);
+        printDashboardBanner(hippoRoot, boundPort, token, hasDistUi ? distUiDir : null);
     });
     return server;
 }

package/dist/db/connect.d.ts

@@ -8,6 +8,7 @@ export interface OpenedDb {
     readonly db: DatabaseSyncLike;
     readonly facts: OpenFacts | null;
 }
-/** A new connection with the store's pragmas and migrations applied and the mirror cleanup run when it is due; the caller owns and closes it. */
+/** A new connection with the store's pragmas and migrations applied and the mirror cleanup run when it is due; the caller owns and closes it.
+ *  Outside any request scope (CLI start-up, timers) this is the only handle there is; openHippoDb reuses the scope's when one exists. */
 export declare function connectWithFacts(hippoRoot: string, busyWaitMs?: number): OpenedDb;
 //# sourceMappingURL=connect.d.ts.map

package/dist/db/connect.js

@@ -51,7 +51,8 @@ function archiveTop(db) {
     const row = db.prepare('SELECT MAX(id) AS top FROM raw_archive').get();
     return Number(row?.top ?? 0);
 }
-/** A new connection with the store's pragmas and migrations applied and the mirror cleanup run when it is due; the caller owns and closes it. */
+/** A new connection with the store's pragmas and migrations applied and the mirror cleanup run when it is due; the caller owns and closes it.
+ *  Outside any request scope (CLI start-up, timers) this is the only handle there is; openHippoDb reuses the scope's when one exists. */
 export function connectWithFacts(hippoRoot, busyWaitMs = DEFAULT_BUSY_WAIT_MS) {
     createStoreFilesOwnerOnly(hippoRoot);
     const db = new DatabaseSync(getHippoDbPath(hippoRoot));

package/dist/db/migrate.js

@@ -1,11 +1,12 @@
 import { PACKAGE_VERSION, compareSemver } from '../util/version.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { importLegacyEmbeddingIndex } from './vector-store.js';
 import { execWithBusyRetry, withWriteScope } from './busy.js';
 import { tableExists } from './tables.js';
 import { ensureMetaTable, getMeta, getSchemaVersion, setMeta, setSchemaVersion } from './meta.js';
 import { MEMORIES_FTS_DDL, REQUIRED_SCHEMA_OBJECTS, ensureContinuityIndexes, ensureContinuityTables } from './continuity.js';
 import { CURRENT_SCHEMA_VERSION, MIGRATIONS } from './migrations/index.js';
+import { placeholders } from '../util/sql.js';
 export function getCurrentSchemaVersion() {
     return CURRENT_SCHEMA_VERSION;
 }
@@ -130,7 +131,7 @@ function ensureMetaDefaults(db) {
     const keys = META_DEFAULTS.map(([key]) => key);
     // SAFETY: the statement selects only the `key` column of `meta`, which is TEXT NOT NULL, so each row is { key: string }.
     const present = new Set(db
-        .prepare(`SELECT key FROM meta WHERE key IN (${keys.map(() => '?').join(',')})`)
+        .prepare(`SELECT key FROM meta WHERE key IN (${placeholders(keys.length)})`)
         .all(...keys)
         .map((r) => r.key));
     if (present.size === META_DEFAULTS.length)
@@ -142,18 +143,24 @@ function ensureMetaDefaults(db) {
     }
 }
 function ensureOptionalFts(db) {
-    let available = false;
     try {
         db.exec(MEMORIES_FTS_DDL);
         repairFtsDrift(db);
-        available = true;
     }
     catch (err) {
+        // A busy or locked open says nothing about fts5, so only a missing module may flip the flag.
+        if (!/no such module/i.test(errorMessage(err)) || !/fts5/i.test(errorMessage(err))) {
+            log.warn(`full-text index not set up this open (${errorMessage(err)}); the next open retries`, errorFields(err));
+            return;
+        }
         log.warn(`full-text index unavailable (${errorMessage(err)}); search falls back to slower LIKE matching`);
+        writeFtsFlag(db, '0');
+        return;
     }
-    // Read-first: only write when the flag actually changed, so a healthy
-    // store's open doesn't take a write lock for a same-value upsert.
-    const flag = available ? '1' : '0';
+    writeFtsFlag(db, '1');
+}
+// Read-first: only write when the flag actually changed, so a healthy store's open takes no write lock.
+function writeFtsFlag(db, flag) {
     if (getMeta(db, 'fts5_available') !== flag)
         setMeta(db, 'fts5_available', flag);
 }

package/dist/db/migrations/v11.js

@@ -9,6 +9,7 @@ export const v11 = {
         if (!tableHasColumn(db, 'memories', 'superseded_by')) {
             db.exec(`ALTER TABLE memories ADD COLUMN superseded_by TEXT`);
         }
+        // SHORTCUT: overlaps idx_memories_layer_created (v01); dropping it is held until a schema migration is approved.
         db.exec(`CREATE INDEX IF NOT EXISTS idx_memories_current ON memories(layer, created) WHERE superseded_by IS NULL`);
     },
 };

package/dist/db/migrations/v14.js

@@ -48,6 +48,7 @@ export const v14 = {
         if (!tableHasColumn(db, 'memories', 'owner')) {
             db.exec(`ALTER TABLE memories ADD COLUMN owner TEXT`);
         }
+        // SHORTCUT: artifact_ref has no index, so connector deletes and vault lookups scan the tenant; the index is held until a schema migration is approved.
         if (!tableHasColumn(db, 'memories', 'artifact_ref')) {
             db.exec(`ALTER TABLE memories ADD COLUMN artifact_ref TEXT`);
         }

package/dist/db/physics-state.d.ts

@@ -2,8 +2,6 @@
 import type { DatabaseSyncLike } from './index.js';
 import type { MemoryEntry } from '../core/memory.js';
 import type { PhysicsParticle } from '../core/physics.js';
-export declare function float32ToBuffer(arr: number[]): Buffer;
-export declare function bufferToFloat32(buf: Buffer | Uint8Array): number[];
 /** Create the memory_physics table (migration v8). */
 export declare function createPhysicsTable(db: DatabaseSyncLike): void;
 /**
@@ -14,8 +12,6 @@ export declare function loadPhysicsState(db: DatabaseSyncLike, memoryIds?: strin
  * Save physics state for multiple particles (batch upsert).
  */
 export declare function savePhysicsState(db: DatabaseSyncLike, particles: PhysicsParticle[]): void;
-/** Initialize physics state for a memory from its embedding vector; returns the new particle without persisting (the caller must save). */
-export declare function initializeParticle(entry: MemoryEntry, embedding: number[], now?: Date): PhysicsParticle;
 /** Drops every particle, then seeds one per entry that has an embedding; `entries` may be read lazily, as each batch is written before the next is read. */
 export declare function resetAllPhysicsState(db: DatabaseSyncLike, entries: Iterable<MemoryEntry>, embeddingIndex: Record<string, number[]>, now?: Date): number;
 /** Refresh mass, charge and temperature for existing particles from current memory attributes (called during consolidation). */

package/dist/db/physics-state.js

@@ -1,23 +1,11 @@
 /** Physics state persistence: particle state (position, velocity, mass, charge, temperature) in SQLite, with BLOB columns for 384-dim vectors. */
 import { evalNow, strengthAblation } from '../core/ablation.js';
 import { withWriteScope } from './busy.js';
-import { computeMass, computeCharge, computeTemperature, vecZero } from '../core/physics.js';
+import { computeMass, computeCharge, computeTemperature, initializeParticle } from '../core/physics.js';
 import { calculateStrength } from '../core/memory.js';
 import { DAY_MS } from '../util/time.js';
-// Float32Array <-> Buffer serialization
-export function float32ToBuffer(arr) {
-    const f32 = new Float32Array(arr);
-    return Buffer.from(f32.buffer);
-}
-export function bufferToFloat32(buf) {
-    if (buf.byteLength === 0 || buf.byteLength % 4 !== 0)
-        return [];
-    // Ensure we have a properly aligned copy (SQLite may return Uint8Array, not Buffer)
-    const bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-    const aligned = new ArrayBuffer(bytes.length);
-    new Uint8Array(aligned).set(bytes);
-    return Array.from(new Float32Array(aligned));
-}
+import { placeholders } from '../util/sql.js';
+import { bufferToFloat32, float32ToBuffer } from '../util/vector-codec.js';
 // Schema migration
 /** Create the memory_physics table (migration v8). */
 export function createPhysicsTable(db) {
@@ -48,10 +36,10 @@ export function loadPhysicsState(db, memoryIds) {
         // Chunked so a whole-store candidate list stays under SQLite's bound-parameter limit.
         for (let i = 0; i < memoryIds.length; i += PHYSICS_ID_CHUNK) {
             const chunk = memoryIds.slice(i, i + PHYSICS_ID_CHUNK);
-            const placeholders = chunk.map(() => '?').join(',');
+            const marks = placeholders(chunk.length);
             // SAFETY: the SELECT projects exactly the PhysicsRow columns, in order.
             rows = rows.concat(db.prepare(`SELECT memory_id, position_blob, velocity_blob, mass, charge, temperature, last_simulation
-         FROM memory_physics WHERE memory_id IN (${placeholders})`).all(...chunk));
+         FROM memory_physics WHERE memory_id IN (${marks})`).all(...chunk));
         }
     }
     else {
@@ -97,20 +85,6 @@ export function savePhysicsState(db, particles) {
         }
     });
 }
-/** 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;
-    return {
-        memoryId: entry.id,
-        position: [...embedding], // copy — position will diverge from original embedding
-        velocity: vecZero(embedding.length),
-        mass: computeMass(strength, entry.retrieval_count),
-        charge: computeCharge(entry.emotional_valence),
-        temperature: computeTemperature(ageDays, 1.0),
-        lastSimulation: now.toISOString(),
-    };
-}
 const RESET_BATCH = 64;
 /** Drops every particle, then seeds one per entry that has an embedding; `entries` may be read lazily, as each batch is written before the next is read. */
 export function resetAllPhysicsState(db, entries, embeddingIndex, now = evalNow()) {

package/dist/db/request-stores.d.ts

@@ -15,6 +15,7 @@ export declare class RequestStores implements RequestScope {
     readonly busyWaitMs: number | undefined;
     readonly requestId: string | undefined;
     readonly deadline: import("../util/request-scope.js").RequestDeadline | undefined;
+    readonly signal: AbortSignal | undefined;
     readonly setupDoneFor: string | undefined;
     constructor(opts?: RequestStoresOptions);
     get closed(): boolean;