bantamkit-mcp 0.26.0

package/dist/memory/pyfs.d.ts

@@ -0,0 +1,521 @@
+/** The errno names this port claims to render in CPython's words. The suite reads it. */
+export declare const STRERROR_NAMES: readonly string[];
+/**
+ * `os.strerror` for one errno NAME — the table alone, with no Windows arm in front of it.
+ *
+ * The conformance case that checks these wordings used to read them back through
+ * `asPyOSError`, which now answers with the WIN32 message on Windows for exactly the codes
+ * the table also carries. Reading the table directly keeps that case measuring the thing its
+ * name says, and leaves the winerror wordings to the `winerror table` case beside it.
+ */
+export declare function pyStrerror(code: string): string | undefined;
+/**
+ * `type(exc).__name__` for an `OSError` with this errno NAME — the table and its default.
+ *
+ * ONE reader of `OSERROR_SUBCLASS` for two callers, because the default is half the rule:
+ * an unlisted errno is `OSError` in CPython, and a second `?? 'OSError'` written somewhere
+ * else is a second place for the two halves to drift apart. `PyOSError`'s own constructor
+ * takes its `name` from here, and `eventlog.ts` asks the same question of an exception it
+ * is about to record — the port had already decided this question in the constructor and
+ * the event log answered it with the JavaScript constructor name instead, recording
+ * `PyOSError` where CPython records `NotADirectoryError`.
+ */
+export declare function osErrorClassName(code: string): string;
+/**
+ * An `OSError` as Python prints one.
+ *
+ * `str(OSError)` is `[Errno {errno}] {strerror}: {filename!r}`, and that text is not
+ * decoration: `_ensure_dirs` lets a `FileExistsError` out of `save` unconverted, and
+ * `component.Memory.save` turns whatever comes out into the sentence a model reads.
+ * `errno` is the platform number, which is what Python prints and what libuv already
+ * gives us as the magnitude of `err.errno`.
+ */
+export declare class PyOSError extends Error {
+    readonly errno: number;
+    readonly code: string;
+    readonly strerror: string;
+    readonly filename: string | null;
+    /** `OSError.filename2` — set by the two-path syscalls, and PRINTED when it is. */
+    readonly filename2: string | null;
+    /**
+     * `OSError.winerror`, which exists ONLY on Windows and CHANGES `__str__`.
+     *
+     * CPython carries both numbers for a call that went through the Win32 API: the translated
+     * POSIX `errno` and the raw Win32 code. `OSError.__str__` prefers the latter and prints
+     * `[WinError %d] <the Win32 message>`. `null` here means "this OSError has no winerror",
+     * which is every OSError on POSIX and every OSError CPython raises on Windows out of the
+     * C runtime rather than out of the Win32 API — see `asPyOSError`'s `origin`.
+     */
+    readonly winerror: number | null;
+    constructor(errno: number, code: string, strerror: string, filename: string | null, filename2?: string | null, winerror?: number | null);
+}
+/** The winerrors this port claims to render in CPython's words. The suite reads it. */
+export declare const WINERROR_NUMBERS: readonly number[];
+/** One Win32 wording, as CPython trims it. The `winerror table` case checks every entry. */
+export declare function pyWinStrerror(winerror: number): string | undefined;
+/**
+ * Which SHAPE of Windows call produced an error, because CPython's answer depends on it.
+ *
+ * `os.stat`, `os.scandir`, `os.mkdir`, `os.replace` and `os.unlink` go through the Win32 API
+ * and raise an OSError with `winerror` SET. `open()` does NOT: it goes through the C runtime,
+ * which fills in `errno` alone, and `str()` of that error is the ordinary `[Errno %d]` form
+ * with the CRT's own POSIX wording. MEASURED, run 32646521489: opening a directory for write
+ * is `[Errno 13] Permission denied` on CPython-for-Windows — not `[WinError 5]`, and not the
+ * `[Errno 21] Is a directory` libuv reports. Getting this split wrong renders the right
+ * number in the wrong sentence.
+ */
+export type OSErrorOrigin = 'win32' | 'crt' | 'scandir';
+/**
+ * libuv's code -> the Win32 error CPython would have carried, or `null` for "no winerror".
+ *
+ * THE MAPPING IS MANY-TO-ONE IN THE DIRECTION THAT LOSES INFORMATION, which is why this
+ * cannot be a plain table. libuv translates every Win32 error into one POSIX-shaped code, so
+ * `ERROR_FILE_NOT_FOUND` (2) and `ERROR_PATH_NOT_FOUND` (3) both arrive as `ENOENT` and the
+ * distinction Windows drew has to be RE-DERIVED. Win32 picks 3 whenever the component that
+ * failed was needed AS A DIRECTORY and 2 when only the final name was missing, so the probe
+ * is exactly that: which of the components is not there.
+ *
+ * Verified against the reference for both arms on run 32646521489 — `os.replace` onto a
+ * missing destination DIRECTORY is 3, `os.replace` of a missing source FILE beside an
+ * existing directory is 2. `exists` is injected so the derivation is a pure function with a
+ * node that goes red on a laptop.
+ */
+export declare function winerrorFor(code: string, origin: OSErrorOrigin, path: string | null, dest: string | null, exists: (candidate: string) => boolean): number | null;
+/**
+ * `winerror_to_errno` — CPython's translation, which is NOT the one libuv already applied.
+ *
+ * THE CLASS COMES OFF THE ERRNO, and the errno CPython carries is the one IT derived from
+ * the Win32 code, not the one libuv derived. MEASURED, run 32651049453: `os.unlink` of a
+ * name holding a newline is `ERROR_INVALID_NAME` (123), which CPython translates to EINVAL
+ * — and EINVAL is not in `errnomap`, so the exception is a plain `OSError`. libuv had folded
+ * the same failure into ENOENT, so this port raised `FileNotFoundError` and a caller's
+ * `except FileNotFoundError` would have swallowed an error the reference lets past.
+ *
+ * Every other arm here is an identity on the codes this port can reach (2/3 -> ENOENT,
+ * 183 -> EEXIST, 267 -> ENOTDIR), which is why only the 123 case was visible. The table is
+ * written out in full anyway: an arm that happens to be an identity today is exactly the one
+ * that stops being one without anybody noticing.
+ */
+export declare function winerrorToCode(winerror: number): string;
+/**
+ * The C runtime's answer where it is NOT libuv's, for the calls `open()` makes.
+ *
+ * One entry, and it is measured: opening a directory for writing is `EISDIR` to libuv and
+ * `EACCES` to the Windows CRT, so CPython prints `[Errno 13] Permission denied` for the
+ * `.tmp` that shiftwork's clock-out could not write. Everything else the CRT can raise here
+ * — ENOENT, EACCES, EEXIST, EINVAL — already agrees with libuv in both number and wording.
+ */
+export declare function crtCode(code: string, path?: string | null): string;
+/**
+ * Does any component of this path hold a character Win32 forbids in a name?
+ *
+ * `< > : " | ? *` and every control character below U+0020. The separators are excluded
+ * because they SPLIT the name rather than sitting in one, and the drive's colon is excluded
+ * for the same reason — it is part of the anchor, not of a component. Windows also strips a
+ * trailing space or dot silently rather than refusing, so neither is treated as invalid.
+ */
+export declare function ntNameIsInvalid(path: string | null): boolean;
+/**
+ * A Node `fs` rejection, restated as the `OSError` CPython would have raised.
+ *
+ * An errno outside the table keeps libuv's own lowercase wording rather than a fabricated
+ * one — a wrong capital letter in a sentence a model reads is worse than a visibly
+ * different one, and the table is the thing the conformance suite can check.
+ *
+ * `origin` says which of CPython's two error paths the call would have taken on Windows;
+ * off Windows it changes nothing, because there is only one path there.
+ */
+export declare function asPyOSError(error: unknown, fallbackPath?: string, fallbackDest?: string, origin?: OSErrorOrigin): PyOSError;
+/** `UnicodeDecodeError`, which is a `ValueError` in Python and is NOT an `OSError`. */
+export declare class PyUnicodeDecodeError extends Error {
+    readonly start: number;
+    readonly end: number;
+    readonly reason: string;
+    constructor(bytes: Uint8Array, start: number, end: number, reason: string);
+}
+/**
+ * `bytes.decode("utf-8")` with `errors="strict"`, including the message.
+ *
+ * `TextDecoder` without `fatal` substitutes U+FFFD, which would let a corrupt fact file
+ * through and have `_stamp` write the substitution back over the original bytes — a
+ * silent, destructive divergence rather than a loud one. `fatal: true` raises, but with a
+ * `TypeError` whose text says nothing about where. `_facts` reads OUTSIDE its `try`, so
+ * this message is what a model sees for a binary file in `facts/`, verbatim.
+ *
+ * The three reasons and the reported span are CPython's, derived by running its decoder
+ * over 220 sequences and matched against all of them (the `utf-8 decode` cases in the
+ * conformance suite re-run that comparison).
+ *
+ * `ignoreBOM: true` IS THE DEFAULT SPELLING BACKWARDS, and it is the point. `TextDecoder`
+ * defaults `ignoreBOM` to FALSE, which means "treat a leading EF BB BF as a byte-order mark
+ * and DROP it". CPython's utf-8 codec has no such rule — `b'\xef\xbb\xbf'.decode('utf-8')`
+ * is `'\ufeff'`, one character, and `utf-8-sig` is the codec that strips it. The validator
+ * above already accepted EF BB BF as an ordinary three-byte sequence, so this module was
+ * checking one thing and returning another: N8 measured a BOM'd checkpoint that CPython
+ * REFUSES (`json.loads` answers `Unexpected UTF-8 BOM (decode using utf-8-sig)`) and that
+ * this port parsed and then WROTE. Every text read in the package now comes through here,
+ * `assets.ts` included, so there is one UTF-8 decode and not two with opposite answers.
+ */
+export declare function pyDecodeUtf8(bytes: Uint8Array): string;
+/**
+ * `Path.read_text(encoding="utf-8")`: strict UTF-8 AND universal-newline translation.
+ *
+ * The translation half is N2's `decodeFactBytes`, re-derived nowhere: this reads the bytes,
+ * decodes them strictly, and hands the string to the same fold. A CRLF fact file therefore
+ * parses in both runtimes, which is the property the codec suite already measures.
+ */
+export declare function pyReadText(path: string): string;
+/**
+ * `io.TextIOWrapper`'s outgoing newline translation, which is `newline=None`'s whole effect.
+ *
+ * THIS REVERSES N2's RULING, and the reason it was reversed is worth more than the ruling
+ * was. N2 wrote LF on every platform, arguing that CRLF "already disagrees with the store's
+ * own arithmetic" and that reproducing it "would make the same Fact emit different bytes on
+ * two machines". Both halves describe the REFERENCE, not a defect being avoided: CPython's
+ * `_check_index_budget` counts the LF string it just built while `write_text` puts CRLF on
+ * the disk, and CPython already emits different bytes for the same Fact on Windows and on
+ * macOS. A port that "fixes" that is not byte-compatible with the thing it stands beside —
+ * and byte-compatibility is the product, because the Python server and this one read and
+ * write the SAME store on the SAME machine. MEASURED, run 32646521489: 83 conformance cases
+ * differed by exactly this, one byte per line, in files both runtimes had just written.
+ *
+ * The arithmetic does not move. Python counts the in-memory LF text and so does this port;
+ * only the bytes leaving through `write` are translated, which is where CPython does it too.
+ *
+ * The translation is unconditional on `\n`, INCLUDING the `\n` of a `\r\n`: CPython emits
+ * `\r\r\n` for a string that already held a CRLF, and so does this.
+ */
+export declare function toCrlf(text: string): string;
+/** The same translation, gated the way CPython gates it: `#ifdef MS_WINDOWS`. */
+export declare function pyNewlineOut(text: string): string;
+/** `os.linesep` as one string — the line terminator a text-mode write actually emits. */
+export declare const PY_LINESEP: string;
+/** `Path.write_text(text, encoding="utf-8")`, newline translation included. */
+export declare function pyWriteText(path: string, text: string): void;
+/**
+ * `path.open("a", encoding="utf-8").write(text)` — the accounting log's append.
+ *
+ * Same newline translation as `pyWriteText`, for the same reason. One `appendFileSync` is
+ * one `open(O_APPEND)/write/close`, which is what CPython's `with` block does, so a line is
+ * never interleaved with another process's.
+ */
+export declare function pyAppendText(path: string, text: string): void;
+/**
+ * `os.path.lexists(path)` — `lstat` without following, and FALSE for every error.
+ *
+ * Not `lstatSync(p, {throwIfNoEntry: false})`: that returns `undefined` for ENOENT but
+ * still throws for EACCES on the parent, and `lexists` catches `(OSError, ValueError)`
+ * wholesale. This is the middle arm of the `_listing` three-way, so getting the error
+ * behaviour wrong turns an unreadable store back into an empty one.
+ */
+export declare function pyLexists(path: string): boolean;
+export declare function pyExists(path: string): boolean;
+/**
+ * `Path.mkdir(parents=True, exist_ok=True)`.
+ *
+ * `exist_ok` suppresses `FileExistsError` only when the path is a DIRECTORY: CPython
+ * re-raises when a regular file sits there, which is exactly how `save` fails on a store
+ * whose `facts/` is a file — before the listing, with a bare `FileExistsError`
+ * (`test_a_facts_path_that_is_not_a_directory_is_unreadable_not_empty` says so). Node's
+ * recursive `mkdirSync` raises EEXIST there too; this only restates the error.
+ */
+export declare function pyMkdirParents(path: string): void;
+/**
+ * `os.scandir(directory)` reduced to names, raising the way CPython does.
+ *
+ * The caller decides what a failure MEANS — that decision is `store._listing`'s and
+ * `layers.count_facts` makes a different one from the same syscall.
+ */
+export declare function pyScandirNames(directory: string): string[];
+/** The decision inside `scandirShape`, without the platform gate, so a laptop can fail it. */
+export declare function scandirIsNotADirectory(code: string, lexists: () => boolean): boolean;
+/**
+ * `fnmatch.fnmatch(name, "*.md")`, which is the match `pathlib.glob` performs.
+ *
+ * Two things it is not: it is not "ends with .md" on Windows, where `os.path.normcase`
+ * lowercases first and `FACT.MD` is therefore a fact; and it has no dotfile or
+ * directory-entry special case, so `.hidden.md` counts and a DIRECTORY called `x.md`
+ * counts. `_listing`'s docstring makes not changing the counted set an explicit
+ * requirement, so this deliberately keeps every oddity.
+ */
+export declare function matchesMd(name: string): boolean;
+/** `os.path.normcase` — identity off Windows, `s.replace('/', '\\').lower()` on it. */
+export declare function normcase(name: string): string;
+/**
+ * Python's `<` on `str`, which is CODEPOINT order. JS compares UTF-16 code units.
+ *
+ * They disagree for every astral character: `['\u{1F414}.md', '！.md'].sort()` puts the
+ * chicken first because its lead surrogate is 0xD83D, and Python puts it last because
+ * 0x1F414 > 0xFF01. `_fact_paths` sorts, `recall` breaks score ties on the name, and the
+ * index is written in that order — so a single astral fact name is enough to make two
+ * `index.md` files that differ.
+ */
+export declare function cmpCodepoint(a: string, b: string): number;
+/**
+ * `sorted(directory / name for name in names)` — sorting `Path`s, not strings.
+ *
+ * `PurePath` compares `_parts_normcase` tuples. Every path here shares a parent, so the
+ * comparison reduces to the last component; what survives is the CASE FOLD, which
+ * `_parts_normcase` applies on Windows and nowhere else. Ties under that fold keep listing
+ * order, because both runtimes sort stably.
+ */
+export declare function sortedPathNames(names: readonly string[]): string[];
+/**
+ * `sorted(paths)` when the paths are NESTED — the case `sortedPathNames` above cannot cover.
+ *
+ * `PurePath.__lt__` compares the `_parts_normcase` TUPLE, and a tuple comparison stops at
+ * the first component that differs; it never sees the separator. Sorting the same paths as
+ * STRINGS does see it, and `-` (0x2D) sorts before `/` (0x2F), so the two orders are
+ * opposite for a pair like `a/b` and `a-b`:
+ *
+ *     sorted([Path("assets/a/b"), Path("assets/a-b")]) -> ['assets/a/b', 'assets/a-b']
+ *     sorted(["assets/a/b", "assets/a-b"])             -> ['assets/a-b', 'assets/a/b']
+ *
+ * N3 measured that this does not bite `_fact_paths`, whose paths are all siblings of one
+ * directory. It DOES bite `mcpserver._tree_digest`, which walks a nested tree and folds the
+ * order straight into `assets_digest` — a digest computed in string order over the shipped
+ * pack is a different digest, silently, and `build_identity` exists precisely to be
+ * trustworthy about that. A shorter tuple sorts first when it is a prefix of the longer one,
+ * which is `[] < ['b']` and needs no special case.
+ */
+export declare function sortedPathParts(paths: readonly (readonly string[])[]): string[][];
+/**
+ * `PurePath.__truediv__` and `str(Path)`, for the shapes a store root can take.
+ *
+ * Not `path.join`: `join('/a/b/..', 'facts')` collapses to `/a/facts` while
+ * `str(Path('/a/b/..') / 'facts')` keeps `/a/b/../facts`. Both open the same file, but the
+ * store PRINTS this path in the sentence a model reads for an unreadable store, and a port
+ * whose error names a different path than the reference's is a difference nobody put in
+ * writing. Empty and `.` components are dropped, `..` is kept, and the anchor survives —
+ * which is `PurePath`'s parsing, not a normalization.
+ *
+ * On Windows the separator is `\` and `/` is also accepted as one; drive-relative paths
+ * (`C:foo`) and UNC roots are outside what a store root has ever been and are not modelled.
+ */
+export declare function pyJoin(...parts: string[]): string;
+/**
+ * `ntpath.splitroot` — drive, root, and the rest, ported branch for branch.
+ *
+ * The old spelling of `parsePath` counted leading separators the way `PurePosixPath` does,
+ * and that reading is WRONG ON WINDOWS in the direction that changes an answer: `//a/b` is
+ * not "a root and two components", it is a UNC share whose whole text is the drive, with no
+ * parents at all and nothing for `_walk_to_store` to iterate. MEASURED against CPython 3.12
+ * on run 32646521489 — `PureWindowsPath('//a/b').parents` is `[]` and this port answered
+ * `['\\\\a', '\\\\']`, which is a walk over two directories that do not exist.
+ *
+ * The result is spelled with the CALLER's separators, not normalised ones, exactly as
+ * `ntpath.splitroot` returns slices of its argument.
+ */
+export declare function ntSplitRoot(path: string): [string, string, string];
+/**
+ * `PurePath._parse_path` under the Windows flavour: drive, root and the `_tail` components.
+ *
+ * The `drv_parts` arm is not decoration. `splitroot` hands back a bare `\\server\share` with
+ * an EMPTY root, and pathlib puts the root back on when the drive names a real share (four
+ * pieces) or a `\\?\UNC\server\share` (six) — which is why `//a/b` prints with a trailing
+ * separator and `//a` does not.
+ */
+export declare function parseWindowsPath(path: string): {
+    drive: string;
+    root: string;
+    tail: string[];
+};
+/**
+ * `ntpath.join` — what `PurePath.__truediv__` actually feeds the parser.
+ *
+ * `PurePath('//a') / 'facts'` is `\\a\facts\`, not `\\a\facts`, because the join produces
+ * `//a\facts` and the RE-PARSE reads all of it as a share. Nothing else reproduces that.
+ */
+export declare function ntJoin(...parts: string[]): string;
+/**
+ * `PurePath._format_parsed_parts` under the Windows flavour — `str(PureWindowsPath)`.
+ *
+ * Exported, and every Windows arm below goes through it, so the flavour has exactly ONE
+ * implementation and the conformance suite can drive it against `PureWindowsPath` from a
+ * laptop instead of from a runner.
+ */
+export declare function winFormat(drive: string, root: string, tail: readonly string[]): string;
+/** `str(PureWindowsPath(path))`. */
+export declare function winStr(path: string): string;
+/** `PureWindowsPath.parents`. `//a/b` is a share and has NONE. */
+export declare function winParents(path: string): string[];
+/** `PureWindowsPath.name`. */
+export declare function winName(path: string): string;
+/** `PureWindowsPath.is_absolute()` — `bool(drive and root)`, so a bare `//a` is NOT one. */
+export declare function winIsAbsolute(path: string): boolean;
+/** `PureWindowsPath.with_suffix`, which rebuilds the path in the flavour's own spelling. */
+export declare function winWithSuffix(path: string, suffix: string): string;
+/**
+ * `PurePath.parents` — `_walk_to_store` iterates `(base, *base.parents)` and stops at `/`.
+ *
+ * The tail is not the anchor: `/a/b` yields `/a` then `/` and stops, while `a/b` yields `a`
+ * then `.` — a relative start walks to the CWD-relative dot and no further, which is why
+ * `_resolved_base` resolves before walking. `/` and `.` have no parents at all.
+ */
+export declare function pyParents(path: string): string[];
+/** `PurePath.parent`. `/`'s parent is `/` and `.`'s is `.`, as in Python. */
+export declare function pyParent(path: string): string;
+/** `PurePath.name` — the last component, or `''` for a bare anchor. */
+export declare function pyName(path: string): string;
+/**
+ * `PurePath.is_absolute()`.
+ *
+ * On Windows a root without a drive is NOT absolute (`PureWindowsPath('/a')` is relative to
+ * the current drive), which is why this is not "starts with a separator". `_pinned_store`
+ * raises on a relative pin, so getting this wrong there would accept a pin the reference
+ * refuses, or refuse one it accepts.
+ */
+export declare function pyIsAbsolute(path: string): boolean;
+/**
+ * `RuntimeError`, which `Path.expanduser()` and `Path.resolve()` raise. NOT an `OSError`, so
+ * nothing that catches `OSError` catches it — `_pinned_store`'s `except OSError` included.
+ */
+export declare class PyRuntimeError extends Error {
+    constructor(message: string);
+}
+/**
+ * `Path.home()`, which is `os.path.expanduser('~')`.
+ *
+ * `$HOME` FIRST, and only then the passwd database — verified by overriding it. That order
+ * is what lets the tests and the conformance harness point the profile layer somewhere that
+ * is not the operator's own facts; a port that read the uid's home directly would recall
+ * against, and STAMP, the real store on every run.
+ *
+ * An empty `HOME` is still a set `HOME` in Python (the test is `'HOME' not in os.environ`),
+ * and `''.rstrip('/') or '/'` makes it `/`. `os.homedir()` falls back to the passwd entry
+ * there instead, so the rule is spelled out rather than delegated.
+ *
+ * On Windows Python reads `USERPROFILE`, then `HOMEDRIVE`+`HOMEPATH`; `os.homedir()` reads
+ * `USERPROFILE` and then the API. The first arm is the same, and it is the one a host sets.
+ */
+export declare function pyHome(): string;
+/**
+ * `Path(raw).expanduser()`.
+ *
+ * Only a FIRST component beginning with `~` expands, and only when the path has no anchor;
+ * `/~/x` and `a/~` are left alone. An MCP host passes `env` verbatim with no shell, so the
+ * tilde arrives literal and this is the only thing that expands it — see `_pinned_store`.
+ *
+ * RULING — `~someone-else`. Python asks the passwd database and resolves any account on the
+ * machine (measured: `~root` -> `/var/root`). Node has no `getpwnam`, so this resolves `~`
+ * and `~<the current user>` and raises Python's own `RuntimeError` for anything else, where
+ * Python would have answered a path. Reproducing it means shelling out to `dscl`/`getent` at
+ * runtime — a subprocess, in a pure-Node package, for a spelling of the pin nothing has ever
+ * used. Carried as a must-differ case in `tools/conformance/suites/recall-strings.mjs`, so
+ * it is re-measured on every run rather than remembered.
+ */
+export declare function pyExpanduser(path: string): string;
+/** `Path.cwd()`. */
+export declare function pyCwd(): string;
+/**
+ * `Path.resolve()` with `strict=False`: `posixpath.realpath`, then pathlib's ELOOP check.
+ *
+ * WHY NOT `fs.realpathSync`: it is strict. `_resolved_base` resolves a START DIRECTORY that
+ * may not exist, and `load_grants` resolves a granted path precisely in order to then ask
+ * whether it exists. Python resolves as far as the filesystem goes and appends the rest
+ * verbatim — measured, `<bed>/nope/x` resolves to itself, and so does `<0o000-dir>/x/y`.
+ *
+ * `..` is applied to the path resolved SO FAR, not lexically to the input, so through a
+ * symlinked directory it lands in the target's parent. That is what makes a symlinked
+ * worktree bind the store beside its real checkout.
+ *
+ * A symlink LOOP is the one failure that is not swallowed: non-strict `realpath` returns the
+ * unresolved path, `Path.resolve` then stats it, gets ELOOP, and raises
+ * `RuntimeError("Symlink loop from %r" % e.filename)`. The `%r` is `repr`, not a pair of
+ * apostrophes — the second spelling of the `OSError.__str__` bug N8 found, and fixed the
+ * same way. Measured against CPython here.
+ *
+ * WINDOWS IS AN APPROXIMATION AND SAYS SO. `ntpath.realpath` goes through
+ * `GetFinalPathNameByHandle` and returns forms this cannot reproduce; there this resolves
+ * what it can natively and falls back to the lexical form. NOT MEASURED — no Windows runner
+ * has run this port.
+ */
+export declare function pyResolve(path: string): string;
+/**
+ * `ntpath.split` — the head keeps its trailing separators only where they are the root.
+ *
+ * Read off `Lib/ntpath.py` at 3.12, which is the interpreter the reference side runs:
+ * `return d + r + head.rstrip(seps), tail`, with no fallback to the unstripped head.
+ */
+export declare function ntSplit(path: string): [string, string];
+/**
+ * `ntpath.isabs`, which is NOT `PureWindowsPath.is_absolute()`.
+ *
+ * `ntpath` calls `\a` absolute — a leading separator is enough — while pathlib calls it
+ * relative, because a rooted path with no drive is relative to the CURRENT drive. CPython's
+ * own source labels the difference a LEGACY BUG and keeps it. Both readings are right for
+ * their own caller, and
+ * `realpath` is `ntpath`'s caller: it prepends the cwd on `not isabs(path)`, so using
+ * pathlib's stricter test there would join the cwd onto a path Windows already resolves
+ * from the drive root.
+ */
+export declare function ntIsAbs(path: string): boolean;
+/**
+ * `Path.is_dir()` — and it RE-RAISES, which is the half that matters.
+ *
+ * `pathlib` swallows only `_IGNORED_ERRNOS`; `EACCES` is not one of them, so a candidate
+ * inside a directory the process cannot traverse raises `PermissionError` out of the WALK
+ * itself. MEASURED against CPython 3.12 here: `_walk_to_store` through a `0o000` ancestor
+ * raises rather than skipping the candidate, which refutes the claim in `_pinned_store`'s
+ * docstring that the walk "lives with" an unreadable candidate. `existsSync` and
+ * `statSync(p, {throwIfNoEntry: false})` both answer `false` there and would bind a
+ * different store in silence.
+ */
+export declare function pyIsDir(path: string): boolean;
+/** `Path.is_file()`, with the same swallow set as `pyIsDir`. */
+export declare function pyIsFile(path: string): boolean;
+/**
+ * `os.stat(p)` reduced to "is it a directory", unguarded.
+ *
+ * `_pinned_store` uses `os.stat` rather than `is_dir()` on purpose: a pin is a single path
+ * the operator named out loud, so an unreadable one gets the accurate reason instead of
+ * being reported as a typo.
+ */
+export declare function pyStatIsDir(path: string): boolean;
+/**
+ * `repr(str)`, which `_pinned_store` interpolates with `{raw!r}` for a relative pin.
+ *
+ * Python quotes with `'` unless the value contains a `'` and no `"`; it escapes `\\`, the
+ * quote, `\t`, `\n`, `\r`, and every codepoint that is not `str.isprintable()` — that is,
+ * everything in a `C*` category and every separator except the space itself. JS spells the
+ * same predicate `\p{C}` / `\p{Z}` under the `u` flag, so this is the rule rather than a
+ * table. The escapes are `\xNN` below U+0100, `\uNNNN` below U+10000, `\UNNNNNNNN` above.
+ *
+ * The one place it can drift is a codepoint whose category changed between CPython 3.12's
+ * Unicode 15.0 and the ICU this Node was built against: a newly assigned character is `Cn`
+ * (not printable, escaped) for Python and assigned (printable, raw) here. A pin path made of
+ * brand-new codepoints is the only input that reaches it.
+ */
+export declare function pyRepr(value: string): string;
+/**
+ * `repr(float)`.
+ *
+ * CPython formats with `PyOS_double_to_string(v, 'r', 0, Py_DTSF_ADD_DOT_0)`: the shortest
+ * decimal that round-trips, rendered in scientific notation when the decimal point falls at
+ * or left of position -4 or right of position 16, and with a forced `.0` otherwise. JS
+ * agrees on the DIGITS (`toExponential()` with no argument is also shortest-round-trip) and
+ * on nothing else: it switches to scientific at 1e21 and 1e-7, writes `10000000000000000`
+ * where Python writes `1e+16`, and never pads the exponent to two digits.
+ */
+export declare function pyFloatRepr(x: number): string;
+/**
+ * `PurePath.with_suffix(suffix)` on the LAST component.
+ *
+ * `_write_fact` writes `path.with_suffix(".md.tmp")`, and the rule is not "append": a name
+ * whose last component already has a suffix has that suffix REPLACED, while a component
+ * that is all leading dots has one appended. `facts/a.b.md` -> `facts/a.b.md.tmp`, and the
+ * degenerate `facts/.md` (a fact whose frontmatter name is empty) -> `facts/.md.md.tmp`.
+ */
+export declare function pyWithSuffix(path: string, suffix: string): string;
+/**
+ * `PurePath.suffix` as a value, which `shiftwork.clock_out` needs on its own:
+ * `path.with_suffix(path.suffix + ".tmp")` turns `cp.json` into `cp.json.tmp` and a
+ * suffix-less `cp` into `cp.tmp`, and the two arms are only distinguishable by reading the
+ * suffix first.
+ */
+export declare function pySuffix(path: string): string;
+/** `Path.unlink()` and `Path.replace(target)`, with CPython's error text. */
+export declare function pyUnlink(path: string): void;
+export declare function pyReplace(source: string, target: string): void;
+/** `date.fromtimestamp(path.stat().st_mtime).isoformat()` — LOCAL, like `date.today()`. */
+export declare function pyMtimeDate(path: string): string;