studiograph 1.3.48-next.13 → 1.3.48-next.131

package/dist/core/graph.d.ts

@@ -6,10 +6,9 @@
  */
 import { GitService, GitUser } from '../services/git.js';
 import { MarkdownDocument } from '../services/markdown.js';
-import { AssetInfo, AssetConfig } from '../services/assets/index.js';
-import { EntityType, type EntityData, type DatasetRow } from './validation.js';
+import { AssetInfo, AssetRecord, AssetConfig } from '../services/assets/index.js';
+import { EntityType, type EntityData } from './validation.js';
 import { SchemaRegistry } from './schema-registry.js';
-import { type DatasetFilter } from '../services/csv-service.js';
 import { type VectorService } from '../services/vector-service.js';
 export interface GraphConfig {
     repoPath: string;
@@ -20,14 +19,34 @@ export interface GraphConfig {
     schemaRegistry?: SchemaRegistry;
     /** When true, all git operations are skipped. Used for the private/ graph. */
     noGit?: boolean;
+    /** Workspace root path. Used to anchor cross-repo artefacts like the
+     *  PDF text sidecar at `<workspaceRoot>/.studiograph/assets-text/...`.
+     *  Optional — when undefined, sidecar cleanup is a no-op. */
+    workspaceRoot?: string;
 }
 export interface EntityFile {
     id: string;
     path: string;
+    /** Repo-relative POSIX path of the containing folder. "" for repo root. */
+    folder_path: string;
     entityType: string;
     data: EntityData;
     document: MarkdownDocument;
 }
+export interface FolderEntry {
+    /** Repo-relative POSIX path. */
+    path: string;
+    /** Last segment of the path. */
+    name: string;
+    /** Optional human-readable label. Set only when an explicit override exists
+     *  in the folder's `.studiograph-folder.json` sidecar; clients fall back to
+     *  toDisplayName(name) when undefined. */
+    display_name?: string;
+}
+export interface FolderDeleteResult {
+    entriesDeleted: number;
+    subfoldersDeleted: number;
+}
 export interface SearchOptions {
     entityType?: EntityType;
     query?: string;
@@ -48,6 +67,11 @@ export interface CreateEntityOptions {
     content?: string;
     commitMessage?: string;
     skipCommit?: boolean;
+    /**
+     * Repo-relative folder to create the entry in. Empty/undefined = repo root.
+     * Parent folders are auto-created (mkdir -p semantics).
+     */
+    folderPath?: string;
     /** Override commit author (for per-user attribution in web UI). */
     user?: GitUser;
 }
@@ -60,6 +84,66 @@ export interface UpdateEntityOptions {
     skipCommit?: boolean;
     /** Override commit author (for per-user attribution in web UI). */
     user?: GitUser;
+    /**
+     * Skip the Yjs `onContentUpdate` callback. Set by paths whose content
+     * already came from the live Y.Doc (web editor autosave PUT) — mirroring
+     * that content back into the Y.Doc would race in-flight keystrokes typed
+     * during the round trip and revert them. Server-side bypass paths
+     * (MCP tools, agent tools, event processor) leave this unset so the
+     * sync fires and the Y.Doc picks up their writes.
+     */
+    skipYjsSync?: boolean;
+}
+/**
+ * Callbacks that fire AFTER successful structural mutations. Used by the Yjs
+ * persistence layer so snapshot files follow the .md file (rename → rename
+ * snapshot, delete → delete snapshot, type change → rename across type dirs).
+ *
+ * Hooked at this layer because the four mutation methods (delete, rename,
+ * changeType, plus cross-repo create+delete via /transfer) are the canonical
+ * mutation surface — every code path that moves an entity goes through them.
+ */
+export interface GraphMutationCallbacks {
+    onDelete?(repo: string, entityType: string, entityId: string): void | Promise<void>;
+    onRename?(repo: string, entityType: string, oldId: string, newId: string): void | Promise<void>;
+    onChangeType?(repo: string, entityId: string, fromType: string, toType: string): void | Promise<void>;
+    /**
+     * Fired immediately AFTER `graph.update()` writes the .md file but BEFORE
+     * any await yields, so JavaScript's single-threaded event loop guarantees
+     * no concurrent writer can preempt the `write-md → notify-Y.Doc` critical
+     * section. The wired callback (server bootstrap) calls
+     * `yjsManager.syncDocFromDisk(docName)` which smart-merges the new .md
+     * content into the active Y.Doc — without this, server-side writes that
+     * bypass Yjs (MCP `update_entity`, agent tools, event processor) get
+     * silently overwritten by the next autosave PUT carrying the stale
+     * Y.Text content.
+     *
+     * Skipped when `UpdateEntityOptions.skipYjsSync` is true. The web autosave
+     * PUT sets that — its content already came from Y.Text, so mirroring the
+     * just-written disk content back into Y.Doc would race with in-flight
+     * keystrokes typed during the autosave round-trip.
+     *
+     * Sync (not async). Must run before any awaits in graph.update.
+     */
+    onContentUpdate?(repo: string, entityType: string, entityId: string): void;
+}
+/**
+ * Thrown by `restoreFile` when the path the recreate would land at is
+ * currently occupied by a different entity. Carries the occupant's
+ * coordinates so callers (agent tool, REST endpoint) can surface a
+ * useful error to the user.
+ */
+export declare class PathConflictError extends Error {
+    readonly path: string;
+    readonly occupiedBy: {
+        entityType: string;
+        entityId: string;
+    };
+    readonly code: "PATH_CONFLICT";
+    constructor(path: string, occupiedBy: {
+        entityType: string;
+        entityId: string;
+    });
 }
 export declare class BaseGraphManager {
     private repoPath;
@@ -69,20 +153,90 @@ export declare class BaseGraphManager {
     private markdownService;
     private assetService?;
     private gitUser;
-    private csvService;
     private vectorService?;
     private schemaRegistry?;
+    private workspaceRoot?;
+    private mutationCallbacks?;
     constructor(config: GraphConfig);
-    /** Expose git service for deferred commit operations (e.g. CommitScheduler). */
+    /** Expose git service for deferred commit operations (SessionManager). */
     getGitService(): GitService | undefined;
+    /** Absolute repo path on disk. Used by callers that need to convert
+     *  an entity's absolute path to a repo-relative one (e.g. for `git log`). */
+    getRepoPath(): string;
+    /**
+     * Find an entity at a specific commit (existing or deleted) and
+     * return its repo-relative path + content. Public surface for the
+     * history tools — wraps the private `findEntityInCommit` walker.
+     * Returns null when no .md file at that commit matches the
+     * (entityType, entityId) pair.
+     */
+    getEntityAtCommit(entityType: EntityType, entityId: string, commitHash: string): {
+        path: string;
+        content: string;
+    } | null;
+    /** Workspace root passed in via GraphConfig. Used by the asset upload
+     *  service to anchor PDF text sidecars at workspace level (so all repos
+     *  share the same `assets-text/` tree, mirroring the shared
+     *  `.studiograph/assets/` directory the local backend uses). */
+    getWorkspaceRoot(): string | undefined;
+    /**
+     * Install post-mutation callbacks. Called once after construction by the
+     * server bootstrap (or test setup) so the Yjs persistence layer can react
+     * to structural mutations without route-layer code calling persistence
+     * APIs directly.
+     */
+    setMutationCallbacks(callbacks: GraphMutationCallbacks | undefined): void;
     /**
      * Ensure repository exists
      */
     private ensureRepo;
     /**
-     * Get entity file path: {repo}/{plural-type}/{entityId}.md
+     * Compute the on-disk path for a new entity.
+     *
+     * - When `folderPath` is provided, the entry lives at {repo}/{folderPath}/{id}.md
+     *   regardless of type. This is the nested-folders layout.
+     * - Without `folderPath` (or empty string), the entry lands at the repo
+     *   root: {repo}/{id}.md. The historical {repo}/{plural-type}/{id}.md
+     *   fallback was confusing — entries hidden under a typed directory the
+     *   list view never showed at repo root, contradicting the agent tool
+     *   description that says "Omit to land at repo root."
+     *
+     * Note: this is for *new* paths only. Existing entries living under the
+     * legacy {plural-type}/ directories continue to be readable via
+     * findEntityFile() — only the create path moved.
      */
     private getEntityPath;
+    private fileIndex?;
+    /** Drop the cached file index so the next read rebuilds it. */
+    private invalidateIndex;
+    /**
+     * Walk every .md file under this repo, calling `visit` with the absolute
+     * path. Skips hidden directories (.git, .studiograph, etc.) and files that
+     * start with ".".
+     */
+    private walkMarkdownFiles;
+    /**
+     * Build (or fetch the cached) "type/id" → absolute path index.
+     * Type comes from frontmatter `entity_type`; if missing, falls back to the
+     * top-level plural-type directory name (legacy layout). Files without either
+     * (e.g. README.md) are skipped — they aren't entities.
+     */
+    private getFileIndex;
+    /**
+     * Infer entity type from a file's location for legacy layouts where the
+     * file sits directly inside a top-level plural-type directory
+     * ({repo}/meetings/foo.md). Returns undefined for any other layout.
+     */
+    private inferLegacyType;
+    /**
+     * Resolve an entity's absolute path by (type, id). Returns undefined if not
+     * found. Uses the file index — the index keys by `${entityType}/${entityId}`
+     * which is type-aware, unlike the on-disk filename. (We previously had a
+     * legacy {plural-type}/{id}.md fast path here; once the create path moved
+     * to flat repo-root layout, that fast path could return a different
+     * type's file at the same id.)
+     */
+    private findEntityFile;
     /**
      * Validate entity data against schema
      */
@@ -92,11 +246,16 @@ export declare class BaseGraphManager {
      */
     create(options: CreateEntityOptions): Promise<EntityFile>;
     /**
-     * Get an entity by type and ID
+     * Get an entity by type and ID. Searches nested folders if the entry isn't
+     * at the legacy {plural-type}/{id}.md path.
      */
     get(entityType: EntityType, entityId: string): EntityFile;
     /**
-     * Get an entity by ID only (type resolved from frontmatter)
+     * Get an entity by ID only (type resolved from the filesystem).
+     *
+     * Walks the file index to find any entry with this id, regardless of folder
+     * depth or type. Used by the agent's `get_entity` tool when the caller
+     * doesn't know the entity's type.
      */
     getById(entityId: string): EntityFile;
     /**
@@ -106,6 +265,62 @@ export declare class BaseGraphManager {
     /**
      * Delete an entity
      */
+    /**
+     * Delete multiple entities in a single git transaction. Each entity's
+     * file is removed from disk; folder markers (.gitkeep) are added where
+     * the deletion left a folder empty. Then everything commits as one
+     * atomic operation.
+     *
+     * Compared to looping `delete()` per entity, this is a real performance
+     * primitive: one fork of git, one index update, one commit, one ref
+     * advance — instead of N. Bulk delete of a few hundred entities goes
+     * from minutes to seconds.
+     *
+     * Errors per entity (e.g. "not found") don't abort the batch — they're
+     * collected in `errors` and the rest still commit. Returns both the
+     * successfully-deleted set (for vector cleanup + WS broadcast) and the
+     * errors so the caller can surface partial failures.
+     */
+    bulkDelete(specs: Array<{
+        entityType: EntityType;
+        entityId: string;
+    }>, options?: {
+        commitMessage?: string;
+        user?: GitUser;
+    }): Promise<{
+        deleted: Array<{
+            entityType: EntityType;
+            entityId: string;
+            path: string;
+        }>;
+        errors: Array<{
+            entityType: EntityType;
+            entityId: string;
+            error: string;
+        }>;
+    }>;
+    /**
+     * Commit a set of already-on-disk file changes as a single git
+     * operation. Used by callers (e.g. the import route) that perform many
+     * `skipCommit: true` writes and want one transaction at the end instead
+     * of per-file commits.
+     *
+     * `entries` describes what each file represents so the transaction can
+     * be staged correctly. No-op when nothing is staged or git isn't
+     * available.
+     */
+    commitPending(entries: Array<{
+        operation: 'create' | 'update' | 'delete';
+        entityType: EntityType;
+        entityId: string;
+        filePath: string;
+    }>, options: {
+        commitMessage: string;
+        user?: GitUser;
+        extraPaths?: string[];
+    }): Promise<{
+        committed: boolean;
+    }>;
     delete(entityType: EntityType, entityId: string, commitMessage?: string, user?: GitUser): Promise<void>;
     /**
      * Rename an entity (change its ID). Preserves all data, content, and source_ref.
@@ -113,18 +328,124 @@ export declare class BaseGraphManager {
      */
     rename(entityType: EntityType, oldId: string, newId: string, commitMessage?: string, user?: GitUser): Promise<EntityFile>;
     /**
-     * Change an entity's type. Moves the file from oldType/ to newType/ directory.
-     * Preserves all data and content. Updates entity_type in frontmatter.
+     * Change an entity's type. Updates frontmatter only — the file stays in
+     * its current folder. In the type-agnostic folder model, type is a
+     * frontmatter property independent of location. (Legacy behavior moved
+     * the file between {plural-type}/ dirs; that's no longer correct because
+     * those dirs are now ordinary user-visible folders, not type markers.)
+     *
+     * If the user wants the file to also move (e.g. out of a "meetings/"
+     * folder when changed to a note), they invoke move() separately.
      */
     changeType(entityId: string, fromType: EntityType, toType: EntityType, commitMessage?: string, user?: GitUser): Promise<EntityFile>;
     /**
-     * List entities of a given type
+     * Move an entry to a different folder within the same repo. The filename
+     * (and therefore the entity id) and type are unchanged. Auto-creates parent
+     * folders. Refuses if the target path already has an entry with this id.
+     */
+    move(entityType: EntityType, entityId: string, targetFolderPath: string, commitMessage?: string, user?: GitUser): Promise<EntityFile>;
+    /**
+     * Restore an entity to its content at a specific commit. Single-entity
+     * scope only — multi-entity rollback (e.g. "undo this commit's effects
+     * across all touched files") is a separate, more cautious flow that
+     * isn't built yet.
+     *
+     * Two paths through the method:
+     *   - **Overwrite**: the entity exists today at path `P`. Read content
+     *     from `git show <hash>:<P>` and write it back to `P`.
+     *   - **Recreate**: the entity is gone today. Walk the historical
+     *     commit's tree to find the .md file whose basename matches
+     *     `entityId` AND whose frontmatter `entity_type` matches
+     *     `entityType`. That path is the restore target. The walk only
+     *     fires when the entity is truly absent — overwrites stay cheap.
+     *
+     * Throws a `PathConflictError` if the recreate target path is now
+     * occupied by a DIFFERENT entity (different type+id) — recreating
+     * over it would silently overwrite unrelated work. Caller surfaces
+     * the conflict to the user; resolution is "move or delete the
+     * occupant first."
+     */
+    restoreFile(entityType: EntityType, entityId: string, commitHash: string, user?: GitUser): Promise<{
+        action: 'recreate' | 'overwrite';
+        path: string;
+    }>;
+    /**
+     * Walk a commit's tree looking for a .md file whose basename matches
+     * `entityId` AND whose frontmatter `entity_type` matches `entityType`.
+     * Returns repo-relative path + content when found, otherwise null.
+     * Used by `restoreFile` for the recreate-from-deletion case.
+     */
+    private findEntityInCommit;
+    /**
+     * Identify the entity (if any) currently occupying `absPath`. Returns
+     * null when the path holds something that isn't an entity (README, etc).
+     * Mirrors the inference rules used in `getFileIndex`.
+     */
+    private identifyEntityAtPath;
+    /**
+     * Enumerate the distinct entity types present in this repo. Used by
+     * /api/repos to let the sidebar render the Views list without a full
+     * entity fetch per folder.
+     *
+     * Derived from the file index (which reads frontmatter), so it works for
+     * entries in any folder — not just the legacy {plural-type}/ dirs.
+     */
+    listEntityTypes(): string[];
+    /**
+     * Folder lifecycle: a directory is treated as a first-class persistent
+     * object. It exists from the moment it's created (createFolder, the destination
+     * of a moved entry, etc.) until it's explicitly removed via a folder-level
+     * operation (deleteFolder, renameFolder, moveFolderToRepo). Entry-level
+     * operations (create, delete, move, transfer) never decide whether a folder
+     * lives or dies.
+     *
+     * `listFolders()` requires either a .md child or a .gitkeep marker for a
+     * directory to surface in the API, so the two helpers below are the single
+     * place that adds and removes the marker:
+     *
+     *  - `ensureFolderMarker` — call after an op that may have left `dir`
+     *    without .md children. Writes `.gitkeep` and returns its path so the
+     *    caller can stage it in the same commit.
+     *  - `removeFolderMarker` — call after an op that placed an .md into `dir`.
+     *    Drops a now-redundant `.gitkeep` so the repo stays tidy.
+     *
+     * Both no-op for the repo root (always implicit) and for paths that don't
+     * exist. Both return `null` when nothing changed.
+     */
+    private ensureFolderMarker;
+    private removeFolderMarker;
+    /**
+     * Walk up from `dir`, removing each directory that became empty after a
+     * folder-level removal (deleteFolder, renameFolder, moveFolderToRepo).
+     * Stops at the repo root. Silently no-ops if a directory is missing,
+     * non-empty, or can't be removed.
+     *
+     * NOT called by entry-level operations (create/delete/move/transfer) —
+     * they preserve folder structure regardless of whether they emptied a
+     * directory. Use `ensureFolderMarker` instead for those paths.
+     */
+    private pruneEmptyAncestors;
+    /**
+     * List entities of a given type (or all types if not specified).
+     *
+     * Walks the entire repo tree so entries in nested folders are discovered.
+     * The type filter is applied against frontmatter `entity_type`; legacy
+     * entries without explicit frontmatter type fall back to the depth-1
+     * plural-type directory name (so `meetings/foo.md` still resolves as a
+     * meeting). Files with no inferable type (README.md, CONTRIBUTING.md, etc.)
+     * are skipped.
      */
     list(entityType?: EntityType, limit?: number): EntityFile[];
     /**
      * Search entities
      */
     search(options: SearchOptions): EntityFile[];
+    /**
+     * Resolve a markdown file (anywhere under the repo) to its (type, id),
+     * tolerating both legacy {plural-type}/{id}.md and nested-folder layouts.
+     * Returns undefined for files without a recognizable entity type.
+     */
+    private resolveFileToEntity;
     /**
      * Get entities related to a given entity (via wikilinks)
      */
@@ -146,6 +467,119 @@ export declare class BaseGraphManager {
     refactorWikilink(oldId: string, newId: string, commitMessage?: string): Promise<{
         updated: number;
     }>;
+    /**
+     * List every non-empty folder in this repo, plus folders explicitly kept
+     * via .gitkeep. Returns repo-relative POSIX paths, sorted, deduplicated.
+     * The repo root ("") is intentionally omitted — it's implicit.
+     */
+    listFolders(): FolderEntry[];
+    /**
+     * Read the display_name override for a single folder, or null if no sidecar
+     * exists / is unreadable. Used by mutation paths that need the current
+     * override before deciding whether to rewrite it.
+     */
+    readFolderDisplayName(folderPath: string): string | null;
+    /**
+     * Write or remove the per-folder display_name sidecar. Pass `null` /
+     * empty-string to remove (returns to slug fallback). Returns the absolute
+     * path of the sidecar (for git staging) when one was written or removed,
+     * or null when no change was needed (idempotent).
+     *
+     * Caller is responsible for committing — the helper only touches the
+     * filesystem. Folder must already exist; this never creates one.
+     */
+    writeFolderDisplayName(folderPath: string, displayName: string | null): string | null;
+    /**
+     * Bulk-write display_name sidecars for many folders at once. Used by the
+     * import path to record original-casing overrides for every nested
+     * directory it slugified. First-writer-wins: existing sidecars are NOT
+     * overwritten, so a second import doesn't clobber a user's manual rename.
+     *
+     * Returns the list of sidecar paths actually written (for git staging).
+     * Skipped paths (folder missing, slug already matches display, sidecar
+     * already exists) are quietly omitted.
+     */
+    recordFolderDisplays(entries: Array<{
+        path: string;
+        display_name: string;
+    }>): string[];
+    /**
+     * Create a folder at the given path (mkdir -p semantics) and drop a
+     * .gitkeep so git tracks it even when empty. Validates the path. No-op if
+     * the folder already exists; .gitkeep is added if missing.
+     */
+    createFolder(folderPath: string, commitMessage?: string, user?: GitUser, options?: {
+        displayName?: string;
+    }): Promise<void>;
+    /**
+     * Rename / move a folder within the repo. Moves the entire subtree
+     * atomically via filesystem rename. Refuses if the target path is already
+     * occupied.
+     */
+    renameFolder(fromPath: string, toPath: string, commitMessage?: string, user?: GitUser, options?: {
+        displayName?: string | null;
+    }): Promise<void>;
+    /**
+     * Move a folder (and its full subtree) into a different repo at `targetFolderPath`.
+     *
+     * The naive way to do this is to iterate the source's entries and call
+     * `transfer` per entry — that's what the web UI used to do, and it costs
+     * 2 git commits per entry (1600 commits for 800 files), each blocking the
+     * Node event loop via `execSync`. This method performs the move as a
+     * single FS-level rename + one commit per repo, regardless of how many
+     * files are inside.
+     *
+     * Returns the count of entries + subfolders moved so the caller can
+     * surface progress.
+     */
+    moveFolderToRepo(sourceFolderPath: string, target: BaseGraphManager, targetFolderPath: string, options?: {
+        commitMessage?: string;
+        user?: GitUser;
+    }): Promise<FolderDeleteResult>;
+    /**
+     * Move a batch of entries (potentially across many source folders) into a
+     * single target folder, optionally in a different repo. The web UI's
+     * multi-select bulk move used to call /move or /transfer per entry — that
+     * was 1-2 sync git commits per entry, blocking the event loop on each one.
+     * This collapses the operation to a single FS rename per file plus one
+     * commit on each repo touched.
+     */
+    moveEntitiesToRepo(entries: Array<{
+        entityType: EntityType;
+        entityId: string;
+    }>, target: BaseGraphManager, targetFolderPath: string, options?: {
+        commitMessage?: string;
+        user?: GitUser;
+    }): Promise<{
+        moved: number;
+    }>;
+    /**
+     * Delete a folder. Refuses non-empty folders unless `recursive: true`.
+     * Returns the count of entries + subfolders removed (for blast-radius UI).
+     */
+    deleteFolder(folderPath: string, options?: {
+        recursive?: boolean;
+        commitMessage?: string;
+        user?: GitUser;
+    }): Promise<FolderDeleteResult>;
+    /**
+     * Count the entries (.md files with entity_type) and subfolders inside an
+     * absolute directory, recursively. Used to surface blast radius in the
+     * delete-folder approval UI.
+     */
+    private countFolderContents;
+    /**
+     * Return the storage backend the graph is bound to, or `undefined` if
+     * no asset service is configured. Used by routes that need to branch
+     * between local-stream and R2-redirect behavior.
+     */
+    getAssetStorage(): 'local' | 'r2' | undefined;
+    /**
+     * Mint a short-lived pre-signed URL for an asset. Only supported by
+     * remote backends (R2); the local backend throws. `method` selects
+     * the verb the URL is signed against — HEAD callers need a HEAD URL.
+     */
+    getAssetSignedUrl(entityType: EntityType, entityId: string, filename: string, keyPrefix?: string, expiresIn?: number, method?: 'GET' | 'HEAD'): Promise<string>;
     /**
      * Upload asset for an entity
      */
@@ -155,21 +589,39 @@ export declare class BaseGraphManager {
      */
     listAssets(entityType: EntityType, entityId: string, keyPrefix?: string): Promise<AssetInfo[]>;
     /**
-     * Delete an asset
+     * List every asset in the backend in one round-trip, tagged with
+     * (entityType, entityId) origin. Workspace-wide since the asset backend
+     * is shared across repos — callers filter by repo via {@link listEntityIds}.
      */
-    deleteAsset(entityType: EntityType, entityId: string, filename: string, keyPrefix?: string): Promise<void>;
+    listAllAssets(): Promise<AssetRecord[]>;
     /**
-     * Delete all assets for an entity (when entity is deleted)
+     * Enumerate (type, id) pairs in this repo. Used by endpoints (like
+     * /api/repos/:repo/assets) that need to answer "does entity X belong to
+     * this repo?".
+     *
+     * Backed by the file index, which reads frontmatter — so entries in
+     * nested folders are included alongside legacy {plural-type}/ entries.
      */
-    deleteAllAssets(entityType: EntityType, entityId: string, keyPrefix?: string): Promise<number>;
+    listEntityIds(): Array<{
+        entityType: EntityType;
+        id: string;
+    }>;
     /**
-     * Get dataset rows, optionally filtered
+     * Resolve the absolute on-disk markdown path for an entity. Goes through
+     * the file index so it works for both the flat repo-root layout and
+     * arbitrary nested folders. Use this anywhere callers need a path —
+     * never reconstruct one from `${plural-type}/${id}.md`, which assumes
+     * the legacy typed-folder layout and silently misses everything else.
      */
-    getDatasetRows(entityId: string, filter?: DatasetFilter): DatasetRow[];
+    getEntityFilePath(entityType: EntityType, entityId: string): string | undefined;
     /**
-     * Append rows to a dataset entity
+     * Delete an asset
      */
-    appendDatasetRows(entityId: string, newRows: DatasetRow[], commitMessage?: string): Promise<EntityFile>;
+    deleteAsset(entityType: EntityType, entityId: string, filename: string, keyPrefix?: string): Promise<void>;
+    /**
+     * Delete all assets for an entity (when entity is deleted)
+     */
+    deleteAllAssets(entityType: EntityType, entityId: string, keyPrefix?: string): Promise<number>;
     /**
      * Get repository status
      */