/**
 * Path fingerprints of a project checkout (T9149, demoted by T12470).
 *
 * A project is identified ONLY by the id it declares — the tracked
 * `.cleo/project-id`, then `project-info.json` (ADR-094; see
 * `readDeclaredProjectIdentity` in `@cleocode/paths`). The values computed here
 * hash a checkout's LOCATION (git-root realpath + name + remote), so they
 * change when the project moves. They survive only as alias keys in
 * `nexus_project_id_aliases`, which keeps ids that older CLEO versions derived
 * from a path resolvable. Never return one as a project id and never key a
 * registry row by one. This supersedes the T9149 realpath-fingerprint identity.
 *
 * @task T9149
 * @task T12470
 * @module nexus/identity
 */
import type { OperationExecutionContext } from '@cleocode/contracts/jobs';
/**
 * Read the project's declared, portable identity without creating or migrating it.
 *
 * @param projectRoot - Checkout whose tracked identity (or legacy cache) is read.
 * @returns The declared id, independent of the checkout's current path.
 * @throws {CleoError} When identity is missing; a path fingerprint is never a fallback.
 */
export declare function requireNexusProjectId(projectRoot: string): string;
/** Components that make up the canonical project fingerprint. */
export interface ProjectIdentityComponents {
    /** Absolute realpath of the git root (resolves symlinks). */
    readonly gitRoot: string;
    /** Project name from project-info.json (if present). */
    readonly projectName?: string;
    /** First git remote URL (origin fetch URL, if present). */
    readonly remoteUrl?: string;
}
/** Result of path-fingerprint computation (an alias key, not an identity). */
export interface CanonicalProjectIdResult {
    /** The 12-hex-char path fingerprint — an alias key, never a project id. */
    readonly id: string;
    /** The components used to compute the ID. */
    readonly components: ProjectIdentityComponents;
    /**
     * Legacy base64url(path) IDs that should be aliased to this canonical ID.
     * Populated when the caller supplies known legacy IDs for migration.
     */
    readonly legacyAliases?: ReadonlyArray<string>;
}
/**
 * Find the git root for a given directory using `git rev-parse --show-toplevel`.
 *
 * Returns `null` if the directory is not inside a git repo (non-fatal: allows
 * use outside git repos).
 * @param fromPath - Explicit directory for Git discovery.
 * @param execution - Optional original lifetime; cancellation/deadline are never absent-Git fallback.
 * @returns Git root or null when Git is unavailable.
 * @remarks An execution context bounds and cancels the actual child; omitted context
 * retains the legacy unbounded lifetime. Synchronous scheduling is not preempted.
 * @example
 * ```ts
 * const root = await findGitRoot(projectRoot, execution);
 * ```
 */
export declare function findGitRoot(fromPath: string, execution?: OperationExecutionContext): Promise<string | null>;
/**
 * Find the primary git remote URL (origin fetch URL).
 *
 * Returns `null` when there are no remotes or git is unavailable.
 * @param fromPath - Explicit directory for remote lookup.
 * @param execution - Optional original lifetime, shared with preceding discovery stages.
 * @returns Remote URL, or null for an unavailable Git remote.
 * @remarks Context cancellation and deadline failures propagate instead of producing
 * a fallback fingerprint. Actual children receive the same signal and remaining timeout.
 * @example
 * ```ts
 * const remote = await findGitRemoteUrl(projectRoot, execution);
 * ```
 */
export declare function findGitRemoteUrl(fromPath: string, execution?: OperationExecutionContext): Promise<string | null>;
/**
 * Normalise a git remote URL so `git@host:o/r.git` and `https://host/o/r`
 * compare equal. Returns `null` for empty input.
 *
 * @param url - Raw `git remote get-url` output or a stored `remoteUrl`.
 * @returns A `host/owner/repo` style key, or `null`.
 *
 * @example
 * ```ts
 * normalizeRemoteUrl('git@github.com:o/r.git'); // 'github.com/o/r'
 * ```
 */
export declare function normalizeRemoteUrl(url: string | null | undefined): string | null;
/**
 * Git facts about a checkout, recorded on its location for DISPLAY (T12470).
 * Never proof: a clone shares both, a bare `git init` can add any remote, and
 * a root commit can be faked. Moves are proven by the checkout nonce
 * (`nexus/checkout-nonce.ts`) alone. `null` means unknown.
 */
export interface CheckoutEvidence {
    /** First (parentless) commit of the repository — the lexically smallest when several. */
    readonly gitRootCommit: string | null;
    /** Normalised `origin` URL ({@link normalizeRemoteUrl}). */
    readonly gitRemote: string | null;
}
/**
 * Collect {@link CheckoutEvidence} for a checkout. Never throws for an absent
 * repository, commit or remote — those fields are `null`.
 *
 * @param fromPath - Checkout root.
 * @param execution - Optional captured caller lifetime.
 * @returns The evidence.
 *
 * @example
 * ```ts
 * const { gitRootCommit, gitRemote } = await collectCheckoutEvidence(root);
 * ```
 */
export declare function collectCheckoutEvidence(fromPath: string, execution?: OperationExecutionContext): Promise<CheckoutEvidence>;
/**
 * Compute the path fingerprint `sha256(gitRoot|name|remote)[0:12]` of a checkout.
 *
 * **Alias key only (T12470).** The value depends on where the checkout lives,
 * so it is recorded in `nexus_project_id_aliases` to keep path-derived ids
 * from older CLEO versions resolvable — it is never a project's identity.
 *
 * @param repoPath - Absolute path to the checkout (may be a symlink or bind-mount).
 * @param execution - Optional captured caller lifetime, never renewed between stages.
 * @remarks All started Git children settle before this operation finishes. Context
 * cancellation/deadline failures cannot establish a fallback fingerprint.
 * @example
 * ```ts
 * const { id: aliasKey } = await projectPathFingerprint(projectRoot, execution);
 * ```
 * @returns The fingerprint with the components it was computed from.
 *
 * @task T9149
 * @task T12470
 */
export declare function projectPathFingerprint(repoPath: string, execution?: OperationExecutionContext): Promise<CanonicalProjectIdResult>;
/**
 * Former name of {@link projectPathFingerprint}.
 *
 * @deprecated T12470 — the value is a path fingerprint (alias key), not a
 * project id. Read identity with `readDeclaredProjectIdentity` from
 * `@cleocode/paths`.
 */
export declare const canonicalProjectId: typeof projectPathFingerprint;
/**
 * Compute the legacy base64url(path) ID for a given path.
 *
 * Canonical source: `@cleocode/paths` (`packages/paths/src/cleo-paths.ts`).
 * Re-exported here for backward compatibility — all internal nexus consumers
 * should import from `@cleocode/paths` directly.
 *
 * This is the old algorithm used before W5: `Buffer.from(path).toString('base64url').slice(0, 32)`.
 * Used to populate `projectIdAliases` when migrating existing registrations.
 */
export { legacyProjectId } from '@cleocode/paths';
/**
 * Build the set of legacy IDs that should be aliased to the canonical ID.
 *
 * Includes the direct path legacy ID and any additional known paths (e.g.
 * from container mount variants).
 */
export declare function computeLegacyAliases(repoPath: string, additionalPaths?: string[]): string[];
//# sourceMappingURL=identity.d.ts.map