hippo-memory 1.70.0 → 1.72.0

package/dist/store/embeddings/local.js

@@ -1,192 +0,0 @@
-// The local Transformers.js embedder, a leaf so embedding-provider.ts can wrap it without importing embeddings.ts.
-import { envModelCache } from '../../util/env.js';
-import * as fs from 'fs';
-import * as path from 'path';
-import { createRequire } from 'module';
-import { loadConfig } from '../../core/config.js';
-import { errorMessage, log } from '../../util/log.js';
-const _require = createRequire(import.meta.url);
-let _embeddingAvailable = null;
-// A pipeline is expensive to load, so one instance per model is kept for the process.
-const _pipelineInstances = new Map();
-const _pipelineLoading = new Map();
-const _pipelineErrors = new Map();
-export const DEFAULT_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
-/** BGE was trained with CLS pooling; everything else gets mean, the sentence-transformers default, since CLS degrades mean-trained models. */
-export function poolingFor(model) {
-    return /\bbge\b/i.test(model) ? 'cls' : 'mean';
-}
-/** e5 models only match a query to a passage when each side carries its trained prefix. */
-export function prefixFor(model, role) {
-    if (!role)
-        return '';
-    if (/\be5\b/i.test(model)) {
-        return role === 'query' ? 'query: ' : 'passage: ';
-    }
-    return '';
-}
-// Use Function constructor to bypass TypeScript static module resolution
-// for optional peer dependencies that may not be installed.
-// SAFETY: `import(s)` always resolves to a module namespace object (or rejects);
-// Promise<object> names that honestly without claiming a specific module shape.
-const _dynImport = new Function('s', 'return import(s)');
-/** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
-export function isEmbeddingAvailable() {
-    if (_embeddingAvailable !== null)
-        return _embeddingAvailable;
-    try {
-        _require.resolve('@xenova/transformers');
-        _embeddingAvailable = true;
-        return true;
-    }
-    catch {
-        // fall through
-    }
-    try {
-        _require.resolve('@huggingface/transformers');
-        _embeddingAvailable = true;
-        return true;
-    }
-    catch {
-        // fall through
-    }
-    _embeddingAvailable = false;
-    return false;
-}
-// Importing both packages loads two incompatible onnxruntime-node builds whose finalizers can double-free on exit,
-// so pick one first: the maintained package hippo ships, with Xenova only as a fallback a user installed.
-function resolveTransformersPackage() {
-    try {
-        _require.resolve('@huggingface/transformers');
-        return '@huggingface/transformers';
-    }
-    catch {
-        // fall through
-    }
-    try {
-        _require.resolve('@xenova/transformers');
-        return '@xenova/transformers';
-    }
-    catch {
-        return null; // neither optional package is installed; callers fall back to no local embeddings
-    }
-}
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function loadPipeline(model) {
-    if (_pipelineInstances.has(model))
-        return _pipelineInstances.get(model);
-    if (_pipelineLoading.has(model))
-        return _pipelineLoading.get(model);
-    const loading = createPipeline(model);
-    _pipelineLoading.set(model, loading);
-    return loading;
-}
-/** The model's pipeline, or null with the reason recorded in `_pipelineErrors`. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function createPipeline(model) {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const pkg = resolveTransformersPackage();
-    if (!pkg) {
-        _pipelineErrors.set(model, 'no transformers package is installed');
-        return null;
-    }
-    const pipelineFn = await importPipelineFactory(pkg, model);
-    if (!pipelineFn)
-        return null;
-    // The offline bundle used in egress-blocked sandboxes ships only the FP32 model, so use whichever file is on disk.
-    const cacheRoot = envModelCache();
-    const quantized = !cacheRoot
-        || fs.existsSync(path.join(cacheRoot, model, 'onnx', 'model_quantized.onnx'));
-    try {
-        const instance = await pipelineFn('feature-extraction', model, { quantized });
-        _pipelineInstances.set(model, instance);
-        return instance;
-    }
-    catch (err) {
-        const reason = `embedding pipeline load failed (${model}): ${String(err)}`;
-        log.debug(reason);
-        _pipelineErrors.set(model, reason);
-        return null;
-    }
-    finally {
-        _pipelineLoading.delete(model);
-    }
-}
-/** The package's `pipeline` function, or null with the reason recorded in `_pipelineErrors`. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function importPipelineFactory(pkg, model) {
-    let pipelineFn = null;
-    try {
-        // SAFETY: the resolved module's shape is untyped by design (optional peer
-        // dependency); pipelineFn/mod.env are read defensively below and any
-        // failure to find a usable pipeline falls through to `return null`.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const mod = await _dynImport(pkg);
-        if (envModelCache()) {
-            if (mod.env) {
-                mod.env.cacheDir = envModelCache();
-                mod.env.localModelPath = envModelCache();
-                mod.env.allowRemoteModels = false;
-            }
-        }
-        pipelineFn = mod.pipeline ?? mod.default?.pipeline;
-    }
-    catch (err) {
-        // String(err) keeps a Node error's [ERR_...] code, which callers match on.
-        const reason = `transformers import failed (${pkg}): ${String(err)}`;
-        log.debug(reason);
-        _pipelineErrors.set(model, reason);
-        return null;
-    }
-    if (!pipelineFn) {
-        _pipelineErrors.set(model, `${pkg} exports no pipeline function`);
-        return null;
-    }
-    return pipelineFn;
-}
-/** Throws, with the reason, when the model's pipeline cannot load: a provider-level failure, not a per-item skip. */
-export async function requireLocalPipeline(model) {
-    if (await loadPipeline(model))
-        return;
-    throw new Error(`local embedding model did not load: ${_pipelineErrors.get(model) ?? 'unknown reason'}`);
-}
-export function resolveEmbeddingModel(hippoRoot, explicitModel) {
-    const direct = explicitModel?.trim();
-    if (direct)
-        return direct;
-    try {
-        const configured = loadConfig(hippoRoot).embeddings.model?.trim();
-        if (configured)
-            return configured;
-    }
-    catch {
-        // Fall back to the default model when config cannot be read.
-    }
-    return DEFAULT_EMBEDDING_MODEL;
-}
-/** Embeds `text` with the local model, or returns `[]` when Transformers.js is missing or fails; `role` adds e5-style prefixes. */
-export async function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL, role) {
-    if (!isEmbeddingAvailable())
-        return [];
-    try {
-        const pipe = await loadPipeline(model);
-        if (!pipe)
-            return [];
-        const prefix = prefixFor(model, role);
-        const input = prefix ? `${prefix}${text}` : text;
-        // SAFETY: pipe() is a Transformers.js feature-extraction pipeline call;
-        // its untyped output is read defensively below (only `.data`, cast on
-        // the return line to the documented Float32Array tensor shape).
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const output = await pipe(input, { pooling: poolingFor(model), normalize: true });
-        // SAFETY: output.data is a Float32Array per the feature-extraction
-        // pipeline's documented tensor output shape.
-        return Array.from(output.data);
-    }
-    catch (err) {
-        // The caller sees `[]` and names the memory; the reason only shows at debug.
-        log.debug(`local embedding failed: ${errorMessage(err)}`);
-        return [];
-    }
-}
-//# sourceMappingURL=local.js.map

