import type { CheckpointId, GoalId, MessageId, ProjectId, SessionId, TaskId, TurnId } from '../types/ids/index.js';
/**
 * The on-disk layout of `NAMZU_HOME`, shared by the SDK and the CLI:
 *
 * ```text
 * $NAMZU_HOME/
 *   index.sqlite                     rebuildable index over every log
 *   projects/<slug>/
 *     project.json                   the project id, minted once
 *     memory/  residents/  worktrees/<label>/
 *     <session-id>.jsonl             the session log (source of truth)
 *     <session-id>/
 *       subagents/<child-id>.jsonl, <child-id>.meta.json, <child-id>/subagents/…
 *       tool-results/  checkpoints/  budgets/  tasks/  feedback/  goals/
 *       file-history/  lease.json
 * $TMPDIR/namzu-<user>/<slug>/<session-id>/scratchpad/
 * ```
 *
 * Every id that becomes a path segment is checked here, because a brand does
 * not validate a value read from JSON.
 */
/** Names a session in the tree: its id, and its ancestors from the root down (empty for a root session). */
export interface SessionLocator {
    readonly sessionId: SessionId;
    readonly ancestors?: readonly SessionId[];
}
/**
 * The locator a session log's own path spells out: `<session-id>.jsonl` at the
 * top of a project is a root session, and each `<ancestor-id>/subagents/`
 * above it names an ancestor, nearest last. `undefined` when the file is not
 * named `<sessionId>.jsonl`.
 *
 * The path alone does not say which project the file is in: a
 * `<sessionId>.jsonl` kept outside any layout still reads as a root session
 * here. `resolveSessionStorage` trusts this locator only when the layout it
 * was given puts that locator's log at this very file.
 *
 * A log opened from the index's `logPath` knows only its file; this is how it
 * finds the same `checkpoints/` (and the rest of its session directory) that
 * {@link SessionPaths} placed for it.
 */
export declare function sessionLocatorFromLogFile(file: string, sessionId: SessionId): SessionLocator | undefined;
export interface SessionPathsOptions {
    /** The resolved `NAMZU_HOME` (see `resolveNamzuHome`). */
    readonly home: string;
    /** The project's slug, as `ensureProject` returned it. */
    readonly slug: string;
    /**
     * The per-user temporary root (`$TMPDIR/namzu-<user>`). Defaults to
     * {@link tempRoot}, resolved (and created) the first time `tempDir` is called.
     */
    readonly tempRoot?: string;
}
/** A path segment that is not an id of the expected kind, or not a safe name. */
export declare class SessionPathError extends Error {
    readonly name = "SessionPathError";
}
/**
 * The slug a working directory is filed under: every character outside
 * `[A-Za-z0-9]` becomes `-`.
 *
 * Pass the canonical path (`realpath`); `ensureProject` does. A POSIX
 * absolute path starts with `/`, so its slug starts with `-`; a Windows path
 * `C:\…` gives `C-…`; a UNC path gives `--…`. None of these can look like a
 * UUID, which is how a layout reader tells a slug from a legacy
 * `projects/<uuid>/` directory. A slug longer than 200 characters keeps its
 * first 191 and ends in `-` plus 8 hex digits of the path's SHA-256.
 */
export declare function slugForCwd(cwd: string): string;
/** The slug used when `project.json` under the plain slug belongs to a different directory. */
export declare function hashedSlugForCwd(cwd: string): string;
export interface EnsureProjectOptions {
    readonly home: string;
    readonly cwd: string;
    /** Clock for `createdAt`; tests pin it. */
    readonly now?: () => Date;
}
export interface EnsuredProject {
    readonly slug: string;
    readonly projectId: ProjectId;
    /** The canonical working directory the project stands for. */
    readonly cwd: string;
    readonly projectDir: string;
    /** True when this call minted `project.json`; false when it adopted an existing one. */
    readonly created: boolean;
}
/** `project.json` exists and cannot be read as a project document. */
export declare class ProjectDocumentError extends Error {
    readonly name = "ProjectDocumentError";
}
/**
 * Find or create the project a working directory stands for.
 *
 * The directory is canonicalised, slugged, and `projects/<slug>/project.json`
 * is created exclusively: the document is written complete to a private
 * temporary file and then hard-linked into place, which fails with `EEXIST`
 * if another process got there first. So a reader never sees a half-written
 * document, and of two processes racing, exactly one mints the project id and
 * the other adopts it. If the existing document names a different directory
 * (two paths that slug alike), the project moves to the hashed slug.
 */
