studiograph 1.3.46 → 1.3.48-beta.0

package/dist/services/user-person-bridge.js

@@ -0,0 +1,306 @@
+/**
+ * User ↔ Person bridge
+ *
+ * Resolves between auth.db user accounts and person entities. The pointer
+ * lives on the person side as `user_handle` (scalar handle, not a wikilink —
+ * users are out-of-graph identities). Workspace-unique: at most one person
+ * entity per auth handle, workspace-wide.
+ *
+ * The lookup primitives here are intentionally cheap (in-memory scan of
+ * already-loaded person entities). No persistent cache in v1 — if profiling
+ * later shows this is hot, add one with explicit invalidation on entity
+ * writes and on createUser/deleteUser.
+ */
+import { isWorkspaceOwner } from './auth-service.js';
+import { log } from '../utils/log.js';
+export class BridgeError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'BridgeError';
+    }
+}
+/**
+ * Forward lookup: given an auth user handle, return the person entity that
+ * represents them. Returns null when the user has no linked entity (legacy,
+ * unprovisioned, or explicitly unlinked).
+ */
+export function findPersonRefForUser(workspace, userHandle) {
+    for (const entity of workspace.list('person')) {
+        const data = entity.data;
+        if (data.user_handle === userHandle) {
+            return { repo: entity.repoName, entityId: data.entity_id };
+        }
+    }
+    return null;
+}
+/**
+ * Reverse lookup: given a person-entity target ID (the wikilink target, e.g.
+ * `fritz` from `[[fritz]]`), return the auth user that entity is linked to.
+ * Returns null when the entity isn't linked, doesn't exist, or refers to a
+ * non-existent user (pre-link case).
+ */
+export function findUserForPersonRef(workspace, authService, targetId) {
+    // The wikilink target ID alone isn't unique across repos — multiple repos
+    // can have a `person/fritz`. We scan for the first match carrying a
+    // user_handle. In practice the team-repo entity is the canonical one and
+    // satellite copies don't carry the handle, so the first match is right.
+    for (const entity of workspace.list('person')) {
+        const data = entity.data;
+        if (data.entity_id === targetId && typeof data.user_handle === 'string') {
+            return authService.findUserByHandle(data.user_handle) ?? null;
+        }
+    }
+    return null;
+}
+/**
+ * Bulk forward map: handle → personRef for every linked person in the
+ * workspace. Useful for `list_workspace_users` and for migration reporting.
+ */
+export function getHandleToPersonRefMap(workspace) {
+    const map = new Map();
+    for (const entity of workspace.list('person')) {
+        const data = entity.data;
+        if (typeof data.user_handle === 'string') {
+            // First write wins. If two entities somehow carry the same handle,
+            // the uniqueness check at write time should have blocked it; if it
+            // slipped through (e.g. seeded data), we surface only one and the
+            // migration script's ambiguous-skip path catches the rest.
+            if (!map.has(data.user_handle)) {
+                map.set(data.user_handle, {
+                    repo: entity.repoName,
+                    entityId: data.entity_id,
+                });
+            }
+        }
+    }
+    return map;
+}
+/**
+ * Workspace-wide uniqueness check. Throws BridgeError(USER_HANDLE_CONFLICT)
+ * when another person entity already carries `userHandle`. The `exceptRef`
+ * lets update paths skip the check for the entity being written.
+ *
+ * Called from the write path (graph-api create/update, agent graph-tools
+ * create/update) before delegating to graph.create/update.
+ */
+export function assertUserHandleUnique(workspace, userHandle, exceptRef) {
+    for (const entity of workspace.list('person')) {
+        const data = entity.data;
+        if (data.user_handle !== userHandle)
+            continue;
+        const entityId = data.entity_id;
+        if (exceptRef && exceptRef.repo === entity.repoName && exceptRef.entityId === entityId) {
+            continue;
+        }
+        throw new BridgeError('USER_HANDLE_CONFLICT', `user_handle "${userHandle}" is already linked to ${entity.repoName}/${entityId}`, { conflictingRef: { repo: entity.repoName, entityId } });
+    }
+}
+/**
+ * Authz gate: only workspace owners can stamp or change `user_handle` on a
+ * person entity. Mirrors the `ownerOnly()` gate on the dedicated
+ * `link_person_to_user` / `unlink_person_from_user` agent tools — without
+ * this, a non-owner member with folder-write access could rewrite the
+ * bridge via the generic update_entity REST/agent path, "claiming"
+ * another user's auth identity through the agent's Current User prompt.
+ *
+ * Rules:
+ *   - Payload doesn't include `user_handle` → no-op (caller wasn't trying
+ *     to change the bridge).
+ *   - Payload's value equals the current stored value → no-op (a form
+ *     resubmit including the unchanged field shouldn't 403).
+ *   - Caller is a workspace owner → allowed.
+ *   - Anyone else → throw OWNER_REQUIRED.
+ *
+ * Pass `currentHandle = ''` for create paths (no prior entity).
+ */
+export function assertCanChangeUserHandle(authUser, currentHandle, newHandle) {
+    if (newHandle === undefined)
+        return;
+    const normalized = typeof newHandle === 'string' ? newHandle : '';
+    if (normalized === currentHandle)
+        return;
+    if (authUser && isWorkspaceOwner(authUser.role))
+        return;
+    throw new BridgeError('OWNER_REQUIRED', 'Workspace owner role required to change the linked account on a person entity.', { currentHandle, attemptedHandle: normalized });
+}
+/**
+ * Inspect a frontmatter payload for `user_handle` and, if present, validate
+ * uniqueness against the current workspace state. No-op when the field is
+ * absent or empty.
+ *
+ * `exceptRef` is the entity being written (for updates) so the check
+ * doesn't reject an entity for clashing with itself.
+ */
+export function validateUserHandleInPayload(workspace, data, exceptRef) {
+    const handle = data.user_handle;
+    if (typeof handle !== 'string' || handle.length === 0)
+        return;
+    assertUserHandleUnique(workspace, handle, exceptRef);
+}
+/**
+ * Map an AuthUser to a GitUser for commit attribution. Mirrors `reqGitUser`
+ * in graph-api-access.ts — kept here so the registration / CLI sites
+ * (which don't have a Fastify request) can call into the bridge without
+ * importing the request-scoped helper.
+ */
+export function authUserToGitUser(user) {
+    return {
+        id: user.handle,
+        name: user.displayName,
+        email: `${user.handle}@studiograph.local`,
+    };
+}
+/**
+ * Resolve a person entity for a freshly-registered (or existing) user.
+ *
+ *   1. If the user is already linked, return.
+ *   2. If a person entity carries `email === user.email` and no `user_handle`,
+ *      stamp the handle onto it ("linked" — preserves the user-edited record).
+ *   3. Otherwise auto-create a person entity in the workspace's team repo
+ *      with the user's name/email and the new handle.
+ *
+ * Returns `{ action: 'skipped' }` when no suitable team repo exists and no
+ * email-matchable entity is available — the caller can warn the operator
+ * but should never block user creation on this.
+ */
+export async function ensurePersonForUser(workspace, authService, authUser, gitUser) {
+    // 1. Already linked? No-op.
+    const existing = findPersonRefForUser(workspace, authUser.handle);
+    if (existing) {
+        return { action: 'already-linked', ref: existing };
+    }
+    // 2. Email-match an existing entity that has no handle yet. Don't touch
+    //    entities that already carry a different handle — that's the
+    //    multi-match case the migration script logs as ambiguous.
+    if (authUser.email) {
+        const normalized = authUser.email.toLowerCase().trim();
+        const candidates = [];
+        for (const entity of workspace.list('person')) {
+            const data = entity.data;
+            const entityEmail = typeof data.email === 'string' ? data.email.toLowerCase().trim() : '';
+            if (entityEmail !== normalized)
+                continue;
+            if (typeof data.user_handle === 'string' && data.user_handle.length > 0)
+                continue;
+            candidates.push({ repo: entity.repoName, entityId: data.entity_id });
+        }
+        if (candidates.length === 1) {
+            const target = candidates[0];
+            const graph = workspace.getGraph(target.repo);
+            // graph.update merges the supplied data over the current frontmatter,
+            // so we only need to write the new field + audit metadata.
+            await graph.update({
+                entityType: 'person',
+                entityId: target.entityId,
+                data: {
+                    user_handle: authUser.handle,
+                    updated_at: new Date().toISOString(),
+                    updated_by: gitUser.id,
+                },
+                commitMessage: `Link person/${target.entityId} to user ${authUser.handle}`,
+                user: gitUser,
+            });
+            log.info(`[user-person-bridge] linked person ${target.repo}/${target.entityId} to user ${authUser.handle}`);
+            return { action: 'linked', ref: target };
+        }
+        if (candidates.length > 1) {
+            log.warn(`[user-person-bridge] ${candidates.length} person entities match email ${normalized} for user ${authUser.handle}; ` +
+                `skipping auto-link. Resolve via the agent's link_person_to_user tool or the Profile settings.`);
+            // Fall through to auto-create — the user still gets a record, and the
+            // ambiguous matches can be reconciled later.
+        }
+    }
+    // 3. Auto-create in the team repo. If no team repo is designated and no
+    //    fallback can be chosen, skip with a warning — never block user
+    //    creation on this.
+    const targetRepo = pickTeamRepo(workspace, authService, authUser.id, authUser.role);
+    if (!targetRepo) {
+        log.warn(`[user-person-bridge] no team repo available for user ${authUser.handle}; ` +
+            `person entity NOT auto-provisioned. Configure team_repo in workspace.json.`);
+        return { action: 'skipped', reason: 'no-team-repo' };
+    }
+    const graph = workspace.getGraph(targetRepo);
+    const entityId = allocateEntityId(workspace, authUser.handle);
+    const now = new Date().toISOString();
+    await graph.create({
+        entityType: 'person',
+        entityId,
+        data: {
+            entity_type: 'person',
+            entity_id: entityId,
+            name: authUser.displayName,
+            email: authUser.email,
+            category: 'employee',
+            status: 'current',
+            user_handle: authUser.handle,
+            created_at: now,
+            updated_at: now,
+            created_by: gitUser.id,
+            updated_by: gitUser.id,
+        },
+        content: '',
+        commitMessage: `Auto-provision person/${entityId} for user ${authUser.handle}`,
+        user: gitUser,
+    });
+    log.info(`[user-person-bridge] auto-provisioned person ${targetRepo}/${entityId} for user ${authUser.handle}`);
+    return { action: 'created', ref: { repo: targetRepo, entityId } };
+}
+/**
+ * Pick the repo where a new user's person entity should land.
+ *
+ *   1. `workspace.config.team_repo` if set and the repo still exists.
+ *      Owner's explicit policy — auto-provision into a shared space.
+ *   2. First non-private repo the user actually has write access to
+ *      (covers the first-owner bootstrap path where every non-personal
+ *      repo gets admin granted before this runs).
+ *   3. User's personal repo as last-resort.
+ *
+ * The access check on step 2 closes the squat vector: a non-owner member
+ * registering on a workspace without team_repo configured no longer
+ * silently plants a person entity in a shared repo they have no
+ * folder-access to.
+ */
+function pickTeamRepo(workspace, authService, userId, userRole) {
+    const configured = workspace.getConfig().team_repo;
+    if (configured && workspace.getRepoNames().includes(configured)) {
+        return configured;
+    }
+    // Workspace owners + folder-admins-of-shared-repos can plant records in
+    // shared space; others can't. Iterate non-private repos and pick the
+    // first one the user can write to.
+    for (const repo of workspace.getAllRepoConfigs()) {
+        if (repo.personal)
+            continue;
+        if (userRole === 'owner')
+            return repo.name;
+        const folderRole = authService.getFolderRole(userId, repo.name);
+        if (folderRole === 'admin' || folderRole === 'editor')
+            return repo.name;
+    }
+    const personal = workspace.getUserPersonalRepo(userId);
+    return personal ? personal.name : null;
+}
+/**
+ * Choose an entity ID for the auto-provisioned person. Defaults to the
+ * user's handle (already kebab-case and workspace-unique among users), but
+ * falls back to `<handle>-2`, `<handle>-3`, … if a non-user person entity
+ * already occupies that slug somewhere in the workspace. Mirrors
+ * `AuthService.allocateHandle`'s collision strategy.
+ */
+function allocateEntityId(workspace, handle) {
+    if (!workspace.findEntityById(handle))
+        return handle;
+    for (let suffix = 2; suffix < 1000; suffix++) {
+        const candidate = `${handle}-${suffix}`;
+        if (!workspace.findEntityById(candidate))
+            return candidate;
+    }
+    // Pathological. Defer to the handle (graph.create will reject and we'll
+    // surface the conflict to the caller).
+    return handle;
+}
+//# sourceMappingURL=user-person-bridge.js.map