package/dist/store/embeddings/provider.d.ts

@@ -1,77 +0,0 @@
-/**
- * Pluggable embedding providers for Hippo.
- *
- * The local `@huggingface/transformers` path stays the zero-DEPENDENCY DEFAULT. Opt-in
- * API providers (OpenAI / Voyage / Cohere) let a user bring a frontier embedder
- * (e.g. text-embedding-3-large) for frontier-class retrieval. They use the native
- * `fetch` global (Node >= 22.16, see package.json engines; NO new dependency) and
- * read their key from a conventional env var. The provider is selected by
- * `config.embeddings.provider` (default `'local'`).
- *
- * Design contract:
- *   - Local provider `id` is the BARE model string; the STORED identity adds a `#t<N>`
- *     embed-text-format suffix (`embeddingIndexIdentity`), so older stores reindex once:
- *     their vectors were computed over path-contaminated text.
- *   - API provider `id` is `${kind}:${model}`; switching to/from an API embedder
- *     (or a dimension change) flips the identity and triggers the existing
- *     reindex-on-change path.
- *   - `resolveEmbeddingProvider` throws on an invalid config (unknown provider,
- *     bad apiBaseUrl); `embedMemory` turns that into a warning. `isAvailable()` is provider-aware
- *     (local -> dependency installed; api -> key present). `embed()` MAY throw on
- *     a hard transport/auth failure so a reindex can abort atomically; hot paths
- *     wrap it and fall back to BM25.
- *
- * The exact request/response shapes for the API providers are documented from each
- * vendor's public embeddings API; they are unit-tested here against a mocked
- * `fetch` and are integration-verified in Workstream C (real API calls are
- * egress-blocked in the build sandbox).
- */
-import { type EmbeddingRole } from './local.js';
-export type EmbeddingProviderKind = 'local' | 'openai' | 'voyage' | 'cohere';
-export declare const API_PROVIDER_KINDS: readonly EmbeddingProviderKind[];
-export interface EmbeddingProvider {
-    readonly kind: EmbeddingProviderKind;
-    readonly model: string;
-    /**
-     * Identity recorded in DB meta to drive reindex-on-change.
-     * local -> bare model string (back-compat); api -> `${kind}:${model}`.
-     */
-    readonly id: string;
-    /** Known fixed output dimension, if any (undefined for local / unknown). */
-    readonly dimensions?: number;
-    /** Env var holding this provider's API key (undefined for the local provider). */
-    readonly keyEnv?: string;
-    /** local -> dependency installed; api -> key present. NEVER throws. */
-    isAvailable(): boolean;
-    /**
-     * Batch-embed. Returns one row per input in order; a row is `[]` when that
-     * single item could not be embedded. MAY throw on a hard transport/auth
-     * failure (so a reindex aborts before saving a partial index).
-     */
-    embed(texts: string[], role?: EmbeddingRole): Promise<number[][]>;
-}
-export interface ResolveProviderOptions {
-    /** Explicit model override (mirrors resolveEmbeddingModel's explicitModel). */
-    model?: string;
-    /** Explicit provider override (mainly for tests). */
-    provider?: EmbeddingProviderKind;
-}
-/**
- * Build the active embedding provider from config (or an explicit override).
- * Never throws for a missing key — that surfaces via `isAvailable()` on the hot
- * paths and as a hard error only from the explicit `hippo embed` command. The
- * only hard throw is an invalid config (e.g. an insecure apiBaseUrl), a
- * deliberate loud failure; hot-path callers (search) wrap this in try/catch.
- */
-export declare function resolveEmbeddingProvider(hippoRoot: string, opts?: ResolveProviderOptions): EmbeddingProvider;
-/**
- * The reindex identity for the active provider. Use this (NOT resolveEmbeddingModel)
- * everywhere `embeddingModelRequiresReindex` / stored-model comparisons happen.
- */
-export declare function resolveEmbeddingIdentity(hippoRoot: string, opts?: ResolveProviderOptions): string;
-/**
- * Provider-aware availability for a store: local -> dependency installed;
- * api -> key present. Use at the call sites that decide whether to embed.
- */
-export declare function isEmbeddingConfigured(hippoRoot: string): boolean;
-//# sourceMappingURL=provider.d.ts.map

