hippo-memory 1.69.0 → 1.71.0

package/dist/connectors/github/cli-impl.js

@@ -1,227 +0,0 @@
-/**
- * Implementation of `hippo github` CLI subcommands. Extracted from the main
- * cli.ts so unit tests can import these functions directly without triggering
- * the cli.ts main() side effects. The cli.ts dispatcher re-exports the
- * top-level cmdGithub.
- *
- * Subcommands mirror the Slack connector shape (cli.ts §Slack subcommands):
- *   - hippo github backfill --repo <owner/name> [--since ISO] [--max <N>]
- *   - hippo github dlq list
- *   - hippo github dlq replay <id> [--force]
- */
-import { envGithubToken, envGithubWebhookSecret, envGithubWebhookSecretPrevious } from '../../env.js';
-import { adminActor } from '../../api.js';
-import { openHippoDb, closeHippoDb } from '../../db.js';
-import { resolveTenantId } from '../../tenant.js';
-import { backfillRepo } from './backfill.js';
-import { realGitHubFetcher } from './octokit-client.js';
-import { listDlq, replayDlqEntry } from './dlq.js';
-import { ingestEvent } from './ingest.js';
-import { handleCommentDeleted } from './deletion.js';
-import { computeDeletionKey } from './signature.js';
-import { isGitHubIssueEvent, isGitHubIssueCommentEvent, isGitHubPullRequestEvent, isGitHubPullRequestReviewCommentEvent, } from './types.js';
-function isFlagString(value) {
-    return typeof value === 'string';
-}
-// FlagValue never includes `number` (see its declaration above), so a
-// `value is number` predicate directly on FlagValue would not type-check —
-// the generic wrapper narrows a value of any type T instead.
-function isNumberLike(value) {
-    return typeof value === 'number';
-}
-function isFlagValueNumberLike(value) {
-    return isNumberLike(value);
-}
-/**
- * Map a parsed envelope + eventName header to an IngestEvent discriminated
- * union. Returns null for unknown event types or shapes that don't pass the
- * type guards.
- */
-function parsedToIngestEvent(parsed, eventName) {
-    if (eventName === 'issues' && isGitHubIssueEvent(parsed, eventName)) {
-        return { eventName: 'issues', payload: parsed };
-    }
-    if (eventName === 'issue_comment' && isGitHubIssueCommentEvent(parsed, eventName)) {
-        return { eventName: 'issue_comment', payload: parsed };
-    }
-    if (eventName === 'pull_request' && isGitHubPullRequestEvent(parsed, eventName)) {
-        return { eventName: 'pull_request', payload: parsed };
-    }
-    if (eventName === 'pull_request_review_comment' &&
-        isGitHubPullRequestReviewCommentEvent(parsed, eventName)) {
-        return { eventName: 'pull_request_review_comment', payload: parsed };
-    }
-    return null;
-}
-// Console lines below are the `hippo github` command's printed result and usage text, so they stay off the logger.
-export function printGithubBackfillUsage() {
-    console.log('hippo github backfill --repo <owner/name> [--since ISO] [--max <N>]');
-    console.log('  --repo   GitHub repository in owner/name format (required, e.g. acme/widgets)');
-    console.log('  --since  Initial high-water-mark for first run (optional, ISO 8601)');
-    console.log('  --max    Cap items per stream (optional, integer)');
-    console.log('  Requires GITHUB_TOKEN env var with repo read scope.');
-}
-/**
- * `hippo github backfill`. The fetcher is injectable so tests can drive the
- * code path without hitting the network. Defaults to `realGitHubFetcher`.
- */
-export async function cmdGithubBackfill(hippoRoot, flags, fetcher = realGitHubFetcher) {
-    const repo = flags['repo'];
-    if (!isFlagString(repo) || !repo.includes('/')) {
-        printGithubBackfillUsage();
-        process.exit(2);
-    }
-    const token = envGithubToken();
-    if (!token) {
-        console.error('GITHUB_TOKEN is not set. Backfill requires a personal access token with repo read scope.');
-        process.exit(2);
-    }
-    const maxRaw = flags['max'];
-    let maxPerStream;
-    if (isFlagString(maxRaw) || isFlagValueNumberLike(maxRaw)) {
-        const parsed = Number(maxRaw);
-        if (Number.isFinite(parsed) && parsed > 0) {
-            maxPerStream = Math.floor(parsed);
-        }
-    }
-    const sinceFlag = flags['since'];
-    const sinceIso = isFlagString(sinceFlag) ? sinceFlag : undefined;
-    const tenantId = resolveTenantId({});
-    // Seed the github_cursors row so all 3 streams use --since on a fresh run.
-    // COALESCE preserves any existing HWM (subsequent runs ignore --since for
-    // streams that already drained at least once — same idempotency story as
-    // Slack's slack_cursors).
-    if (sinceIso) {
-        const db = openHippoDb(hippoRoot);
-        try {
-            db.prepare(`INSERT INTO github_cursors (tenant_id, repo_full_name, issues_hwm, issue_comments_hwm, pr_review_comments_hwm, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?)
-         ON CONFLICT(tenant_id, repo_full_name) DO UPDATE SET
-           issues_hwm = COALESCE(github_cursors.issues_hwm, excluded.issues_hwm),
-           issue_comments_hwm = COALESCE(github_cursors.issue_comments_hwm, excluded.issue_comments_hwm),
-           pr_review_comments_hwm = COALESCE(github_cursors.pr_review_comments_hwm, excluded.pr_review_comments_hwm),
-           updated_at = excluded.updated_at`).run(tenantId, repo, sinceIso, sinceIso, sinceIso, new Date().toISOString());
-        }
-        finally {
-            closeHippoDb(db);
-        }
-    }
-    const ctx = {
-        hippoRoot,
-        tenantId,
-        actor: adminActor('cli:github-backfill'),
-    };
-    try {
-        const result = await backfillRepo(ctx, {
-            repoFullName: repo,
-            fetcher,
-            token,
-            maxPerStream,
-        });
-        console.log(JSON.stringify(result, null, 2));
-    }
-    catch (e) {
-        // SAFETY: this is a best-effort error message only; property access on
-        // any JS value is safe (undefined if absent), preserving the existing
-        // lenient formatting even when something non-Error was thrown.
-        console.error('backfill failed:', e.message);
-        process.exit(3);
-    }
-}
-export function cmdGithubDlqList(hippoRoot, _flags) {
-    const db = openHippoDb(hippoRoot);
-    try {
-        const tenantId = resolveTenantId({});
-        const items = listDlq(db, { tenantId });
-        if (items.length === 0) {
-            console.log('no entries');
-            return;
-        }
-        for (const it of items) {
-            console.log(`${it.id}\t${it.bucket}\t${it.tenantId}\t${it.eventName ?? '-'}\t${it.receivedAt}\t${it.error}`);
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export async function cmdGithubDlqReplay(hippoRoot, args, flags) {
-    const idArg = args[0];
-    if (!idArg) {
-        console.error('Usage: hippo github dlq replay <id> [--force]');
-        process.exit(1);
-    }
-    const id = Number(idArg);
-    if (!Number.isFinite(id) || !Number.isInteger(id) || id < 1) {
-        console.error(`replay: invalid id ${idArg}`);
-        process.exit(1);
-    }
-    const force = flags['force'] === true;
-    const ctx = {
-        hippoRoot,
-        tenantId: resolveTenantId({}),
-        actor: adminActor('cli:github-dlq-replay'),
-    };
-    // Without an ingestHook replay only bumps retry_count while printing "replay ok"; the real hook re-runs ingest.
-    const result = await replayDlqEntry(ctx, id, {
-        force,
-        webhookSecret: envGithubWebhookSecret(),
-        previousSecret: envGithubWebhookSecretPrevious(),
-        ingestHook: async (innerCtx, args) => {
-            const parsed = JSON.parse(args.rawPayload);
-            const event = parsedToIngestEvent(parsed, args.eventName);
-            if (!event) {
-                return { memoryId: null };
-            }
-            // A replayed comment `.deleted` row must route to the deletion handler, NOT to ingestEvent,
-            // which would write the deleted comment as a NEW raw memory instead of archiving the matching ones.
-            if ((event.eventName === 'issue_comment' || event.eventName === 'pull_request_review_comment') &&
-                event.payload.action === 'deleted') {
-                const repo = event.payload.repository?.full_name ?? '';
-                const artifactRef = event.eventName === 'issue_comment'
-                    ? `github://${repo}/issue/${event.payload.issue.number}/comment/${event.payload.comment.id}`
-                    : `github://${repo}/pull/${event.payload.pull_request.number}/review_comment/${event.payload.comment.id}`;
-                const idempotencyKey = computeDeletionKey(artifactRef, event.payload.comment.updated_at ?? null);
-                const r = handleCommentDeleted(innerCtx, {
-                    artifactRef,
-                    idempotencyKey,
-                    deliveryId: args.deliveryId,
-                    eventName: event.eventName,
-                });
-                // archivedCount maps to memoryId only loosely — return null since the
-                // archive operation can affect multiple rows. The replay-result audit
-                // trail is in github_dlq.retry_count + retried_at.
-                return { memoryId: r.archivedCount > 0 ? 'archived' : null };
-            }
-            const r = ingestEvent(innerCtx, {
-                event,
-                rawBody: args.rawPayload,
-                deliveryId: args.deliveryId,
-            });
-            return { memoryId: r.memoryId };
-        },
-    });
-    if (!result.ok) {
-        console.error(`replay failed: status=${result.status} retry_count=${result.retryCount}${result.reason ? ` reason=${result.reason}` : ''}`);
-        process.exit(1);
-    }
-    console.log(`replay ok: status=${result.status} memory_id=${result.memoryId ?? '(none)'} retry_count=${result.retryCount}`);
-}
-export async function cmdGithub(hippoRoot, args, flags) {
-    const sub = args[0];
-    if (sub === 'backfill') {
-        await cmdGithubBackfill(hippoRoot, flags);
-        return;
-    }
-    if (sub === 'dlq' && args[1] === 'list') {
-        cmdGithubDlqList(hippoRoot, flags);
-        return;
-    }
-    if (sub === 'dlq' && args[1] === 'replay') {
-        await cmdGithubDlqReplay(hippoRoot, args.slice(2), flags);
-        return;
-    }
-    console.error('Usage: hippo github <backfill|dlq list|dlq replay <id> [--force]> [...]');
-    process.exit(1);
-}
-//# sourceMappingURL=cli-impl.js.map

package/dist/connectors/github/idempotency.d.ts

@@ -1,19 +0,0 @@
-import type { DatabaseSyncLike } from '../../db.js';
-/**
- * Thrown by ingest's afterWrite hook when a concurrent worker has already
- * inserted github_event_log for the same idempotency_key. Roll back the
- * SAVEPOINT so exactly one memory row exists per key.
- */
-export declare class DuplicateIdempotencyError extends Error {
-    readonly idempotencyKey: string;
-    constructor(idempotencyKey: string);
-}
-export declare function hasSeenKey(db: DatabaseSyncLike, idempotencyKey: string): boolean;
-export declare function markKeySeen(db: DatabaseSyncLike, args: {
-    idempotencyKey: string;
-    deliveryId: string;
-    eventName: string;
-    memoryId: string | null;
-}): void;
-export declare function lookupMemoryByKey(db: DatabaseSyncLike, idempotencyKey: string): string | null;
-//# sourceMappingURL=idempotency.d.ts.map

package/dist/connectors/github/idempotency.js

@@ -1,27 +0,0 @@
-/**
- * Thrown by ingest's afterWrite hook when a concurrent worker has already
- * inserted github_event_log for the same idempotency_key. Roll back the
- * SAVEPOINT so exactly one memory row exists per key.
- */
-export class DuplicateIdempotencyError extends Error {
-    idempotencyKey;
-    constructor(idempotencyKey) {
-        super(`duplicate github idempotency_key: ${idempotencyKey}`);
-        this.name = 'DuplicateIdempotencyError';
-        this.idempotencyKey = idempotencyKey;
-    }
-}
-export function hasSeenKey(db, idempotencyKey) {
-    const row = db.prepare(`SELECT 1 FROM github_event_log WHERE idempotency_key = ?`).get(idempotencyKey);
-    return !!row;
-}
-export function markKeySeen(db, args) {
-    db.prepare(`INSERT OR IGNORE INTO github_event_log (idempotency_key, delivery_id, event_name, ingested_at, memory_id) VALUES (?, ?, ?, ?, ?)`).run(args.idempotencyKey, args.deliveryId, args.eventName, new Date().toISOString(), args.memoryId);
-}
-export function lookupMemoryByKey(db, idempotencyKey) {
-    // SAFETY: the row comes from the SELECT above, which projects exactly the
-    // memory_id column of github_event_log.
-    const row = db.prepare(`SELECT memory_id FROM github_event_log WHERE idempotency_key = ?`).get(idempotencyKey);
-    return row?.memory_id ?? null;
-}
-//# sourceMappingURL=idempotency.js.map

package/dist/connectors/slack/idempotency.d.ts

@@ -1,17 +0,0 @@
-import type { DatabaseSyncLike } from '../../db.js';
-/**
- * Thrown by the ingest afterWrite hook when a concurrent worker has already
- * inserted slack_event_log for the same event_id. The throw propagates out of
- * writeEntry's SAVEPOINT, rolling back the duplicate memory write so exactly
- * one memory row exists per Slack event_id even under two-worker races.
- *
- * Caller maps to `{status: 'skipped_duplicate'}` at the public API boundary.
- */
-export declare class DuplicateEventError extends Error {
-    readonly eventId: string;
-    constructor(eventId: string);
-}
-export declare function hasSeenEvent(db: DatabaseSyncLike, eventId: string): boolean;
-export declare function markEventSeen(db: DatabaseSyncLike, eventId: string, memoryId: string | null): void;
-export declare function lookupMemoryByEvent(db: DatabaseSyncLike, eventId: string): string | null;
-//# sourceMappingURL=idempotency.d.ts.map

package/dist/connectors/slack/idempotency.js

@@ -1,31 +0,0 @@
-/**
- * Thrown by the ingest afterWrite hook when a concurrent worker has already
- * inserted slack_event_log for the same event_id. The throw propagates out of
- * writeEntry's SAVEPOINT, rolling back the duplicate memory write so exactly
- * one memory row exists per Slack event_id even under two-worker races.
- *
- * Caller maps to `{status: 'skipped_duplicate'}` at the public API boundary.
- */
-export class DuplicateEventError extends Error {
-    eventId;
-    constructor(eventId) {
-        super(`duplicate slack event_id: ${eventId}`);
-        this.name = 'DuplicateEventError';
-        this.eventId = eventId;
-    }
-}
-export function hasSeenEvent(db, eventId) {
-    const row = db.prepare(`SELECT 1 FROM slack_event_log WHERE event_id = ?`).get(eventId);
-    return !!row;
-}
-export function markEventSeen(db, eventId, memoryId) {
-    db.prepare(`INSERT OR IGNORE INTO slack_event_log (event_id, ingested_at, memory_id) VALUES (?, ?, ?)`)
-        .run(eventId, new Date().toISOString(), memoryId);
-}
-export function lookupMemoryByEvent(db, eventId) {
-    // SAFETY: query selects only `memory_id`, a nullable column, so a returned
-    // row has this shape; .get() returns undefined when no row matches.
-    const row = db.prepare(`SELECT memory_id FROM slack_event_log WHERE event_id = ?`).get(eventId);
-    return row?.memory_id ?? null;
-}
-//# sourceMappingURL=idempotency.js.map

package/dist/correction-latency.d.ts

@@ -1,36 +0,0 @@
-import { MemoryEntry } from './memory.js';
-export interface CorrectionPair {
-    oldId: string;
-    newId: string;
-    correctedAt: string;
-    observedAt: string;
-    latencyMs: number;
-    /** 'extraction' = new fact derived from a raw receipt; 'manual' = direct supersede call */
-    via: 'extraction' | 'manual';
-}
-export interface CorrectionLatencyReport {
-    count: number;
-    manualCount: number;
-    extractionCount: number;
-    /** Percentiles computed over `extraction` pairs only — manual pairs have no measurable lag */
-    p50Ms: number | null;
-    p95Ms: number | null;
-    maxMs: number | null;
-    pairs: CorrectionPair[];
-}
-/**
- * Correction latency = wall-clock delta between when hippo first saw the
- * change-of-truth and when the supersession actually landed.
- *
- * For each (old, new) chain via `old.superseded_by = new.id`:
- *   - `correctedAt` = `new.created` (always)
- *   - `observedAt`  = source row's `created` if `new.extracted_from` is set,
- *                     else `new.created` (no earlier observation possible)
- *
- * Pairs split into two cohorts:
- *   - `extraction` — derived from a raw receipt; latency is meaningful
- *   - `manual`     — direct supersede call; latency is trivially 0 and
- *                    excluded from percentiles to avoid masking real lag
- */
-export declare function buildCorrectionLatency(entries: MemoryEntry[]): CorrectionLatencyReport;
-//# sourceMappingURL=correction-latency.d.ts.map

package/dist/customer-notes.d.ts

@@ -1,96 +0,0 @@
-/**
- * customer_note first-class object.
- *
- * A `customer_note` is a discrete note recorded against an account/customer entity:
- * a `note` body scoped to a `customer`, evolving via the supersede delta lifecycle.
- * Entity-scoping is a free-form `customer` column (the `entities` table is unbuilt,
- * so an FK is deferred). Unlike project_brief's one-summary-per-repo,
- * a customer accrues MANY discrete notes over time, each with its own supersede chain
- * (correct a note -> a new version preserving history; close retires it).
- *
- * Reuses the project_brief/skill supersede machinery verbatim (superseded_by self-FK
- * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It has NO assembler/renderer (the simplest first-class object): the
- * contribution is purely the entity-scoping dimension.
- *
- * The `customer_notes` table is the source of truth (survives memory decay); the
- * memory mirror is for recall. memory_id is NULLABLE with ON DELETE SET NULL.
- *
- * Lifecycle: active -> superseded (a corrected version) or active -> closed (retired).
- */
-import { type KeysetPosition } from './keyset.js';
-export type NoteStatus = 'active' | 'superseded' | 'closed';
-export declare const VALID_NOTE_STATES: ReadonlySet<NoteStatus>;
-/** Field caps (untrusted at the HTTP/SDK boundary). note is a body, so a larger cap
- *  than the 4096 short-field convention. */
-export declare const MAX_CUSTOMER_LEN = 256;
-export declare const MAX_NOTE_LEN = 8192;
-export declare const MAX_CHANGE_SUMMARY_LEN = 4096;
-export interface CustomerNote {
-    id: number;
-    /** Nullable: ON DELETE SET NULL lets memory deletion proceed without breaking
-     *  the note row. */
-    memoryId: string | null;
-    tenantId: string;
-    /** The account/customer entity this note is scoped to (free-form identifier). */
-    customer: string;
-    /** The note body. */
-    note: string;
-    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
-    version: number;
-    status: NoteStatus;
-    supersededBy: number | null;
-    supersededAt: string | null;
-    /** The per-version delta note; set on a successor row only (NULL on a v1). */
-    changeSummary: string | null;
-    closedAt: string | null;
-    createdAt: string;
-}
-export interface SaveCustomerNoteOpts {
-    customer: string;
-    note: string;
-    /** The delta note for a supersession; ignored (stored NULL) on a fresh create. */
-    changeSummary?: string;
-    /** Table id of an ACTIVE note this new version supersedes. */
-    supersedesNoteId?: number;
-    /** Extra memory tags merged after ['customer_note', 'customer:<lc>']. */
-    extraTags?: string[];
-}
-export interface ListCustomerNotesOpts {
-    status?: NoteStatus;
-    /** Filter to a single customer. */
-    customer?: string;
-    limit?: number;
-    /** Resume after this row: the position the previous page ended on. */
-    after?: KeysetPosition;
-}
-/**
- * Create a customer_note (or a new version that supersedes an existing one). Writes
- * the memory mirror + the customer_notes row atomically inside writeEntry's SAVEPOINT.
- * When supersedesNoteId is given, the referenced ACTIVE row is preflighted (status +
- * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same SAVEPOINT;
- * the new version = predecessor.version + 1 (server-derived).
- *
- * The memory mirror carries a `customer:<lc>` tag (in addition to ['customer_note']
- * + caller extraTags) so scope-aware recall treats the note as entity-local. There is
- * no self-recursion path (customer_note has no receipt-query/refresh).
- */
-export declare function saveCustomerNote(hippoRoot: string, tenantId: string, opts: SaveCustomerNoteOpts, actor?: string): CustomerNote;
-/**
- * Close (retire) an active note. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. A superseded row is terminal.
- */
-export declare function closeCustomerNote(hippoRoot: string, tenantId: string, id: number, actor?: string): CustomerNote;
-export declare function loadCustomerNoteById(hippoRoot: string, tenantId: string, id: number): CustomerNote | null;
-export declare function loadCustomerNotes(hippoRoot: string, tenantId: string, opts?: ListCustomerNotesOpts): CustomerNote[];
-/**
- * All ACTIVE notes for a customer, newest first. Returns a LIST (a customer accrues
- * MANY notes) - this deliberately DIVERGES from project_brief's
- * loadActiveBriefForRepo, which returns a single brief-or-null because a repo has one
- * evolving summary. A future caller cloning the project_brief shape by analogy must
- * not assume a single-return here; the plural name signals the list contract.
- */
-export declare function loadActiveNotesForCustomer(hippoRoot: string, tenantId: string, customer: string, opts?: {
-    limit?: number;
-}): CustomerNote[];
-//# sourceMappingURL=customer-notes.d.ts.map