hippo-memory 1.72.0 → 2.1.0

package/dist/api/objects/cards.d.ts

@@ -0,0 +1,39 @@
+import type { Card, CardComment, CardRun, CardStatus } from '../../core/card.js';
+import type { HandoffOutcome } from '../../core/handoff.js';
+import type { CardDetail } from '../../store/card-detail.js';
+import type { CardCreate } from '../../store/index.js';
+import type { ContextWith } from '../types.js';
+type Ctx = ContextWith<'cards'>;
+/** Create a card in the caller's tenant. Throws on an empty title or an unknown dependency. */
+export declare function cardCreate(ctx: Ctx, input: CardCreate): Promise<Card>;
+/** One card by id, or null when the caller's tenant has none. */
+export declare function cardLoad(ctx: Ctx, id: string): Promise<Card | null>;
+/** The card with its dependencies, runs, comments and latest handoff, or null when unknown. */
+export declare function cardDetail(ctx: Ctx, id: string): Promise<CardDetail | null>;
+/** The caller's cards, newest-updated first, optionally filtered to one status. */
+export declare function cardList(ctx: Ctx, opts?: {
+    status?: CardStatus;
+}): Promise<Card[]>;
+/** Every run of a card, newest first. */
+export declare function cardRuns(ctx: Ctx, id: string): Promise<CardRun[]>;
+/** Claim a ready or blocked card for a runtime; null when it cannot be claimed. */
+export declare function cardClaim(ctx: Ctx, id: string, runtime: string, sessionId?: string): Promise<(Card & {
+    runId: number;
+}) | null>;
+/** Extend a live run's lease; null when the run is not live. */
+export declare function cardHeartbeat(ctx: Ctx, id: string, runId: number): Promise<Card | null>;
+/** Block a running card with a reason; null when it is not running. */
+export declare function cardBlock(ctx: Ctx, id: string, reason: string, runId?: number): Promise<Card | null>;
+/** Move a running card to review; null when it is not running. */
+export declare function cardReview(ctx: Ctx, id: string, runId?: number): Promise<Card | null>;
+/** Complete a card in review and promote the children it unblocks; null when not in review. */
+export declare function cardComplete(ctx: Ctx, id: string, outcome: HandoffOutcome, runId?: number): Promise<{
+    card: Card;
+    promotedChildren: string[];
+} | null>;
+/** Return every card with an expired lease to ready; yields the reclaimed ids. */
+export declare function cardReclaimExpired(ctx: Ctx): Promise<string[]>;
+/** Add a comment to a card. Throws on an empty body. */
+export declare function cardComment(ctx: Ctx, cardId: string, author: string, body: string): Promise<CardComment>;
+export {};
+//# sourceMappingURL=cards.d.ts.map

package/dist/api/{cards.js → objects/cards.js}

@@ -1,52 +1,50 @@
 // The agent work board: create, claim, review and complete cards, scoped to the caller's tenant.
