@dikshanty94/webnav 0.2.0

package/dist/mapstore/record.d.ts

@@ -0,0 +1,128 @@
+import Database from 'better-sqlite3';
+import type { SnapshotDiff } from '../explorer/diff.js';
+import type { ElementFingerprint } from '../playwright/fingerprint.js';
+export interface DeclaredLink {
+    to: string;
+    via: string;
+}
+export interface Observation {
+    url: string;
+    fingerprint: string[];
+    declaredLinks: DeclaredLink[];
+}
+export interface StoredObservation extends Observation {
+    seq: number;
+    capturedAt: number;
+}
+export interface ActionRef {
+    role: string;
+    name: string | null;
+    ref: string | null;
+    elementFp?: ElementFingerprint | null;
+    value?: string;
+    hover?: boolean;
+    rightClick?: boolean;
+}
+export interface ActionEffect {
+    fromUrl: string;
+    fromSnapshot: string;
+    action: ActionRef | null;
+    toUrl: string;
+    toSnapshot: string;
+    navigated: boolean;
+    diff: SnapshotDiff;
+    requestedUrl?: string;
+    nameHints?: Record<string, string>;
+}
+export interface StoredActionEffect extends ActionEffect {
+    seq: number;
+    capturedAt: number;
+}
+export interface LedgerEvent {
+    t?: number;
+    source: 'human' | 'agent';
+    kind: string;
+    descriptor: Record<string, unknown>;
+}
+export interface StoredLedgerEvent extends LedgerEvent {
+    seq: number;
+    disposition: string | null;
+}
+export interface RecordSessionInfo {
+    sessionId: string;
+    active: boolean;
+    startedAt: number;
+    stoppedAt: number | null;
+    steps: number;
+    site: string | null;
+    review?: {
+        approved: boolean;
+        gaps: number;
+        at: number;
+        model?: string;
+        reason?: string;
+    } | null;
+}
+/** Persists raw page observations per record-session. Sibling of MapStore;
+ *  same Database handle, separate tables. No clustering here — that's analyse. */
+export declare class RecordStore {
+    private db;
+    constructor(path?: string);
+    static fromDatabase(db: Database.Database): RecordStore;
+    private migrate;
+    /** Store the capture-review verdict for a session (graph-ready gate). */
+    setReview(sessionId: string, verdict: {
+        approved: boolean;
+        gaps: number;
+        at: number;
+        model?: string;
+        reason?: string;
+    }): void;
+    reviewOf(sessionId: string): {
+        approved: boolean;
+        gaps: number;
+        at: number;
+        model?: string;
+        reason?: string;
+    } | null;
+    /** Tag who recorded the session ('agent' | 'extension' | 'manual'); only sets if not already set. */
+    setOrigin(sessionId: string, origin: 'agent' | 'extension' | 'manual'): void;
+    originOf(sessionId: string): 'agent' | 'extension' | 'manual';
+    /** Record the intended start URL for a session (idempotent; only sets if given). */
+    setStartUrl(sessionId: string, url: string): void;
+    startUrl(sessionId: string): string | null;
+    /** The named profile a session runs under (null ⇒ caller applies 'default'). */
+    setProfile(sessionId: string, profile: string): void;
+    profileOf(sessionId: string): string | null;
+    /** Session ids using a given profile (for the Profiles tab count + rename). */
+    sessionsUsingProfile(profile: string): string[];
+    /** Repoint every session on `from` to `to` (rename). */
+    renameProfileRefs(from: string, to: string): void;
+    start(sessionId: string, nowMs?: number): string;
+    stop(sessionId: string, nowMs?: number): void;
+    /** Drop all buffered observations for a session (so re-recording into the same
+     *  session id replaces, not appends — the ingest receiver's default session is reused). */
+    clearSession(sessionId: string): void;
+    /** Delete a recording ENTIRELY — observations AND the session row (live finding:
+     *  clearSession alone left the row, so a "deleted" recording stayed in the list). */
+    deleteSession(sessionId: string): void;
+    /** Rename a recording's id across BOTH tables (session row + its observations). Refuses
+     *  if `to` already exists (would merge two recordings silently). Returns false if `from`
+     *  is unknown or `to` is taken. On-disk video/review dirs are moved by the CLI caller. */
+    renameSession(from: string, to: string): boolean;
+    isActive(sessionId: string): boolean;
+    append(sessionId: string, obs: Observation, nowMs?: number): void;
+    observations(sessionId: string): StoredObservation[];
+    appendActionEffect(sessionId: string, fx: ActionEffect, nowMs?: number): number | null;
+    /** Append one raw event to the session's ledger. isActive-gated like steps:
+     *  recording off = off, for BOTH capture paths. Returns the ledger seq (for the
+     *  later disposition stamp) or null when not recording. `ev.t` (the human path's
+     *  page-clock timestamp) always wins; agent-path callers that pass no `t` get
+     *  stamped with `nowMs` so the dashboard's ledger time column is never blank. */
+    appendEvent(sessionId: string, ev: LedgerEvent, nowMs?: number): number | null;
+    /** Stamp an event's fate: 'step:<stepSeq>' or 'dropped:<reason>'. */
+    stampEvent(sessionId: string, seq: number, disposition: string): void;
+    events(sessionId: string): StoredLedgerEvent[];
+    actionEffects(sessionId: string): StoredActionEffect[];
+    listSessions(): RecordSessionInfo[];
+}

