hippo-memory 1.61.0 → 1.63.0

package/dist/shared.js

@@ -19,8 +19,9 @@ import { passesScopeFilterForRecall, passesCliRecallScopeFilter } from './recall
 import { search } from './search/bm25-search.js';
 import { hybridSearch } from './search/hybrid.js';
 import { fitBudget } from './search/finalize.js';
+import { DEFAULT_LOCAL_BUMP, DEFAULT_RECALL_BUDGET } from './search/types.js';
 import { evalNow } from './ablation.js';
-import { deriveOriginProject, classifyOriginProject, resolveGlobalRootDir } from './project-identity.js';
+import { deriveOriginProject, classifyOriginProject, resolveGlobalRootDir, resolveProjectIdentity } from './project-identity.js';
 import { detectSecret } from './secret-detect.js';
 import { isQuarantineScope } from './quarantine.js';
 import { RejectedValueError } from './rejection.js';
@@ -62,12 +63,12 @@ export function promoteToGlobal(localRoot, id, opts) {
     const entry = readEntry(localRoot, id, opts?.tenantId);
     if (!entry)
         throw new NotFoundError(`Memory not found: ${id}`);
-    // CD5: same veto as shareMemory; a promoted copy would have no quarantine record to review.
+    // Same quarantine veto as shareMemory; a promoted copy would have no quarantine record to review.
     if (isQuarantineScope(entry.scope)) {
         throw new BadRequestError(`Refusing to promote ${id}: it is quarantined pending review. Approve it first via 'hippo quarantine approve ${id}'.`);
     }
-    // v39 S4 producer veto: promote is a producer path to the global store
-    // exactly like shareMemory - same hard rule (codex gating review P2).
+    // Secret producer veto: promote is a producer path to the global store
+    // exactly like shareMemory - same hard rule.
     const promoteSecret = detectSecret(entry);
     if (promoteSecret.flagged) {
         throw new BadRequestError(`Refusing to promote ${id} to the global store: content matches secret material (${promoteSecret.reason}). ` +
@@ -95,7 +96,7 @@ export function promoteToGlobal(localRoot, id, opts) {
  * Returns results sorted by adjusted score, within combined token budget.
  */
 export function searchBoth(query, localRoot, globalRoot, options = {}) {
-    const { budget = 4000, now = evalNow(), minResults, tenantId } = options;
+    const { budget = DEFAULT_RECALL_BUDGET, now = evalNow(), minResults, tenantId } = options;
     const effectiveMin = minResults ?? 1;
     const localEntries = fs.existsSync(localRoot) ? loadSearchEntries(localRoot, query, undefined, tenantId) : [];
     const globalEntries = fs.existsSync(globalRoot) ? loadSearchEntries(globalRoot, query, undefined, tenantId) : [];
@@ -105,14 +106,13 @@ export function searchBoth(query, localRoot, globalRoot, options = {}) {
     const localResults = search(query, localEntries, { budget, now, minResults });
     const globalResults = search(query, globalEntries, { budget, now, minResults });
     // Tag global results. Local memories get a configurable priority bump.
-    const syncLocalBump = 1.2;
     const tagged = [
         ...localResults.map((r) => ({
             ...r,
             isGlobal: false,
-            score: r.score * syncLocalBump,
+            score: r.score * DEFAULT_LOCAL_BUMP,
             breakdown: r.breakdown
-                ? { ...r.breakdown, sourceBump: syncLocalBump, final: r.breakdown.final * syncLocalBump }
+                ? { ...r.breakdown, sourceBump: DEFAULT_LOCAL_BUMP, final: r.breakdown.final * DEFAULT_LOCAL_BUMP }
                 : undefined,
         })),
         ...globalResults.map((r) => ({ ...r, isGlobal: true })),
@@ -126,11 +126,8 @@ export function searchBoth(query, localRoot, globalRoot, options = {}) {
         seen.add(key);
         return true;
     });
-    // T2 note: PLAIN stable score sort on purpose -- local/global inputs are
-    // each deterministically ordered (content tail applied in the underlying
-    // search), stability inherits that, and an exact post-bump tie keeps the
-    // LOCAL result ahead of the global one (the concat order), preserving the
-    // pre-T2 semantics.
+    // PLAIN stable score sort on purpose: both inputs are deterministically ordered,
+    // and an exact tie keeps the LOCAL result ahead of the global one (concat order).
     deduped.sort((a, b) => b.score - a.score);
     // Apply combined token budget (guarantee at least minResults items)
     const results = [];
@@ -148,19 +145,13 @@ export function searchBoth(query, localRoot, globalRoot, options = {}) {
  * Async version of searchBoth that calls hybridSearch instead of search.
  */
 export async function searchBothHybrid(query, localRoot, globalRoot, options = {}) {
-    const { budget = 4000, now = evalNow(), embeddingWeight, explain, mmr, mmrLambda, localBump = 1.2, minResults, cost, scope, includeSuperseded, asOf, tenantId, summaryDeboost, summaryFreshness, entryFilter, recallScope } = options;
+    const { includeSuperseded, asOf, tenantId, entryFilter, recallScope } = options;
     // When an admission filter is active, lift the per-store candidate cap
     // (default 200): excluded rows matching the query could otherwise fill the
-    // window before any admitted row is even loaded (codex gating round 6).
-    // Only ambient-context query mode sets entryFilter, and that path is
-    // interactive - never the per-turn pinned-only hook - so ranking the full
-    // match set is acceptable.
-    // 5000 = 25x the default 200-row window: large enough that exclusion
-    // crowding is a non-issue on real stores, bounded so a common query term
-    // on a 100k-row store cannot stall an interactive call by ranking every
-    // match (post-merge adversarial review, 2026-07-02).
+    // window before any admitted row is even loaded. 5000 is bounded so a common
+    // term on a large store cannot stall an interactive call by ranking every match.
     const searchWindow = entryFilter ? 5000 : undefined;
-    // v1.25.0 recall mode: push the scope predicate into SQL exactly like
+    // Recall mode: push the scope predicate into SQL exactly like
     // api.recall (loadRecallSearchEntries), so quarantine/private rows never
     // enter the candidate set, never shadow admitted duplicates in the dedupe
     // pass, and never consume budget. The JS post-filter below is the
@@ -179,8 +170,6 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
     const admit = (e) => passesScope(e) && (!entryFilter || entryFilter(e));
     const localEntries = loadEntries(localRoot).filter(admit);
     const globalEntries = loadEntries(globalRoot).filter(admit);
-    if (localEntries.length === 0 && globalEntries.length === 0)
-        return [];
     // The vector arm loads under the same SQL rules as loadEntries, then the same JS admission.
     const vectorCandidates = {
         tenantId,
@@ -188,9 +177,16 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
         includeSuperseded: !recallScope || Boolean(includeSuperseded) || Boolean(asOf),
         admit,
     };
+    return rankBothStores(query, { local: localRoot, global: globalRoot }, { local: localEntries, global: globalEntries }, vectorCandidates, options);
+}
+/** Hybrid ranking of rows already loaded from each store: the local bump, one copy per text, then the shared budget. */
+export async function rankBothStores(query, roots, entries, vectorCandidates, options = {}) {
+    const { budget = DEFAULT_RECALL_BUDGET, now = evalNow(), embeddingWeight, explain, mmr, mmrLambda, localBump = DEFAULT_LOCAL_BUMP, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness } = options;
+    if (entries.local.length === 0 && entries.global.length === 0)
+        return [];
     const shared = { budget, now, embeddingWeight, explain, mmr, mmrLambda, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness, vectorCandidates };
-    const localResults = await hybridSearch(query, localEntries, { ...shared, hippoRoot: localRoot });
-    const globalResults = await hybridSearch(query, globalEntries, { ...shared, hippoRoot: globalRoot });
+    const localResults = await hybridSearch(query, entries.local, { ...shared, hippoRoot: roots.local });
+    const globalResults = await hybridSearch(query, entries.global, { ...shared, hippoRoot: roots.global });
     // Tag global results. Local memories get a configurable priority bump.
     const tagged = [
         ...localResults.map((r) => ({
@@ -212,7 +208,7 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
         seen.add(key);
         return true;
     });
-    // T2 note: PLAIN stable score sort on purpose -- see searchBoth above;
+    // PLAIN stable score sort on purpose -- see searchBoth above;
     // same rationale (deterministic inputs + stability; local-first on ties).
     deduped.sort((a, b) => b.score - a.score);
     return fitBudget(deduped, budget, minResults ?? 1, cost);
@@ -284,7 +280,7 @@ export function shareMemory(localRoot, id, options = {}) {
     const entry = readEntry(localRoot, id, options.tenantId);
     if (!entry)
         throw new NotFoundError(`Memory not found: ${id}`);
-    // v39 S4 producer veto: secrets never go to the global store, not even
+    // Secret producer veto: secrets never go to the global store, not even
     // with --force. Explicit and loud - a silent null would read as "low
     // transfer score" and invite retries.
     const secret = detectSecret(entry);
@@ -292,7 +288,7 @@ export function shareMemory(localRoot, id, options = {}) {
         throw new BadRequestError(`Refusing to share ${id} to the global store: content matches secret material (${secret.reason}). ` +
             `Secrets stay in their owning project's store.`);
     }
-    // CD5: a quarantined row is unreviewed input, not a lesson; sharing it would spread poison globally.
+    // A quarantined row is unreviewed input, not a lesson; sharing it would spread poison globally.
     if (isQuarantineScope(entry.scope)) {
         throw new BadRequestError(`Refusing to share ${id}: it is quarantined pending review. Approve it first via 'hippo quarantine approve ${id}'.`);
     }
@@ -326,7 +322,7 @@ export function shareMemory(localRoot, id, options = {}) {
  * List all projects that have contributed memories to the global store.
  * Parses the source field for 'shared:<project>:' or 'promoted:<path>' patterns.
  *
- * D4 v1.12.10: `tenantId` is now optional. When provided, the global entries
+ * `tenantId` is optional. When provided, the global entries
  * are filtered to that tenant before aggregation — matches every other
  * read path's default-safe behaviour. When undefined, host-wide (back-compat
  * for legacy callers like CLI standalone + dashboard internal use). Operators
@@ -337,7 +333,7 @@ export function listPeers(globalRoot, tenantId) {
     const root = globalRoot ?? getGlobalRoot();
     if (!fs.existsSync(root))
         return [];
-    // D4: tenant-scoped by default when tenantId provided. Host-wide when
+    // Tenant-scoped by default when tenantId provided. Host-wide when
     // undefined (preserves back-compat).
     const tallies = tallySources(root, tenantId).sort((a, b) => (a.first < b.first ? -1 : a.first > b.first ? 1 : 0));
     const peerMap = new Map();
@@ -368,25 +364,85 @@ export function listPeers(globalRoot, tenantId) {
         .map(([project, data]) => ({ project, ...data }))
         .sort((a, b) => b.count - a.count);
 }
+function isAutoShareCandidate(entry, globalContentSet, minScore, stats) {
+    // shareMemory refuses quarantined rows; filtering here keeps sleep from aborting on one.
+    if (isQuarantineScope(entry.scope ?? null))
+        return false;
+    // Before the score: these rows describe one project only, and a git seed's 'error' tag clears the bar.
+    if (entry.tags.some((t) => NEVER_AUTO_SHARE_TAGS.has(t)) || entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX)) {
+        if (stats)
+            stats.neverAutoShareSkipped = (stats.neverAutoShareSkipped ?? 0) + 1;
+        return false;
+    }
+    const score = transferScore(entry);
+    if (score < minScore)
+        return false;
+    // Skip if already shared (same text apart from spacing)
+    if (globalContentSet.has(duplicateKey(entry.content)))
+        return false;
+    // Secret producer veto: secret rows never auto-share, regardless of
+    // transfer score. (shareMemory would throw; filtering here keeps the
+    // sleep pipeline fail-safe.) Checked LAST so the stats counter
+    // only counts rows the veto actually withheld — a row failing the score
+    // or dedupe gates was never going to share, secret or not.
+    if (detectSecret(entry).flagged) {
+        if (stats)
+            stats.secretSkipped++;
+        return false;
+    }
+    return true;
+}
+// Rejection containment (sync/promote/share copy paths must not let ONE rejected
+// candidate kill the batch): shareMemory -> writeEntry hits the LIVE guard
+// against the GLOBAL store's tombstones. A matching candidate throws
+// RejectedValueError, which (uncaught) would abort this whole loop and,
+// via api.ts's sleep pipeline, the entire autoShare sleep phase. Mirrors
+// syncGlobalToLocal's per-item catch just above in this file. writeEntry's
+// own catch already writes the reject_refusal audit before rethrowing,
+// so do not double-audit here, just count and continue.
+function shareCandidates(localRoot, candidates, stats) {
+    const shared = [];
+    let rejectedSkipped = 0;
+    for (const entry of candidates) {
+        try {
+            // skipEmbed: batching invariant, this is a batch producer, so it embeds
+            // once via embedAll() below rather than once per row inside shareMemory.
+            const result = shareMemory(localRoot, entry.id, { force: true, skipEmbed: true });
+            if (result)
+                shared.push(result);
+        }
+        catch (err) {
+            if (err instanceof RejectedValueError) {
+                rejectedSkipped++;
+                if (stats)
+                    stats.rejectedSkipped = (stats.rejectedSkipped ?? 0) + 1;
+                continue;
+            }
+            throw err;
+        }
+    }
+    if (rejectedSkipped > 0) {
+        log.warn(`autoShare: skipped ${rejectedSkipped} candidate(s) refused by the global store's rejection tombstone`);
+    }
+    return shared;
+}
 /**
  * Auto-share: local memories with high transfer scores, not already global, no NEVER_AUTO_SHARE_TAGS tag.
  * Returns the list of shared entries.
  *
- * L9: `options.tenantId` is opt-in. When provided, the LOCAL-entries read is
+ * `options.tenantId` is opt-in. When provided, the LOCAL-entries read is
  * scoped to that tenant. When undefined, the local read is host-wide (current
  * behaviour). The GLOBAL-entries read is always unioned — the global root IS
- * the cross-tenant aggregate by design. The only intentional unscoped
- * internal caller as of v1.12.1 is `api.sleep` (`src/api.ts:2041`), which
- * passes options without tenantId because `sleep` is host-wide by intent;
- * see `src/api.ts:2073-2077` for the cross-tenant dedup rationale.
+ * the cross-tenant aggregate by design. `api.sleep` passes no tenantId
+ * because `sleep` is host-wide by intent.
  *
- * v1.25.0: `options.stats` is an opt-in out-param. When provided,
+ * `options.stats` is an opt-in out-param. When provided,
  * `stats.secretSkipped` is incremented once per row that passed every OTHER
  * admission gate (transfer score, not-already-global) and was withheld SOLELY
  * by the secret veto — i.e. it counts shares actually prevented, not secret
  * rows merely present. Filled identically under `dryRun`.
  *
- * AT1: `stats.rejectedSkipped` (optional) is incremented once per candidate
+ * `stats.rejectedSkipped` (optional) is incremented once per candidate
  * refused by the GLOBAL store's rejection tombstone (RejectedValueError from
  * shareMemory -> writeEntry). Unlike secretSkipped, this can only be
  * detected by attempting the write — `dryRun` returns candidates before the
@@ -399,73 +455,15 @@ export function autoShare(localRoot, options = {}) {
     const localEntries = loadAllEntries(localRoot, options.tenantId);
     initGlobal();
     const globalRoot = getGlobalRoot();
-    // L9: host-wide read. The global store IS the union across all tenants;
+    // Host-wide read. The global store IS the union across all tenants;
     // per-tenant filtering on the global root would defeat the purpose.
     const globalEntries = loadAllEntries(globalRoot);
     // Build set of global content hashes to avoid duplicates
     const globalContentSet = storedTextKeys(globalEntries);
-    const candidates = localEntries.filter((entry) => {
-        // CD5: shareMemory refuses quarantined rows; filtering here keeps sleep from aborting on one.
-        if (isQuarantineScope(entry.scope ?? null))
-            return false;
-        // Before the score: these rows describe one project only, and a git seed's 'error' tag clears the bar.
-        if (entry.tags.some((t) => NEVER_AUTO_SHARE_TAGS.has(t)) || entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX)) {
-            if (options.stats)
-                options.stats.neverAutoShareSkipped = (options.stats.neverAutoShareSkipped ?? 0) + 1;
-            return false;
-        }
-        const score = transferScore(entry);
-        if (score < minScore)
-            return false;
-        // Skip if already shared (same text apart from spacing)
-        if (globalContentSet.has(duplicateKey(entry.content)))
-            return false;
-        // v39 S4 producer veto: secret rows never auto-share, regardless of
-        // transfer score. (shareMemory would throw; filtering here keeps the
-        // sleep pipeline fail-safe.) Checked LAST (v1.25.0) so the stats counter
-        // only counts rows the veto actually withheld — a row failing the score
-        // or dedupe gates was never going to share, secret or not.
-        if (detectSecret(entry).flagged) {
-            if (options.stats)
-                options.stats.secretSkipped++;
-            return false;
-        }
-        return true;
-    });
+    const candidates = localEntries.filter((entry) => isAutoShareCandidate(entry, globalContentSet, minScore, options.stats));
     if (dryRun)
         return candidates;
-    const shared = [];
-    // AT1 containment (docs/plans/2026-08-15-at1-rejected-value-tombstone.md
-    // plan §3 — sync/promote/share copy paths must not let ONE rejected
-    // candidate kill the batch): shareMemory -> writeEntry hits the LIVE guard
-    // against the GLOBAL store's tombstones. A matching candidate throws
-    // RejectedValueError, which (uncaught) would abort this whole loop and,
-    // via api.ts's sleep pipeline, the entire autoShare sleep phase. Mirrors
-    // syncGlobalToLocal's per-item catch just above in this file. writeEntry's
-    // own catch already writes the reject_refusal audit before rethrowing
-    // (plan §3) — do not double-audit here, just count and continue.
-    let rejectedSkipped = 0;
-    for (const entry of candidates) {
-        try {
-            // skipEmbed: batching invariant, this is a batch producer, so it embeds
-            // once via embedAll() below rather than once per row inside shareMemory.
-            const result = shareMemory(localRoot, entry.id, { force: true, skipEmbed: true });
-            if (result)
-                shared.push(result);
-        }
-        catch (err) {
-            if (err instanceof RejectedValueError) {
-                rejectedSkipped++;
-                if (options.stats)
-                    options.stats.rejectedSkipped = (options.stats.rejectedSkipped ?? 0) + 1;
-                continue;
-            }
-            throw err;
-        }
-    }
-    if (rejectedSkipped > 0) {
-        log.warn(`autoShare: skipped ${rejectedSkipped} candidate(s) refused by the global store's rejection tombstone`);
-    }
+    const shared = shareCandidates(localRoot, candidates, options.stats);
     if (shared.length > 0) {
         void embedAll(globalRoot).catch((err) => logEmbedAllFailure('autoShare', err));
     }
@@ -479,18 +477,18 @@ export function autoShare(localRoot, options = {}) {
 export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
     if (!fs.existsSync(globalRoot))
         return 0;
-    // L9: host-wide read. syncGlobalToLocal copies the global union into a
+    // Host-wide read. syncGlobalToLocal copies the global union into a
     // tenant-scoped local store; writeEntry on each row carries the tenant if
     // the local-root context provides one.
     const globalEntries = loadAllEntries(globalRoot);
     const localIndex = loadIndex(localRoot);
     const textKey = (e) => `${e.tenantId}\n${e.content}`;
     const localText = new Set(loadAllEntries(localRoot).map(textKey));
-    // v39 (codex P1-4): syncing down must not re-import what ambient context
+    // Syncing down must not re-import what ambient context
     // excludes - other-project rows are skipped by default and secret rows
     // are never copied. origin_project is preserved on the copy (writeEntry
     // only stamps when the field is missing).
-    const currentName = deriveOriginProject(path.dirname(path.resolve(localRoot)));
+    const currentProject = resolveProjectIdentity(path.dirname(path.resolve(localRoot)));
     let count = 0;
     // A locally rejected value must not come back through sync down: caught per item, printed as one line.
     let rejected = 0;
@@ -506,7 +504,7 @@ export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
         if (detectSecret(entry).flagged)
             continue;
         if (!opts.includeCrossProject &&
-            classifyOriginProject(entry.origin_project, currentName) === 'cross-project')
+            classifyOriginProject(entry.origin_project, currentProject) === 'cross-project')
             continue;
         try {
             writeEntry(localRoot, entry);

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 /**
- * E2 skill first-class object (docs/plans/2026-05-30-e2-skill-object.md).
+ * Skills as a first-class, versioned object.
  *
  * A `skill` is a reusable, agent-followable capability: an `instructions` body
  * plus an optional `trigger` ("when to apply"), evolving via the supersede delta
@@ -29,8 +29,8 @@ export declare const VALID_SKILL_STATES: ReadonlySet<SkillStatus>;
 export declare const MAX_SKILL_NAME_LEN = 256;
 export declare const MAX_SKILL_INSTRUCTIONS_LEN = 8192;
 export declare const MAX_SKILL_TRIGGER_LEN = 1024;
-/** Aggregate bound on a single export render (plan-eng-critic: cap the unbounded
- *  export body). Realistic active-skill counts are tens; 1000 is a generous bound. */
+/** Aggregate bound on a single export render so the export body is never unbounded.
+ *  Realistic active-skill counts are tens; 1000 is a generous bound. */
 export declare const MAX_EXPORT_SKILLS = 1000;
 export interface Skill {
     id: number;

package/dist/skills.js

@@ -1,5 +1,5 @@
 /**
- * E2 skill first-class object (docs/plans/2026-05-30-e2-skill-object.md).
+ * Skills as a first-class, versioned object.
  *
  * A `skill` is a reusable, agent-followable capability: an `instructions` body
  * plus an optional `trigger` ("when to apply"), evolving via the supersede delta
@@ -39,13 +39,13 @@ export const VALID_SKILL_STATES = new Set([
 export const MAX_SKILL_NAME_LEN = 256;
 export const MAX_SKILL_INSTRUCTIONS_LEN = 8192;
 export const MAX_SKILL_TRIGGER_LEN = 1024;
-/** Aggregate bound on a single export render (plan-eng-critic: cap the unbounded
- *  export body). Realistic active-skill counts are tens; 1000 is a generous bound. */
+/** Aggregate bound on a single export render so the export body is never unbounded.
+ *  Realistic active-skill counts are tens; 1000 is a generous bound. */
 export const MAX_EXPORT_SKILLS = 1000;
 /**
  * Validate + normalise skill fields. skill_name is trimmed and MUST be a single
- * line (no newlines) so it cannot break the H2 header in the export render
- * (plan-eng-critic). instructions are kept verbatim (operator content) but capped.
+ * line (no newlines) so it cannot break the H2 header in the export render.
+ * instructions are kept verbatim (operator content) but capped.
  * Returns the normalised name + trigger (null when absent/empty).
  */
 function validateSkillFields(skillName, instructions, trigger) {
@@ -69,8 +69,8 @@ function validateSkillFields(skillName, instructions, trigger) {
             throw new BadRequestError(`saveSkill: trigger exceeds the ${MAX_SKILL_TRIGGER_LEN}-char cap`);
         }
         // Single-line, like skill_name: a trigger is a short "when to apply" phrase,
-        // and a newline would let it forge a heading inside the export **When:** line
-        // (independent-review 2026-05-30). Reject rather than emit a multi-line trigger.
+        // and a newline would let it forge a heading inside the export **When:** line.
+        // Reject rather than emit a multi-line trigger.
         if (/[\r\n]/.test(trigger)) {
             throw new BadRequestError('saveSkill: trigger must be a single line (no newlines)');
         }
@@ -111,9 +111,76 @@ function buildSkillContent(skillName, instructions, trigger) {
     content += `\n\n${instructions}`;
     return content;
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
+// Preflight the supersede target BEFORE inserting the new row (so the new
+// autoincrement id can never be its own supersede target); read the
+// predecessor version in the same SELECT for server-derived versioning.
+// Mirrors saveProcess / savePolicy.
+function preflightSkillSupersede(db, tenantId, supersedesId) {
+    // SAFETY: row shape matches the `status, version` columns named in the SELECT below.
+    const pred = db.prepare(`SELECT status, version FROM skills WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
+    if (!pred) {
+        throw new NotFoundError(`saveSkill: skill ${supersedesId} to supersede not found for tenant ${tenantId}`);
+    }
+    if (pred.status !== 'active') {
+        throw new ConflictError(`saveSkill: skill ${supersedesId} is not active (status='${pred.status}'); only active skills can be superseded.`);
+    }
+    return pred.version + 1;
+}
+function insertSkillRow(db, memoryId, w, version) {
+    const result = db.prepare(`
+    INSERT INTO skills(
+      memory_id, tenant_id, skill_name, instructions, trigger_text, version,
+      status, superseded_by, superseded_at, change_summary, closed_at, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
+  `).run(memoryId, w.tenantId, w.name, w.instructions, w.trigger, version, w.changeSummary, w.now);
+    return Number(result.lastInsertRowid ?? 0);
+}
+function supersedeSkillRow(db, w, supersedesId, skillId, version) {
+    const sup = db.prepare(`
+    UPDATE skills
+    SET status = 'superseded', superseded_by = ?, superseded_at = ?
+    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
+  `).run(skillId, w.now, supersedesId, w.tenantId, skillId);
+    if (sup.changes === 0) {
+        throw new ConflictError(`saveSkill: skill ${supersedesId} could not be superseded (no longer active or self-reference).`);
+    }
+    appendAuditEvent(db, {
+        tenantId: w.tenantId,
+        actor: w.actor,
+        op: 'skill_supersede',
+        targetId: String(supersedesId),
+        metadata: {
+            skill_id: supersedesId,
+            superseded_by: skillId,
+            new_version: version,
+        },
+    });
+}
+/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
+function writeSkillRow(db, memoryId, w) {
+    const version = w.supersedesId !== undefined ? preflightSkillSupersede(db, w.tenantId, w.supersedesId) : 1;
+    const skillId = insertSkillRow(db, memoryId, w, version);
+    if (w.supersedesId !== undefined)
+        supersedeSkillRow(db, w, w.supersedesId, skillId, version);
+    // SAFETY: row's shape matches the columns named in SKILL_COLS above.
+    const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ?`)
+        .get(skillId);
+    if (!row)
+        throw new Error('saveSkill: failed to reload saved skill row');
+    // GDPR-light metadata: ids + flags only, no skill text.
+    appendAuditEvent(db, {
+        tenantId: w.tenantId,
+        actor: w.actor,
+        op: 'skill_create',
+        targetId: String(skillId),
+        metadata: {
+            skill_id: skillId,
+            version,
+            has_trigger: w.trigger !== null,
+        },
+    });
+    return row;
+}
 /**
  * Create a skill (or a new version that supersedes an existing one). Writes the
  * memory mirror + the skills row atomically inside writeEntry's SAVEPOINT. When
@@ -137,72 +204,21 @@ export function saveSkill(hippoRoot, tenantId, opts, actor = 'cli') {
         baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
         tenantId,
     });
+    const w = {
+        tenantId,
+        actor,
+        name,
+        instructions: opts.instructions,
+        trigger,
+        changeSummary,
+        supersedesId: opts.supersedesSkillId,
+        now,
+    };
     let savedRow;
     writeEntry(hippoRoot, mem, {
         actor,
         afterWrite: (db, memoryId) => {
-            // Preflight the supersede target BEFORE inserting the new row (so the new
-            // autoincrement id can never be its own supersede target); read the
-            // predecessor version in the same SELECT for server-derived versioning.
-            // Mirrors saveProcess / savePolicy (codex P1 2026-05-28).
-            let version = 1;
-            if (opts.supersedesSkillId !== undefined) {
-                // SAFETY: row shape matches the `status, version` columns named in the SELECT below.
-                const pred = db.prepare(`SELECT status, version FROM skills WHERE id = ? AND tenant_id = ?`).get(opts.supersedesSkillId, tenantId);
-                if (!pred) {
-                    throw new NotFoundError(`saveSkill: skill ${opts.supersedesSkillId} to supersede not found for tenant ${tenantId}`);
-                }
-                if (pred.status !== 'active') {
-                    throw new ConflictError(`saveSkill: skill ${opts.supersedesSkillId} is not active (status='${pred.status}'); only active skills can be superseded.`);
-                }
-                version = pred.version + 1;
-            }
-            const result = db.prepare(`
-        INSERT INTO skills(
-          memory_id, tenant_id, skill_name, instructions, trigger_text, version,
-          status, superseded_by, superseded_at, change_summary, closed_at, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
-      `).run(memoryId, tenantId, name, opts.instructions, trigger, version, changeSummary, now);
-            const skillId = Number(result.lastInsertRowid ?? 0);
-            if (opts.supersedesSkillId !== undefined) {
-                const sup = db.prepare(`
-          UPDATE skills
-          SET status = 'superseded', superseded_by = ?, superseded_at = ?
-          WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-        `).run(skillId, now, opts.supersedesSkillId, tenantId, skillId);
-                if (sup.changes === 0) {
-                    throw new ConflictError(`saveSkill: skill ${opts.supersedesSkillId} could not be superseded (no longer active or self-reference).`);
-                }
-                appendAuditEvent(db, {
-                    tenantId,
-                    actor,
-                    op: 'skill_supersede',
-                    targetId: String(opts.supersedesSkillId),
-                    metadata: {
-                        skill_id: opts.supersedesSkillId,
-                        superseded_by: skillId,
-                        new_version: version,
-                    },
-                });
-            }
-            // SAFETY: row's shape matches the columns named in SKILL_COLS above.
-            const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ?`)
-                .get(skillId);
-            if (!row)
-                throw new Error('saveSkill: failed to reload saved skill row');
-            savedRow = row;
-            // GDPR-light metadata: ids + flags only, no skill text.
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'skill_create',
-                targetId: String(skillId),
-                metadata: {
-                    skill_id: skillId,
-                    version,
-                    has_trigger: trigger !== null,
-                },
-            });
+            savedRow = writeSkillRow(db, memoryId, w);
         },
     });
     if (!savedRow) {

package/dist/store/audit-event.d.ts

@@ -1,7 +1,7 @@
 import { openHippoDb } from '../db.js';
 import { type AuditOp } from '../audit.js';
 import { RejectedValueError } from '../rejection.js';
-import type { JsonValue } from './rows.js';
+import type { JsonValue } from '../json.js';
 /**
  * Emit an audit event for a mutation against `db`. Wrapped so a broken audit
  * log can never crash the surrounding mutation — the SQLite store is still the
@@ -9,7 +9,7 @@ import type { JsonValue } from './rows.js';
  */
 export declare function audit(db: ReturnType<typeof openHippoDb>, op: AuditOp, targetId?: string, metadata?: Record<string, JsonValue>, actor?: string, tenantId?: string): void;
 /**
- * Refusal audit for the AT1 rejection guard (plan §3). Written by the
+ * Refusal audit for the rejected-value guard. Written by the
  * transaction OWNER post-rollback — writeEntry's catch (no outer tx exists
  * there, so this lands in a fresh implicit transaction) and api.supersede's
  * catch (after its own ROLLBACK) — never inside a scope the caller's own

package/dist/store/audit-event.js

@@ -21,7 +21,7 @@ export function audit(db, op, targetId, metadata, actor = 'cli', tenantId) {
     }
 }
 /**
- * Refusal audit for the AT1 rejection guard (plan §3). Written by the
+ * Refusal audit for the rejected-value guard. Written by the
  * transaction OWNER post-rollback — writeEntry's catch (no outer tx exists
  * there, so this lands in a fresh implicit transaction) and api.supersede's
  * catch (after its own ROLLBACK) — never inside a scope the caller's own

package/dist/store/candidates.d.ts

@@ -16,8 +16,8 @@ export declare function loadAmbientCandidates(hippoRoot: string, tenantId: strin
 export interface ContextCandidateFilter {
     /** Envelope scope asked for by name; absent applies recall's default deny. */
     exactScope?: string;
-    /** Rows of this project and user-global rows pass; absent admits every origin. */
-    project?: string;
+    /** Rows carrying one of these project names, and user-global rows, pass; absent admits every origin. */
+    project?: readonly string[];
     /** Most rows returned; past it, the rows decay has worn least win. */
     cap: number;
     now: Date;

package/dist/store/candidates.js

@@ -2,6 +2,7 @@ import { closeHippoDb } from '../db.js';
 import { RECALL_DEFAULT_DENY_SCOPES } from '../recall-scope.js';
 import { MEMORY_SELECT_COLUMNS, rowToEntry, parseJsonArray } from './rows.js';
 import { openStore } from './open.js';
+import { originInSql } from '../project-identity.js';
 import { pickRarestFtsQuery, loadRecallSearchEntriesFromDb } from './search-rows.js';
 const AMBIENT_SCOPED = 'superseded_by IS NULL AND tenant_id = ?';
 /** Exported so the plan test runs the exact SQL; idx_memories_pinned (db.ts v51) serves it. */
@@ -9,7 +10,7 @@ export const AMBIENT_PINNED_WHERE = `pinned = 1 AND ${AMBIENT_SCOPED} ORDER BY c
 /** Exported so the plan test runs the exact SQL; idx_memories_created_drift (db.ts v51) serves it. */
 export const AMBIENT_DRIFT_SQL = `SELECT 1 FROM memories WHERE ${AMBIENT_SCOPED} AND (length(created) <> 24 OR created NOT LIKE '%Z') LIMIT 1`;
 // The pins plus the `recentNeeded` newest rows that pass `admit`, for ambient
-// injection. One connection; `recall` piggybacks the Z1 FTS query on it too.
+// injection. One connection; `recall` piggybacks the prompt-recall FTS query on it too.
 export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit, recall) {
     // A SQL LIMIT takes an integer; the Array.slice this replaced truncated one,
     // and include_recent is any non-negative finite number at the HTTP edge.
@@ -78,8 +79,8 @@ export function loadContextCandidates(hippoRoot, tenantId, filter) {
         params.push(...RECALL_DEFAULT_DENY_SCOPES);
     }
     if (filter.project !== undefined) {
-        where.push(`(origin_project = '' OR origin_project = ?)`);
-        params.push(filter.project);
+        where.push(`(origin_project = '' OR ${originInSql(filter.project)})`);
+        params.push(...filter.project);
     }
     const db = openStore(hippoRoot);
     try {