hippo-memory 1.70.0 → 1.71.0

package/dist/api/context-types.d.ts

@@ -4,17 +4,8 @@ import type { MemoryEntry } from '../core/memory.js';
 import type { DeliveryObserver } from '../store/delivery-recorder.js';
 import type { AmbientState } from '../core/ambient.js';
 import type { ProjectRef } from '../core/project-identity.js';
-/**
- * Options for `getContext` — assemble a budget-bounded context bundle
- * (recalled memories + active task snapshot + handoff + recent events).
- *
- * Named `getContext` (not `context`) to avoid collision with the `Context`
- * interface above and the ubiquitous `ctx: Context` convention. Follows the
- * existing `getEntry` naming pattern in store.ts.
- *
- * Rendering opts (`format`, `framing`, `rendered`) and host-side opts (`auto`) stay in the CLI,
- * because its print helpers are shared with `cmdRecall` / `cmdSnapshot` / `cmdHandoffShow`.
- */
+/** Options for `getContext`: a budget-bounded bundle of recalled memories, active task snapshot, handoff and recent events.
+ * Rendering opts (`format`, `framing`, `rendered`) and host-side opts (`auto`) stay in the CLI, whose print helpers are shared. */
 export interface ContextOpts {
     q?: string;
     /** Default 1500 tokens. */
@@ -24,30 +15,16 @@ export interface ContextOpts {
     scope?: string;
     /** Envelope scope to match exactly, as in `recall`: admits that scope even when private, after the actor's scope check. */
     exactScope?: string;
-    /** With `pinnedOnly`, also inject the N most recent writes that pass the
-     *  quality floor (`isWorthSurfacing`). Filtering happens BEFORE
-     *  the take-N, so a caller asking for 5 gets 5 qualifying entries rather
-     *  than 5-minus-junk; pinned entries bypass the floor. Entries are only
-     *  skipped for this read, never mutated or deleted. Ignored when
-     *  `pinnedOnly` is false — no other path reads it. */
+    /** With `pinnedOnly`, also inject the N most recent writes that pass the quality floor (`isWorthSurfacing`); pinned entries bypass it.
+     *  Filtering happens BEFORE the take-N, so asking for 5 gets 5 qualifying entries. Ignored when `pinnedOnly` is false. */
     includeRecent?: number;
-    /** v39 memory scope isolation: re-include other-project memories that the
-     *  origin partition excludes by default. They come back tagged
-     *  `category: 'cross-project'` so renderers can demarcate them. */
+    /** Re-include other-project memories the origin partition excludes by default; they come back tagged `category: 'cross-project'`. */
     crossProject?: boolean;
-    /** The active project for the origin partition ('' = not in a project): a
-     *  name, or an identity whose rows may also carry its legacy folder name.
-     *  Defaults to `resolveProjectIdentity(process.cwd())`; surfaces whose
-     *  process cwd is not the caller's project (HTTP server) should pass it. */
+    /** The active project for the origin partition ('' = not in a project): a name, or an identity whose rows may carry its legacy folder name.
+     *  Defaults to `resolveProjectIdentity(process.cwd())`; surfaces whose cwd is not the caller's project (HTTP server) should pass it. */
     currentProject?: ProjectRef;
-    /** The calling
-     *  session's id. Stamped on this call's recall trace, and the owner-match input to
-     *  `loadFreshActiveTaskSnapshot` — when it strictly equals the active
-     *  snapshot's `session_id`, the read is unbounded (same-session
-     *  continuity); otherwise the snapshot must pass the freshness bound to
-     *  surface. Absent (undefined/null/'') never short-circuits as a match;
-     *  it just means every snapshot goes through the age check. Host-resolved
-     *  (stdin payload, HIPPO_SESSION_ID, else the host's session var) so this stays host-agnostic. */
+    /** The calling session's id, stamped on this call's recall trace. When it strictly equals the active snapshot's `session_id` the read is unbounded;
+     *  otherwise the snapshot must pass the freshness bound. Absent (undefined/null/'') never matches. Host-resolved, so this stays host-agnostic. */
     currentSessionId?: string | null;
     /** Raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
     prompt?: string;
@@ -83,9 +60,7 @@ export interface ContextResultEntry {
     promptRecall?: boolean;
     /** v39: the entry's owning project ('' = user-global, null = legacy row). */
     origin?: string | null;
-    /** v39: how the origin relates to the active project. 'cross-project'
-     *  entries only appear when ContextOpts.crossProject was set (or isolation
-     *  is disabled). */
+    /** How the origin relates to the active project; 'cross-project' appears only when `crossProject` was set (or isolation is disabled). */
     category?: 'project' | 'user-global' | 'cross-project';
 }
 export interface ContextResult {

package/dist/api/context.d.ts

@@ -3,28 +3,11 @@ import { type ProjectRef } from '../core/project-identity.js';
 import type { ContextOpts, ContextResult } from './context-types.js';
 import { type Context } from './types.js';
 export { oneCopyPerMemory } from './context-select.js';
-/**
- * The secret half of the ambient policy on its own, for callers
- * that apply their own scope rule. A flagged row is only admitted inside its owning project;
- * flagged rows with no project origin never ambient-inject.
- */
+/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only inside its owning project. */
 export declare function ambientSecretAdmit(e: MemoryEntry, currentProject: ProjectRef): boolean;
-/**
- * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
- * fallback / hybrid search) + active task snapshot + session handoff + recent
- * session events. Budget-bounded, tenant-scoped. Mutates `last_retrieval_ids`
- * + emits a 'recall' audit row for non-pinned, non-'*' queries.
- *
- * Behaves like the pre-extraction `cmdContext` data-loading + selection
- * pipeline. CLI presentation (markdown / json / additional-context rendering)
- * stays in `cli.ts`.
- *
- * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
- * `ctx.tenantId`. Cross-tenant rows are filtered out.
- *
- * @returns An empty result (`entries: []`, snapshot/handoff/events undefined)
- * when there's nothing to surface (no memories AND no snapshot AND no handoff
- * AND no recent events).
- */
+/** Tokens a context block may use when the caller sets no budget; the hook command and the CLI default match it. */
+export declare const DEFAULT_CONTEXT_BUDGET = 1500;
+/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit row for non-pinned, non-'*' queries.
+ * Returns an empty result when there are no memories, snapshot, handoff or recent events. CLI rendering stays in `cli.ts`. */
 export declare function getContext(ctx: Context, opts?: ContextOpts): Promise<ContextResult>;
 //# sourceMappingURL=context.d.ts.map

package/dist/api/context.js

@@ -5,7 +5,7 @@ import { freshActiveSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessi
 import { estimateTokens } from '../util/token-text.js';
 import { markRetrieved, COMPACTION_MEMORY_TAG } from '../core/memory.js';
 import { isWorthSurfacing } from '../core/memory-quality.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import { evalNow } from '../core/ablation.js';
 import { dropHeldCopies } from '../util/same-text.js';
 import { BadRequestError } from '../core/api-errors.js';
@@ -24,19 +24,8 @@ import { andThen, onStore } from './on-store.js';
 import { strengthenOf } from './recall-record.js';
 import { ownerOrSubject } from './types.js';
 export { oneCopyPerMemory } from './context-select.js';
-/**
- * v39: the single ambient-injection admission policy, shared by getContext
- * and the CLI-side ambient-state summary so the two cannot drift.
- *
- * - Secret veto is UNCONDITIONAL: neither crossProject nor
- *   contextProjectIsolation:false re-includes secrets. A flagged row only
- *   injects inside its owning project; flagged rows with no project origin
- *   (''/null) never ambient-inject at all. Explicit recall is unaffected -
- *   recalling a secret is a deliberate act.
- * - Envelope parity: private/quarantine scopes never inject unless `exactScope` names one.
- * - Origin partition: other-project rows are excluded unless
- *   `includeCrossProject`.
- */
+/** The single ambient-injection admission policy, shared by getContext and the CLI ambient-state summary so they cannot drift.
+ * Secret veto is unconditional (flagged rows inject only in their own project); private scopes need `exactScope`, other projects `includeCrossProject`. */
 function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, own) {
     if (!ambientSecretAdmit(e, currentProject))
         return false;
@@ -46,11 +35,7 @@ function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, o
         return true;
     return classifyOriginProject(e.origin_project, currentProject) !== 'cross-project';
 }
-/**
- * The secret half of the ambient policy on its own, for callers
- * that apply their own scope rule. A flagged row is only admitted inside its owning project;
- * flagged rows with no project origin never ambient-inject.
- */
+/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only inside its owning project. */
 export function ambientSecretAdmit(e, currentProject) {
     if (!detectSecret(e).flagged)
         return true;
@@ -59,6 +44,8 @@ export function ambientSecretAdmit(e, currentProject) {
         return false;
     return projectNames(currentProject).includes(origin);
 }
+/** Tokens a context block may use when the caller sets no budget; the hook command and the CLI default match it. */
+export const DEFAULT_CONTEXT_BUDGET = 1500;
 /** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
 const CONTEXT_CANDIDATE_CAP = 2000;
 /** A store's base search and context reads; a store without the group throws StoreNotPortedError. */
@@ -98,25 +85,10 @@ async function loadAmbientEntries(source, tenantId, options) {
     const entries = loaded.entries.filter((e) => ownTenant(e) && recheck(e));
     return loaded.recall ? { entries, recall: loaded.recall.filter(ownTenant) } : { entries };
 }
-/**
- * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
- * fallback / hybrid search) + active task snapshot + session handoff + recent
- * session events. Budget-bounded, tenant-scoped. Mutates `last_retrieval_ids`
- * + emits a 'recall' audit row for non-pinned, non-'*' queries.
- *
- * Behaves like the pre-extraction `cmdContext` data-loading + selection
- * pipeline. CLI presentation (markdown / json / additional-context rendering)
- * stays in `cli.ts`.
- *
- * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
- * `ctx.tenantId`. Cross-tenant rows are filtered out.
- *
- * @returns An empty result (`entries: []`, snapshot/handoff/events undefined)
- * when there's nothing to surface (no memories AND no snapshot AND no handoff
- * AND no recent events).
- */
+/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit row for non-pinned, non-'*' queries.
+ * Returns an empty result when there are no memories, snapshot, handoff or recent events. CLI rendering stays in `cli.ts`. */
 export async function getContext(ctx, opts = {}) {
-    const budget = opts.budget ?? 1500;
+    const budget = opts.budget ?? DEFAULT_CONTEXT_BUDGET;
     assertScopeRequestAllowed(ctx.actor, opts.exactScope);
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
@@ -247,6 +219,8 @@ function openBlockBudget(plan, opts, budget) {
     obs?.facts({ projectName: projectId(plan.currentProject), budgetTokens: blockBudget, promptRecall: promptRecallPending });
     if (pinnedOnly && !config.pinnedInject.enabled)
         obs?.disabled();
+    if (!pinnedOnly)
+        obs?.queried(plan.query);
     return cost
         ? Math.max(0, blockBudget - cost.fixed(blockBudget, { cross: plan.includeCrossProject, promptRecall: promptRecallPending, ambient: !pinnedOnly && config.ambient.enabled }))
         : blockBudget;
@@ -348,6 +322,12 @@ async function loadPools(ctx, plan, admission, recallRequest) {
 /** The `limit` cut, then the held-copy drop, then each entry's origin annotation. */
 function finalizeSelection(picked, plan) {
     const { obs } = plan;
+    // Ranking reports nothing itself, so its results are offered here and the cuts below can name what they drop.
+    if (!plan.pinnedOnly && obs) {
+        const pool = plan.query === '*' ? 'strength' : 'search';
+        obs.offer(picked.filter((r) => r.isGlobal !== true).map((r) => r.entry), false, pool);
+        obs.offer(picked.filter((r) => r.isGlobal === true).map((r) => r.entry), true, pool);
+    }
     let selected = picked;
     if (plan.limit < selected.length) {
         const cut = selected.slice(0, plan.limit);
@@ -405,7 +385,10 @@ async function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
     };
     const writes = { goalLog: [], audit: [], trace, strengthen: strengthenOf(ctx, retrievedIds) };
     // hippo.db keeps the ids as its last recall, which feeds only outcomeForLastRecall, and it alone reads a second root.
-    await onStore(ctx, (port, local) => andThen(local.finishLastRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined), () => port.bumpRecallStats(selected.length)));
+    await onStore(ctx, (port, local) => andThen(local.finishLastRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined), (traceId) => {
+        plan.obs?.traced(traceId);
+        return port.bumpRecallStats(selected.length);
+    }));
     // Replace selectedItems entries with markRetrieved-updated copies so
     // the returned ContextResult reflects post-recall state.
     const items = selected.map((s) => ({

package/dist/api/dormant.d.ts

@@ -1,29 +1,13 @@
 import { type DormantMemory, type ListDormantOpts } from '../store/dormant.js';
 import { type MemoryEntry } from '../core/memory.js';
 import type { Context } from './types.js';
-/**
- * A tenant's dormant memories (src/store/dormant.ts): what sleep moved out of
- * active memory instead of deleting, when `dormant.enabled` is on. Newest
- * first; `opts.query` keeps rows containing every term (case-insensitive).
- */
+/** A tenant's dormant memories (src/store/dormant.ts): what sleep moved out of active memory when `dormant.enabled` is on. Newest first;
+ * `opts.query` keeps rows containing every term (case-insensitive). */
 export declare function listDormant(ctx: Context, opts?: ListDormantOpts): DormantMemory[];
-/**
- * Bring a dormant memory back into active memory. It returns as if just
- * recalled, with a full half-life. A row audit repair set aside returns
- * `verified`, so no quality check judges it again. Every other field is the
- * snapshot taken when it went dormant.
- *
- * Throws when the tenant has no dormant memory with that id (another
- * tenant's id, or another person's personal row, reads the same way), when a live memory already holds the id,
- * and RejectedValueError when the value has been rejected since. On any
- * throw the dormant copy stays where it is.
- */
+/** Restores a dormant memory as if just recalled, with a full half-life; a row set aside by audit repair returns `verified`.
+ * Throws if the tenant has no such dormant id or a live memory holds it, and RejectedValueError if the value was since rejected (the dormant copy stays). */
 export declare function restoreDormant(ctx: Context, id: string): MemoryEntry;
-/**
- * Permanently delete a dormant memory: the explicit "forget it for good"
- * that dormant storage leaves to the user. Throws when the tenant has no
- * dormant memory with that id.
- */
+/** Permanently deletes a dormant memory, the explicit "forget it for good"; throws when the tenant has no dormant memory with that id. */
 export declare function forgetDormant(ctx: Context, id: string): void;
 /** Whether the tenant holds a dormant memory with this id that the caller may touch (for "not found" hints). */
 export declare function isDormant(ctx: Context, id: string): boolean;

package/dist/api/dormant.js

@@ -7,25 +7,13 @@ import { createMemory, calculateStrength } from '../core/memory.js';
 import { loadConfig } from '../core/config.js';
 import { canTouchScope, personalScopeOf, touchableScopeSql } from '../store/recall-scope.js';
 const touchable = (ctx) => touchableScopeSql('', personalScopeOf(ctx.actor));
-/**
- * A tenant's dormant memories (src/store/dormant.ts): what sleep moved out of
- * active memory instead of deleting, when `dormant.enabled` is on. Newest
- * first; `opts.query` keeps rows containing every term (case-insensitive).
- */
+/** A tenant's dormant memories (src/store/dormant.ts): what sleep moved out of active memory when `dormant.enabled` is on. Newest first;
+ * `opts.query` keeps rows containing every term (case-insensitive). */
 export function listDormant(ctx, opts = {}) {
     return loadDormantMemories(ctx.hippoRoot, ctx.tenantId, opts, touchable(ctx));
 }
-/**
- * Bring a dormant memory back into active memory. It returns as if just
- * recalled, with a full half-life. A row audit repair set aside returns
- * `verified`, so no quality check judges it again. Every other field is the
- * snapshot taken when it went dormant.
- *
- * Throws when the tenant has no dormant memory with that id (another
- * tenant's id, or another person's personal row, reads the same way), when a live memory already holds the id,
- * and RejectedValueError when the value has been rejected since. On any
- * throw the dormant copy stays where it is.
- */
+/** Restores a dormant memory as if just recalled, with a full half-life; a row set aside by audit repair returns `verified`.
+ * Throws if the tenant has no such dormant id or a live memory holds it, and RejectedValueError if the value was since rejected (the dormant copy stays). */
 export function restoreDormant(ctx, id) {
     const outcome = restoreDormantMemory(ctx.hippoRoot, {
         tenantId: ctx.tenantId,
@@ -42,11 +30,8 @@ export function restoreDormant(ctx, id) {
     return outcome.entry;
 }
 function reviveSnapshot(ctx, dormant, now) {
-    // Dormant rows are long-lived, so a snapshot can predate a field added
-    // later: createMemory supplies a default for anything it lacks, then
-    // the snapshot overrides every field it does carry, content included.
-    // (The placeholder only satisfies createMemory's minimum length, so a
-    // legacy row shorter than 3 chars can still be restored.)
+    // A snapshot can predate a field added later: createMemory supplies defaults, then the snapshot overrides every field it carries.
+    // The placeholder content only meets createMemory's minimum length, so a legacy row under 3 chars still restores.
     const revived = {
         ...createMemory('dormant snapshot defaults', { baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays }),
         ...dormant.entry,
@@ -56,11 +41,7 @@ function reviveSnapshot(ctx, dormant, now) {
         revived.confidence = 'verified';
     return stampOriginProject(ctx.hippoRoot, { ...revived, strength: calculateStrength(revived, now) });
 }
-/**
- * Permanently delete a dormant memory: the explicit "forget it for good"
- * that dormant storage leaves to the user. Throws when the tenant has no
- * dormant memory with that id.
- */
+/** Permanently deletes a dormant memory, the explicit "forget it for good"; throws when the tenant has no dormant memory with that id. */
 export function forgetDormant(ctx, id) {
     const forgotten = forgetDormantMemory(ctx.hippoRoot, { tenantId: ctx.tenantId, id, actor: ctx.actor.subject, admit: touchable(ctx) });
     if (!forgotten)

package/dist/api/drill-down.d.ts

@@ -3,21 +3,10 @@ import type { Context } from './types.js';
 export interface DrillDownOpts {
     /** Cap on number of children returned. Default 50. */
     limit?: number;
-    /**
-     * Optional token budget. When set, children are appended in chronological
-     * order (created ASC) until adding the next child would exceed the budget.
-     * Token cost = the child's printed line under `cost`, else ceil(content.length / 4).
-     *
-     * For depth > 1, the budget is GLOBAL cumulative (NOT per-level).
-     */
+    /** Token budget: children append in created order until the next would exceed it (cost: printed line under `cost`, else ceil(content.length / 4)).
+     * For depth > 1 the budget is global and cumulative, not per level. */
     budget?: number;
-    /**
-     * v0.30 / E5 — walk N levels down (default 1 = direct children only).
-     * Higher values include children of children, etc. Internal hard cap 10
-     * to prevent pathological depth walks. BFS uses visited Set for dedup
-     * (defensive against shared-child data anomalies; DAG is acyclic by
-     * construction).
-     */
+    /** Levels to walk down (default 1 = direct children); capped at 10 internally. BFS dedups with a visited Set, defensive against shared-child anomalies. */
     depth?: number;
     cost?: DrillDownCost;
     project?: CallerProject;
@@ -46,41 +35,13 @@ export interface DrillDownResult {
     totalChildren: number;
     truncated: boolean;
 }
-/**
- * v1.6.4 discriminated failure shape. Two reasons distinguishable:
- *   - `not_found`: covers genuinely-missing, wrong-tenant, AND
- *     scope-blocked (codex round 3 P1 — distinguishing scope_blocked
- *     from not_found on non-HTTP surfaces leaked private-row existence
- *     to no-scope callers, even though the HTTP route already collapsed
- *     them. Collapse at the API layer.)
- *   - `not_drillable`: id is a leaf row (level 0/1). Caller-actionable.
- *
- * If a future drillDown gains a `scope` opt for explicit-scope callers,
- * a `scope_blocked` failure could be safely re-introduced ONLY for that
- * code path (caller already proved authorization by passing a scope).
- */
+/** `not_found` covers missing, wrong-tenant AND scope-blocked, because distinguishing scope_blocked leaked private-row existence to no-scope callers.
+ *  `not_drillable`: the id is a leaf row (level 0/1), which the caller can act on. */
 export interface DrillDownFailure {
     failure: 'not_found' | 'not_drillable';
 }
 export type DrillDownOutcome = DrillDownResult | DrillDownFailure;
-/**
- * Walk one step down the DAG from a level-2 (or higher) summary to its direct
- * children. Companion to `recall(... summarizeOverflow: true)` — when recall
- * surfaces a summary with `substitutedFor: [...]`, the caller drills into the
- * summary id to recover the original detail.
- *
- * Tenant scope: only summaries owned by `ctx.tenantId` are reachable. The same
- * scope filter that recall applies is enforced on the children — a level-2
- * summary in `slack:public:CGEN` cannot leak `slack:private:*` children even
- * if the underlying DAG accidentally linked across scopes.
- *
- * Returns a discriminated `DrillDownOutcome`: `DrillDownResult` on success,
- * or `{failure: '...'}` for `not_found` (covers genuinely-missing, wrong-
- * tenant and scope-blocked, intentionally indistinguishable) or
- * `not_drillable` (id is a leaf row).
- *
- * Pre-v1.6.4 returned null for all three cases. JS callers migrate via
- * `'failure' in result` checks; HTTP route maps `not_drillable` to 422.
- */
+/** One step down the DAG from a level-2+ summary to its direct children (the way back from `recall(... summarizeOverflow: true)` substitutions). Only
+ * `ctx.tenantId` summaries are reachable; children get recall's scope filter. Returns `DrillDownResult` or `{failure}`; HTTP maps `not_drillable` to 422. */
 export declare function drillDown(ctx: Context, summaryId: string, opts?: DrillDownOpts): Promise<DrillDownOutcome>;
 //# sourceMappingURL=drill-down.d.ts.map

package/dist/api/drill-down.js

@@ -4,25 +4,8 @@ import { estimateTokens } from '../util/token-text.js';
 import { passesScopeFilterForRecall, personalScopeOf } from '../store/recall-scope.js';
 import { classifyOriginProject } from '../core/project-identity.js';
 const DEFAULT_DRILL_DOWN_LIMIT = 50;
-/**
- * Walk one step down the DAG from a level-2 (or higher) summary to its direct
- * children. Companion to `recall(... summarizeOverflow: true)` — when recall
- * surfaces a summary with `substitutedFor: [...]`, the caller drills into the
- * summary id to recover the original detail.
- *
- * Tenant scope: only summaries owned by `ctx.tenantId` are reachable. The same
- * scope filter that recall applies is enforced on the children — a level-2
- * summary in `slack:public:CGEN` cannot leak `slack:private:*` children even
- * if the underlying DAG accidentally linked across scopes.
- *
- * Returns a discriminated `DrillDownOutcome`: `DrillDownResult` on success,
- * or `{failure: '...'}` for `not_found` (covers genuinely-missing, wrong-
- * tenant and scope-blocked, intentionally indistinguishable) or
- * `not_drillable` (id is a leaf row).
- *
- * Pre-v1.6.4 returned null for all three cases. JS callers migrate via
- * `'failure' in result` checks; HTTP route maps `not_drillable` to 422.
- */
+/** One step down the DAG from a level-2+ summary to its direct children (the way back from `recall(... summarizeOverflow: true)` substitutions). Only
+ * `ctx.tenantId` summaries are reachable; children get recall's scope filter. Returns `DrillDownResult` or `{failure}`; HTTP maps `not_drillable` to 422. */
 export async function drillDown(ctx, summaryId, opts = {}) {
     const limit = opts.limit ?? DEFAULT_DRILL_DOWN_LIMIT;
     // v0.30 / E5: depth defaults 1 (backward compat); hard cap 10 levels
@@ -38,10 +21,8 @@ export async function drillDown(ctx, summaryId, opts = {}) {
         admit: (row) => readable(row) && (row.id !== summaryId || isDrillable(row)),
         page: limit >= 0 && Number.isSafeInteger(pastLimit) ? { rows: pastLimit, admit: readable } : undefined,
     });
-    // No unscoped cross-tenant probe here: the tenant-scoped read's miss covers
-    // both "doesn't exist" and "exists in another tenant" by design.
-    // Distinguishing them via an unscoped lookup would leak existence to
-    // unauthorised tenants. The two cases collapse into not_found.
+    // No unscoped cross-tenant probe: the tenant-scoped miss covers "missing" and "in another tenant" alike,
+    // because telling them apart would leak existence to unauthorised tenants.
     if (!walked)
         return { failure: 'not_found' };
     // A distinguishable "scope_blocked" would tell a no-scope caller "this row
@@ -80,9 +61,7 @@ function drillResult({ summary, levels, sizes: counted }, opts, limit) {
     return {
         summary: summaryOut,
         children,
-        // v0.30 / E5: totalChildren = BFS-collected count (depth-aware). For
-        // depth=1 this equals the eligible direct-children count (backward
-        // compat). For depth>1 it is the cumulative count across levels.
+        // totalChildren is the BFS-collected count, cumulative across levels (equals the direct-children count at depth=1).
         totalChildren: total,
         truncated,
     };

package/dist/api/forget.d.ts

@@ -1,6 +1,6 @@
-import type { RejectedValueRow } from '../store/rejection.js';
 import type { Context, StoreReply } from './types.js';
-/** Delete a memory by id. Reach is checked inside the delete's write scope, and a row out of reach answers as not found, so a caller learns nothing about it. */
+/** Delete a memory by id. Reach is checked inside the delete's write scope, and a
+ * row out of reach answers as not found, so a caller learns nothing about it. */
 export interface ForgetResult {
     ok: true;
     id: string;
@@ -18,31 +18,12 @@ export interface RejectResult {
     digest: string;
     removedIds: string[];
 }
-/**
- * Reject a value: tombstone its normalized digest so a matching write is
- * refused everywhere (remember/capture/import/sync) until `unreject`. Two
- * forms — pass exactly one:
- *  - `memoryId`: reject the CURRENT content of an existing memory. Removes
- *    that row and every other live row in the tenant whose normalized
- *    digest matches (not just the id passed), except another person's personal rows.
- *  - `value`: pre-emptive form — tombstone content that may not currently
- *    be stored (or is already gone). Zero removals.
- *
- * `reason` is required (the tombstone stores no content; reason is its
- * only human-readable identity). Throws if the memory id is not found in
- * `ctx.tenantId`, or if both/neither of `memoryId`/`value` are given.
- */
+/** Tombstones a value's normalized digest so a matching write is refused everywhere until `unreject`; pass exactly one of `memoryId` or `value`.
+ * `memoryId` also removes every live tenant row with that digest (not others' personal rows); `reason` is required. Throws on an unknown id or both/neither. */
 export declare function reject(ctx: Context, opts: RejectOpts): RejectResult;
-/**
- * Delete a tombstone by exact digest or unambiguous prefix, restoring the
- * value's writability — the only v1 escape hatch (no per-write force flag).
- * Throws if `digestOrPrefix` matches no tombstone, is blank, or matches
- * more than one (use a longer prefix).
- */
+/** Deletes a tombstone by exact digest or unambiguous prefix, restoring writability (the only v1 escape hatch); throws on blank, no match or several. */
 export declare function unreject(ctx: Context, digestOrPrefix: string): {
     ok: boolean;
     digest: string;
 };
-/** List every rejected-value tombstone for `ctx.tenantId`, newest first. */
-export declare function listRejections(ctx: Context): RejectedValueRow[];
 //# sourceMappingURL=forget.d.ts.map

package/dist/api/forget.js

@@ -1,6 +1,6 @@
 // Forget a memory, and reject or unreject a value so it cannot be stored again.
 import { BadRequestError, NotFoundError } from '../core/api-errors.js';
-import { rejectValue, unrejectValue, listRejectionsForTenant } from '../trust/reject-flow.js';
+import { rejectValue, unrejectValue } from '../trust/reject-flow.js';
 import { andThen, notPorted, onStore } from './on-store.js';
 import { readEntry } from '../store/entry-reads.js';
 import { canTouchScope, personalScopeOf } from '../store/recall-scope.js';
@@ -11,25 +11,11 @@ export function forget(ctx, id) {
         return andThen(entryWrites.forget(removal), () => ({ ok: true, id }));
     });
 }
-/**
- * Reject a value: tombstone its normalized digest so a matching write is
- * refused everywhere (remember/capture/import/sync) until `unreject`. Two
- * forms — pass exactly one:
- *  - `memoryId`: reject the CURRENT content of an existing memory. Removes
- *    that row and every other live row in the tenant whose normalized
- *    digest matches (not just the id passed), except another person's personal rows.
- *  - `value`: pre-emptive form — tombstone content that may not currently
- *    be stored (or is already gone). Zero removals.
- *
- * `reason` is required (the tombstone stores no content; reason is its
- * only human-readable identity). Throws if the memory id is not found in
- * `ctx.tenantId`, or if both/neither of `memoryId`/`value` are given.
- */
+/** Tombstones a value's normalized digest so a matching write is refused everywhere until `unreject`; pass exactly one of `memoryId` or `value`.
+ * `memoryId` also removes every live tenant row with that digest (not others' personal rows); `reason` is required. Throws on an unknown id or both/neither. */
 export function reject(ctx, opts) {
     if (opts.memoryId !== undefined) {
-        // Tenant scope, same not-found-shaped denial as forget/promote above:
-        // rejectValue itself also tenant-checks the id, but pre-checking here
-        // keeps the error message consistent with the rest of this module.
+        // Tenant scope: same not-found-shaped denial as forget/promote; rejectValue tenant-checks too, but pre-checking keeps the error message consistent.
         const entry = readEntry(ctx.hippoRoot, opts.memoryId);
         if (entry?.tenantId !== ctx.tenantId || !canTouchScope(ctx.actor, entry.scope)) {
             throw new NotFoundError(`memory not found: ${opts.memoryId}`);
@@ -46,12 +32,7 @@ export function reject(ctx, opts) {
     });
     return { digest: result.digest, removedIds: result.removedIds };
 }
-/**
- * Delete a tombstone by exact digest or unambiguous prefix, restoring the
- * value's writability — the only v1 escape hatch (no per-write force flag).
- * Throws if `digestOrPrefix` matches no tombstone, is blank, or matches
- * more than one (use a longer prefix).
- */
+/** Deletes a tombstone by exact digest or unambiguous prefix, restoring writability (the only v1 escape hatch); throws on blank, no match or several. */
 export function unreject(ctx, digestOrPrefix) {
     const outcome = unrejectValue(ctx.hippoRoot, ctx.tenantId, digestOrPrefix, ctx.actor.subject);
     if (outcome.status === 'not_found') {
@@ -62,8 +43,4 @@ export function unreject(ctx, digestOrPrefix) {
     }
     return { ok: true, digest: outcome.digest };
 }
-/** List every rejected-value tombstone for `ctx.tenantId`, newest first. */
-export function listRejections(ctx) {
-    return listRejectionsForTenant(ctx.hippoRoot, ctx.tenantId);
-}
 //# sourceMappingURL=forget.js.map

package/dist/api/graph.d.ts

@@ -0,0 +1,8 @@
+import type { GraphRows } from '../store/port.js';
+import type { Context } from './types.js';
+/** The entity/relation rows behind GET /v1/graph, as the caller's role, scopes and owner may see them. */
+export declare function graphRows(ctx: Context, query: {
+    entity?: string;
+    limit: number;
+}): Promise<GraphRows>;
+//# sourceMappingURL=graph.d.ts.map

package/dist/api/graph.js

@@ -0,0 +1,7 @@
+import { requireGroup, storeFor } from '../store/index.js';
+/** The entity/relation rows behind GET /v1/graph, as the caller's role, scopes and owner may see them. */
+export async function graphRows(ctx, query) {
+    const { role, scopes, owner } = ctx.actor;
+    return requireGroup(storeFor(ctx), 'graphReads').graphRows(ctx.tenantId, { ...query, reader: { role, scopes, owner } });
+}
+//# sourceMappingURL=graph.js.map

package/dist/api/index.d.ts

@@ -6,6 +6,7 @@ export type { FailureSummary } from '../store/failure-log.js';
 export { classifyOriginProject } from '../core/project-identity.js';
 export * from './types.js';
 export * from './remember.js';
+export * from './remember-local.js';
 export * from './recall-types.js';
 export * from './recall.js';
 export * from './assemble.js';
@@ -23,4 +24,5 @@ export * from './quarantine.js';
 export * from './sleep.js';
 export * from './goals.js';
 export * from './learn.js';
+export * from './refine.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/api/index.js

@@ -9,6 +9,7 @@ export { passesCliRecallScopeFilter, ScopeForbiddenError } from '../store/recall
 export { classifyOriginProject } from '../core/project-identity.js';
 export * from './types.js';
 export * from './remember.js';
+export * from './remember-local.js';
 export * from './recall-types.js';
 export * from './recall.js';
 export * from './assemble.js';
@@ -26,4 +27,5 @@ export * from './quarantine.js';
 export * from './sleep.js';
 export * from './goals.js';
 export * from './learn.js';
+export * from './refine.js';
 //# sourceMappingURL=index.js.map