hippo-memory 1.72.0 → 2.0.0

package/dist/server/client-ip.js

@@ -6,15 +6,15 @@ import { HttpError } from '../util/http-util.js';
 const IPV6_PREFIX_GROUPS = 4;
 /**
  * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated traffic can drain.
- * Set HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) only when a trusted proxy fronts EVERY request, or clients could mint a fresh bucket per request.
- * HIPPO_TRUSTED_PROXIES (IPs or CIDRs) pins which peers count as that proxy; in a comma-joined chain the key is the rightmost hop no trusted proxy added. */
+ * HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) is read only from a peer in HIPPO_TRUSTED_PROXIES (IPs or CIDRs, or `*` for any peer),
+ * so a caller that reaches the port past the proxy cannot pick its own bucket. In a comma-joined chain the key is the rightmost hop no trusted proxy added. */
 export function clientIpForRateLimit(req) {
     const socketIp = req.socket.remoteAddress ?? 'unknown';
     const header = envClientIpHeader();
     if (!header)
         return socketIp;
-    const trusted = trustedProxyList(envTrustedProxies());
-    if (trusted && !isTrustedProxy(trusted, socketIp))
+    const trust = proxyTrust(envTrustedProxies());
+    if (trust === undefined || (trust !== ANY_PEER && !isTrustedProxy(trust, socketIp)))
         return socketIp;
     const raw = req.headers[header];
     const hops = (Array.isArray(raw) ? raw.join(',') : raw ?? '')
@@ -22,20 +22,25 @@ export function clientIpForRateLimit(req) {
         .map((hop) => hop.trim())
         .filter((hop) => hop.length > 0);
     for (let i = hops.length - 1; i >= 0; i--) {
-        if (!trusted || !isTrustedProxy(trusted, hops[i]))
+        if (trust === ANY_PEER || !isTrustedProxy(trust, hops[i]))
             return hops[i];
     }
     return hops[0] ?? socketIp;
 }
+/** HIPPO_TRUSTED_PROXIES=*: every peer is the proxy, and the hop it appended is the client. */
+const ANY_PEER = '*';
 let trustedProxyCache;
-/** Parses HIPPO_TRUSTED_PROXIES once per distinct value; undefined when unset, so any peer may set the header. */
-function trustedProxyList(raw) {
-    if (!raw?.trim())
+/** Parses HIPPO_TRUSTED_PROXIES once per distinct value; undefined when unset, so no peer's header is read. */
+function proxyTrust(raw) {
+    const value = raw?.trim();
+    if (!value)
         return undefined;
-    if (trustedProxyCache?.raw === raw)
+    if (value === ANY_PEER)
+        return ANY_PEER;
+    if (trustedProxyCache?.raw === value)
         return trustedProxyCache.list;
     const list = new BlockList();
-    for (const entry of raw.split(',').map((e) => e.trim()).filter((e) => e.length > 0)) {
+    for (const entry of value.split(',').map((e) => e.trim()).filter((e) => e.length > 0)) {
         const [addr = '', prefix] = entry.split('/');
         const family = isIP(addr) === 6 ? 'ipv6' : 'ipv4';
         const bits = prefix === undefined ? undefined : Number(prefix);
@@ -49,17 +54,30 @@ function trustedProxyList(raw) {
         else
             list.addSubnet(addr, bits, family);
     }
-    trustedProxyCache = { raw, list };
+    trustedProxyCache = { raw: value, list };
     return list;
 }
-/** Said once at boot: with no proxy list, a caller that reaches the port without the proxy picks its own bucket by sending the header. */
-export function warnIfClientIpHeaderUnpinned() {
+/** serve() refused HIPPO_CLIENT_IP_HEADER with no HIPPO_TRUSTED_PROXIES: the header would be read from no one, so the setting is a mistake. */
+export class UntrustedClientIpHeaderError extends Error {
+    header;
+    constructor(header) {
+        super(`hippo serve: HIPPO_CLIENT_IP_HEADER is ${header} but HIPPO_TRUSTED_PROXIES is unset, so no peer may set that header. ` +
+            "Set HIPPO_TRUSTED_PROXIES to the proxy's addresses or CIDRs, or to * when the proxy is the only peer that can reach this port.");
+        this.header = header;
+        this.name = 'UntrustedClientIpHeaderError';
+    }
+}
+/** Checked at boot: a client-IP header needs a trusted-proxy list, and `*` is said once, since it believes any peer. */
+export function assertClientIpHeaderPinned() {
     const header = envClientIpHeader();
-    if (!header || trustedProxyList(envTrustedProxies()))
+    if (!header)
         return;
-    log.warn(`serve: HIPPO_CLIENT_IP_HEADER is ${header} and HIPPO_TRUSTED_PROXIES is unset, so any caller that reaches this port ` +
-        `without passing the proxy can send that header and pick its own rate-limit bucket. ` +
-        "Set HIPPO_TRUSTED_PROXIES to the proxy's addresses or CIDRs, so the header is read from the proxy alone.");
+    const trust = proxyTrust(envTrustedProxies());
+    if (trust === undefined)
+        throw new UntrustedClientIpHeaderError(header);
+    if (trust === ANY_PEER) {
+        log.warn(`serve: HIPPO_TRUSTED_PROXIES is *, so ${header} is read from any peer; keep the proxy the only route to this port.`);
+    }
 }
 /** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
 function subscriberKey(ip) {

package/dist/server/route-table.js

@@ -50,7 +50,7 @@ export const V1_ROUTES = [
     { method: 'GET', path: '/v1/quarantine', auth: 'admin', storeReady: 'quarantine', loop: 'off', handler: handleListQuarantine },
     { method: 'POST', pattern: '/v1/quarantine/:id/approve', auth: 'admin', storeReady: 'quarantine', loop: 'off', handler: handleApproveQuarantine },
     { method: 'POST', pattern: '/v1/quarantine/:id/reject', auth: 'admin', storeReady: 'quarantine', loop: 'off', handler: handleRejectQuarantine },
-    { method: 'GET', path: '/v1/audit', auth: 'caller', storeReady: 'auditLog', loop: 'off', handler: handleListAudit },
+    { method: 'GET', path: '/v1/audit', auth: 'admin', storeReady: 'auditLog', loop: 'off', handler: handleListAudit },
     { method: 'POST', path: '/v1/predictions', auth: 'caller', storeReady: 'predictions', loop: 'off', handler: handleCreatePrediction },
     { method: 'GET', path: '/v1/predictions', auth: 'caller', storeReady: 'predictions', loop: 'off', handler: handleListPredictions },
     { method: 'GET', path: '/v1/predictions/stats', auth: 'caller', storeReady: 'predictions', loop: 'off', handler: handlePredictionStats },
@@ -188,10 +188,9 @@ export function dispatchPublicJson({ req, res, opts }, method, path) {
     res.end(text);
     return true;
 }
-/** Under another store, a route that names no group, or one the store lacks, answers 501 without running. */
-function assertRoutePorted(opts, group) {
-    if (opts.store.kind === 'sqlite' || (group !== undefined && hasGroup(opts.store, group)))
-        return;
-    throw new HttpError(501, STORE_NOT_PORTED_MESSAGE);
+/** A route answers 501 without running when the store lacks its group; a route that names none, a sqliteOnly one among them, needs hippo.db's local files. */
+function assertRoutePorted(opts, group = 'localFiles') {
+    if (!hasGroup(opts.store, group))
+        throw new HttpError(501, STORE_NOT_PORTED_MESSAGE);
 }
 //# sourceMappingURL=route-table.js.map

package/dist/server/routes/memories.js

@@ -4,6 +4,7 @@ import { archiveRaw, forget, outcome, outcomeForLastRecall, promote, remember, s
 import { MEMORY_KINDS } from '../../core/memory.js';
 import { graphModelOf } from '../../graph/view.js';
 import { MAX_ENTITY_NAME_LEN } from '../../store/graph-rows.js';
+import { hasGroup } from '../../store/index.js';
 import { HttpError, sendJson } from '../../util/http-util.js';
 import { sleepInChild } from '../sleep-offload.js';
 import { getCallerProject, getString, getStringArray, isSetMember, parseJsonBody, parseListLimit, validateIdSegment } from '../validation.js';
@@ -115,9 +116,10 @@ export async function handleApplyOutcome({ req, res, ctx }) {
         sendJson(res, 200, { applied });
     }
     else {
-        // The last recall's ids live in hippo.db alone, so a client of another store must send the ids its recall returned.
-        if (ctx.store !== undefined && ctx.store.kind !== 'sqlite')
+        // A store without the group keeps no last recall, so its client must send the ids its recall returned.
+        if (ctx.store !== undefined && !hasGroup(ctx.store, 'lastRecall')) {
             throw new HttpError(501, 'this store keeps no last recall: send the ids your recall returned');
+        }
         const result = await outcomeForLastRecall(ctx, good);
         sendJson(res, 200, result);
     }

package/dist/server/sleep-offload.js

@@ -2,7 +2,7 @@
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { sleep } from '../api/index.js';
-import { StoreBusyError } from '../store/port.js';
+import { hasGroup, StoreBusyError } from '../store/port.js';
 import { envSleepTimeoutMs } from '../util/env.js';
 import { HttpError } from '../util/http-util.js';
 const DEFAULT_SLEEP_DEADLINE_MS = 600_000;
@@ -67,8 +67,8 @@ function inTurn(job) {
 }
 /** `sleep` for the HTTP route: same result and errors, run outside the serving process and stopped at the deadline (10 minutes, or HIPPO_SLEEP_TIMEOUT_MS). */
 export function sleepInChild(ctx, opts) {
-    // The child reopens the store by path, which only SQLite has; any other store keeps sleep's own refusal.
-    if (ctx.store && ctx.store.kind !== 'sqlite')
+    // The child reopens the store by path, which only a store of local files has; any other store keeps sleep's own refusal.
+    if (ctx.store && !hasGroup(ctx.store, 'localFiles'))
         return sleep(ctx, opts);
     return inTurn({ kind: 'sleep', hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, actor: ctx.actor, opts });
 }

package/dist/server/tls.d.ts

@@ -1,6 +1,11 @@
 import { type RequestListener, type Server } from 'node:http';
 import type { ServeOpts } from './types.js';
 export declare function createListener(tls: ServeOpts['tls'], onRequest: RequestListener): Server;
-/** Said once at boot: a non-loopback bind without TLS sends every key and memory over the network as plain text. */
-export declare function warnIfCleartext(host: string, tls: ServeOpts['tls'], loopbackHosts: ReadonlySet<string>): void;
+/** serve() refused a non-loopback bind without TLS: every key and memory would cross the network as plain text. */
+export declare class CleartextBindError extends Error {
+    readonly host: string;
+    constructor(host: string);
+}
+/** Throws CleartextBindError for a non-loopback bind without TLS unless the operator allowed cleartext, which is then said once at boot. */
+export declare function assertTlsOrCleartextAllowed(host: string, tls: ServeOpts['tls'], loopbackHosts: ReadonlySet<string>, allowCleartext: boolean): void;
 //# sourceMappingURL=tls.d.ts.map

package/dist/server/tls.js

@@ -1,4 +1,4 @@
-// The serve() listener: node:https when a certificate is given, else node:http and a boot warning off loopback.
+// The serve() listener: node:https when a certificate is given, else node:http, which a non-loopback bind must opt into.
 import { createServer as createHttpServer } from 'node:http';
 import { createServer as createHttpsServer } from 'node:https';
 import { errorMessage, log } from '../util/log.js';
@@ -14,11 +14,23 @@ export function createListener(tls, onRequest) {
         throw new Error(`hippo serve: the TLS certificate or key was refused: ${errorMessage(err)}`, { cause: err });
     }
 }
-/** Said once at boot: a non-loopback bind without TLS sends every key and memory over the network as plain text. */
-export function warnIfCleartext(host, tls, loopbackHosts) {
+/** serve() refused a non-loopback bind without TLS: every key and memory would cross the network as plain text. */
+export class CleartextBindError extends Error {
+    host;
+    constructor(host) {
+        super(`hippo serve: refusing to listen on ${host} without TLS, since API keys and memory text would travel in cleartext. ` +
+            'Pass --tls-cert and --tls-key (or set HIPPO_TLS_CERT and HIPPO_TLS_KEY) to serve HTTPS. If a TLS-terminating proxy sits in front, ' +
+            'start with --allow-cleartext, set HIPPO_ALLOW_CLEARTEXT=1, or pass allowCleartext: true to serve().');
+        this.host = host;
+        this.name = 'CleartextBindError';
+    }
+}
+/** Throws CleartextBindError for a non-loopback bind without TLS unless the operator allowed cleartext, which is then said once at boot. */
+export function assertTlsOrCleartextAllowed(host, tls, loopbackHosts, allowCleartext) {
     if (tls || loopbackHosts.has(host))
         return;
-    log.warn(`serve: listening on ${host} without TLS, so API keys and memory text travel in cleartext unless a TLS-terminating proxy sits in front. ` +
-        'To serve HTTPS directly, pass --tls-cert and --tls-key (or set HIPPO_TLS_CERT and HIPPO_TLS_KEY).');
+    if (!allowCleartext)
+        throw new CleartextBindError(host);
+    log.warn(`serve: listening on ${host} without TLS, as allowed; API keys and memory text are cleartext until the proxy in front adds TLS.`);
 }
 //# sourceMappingURL=tls.js.map

package/dist/server/types.d.ts

@@ -66,11 +66,16 @@ export interface ServeOpts {
         cert: string | Buffer;
         key: string | Buffer;
     };
+    /** Lets a non-loopback bind start without `tls`, for TLS that ends at a proxy in front; else serve() refuses it. Also HIPPO_ALLOW_CLEARTEXT=1. */
+    allowCleartext?: boolean;
+    /** The role a keyless local request (HIPPO_ALLOW_KEYLESS_LOCAL=1) gets; defaults to HIPPO_KEYLESS_LOCAL_ROLE, else 'member'. Only 'admin' is host admin. */
+    keylessLocalRole?: 'member' | 'admin';
     /** Static JSON served to anyone at GET <path>; built once at boot and never authenticated, so it must hold nothing secret. */
     publicJson?: Readonly<Record<string, JsonValue>>;
-    /** Request limits: perCaller after auth; perAddress replaces HIPPO_V1_RPS when set, 'off' disables it; failedAuthPerAddress guards scrypt. */
+    /** Request limits: perCaller after auth, on by default (HIPPO_CALLER_RPS, else 20 per second, burst 40); perAddress replaces HIPPO_V1_RPS when set;
+     * 'off' disables either; failedAuthPerAddress guards scrypt. */
     rateLimits?: {
-        perCaller?: RateLimitSpec;
+        perCaller?: RateLimitSpec | 'off';
         perAddress?: RateLimitSpec | 'off';
         failedAuthPerAddress?: RateLimitSpec;
     };

package/dist/server.d.ts

@@ -1,54 +1,17 @@
-import { type Actor, authCreateSelf, type AuthCreateSelfOpts, type AuthCreateSelfResult, authRevoke, type AuthRevokeReply, type AuthRevokeResult, type Context } from './api/index.js';
-import { ForbiddenError, NotFoundError } from './core/api-errors.js';
+import { type Actor, authCreateSelf, type AuthCreateSelfOpts, type AuthCreateSelfResult, authRevoke, type AuthRevokeResult, type Context } from './api/index.js';
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './core/api-errors.js';
 export { serve } from './server/boot.js';
-export { authCreateSelf, authRevoke, ForbiddenError, NotFoundError, type AuthCreateSelfOpts, type AuthCreateSelfResult, type AuthRevokeReply, type AuthRevokeResult, type Context, type Actor, };
+export { authCreateSelf, authRevoke, BadRequestError, ConflictError, ForbiddenError, NotFoundError, type AuthCreateSelfOpts, type AuthCreateSelfResult, type AuthRevokeResult, type Context, type Actor, };
 export { isCrossSite, LOOPBACK_HOST_HEADER } from './util/http-util.js';
-export { __resetSessionRecallHistoryHttp } from './server/routes/recall.js';
 export { clientIpForRateLimit } from './server/client-ip.js';
 export { isLoopback, isReservedActor } from './server/auth.js';
 export type { AddonCall, AddonRoute, AuthResolver, RateLimitSpec, ResolvedBearer, ServeOpts, ServerHandle } from './server/types.js';
+export type { HippoStore } from './store/index.js';
 export { HttpError } from './util/http-util.js';
 export { promptHookContext, type CallerProject } from './api/prompt-hook.js';
 export type { JsonValue } from './util/json.js';
 export { captureSessionTexts, type SessionCaptureRequest, type SessionCaptureResult } from './capture/session-texts.js';
-export { hasGroup, sqliteStore, type AmbientCandidateRequest, type ContextReads, type EntryRemoval, type EntryTarget, type EntryWrite, type EntryWrites, type HippoStore, type KeyAudit, type KeyListQuery, type KeyMint, type KeyRevoke, type KeyWrites, type OutcomeWrite, type RawArchive, type RecallSearchArgs, type RecallWrites, type SelfKeyMint, type StoreGroup, type StoreGroups, type SupersedeWrite, type VectorReads, type VectorBackfillQuery, type VectorRowWrite, type VectorWrite, type VectorWriteResult, type VectorWrites, } from './store/index.js';
-export { entryAfterOutcome } from './core/memory.js';
-export { rejectionDigest } from './store/rejection.js';
-export { RejectedValueError } from './core/api-errors.js';
-export { ownScopeTouches } from './core/recall-scope.js';
-export { BadRequestError, ConflictError } from './core/api-errors.js';
-export type { HippoDbContext, StoreReply } from './api/types.js';
-export type { ApiKeyListItem, ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from './store/auth.js';
-export type { KeysetPosition } from './util/keyset.js';
-export type { AppendAuditOpts, AuditEvent, ListAuditAfterOpts } from './store/audit.js';
-export type { ContinuityBlock } from './api/recall-types.js';
-export type { ActiveGoals, GetActiveGoalsOpts, Goal, GoalRecallLogRow, RetrievalPolicy } from './store/goals.js';
-export type { MemoryEntry } from './core/memory.js';
-export type { ClassResolution, PlanningFallacyEvidence } from './store/planning-fallacy-evidence.js';
-export type { PredictionBaserate } from './store/predictions.js';
-export type { RecallTraceInput } from './store/recall-trace.js';
-export type { StrengthenOptions } from './store/entry-writes.js';
-export type { OriginFilter, RecallScopeFilter, VectorCandidateSpec } from './store/search-rows.js';
-export type { ContinuityKey } from './store/sessions.js';
-export type { SessionEvent, TaskSnapshot } from './store/rows.js';
-export type { SessionHandoff } from './core/handoff.js';
-export type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, RecentOrigins } from './store/candidates.js';
-export type { AmbientStoreFilter } from './store/ambient.js';
-export type { AmbientTallies } from './core/ambient.js';
-export type { TokenUse } from './store/token-ledger.js';
-export type { EmbeddingIndexState } from './store/vector-index.js';
-export type { PhysicsParticle } from './core/physics.js';
-export { StoreBusyError } from './store/port.js';
-export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows, type VectorMatch, type VectorRow } from './db/vector-store.js';
-export { bufferToFloat32, float32ToBuffer } from './db/physics-state.js';
-export { replacesIndex } from './store/vector-index.js';
-export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './core/recall-scope.js';
-export { SECRET_TAGS } from './util/secret-detect.js';
-export { tallyAmbientEntries } from './core/ambient.js';
-export { ftsTermParts, rarestFtsQuery } from './core/prompt-recall.js';
-export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db/index.js';
 export { authCreate, type AuthCreateOpts, type AuthCreateResult } from './api/index.js';
-export { isSharedStore } from './core/config.js';
 export { ownerOrSubject } from './api/index.js';
 export { bindSessionOwner } from './api/session-owners.js';
 export { preCompactForCaller, type CallerHookOutput, type CallerPreCompactRequest } from './capture/pre-compact-caller.js';

package/dist/server.js

@@ -1,45 +1,18 @@
 import { authCreateSelf, authRevoke, } from './api/index.js';
-import { ForbiddenError, NotFoundError } from './core/api-errors.js';
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './core/api-errors.js';
 export { serve } from './server/boot.js';
 // Add-on packages mint and revoke keys through these without importing the whole api surface.
-export { authCreateSelf, authRevoke, ForbiddenError, NotFoundError, };
-// Published on the hippo-memory/server subpath before they moved to http-util.ts, so they stay exported here.
+export { authCreateSelf, authRevoke, BadRequestError, ConflictError, ForbiddenError, NotFoundError, };
 export { isCrossSite, LOOPBACK_HOST_HEADER } from './util/http-util.js';
-// The code behind these lives in src/server/; this subpath keeps exporting them.
-export { __resetSessionRecallHistoryHttp } from './server/routes/recall.js';
 export { clientIpForRateLimit } from './server/client-ip.js';
 export { isLoopback, isReservedActor } from './server/auth.js';
-// What an add-on route handler needs: HttpError for its 4xx replies, promptHookContext
-// for a caller that renders the prompt hook elsewhere, JsonValue for its body.
+// An add-on route replies 4xx with HttpError, renders the prompt hook elsewhere with promptHookContext, and types its body as JsonValue.
 export { HttpError } from './util/http-util.js';
 export { promptHookContext } from './api/prompt-hook.js';
 // A session-end route stores the turns its caller read from a transcript on the caller's own machine.
 export { captureSessionTexts } from './capture/session-texts.js';
-// An add-on serves from another database by passing serve() its own HippoStore.
-export { hasGroup, sqliteStore, } from './store/index.js';
-// An add-on store's entry writes apply an outcome, guard tombstones and check reach exactly as hippo.db does.
-export { entryAfterOutcome } from './core/memory.js';
-export { rejectionDigest } from './store/rejection.js';
-export { RejectedValueError } from './core/api-errors.js';
-export { ownScopeTouches } from './core/recall-scope.js';
-export { BadRequestError, ConflictError } from './core/api-errors.js';
-export { StoreBusyError } from './store/port.js';
-// An add-on store encodes, decodes and ranks vectors and particles with hippo.db's own code, and drops the index by its rule,
-// so both stores keep the same bytes and return the same ids in the same order.
-export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows } from './db/vector-store.js';
-export { bufferToFloat32, float32ToBuffer } from './db/physics-state.js';
-export { replacesIndex } from './store/vector-index.js';
-// An add-on's ContextReads applies hippo.db's scope, secret, tally and rarest-term rules with the same code.
-export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './core/recall-scope.js';
-export { SECRET_TAGS } from './util/secret-detect.js';
-export { tallyAmbientEntries } from './core/ambient.js';
-export { ftsTermParts, rarestFtsQuery } from './core/prompt-recall.js';
-// store copy --db writes the marker and reads the old hippo.db under the waiver.
-export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db/index.js';
 // An add-on's install step mints the first admin key into a store folder it names, which `hippo auth create` cannot reach.
 export { authCreate } from './api/index.js';
-// An add-on that serves a team store checks the flag before it starts.
-export { isSharedStore } from './core/config.js';
 export { ownerOrSubject } from './api/index.js';
 // A route that writes for a session binds it to the caller's owner first.
 export { bindSessionOwner } from './api/session-owners.js';

package/dist/sharing/global-store.d.ts

@@ -1,19 +1,18 @@
 import { MemoryEntry } from '../core/memory.js';
-import type { DatabaseSyncLike } from '../db/index.js';
 /** Returns the path to the global Hippo store.
  *  Resolution order: $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo/ */
 export declare function getGlobalRoot(): string;
 /** Ensure the global store exists. */
 export declare function initGlobal(): void;
-/** Copies a local memory to the global store and returns the copy, which gets a new `g_` id so it cannot collide. */
-export declare function promoteToGlobal(localRoot: string, id: string, opts?: {
+export interface PromoteOptions {
     actor?: string;
     tenantId?: string;
-    afterWrite?: (db: DatabaseSyncLike, globalId: string) => void;
     /** Also writes one `promote` audit row for the copy ({sourceId}), in the copy's own transaction. */
     auditAs?: {
         tenantId: string;
         actor: string;
     };
-}): MemoryEntry;
+}
+/** Copies a local memory to the global store and returns the copy, which gets a new `g_` id so it cannot collide. */
+export declare function promoteToGlobal(localRoot: string, id: string, opts?: PromoteOptions): MemoryEntry;
 //# sourceMappingURL=global-store.d.ts.map

package/dist/sharing/global-store.js

@@ -3,7 +3,7 @@ import { BadRequestError, NotFoundError } from '../core/api-errors.js';
 import * as fs from 'fs';
 import { generateId } from '../core/memory.js';
 import { initStore } from '../store/open.js';
-import { writeEntry } from '../store/entry-writes.js';
+import { writeEntryWithHook } from '../store/entry-writes.js';
 import { readEntry } from '../store/entry-reads.js';
 import { isPersonalScope } from '../core/recall-scope.js';
 import { fallbackOrigin, resolveGlobalRootDir } from '../core/project-identity.js';
@@ -30,15 +30,6 @@ export function initGlobal() {
         initStore(globalRoot);
     }
 }
-/** The copy's write hook: the `promote` row when asked for, then the caller's own hook, both in the copy's transaction. */
-function promoteHook(sourceId, auditAs, afterWrite) {
-    if (!auditAs)
-        return afterWrite;
-    return (db, globalId) => {
-        appendAuditEvent(db, { tenantId: auditAs.tenantId, actor: auditAs.actor, op: 'promote', targetId: globalId, metadata: { sourceId } });
-        afterWrite?.(db, globalId);
-    };
-}
 /** Copies a local memory to the global store and returns the copy, which gets a new `g_` id so it cannot collide. */
 export function promoteToGlobal(localRoot, id, opts) {
     const entry = readEntry(localRoot, id, opts?.tenantId);
@@ -67,7 +58,11 @@ export function promoteToGlobal(localRoot, id, opts) {
         source: isSharedStore(localRoot) ? `shared::${new Date().toISOString()}` : `promoted:${localRoot}`,
         origin_project: entry.origin_project ?? fallbackOrigin(localRoot),
     };
-    writeEntry(globalRoot, globalEntry, { actor: opts?.actor, afterWrite: promoteHook(id, opts?.auditAs, opts?.afterWrite) });
+    const { auditAs } = opts ?? {};
+    const promoteRow = auditAs && ((db, globalId) => {
+        appendAuditEvent(db, { tenantId: auditAs.tenantId, actor: auditAs.actor, op: 'promote', targetId: globalId, metadata: { sourceId: id } });
+    });
+    writeEntryWithHook(globalRoot, globalEntry, { actor: opts?.actor, afterWrite: promoteRow });
     // Fire-and-forget: embedMemory gates on availability and never rejects.
     void embedMemory(globalRoot, globalEntry);
     return globalEntry;

package/dist/sharing/global-sync.js

@@ -24,7 +24,7 @@ export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
         return 0;
     return withRequestStoresSync(() => copyMissingRows(localRoot, globalRoot, opts.includeCrossProject === true));
 }
-const textKey = (e) => `${e.tenantId}\n${e.content}`;
+const textKey = (e) => `${e.tenant_id}\n${e.content}`;
 /** One open per store and one transaction: id, tenant and text decide which rows to read whole, and the copies commit together. */
 function copyMissingRows(localRoot, globalRoot, includeCrossProject) {
     // Host-wide read: the global union is copied into a tenant-scoped local store, and each copy keeps its own tenant.

package/dist/sharing/search-both.js

@@ -1,7 +1,7 @@
 // Search across the local and global stores, merged into one ranked, budgeted list.
 import { compareScoresDesc } from '../core/compare.js';
 import * as fs from 'fs';
-import { loadSearchEntries, loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
+import { loadSearchEntries, loadRecallEntries, recallScopeFilter } from '../store/search-rows.js';
 import { passesScopeFilterForRecall, passesCliRecallScopeFilter } from '../core/recall-scope.js';
 import { search } from '../search/bm25-search.js';
 import { hybridSearch } from '../search/hybrid.js';
@@ -79,7 +79,14 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
         if (!fs.existsSync(root))
             return [];
         return recallScope
-            ? loadRecallSearchEntries(root, query, searchWindow, tenantId, recallScope.requested, recallScope.additive ? 'additive' : 'exact', Boolean(includeSuperseded) || Boolean(asOf), undefined, recallScope.ownScope)
+            ? loadRecallEntries(root, query, {
+                limit: searchWindow,
+                tenantId,
+                requestedScope: recallScope.requested,
+                explicitScopeMode: recallScope.additive ? 'additive' : 'exact',
+                includeSuperseded: Boolean(includeSuperseded) || Boolean(asOf),
+                ownScope: recallScope.ownScope,
+            })
             : loadSearchEntries(root, query, searchWindow, tenantId);
     };
     const passesScope = (e) => !recallScope || (recallScope.additive

package/dist/sharing/share.js

@@ -5,7 +5,7 @@ import * as path from 'path';
 import { generateId, COMPACTION_MEMORY_TAG } from '../core/memory.js';
 import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TAGS } from '../core/agent-memory-tools.js';
 import { writeEntriesSkippingRejected, writeEntry } from '../store/entry-writes.js';
-import { loadAllEntries, readEntry } from '../store/entry-reads.js';
+import { loadAllEntries, loadEntryTextKeys, readEntry } from '../store/entry-reads.js';
 import { tallySources } from '../store/candidates.js';
 import { isPersonalScope } from '../core/recall-scope.js';
 import { fallbackOrigin } from '../core/project-identity.js';
@@ -214,9 +214,7 @@ export function autoShare(localRoot, options = {}) {
     const globalRoot = getGlobalRoot();
     // Host-wide read. The global store IS the union across all tenants;
     // per-tenant filtering on the global root would defeat the purpose.
-    const globalEntries = loadAllEntries(globalRoot);
-    // Build set of global content hashes to avoid duplicates
-    const globalContentSet = storedTextKeys(globalEntries);
+    const globalContentSet = storedTextKeys(loadEntryTextKeys(globalRoot));
     const candidates = localEntries.filter((entry) => isAutoShareCandidate(entry, globalContentSet, minScore, options.stats));
     if (dryRun)
         return candidates;

package/dist/store/ambient.js

@@ -5,6 +5,7 @@ import { onHandle, openStore } from './open.js';
 import { jsonList } from './candidates.js';
 import { originInSql } from '../core/project-identity.js';
 import { AMBIENT_FRESH_WINDOW_MS, HIGH_SCHEMA_FIT_ABOVE, isErrorTagged } from '../core/ambient.js';
+import { placeholders } from '../util/sql.js';
 // SHORTCUT: mirrors loadContextCandidates' WHERE (request-path snapshots pin the match); share it once store.ts is split.
 function contextRowsWhere(tenantId, filter) {
     const where = ['tenant_id = ?', `COALESCE(superseded_by, '') = ''`, `COALESCE(kind, '') != 'archived'`];
@@ -29,7 +30,7 @@ function secretTaggedSql() {
     const tags = [...SECRET_TAGS];
     return {
         sql: `((${tags.map(() => 'tags_json LIKE ?').join(' OR ')})
-      AND EXISTS (SELECT 1 FROM json_each(${jsonList('tags_json')}) WHERE lower(value) IN (${tags.map(() => '?').join(', ')})))`,
+      AND EXISTS (SELECT 1 FROM json_each(${jsonList('tags_json')}) WHERE lower(value) IN (${placeholders(tags.length)})))`,
         params: [...tags.map((t) => `%"${t}"%`), ...tags],
     };
 }

package/dist/store/candidates.js

@@ -1,7 +1,7 @@
 import { FALLBACK_HALF_LIFE_DAYS, Layer, calculateStrength, facetsOf, schemaFitFrom } from '../core/memory.js';
 import { strengthSql } from './rule-sql.js';
 import { withReadSnapshot } from '../db/index.js';
-import { scopeAdmitSql } from './rule-sql.js';
+import { rewardFactorSql, scopeAdmitSql } from './rule-sql.js';
 import { MEMORY_SELECT_COLUMNS, rowToEntry, parseJsonArray } from './rows.js';
 import { onHandle, openStore } from './open.js';
 import { originInSql } from '../core/project-identity.js';
@@ -89,10 +89,10 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
     }, openStore);
 }
 // calculateStrength's decay exponent with its reward factor, pins first: the strongest rows, without scoring each one in JS.
-const DECAY_RANK_SQL = `pinned DESC,
+// A function, not a constant, so the outcome-slow ablation is read per query as strengthSql reads it.
+const decayRankSql = () => `pinned DESC,
   CASE WHEN half_life_days > 0 THEN (julianday(?) - julianday(last_retrieved))
-    / (half_life_days * (1.0 + 0.5 * (COALESCE(outcome_positive, 0) - COALESCE(outcome_negative, 0))
-      / (COALESCE(outcome_positive, 0) + COALESCE(outcome_negative, 0) + 1.0))) END ASC NULLS LAST,
+    / (half_life_days * ${rewardFactorSql()}) END ASC NULLS LAST,
   id ASC`;
 /** Live tenant rows passing `filter`, at most `filter.cap`, in loadAllEntries' order; below the cap, every such row. */
 export function loadContextCandidates(hippoRoot, tenantId, filter) {
@@ -111,11 +111,21 @@ export function loadContextCandidates(hippoRoot, tenantId, filter) {
         where.push(`(origin_project = '' OR ${originInSql(filter.project)})`);
         params.push(...filter.project);
     }
+    const cap = Math.max(0, Math.trunc(filter.cap));
+    const whereSql = where.join(' AND ');
     return onHandle(hippoRoot, (db) => {
-        // SAFETY: the outer SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set; the rank sort carries ids only.
-        const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (
-        SELECT id FROM memories WHERE ${where.join(' AND ')} ORDER BY ${DECAY_RANK_SQL} LIMIT ?
-      ) ORDER BY created ASC, id ASC`).all(...params, filter.now.toISOString(), Math.max(0, Math.trunc(filter.cap)));
+        // SAFETY: the count row has the one column named.
+        const matched = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE ${whereSql}`).get(...params).n;
+        // Under the cap every match is returned, so the per-row decay math and the sort are skipped.
+        // SHORTCUT: past the cap the rank still scans the tenant; a stored decay rank column needs a schema migration, held until one is approved.
+        const ranked = matched > cap;
+        const sql = ranked
+            ? `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (
+        SELECT id FROM memories WHERE ${whereSql} ORDER BY ${decayRankSql()} LIMIT ?
+      ) ORDER BY created ASC, id ASC`
+            : `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE ${whereSql} ORDER BY created ASC, id ASC`;
+        // SAFETY: both SELECTs name exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set; the rank sort carries ids only.
+        const rows = db.prepare(sql).all(...params, ...(ranked ? [filter.now.toISOString(), cap] : []));
         return rows.map(rowToEntry);
     }, openStore);
 }

package/dist/store/cards.js

@@ -6,6 +6,7 @@ import { assertTenantId } from './tenant.js';
 import { onHandle, openStore } from './open.js';
 import { chunked } from '../util/chunked.js';
 import { HANDOFF_COLUMNS } from './handoffs.js';
+import { placeholders } from '../util/sql.js';
 const CARD_COLUMNS = 'id, title, status, assignee_runtime, repo, contract, budget, lease_until, heartbeat_at, created_at, updated_at, tenant_id, scope';
 function rowToCard(row) {
     return {
@@ -88,10 +89,10 @@ function transitionCards(db, tenantId, cardIds, options) {
     const now = new Date().toISOString();
     // Lease columns follow status: set on the move to running, cleared on every other move (rule 15).
     const lease = to === 'running' ? [leaseUntilFrom(now), now] : [null, null];
-    const fromPlaceholders = from.map(() => '?').join(', ');
+    const fromPlaceholders = placeholders(from.length);
     const sql = `
     UPDATE cards SET status = ?, updated_at = ?, lease_until = ?, heartbeat_at = ?${extra?.setSql ? `, ${extra.setSql}` : ''}
-    WHERE id IN (${cardIds.map(() => '?').join(', ')}) AND tenant_id = ? AND status IN (${fromPlaceholders})${extra?.whereSql ? ` AND ${extra.whereSql}` : ''}
+    WHERE id IN (${placeholders(cardIds.length)}) AND tenant_id = ? AND status IN (${fromPlaceholders})${extra?.whereSql ? ` AND ${extra.whereSql}` : ''}
   `;
     const params = [to, now, ...lease, ...(extra?.params ?? []), ...cardIds, tenantId, ...from];
     const result = db.prepare(sql).run(...params);
@@ -134,9 +135,9 @@ export function createCard(hippoRoot, tenantId, input) {
 function everyParentDone(db, tenantId, dependsOn) {
     if (dependsOn.length === 0)
         return true;
-    const placeholders = dependsOn.map(() => '?').join(', ');
+    const marks = placeholders(dependsOn.length);
     // SAFETY: rows' shape matches the two columns named in the SELECT below.
-    const rows = db.prepare(`SELECT id, status FROM cards WHERE tenant_id = ? AND id IN (${placeholders})`).all(tenantId, ...dependsOn);
+    const rows = db.prepare(`SELECT id, status FROM cards WHERE tenant_id = ? AND id IN (${marks})`).all(tenantId, ...dependsOn);
     const found = new Map(rows.map((r) => [r.id, r.status]));
     // Pre-check before any write: a typo'd --depends-on can never commit a card row.
     for (const parentId of dependsOn) {

package/dist/store/compactions-record.js

@@ -334,24 +334,25 @@ function spoolRecorder(db, hippoRoot, log) {
         saveItems(db, hippoRoot, itemContext(spooled.tenantId, record), log);
     };
 }
-/** Runs `step` over each record until the deadline; a record that throws is logged and the rest still run. Returns how many `step` finished. */
-function replayEach(run, records, what, step) {
+/** Runs `step` over each row until the deadline; a row that will not map or a step that throws is logged and the rest still run.
+ * Returns how many `step` finished. */
+function replayEach(run, rows, what, step) {
     let finished = 0;
-    for (const record of records) {
+    for (const row of rows) {
         if (Date.now() > run.deadline)
             break;
         try {
-            if (step(record))
+            if (step(toRecord(row)))
                 finished++;
         }
         catch (err) {
-            run.log(`${what} of ${record.id} failed: ${errorMessage(err)}`);
+            run.log(`${what} of ${row.id} failed: ${errorMessage(err)}`);
         }
     }
     return finished;
 }
 function replayStalled(run) {
-    const stalled = stalledSummarisedRows(run.db, run.tenantId, new Date(run.now - REPLAY_AFTER_MS).toISOString()).map(toRecord);
+    const stalled = stalledSummarisedRows(run.db, run.tenantId, new Date(run.now - REPLAY_AFTER_MS).toISOString());
     return replayEach(run, stalled, 'replay', (record) => {
         saveItems(run.db, run.hippoRoot, itemContext(run.tenantId, record), run.log);
         return true;
@@ -389,7 +390,7 @@ function fillFromTranscript(run, record) {
     return true;
 }
 function replayOpen(run) {
-    const open = openTranscriptRows(run.db, run.tenantId, new Date(run.now - REPLAY_AFTER_MS).toISOString(), new Date(run.now - TRANSCRIPT_FILL_WINDOW_MS).toISOString()).map(toRecord);
+    const open = openTranscriptRows(run.db, run.tenantId, new Date(run.now - REPLAY_AFTER_MS).toISOString(), new Date(run.now - TRANSCRIPT_FILL_WINDOW_MS).toISOString());
     return replayEach(run, open, 'transcript fill', (record) => fillFromTranscript(run, record));
 }
 /** Finishes what a killed hook or a busy store left: `summarised` records, spool files, and `started` records the transcript can fill.