package/dist/mapstore/record.js

@@ -0,0 +1,224 @@
+import Database from 'better-sqlite3';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { dbPath } from '../paths.js';
+const SCHEMA = readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'schema.sql'), 'utf8');
+/** Persists raw page observations per record-session. Sibling of MapStore;
+ *  same Database handle, separate tables. No clustering here — that's analyse. */
+export class RecordStore {
+    db;
+    constructor(path = dbPath()) {
+        this.db = new Database(path);
+        this.db.exec(SCHEMA);
+        this.migrate();
+    }
+    static fromDatabase(db) {
+        const s = Object.create(RecordStore.prototype);
+        s.db = db;
+        db.exec(SCHEMA);
+        s.migrate();
+        return s;
+    }
+    migrate() {
+        const cols = this.db.prepare('PRAGMA table_info(record_observations)').all();
+        const have = new Set(cols.map((c) => c.name));
+        for (const [col, type] of [['from_url', 'TEXT'], ['from_snapshot', 'TEXT'], ['action', 'TEXT'],
+            ['to_url', 'TEXT'], ['to_snapshot', 'TEXT'], ['navigated', 'INTEGER'], ['diff', 'TEXT'],
+            ['requested_url', 'TEXT'], ['name_hints', 'TEXT']]) {
+            if (!have.has(col))
+                this.db.exec(`ALTER TABLE record_observations ADD COLUMN ${col} ${type}`);
+        }
+        // start_url = the URL the operator ASKED to record at (not wherever an auth
+        // redirect bounced them) — so reopen returns to the product, not the login page.
+        const scols = new Set(this.db.prepare('PRAGMA table_info(record_sessions)').all().map((c) => c.name));
+        if (!scols.has('start_url'))
+            this.db.exec('ALTER TABLE record_sessions ADD COLUMN start_url TEXT');
+        // profile = the NAMED browser profile a session runs under (shared logged-in
+        // state; null ⇒ 'default'). Lets "log in once" apply across every session.
+        if (!scols.has('profile'))
+            this.db.exec('ALTER TABLE record_sessions ADD COLUMN profile TEXT');
+        // origin = who recorded this session: 'agent' (use session / use-driven CLI walk),
+        // 'extension' (the webnav Chrome extension's agent run), or 'manual' (human
+        // record-live / dashboard). Null (legacy rows) reads as 'manual'.
+        if (!scols.has('origin'))
+            this.db.exec('ALTER TABLE record_sessions ADD COLUMN origin TEXT');
+        // review = the capture-review verdict JSON ({approved, gaps, at, model, reason}) — set
+        // by `dev review`. A session is GRAPH-READY only when approved (all on-screen actions
+        // captured as steps). Null (never reviewed) reads as not-approved.
+        if (!scols.has('review'))
+            this.db.exec('ALTER TABLE record_sessions ADD COLUMN review TEXT');
+    }
+    /** Store the capture-review verdict for a session (graph-ready gate). */
+    setReview(sessionId, verdict) {
+        this.db.prepare('UPDATE record_sessions SET review=? WHERE session_id=?').run(JSON.stringify(verdict), sessionId);
+    }
+    reviewOf(sessionId) {
+        const r = this.db.prepare('SELECT review FROM record_sessions WHERE session_id=?').get(sessionId);
+        if (!r?.review)
+            return null;
+        try {
+            return JSON.parse(r.review);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Tag who recorded the session ('agent' | 'extension' | 'manual'); only sets if not already set. */
+    setOrigin(sessionId, origin) {
+        this.db.prepare('UPDATE record_sessions SET origin=? WHERE session_id=? AND origin IS NULL').run(origin, sessionId);
+    }
+    originOf(sessionId) {
+        const r = this.db.prepare('SELECT origin FROM record_sessions WHERE session_id=?').get(sessionId);
+        return r?.origin === 'agent' || r?.origin === 'extension' ? r.origin : 'manual'; // legacy/null → manual
+    }
+    /** Record the intended start URL for a session (idempotent; only sets if given). */
+    setStartUrl(sessionId, url) {
+        this.db.prepare('UPDATE record_sessions SET start_url=? WHERE session_id=?').run(url, sessionId);
+    }
+    startUrl(sessionId) {
+        const r = this.db.prepare('SELECT start_url FROM record_sessions WHERE session_id=?').get(sessionId);
+        return r?.start_url ?? null;
+    }
+    /** The named profile a session runs under (null ⇒ caller applies 'default'). */
+    setProfile(sessionId, profile) {
+        this.db.prepare('UPDATE record_sessions SET profile=? WHERE session_id=?').run(profile, sessionId);
+    }
+    profileOf(sessionId) {
+        const r = this.db.prepare('SELECT profile FROM record_sessions WHERE session_id=?').get(sessionId);
+        return r?.profile ?? null;
+    }
+    /** Session ids using a given profile (for the Profiles tab count + rename). */
+    sessionsUsingProfile(profile) {
+        return this.db.prepare('SELECT session_id FROM record_sessions WHERE profile=?').all(profile).map((r) => r.session_id);
+    }
+    /** Repoint every session on `from` to `to` (rename). */
+    renameProfileRefs(from, to) {
+        this.db.prepare('UPDATE record_sessions SET profile=? WHERE profile=?').run(to, from);
+    }
+    start(sessionId, nowMs = Date.now()) {
+        this.db.prepare(`INSERT INTO record_sessions (session_id,active,started_at) VALUES (?,1,?)
+       ON CONFLICT(session_id) DO UPDATE SET active=1, started_at=?, stopped_at=NULL`)
+            .run(sessionId, nowMs, nowMs);
+        return sessionId;
+    }
+    stop(sessionId, nowMs = Date.now()) {
+        this.db.prepare('UPDATE record_sessions SET active=0, stopped_at=? WHERE session_id=?')
+            .run(nowMs, sessionId);
+    }
+    /** Drop all buffered observations for a session (so re-recording into the same
+     *  session id replaces, not appends — the ingest receiver's default session is reused). */
+    clearSession(sessionId) {
+        this.db.prepare('DELETE FROM record_observations WHERE session_id=?').run(sessionId);
+        this.db.prepare('DELETE FROM record_events WHERE session_id=?').run(sessionId);
+    }
+    /** Delete a recording ENTIRELY — observations AND the session row (live finding:
+     *  clearSession alone left the row, so a "deleted" recording stayed in the list). */
+    deleteSession(sessionId) {
+        this.clearSession(sessionId);
+        this.db.prepare('DELETE FROM record_sessions WHERE session_id=?').run(sessionId);
+    }
+    /** Rename a recording's id across BOTH tables (session row + its observations). Refuses
+     *  if `to` already exists (would merge two recordings silently). Returns false if `from`
+     *  is unknown or `to` is taken. On-disk video/review dirs are moved by the CLI caller. */
+    renameSession(from, to) {
+        if (from === to)
+            return true;
+        const exists = (id) => !!this.db.prepare('SELECT 1 FROM record_sessions WHERE session_id=?').get(id);
+        if (!exists(from) || exists(to))
+            return false;
+        this.db.transaction(() => {
+            this.db.prepare('UPDATE record_sessions SET session_id=? WHERE session_id=?').run(to, from);
+            this.db.prepare('UPDATE record_observations SET session_id=? WHERE session_id=?').run(to, from);
+            this.db.prepare('UPDATE record_events SET session_id=? WHERE session_id=?').run(to, from);
+        })();
+        return true;
+    }
+    isActive(sessionId) {
+        const r = this.db.prepare('SELECT active FROM record_sessions WHERE session_id=?').get(sessionId);
+        return !!r && r.active === 1;
+    }
+    append(sessionId, obs, nowMs = Date.now()) {
+        if (!this.isActive(sessionId))
+            return; // recording off → no-op
+        const seq = this.db.prepare('SELECT COUNT(*) AS c FROM record_observations WHERE session_id=?').get(sessionId);
+        this.db.prepare(`INSERT INTO record_observations (session_id,seq,url,fingerprint,declared_links,captured_at)
+       VALUES (?,?,?,?,?,?)`)
+            .run(sessionId, seq.c, obs.url, JSON.stringify(obs.fingerprint), JSON.stringify(obs.declaredLinks), nowMs);
+    }
+    observations(sessionId) {
+        const rows = this.db.prepare('SELECT * FROM record_observations WHERE session_id=? ORDER BY seq').all(sessionId);
+        return rows.map((r) => ({ url: r.url, fingerprint: JSON.parse(r.fingerprint),
+            declaredLinks: JSON.parse(r.declared_links), seq: r.seq, capturedAt: r.captured_at }));
+    }
+    appendActionEffect(sessionId, fx, nowMs = Date.now()) {
+        if (!this.isActive(sessionId))
+            return null;
+        const seq = this.db.prepare('SELECT COUNT(*) AS c FROM record_observations WHERE session_id=?').get(sessionId);
+        this.db.prepare(`INSERT INTO record_observations
+        (session_id,seq,url,fingerprint,declared_links,captured_at,
+         from_url,from_snapshot,action,to_url,to_snapshot,navigated,diff,requested_url,name_hints)
+       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+            .run(sessionId, seq.c, fx.toUrl, '[]', '[]', nowMs, fx.fromUrl, fx.fromSnapshot, JSON.stringify(fx.action), fx.toUrl, fx.toSnapshot, fx.navigated ? 1 : 0, JSON.stringify(fx.diff), fx.requestedUrl ?? null, fx.nameHints ? JSON.stringify(fx.nameHints) : null);
+        return seq.c;
+    }
+    /** Append one raw event to the session's ledger. isActive-gated like steps:
+     *  recording off = off, for BOTH capture paths. Returns the ledger seq (for the
+     *  later disposition stamp) or null when not recording. `ev.t` (the human path's
+     *  page-clock timestamp) always wins; agent-path callers that pass no `t` get
+     *  stamped with `nowMs` so the dashboard's ledger time column is never blank. */
+    appendEvent(sessionId, ev, nowMs = Date.now()) {
+        if (!this.isActive(sessionId))
+            return null;
+        const seq = this.db.prepare('SELECT COUNT(*) AS c FROM record_events WHERE session_id=?').get(sessionId);
+        this.db.prepare('INSERT INTO record_events (session_id,seq,t,source,kind,descriptor) VALUES (?,?,?,?,?,?)')
+            .run(sessionId, seq.c, ev.t ?? nowMs, ev.source, ev.kind, JSON.stringify(ev.descriptor));
+        return seq.c;
+    }
+    /** Stamp an event's fate: 'step:<stepSeq>' or 'dropped:<reason>'. */
+    stampEvent(sessionId, seq, disposition) {
+        this.db.prepare('UPDATE record_events SET disposition=? WHERE session_id=? AND seq=?')
+            .run(disposition, sessionId, seq);
+    }
+    events(sessionId) {
+        const rows = this.db.prepare('SELECT * FROM record_events WHERE session_id=? ORDER BY seq').all(sessionId);
+        return rows.map((r) => ({ seq: r.seq, t: r.t ?? undefined, source: r.source, kind: r.kind,
+            descriptor: JSON.parse(r.descriptor), disposition: r.disposition ?? null }));
+    }
+    actionEffects(sessionId) {
+        const rows = this.db.prepare('SELECT * FROM record_observations WHERE session_id=? AND from_snapshot IS NOT NULL ORDER BY seq').all(sessionId);
+        return rows.map((r) => ({
+            fromUrl: r.from_url, fromSnapshot: r.from_snapshot,
+            action: JSON.parse(r.action), toUrl: r.to_url, toSnapshot: r.to_snapshot,
+            navigated: r.navigated === 1, diff: JSON.parse(r.diff),
+            requestedUrl: r.requested_url ?? undefined,
+            nameHints: r.name_hints ? JSON.parse(r.name_hints) : undefined,
+            seq: r.seq, capturedAt: r.captured_at,
+        }));
+    }
+    listSessions() {
+        const rows = this.db.prepare(`SELECT s.session_id, s.active, s.started_at, s.stopped_at, s.review,
+        (SELECT COUNT(*) FROM record_observations o
+          WHERE o.session_id = s.session_id AND o.from_snapshot IS NOT NULL) AS steps,
+        (SELECT o2.from_url FROM record_observations o2
+          WHERE o2.session_id = s.session_id AND o2.from_snapshot IS NOT NULL
+          ORDER BY o2.seq LIMIT 1) AS first_url
+       FROM record_sessions s ORDER BY s.started_at DESC`).all();
+        const hostOf = (u) => { try {
+            return u ? new URL(u).host : null;
+        }
+        catch {
+            return null;
+        } };
+        const parseReview = (v) => { if (!v)
+            return null; try {
+            return JSON.parse(v);
+        }
+        catch {
+            return null;
+        } };
+        return rows.map((r) => ({ sessionId: r.session_id, active: r.active === 1,
+            startedAt: r.started_at, stoppedAt: r.stopped_at ?? null, steps: r.steps, site: hostOf(r.first_url),
+            review: parseReview(r.review) }));
+    }
+}

package/dist/mapstore/schema.sql

@@ -0,0 +1,47 @@
+CREATE TABLE IF NOT EXISTS states (
+  id TEXT PRIMARY KEY, node_id TEXT, semantic_name TEXT NOT NULL, url_pattern TEXT NOT NULL,
+  role TEXT NOT NULL, available_signals TEXT NOT NULL, fingerprint TEXT NOT NULL, affordances TEXT,
+  declared_shadow TEXT
+);
+CREATE TABLE IF NOT EXISTS edges (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_state TEXT NOT NULL, to_state TEXT NOT NULL, semantic_step TEXT NOT NULL,
+  selector_cache TEXT, kind TEXT NOT NULL, accepts_input TEXT,
+  cost REAL NOT NULL DEFAULT 0,
+  requires_affordances TEXT, core INTEGER, element_fp TEXT,
+  UNIQUE(from_state, to_state, semantic_step)
+);
+CREATE TABLE IF NOT EXISTS nodes (
+  id TEXT PRIMARY KEY, home_url TEXT NOT NULL, capabilities TEXT NOT NULL, topics TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS node_edges (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_node TEXT NOT NULL, to_node TEXT NOT NULL, kind TEXT NOT NULL,
+  UNIQUE(from_node, to_node, kind)
+);
+CREATE TABLE IF NOT EXISTS record_sessions (
+  session_id TEXT PRIMARY KEY, active INTEGER NOT NULL DEFAULT 1,
+  started_at INTEGER NOT NULL, stopped_at INTEGER
+);
+CREATE TABLE IF NOT EXISTS record_observations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL, seq INTEGER NOT NULL,
+  url TEXT NOT NULL, fingerprint TEXT NOT NULL, declared_links TEXT NOT NULL,
+  captured_at INTEGER NOT NULL,
+  from_url TEXT, from_snapshot TEXT, action TEXT, to_url TEXT, to_snapshot TEXT,
+  navigated INTEGER, diff TEXT,
+  UNIQUE(session_id, seq)
+);
+CREATE TABLE IF NOT EXISTS record_events (
+  session_id TEXT NOT NULL, seq INTEGER NOT NULL,
+  t INTEGER, source TEXT NOT NULL, kind TEXT NOT NULL,
+  descriptor TEXT NOT NULL, disposition TEXT,
+  PRIMARY KEY (session_id, seq)
+);
+CREATE TABLE IF NOT EXISTS walk_sessions (
+  session_id TEXT PRIMARY KEY,
+  start_state TEXT NOT NULL, goal_state TEXT NOT NULL,
+  path TEXT NOT NULL, pos INTEGER NOT NULL DEFAULT 0,
+  browser_session TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'paused',
+  created_at INTEGER NOT NULL
+);

package/dist/mapstore/store.d.ts

@@ -0,0 +1,108 @@
+import Database from 'better-sqlite3';
+import type { State, Edge, InteriorEdge, SiteNode, NodeEdge, ElementFingerprint } from './types.js';
+/** The data-access seam. SqliteMapStore is the only impl today; a hosted
+ *  backend (Firestore/Postgres) can implement the same interface later. */
+export interface IMapStore {
+    transaction(fn: () => void): void;
+    upsertState(s: State): void;
+    getState(id: string): State | null;
+    allStates(): State[];
+    statesForNode(nodeId: string): State[];
+    upsertEdge(e: Edge): void;
+    deleteEdgesFromPrefix(prefix: string): void;
+    clearNode(nodeId: string): void;
+    removeNode(nodeId: string): void;
+    edgesFrom(fromState: string): Edge[];
+    allEdges(): Edge[];
+    interiorEdges(nodeId: string): InteriorEdge[];
+    recordSelector(fromState: string, toState: string, semanticStep: string, selector: string): void;
+    recordElementFp(fromState: string, affordanceId: string, fp: ElementFingerprint): boolean;
+    upsertNode(n: SiteNode): void;
+    getNode(id: string): SiteNode | null;
+    allNodes(): SiteNode[];
+    upsertNodeEdge(e: NodeEdge): void;
+    nodeEdgesFrom(fromNode: string): NodeEdge[];
+    allNodeEdges(): NodeEdge[];
+}
+export declare class MapStore implements IMapStore {
+    private db;
+    constructor(path?: string);
+    /** Open a store over an already-constructed Database handle (used by tests + migration). */
+    static fromDatabase(db: Database.Database): MapStore;
+    /** Idempotent: add states.node_id if missing, backfill from the id prefix. */
+    private migrate;
+    /** Run `fn` atomically — all writes commit together or none do (no torn skeleton). */
+    transaction(fn: () => void): void;
+    upsertState(s: State): void;
+    getState(id: string): State | null;
+    allStates(): State[];
+    statesForNode(nodeId: string): State[];
+    upsertEdge(e: Edge): void;
+    deleteEdgesFromPrefix(prefix: string): void;
+    /** Wipe a single node's INTERIOR — its states and their stored edges — so the site can be
+     *  RE-LEARNED from scratch through webnav (never raw sqlite). The node row itself stays
+     *  (its id/homeUrl), so a fresh graph-edit lands back under it. No-op if unknown. */
+    clearNode(nodeId: string): void;
+    /** Fully DELETE a node: its interior (states + edges, via clearNode), its node_edges (both
+     *  directions), AND the node row itself — so a stale/empty site disappears entirely. For
+     *  cleaning up dashboard cruft; never raw sqlite. No-op if unknown. Touches ONLY this node. */
+    removeNode(nodeId: string): void;
+    /**
+     * Project a state's navigate/reveal affordances (recursing into reveal children)
+     * into edges. Affordances are the SOURCE OF TRUTH; this is how the router/walk
+     * see them as edges WITHOUT changing their interface (principle: edges = actions).
+     * mutate/input affordances and navigate/reveal with no toState do NOT project.
+     */
+    private projectFromAffordances;
+    /** Edges leaving a state = stored edges UNION projected-from-affordances UNION the
+     *  site's `_shell` navigate affordances (from-anywhere: the shell's nav/header/footer
+     *  links are reachable from every page, not just the shell record itself), deduped
+     *  by (from,to,semanticStep) preferring the stored row (carries the self-heal
+     *  selector_cache and teach-written fields) then the state's own projected edges. */
+    edgesFrom(fromState: string): Edge[];
+    /** Project the node's `_shell` navigate affordances as edges FROM `fromState` (from-anywhere:
+     *  shell chrome — nav/header/footer — is present on every page, not routable only from the
+     *  shell record). No-op when `fromState` IS the shell (it projects its own affordances above,
+     *  and re-adding them here would just be filtered as duplicates anyway) or when the node has
+     *  no `_shell` state. */
+    private shellEdgesFor;
+    /** NOTE: does NOT fan the `_shell` from-anywhere edges out onto every page here — this is the
+     *  flat human-facing listing (graph-show/outline/mermaid); duplicating N shell edges across
+     *  every page would just be noise for a human reading the map. The router (`edgesFrom`, used
+     *  per-node by findPath's Dijkstra) is where from-anywhere routing actually needs them. */
+    allEdges(): Edge[];
+    /**
+     * Viewer-facing projection for ONE node's interior: every navigate/reveal
+     * affordance becomes an edge tagged with the affordance id that triggers it
+     * (`viaAffordance`, so the UI can anchor the arrow to that row). navigate/reveal
+     * with no toState emit a `dangling` stub (to=null) so the UI shows "unexplored".
+     *
+     * DELIBERATELY does not fan `_shell`'s navigate affordances out onto every OTHER state here the
+     * way `edgesFrom` does (from-anywhere routing) — the `_shell` state's own affordances already
+     * walk() below (it's one of `statesForNode`), so its edges appear once, anchored to `_shell`.
+     * The viewer renders `_shell` as its own distinct chrome node (Task 13) rather than every page
+     * repeating identical "open the nav menu" arrows.
+     */
+    interiorEdges(nodeId: string): InteriorEdge[];
+    private allEdgesStored;
+    /** SELF-HEAL write-back (principle #3): record the durable name an agent's ref
+     *  resolved to on a step that deterministic resolution had MISSED, so the next
+     *  walk re-resolves it without re-asking. Stored as the edge's selector_cache.
+     *  A no-op if the edge isn't a stored row (a purely affordance-projected edge
+     *  with no edges-table backing); upserting one here is out of scope. */
+    recordSelector(fromState: string, toState: string, semanticStep: string, selector: string): void;
+    /** SELF-HEAL write-back, fingerprint flavor (B1): persist a `{role,name,near}` element
+     *  fingerprint onto the OWNING AFFORDANCE in `fromState` (located by its id), so the next
+     *  walk resolves the once-ambiguous step deterministically. Writes the affordance blob —
+     *  NOT the edges table — because both motivating maps store affordances only (no edge rows),
+     *  where an `UPDATE edges` would no-op. Recurses reveal children. No-op if the affordance
+     *  isn't found (caller falls back to recordSelector for a legacy stored row). */
+    recordElementFp(fromState: string, affordanceId: string, fp: ElementFingerprint): boolean;
+    upsertNode(n: SiteNode): void;
+    getNode(id: string): SiteNode | null;
+    allNodes(): SiteNode[];
+    upsertNodeEdge(e: NodeEdge): void;
+    nodeEdgesFrom(fromNode: string): NodeEdge[];
+    /** ALL node edges (the export/visualization needs every edge, not just from one node). */
+    allNodeEdges(): NodeEdge[];
+}