package/dist/services/user-person-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-person-bridge.js","sourceRoot":"","sources":["../../src/services/user-person-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,gBAAgB,EAAmC,MAAM,mBAAmB,CAAC;AAEtF,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAgBtC,MAAM,OAAO,WAAY,SAAQ,KAAK;IAElB;IAEA;IAHlB,YACkB,IAAqB,EACrC,OAAe,EACC,OAAiC;QAEjD,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAiB;QAErB,YAAO,GAAP,OAAO,CAA0B;QAGjD,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAA2B,EAC3B,UAAkB;IAElB,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAA+B,CAAC;QACpD,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;YACpC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,SAAmB,EAAE,CAAC;QACvE,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAA2B,EAC3B,WAAwB,EACxB,QAAgB;IAEhB,0EAA0E;IAC1E,oEAAoE;IACpE,yEAAyE;IACzE,wEAAwE;IACxE,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAA+B,CAAC;QACpD,IAAI,IAAI,CAAC,SAAS,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;YACxE,OAAO,WAAW,CAAC,gBAAgB,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;QAChE,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAA2B;IAE3B,MAAM,GAAG,GAAG,IAAI,GAAG,EAAqB,CAAC;IACzC,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAA+B,CAAC;QACpD,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;YACzC,mEAAmE;YACnE,mEAAmE;YACnE,kEAAkE;YAClE,2DAA2D;YAC3D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC/B,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE;oBACxB,IAAI,EAAE,MAAM,CAAC,QAAQ;oBACrB,QAAQ,EAAE,IAAI,CAAC,SAAmB;iBACnC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAA2B,EAC3B,UAAkB,EAClB,SAAqB;IAErB,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAA+B,CAAC;QACpD,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU;YAAE,SAAS;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAmB,CAAC;QAC1C,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,MAAM,CAAC,QAAQ,IAAI,SAAS,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACvF,SAAS;QACX,CAAC;QACD,MAAM,IAAI,WAAW,CACnB,sBAAsB,EACtB,gBAAgB,UAAU,0BAA0B,MAAM,CAAC,QAAQ,IAAI,QAAQ,EAAE,EACjF,EAAE,cAAc,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,CACxD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAqC,EACrC,aAAqB,EACrB,SAAkB;IAElB,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO;IACpC,MAAM,UAAU,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IAClE,IAAI,UAAU,KAAK,aAAa;QAAE,OAAO;IACzC,IAAI,QAAQ,IAAI,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IACxD,MAAM,IAAI,WAAW,CACnB,gBAAgB,EAChB,gFAAgF,EAChF,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,CAC/C,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CACzC,SAA2B,EAC3B,IAA6B,EAC7B,SAAqB;IAErB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;IAChC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC9D,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,MAAM;QACf,IAAI,EAAE,IAAI,CAAC,WAAW;QACtB,KAAK,EAAE,GAAG,IAAI,CAAC,MAAM,oBAAoB;KAC1C,CAAC;AACJ,CAAC;AASD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAA2B,EAC3B,WAAwB,EACxB,QAAkB,EAClB,OAAgB;IAEhB,4BAA4B;IAC5B,MAAM,QAAQ,GAAG,oBAAoB,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClE,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;IACrD,CAAC;IAED,wEAAwE;IACxE,iEAAiE;IACjE,8DAA8D;IAC9D,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QACvD,MAAM,UAAU,GAA8C,EAAE,CAAC;QACjE,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAA+B,CAAC;YACpD,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1F,IAAI,WAAW,KAAK,UAAU;gBAAE,SAAS;YACzC,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAClF,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,SAAmB,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAC7B,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC9C,sEAAsE;YACtE,2DAA2D;YAC3D,MAAM,KAAK,CAAC,MAAM,CAAC;gBACjB,UAAU,EAAE,QAAQ;gBACpB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,IAAI,EAAE;oBACJ,WAAW,EAAE,QAAQ,CAAC,MAAM;oBAC5B,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;oBACpC,UAAU,EAAE,OAAO,CAAC,EAAE;iBACvB;gBACD,aAAa,EAAE,eAAe,MAAM,CAAC,QAAQ,YAAY,QAAQ,CAAC,MAAM,EAAE;gBAC1E,IAAI,EAAE,OAAO;aACd,CAAC,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,sCAAsC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,YAAY,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YAC5G,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;QAC3C,CAAC;QACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,GAAG,CAAC,IAAI,CACN,wBAAwB,UAAU,CAAC,MAAM,gCAAgC,UAAU,aAAa,QAAQ,CAAC,MAAM,IAAI;gBACnH,+FAA+F,CAChG,CAAC;YACF,sEAAsE;YACtE,6CAA6C;QAC/C,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,oEAAoE;IACpE,uBAAuB;IACvB,MAAM,UAAU,GAAG,YAAY,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpF,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,GAAG,CAAC,IAAI,CACN,wDAAwD,QAAQ,CAAC,MAAM,IAAI;YAC3E,4EAA4E,CAC7E,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,KAAK,CAAC,MAAM,CAAC;QACjB,UAAU,EAAE,QAAQ;QACpB,QAAQ;QACR,IAAI,EAAE;YACJ,WAAW,EAAE,QAAQ;YACrB,SAAS,EAAE,QAAQ;YACnB,IAAI,EAAE,QAAQ,CAAC,WAAW;YAC1B,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,QAAQ,EAAE,UAAU;YACpB,MAAM,EAAE,SAAS;YACjB,WAAW,EAAE,QAAQ,CAAC,MAAM;YAC5B,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,OAAO,CAAC,EAAE;YACtB,UAAU,EAAE,OAAO,CAAC,EAAE;SACvB;QACD,OAAO,EAAE,EAAE;QACX,aAAa,EAAE,yBAAyB,QAAQ,aAAa,QAAQ,CAAC,MAAM,EAAE;QAC9E,IAAI,EAAE,OAAO;KACd,CAAC,CAAC;IACH,GAAG,CAAC,IAAI,CAAC,gDAAgD,UAAU,IAAI,QAAQ,aAAa,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/G,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,YAAY,CACnB,SAA2B,EAC3B,WAAwB,EACxB,MAAc,EACd,QAAgB;IAEhB,MAAM,UAAU,GAAG,SAAS,CAAC,SAAS,EAAE,CAAC,SAAS,CAAC;IACnD,IAAI,UAAU,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAChE,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,wEAAwE;IACxE,qEAAqE;IACrE,mCAAmC;IACnC,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,iBAAiB,EAAE,EAAE,CAAC;QACjD,IAAI,IAAI,CAAC,QAAQ;YAAE,SAAS;QAC5B,IAAI,QAAQ,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;QAC3C,MAAM,UAAU,GAAG,WAAW,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,IAAI,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IAC1E,CAAC;IACD,MAAM,QAAQ,GAAG,SAAS,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACvD,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,SAA2B,EAAE,MAAc;IACnE,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACrD,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;QACxC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC7D,CAAC;IACD,wEAAwE;IACxE,uCAAuC;IACvC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/services/vector-service.d.ts

