/**
 * Ref layout constants and helpers for WARP (Write-Ahead Reference Protocol).
 *
 * Provides functions for building, parsing, and validating Git ref paths
 * used by the WARP protocol. All refs live under the refs/warp/ namespace.
 *
 * Ref layout:
 * - refs/warp/<graph>/writers/<writer_id>
 * - refs/warp/<graph>/checkpoints/head
 * - refs/warp/<graph>/coverage/head
 * - refs/warp/<graph>/cursor/active
 * - refs/warp/<graph>/cursor/saved/<name>
 * - refs/warp/<graph>/strands/<id>
 * - refs/warp/<graph>/strand-overlays/<id>
 * - refs/warp/<graph>/strand-braids/<id>/<support_id>
 * - refs/warp/<graph>/audit/<writer_id>
 * - refs/warp/<graph>/trust/records
 *
 * @module domain/utils/RefLayout
 */
/** The prefix for all warp refs. */
export declare const REF_PREFIX: string;
/** Maximum length for a writer ID. */
export declare const MAX_WRITER_ID_LENGTH: number;
/**
 * Ref-layout keywords that must not appear as any `/`-delimited segment
 * of a graph name. Using one of these would create an ambiguous ref path
 * (e.g. `refs/warp/writers/writers/alice`).
 */
export declare const RESERVED_GRAPH_NAME_SEGMENTS: Set<string>;
/**
 * Validates a graph name and throws if invalid.
 *
 * Graph names must not contain:
 * - Path traversal sequences (`..`)
 * - Semicolons (`;`)
 * - Spaces
 * - Null bytes (`\0`)
 * - Empty strings
 *
 * @throws {Error} If the name is not a string, is empty, or contains
 *   forbidden characters (`..`, `;`, space, `\0`)
 *
 * @example
 * validateGraphName('events');    // OK
 * validateGraphName('team/proj'); // OK (slashes allowed)
 * validateGraphName('../etc');    // throws — path traversal
 * validateGraphName('my graph');  // throws — contains space
 */
export declare function validateGraphName(name: string): void;
/**
 * Validates a writer ID and throws if invalid.
 *
 * Writer IDs must:
 * - Be ASCII ref-safe: only `[A-Za-z0-9._-]`
 * - Be 1-64 characters long
 * - Not contain `/`, `..`, whitespace, or NUL
 *
 * @throws {Error} If the ID is not a string, is empty, exceeds 64 characters,
 *   or contains forbidden characters (`/`, `..`, whitespace, NUL, non-ASCII)
 *
 * @example
 * validateWriterId('node-1');        // OK
 * validateWriterId('a/b');           // throws — contains forward slash
 * validateWriterId('x'.repeat(65));  // throws — exceeds max length
 * validateWriterId('has space');     // throws — contains whitespace
 */
export declare function validateWriterId(id: string): void;
/**
 * Builds a writer ref path for the given graph and writer ID.
 *
 * @example
 * buildWriterRef('events', 'node-1');
 * // => 'refs/warp/events/writers/node-1'
 */
export declare function buildWriterRef(graphName: string, writerId: string): string;
/**
 * Builds the checkpoint head ref path for the given graph.
 *
 * @example
 * buildCheckpointRef('events');
 * // => 'refs/warp/events/checkpoints/head'
 */
export declare function buildCheckpointRef(graphName: string): string;
/**
 * Builds the coverage head ref path for the given graph.
 *
 * @example
 * buildCoverageRef('events');
 * // => 'refs/warp/events/coverage/head'
 */
export declare function buildCoverageRef(graphName: string): string;
/**
 * Builds the writers prefix path for the given graph.
 * Useful for listing all writer refs under a graph
 * (e.g. via `git for-each-ref`).
 *
 * @example
 * buildWritersPrefix('events');
 * // => 'refs/warp/events/writers/'
 */
export declare function buildWritersPrefix(graphName: string): string;
/**
 * Builds the active cursor ref path for the given graph.
 *
 * The active cursor is a single ref that stores the current time-travel
 * position used by `git warp seek`. It points to a commit SHA representing
 * the materialization frontier the user has seeked to.
 *
 * @example
 * buildCursorActiveRef('events');
 * // => 'refs/warp/events/cursor/active'
 */
