project-tiny-context-harness 0.8.11 → 0.8.13

package/dist/lib/long-task-hook-install.js

@@ -1,8 +1,21 @@
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { pathExists } from "./fs.js";
 const MANAGED_STATUS = "Tiny Context long-task live authority gate";
+const PRE_TOOL_USE_MATCHER = "^(spawn_agent|Agent)$";
+const LONG_TASK_IMPLEMENTATION_AGENT_MATCHER = "^long_task_implementation$";
+const MANAGED_HOOK_EVENTS = [
+    "PreToolUse",
+    "SessionStart",
+    "PostCompact",
+    "Stop",
+    "SubagentStart",
+];
+const MANAGED_MATCHERS = new Set([
+    PRE_TOOL_USE_MATCHER,
+    LONG_TASK_IMPLEMENTATION_AGENT_MATCHER,
+]);
 const LEGACY_MANAGED_STATUSES = new Set([
     "Tiny Context long-task live authority gate",
     "Tiny Context long-task authority gate",
@@ -17,94 +30,85 @@ const LEGACY_REPO_LOCAL_COMMANDS = new Set([
     "node .codex\\hooks\\long-task-hook.mjs",
     'node ".codex\\hooks\\long-task-hook.mjs"',
 ]);
-export async function installLongTaskHooks(projectRoot, report) {
+export const LONG_TASK_HOOK_TRUST_REVIEW_NOTICE = "Codex Hook review required: open /hooks and trust the current Tiny Context project Hook before relying on PreToolUse, SubagentStart, SessionStart or Stop behavior. Tiny Context cannot observe or persist Codex Hook trust.";
+const DEFAULT_FILE_OPERATIONS = {
+    lstat: (target) => fs.lstat(target),
+    readFile: (target, encoding) => fs.readFile(target, encoding),
+    mkdir: (target, options) => fs.mkdir(target, options),
+    writeFile: (target, content, options) => fs.writeFile(target, content, options),
+    rename: (source, destination) => fs.rename(source, destination),
+    rm: (target, options) => fs.rm(target, options),
+    randomId: () => randomUUID(),
+};
+export async function installLongTaskHooks(projectRoot, report, fileOperations = {}) {
+    const operations = operationsWith(fileOperations);
     const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
     const entry = path.join(packageRoot, "dist", "long-task-hook.js");
-    if (!(await pathExists(entry))) {
+    const entryStatus = await lstatOrNull(entry, operations);
+    if (!entryStatus || entryStatus.isSymbolicLink() || !entryStatus.isFile()) {
         report.blocked.push("package-owned dist/long-task-hook.js is missing");
         return;
     }
-    const legacyScript = path.join(projectRoot, ".codex", "hooks", "long-task-hook.mjs");
-    if (await pathExists(legacyScript)) {
-        await rm(legacyScript, { force: true });
-        report.changed.push(".codex/hooks/long-task-hook.mjs");
-    }
-    const command = packageOwnedCommand(entry);
     const config = path.join(projectRoot, ".codex", "hooks.json");
-    let root = {};
-    if (await pathExists(config)) {
-        try {
-            root = JSON.parse(await readFile(config, "utf8"));
+    const legacyScript = path.join(projectRoot, ".codex", "hooks", "long-task-hook.mjs");
+    try {
+        const legacy = await inspectLegacyScript(projectRoot, operations);
+        const loaded = await readHookConfig(projectRoot, true, operations);
+        const command = packageOwnedCommand(entry);
+        const packageHooksWereCurrent = packageHooksAreCurrent(loaded.root, command);
+        const next = mergeManagedHooks(loaded.root, command);
+        const content = `${JSON.stringify(next, null, 2)}\n`;
+        if (loaded.snapshot.kind === "regular" &&
+            loaded.snapshot.content === content) {
+            report.skipped.push(".codex/hooks.json");
         }
-        catch {
-            report.blocked.push(".codex/hooks.json: invalid JSON");
-            return;
+        else {
+            await publishHookConfig(config, loaded.snapshot, content, operations);
+            report.changed.push(".codex/hooks.json");
+            if (!packageHooksWereCurrent)
+                addNotice(report);
         }
+        await removeLegacyScriptIfPresent(projectRoot, legacyScript, legacy, report, operations);
     }
-    const hooks = object(root.hooks);
-    root.hooks = hooks;
-    for (const event of ["SessionStart", "PostCompact", "Stop"]) {
-        const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
-        const cleaned = removeManagedHookEntries(groups, command);
-        cleaned.groups.push({
-            hooks: [
-                {
-                    type: "command",
-                    command,
-                    commandWindows: command,
-                    timeout: event === "Stop" ? 3600 : 10,
-                    statusMessage: MANAGED_STATUS,
-                },
-            ],
-        });
-        hooks[event] = cleaned.groups;
+    catch (error) {
+        report.blocked.push(`.codex/hooks.json: ${message(error)}`);
     }
-    if (await writeIfChanged(config, `${JSON.stringify(root, null, 2)}\n`))
-        report.changed.push(".codex/hooks.json");
-    else
-        report.skipped.push(".codex/hooks.json");
 }
-export async function uninstallLongTaskHooks(projectRoot, report) {
+export async function uninstallLongTaskHooks(projectRoot, report, fileOperations = {}) {
+    const operations = operationsWith(fileOperations);
     const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
     const command = packageOwnedCommand(path.join(packageRoot, "dist", "long-task-hook.js"));
-    const legacyScript = path.join(projectRoot, ".codex", "hooks", "long-task-hook.mjs");
-    if (await pathExists(legacyScript)) {
-        await rm(legacyScript, { force: true });
-        report.changed.push(".codex/hooks/long-task-hook.mjs");
-    }
     const config = path.join(projectRoot, ".codex", "hooks.json");
-    if (!(await pathExists(config)))
-        return;
-    let root;
+    const legacyScript = path.join(projectRoot, ".codex", "hooks", "long-task-hook.mjs");
     try {
-        root = JSON.parse(await readFile(config, "utf8"));
-    }
-    catch {
-        report.skipped.push(".codex/hooks.json: invalid JSON");
-        return;
+        const legacy = await inspectLegacyScript(projectRoot, operations);
+        const loaded = await readHookConfig(projectRoot, false, operations);
+        let removed = 0;
+        const hooks = hookMap(loaded.root);
+        for (const event of MANAGED_HOOK_EVENTS) {
+            if (!Array.isArray(hooks[event]))
+                continue;
+            const cleaned = removeManagedHookEntries(hooks[event], command);
+            removed += cleaned.removed;
+            if (cleaned.groups.length)
+                hooks[event] = cleaned.groups;
+            else
+                delete hooks[event];
+        }
+        if (removed > 0 && loaded.snapshot.kind === "regular") {
+            loaded.root.hooks = hooks;
+            if (Object.keys(hooks).length === 0 &&
+                Object.keys(loaded.root).length === 1)
+                await removeHookConfig(config, loaded.snapshot, operations);
+            else
+                await publishHookConfig(config, loaded.snapshot, `${JSON.stringify(loaded.root, null, 2)}\n`, operations);
+            report.changed.push(".codex/hooks.json");
+        }
+        await removeLegacyScriptIfPresent(projectRoot, legacyScript, legacy, report, operations);
     }
-    const hooks = object(root.hooks);
-    let changed = false;
-    for (const event of ["SessionStart", "PostCompact", "Stop"]) {
-        if (!Array.isArray(hooks[event]))
-            continue;
-        const cleaned = removeManagedHookEntries(hooks[event], command);
-        if (cleaned.removed === 0)
-            continue;
-        changed = true;
-        if (cleaned.groups.length)
-            hooks[event] = cleaned.groups;
-        else
-            delete hooks[event];
+    catch (error) {
+        report.blocked.push(`.codex/hooks.json: ${message(error)}`);
     }
-    if (!changed)
-        return;
-    root.hooks = hooks;
-    if (Object.keys(hooks).length === 0 && Object.keys(root).length === 1)
-        await rm(config, { force: true });
-    else
-        await writeIfChanged(config, `${JSON.stringify(root, null, 2)}\n`);
-    report.changed.push(".codex/hooks.json");
 }
 export function packageOwnedCommand(entry) {
     return `node "${path.resolve(entry).replace(/"/gu, '\\"')}"`;
@@ -129,8 +133,13 @@ export function removeManagedHookEntries(groups, currentPackageCommand = "") {
             retained.push({ ...groupValue, hooks });
             continue;
         }
-        if (Object.keys(groupValue).some((key) => key !== "hooks"))
-            retained.push({ ...groupValue, hooks });
+        const keys = Object.keys(groupValue);
+        if (keys.every((key) => key === "hooks"))
+            continue;
+        if (MANAGED_MATCHERS.has(String(groupValue.matcher ?? "")) &&
+            keys.every((key) => key === "matcher" || key === "hooks"))
+            continue;
+        retained.push({ ...groupValue, hooks });
     }
     return { groups: retained, removed };
 }
@@ -141,8 +150,7 @@ export function isManagedHookEntry(entry, currentPackageCommand = "") {
     const commands = [row.command, row.commandWindows]
         .filter((value) => typeof value === "string")
         .map((value) => value.trim());
-    const repoLocal = commands.some((command) => LEGACY_REPO_LOCAL_COMMANDS.has(command));
-    if (repoLocal)
+    if (commands.some((command) => LEGACY_REPO_LOCAL_COMMANDS.has(command)))
         return true;
     const status = String(row.statusMessage ?? "");
     if (!LEGACY_MANAGED_STATUSES.has(status))
@@ -150,6 +158,201 @@ export function isManagedHookEntry(entry, currentPackageCommand = "") {
     return commands.some((command) => (Boolean(currentPackageCommand) && command === currentPackageCommand) ||
         isHistoricalPackageOwnedCommand(command));
 }
+function mergeManagedHooks(root, command) {
+    const hooks = hookMap(root);
+    root.hooks = hooks;
+    for (const event of MANAGED_HOOK_EVENTS) {
+        const current = hooks[event];
+        if (current !== undefined && !Array.isArray(current))
+            throw new Error(`hook_event_not_array:${event}`);
+        const cleaned = removeManagedHookEntries(current ?? [], command);
+        cleaned.groups.push(managedHookGroup(event, command));
+        hooks[event] = cleaned.groups;
+    }
+    return root;
+}
+function managedHookGroup(event, command) {
+    return {
+        ...(event === "PreToolUse" ? { matcher: PRE_TOOL_USE_MATCHER } : {}),
+        ...(event === "SubagentStart"
+            ? { matcher: LONG_TASK_IMPLEMENTATION_AGENT_MATCHER }
+            : {}),
+        hooks: [
+            {
+                type: "command",
+                command,
+                commandWindows: command,
+                timeout: event === "Stop" ? 3600 : 10,
+                statusMessage: MANAGED_STATUS,
+            },
+        ],
+    };
+}
+function packageHooksAreCurrent(root, command) {
+    let hooks;
+    try {
+        hooks = hookMap(root);
+    }
+    catch {
+        return false;
+    }
+    return MANAGED_HOOK_EVENTS.every((event) => {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            return false;
+        const matches = [];
+        for (const groupValue of groups) {
+            if (!isObject(groupValue) || !Array.isArray(groupValue.hooks))
+                continue;
+            for (const entryValue of groupValue.hooks) {
+                if (!isManagedHookEntry(entryValue, command))
+                    continue;
+                matches.push({ group: groupValue, entry: object(entryValue) });
+            }
+        }
+        if (matches.length !== 1)
+            return false;
+        const [{ group, entry }] = matches;
+        const expectedMatcher = event === "PreToolUse"
+            ? PRE_TOOL_USE_MATCHER
+            : event === "SubagentStart"
+                ? LONG_TASK_IMPLEMENTATION_AGENT_MATCHER
+                : undefined;
+        return (entry.type === "command" &&
+            entry.command === command &&
+            entry.commandWindows === command &&
+            entry.timeout === (event === "Stop" ? 3600 : 10) &&
+            entry.statusMessage === MANAGED_STATUS &&
+            (expectedMatcher === undefined
+                ? !Object.hasOwn(group, "matcher")
+                : group.matcher === expectedMatcher));
+    });
+}
+async function readHookConfig(projectRoot, createDirectory, operations) {
+    const directory = await inspectCodexDirectory(projectRoot, createDirectory, operations);
+    if (directory === "absent")
+        return { root: {}, snapshot: { kind: "absent" } };
+    const config = path.join(projectRoot, ".codex", "hooks.json");
+    const status = await lstatOrNull(config, operations);
+    if (!status)
+        return { root: {}, snapshot: { kind: "absent" } };
+    if (status.isSymbolicLink())
+        throw new Error("destination_symlink_or_junction");
+    if (!status.isFile())
+        throw new Error("destination_not_regular_file");
+    const content = await operations.readFile(config, "utf8");
+    let decoded;
+    try {
+        decoded = JSON.parse(content);
+    }
+    catch {
+        throw new Error("invalid JSON");
+    }
+    if (!isObject(decoded))
+        throw new Error("root_not_object");
+    hookMap(decoded);
+    return { root: decoded, snapshot: { kind: "regular", content } };
+}
+function hookMap(root) {
+    if (root.hooks === undefined)
+        return {};
+    if (!isObject(root.hooks))
+        throw new Error("hooks_not_object");
+    return root.hooks;
+}
+async function inspectCodexDirectory(projectRoot, create, operations) {
+    const directory = path.join(projectRoot, ".codex");
+    let status = await lstatOrNull(directory, operations);
+    if (!status && create) {
+        await operations.mkdir(directory, { recursive: true });
+        status = await lstatOrNull(directory, operations);
+    }
+    if (!status)
+        return "absent";
+    if (status.isSymbolicLink())
+        throw new Error("parent_symlink_or_junction:.codex");
+    if (!status.isDirectory())
+        throw new Error("parent_not_directory:.codex");
+    return "regular";
+}
+async function inspectLegacyScript(projectRoot, operations) {
+    if ((await inspectCodexDirectory(projectRoot, false, operations)) === "absent")
+        return { kind: "absent" };
+    const parent = path.join(projectRoot, ".codex", "hooks");
+    const parentStatus = await lstatOrNull(parent, operations);
+    if (!parentStatus)
+        return { kind: "absent" };
+    if (parentStatus.isSymbolicLink())
+        throw new Error("legacy_parent_symlink_or_junction");
+    if (!parentStatus.isDirectory())
+        throw new Error("legacy_parent_not_directory");
+    const target = path.join(parent, "long-task-hook.mjs");
+    const targetStatus = await lstatOrNull(target, operations);
+    if (!targetStatus)
+        return { kind: "absent" };
+    if (targetStatus.isSymbolicLink())
+        throw new Error("legacy_hook_symlink_or_junction");
+    if (!targetStatus.isFile())
+        throw new Error("legacy_hook_not_regular_file");
+    return { kind: "regular" };
+}
+async function removeLegacyScriptIfPresent(projectRoot, target, initial, report, operations) {
+    if (initial.kind === "absent")
+        return;
+    const current = await inspectLegacyScript(projectRoot, operations);
+    if (current.kind !== "regular")
+        throw new Error("legacy_hook_changed_before_delete");
+    await operations.rm(target, { force: true });
+    report.changed.push(".codex/hooks/long-task-hook.mjs");
+}
+async function publishHookConfig(target, initial, content, operations) {
+    const temp = `${target}.tmp-${process.pid}-${operations.randomId()}`;
+    let renamed = false;
+    try {
+        await operations.writeFile(temp, content, { flag: "wx" });
+        await assertTargetUnchanged(target, initial, operations);
+        await operations.rename(temp, target);
+        renamed = true;
+    }
+    finally {
+        if (!renamed)
+            await operations.rm(temp, { force: true }).catch(() => { });
+    }
+}
+async function removeHookConfig(target, initial, operations) {
+    await assertTargetUnchanged(target, initial, operations);
+    await operations.rm(target, { force: true });
+}
+async function assertTargetUnchanged(target, initial, operations) {
+    const projectRoot = path.dirname(path.dirname(target));
+    await inspectCodexDirectory(projectRoot, false, operations);
+    const status = await lstatOrNull(target, operations);
+    if (initial.kind === "absent") {
+        if (status)
+            throw new Error("concurrent change: destination appeared");
+        return;
+    }
+    if (!status || status.isSymbolicLink() || !status.isFile())
+        throw new Error("concurrent change: destination type changed");
+    if ((await operations.readFile(target, "utf8")) !== initial.content)
+        throw new Error("concurrent change: destination content changed");
+}
+function addNotice(report) {
+    (report.notices ??= []).push(LONG_TASK_HOOK_TRUST_REVIEW_NOTICE);
+}
+function operationsWith(overrides) {
+    return { ...DEFAULT_FILE_OPERATIONS, ...overrides };
+}
+async function lstatOrNull(target, operations) {
+    try {
+        return await operations.lstat(target);
+    }
+    catch (error) {
+        if (code(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
 function isHistoricalPackageOwnedCommand(command) {
     const match = /^node "([^"\r\n]+)"$/u.exec(command);
     if (!match)
@@ -163,22 +366,16 @@ function isHistoricalPackageOwnedCommand(command) {
     return (/\/node_modules\/project-tiny-context-harness\/dist\/long-task-hook\.js$/u.test(normalized) || /\/packages\/ty-context\/dist\/long-task-hook\.js$/u.test(normalized));
 }
 function object(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : {};
+    return isObject(value) ? value : {};
 }
 function isObject(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
-async function writeIfChanged(file, content) {
-    try {
-        if ((await readFile(file, "utf8")) === content)
-            return false;
-    }
-    catch { }
-    await mkdir(path.dirname(file), { recursive: true });
-    const temp = `${file}.tmp-${process.pid}-${Date.now()}`;
-    await writeFile(temp, content, { flag: "wx" });
-    await rename(temp, file);
-    return true;
+function code(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : "";
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
 }

package/dist/lib/long-task-json-pointer-observation.d.ts

@@ -0,0 +1,59 @@
+export declare const JSON_POINTER_EXACT_CAPABILITY = "json-pointer-exact-v1";
+export declare const JSON_POINTER_EXACT_ORACLE_IDENTITY = "ty-context-json-pointer-exact";
+export declare const JSON_POINTER_EXACT_ORACLE_VERSION = "1.0.0";
+export declare const JSON_POINTER_EXACT_METHODS: readonly ["exact_value", "content", "component_state"];
+export declare const JSON_POINTER_EXACT_LIMITS: Readonly<{
+    max_file_bytes: 1048576;
+    max_depth: 64;
+    max_pointer_bytes: 4096;
+    max_pointer_segments: 128;
+    max_canonical_value_bytes: 262144;
+    max_artifacts_per_check: 256;
+    max_total_artifact_bytes: 16777216;
+}>;
+export declare const JSON_POINTER_EXACT_SPEC_SHA256: string;
+export interface JsonPointerExactBudget {
+    readonly seen_artifact_paths: Set<string>;
+    total_artifact_bytes: number;
+}
+export interface JsonPointerExactLocator {
+    kind: string;
+    value: string;
+}
+export interface JsonPointerExactObservation {
+    capability: typeof JSON_POINTER_EXACT_CAPABILITY;
+    artifact_path: string;
+    artifact_sha256: string;
+    locator: {
+        kind: "json_pointer";
+        value: string;
+    };
+    value_sha256: string;
+    canonical_value_bytes: number;
+    sensitivity: "plain";
+}
+export declare function createJsonPointerExactBudget(): JsonPointerExactBudget;
+export declare function isJsonPointerExactOracle(oracle: {
+    trust?: string;
+    identity?: string;
+    version?: string;
+    sha256?: string | null;
+}): boolean;
+export declare function extractJsonPointerExactObservationFromBytes(input: {
+    artifact_path: string;
+    bytes: Uint8Array;
+    locator: JsonPointerExactLocator;
+    sensitivity: string;
+    budget?: JsonPointerExactBudget;
+}): JsonPointerExactObservation;
+export declare function validateJsonPointerExactLocator(locator: JsonPointerExactLocator): {
+    kind: "json_pointer";
+    value: string;
+};
+export declare function normalizeObservationArtifactPath(value: string): string;
+export declare function invalidObservation(code: string): Error;
+export declare function observationErrorMessage(error: unknown): string;
+export declare function resolveJsonPointer(root: unknown, pointer: string): unknown;
+export declare function parseJsonWithoutDuplicateKeys(content: string): unknown;
+export declare function decodeUtf8Json(bytes: Uint8Array): string;
+export declare function assertJsonTree(value: unknown, depth: number): void;

package/dist/lib/long-task-json-pointer-observation.js

@@ -0,0 +1,184 @@
+import path from "node:path";
+import { canonicalValueJson, parseStrictYaml, sha256Hex, } from "./strict-codec.js";
+export const JSON_POINTER_EXACT_CAPABILITY = "json-pointer-exact-v1";
+export const JSON_POINTER_EXACT_ORACLE_IDENTITY = "ty-context-json-pointer-exact";
+export const JSON_POINTER_EXACT_ORACLE_VERSION = "1.0.0";
+export const JSON_POINTER_EXACT_METHODS = Object.freeze([
+    "exact_value",
+    "content",
+    "component_state",
+]);
+export const JSON_POINTER_EXACT_LIMITS = Object.freeze({
+    max_file_bytes: 1_048_576,
+    max_depth: 64,
+    max_pointer_bytes: 4_096,
+    max_pointer_segments: 128,
+    max_canonical_value_bytes: 262_144,
+    max_artifacts_per_check: 256,
+    max_total_artifact_bytes: 16_777_216,
+});
+export const JSON_POINTER_EXACT_SPEC_SHA256 = sha256Hex(canonicalValueJson({
+    capability: JSON_POINTER_EXACT_CAPABILITY,
+    oracle_identity: JSON_POINTER_EXACT_ORACLE_IDENTITY,
+    oracle_version: JSON_POINTER_EXACT_ORACLE_VERSION,
+    media_type: "application/json",
+    encoding: "utf-8",
+    locator: "rfc6901-json-pointer",
+    canonicalization: "canonical-json-v1",
+    methods: JSON_POINTER_EXACT_METHODS,
+    comparator: "exact_value",
+    mode: "exact",
+    sensitivity: "plain",
+    limits: JSON_POINTER_EXACT_LIMITS,
+}));
+export function createJsonPointerExactBudget() {
+    return { seen_artifact_paths: new Set(), total_artifact_bytes: 0 };
+}
+export function isJsonPointerExactOracle(oracle) {
+    return (oracle.trust === "named_external_tcb" &&
+        oracle.identity === JSON_POINTER_EXACT_ORACLE_IDENTITY &&
+        oracle.version === JSON_POINTER_EXACT_ORACLE_VERSION &&
+        oracle.sha256 === null);
+}
+export function extractJsonPointerExactObservationFromBytes(input) {
+    const artifactPath = normalizeObservationArtifactPath(input.artifact_path);
+    if (input.sensitivity !== "plain")
+        throw invalidObservation("observation_protected_requires_frozen_adapter");
+    if (input.bytes.byteLength > JSON_POINTER_EXACT_LIMITS.max_file_bytes)
+        throw invalidObservation("observation_artifact_size_limit");
+    accountForArtifact(input.budget, artifactPath, input.bytes.byteLength);
+    const locator = validateJsonPointerExactLocator(input.locator);
+    const parsed = parseJsonWithoutDuplicateKeys(decodeUtf8Json(input.bytes));
+    assertJsonTree(parsed, 0);
+    const canonical = canonicalValueJson(resolveJsonPointer(parsed, locator.value));
+    const canonicalBytes = Buffer.byteLength(canonical, "utf8");
+    if (canonicalBytes > JSON_POINTER_EXACT_LIMITS.max_canonical_value_bytes)
+        throw invalidObservation("observation_canonical_value_size_limit");
+    return {
+        capability: JSON_POINTER_EXACT_CAPABILITY,
+        artifact_path: artifactPath,
+        artifact_sha256: sha256Hex(input.bytes),
+        locator,
+        value_sha256: sha256Hex(canonical),
+        canonical_value_bytes: canonicalBytes,
+        sensitivity: "plain",
+    };
+}
+export function validateJsonPointerExactLocator(locator) {
+    if (locator.kind !== "json_pointer" ||
+        typeof locator.value !== "string" ||
+        locator.value.startsWith("#") ||
+        (locator.value !== "" && !locator.value.startsWith("/")) ||
+        Buffer.byteLength(locator.value, "utf8") >
+            JSON_POINTER_EXACT_LIMITS.max_pointer_bytes)
+        throw invalidObservation("observation_locator_not_admitted");
+    const encoded = locator.value === "" ? [] : locator.value.slice(1).split("/");
+    if (encoded.length > JSON_POINTER_EXACT_LIMITS.max_pointer_segments)
+        throw invalidObservation("observation_locator_segment_limit");
+    for (const token of encoded)
+        if (/~(?:[^01]|$)/u.test(token))
+            throw invalidObservation("observation_locator_not_admitted");
+    return { kind: "json_pointer", value: locator.value };
+}
+export function normalizeObservationArtifactPath(value) {
+    if (!value ||
+        value.includes("\\") ||
+        value.includes("\0") ||
+        path.posix.isAbsolute(value) ||
+        /^[a-z]:/iu.test(value))
+        throw invalidObservation("observation_artifact_path_escape");
+    const segments = value.split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === ".."))
+        throw invalidObservation("observation_artifact_path_escape");
+    return segments.join("/");
+}
+export function invalidObservation(code) {
+    return new Error(code);
+}
+export function observationErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function resolveJsonPointer(root, pointer) {
+    let current = root;
+    if (pointer === "")
+        return current;
+    for (const encoded of pointer.slice(1).split("/")) {
+        const token = encoded.replace(/~1/gu, "/").replace(/~0/gu, "~");
+        if (Array.isArray(current)) {
+            if (!/^(?:0|[1-9]\d*)$/u.test(token))
+                throw invalidObservation("observation_locator_array_index_invalid");
+            const index = Number(token);
+            if (!Number.isSafeInteger(index) || index >= current.length)
+                throw invalidObservation("observation_locator_not_found");
+            current = current[index];
+            continue;
+        }
+        if (!current ||
+            typeof current !== "object" ||
+            !Object.hasOwn(current, token))
+            throw invalidObservation("observation_locator_not_found");
+        current = current[token];
+    }
+    return current;
+}
+export function parseJsonWithoutDuplicateKeys(content) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw invalidObservation("observation_json_invalid");
+    }
+    try {
+        const strict = parseStrictYaml(content);
+        if (canonicalValueJson(strict) !== canonicalValueJson(parsed))
+            throw invalidObservation("observation_json_canonicalization_mismatch");
+    }
+    catch (error) {
+        if (observationErrorMessage(error).includes("unique"))
+            throw invalidObservation("observation_json_duplicate_key");
+        if (observationErrorMessage(error).startsWith("observation_"))
+            throw error;
+        throw invalidObservation("observation_json_invalid");
+    }
+    return parsed;
+}
+export function decodeUtf8Json(bytes) {
+    if (bytes.byteLength >= 3 &&
+        bytes[0] === 0xef &&
+        bytes[1] === 0xbb &&
+        bytes[2] === 0xbf)
+        throw invalidObservation("observation_json_utf8_invalid");
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw invalidObservation("observation_json_utf8_invalid");
+    }
+}
+export function assertJsonTree(value, depth) {
+    if (depth > JSON_POINTER_EXACT_LIMITS.max_depth)
+        throw invalidObservation("observation_json_depth_limit");
+    if (typeof value === "number" && !Number.isFinite(value))
+        throw invalidObservation("observation_json_number_invalid");
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            assertJsonTree(entry, depth + 1);
+        return;
+    }
+    if (value && typeof value === "object")
+        for (const entry of Object.values(value))
+            assertJsonTree(entry, depth + 1);
+}
+function accountForArtifact(budget, artifactPath, bytes) {
+    if (!budget || budget.seen_artifact_paths.has(artifactPath))
+        return;
+    if (budget.seen_artifact_paths.size >=
+        JSON_POINTER_EXACT_LIMITS.max_artifacts_per_check)
+        throw invalidObservation("observation_artifact_count_limit");
+    if (budget.total_artifact_bytes + bytes >
+        JSON_POINTER_EXACT_LIMITS.max_total_artifact_bytes)
+        throw invalidObservation("observation_artifact_total_size_limit");
+    budget.seen_artifact_paths.add(artifactPath);
+    budget.total_artifact_bytes += bytes;
+}