/**
 * WorkspaceRef + backend metadata.
 *
 * See session-hierarchy.md §4.9 (WorkspaceRef) and §7 (Workspace and
 * Worktree). The `meta` field is a discriminated union on `backend` — Phase 3
 * ships the `git-worktree` variant; `tmpfs`, `container`, and `shared` land
 * in a later phase of the overall roadmap (post-MVP) without breaking
 * existing consumers (Convention #6).
 */

import type { WorkspaceId } from '../session/ids.js'

/**
 * Supported backend kinds. Additional variants are append-only; existing
 * consumers switch with an `_exhaustive` never-guard and will fail to compile
 * when the union grows — paired with the update at the discriminated
 * {@link WorkspaceBackendMeta} site (Convention #6).
 */
export type WorkspaceBackendKind = 'git-worktree' | 'tmpfs' | 'container' | 'shared'

/**
 * Git-worktree backend metadata. Matches session-hierarchy.md §4.9 /§7.2.
 */
export interface GitWorktreeBackendMeta {
	backend: 'git-worktree'
	/** Absolute path to the canonical repo (`.git` directory). */
	repoRoot: string
	/** Branch / ref the worktree tracks. */
	branch: string
	/** Absolute path to the worktree directory. */
	worktreePath: string
}

/**
 * Discriminated union of backend-specific metadata. Only `git-worktree` is
 * populated in Phase 3. Future variants (tmpfs, container, shared) must be
 * added here and to every exhaustive consumer.
 */
export type WorkspaceBackendMeta = GitWorktreeBackendMeta

/**
 * Persisted ref to a provisioned workspace. Every {@link Session} with a
 * running turn persists a {@link WorkspaceRef} so recovery after process
 * restart is possible (session-hierarchy.md §7.1).
 *
 * NOT `Project.rootPath`. This is per-TURN provisioning — a git worktree cut
 * for one turn and discarded after it, which may be a different directory
 * entirely. `Project.rootPath` is the durable binding a host uses to answer
 * "which project is this directory" across sessions and process restarts.
 * The two words are close enough that the distinction has been rediscovered
 * more than once; it is written here so it does not have to be again.
 *
 * A persisted ref is recovery data for the backend configuration that created
 * it, not authority for another driver instance to operate on an arbitrary
 * resource. Reference drivers validate that affiliation before inspection,
 * branching, or disposal.
 */
export interface WorkspaceRef {
	id: WorkspaceId
	meta: WorkspaceBackendMeta
	createdAt: Date
}