@deepwatch/dsh-contracts 0.1.0

package/lib/language.js

@@ -0,0 +1,202 @@
+/**
+ * Language-aware evidence.
+ *
+ * The correction this module encodes (spec §37): Watch is not an English
+ * product with translations bolted on, and it is not an Arabic one either. It
+ * is language-independent architecture with a *measured* support matrix — and
+ * the two claims are very different. "Handles Unicode" is architecture.
+ * "Reads Thai subtitles well" is a measurement, and it belongs to a
+ * qualification result rather than to a type.
+ *
+ * Five things are kept separate that products routinely conflate:
+ *
+ * ```
+ * UI locale            what the interface is in
+ * source language(s)   what the material is in
+ * script(s)            what alphabet it is written in
+ * response language    what the agent answers in
+ * translation target   an optional derived view
+ * ```
+ *
+ * Changing the interface language must not translate evidence. A source can
+ * contain several languages in one frame. And a translation is *derived data
+ * with its own provenance* — the original text stays the evidence, because a
+ * citation that resolved to a translation would be citing something no one
+ * ever said.
+ *
+ * @module @deepwatch/dsh-contracts/language
+ */
+/** Scripts that are written right to left. */
+const RTL_SCRIPTS = new Set(['Arabic', 'Hebrew']);
+/**
+ * Detect the scripts present in a string.
+ *
+ * Range-based rather than library-based on purpose: this runs on the browser
+ * side of an evidence panel, and pulling a full ICU table into a bundle to
+ * answer "is there Arabic in here" is not a trade worth making. It is
+ * deliberately coarse — it reports which scripts appear, which is what
+ * direction and routing need, not a language identification.
+ */
+export function detectScripts(text) {
+    const found = new Set();
+    for (const character of text) {
+        const code = character.codePointAt(0);
+        if (code === undefined)
+            continue;
+        // Skip anything that carries no script identity: digits, punctuation,
+        // whitespace. Counting them would make every string "Latin".
+        if (code < 0x0041)
+            continue;
+        if (code <= 0x024f)
+            found.add('Latin');
+        else if (code >= 0x0370 && code <= 0x03ff)
+            found.add('Greek');
+        else if (code >= 0x0400 && code <= 0x04ff)
+            found.add('Cyrillic');
+        else if (code >= 0x0590 && code <= 0x05ff)
+            found.add('Hebrew');
+        else if (code >= 0x0600 && code <= 0x06ff)
+            found.add('Arabic');
+        else if (code >= 0x0750 && code <= 0x077f)
+            found.add('Arabic');
+        else if (code >= 0x0900 && code <= 0x097f)
+            found.add('Devanagari');
+        else if (code >= 0x0e00 && code <= 0x0e7f)
+            found.add('Thai');
+        else if (code >= 0x0e80 && code <= 0x0eff)
+            found.add('Lao');
+        else if (code >= 0x0f00 && code <= 0x0fff)
+            found.add('Tibetan');
+        else if (code >= 0x1000 && code <= 0x109f)
+            found.add('Myanmar');
+        else if (code >= 0x1780 && code <= 0x17ff)
+            found.add('Khmer');
+        else if (code >= 0x3040 && code <= 0x309f)
+            found.add('Hiragana');
+        else if (code >= 0x30a0 && code <= 0x30ff)
+            found.add('Katakana');
+        else if (code >= 0x4e00 && code <= 0x9fff)
+            found.add('Han');
+        else if (code >= 0xac00 && code <= 0xd7af)
+            found.add('Hangul');
+        else if (code >= 0xfb50 && code <= 0xfdff)
+            found.add('Arabic');
+        else if (code >= 0xfe70 && code <= 0xfeff)
+            found.add('Arabic');
+    }
+    return found.size === 0 ? ['Unknown'] : [...found].sort();
+}
+/**
+ * Which way a string reads.
+ *
+ * `mixed` is a real answer, not a failure to decide. A layout that renders
+ * mixed content as though it were uniformly one direction produces text that
+ * is technically present and unreadable.
+ */
+export function detectDirection(text) {
+    const scripts = detectScripts(text);
+    if (scripts.length === 1 && scripts[0] === 'Unknown')
+        return 'unknown';
+    const hasRtl = scripts.some(script => RTL_SCRIPTS.has(script));
+    const hasLtr = scripts.some(script => script !== 'Unknown' && !RTL_SCRIPTS.has(script));
+    if (hasRtl && hasLtr)
+        return 'mixed';
+    if (hasRtl)
+        return 'rtl';
+    return 'ltr';
+}
+/**
+ * Normalize text for retrieval.
+ *
+ * NFKC plus case folding plus combining-mark removal: enough that a query
+ * typed without diacritics finds text written with them, and that half-width
+ * and full-width forms match. Deliberately not stemming or transliteration —
+ * those change what a word means, and an index that matched across them would
+ * return hits a person cannot see the reason for.
+ */
+export function normalizeForRetrieval(text) {
+    return text
+        // NFKD, not NFKC. Compatibility *decomposition* is what separates a
+        // precomposed É into E plus a combining acute so the next step can remove
+        // it; NFKC would compose it back into one codepoint that matches no
+        // combining-mark pattern, and the diacritic would survive the fold.
+        .normalize('NFKD')
+        .toLowerCase()
+        // Strip combining marks. This folds Arabic and Hebrew vowel points and
+        // Latin accents alike, which is what makes a query match text that was
+        // written more carefully than it was typed.
+        .replace(/\p{M}+/gu, '')
+        // Recompose. NFKD also splits Hangul syllables into jamo, and leaving them
+        // apart would mean composed and decomposed Korean no longer match each
+        // other — the exact failure this function exists to prevent.
+        .normalize('NFC')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+/**
+ * Build the language-aware text for an observed span.
+ *
+ * The normalized form is computed here rather than accepted from a caller, so
+ * every index in the product folds text the same way. Two normalizers that
+ * disagree produce a search that finds a result in one surface and not in
+ * another, for reasons nobody can see.
+ */
+export function describeText(originalText, producer, producerVersion, options = {}) {
+    return {
+        originalText,
+        normalizedText: normalizeForRetrieval(originalText),
+        languageTags: options.languageTags ?? [],
+        scripts: detectScripts(originalText),
+        direction: detectDirection(originalText),
+        languageConfidence: options.languageConfidence ?? null,
+        producer,
+        producerVersion,
+        translations: [],
+        qualityWarnings: options.qualityWarnings ?? [],
+    };
+}
+/**
+ * Attach a translation without disturbing the original.
+ *
+ * Returns a new value. The original text is unchanged and stays first, because
+ * the moment a translation could overwrite it, a citation would resolve to
+ * something nobody said.
+ */
+export function withTranslation(text, translation) {
+    return { ...text, translations: [...text.translations, translation] };
+}
+/**
+ * What a surface should display, given a reader's preference.
+ *
+ * Returns the original unless a translation for the requested language exists,
+ * and always says which it returned. A caller that renders this without
+ * showing `isOriginal` is presenting derived text as observed text.
+ */
+export function displayText(text, preferredLanguage) {
+    if (preferredLanguage === null) {
+        return { text: text.originalText, isOriginal: true, direction: text.direction };
+    }
+    const translation = text.translations.find(entry => entry.targetLanguage === preferredLanguage);
+    if (translation === undefined) {
+        return { text: text.originalText, isOriginal: true, direction: text.direction };
+    }
+    return {
+        text: translation.text,
+        isOriginal: false,
+        // The translation's own direction, not the original's: rendering Arabic
+        // output with the source's ltr direction produces unreadable text.
+        direction: detectDirection(translation.text),
+    };
+}
+/**
+ * Whether a span must be isolated from the surrounding text direction.
+ *
+ * Code, URLs, identifiers and timestamps read left to right inside an
+ * otherwise right-to-left paragraph, and without isolation the bidi algorithm
+ * reorders them into something that looks plausible and is wrong — a path with
+ * its segments reversed, a timestamp reading 30:2.
+ */
+export function needsDirectionIsolation(kind) {
+    return ['code', 'url', 'path', 'identifier', 'timestamp', 'digest', 'version'].includes(kind);
+}
+//# sourceMappingURL=language.js.map

package/lib/paths.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Keeping this machine's directory names out of everything that leaves it.
+ *
+ * A workspace was selected, and from then on `D:\Ws` appeared in the Context
+ * panel, in the session log, and in the text handed to the model — because a
+ * workspace is a directory and every layer below the UI quite reasonably
+ * carries the directory. None of those places needed the absolute path. The
+ * panel needed a name, the log needed something stable to group by, and the
+ * model needed to know which files exist relative to a root it never has to
+ * name.
+ *
+ * So this module converts a real path into a *logical* one: `<workspace>/src`
+ * rather than `D:\Ws\src`. The logical form is stable, comparable, and says
+ * everything the reader needs, and the real path stays on the Host where the
+ * filesystem actually is.
+ *
+ * **Structured, never blanket.** The one thing this must not do is replace
+ * substrings across arbitrary text: evidence content, a transcript, a captured
+ * page, a user's own message may legitimately contain a string that looks like
+ * a path, and rewriting it would corrupt the very record the product exists to
+ * preserve. Everything here therefore operates on a *named field* or on a
+ * bounded diagnostic string a caller has explicitly identified. There is no
+ * function in this file that takes a document and scrubs it.
+ *
+ * Windows makes the comparison harder than it looks, and each of these is
+ * handled rather than hoped about: drive letters differ in case (`D:\` and
+ * `d:\` are one directory), separators are mixed within a single string by the
+ * time Node and a shell have both touched it, UNC paths have a leading `\\`
+ * that is not a separator, and a prefix match without a boundary check makes
+ * `D:\Wsuite` look like it is inside `D:\Ws`.
+ *
+ * @module @deepwatch/dsh-contracts/paths
+ */
+/** A local root worth naming rather than printing. */
+export type PathRootKind = 
+/** The directory the user chose to work in. */
+'workspace'
+/** The DeepWatch profile: runtime, receipts, profile state. */
+ | 'profile'
+/** The DeepSeek Harness home inside that profile. */
+ | 'dsh-home'
+/** A source checkout, present only on a developer's machine. */
+ | 'checkout'
+/** The operating system user's home directory. */
+ | 'home'
+/** The system temporary directory. */
+ | 'temp';
+/** One root, and the label that replaces it. */
+export interface PathRoot {
+    readonly kind: PathRootKind;
+    /** The real absolute path. Never rendered, never sent. */
+    readonly path: string;
+    /**
+     * What a reader sees instead, without the angle brackets.
+     *
+     * Defaults to the kind, so `workspace` renders as `<workspace>`. A caller
+     * with two workspaces open can pass `workspace:notes` and keep them apart
+     * without either becoming a directory name.
+     */
+    readonly label?: string;
+}
+/** The roots a redaction is measured against, longest first. */
+export type PathRoots = readonly PathRoot[];
+/**
+ * Whether a string is an absolute local path in any of the three shapes.
+ *
+ * Used to decide whether a *field known to hold a path* needs converting. It
+ * is deliberately not used to scan prose.
+ */
+export declare function isAbsoluteLocalPath(value: string): boolean;
+/**
+ * One comparable spelling of a path.
+ *
+ * Separators become `/`, a trailing separator is dropped, and a drive letter
+ * is upper-cased — Windows treats `d:` and `D:` as one directory and a
+ * case-sensitive comparison would miss half the matches. The rest of the path
+ * keeps its case: on a case-sensitive filesystem `src` and `SRC` are two
+ * directories, and folding them would make the redaction wrong in the other
+ * direction.
+ */
+export declare function normalisePath(value: string): string;
+/**
+ * Whether `candidate` is `root` or sits inside it.
+ *
+ * The separator check is the whole point: a bare `startsWith` reports that
+ * `D:\Wsuite` is inside `D:\Ws`, which would redact an unrelated
+ * directory and leave the reader with a path that never existed.
+ */
+export declare function isInsideRoot(root: string, candidate: string): boolean;
+/**
+ * One comparable spelling with `.` and `..` resolved away.
+ *
+ * Separate from {@link normalisePath} because the two answer different
+ * questions. Redaction asks "does this path start with a root I know", and a
+ * literal spelling is the right input for that. Containment asks "where does
+ * this path actually land", and there the literal spelling is the attack:
+ * `<workspace>/../elsewhere/notes.md` starts with the workspace and is not
+ * inside it. A containment check that skips this step reports the boundary
+ * holding while a call walks straight out of it.
+ *
+ * A `..` that would climb above the root is dropped rather than escaping into
+ * a relative prefix, so the result is always anchored where it started.
+ */
+export declare function resolveTraversal(value: string): string;
+/**
+ * Whether a path lands inside a root once traversal is resolved.
+ *
+ * The containment question, and the one a boundary must ask.
+ * {@link isInsideRoot} is the redaction question and stays literal; this one
+ * resolves first, so `<root>/../elsewhere` is outside and `<root>/./a/../b` is
+ * inside.
+ *
+ * It cannot see a symlink or a junction — that needs the filesystem, and this
+ * package is shared with the browser. The Host resolves those before calling
+ * this; the two together are the boundary.
+ */
+export declare function containsPath(root: string, candidate: string): boolean;
+/**
+ * The logical form of a path, or the path unchanged when no root contains it.
+ *
+ * Roots are tried longest-first so a workspace nested inside a profile is
+ * reported as `<workspace>/…` rather than `<profile>/workspace/…`: the more
+ * specific name is the more useful one.
+ *
+ * A path under no known root is returned as it came in. That is deliberate —
+ * silently mangling an unrecognised path would make a diagnostic unreadable —
+ * and it is why {@link assertNoLocalPath} exists for the surfaces where an
+ * unrecognised absolute path must be a failure rather than a passthrough.
+ */
+export declare function redactPath(value: string, roots: PathRoots): string;
+/**
+ * The path relative to a root, for the places that want no label at all.
+ *
+ * What a model should be given: `src/index.ts`, not `<workspace>/src/index.ts`
+ * and certainly not `D:\Ws\src\index.ts`. Returns null when the path is not
+ * inside the root, so a caller cannot accidentally send an absolute path by
+ * treating a failed conversion as a success.
+ */
+export declare function relativeToRoot(value: string, root: string): string | null;
+/**
+ * Redact only the named fields of a record.
+ *
+ * The safe shape of this operation. A caller says which keys hold paths, and
+ * nothing else in the object is examined — so a `content`, a `transcript` or a
+ * `message` beside them is carried through byte for byte.
+ *
+ * @param record - the object to copy.
+ * @param fields - the keys whose string values are paths.
+ * @param roots - the roots to measure against.
+ * @returns a shallow copy with those fields converted.
+ */
+export declare function redactFields<T extends Record<string, unknown>>(record: T, fields: readonly (keyof T & string)[], roots: PathRoots): T;
+/**
+ * Redact one diagnostic string a caller has identified as path-bearing.
+ *
+ * Bounded on purpose: it rewrites only complete path tokens, delimited by
+ * whitespace, quotes or the common punctuation a path is wrapped in when it
+ * lands in a message. It is for a log line or an error detail whose shape the
+ * caller knows — never for evidence, a transcript, a captured document or
+ * anything a person wrote.
+ */
+export declare function redactDiagnosticText(text: string, roots: PathRoots): string;
+/**
+ * Every absolute local path a string still contains.
+ *
+ * The test-facing half. A surface that must never carry one asserts this is
+ * empty, and gets the offending text back rather than a bare false.
+ *
+ * A path preceded by `//` in a URL is skipped: `https://host/home/x` names a
+ * server's route, not this machine's disk, and reporting it would be a false
+ * alarm in exactly the diagnostics a reader needs.
+ *
+ * The same false alarm reached the Windows branch by a subtler route, and cost
+ * more: a drive letter is one letter followed by a colon, and `https:` ends in
+ * exactly that shape. Every ordinary URL was therefore reported as a local
+ * path — `s://api.example.com` — so `assertNoLocalPath` threw on honest
+ * diagnostics like "failed to reach https://…", which is precisely the kind of
+ * guard somebody switches off. The lookbehind is what makes a drive letter a
+ * drive letter: nothing alphabetic before it, and no colon before a `//`.
+ *
+ * `file:///D:/Ws/x` still matches, and should: a file URL carries a real local
+ * path, and the `D:` in it is preceded by `/` rather than by a scheme.
+ */
+export declare function findAbsolutePaths(text: string): readonly string[];
+/**
+ * Throw when a value that must be free of local paths is not.
+ *
+ * Used at the boundaries where a passthrough would be a leak rather than a
+ * convenience: a provider payload, an export, a rendered surface. The message
+ * names the field and the offending token so the failure is fixable, and it is
+ * a programming error rather than a runtime condition.
+ */
+export declare function assertNoLocalPath(where: string, value: string): void;
+//# sourceMappingURL=paths.d.ts.map

package/lib/paths.js

@@ -0,0 +1,286 @@
+/**
+ * Keeping this machine's directory names out of everything that leaves it.
+ *
+ * A workspace was selected, and from then on `D:\Ws` appeared in the Context
+ * panel, in the session log, and in the text handed to the model — because a
+ * workspace is a directory and every layer below the UI quite reasonably
+ * carries the directory. None of those places needed the absolute path. The
+ * panel needed a name, the log needed something stable to group by, and the
+ * model needed to know which files exist relative to a root it never has to
+ * name.
+ *
+ * So this module converts a real path into a *logical* one: `<workspace>/src`
+ * rather than `D:\Ws\src`. The logical form is stable, comparable, and says
+ * everything the reader needs, and the real path stays on the Host where the
+ * filesystem actually is.
+ *
+ * **Structured, never blanket.** The one thing this must not do is replace
+ * substrings across arbitrary text: evidence content, a transcript, a captured
+ * page, a user's own message may legitimately contain a string that looks like
+ * a path, and rewriting it would corrupt the very record the product exists to
+ * preserve. Everything here therefore operates on a *named field* or on a
+ * bounded diagnostic string a caller has explicitly identified. There is no
+ * function in this file that takes a document and scrubs it.
+ *
+ * Windows makes the comparison harder than it looks, and each of these is
+ * handled rather than hoped about: drive letters differ in case (`D:\` and
+ * `d:\` are one directory), separators are mixed within a single string by the
+ * time Node and a shell have both touched it, UNC paths have a leading `\\`
+ * that is not a separator, and a prefix match without a boundary check makes
+ * `D:\Wsuite` look like it is inside `D:\Ws`.
+ *
+ * @module @deepwatch/dsh-contracts/paths
+ */
+/** Windows drive-absolute, e.g. `D:\Ws` or `d:/Ws`. */
+const DRIVE_ABSOLUTE = /^[A-Za-z]:[\\/]/;
+/** UNC, e.g. `\\server\share\dir`. */
+const UNC_ABSOLUTE = /^[\\/]{2}[^\\/]+[\\/]+[^\\/]+/;
+/**
+ * Whether a string is an absolute local path in any of the three shapes.
+ *
+ * Used to decide whether a *field known to hold a path* needs converting. It
+ * is deliberately not used to scan prose.
+ */
+export function isAbsoluteLocalPath(value) {
+    return DRIVE_ABSOLUTE.test(value) || UNC_ABSOLUTE.test(value) || value.startsWith('/');
+}
+/**
+ * One comparable spelling of a path.
+ *
+ * Separators become `/`, a trailing separator is dropped, and a drive letter
+ * is upper-cased — Windows treats `d:` and `D:` as one directory and a
+ * case-sensitive comparison would miss half the matches. The rest of the path
+ * keeps its case: on a case-sensitive filesystem `src` and `SRC` are two
+ * directories, and folding them would make the redaction wrong in the other
+ * direction.
+ */
+export function normalisePath(value) {
+    const slashed = value.replace(/\\/g, '/');
+    const drive = /^([A-Za-z]):\//.exec(slashed);
+    const cased = drive === null
+        ? slashed
+        : `${drive[1]?.toUpperCase() ?? ''}:/${slashed.slice(3)}`;
+    return cased.length > 1 && cased.endsWith('/') ? cased.slice(0, -1) : cased;
+}
+/**
+ * Whether `candidate` is `root` or sits inside it.
+ *
+ * The separator check is the whole point: a bare `startsWith` reports that
+ * `D:\Wsuite` is inside `D:\Ws`, which would redact an unrelated
+ * directory and leave the reader with a path that never existed.
+ */
+export function isInsideRoot(root, candidate) {
+    const base = normalisePath(root);
+    const target = normalisePath(candidate);
+    if (base === target)
+        return true;
+    // Windows is case-insensitive about the whole path in practice, but only the
+    // drive is folded above; comparing the remainder exactly is the safe side of
+    // that trade — a missed redaction is caught by tests, a wrong one is not.
+    return target.startsWith(base.endsWith('/') ? base : `${base}/`);
+}
+/**
+ * One comparable spelling with `.` and `..` resolved away.
+ *
+ * Separate from {@link normalisePath} because the two answer different
+ * questions. Redaction asks "does this path start with a root I know", and a
+ * literal spelling is the right input for that. Containment asks "where does
+ * this path actually land", and there the literal spelling is the attack:
+ * `<workspace>/../elsewhere/notes.md` starts with the workspace and is not
+ * inside it. A containment check that skips this step reports the boundary
+ * holding while a call walks straight out of it.
+ *
+ * A `..` that would climb above the root is dropped rather than escaping into
+ * a relative prefix, so the result is always anchored where it started.
+ */
+export function resolveTraversal(value) {
+    const normalised = normalisePath(value);
+    const prefix = /^(?:[A-Z]:\/|\/\/[^/]+\/[^/]+\/|\/)/.exec(normalised)?.[0] ?? '';
+    const rest = normalised.slice(prefix.length);
+    const out = [];
+    for (const segment of rest.split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            out.pop();
+            continue;
+        }
+        out.push(segment);
+    }
+    const joined = `${prefix}${out.join('/')}`;
+    return joined.length > 1 && joined.endsWith('/') ? joined.slice(0, -1) : joined;
+}
+/**
+ * Whether a path lands inside a root once traversal is resolved.
+ *
+ * The containment question, and the one a boundary must ask.
+ * {@link isInsideRoot} is the redaction question and stays literal; this one
+ * resolves first, so `<root>/../elsewhere` is outside and `<root>/./a/../b` is
+ * inside.
+ *
+ * It cannot see a symlink or a junction — that needs the filesystem, and this
+ * package is shared with the browser. The Host resolves those before calling
+ * this; the two together are the boundary.
+ */
+export function containsPath(root, candidate) {
+    return isInsideRoot(resolveTraversal(root), resolveTraversal(candidate));
+}
+/** The label a root renders as, in angle brackets. */
+function labelOf(root) {
+    return `<${root.label ?? root.kind}>`;
+}
+/**
+ * The logical form of a path, or the path unchanged when no root contains it.
+ *
+ * Roots are tried longest-first so a workspace nested inside a profile is
+ * reported as `<workspace>/…` rather than `<profile>/workspace/…`: the more
+ * specific name is the more useful one.
+ *
+ * A path under no known root is returned as it came in. That is deliberate —
+ * silently mangling an unrecognised path would make a diagnostic unreadable —
+ * and it is why {@link assertNoLocalPath} exists for the surfaces where an
+ * unrecognised absolute path must be a failure rather than a passthrough.
+ */
+export function redactPath(value, roots) {
+    if (value === '')
+        return value;
+    const ordered = [...roots].sort((a, b) => normalisePath(b.path).length - normalisePath(a.path).length);
+    for (const root of ordered) {
+        if (!isInsideRoot(root.path, value))
+            continue;
+        const base = normalisePath(root.path);
+        const target = normalisePath(value);
+        const rest = target.slice(base.length).replace(/^\//, '');
+        return rest === '' ? labelOf(root) : `${labelOf(root)}/${rest}`;
+    }
+    return value;
+}
+/**
+ * The path relative to a root, for the places that want no label at all.
+ *
+ * What a model should be given: `src/index.ts`, not `<workspace>/src/index.ts`
+ * and certainly not `D:\Ws\src\index.ts`. Returns null when the path is not
+ * inside the root, so a caller cannot accidentally send an absolute path by
+ * treating a failed conversion as a success.
+ */
+export function relativeToRoot(value, root) {
+    if (!isInsideRoot(root, value))
+        return null;
+    const base = normalisePath(root);
+    const target = normalisePath(value);
+    return target === base ? '.' : target.slice(base.length).replace(/^\//, '');
+}
+/**
+ * Redact only the named fields of a record.
+ *
+ * The safe shape of this operation. A caller says which keys hold paths, and
+ * nothing else in the object is examined — so a `content`, a `transcript` or a
+ * `message` beside them is carried through byte for byte.
+ *
+ * @param record - the object to copy.
+ * @param fields - the keys whose string values are paths.
+ * @param roots - the roots to measure against.
+ * @returns a shallow copy with those fields converted.
+ */
+export function redactFields(record, fields, roots) {
+    const out = { ...record };
+    for (const field of fields) {
+        const value = out[field];
+        if (typeof value === 'string')
+            out[field] = redactPath(value, roots);
+    }
+    return out;
+}
+/**
+ * Redact one diagnostic string a caller has identified as path-bearing.
+ *
+ * Bounded on purpose: it rewrites only complete path tokens, delimited by
+ * whitespace, quotes or the common punctuation a path is wrapped in when it
+ * lands in a message. It is for a log line or an error detail whose shape the
+ * caller knows — never for evidence, a transcript, a captured document or
+ * anything a person wrote.
+ */
+export function redactDiagnosticText(text, roots) {
+    let out = text;
+    const ordered = [...roots].sort((a, b) => normalisePath(b.path).length - normalisePath(a.path).length);
+    for (const root of ordered) {
+        const base = normalisePath(root.path);
+        // Both spellings, because a path reaches a message through Node (forward
+        // slashes) and through a shell or a Windows API (backslashes) equally often.
+        for (const spelling of [base, base.replace(/\//g, '\\')]) {
+            const pattern = new RegExp(
+            // portability-ok: a character class matching either separator, not a path
+            // this module builds. Reading paths written on another platform is the job.
+            `${escapeForPattern(spelling)}(?![A-Za-z0-9_.-])([\\\\/][^\\s"'\`,;)\\]]*)?`, 'g'); // portability-ok
+            out = out.replace(pattern, (_match, rest) => rest === undefined || rest === ''
+                ? labelOf(root)
+                : `${labelOf(root)}${rest.replace(/\\/g, '/')}`);
+        }
+    }
+    return out;
+}
+/** Escape a literal for use inside a regular expression. */
+function escapeForPattern(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * POSIX directories that hold a person's machine rather than a server's URL
+ * space.
+ *
+ * A bare leading `/` cannot be the test: `/api/v1/chat` is a URL path and
+ * appears in every honest diagnostic this product writes, so matching it would
+ * make the assertion below fire constantly and be switched off. These are the
+ * roots a real leak comes from.
+ */
+const POSIX_LOCAL_ROOTS = ['home', 'Users', 'var', 'tmp', 'root', 'mnt', 'media', 'opt', 'private'];
+/**
+ * Every absolute local path a string still contains.
+ *
+ * The test-facing half. A surface that must never carry one asserts this is
+ * empty, and gets the offending text back rather than a bare false.
+ *
+ * A path preceded by `//` in a URL is skipped: `https://host/home/x` names a
+ * server's route, not this machine's disk, and reporting it would be a false
+ * alarm in exactly the diagnostics a reader needs.
+ *
+ * The same false alarm reached the Windows branch by a subtler route, and cost
+ * more: a drive letter is one letter followed by a colon, and `https:` ends in
+ * exactly that shape. Every ordinary URL was therefore reported as a local
+ * path — `s://api.example.com` — so `assertNoLocalPath` threw on honest
+ * diagnostics like "failed to reach https://…", which is precisely the kind of
+ * guard somebody switches off. The lookbehind is what makes a drive letter a
+ * drive letter: nothing alphabetic before it, and no colon before a `//`.
+ *
+ * `file:///D:/Ws/x` still matches, and should: a file URL carries a real local
+ * path, and the `D:` in it is preceded by `/` rather than by a scheme.
+ */
+export function findAbsolutePaths(text) {
+    const found = [];
+    const windows = /(?<![A-Za-z:])(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/\s]+[\\/])[^\s"'`,;)\]]*/g;
+    for (const match of text.matchAll(windows))
+        found.push(match[0]);
+    // portability-ok: the escaped class is regex syntax, not a path separator.
+    const posix = new RegExp(`(^|[^A-Za-z0-9_:/])(/(?:${POSIX_LOCAL_ROOTS.join('|')})/[^\\s"'\`,;)\\]]*)`, 'g'); // portability-ok
+    for (const match of text.matchAll(posix)) {
+        const value = match[2];
+        if (value !== undefined)
+            found.push(value);
+    }
+    return found;
+}
+/**
+ * Throw when a value that must be free of local paths is not.
+ *
+ * Used at the boundaries where a passthrough would be a leak rather than a
+ * convenience: a provider payload, an export, a rendered surface. The message
+ * names the field and the offending token so the failure is fixable, and it is
+ * a programming error rather than a runtime condition.
+ */
+export function assertNoLocalPath(where, value) {
+    const found = findAbsolutePaths(value);
+    if (found.length === 0)
+        return;
+    throw new Error(`${where} carries ${String(found.length)} absolute local path(s), starting with `
+        + `${String(found[0])}. Convert it with redactPath or relativeToRoot first.`);
+}
+//# sourceMappingURL=paths.js.map