-import { addCardComment, blockCard, claimCard, completeCard, createCard, heartbeatCard, listCards, loadCard, loadCardRuns, reclaimExpiredCards, reviewCard, } from '../store/cards.js';
-import { loadCardDetail } from '../store/card-detail.js';
 /** Create a card in the caller's tenant. Throws on an empty title or an unknown dependency. */
 export function cardCreate(ctx, input) {
-    return createCard(ctx.hippoRoot, ctx.tenantId, input);
+    return ctx.store.cards.create(ctx.tenantId, input);
 }
 /** One card by id, or null when the caller's tenant has none. */
 export function cardLoad(ctx, id) {
-    return loadCard(ctx.hippoRoot, ctx.tenantId, id);
+    return ctx.store.cards.load(ctx.tenantId, id);
 }
 /** The card with its dependencies, runs, comments and latest handoff, or null when unknown. */
 export function cardDetail(ctx, id) {
-    return loadCardDetail(ctx.hippoRoot, ctx.tenantId, id);
+    return ctx.store.cards.detail(ctx.tenantId, id);
 }
 /** The caller's cards, newest-updated first, optionally filtered to one status. */
 export function cardList(ctx, opts = {}) {
-    return listCards(ctx.hippoRoot, ctx.tenantId, opts);
+    return ctx.store.cards.list(ctx.tenantId, opts);
 }
 /** Every run of a card, newest first. */
 export function cardRuns(ctx, id) {
-    return loadCardRuns(ctx.hippoRoot, ctx.tenantId, id);
+    return ctx.store.cards.runs(ctx.tenantId, id);
 }
 /** Claim a ready or blocked card for a runtime; null when it cannot be claimed. */
 export function cardClaim(ctx, id, runtime, sessionId) {
-    return claimCard(ctx.hippoRoot, ctx.tenantId, id, runtime, sessionId);
+    return ctx.store.cards.claim(ctx.tenantId, id, runtime, sessionId);
 }
 /** Extend a live run's lease; null when the run is not live. */
 export function cardHeartbeat(ctx, id, runId) {
-    return heartbeatCard(ctx.hippoRoot, ctx.tenantId, id, runId);
+    return ctx.store.cards.heartbeat(ctx.tenantId, id, runId);
 }
 /** Block a running card with a reason; null when it is not running. */
 export function cardBlock(ctx, id, reason, runId) {
-    return blockCard(ctx.hippoRoot, ctx.tenantId, id, reason, runId);
+    return ctx.store.cards.block(ctx.tenantId, id, reason, runId);
 }
 /** Move a running card to review; null when it is not running. */
 export function cardReview(ctx, id, runId) {
-    return reviewCard(ctx.hippoRoot, ctx.tenantId, id, runId);
+    return ctx.store.cards.review(ctx.tenantId, id, runId);
 }
 /** Complete a card in review and promote the children it unblocks; null when not in review. */
 export function cardComplete(ctx, id, outcome, runId) {
-    return completeCard(ctx.hippoRoot, ctx.tenantId, id, outcome, runId);
+    return ctx.store.cards.complete(ctx.tenantId, id, outcome, runId);
 }
 /** Return every card with an expired lease to ready; yields the reclaimed ids. */
 export function cardReclaimExpired(ctx) {
-    return reclaimExpiredCards(ctx.hippoRoot, ctx.tenantId);
+    return ctx.store.cards.reclaimExpired(ctx.tenantId);
 }
 /** Add a comment to a card. Throws on an empty body. */
 export function cardComment(ctx, cardId, author, body) {
-    return addCardComment(ctx.hippoRoot, ctx.tenantId, cardId, author, body);
+    return ctx.store.cards.comment(ctx.tenantId, cardId, author, body);
 }
 //# sourceMappingURL=cards.js.map

package/dist/api/{drill-down.d.ts → objects/drill-down.d.ts}