package/dist/store/markdown.d.ts

@@ -1,10 +0,0 @@
-import { type MemoryEntry } from '../core/memory.js';
-/**
- * Serialize a MemoryEntry to markdown with YAML frontmatter.
- */
-export declare function serializeEntry(entry: MemoryEntry): string;
-/**
- * Deserialize a markdown file to a MemoryEntry.
- */
-export declare function deserializeEntry(raw: string): MemoryEntry | null;
-//# sourceMappingURL=markdown.d.ts.map

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

@@ -1,138 +0,0 @@
-/**
- * Recall-side scope predicates, in a leaf module so shared.ts (which api.ts
- * imports) can apply the same default-deny rule to searchBothHybrid's internal
- * candidate loads without an import cycle. api.ts imports
- * these for its own call sites AND re-exports them for back-compat
- * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
- */
-import { ForbiddenError } from '../core/api-errors.js';
-/**
- * Literal scopes excluded from recall by default-deny when the
- * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
- * helper `passesScopeFilterForRecall` (src/api/index.ts) both read from this
- * constant. Adding a deny scope is a one-place change.
- *
- * Regex-based denies (e.g. `<source>:private:*`) stay in
- * `passesScopeFilterForRecall` as a separate JS step — they don't translate
- * cleanly to SQL.
- *
- * Invariant: never empty. An empty array would silently allow quarantine
- * scopes through both paths (SQL clause omitted, JS check vacuous). The
- * module-load assertion below pins this loudly.
- */
-export declare const RECALL_DEFAULT_DENY_SCOPES: readonly ["unknown:legacy"];
-/**
- * @internal Runtime guard against a future maintainer blanking a
- * load-bearing literal array. Extracted from the inline guard so the throw
- * path is directly testable. `as const` arrays widen via `readonly T[]` at
- * the call site so the empty case is reachable at runtime.
- */
-export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void;
-/**
- * Source-agnostic private-scope detector. A scope string is treated
- * as private when it has the shape `<lowercase-source>:private:<rest>`.
- *
- * Examples that match:
- *   slack:private:Cabc, github:private:owner/repo, jira:private:PROJ-1
- * Examples that DO NOT match:
- *   slack:public:Cgeneral, acme:public:my-private-channel, null, '',
- *   'unknown:legacy', 'private' (alone), 'private:foo' (no source prefix).
- *
- * Used by api.recall, mcp/server.ts (hippo_recall + hippo_context),
- * cli.ts (cmdRecall + cmdExplain + continuity), shared.ts (searchBothHybrid
- * recall mode). Keep these in sync — the export is the single source of
- * truth 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;
-export declare const PERSONAL_SCOPE_PREFIX = "personal:private:";
-export declare const PERSONAL_OWNER_MAX: number;
-/** True for a `personal:private:<owner>` scope, any case, so a case variant is never mistaken for a team scope. */
-export declare function isPersonalScope(scope: string | null | undefined): boolean;
-/** The caller's own personal scope, or null when it has no owner that can hold one. */
-export declare function personalScopeOf(actor: {
-    owner?: string;
-} | undefined): string | null;
-/** Refuses a client-sent `personal:` scope: only the server stamps one, from the caller's owner. */
-export declare function assertClientScope(scope: string | null | undefined): void;
-/** True when `actor` may change or delete a row in `scope`: any non-personal scope, or its own personal one. */
-export declare function canTouchScope(actor: {
-    owner?: string;
-}, scope: string | null): boolean;
-/** 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;
-/**
- * Recall-side scope filter — the canonical JS half of the recall default-deny
- * rule (the SQL half lives in `loadSearchRows` via `loadRecallSearchEntries`).
- *
- * - When `requested` is set and non-empty: exact match required.
- * - When `requested` is undefined/empty: default-deny on any
- *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
- *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
- */
-export declare function passesScopeFilterForRecall(scope: string | null, requested: string | undefined, ownScope?: string | null): boolean;
-export interface SqlFragment {
-    sql: string;
-    params: string[];
-}
-/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
-export declare function scopeAdmitSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
-/** SQL twin of canTouchScope, which is also canReadScope for an admin: every row but another person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
-export declare function touchableScopeSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
-/**
- * The CLI `--scope` variant of the recall filter (JS half of the
- * SQL 'default-deny-or-exact' mode in loadSearchRows).
- *
- * The CLI flag predates the envelope column as a TAG-boost ranking hint
- * (`scope:<v>` tags, HIPPO_SCOPE, detectScope()), so an explicit `--scope X`
- * UNLOCKS envelope scope X in addition to the default-admitted set — it does
- * NOT narrow the result to X (that would return zero rows for every
- * tag-scoped workflow, whose envelope scope is NULL). api.recall keeps the
- * narrowing 'exact' semantics via `passesScopeFilterForRecall`.
- *
- * Note the unlock applies to whatever scope was explicitly named — including
- * a private scope or a quarantine bucket (`--scope unknown:legacy`). That is
- * deliberate owner access, identical in reach to api.recall's exact-match
- * for the same input; only NON-requested private/quarantine scopes stay
- * denied. A named personal scope never unlocks: the CLI has no caller identity to check it against.
- */
-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 that default-deny hides: `<source>:private:*` and the
- * quarantine buckets. Naming one explicitly is what unlocks it, so naming one
- * is the act that 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. */
-export interface ScopeActor {
-    role: 'admin' | 'member';
-    scopes?: readonly string[];
-    owner?: string;
-}
-/** 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. */
-export declare function canReadScope(actor: ScopeActor, scope: string): boolean;
-/** Authorize an explicitly requested scope before any read honours it (member scope grants). */
-export declare function assertScopeRequestAllowed(actor: ScopeActor, requested: string | undefined): void;
-/** Scope a derived row keeps from one source: the restricted scope itself, else null. */
-export declare function derivationScope(scope: string | null | undefined): string | null;
-/** The one derivation scope shared by every source, or `{ ok: false }` when
- *  two disagree, so the caller skips the derived row instead of under-scoping it. */
-export declare function commonDerivationScope(scopes: readonly (string | null | undefined)[]): {
-    ok: true;
-    scope: string | null;
-} | {
-    ok: false;
-};
-/** 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 declare function derivationPartitionKey(tenantId: string, scope: string | null | undefined, origin: string | null | undefined): string;
-//# sourceMappingURL=recall-scope.d.ts.map

package/dist/store/recall-scope.js

@@ -1,216 +0,0 @@
-/**
- * Recall-side scope predicates, in a leaf module so shared.ts (which api.ts
- * imports) can apply the same default-deny rule to searchBothHybrid's internal
- * candidate loads without an import cycle. api.ts imports
- * these for its own call sites AND re-exports them for back-compat
- * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
- */
-import { BadRequestError, ForbiddenError } from '../core/api-errors.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
-/**
- * Literal scopes excluded from recall by default-deny when the
- * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
- * helper `passesScopeFilterForRecall` (src/api/index.ts) both read from this
- * constant. Adding a deny scope is a one-place change.
- *
- * Regex-based denies (e.g. `<source>:private:*`) stay in
- * `passesScopeFilterForRecall` as a separate JS step — they don't translate
- * cleanly to SQL.
- *
- * Invariant: never empty. An empty array would silently allow quarantine
- * scopes through both paths (SQL clause omitted, JS check vacuous). The
- * module-load assertion below pins this loudly.
- */
-export const RECALL_DEFAULT_DENY_SCOPES = ['unknown:legacy'];
-/**
- * @internal Runtime guard against a future maintainer blanking a
- * load-bearing literal array. Extracted from the inline guard so the throw
- * path is directly testable. `as const` arrays widen via `readonly T[]` at
- * the call site so the empty case is reachable at runtime.
- */
-export function assertNonEmpty(arr, name) {
-    if (arr.length === 0) {
-        throw new Error(`${name} cannot be empty — would silently allow quarantine scopes`);
-    }
-}
-assertNonEmpty(RECALL_DEFAULT_DENY_SCOPES, 'RECALL_DEFAULT_DENY_SCOPES');
-/**
- * Source-agnostic private-scope detector. A scope string is treated
- * as private when it has the shape `<lowercase-source>:private:<rest>`.
- *
- * Examples that match:
- *   slack:private:Cabc, github:private:owner/repo, jira:private:PROJ-1
- * Examples that DO NOT match:
- *   slack:public:Cgeneral, acme:public:my-private-channel, null, '',
- *   'unknown:legacy', 'private' (alone), 'private:foo' (no source prefix).
- *
- * Used by api.recall, mcp/server.ts (hippo_recall + hippo_context),
- * cli.ts (cmdRecall + cmdExplain + continuity), shared.ts (searchBothHybrid
- * recall mode). Keep these in sync — the export is the single source of
- * truth so connector work cannot drift.
- */
-export const PRIVATE_SCOPE_RE = /^[a-z][a-z0-9_-]*:private:/;
-function isScopeString(value) {
-    return typeof value === 'string';
-}
-/** True when `scope` matches the `<source>:private:*` shape. */
-export function isPrivateScope(scope) {
-    if (!isScopeString(scope))
-        return false;
-    return PRIVATE_SCOPE_RE.test(scope);
-}
-export const PERSONAL_SCOPE_PREFIX = 'personal:private:';
-// The scope must fit the 256-character scope caps, so the owner gets what the prefix leaves.
-export const PERSONAL_OWNER_MAX = MAX_ID_LEN - PERSONAL_SCOPE_PREFIX.length;
-/** True for a `personal:private:<owner>` scope, any case, so a case variant is never mistaken for a team scope. */
-export function isPersonalScope(scope) {
-    if (!isScopeString(scope))
-        return false;
-    return /^personal:private:/i.test(scope);
-}
-/** The caller's own personal scope, or null when it has no owner that can hold one. */
-export function personalScopeOf(actor) {
-    const owner = actor?.owner;
-    if (!owner || owner.length > PERSONAL_OWNER_MAX || /\p{Cc}/u.test(owner))
-        return null;
-    return `${PERSONAL_SCOPE_PREFIX}${owner}`;
-}
-/** Refuses a client-sent `personal:` scope: only the server stamps one, from the caller's owner. */
-export function assertClientScope(scope) {
-    if (isScopeString(scope) && /^personal:/i.test(scope)) {
-        throw new BadRequestError(`scope ${scope} is reserved: the server sets personal scopes itself`);
-    }
-}
-/** True when `actor` may change or delete a row in `scope`: any non-personal scope, or its own personal one. */
-export function canTouchScope(actor, scope) {
-    return ownScopeTouches(personalScopeOf(actor), scope);
-}
-/** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
-export function ownScopeTouches(ownScope, scope) {
-    return !isPersonalScope(scope) || scope === ownScope;
-}
-/**
- * Recall-side scope filter — the canonical JS half of the recall default-deny
- * rule (the SQL half lives in `loadSearchRows` via `loadRecallSearchEntries`).
- *
- * - When `requested` is set and non-empty: exact match required.
- * - When `requested` is undefined/empty: default-deny on any
- *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
- *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
- */
-export function passesScopeFilterForRecall(scope, requested, ownScope) {
-    if (requested !== undefined && requested !== '') {
-        return scope === requested;
-    }
-    return !isRestrictedScope(scope) || (ownScope != null && scope === ownScope);
-}
-/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
-export function scopeAdmitSql(col, ownScope) {
-    const placeholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
-    const admitted = `${col}scope IS NULL OR (${col}scope NOT IN (${placeholders}) AND ${col}scope NOT LIKE '%:private:%')`;
-    if (ownScope == null)
-        return { sql: `(${admitted})`, params: [...RECALL_DEFAULT_DENY_SCOPES] };
-    // The own arm sits inside the outer parentheses so a caller's `AND ${sql}` cannot split it off.
-    return { sql: `(${admitted} OR ${col}scope = ?)`, params: [...RECALL_DEFAULT_DENY_SCOPES, ownScope] };
-}
-/** SQL twin of canTouchScope, which is also canReadScope for an admin: every row but another person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
-export function touchableScopeSql(col, ownScope) {
-    const notPersonal = `${col}scope IS NULL OR ${col}scope NOT LIKE '${PERSONAL_SCOPE_PREFIX}%'`;
-    if (ownScope == null)
-        return { sql: `(${notPersonal})`, params: [] };
-    return { sql: `(${notPersonal} OR ${col}scope = ?)`, params: [ownScope] };
-}
-/**
- * The CLI `--scope` variant of the recall filter (JS half of the
- * SQL 'default-deny-or-exact' mode in loadSearchRows).
- *
- * The CLI flag predates the envelope column as a TAG-boost ranking hint
- * (`scope:<v>` tags, HIPPO_SCOPE, detectScope()), so an explicit `--scope X`
- * UNLOCKS envelope scope X in addition to the default-admitted set — it does
- * NOT narrow the result to X (that would return zero rows for every
- * tag-scoped workflow, whose envelope scope is NULL). api.recall keeps the
- * narrowing 'exact' semantics via `passesScopeFilterForRecall`.
- *
- * Note the unlock applies to whatever scope was explicitly named — including
- * a private scope or a quarantine bucket (`--scope unknown:legacy`). That is
- * deliberate owner access, identical in reach to api.recall's exact-match
- * for the same input; only NON-requested private/quarantine scopes stay
- * denied. A named personal scope never unlocks: the CLI has no caller identity to check it against.
- */
-export function passesCliRecallScopeFilter(scope, requested) {
-    if (requested !== undefined && requested !== '' && !isPersonalScope(requested) && scope === requested) {
-        return true;
-    }
-    return passesScopeFilterForRecall(scope, undefined);
-}
-/**
- * Thrown when a caller requests a scope its role may not read. The HTTP layer
- * maps it to 403.
- */
-export class ScopeForbiddenError extends ForbiddenError {
-    scope;
-    constructor(scope) {
-        super(`scope ${scope} requires admin role`);
-        this.name = 'ScopeForbiddenError';
-        this.scope = scope;
-    }
-}
-/**
- * True for scopes that default-deny hides: `<source>:private:*` and the
- * quarantine buckets. Naming one explicitly is what unlocks it, so naming one
- * is the act that 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 (not the input) lets .includes() take any scope.
-    // `:private:` anywhere, any case, matches the store's SQL default-deny (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. */
-export function canReadScope(actor, scope) {
-    if (isPersonalScope(scope))
-        return scope === personalScopeOf(actor);
-    if (actor.role === 'admin')
-        return true;
-    if (!isRestrictedScope(scope))
-        return true;
-    return (actor.scopes ?? []).includes(scope);
-}
-/** Authorize an explicitly requested scope before any read honours it (member scope grants). */
-export function assertScopeRequestAllowed(actor, requested) {
-    if (requested === undefined || requested === '')
-        return;
-    if (canReadScope(actor, requested))
-        return;
-    throw new ScopeForbiddenError(requested);
-}
-/** Scope a derived row keeps from one source: the restricted scope itself, else null. */
-export function derivationScope(scope) {
-    return isRestrictedScope(scope) ? (scope ?? null) : null;
-}
-/** The one derivation scope shared by every source, or `{ ok: false }` when
- *  two disagree, so the caller skips the derived row instead of under-scoping it. */
-export function commonDerivationScope(scopes) {
-    let common = null;
-    let seen = false;
-    for (const raw of scopes) {
-        const scope = derivationScope(raw);
-        if (!seen) {
-            common = scope;
-            seen = true;
-        }
-        else if (scope !== common) {
-            return { ok: false };
-        }
-    }
-    return { ok: true, scope: common };
-}
-/** 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
-    return `${tenantId}\u0000${derivationScope(scope) ?? ''}\u0000${project}`;
-}
-//# sourceMappingURL=recall-scope.js.map

package/dist/store/vector-writes.d.ts

@@ -1,13 +0,0 @@
-import { type DatabaseSyncLike } from '../db/index.js';
-import type { MemoryEntry } from '../core/memory.js';
-import type { PhysicsParticle } from '../core/physics.js';
-import type { VectorBackfillQuery, VectorWrite, VectorWriteResult } from './port.js';
-export declare function entriesWithoutVectorAt(db: DatabaseSyncLike, query: VectorBackfillQuery): MemoryEntry[];
-export declare function writeVectorsAt(db: DatabaseSyncLike, write: VectorWrite): VectorWriteResult;
-/** Every particle stored under `hippoRoot`. */
-export declare function loadStoredParticles(hippoRoot: string): PhysicsParticle[];
-/** Writes `particles` over their stored state under `hippoRoot`, as one batch. */
-export declare function saveStoredParticles(hippoRoot: string, particles: PhysicsParticle[]): void;
-/** Replaces every particle under `hippoRoot` with a fresh one per entry that has an embedding; returns how many. */
-export declare function resetStoredParticles(hippoRoot: string, entries: MemoryEntry[], embeddingIndex: Record<string, number[]>): number;
-//# sourceMappingURL=vector-writes.d.ts.map