export declare function buildCursorActiveRef(graphName: string): string;
/**
 * Builds a saved (named) cursor ref path for the given graph and cursor name.
 *
 * Saved cursors are bookmarks created by `git warp seek --save <name>`.
 * Each saved cursor persists a time-travel position that can be restored
 * later without re-seeking.
 *
 * The cursor name is validated with the same rules as a writer ID
 * (ASCII ref-safe: `[A-Za-z0-9._-]`, 1-64 characters).
 *
 * @example
 * buildCursorSavedRef('events', 'before-tui');
 * // => 'refs/warp/events/cursor/saved/before-tui'
 */
export declare function buildCursorSavedRef(graphName: string, name: string): string;
/**
 * Builds the saved cursor prefix path for the given graph.
 * Useful for listing all saved cursor bookmarks under a graph
 * (e.g. via `git for-each-ref`).
 *
 * @example
 * buildCursorSavedPrefix('events');
 * // => 'refs/warp/events/cursor/saved/'
 */
export declare function buildCursorSavedPrefix(graphName: string): string;
/**
 * Builds a strand descriptor ref path for the given graph and id.
 *
 * Strand ids use the same ref-safe validation as writer ids because they
 * appear as the final ref path segment.
 */
export declare function buildStrandRef(graphName: string, strandId: string): string;
/** Builds the strand prefix path for the given graph. */
export declare function buildStrandsPrefix(graphName: string): string;
/**
 * Builds a strand overlay ref path for the given graph and id.
 *
 * Overlay refs keep the patch-log head for a strand separate from the
 * descriptor ref itself, allowing the descriptor to remain a single ref while
 * the overlay history advances independently.
 */
export declare function buildStrandOverlayRef(graphName: string, strandId: string): string;
/**
 * Builds a pinned braid ref for one support overlay inside a target strand.
 *
 * The ref points at the pinned head SHA for the support overlay at braid time,
 * keeping the support patch chain reachable even if the source strand is
 * later dropped or continues independently.
 */
export declare function buildStrandBraidRef(graphName: string, strandId: string, braidedStrandId: string): string;
/**
 * Builds the braid-ref prefix path for all support overlays pinned inside one
 * target strand.
 */
export declare function buildStrandBraidsPrefix(graphName: string, strandId: string): string;
/**
 * Builds the audit ref path for the given graph and writer ID.
 *
 * Audit refs track the latest audit commit for each writer, forming
 * an independent chain of tamper-evident receipts per writer.
 *
 * @example
 * buildAuditRef('events', 'alice');
 * // => 'refs/warp/events/audit/alice'
 */
export declare function buildAuditRef(graphName: string, writerId: string): string;
/**
 * Builds the audit ref prefix for listing all audit writers of a graph.
 *
 * @example
 * buildAuditPrefix('events');
 * // => 'refs/warp/events/audit/'
 */
export declare function buildAuditPrefix(graphName: string): string;
/**
 * Builds the seek cache ref path for the given graph.
 *
 * The seek cache ref points to a blob containing a JSON index of
 * cached materialization states, keyed by (ceiling, frontier) tuples.
 *
 * @example
 * buildSeekCacheRef('events');
 * // => 'refs/warp/events/seek-cache'
 */
export declare function buildSeekCacheRef(graphName: string): string;
/**
 * Builds the trust record chain ref path for the given graph.
 *
 * The trust record ref points to the tip commit of the trust record
 * chain — an append-only sequence of signed trust records (key adds,
 * key revokes, writer bindings).
 *
 * @example
 * buildTrustRecordRef('events');
 * // => 'refs/warp/events/trust/records'
 */
export declare function buildTrustRecordRef(graphName: string): string;
/**
 * Parses and extracts the writer ID from a writer ref path.
 *
 * Returns null for any non-writer ref, including malformed refs. Callers that
 * need to distinguish "not a writer ref" from "malformed ref" should validate
 * the ref format separately before calling this method.
 *
 * @example
 * parseWriterIdFromRef('refs/warp/events/writers/alice');
 * // => 'alice'
 *
 * parseWriterIdFromRef('refs/heads/main');
 * // => null
 */
export declare function parseWriterIdFromRef(refPath: string): string | null;