@@ -1,12 +1,13 @@
-import type { CallerProject } from './prompt-hook.js';
-import type { Context } from './types.js';
+import type { CallerProject } from '../prompt-hook.js';
+import type { ContextWith } from '../types.js';
 export interface DrillDownOpts {
     /** Cap on number of children returned. Default 50. */
     limit?: number;
-    /** 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. */
+    /** 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;
-    /** Levels to walk down (default 1 = direct children); capped at 10 internally. BFS dedups with a visited Set, defensive against shared-child anomalies. */
+    /** 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;
@@ -35,13 +36,14 @@ export interface DrillDownResult {
     totalChildren: number;
     truncated: boolean;
 }
-/** `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. */
+/** `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;
-/** 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>;
+/** 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: ContextWith<'dagReads'>, summaryId: string, opts?: DrillDownOpts): Promise<DrillDownOutcome>;
 //# sourceMappingURL=drill-down.d.ts.map

package/dist/api/{drill-down.js → objects/drill-down.js}

@@ -1,11 +1,11 @@
 // DAG drill-down from a summary to its children.
-import { requireGroup, storeFor } from '../store/index.js';
-import { estimateTokens } from '../util/token-text.js';
-import { passesScopeFilterForRecall, personalScopeOf } from '../core/recall-scope.js';
-import { classifyOriginProject } from '../core/project-identity.js';
+import { estimateTokens } from '../../util/token-text.js';
+import { passesScopeFilterForRecall, personalScopeOf } from '../../core/recall-scope.js';
+import { classifyOriginProject } from '../../core/project-identity.js';
 const DEFAULT_DRILL_DOWN_LIMIT = 50;
-/** 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. */
+/** 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
@@ -15,7 +15,7 @@ export async function drillDown(ctx, summaryId, opts = {}) {
     const readable = (row) => passesScopeFilterForRecall(row.scope ?? null, undefined, own)
         && (!opts.project || classifyOriginProject(row.origin_project, opts.project) !== 'cross-project');
     const pastLimit = Math.floor(limit) + 1;
-    const walked = await requireGroup(storeFor(ctx), 'dagReads').summaryWithDescendants(ctx.tenantId, summaryId, {
+    const walked = await ctx.store.dagReads.summaryWithDescendants(ctx.tenantId, summaryId, {
         depth,
         // A leaf answers not_drillable, so nothing under it is read.
         admit: (row) => readable(row) && (row.id !== summaryId || isDrillable(row)),

package/dist/api/objects/goals.d.ts

@@ -0,0 +1,18 @@
+import type { CompleteGoalOpts, Goal, PushGoalOpts } from '../../store/goals.js';
+import { type ContextWith } from '../types.js';
+/** What a new goal carries; its tenant is always the caller's. */
+export type GoalPushOpts = Omit<PushGoalOpts, 'tenantId'>;
+/** Push a goal onto `sessionId`'s stack in the caller's tenant. */
+export declare function goalPush(ctx: ContextWith<'goals'>, opts: GoalPushOpts): Promise<Goal>;
+/** The caller's goals for `sessionId`: active ones, or every status when `all` is set. */
+export declare function goalList(ctx: ContextWith<'goals'>, opts: {
+    sessionId: string;
+    all: boolean;
+}): Promise<Goal[]>;
+/** Complete a goal by id; a no-op for an unknown or already completed goal. Host admin only. */
+export declare function goalComplete(ctx: ContextWith<'goals'>, goalId: string, opts: CompleteGoalOpts): Promise<void>;
+/** Suspend an active goal by id. Host admin only. */
+export declare function goalSuspend(ctx: ContextWith<'goals'>, goalId: string): Promise<void>;
+/** Resume a suspended goal by id, suspending the oldest active one past the depth cap. Host admin only. */
+export declare function goalResume(ctx: ContextWith<'goals'>, goalId: string): Promise<void>;
+//# sourceMappingURL=goals.d.ts.map

package/dist/api/{goals.js → objects/goals.js}

@@ -1,29 +1,29 @@
 // The per-session goal stack that recall boosts: push, list, complete, suspend and resume.
-import { completeGoal, getActiveGoals, getSessionGoals, pushGoal, resumeGoal, suspendGoal, } from '../store/goals.js';
-import { requireHostAdmin } from './types.js';
+import { requireHostAdmin } from '../types.js';
 /** Push a goal onto `sessionId`'s stack in the caller's tenant. */
 export function goalPush(ctx, opts) {
-    return pushGoal(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+    return ctx.store.goals.push(ctx.tenantId, opts);
 }
 /** The caller's goals for `sessionId`: active ones, or every status when `all` is set. */
-export function goalList(ctx, opts) {
-    const scope = { sessionId: opts.sessionId, tenantId: ctx.tenantId };
-    return opts.all ? getSessionGoals(ctx.hippoRoot, scope) : getActiveGoals(ctx.hippoRoot, scope);
+export async function goalList(ctx, opts) {
+    if (opts.all)
+        return ctx.store.goals.sessionGoals(ctx.tenantId, opts.sessionId);
+    return (await ctx.store.activeGoals({ sessionId: opts.sessionId, tenantId: ctx.tenantId })).goals;
 }
 /** Complete a goal by id; a no-op for an unknown or already completed goal. Host admin only. */
-export function goalComplete(ctx, goalId, opts) {
+export async function goalComplete(ctx, goalId, opts) {
     // Goal ids are not tenant-scoped in the store, so acting on one by id reaches past the caller's tenant.
     requireHostAdmin(ctx, 'Completing a goal by id');
-    completeGoal(ctx.hippoRoot, goalId, opts);
+    await ctx.store.goals.complete(ctx.tenantId, goalId, opts);
 }
 /** Suspend an active goal by id. Host admin only. */
-export function goalSuspend(ctx, goalId) {
+export async function goalSuspend(ctx, goalId) {
     requireHostAdmin(ctx, 'Suspending a goal by id');
-    suspendGoal(ctx.hippoRoot, goalId);
+    await ctx.store.goals.suspend(ctx.tenantId, goalId);
 }
 /** Resume a suspended goal by id, suspending the oldest active one past the depth cap. Host admin only. */
-export function goalResume(ctx, goalId) {
+export async function goalResume(ctx, goalId) {
     requireHostAdmin(ctx, 'Resuming a goal by id');
-    resumeGoal(ctx.hippoRoot, goalId);
+    await ctx.store.goals.resume(ctx.tenantId, goalId);
 }
 //# sourceMappingURL=goals.js.map

package/dist/api/objects/graph.d.ts

@@ -0,0 +1,11 @@
+import type { GraphRows } from '../../store/port.js';
+import type { ContextWith } from '../types.js';
+/** The entity a graph read focuses on. Capped at the 512 entity-name cap, not the id-shaped 256, so a long decision or
+ * policy name stays focusable. */
+export declare function graphEntityOf(raw: string | null): string | undefined;
+/** The entity/relation rows behind GET /v1/graph, as the caller's role, scopes and owner may see them. */
+export declare function graphRows(ctx: ContextWith<'graphReads'>, query: {
+    entity?: string;
+    limit: number;
+}): Promise<GraphRows>;
+//# sourceMappingURL=graph.d.ts.map

package/dist/api/objects/graph.js

@@ -0,0 +1,16 @@
+import { BadRequestError } from '../../core/api-errors.js';
+import { MAX_ENTITY_NAME_LEN } from '../../store/graph-rows.js';
+/** The entity a graph read focuses on. Capped at the 512 entity-name cap, not the id-shaped 256, so a long decision or
+ * policy name stays focusable. */
+export function graphEntityOf(raw) {
+    if (raw !== null && raw.length > MAX_ENTITY_NAME_LEN) {
+        throw new BadRequestError(`entity exceeds the ${MAX_ENTITY_NAME_LEN}-character cap`);
+    }
+    return raw ?? undefined;
+}
+/** 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 ctx.store.graphReads.graphRows(ctx.tenantId, { ...query, reader: { role, scopes, owner } });
+}
+//# sourceMappingURL=graph.js.map

package/dist/api/objects/objects.d.ts

@@ -0,0 +1,9 @@
+import type { SavableDescriptor } from '../../objects/descriptor.js';
+import type { ObjectByKind, SavableKind } from '../../core/object-types.js';
+import type { Objects } from '../../store/port.js';
+import type { ContextWith } from '../types.js';
+/** The request store's object group; the dispatcher has already answered 501 for a store without it. */
+export declare function objectsOf(ctx: ContextWith<'objects'>): Objects;
+/** Saves through the request's store as the authenticated caller. */
+export declare function saveFor<K extends SavableKind, W>(ctx: ContextWith<'objects'>, d: SavableDescriptor<K, W>, write: W): Promise<ObjectByKind[K]>;
+//# sourceMappingURL=objects.d.ts.map

package/dist/api/{objects.js → objects/objects.js}

@@ -1,8 +1,7 @@
-import { saveObject } from '../objects/lifecycle.js';
-import { requireGroup, storeFor } from '../store/index.js';
+import { saveObject } from '../../objects/lifecycle.js';
 /** The request store's object group; the dispatcher has already answered 501 for a store without it. */
 export function objectsOf(ctx) {
-    return requireGroup(storeFor(ctx), 'objects');
+    return ctx.store.objects;
 }
 /** Saves through the request's store as the authenticated caller. */
 export function saveFor(ctx, d, write) {

package/dist/api/objects/predictions.d.ts

@@ -0,0 +1,11 @@
+import { type Prediction, type PredictionBaserate, type SavePredictionOpts } from '../../store/predictions.js';
+import type { PredictionClose, PredictionSave, Predictions } from '../../store/port.js';
+import type { ContextWith } from '../types.js';
+export declare function savePrediction(ctx: ContextWith<'predictions'>, input: PredictionSave): Promise<Prediction>;
+/** A claim saved with its recall mirror, built under the store root's half-life as the HTTP create route builds it. */
+export declare function recordPrediction(ctx: ContextWith<'predictions'>, claim: SavePredictionOpts): Promise<Prediction>;
+export declare function listPredictions(ctx: ContextWith<'predictions'>, query: Parameters<Predictions['listPredictions']>[1]): Promise<Prediction[]>;
+export declare function predictionBaserate(ctx: ContextWith<'predictions'>, classTag: string): Promise<PredictionBaserate>;
+export declare function predictionById(ctx: ContextWith<'predictions'>, id: number): Promise<Prediction | null>;
+export declare function closePrediction(ctx: ContextWith<'predictions'>, id: number, close: PredictionClose): Promise<Prediction>;
+//# sourceMappingURL=predictions.d.ts.map

package/dist/api/{predictions.js → objects/predictions.js}

@@ -1,13 +1,15 @@
-import { predictionMirror } from '../store/predictions.js';
-import { loadConfig } from '../core/config.js';
-import { requireGroup, storeFor } from '../store/index.js';
-const predictionsOf = (ctx) => requireGroup(storeFor(ctx), 'predictions');
+import { predictionMirror, } from '../../store/predictions.js';
+import { configOf } from '../config-of.js';
+const predictionsOf = (ctx) => ctx.store.predictions;
 export async function savePrediction(ctx, input) {
     return predictionsOf(ctx).savePrediction(ctx.tenantId, input, ctx.actor.subject);
 }
 /** A claim saved with its recall mirror, built under the store root's half-life as the HTTP create route builds it. */
 export async function recordPrediction(ctx, claim) {
-    return savePrediction(ctx, { ...claim, mirror: predictionMirror(ctx.tenantId, claim, loadConfig(ctx.hippoRoot).defaultHalfLifeDays) });
+    return savePrediction(ctx, {
+        ...claim,
+        mirror: predictionMirror(ctx.tenantId, claim, configOf(ctx).defaultHalfLifeDays),
+    });
 }
 export async function listPredictions(ctx, query) {
     return predictionsOf(ctx).listPredictions(ctx.tenantId, query);

package/dist/api/{projects.d.ts → objects/projects.d.ts}

@@ -1,7 +1,7 @@
-import { type MergeResult, type ProjectSummary, type RepairResult } from '../sharing/project-merge.js';
-import type { Context } from './types.js';
-export type { MergeResult, ProjectCollision, ProjectSummary, RepairResult } from '../sharing/project-merge.js';
-export type { ProjectFold } from '../agent-memories/project-folds.js';
+import { type MergeResult, type ProjectSummary, type RepairResult } from '../../sharing/project-merge.js';
+import type { Context } from '../types.js';
+export type { MergeResult, ProjectCollision, ProjectSummary, RepairResult } from '../../sharing/project-merge.js';
+export type { ProjectFold } from '../../agent-memories/project-folds.js';
 export interface MergeProjectNamesOpts {
     from: string;
     into: string;
@@ -10,7 +10,10 @@ export interface MergeProjectNamesOpts {
 }
 /** Live rows per project name in the caller's tenant, newest write first. */
 export declare function listProjectNames(ctx: Context): ProjectSummary[];
-/** Folds project `from` into `into`, backed up and audited as `ctx.actor`; throws on user-global, unknown or equal names. */
+/**
+ * Folds project `from` into `into`, backed up and audited as `ctx.actor`; throws on user-global, unknown or equal
+ * names.
+ */
 export declare function mergeProjectNames(ctx: Context, opts: MergeProjectNamesOpts): MergeResult;
 /** Sets aside stray imports, folds renamed projects and re-tags sleep's user-global merges; a dry run only plans. */
 export declare function repairProjectNames(ctx: Context, opts: {

package/dist/api/{projects.js → objects/projects.js}

@@ -1,7 +1,8 @@
-// Project names for every front end: list them, fold one into another, and repair old tags; the store opens hippo.db and owns each transaction.
+// Project names for every front end: list them, fold one into another, and repair old tags; the store opens hippo.db
+// and owns each transaction.
 // SHORTCUT: hippo.db only, since the store port has no project calls; a projects group when a served store needs them.
-import { listProjects, mergeProjects, repairOnceOnSleep, repairProjects, } from '../sharing/project-merge.js';
-import { onProjectTags } from '../store/project-tags.js';
+import { listProjects, mergeProjects, repairOnceOnSleep, repairProjects, } from '../../sharing/project-merge.js';
+import { onProjectTags } from '../../store/project-tags.js';
 function onProjects(ctx, fn) {
     return onProjectTags({ hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, actor: ctx.actor.subject }, fn);
 }
@@ -9,7 +10,10 @@ function onProjects(ctx, fn) {
 export function listProjectNames(ctx) {
     return onProjects(ctx, listProjects);
 }
-/** Folds project `from` into `into`, backed up and audited as `ctx.actor`; throws on user-global, unknown or equal names. */
+/**
+ * Folds project `from` into `into`, backed up and audited as `ctx.actor`; throws on user-global, unknown or equal
+ * names.
+ */
 export function mergeProjectNames(ctx, opts) {
     return onProjects(ctx, (store) => mergeProjects(store, opts));
 }

package/dist/api/pilot-arm.d.ts

@@ -1,10 +1,14 @@
-import { type LedgerRootOpts } from './ledger-db.js';
+import { type LedgerReach } from './ledger-db.js';
 import { type PilotArm } from '../store/pilot-arm.js';
-export interface SessionArmOpts extends LedgerRootOpts {
-    /** Only the caller tenant's arm row counts, so a caller holding another tenant's session id cannot claim that session's arm. */
+export interface SessionArmOpts {
+    readonly reach: LedgerReach;
+    /**
+     * Only the caller tenant's arm row counts, so a caller holding another tenant's session id cannot claim that
+     * session's arm.
+     */
     readonly ownTenantOnly?: boolean;
 }
 /** The session's arm, or null at rate 0, with no session id, or with no store.
  *  `write` books the arm row; a read-only caller (env-only id, sub-agent) follows the stored arm, else the hash. */
-export declare function sessionPilotArm(hippoRoot: string, tenantId: string, sessionId: string | undefined, write: boolean, opts?: SessionArmOpts): PilotArm | null;
+export declare function sessionPilotArm(hippoRoot: string, tenantId: string, sessionId: string | undefined, write: boolean, opts: SessionArmOpts): PilotArm | null;
 //# sourceMappingURL=pilot-arm.d.ts.map

package/dist/api/pilot-arm.js

@@ -1,21 +1,22 @@
-// Which pilot arm a session is in: the rate comes from the ledger store's config, the arm row from src/store/pilot-arm.ts.
+// Which pilot arm a session is in: the rate comes from the ledger store's config, the arm row from
+// src/store/pilot-arm.ts.
 import { loadConfig } from '../core/config.js';
 import { ledgerRoot, onLedgerRoot } from './ledger-db.js';
 import { pilotArmOnRoot } from '../store/ledger-turn.js';
 import { hashArm } from '../store/pilot-arm.js';
 /** The session's arm, or null at rate 0, with no session id, or with no store.
  *  `write` books the arm row; a read-only caller (env-only id, sub-agent) follows the stored arm, else the hash. */
-export function sessionPilotArm(hippoRoot, tenantId, sessionId, write, opts = {}) {
+export function sessionPilotArm(hippoRoot, tenantId, sessionId, write, opts) {
     if (sessionId === undefined || sessionId.trim() === '')
         return null;
-    const root = ledgerRoot(hippoRoot, opts);
+    const root = ledgerRoot(hippoRoot, opts.reach);
     if (root === null)
         return null;
     const rate = loadConfig(root).pilot.holdoutRateBp;
     if (rate <= 0)
         return null;
     const { ownTenantOnly } = opts;
-    const arm = onLedgerRoot(hippoRoot, opts, (at) => pilotArmOnRoot(at, tenantId, sessionId, rate, { write, ownTenantOnly }));
+    const arm = onLedgerRoot(hippoRoot, opts.reach, (at) => pilotArmOnRoot(at, tenantId, sessionId, rate, { write, ownTenantOnly }));
     return arm ?? hashArm(sessionId, rate);
 }
 //# sourceMappingURL=pilot-arm.js.map

package/dist/api/prompt-hook.d.ts

@@ -1,7 +1,9 @@
-import { type Context, type ContextResult, type ContextResultEntry } from './index.js';
-import { type DeliveryEventType, type DeliveryRecorder } from '../store/delivery-recorder.js';
+import { type Context, type ContextResult, type ContextResultEntry, type ContextWith } from './index.js';
+import { type HippoConfig } from '../core/config.js';
+import { type DeliveryEventType, type DeliveryFault, type DeliveryRecorder } from '../store/delivery-recorder.js';
 import type { HookRuntime } from '../core/capture-contract.js';
 import { type JsonValue } from '../util/json.js';
+import { type LedgerReach } from './ledger-db.js';
 import type { MemoryEntry } from '../core/memory.js';
 import type { PilotArm } from '../store/pilot-arm.js';
 import type { DeliveryWrite } from '../store/ledger-turn.js';
@@ -12,16 +14,22 @@ export interface DeliveryStart {
     eventType?: DeliveryEventType;
     /** The host's own session id from its environment, used when the payload names none. */
     envSessionId: string | undefined;
+    /** Passed through to the recorder; only tests set it. */
+    fault?: DeliveryFault;
 }
 /** A delivery recorder for a hook on `ctx.hippoRoot` when the ledger store enables one, else null; never throws. */
 export declare function startDeliveryRecorder(ctx: Context, start: DeliveryStart): DeliveryRecorder | null;
-/** A recorder for `hippo capture-error`, only when the failure log and the ledger are one store, so `failure_id` never points into another. */
+/** A recorder for `hippo capture-error`, only when the failure log and the ledger are one store, so `failure_id` never
+ * points into another. */
 export declare function startToolFailureRecorder(ctx: Context, start: Omit<DeliveryStart, 'eventType'>): DeliveryRecorder | null;
-/** With `write`, stores on the token ledger's connection (same store); without it, opens its own. A second flush is a no-op. */
+/** With `write`, stores on the token ledger's connection (same
+ * store); without it, opens its own. A second flush is a no-op. */
 export declare function flushDeliveryRecorder(rec: DeliveryRecorder | null, write?: DeliveryWrite): void;
 /** What one render needs once api.getContext has answered. */
 export interface ContextView {
     readonly hippoRoot: string;
+    /** The caller's Context config, else the folder's config.json is read. */
+    readonly config?: HippoConfig;
     readonly tenantId: string;
     readonly ledgerSessionId: string | undefined;
     readonly payloadSessionId: string | undefined;
@@ -29,17 +37,20 @@ export interface ContextView {
     readonly framing: string;
     readonly rec: DeliveryRecorder | null;
     readonly result: ContextResult;
-    /** Ledger rows stay in `hippoRoot`, never the global store; see promptHookContext. */
-    readonly sharedStore?: boolean;
+    /** Where the ledger rows go; a shared store's reach has no global store, see promptHookContext. */
+    readonly reach: LedgerReach;
     /** The static block's hash the caller says it printed last. Undefined keeps the ledger-only skip rule;
-     *  a string or null also needs that hash to match, because the ledger counts blocks a caller that prints elsewhere may never have shown. */
+     *  a string or null also needs that hash to match, because the ledger counts blocks a caller that prints elsewhere
+     *  may never have shown. */
     readonly printedHash?: string | null;
     /** The reply's JSON wrapper; absent means Claude Code's UserPromptSubmit. */
     readonly envelope?: HookEnvelope;
 }
-/** `copilot-session-start` is the Copilot harness's top-level reply, `vscode-session-start` the nested one VS Code Local reads. */
+/** `copilot-session-start` is the Copilot harness's top-level reply,
+ * `vscode-session-start` the nested one VS Code Local reads. */
 export type HookEnvelope = 'user-prompt-submit' | 'copilot-session-start' | 'vscode-session-start';
-/** A Copilot sessionStart reply's wrapper, picked by the sender's casing: stdin.ts keeps a camelCase `sessionId`, which only the Copilot harness sends. */
+/** A Copilot sessionStart reply's wrapper, picked by the sender's casing: stdin.ts keeps a camelCase `sessionId`, which
+ * only the Copilot harness sends. */
 export declare function sessionStartEnvelope(stdinText: string | undefined): HookEnvelope;
 export declare function hasContextData(result: ContextResult): boolean;
 export type RenderItem = {
@@ -49,36 +60,40 @@ export type RenderItem = {
     isGlobal: boolean;
 };
 export declare function toRenderItems(entries: ContextResultEntry[]): RenderItem[];
-/** The hook format's stdout, '' when nothing is sent: a skippable static block (snapshot, handoff, events, pins, recent-N) and a never-skipped recall block. */
+/** The hook format's stdout, '' when nothing is sent: a skippable static block (snapshot, handoff, events, pins,
+ * recent-N) and a never-skipped recall block. */
 export declare function additionalContextOutput(view: ContextView): string;
-/** The project a hook caller runs in: its id, the folder name its older rows carry, and any other names it resolves to. */
+/** The project a hook caller runs in: its id, the folder name
+ * its older rows carry, and any other names it resolves to. */
 export interface CallerProject {
     readonly name: string;
     readonly legacyName: string;
     readonly aliases?: readonly string[];
 }
-interface PromptHookRequest {
+export interface PromptHookRequest {
     readonly sessionId: string;
     readonly project: CallerProject;
     readonly payload?: Readonly<Record<string, JsonValue>>;
-    /** The staticHash of the last reply whose stdout the caller printed in this session; absent, the block is always sent. */
+    /** The staticHash of the last reply whose stdout the caller
+     * printed in this session; absent, the block is always sent. */
     readonly printedHash?: string;
 }
-interface PromptHookOpts {
+export interface PromptHookOpts {
     /** The store serves many people, so the caller is not its owner: no global store, no user-global recent rows,
      *  task state only for the caller's own owner and project, and no ledger rows outside this store. */
     readonly sharedStore?: true;
 }
 /** The caps on a hook caller's session id and project names, so a caller other than an HTTP route is bounded too. */
 export declare function assertCallerIds(sessionId: string, project: CallerProject): void;
-/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for its project.
- * Omits an unchanged static block only when `printedHash` matches; `arm` is the ledger arm (`hippo` or `holdout`, null at rate 0); a holdout gets empty stdout.
- * `staticHash` is the hash to echo back (null with no static block, a sub-agent or a holdout). Scope detection and delivery-ledger events are CLI-only.
- * Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
-export declare function promptHookContext(ctx: Context, req: PromptHookRequest, opts?: PromptHookOpts): Promise<{
+/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read
+ * on `ctx`'s store for its project. Omits an unchanged static block only when `printedHash` matches; `arm` is the
+ * ledger arm (`hippo` or `holdout`, null at rate 0); a holdout gets empty stdout. `staticHash` is the hash to echo back
+ * (null with no static block, a sub-agent or a holdout). Scope detection and delivery-ledger events are CLI-only.
+ * Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before
+ * any arm is booked. */
+export declare function promptHookContext(ctx: ContextWith<'contextReads'>, req: PromptHookRequest, opts?: PromptHookOpts): Promise<{
     arm: PilotArm | null;
     stdout: string;
     staticHash: string | null;
 }>;
-export {};
 //# sourceMappingURL=prompt-hook.d.ts.map