@@ -22,14 +22,79 @@ export interface VectorSearchResult {
     entityId: string;
     score: number;
 }
+/**
+ * Snapshot of vector-index health for the /api/health endpoint. Failures are
+ * fire-and-forget at the call sites (we can't block writes on indexing),
+ * so the operator-visible signal lives here instead. Audit (2026-05) flagged
+ * the previous `catch(console.warn)` shape: a steady leak of indexing errors
+ * was undetectable until search results went stale.
+ */
+export interface VectorIndexHealth {
+    /** True when the most recent op succeeded OR no ops have run yet. */
+    healthy: boolean;
+    /** Number of failed ops since process start (or since reset). */
+    failureCount: number;
+    /** Number of in-flight ops not yet acked. Steady growth = backpressure. */
+    inFlight: number;
+    /** ISO timestamp of the most recent failure, if any. */
+    lastFailureAt: string | null;
+    /** Most recent failure message + operation, for log correlation. */
+    lastFailure: {
+        op: 'upsert' | 'delete';
+        entity: string;
+        error: string;
+    } | null;
+    /** Whether Voyage embeddings are configured (Tier 2 — semantic search). */
+    embeddingsEnabled: boolean;
+}
 export declare class VectorService {
     private dbPath;
-    private voyageApiKey?;
+    /**
+     * Legacy fallback key passed via constructor for tests or for early-
+     * boot code paths that run before the secrets store is initialized.
+     * Live calls prefer `tryResolve('voyage.api_key')` so values written
+     * to the store via the UI / CLI take effect without a restart.
+     */
+    private fallbackVoyageApiKey?;
+    private workspaceRoot?;
     private db?;
     private table?;
     private lastIndexedPath;
     private initialized;
-    constructor(dbPath: string, voyageApiKey?: string);
+    private failureCount;
+    private inFlight;
+    private lastFailureAt;
+    private lastFailure;
+    constructor(dbPath: string, voyageApiKey?: string, workspaceRoot?: string);
+    /**
+     * Resolve the Voyage API key fresh on each call: store > constructor
+     * fallback. Lets the operator flip the key via UI / CLI without a
+     * server restart.
+     */
+    private get voyageApiKey();
+    /** Begin tracking an in-flight op. Pair with `recordSuccess`/`recordFailure`. */
+    beginOp(): void;
+    recordSuccess(): void;
+    recordFailure(op: 'upsert' | 'delete', entity: string, err: unknown): void;
+    /**
+     * Snapshot for /api/health. Healthy = the last op succeeded (or none have
+     * run yet) AND there is no abnormal in-flight backlog. The failure count
+     * is informational; a single transient Voyage 503 shouldn't permanently
+     * mark the service unhealthy, but operators can see the trend.
+     */
+    getHealth(): VectorIndexHealth;
+    /**
+     * For asset entities backed by a PDF, the binary's extracted text
+     * lives in a sidecar at `<workspace>/.studiograph/assets-text/asset/<id>.txt`
+     * (written at upload time by `uploadAsset`). Returns the contents so
+     * `buildEntityText` can fold the PDF into the embedding/FTS input. The
+     * markdown body of an asset entity is intentionally light — without
+     * this, PDF assets would be effectively invisible to RAG.
+     *
+     * Best-effort: missing sidecar / read errors return null. Asset stays
+     * indexed by frontmatter alone.
+     */
+    private readPdfSidecar;
     /**
      * Open/create the LanceDB table and ensure the FTS index exists.
      * Call once before using the service.
@@ -43,11 +108,31 @@ export declare class VectorService {
     /**
      * Bulk upsert — used by `studiograph index`. Batches Voyage API calls.
      */
-    upsertMany(repoName: string, entities: EntityFile[]): Promise<void>;
+    upsertMany(repoName: string, entities: EntityFile[], opts?: {
+        /** Called after each embedding batch with the cumulative number of
+         *  entities processed so far inside THIS upsertMany call. Lets the
+         *  caller render a progress bar during long first-time indexes. */
+        onProgress?: (done: number, total: number) => void;
+    }): Promise<void>;
     /**
      * Remove an entity from the index.
      */
     delete(repoName: string, entityType: string, entityId: string): Promise<void>;
+    /**
+     * Remove an entity by `(repo, id)` alone, without needing its type.
+     *
+     * Used by the serve-boot incremental indexer: when git diff reports a
+     * deletion, the file is gone from disk so its type can't be resolved
+     * from frontmatter. The vector store has a discrete `entity_id` column
+     * so we can match on `repo + entity_id` without falling back to a LIKE
+     * pattern on the synthetic id.
+     *
+     * Safe across type renames: a single id that legitimately had two type
+     * rows (e.g. type changed mid-edit and both old + new still exist) gets
+     * both wiped — which is the right behavior for incremental rebuild
+     * since the next upsert recreates the current type's row.
+     */
+    deleteByRepoAndId(repoName: string, entityId: string): Promise<void>;
     /**
      * Search the index.
      * Uses hybrid search (vector + FTS) when Voyage key is configured, FTS only otherwise.
@@ -61,9 +146,13 @@ export declare class VectorService {
      */
     getLastIndexedTime(repoName: string): string | undefined;
     /**
-     * Record the current time as the last index time for a repo.
+     * Record the last index time for a repo.
+     *
+     * Production callers omit `isoTimestamp` and the current time is used.
+     * Tests pass an explicit ISO timestamp so they can rewind the clock and
+     * assert the git-log `--since` window picks up the right commits.
      */
-    setLastIndexedTime(repoName: string): void;
+    setLastIndexedTime(repoName: string, isoTimestamp?: string): void;
     /** Whether Voyage AI embeddings are enabled (Tier 2). */
     get hasEmbeddings(): boolean;
     private generateEmbedding;
@@ -80,9 +169,60 @@ export declare function reindexWorkspace(workspacePath: string, repos: Array<{
     name: string;
     path: string;
 }>, onProgress?: (msg: string) => void): Promise<number>;
+/**
+ * Incremental reindex for the `serve` boot path.
+ *
+ * First run (no last-indexed timestamps): full index of every repo, same
+ * as `reindexWorkspace` but reuses the WorkspaceManager's existing graphs
+ * instead of constructing new ones. Subsequent runs: diff each repo via
+ * `git log --name-status` since the last indexed timestamp, then upsert /
+ * delete only the changed entities. Lifted from `studiograph start`'s
+ * private `initSearchIndex` so the logic survives `start.ts` deletion
+ * (Phase C). No spinner — boot path uses a logger callback.
+ */
+/**
+ * Structural slice of `WorkspaceManager` that `incrementalReindexWorkspace`
+ * touches. Declared locally to avoid a vector-service → workspace-manager
+ * import cycle. `getGraph`'s entity-type parameter is typed loosely (any)
+ * because WorkspaceManager.getGraph().get accepts a narrow EntityType
+ * union — accepting `any` here keeps the parameter contravariantly
+ * compatible without dragging the validation module into vector-service.
+ */
+interface ReindexWorkspaceManager {
+    vectorService?: VectorService;
+    getGraph: (repoName: string) => {
+        list: () => EntityFile[];
+        get: (type: any, id: string) => EntityFile;
+        /** Resolve an entity by ID alone — needed by the incremental indexer
+         *  when the path's type segment isn't reliably present (flat layout,
+         *  hyphenated types, arbitrary nested folders per STU-131). */
+        getById: (id: string) => EntityFile;
+    };
+}
+export declare function incrementalReindexWorkspace(workspaceManager: ReindexWorkspaceManager, repos: Array<{
+    name: string;
+    path: string;
+}>, workspacePath: string, opts?: {
+    log?: (msg: string) => void;
+    /** Fired during first-time indexes to drive a progress bar in the
+     *  caller. `done` is cumulative across all first-time repos, `total`
+     *  is the workspace-wide first-time count. Not fired for the
+     *  incremental (git-diff) path — that path is typically too small
+     *  to need progress UI. */
+    onFirstTimeProgress?: (done: number, total: number) => void;
+}): Promise<{
+    total: number;
+    fresh: boolean;
+}>;
 /**
  * Build a text representation of an entity for FTS/embedding.
  * Combines entity type, key frontmatter fields, and markdown body.
+ *
+ * `extraText` is appended after the body — used by VectorService to
+ * fold PDF sidecar text into asset-entity embeddings. Kept as a plain
+ * string parameter (not file IO) so this stays pure and unit-testable.
+ *
  * Exported for testing.
  */
-export declare function buildEntityText(entity: EntityFile): string;
+export declare function buildEntityText(entity: EntityFile, extraText?: string): string;
+export {};