export declare function ensureProject(options: EnsureProjectOptions): Promise<EnsuredProject>;
export interface TempRootOptions {
    /** Base directory. Default `os.tmpdir()`. */
    readonly tmpdir?: string;
    /** Default `process.platform`. */
    readonly platform?: NodeJS.Platform;
    /**
     * Default `process.getuid`. Pass `undefined` explicitly to model a
     * platform without it (win32).
     */
    readonly getuid?: (() => number) | undefined;
    /** Default `os.userInfo().username`. */
    readonly username?: () => string;
}
/**
 * The per-user temporary root, `$TMPDIR/namzu-<user>`, created if missing.
 *
 * `<user>` is the numeric uid where the platform has one; otherwise the first
 * 12 hex digits of the SHA-256 of the user name; otherwise `user`. On POSIX
 * the directory is created with mode 0700 and refused if it is a symlink, not
 * a directory, owned by another uid, or open to group or others. On win32
 * `%TEMP%` is already per user: a symlink or junction is refused and the
 * owner check is skipped.
 */
export declare function tempRoot(options?: TempRootOptions): string;
/** Every path of one project's layout. Pure: nothing is created or read. */
export declare class SessionPaths {
    #private;
    readonly home: string;
    readonly slug: string;
    constructor(options: SessionPathsOptions);
    /** `$NAMZU_HOME/index.sqlite`. */
    indexFile(): string;
    projectDir(): string;
    projectFile(): string;
    memoryDir(): string;
    residentDir(agentKey: string): string;
    /** The `GitWorktreeManager` default root, or one labelled worktree inside it. */
    worktrees(label?: string): string;
    /** `<session-id>.jsonl`, or `…/subagents/<child-id>.jsonl` for a child session. */
    sessionLog(locator: SessionLocator): string;
    /** The session's own directory, beside its log. */
    sessionDir(locator: SessionLocator): string;
    subagentLog(parent: SessionLocator, childId: SessionId): string;
    /** `<parent-dir>/subagents/<child-id>.meta.json`. */
    subagentMeta(parent: SessionLocator, childId: SessionId): string;
    toolResults(locator: SessionLocator): string;
    /** A spilled tool result, named by the SHA-256 of its provider tool-use id; the manifest is `<file>.manifest.json`. */
    toolResultFile(locator: SessionLocator, toolUseId: string): string;
    checkpoints(locator: SessionLocator): string;
    checkpointFile(locator: SessionLocator, checkpointId: CheckpointId): string;
    /** Token ledgers; written for root sessions only. */
    budgets(locator: SessionLocator): string;
    budgetFile(locator: SessionLocator, rootTurnId: TurnId): string;
    tasks(locator: SessionLocator): string;
    taskFile(locator: SessionLocator, taskId: TaskId): string;
    feedback(locator: SessionLocator): string;
    feedbackFile(locator: SessionLocator, messageId: MessageId): string;
    goals(locator: SessionLocator): string;
    goalFile(locator: SessionLocator, goalId: GoalId): string;
    /** File snapshots a CLI `/restore` rolls back to. */
    fileHistory(locator: SessionLocator): string;
    lease(locator: SessionLocator): string;
    /** `$TMPDIR/namzu-<user>/<slug>/<session-id>/scratchpad`. Not created; the per-user root is. */
    tempDir(sessionId: SessionId): string;
}
//# sourceMappingURL=paths.d.ts.map