@sema-agent/core/dist/core/physical-path.d.ts

Stateless, task-oriented AI agent core

/**
 * THE physical path of a path — one spelling for the whole tree.
 *
 * A physical path is what `realpath(3)` answers: every symlink resolved and, on a case-insensitive
 * volume, the directory entry's ON-DISK spelling. That last half is the reason this module exists.
 * Node has two realpaths and they disagree exactly there (measured on macOS): `realpathSync.native`
 * and `fsPromises.realpath` are the libuv call and return the disk case, while the JS `fs.realpathSync`
 * resolves the links but PRESERVES the caller's casing. A tree that used both minted two spellings for
 * one directory, so a key minted on one face could not be found on the other — a memory write root
 * spelled `…/Proj` by configuration was keyed `…/Proj` by the engine's gates and resolved to `…/proj`
 * by the execution env's fence, and the advertised-writable-directory seat had to refuse the hole its
 * own instruction taught.
 *
 * Case FOLDING is not part of a path's identity and is not done here: folding a filesystem PATH names a
 * different directory on a case-sensitive volume. A store whose in-memory KEY must fold (see
 * `canonicalStoreKey`) folds this answer at its own call site.
 */
export declare function physicalPathOf(p: string): string;
/** The spelling the memory layout keyed by BEFORE this mint — links resolved, the caller's casing kept (the JS
 *  `fs.realpathSync`, which differs from the native call exactly there). Migration probes only: never an identity. */
export declare function priorCallerCasedPathOf(p: string): string;
/** The async door onto the same rule (`fsPromises.realpath` is the libuv call `realpathSync.native`
 *  makes). The `ExecutionEnv` faces take this one: a sync realpath against a hung network mount blocks
 *  the event loop for the mount timeout, and every pending abort with it. */
export declare function physicalPathOfAsync(p: string): Promise<string>;
/**
 * {@link physicalPathOf} for a path that need not exist yet: the deepest ancestor that resolves,
 * canonicalized, with the missing tail rejoined — so a not-yet-created target is still judged against
 * roots that are physical paths, and a symlinked PARENT still cannot carry a write past them (the
 * parent is exactly what gets resolved before the tail is rejoined).
 *
 * Total, by construction rather than by swallowing: a path with no resolvable ancestor at all has no
 * physical form to answer with, and the absolute lexical form is that answer. Callers that must
 * distinguish "unresolvable" from "does not exist yet" call {@link physicalPathOf} and handle the throw
 * beside their own contract.
 */
export declare function physicalPathOfExisting(p: string): string;