attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/semantic/canonical.d.ts

@@ -1,6 +1,67 @@
 /**
  * Canonical JSON (RFC 8785 spirit: sorted keys, no whitespace).
  * Everything that gets signed or digested must go through this first.
+ *
+ * Only strict I-JSON values are accepted. `undefined`, non-finite numbers,
+ * functions, `Date`/`Map`/`Set`, sparse arrays, cycles and accessors are
+ * rejected with a `TypeError` naming the offending path, because
+ * `JSON.stringify` would otherwise silently rewrite them and a digest would no
+ * longer bind the value the caller passed.
+ *
+ * Two further cases are rejected because RFC 8785 rejects them, even though
+ * `JSON.stringify` happily rewrites both:
+ *
+ * - an unpaired surrogate (§3.2.2.2). `JSON.stringify` escapes it and
+ *   `TextEncoder` replaces it with U+FFFD, so two different strings can hash to
+ *   the same digest while a compliant verifier re-derives a different byte
+ *   string. A signature over such a value cannot be re-checked.
+ * - `-0` (appendix B). JCS serialises `-0` as `0`, so `-0` and `0` are one
+ *   digest. That is legal JCS but it is a silent rewrite of the caller's value,
+ *   which is exactly what this module refuses elsewhere. Callers that really
+ *   mean "treat -0 as 0" must say so with `negativeZero: "as-zero"`, which turns
+ *   an accidental collision into a declared policy.
+ *
+ * Unicode normalization is deliberately **not** applied: RFC 8785 §3.1 requires
+ * string data to be preserved as-is, and a digest that normalises would no
+ * longer be a digest of the bytes the caller supplied. Text-level normalisation
+ * belongs to a caller that records the policy, which is what `src/fingerprint`
+ * does for its `text` kind.
+ */
+/**
+ * How `-0` is treated when canonicalising.
+ *
+ * `"reject"` is the default and matches this module's contract that a digest
+ * must never cover a value `JSON.stringify` silently rewrote. `"as-zero"` is
+ * the explicit opt-in for a caller that has to interoperate with a plain JCS
+ * implementation, which maps `-0` to `0`.
+ */
+export type NegativeZeroPolicy = "reject" | "as-zero";
+/**
+ * Options for {@link canonicalJson} and {@link canonical} may only affect the
+ * documented policy, never the shape of the output.
+ */
+export interface CanonicalOptions {
+    negativeZero?: NegativeZeroPolicy;
+}
+/**
+ * Report the first value the strict policy cannot bind, or `undefined`.
+ *
+ * Structural problems are already covered by `jsonValueProblem`; this pass adds
+ * the two policy rules that depend on the caller's options. Keeping it as a
+ * pure function instead of a thrower lets `src/fingerprint` translate the same
+ * decision into its own error type rather than re-implementing RFC 8785.
+ */
+export declare const canonicalProblem: (value: unknown, options?: CanonicalOptions) => string | undefined;
+/**
+ * Canonical JSON with the documented policy options.
+ *
+ * One definition of "the bytes a digest covers" is the whole point: signing,
+ * pinning, ledger chaining and fingerprints all call this instead of each
+ * re-deriving the rules.
+ */
+export declare const canonicalJson: (value: unknown, options?: CanonicalOptions) => string;
+/**
+ * Canonical JSON with the default policy (`-0` rejected).
  */
 export declare const canonical: (value: unknown) => string;
 export declare const digestOf: (value: unknown) => string;

package/lib/semantic/canonical.js

@@ -1,22 +1,149 @@
+import { jsonValueProblem } from "./jsonValue.js";
 import { sha256Hex } from "./sha256.js";
+const SurrogateHighStart = 0xd800;
+const SurrogateHighEnd = 0xdbff;
+const SurrogateLowStart = 0xdc00;
+const SurrogateLowEnd = 0xdfff;
 /**
- * Canonical JSON (RFC 8785 spirit: sorted keys, no whitespace).
- * Everything that gets signed or digested must go through this first.
+ * Report the first unpaired surrogate in one string.
+ *
+ * JS strings are UTF-16 code units, so a string can hold half of a surrogate
+ * pair. JSON can represent it with an escape, but UTF-8 cannot encode it, and
+ * `TextEncoder` silently substitutes U+FFFD —which is why this is an error
+ * rather than a normalisation.
  */
-export const canonical = (value) => {
-    if (value === (void 0)) {
+const surrogateProblem = (text, at) => {
+    for (let index = 0; index < text.length; index += 1) {
+        const unit = text.charCodeAt(index);
+        if (unit >= SurrogateHighStart && unit <= SurrogateHighEnd) {
+            const next = index + 1 < text.length ? text.charCodeAt(index + 1) : 0;
+            if (next < SurrogateLowStart || next > SurrogateLowEnd) {
+                return `${at} contains an unpaired high surrogate at index ${index}`;
+            }
+            index += 1;
+            continue;
+        }
+        if (unit >= SurrogateLowStart && unit <= SurrogateLowEnd) {
+            return `${at} contains an unpaired low surrogate at index ${index}`;
+        }
+    }
+    return (void 0);
+};
+/**
+ * Report the first value the strict policy cannot bind, or `undefined`.
+ *
+ * Structural problems are already covered by `jsonValueProblem`; this pass adds
+ * the two policy rules that depend on the caller's options. Keeping it as a
+ * pure function instead of a thrower lets `src/fingerprint` translate the same
+ * decision into its own error type rather than re-implementing RFC 8785.
+ */
+export const canonicalProblem = (value, options = {}) => {
+    const negativeZero = options.negativeZero ?? "reject";
+    if (negativeZero !== "reject" && negativeZero !== "as-zero") {
+        throw new TypeError(`unknown negativeZero policy "${negativeZero}"; expected "reject" or "as-zero"`);
+    }
+    const walk = (item, at) => {
+        if (item === null) {
+            return (void 0);
+        }
+        const kind = typeof (item);
+        if (kind === "string") {
+            return surrogateProblem(item, at);
+        }
+        if (kind === "number") {
+            return negativeZero === "reject" && Object.is(item, -0) ? `${at} is -0; pass { negativeZero: "as-zero" } to accept it explicitly` : (void 0);
+        }
+        if (kind !== "object") {
+            return (void 0);
+        }
+        if (Array.isArray(item)) {
+            for (let index = 0; index < item.length; index += 1) {
+                const problem = walk(item[index], `${at}[${index}]`);
+                if (problem !== (void 0)) {
+                    return problem;
+                }
+            }
+            return (void 0);
+        }
+        const record = item;
+        const keys = Object.keys(record);
+        for (let index = 0; index < keys.length; index += 1) {
+            const key = keys[index];
+            const keyProblem = surrogateProblem(key, `${at} key`);
+            if (keyProblem !== (void 0)) {
+                return keyProblem;
+            }
+            const problem = walk(record[key], `${at}.${key}`);
+            if (problem !== (void 0)) {
+                return problem;
+            }
+        }
+        return (void 0);
+    };
+    return walk(value, "$");
+};
+/**
+ * Throw a `TypeError` naming the first reason the value cannot be canonicalised.
+ *
+ * Structural and policy problems share one error type because the caller's only
+ * useful response is the same: fix the value. The message names the path.
+ */
+const assertStrictCanonical = (value, options) => {
+    const structural = jsonValueProblem(value);
+    if (structural !== (void 0)) {
+        throw new TypeError(structural);
+    }
+    const policy = canonicalProblem(value, options);
+    if (policy !== (void 0)) {
+        throw new TypeError(policy);
+    }
+};
+/**
+ * Encode a value already proven canonicalisable by `assertStrictCanonical`.
+ */
+const encodeCanonical = (value) => {
+    if (value === null) {
         return "null";
     }
-    if (value === null || typeof (value) !== "object") {
+    const kind = typeof (value);
+    if (kind === "boolean") {
+        return value === true ? "true" : "false";
+    }
+    if (kind === "string" || kind === "number") {
         return JSON.stringify(value);
     }
     if (Array.isArray(value)) {
-        return `[${value.map(canonical).join(",")}]`;
+        const elements = [];
+        for (let index = 0; index < value.length; index += 1) {
+            elements.push(encodeCanonical(value[index]));
+        }
+        return `[${elements.join(",")}]`;
     }
     const record = value;
     const keys = Object.keys(record).sort();
-    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(record[k])}`).join(",")}}`;
+    const members = [];
+    for (let index = 0; index < keys.length; index += 1) {
+        const key = keys[index];
+        members.push(`${JSON.stringify(key)}:${encodeCanonical(record[key])}`);
+    }
+    return `{${members.join(",")}}`;
 };
+/**
+ * Canonical JSON with the documented policy options.
+ *
+ * One definition of "the bytes a digest covers" is the whole point: signing,
+ * pinning, ledger chaining and fingerprints all call this instead of each
+ * re-deriving the rules.
+ */
+export const canonicalJson = (value, options = {}) => {
+    assertStrictCanonical(value, options);
+    return encodeCanonical(value);
+};
+/**
+ * Canonical JSON with the default policy (`-0` rejected).
+ */
+export const canonical = (value) => canonicalJson(value);
 export const digestOf = (value) => {
-    return `sha256:${sha256Hex(canonical(value))}`;
+    const text = canonicalJson(value);
+    return `sha256:${sha256Hex(text)}`;
 };

package/lib/semantic/jsonValue.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Strict I-JSON value inspection.
+ *
+ * `canonical()`, the construction boundary and the persistence layers all need
+ * one definition of "this value can be represented as JSON". JavaScript values
+ * outside that domain (`undefined`, `NaN`, functions, `Date`, sparse arrays,
+ * cycles) must be rejected instead of being silently rewritten by
+ * `JSON.stringify`, because a digest that covers a rewritten value no longer
+ * binds what the caller passed.
+ */
+/**
+ * Describe why `value` is not I-JSON, or `undefined` when it is.
+ */
+export declare const jsonValueProblem: (value: unknown, at?: string) => string | undefined;
+/**
+ * True when the value is exactly representable as JSON without rewriting.
+ */
+export declare const isJsonValue: (value: unknown) => boolean;
+/**
+ * Throw a `TypeError` naming the first non-JSON path.
+ */
+export declare const assertJsonValue: (value: unknown, at?: string) => void;
+/**
+ * Deep-copy a JSON value. Asserts first, so the result cannot contain values
+ * that `JSON.stringify` would drop or rewrite.
+ */
+export declare const cloneJson: <T>(value: T) => T;
+/**
+ * Recursively freeze a JSON value. Assumes the value is acyclic (assert first).
+ */
+export declare const deepFreezeJson: <T>(value: T) => T;

package/lib/semantic/jsonValue.js

@@ -0,0 +1,122 @@
+/**
+ * Strict I-JSON value inspection.
+ *
+ * `canonical()`, the construction boundary and the persistence layers all need
+ * one definition of "this value can be represented as JSON". JavaScript values
+ * outside that domain (`undefined`, `NaN`, functions, `Date`, sparse arrays,
+ * cycles) must be rejected instead of being silently rewritten by
+ * `JSON.stringify`, because a digest that covers a rewritten value no longer
+ * binds what the caller passed.
+ */
+const constructorName = (value) => {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === null) {
+        return "null-prototype object";
+    }
+    const name = prototype.constructor?.name;
+    return typeof (name) === "string" && name.length > 0 ? name : "object";
+};
+const problemAt = (value, at, seen) => {
+    if (value === null) {
+        return (void 0);
+    }
+    const kind = typeof (value);
+    if (kind === "string" || kind === "boolean") {
+        return (void 0);
+    }
+    if (kind === "number") {
+        return Number.isFinite(value) ? (void 0) : `${at} is not a finite number`;
+    }
+    if (kind === "undefined") {
+        return `${at} is undefined`;
+    }
+    if (kind === "bigint" || kind === "function" || kind === "symbol") {
+        return `${at} is a ${kind}`;
+    }
+    const object = value;
+    if (seen.has(object)) {
+        return `${at} contains a cycle`;
+    }
+    seen.add(object);
+    try {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index += 1) {
+                if (!(index in value)) {
+                    return `${at}[${index}] is a hole`;
+                }
+                const problem = problemAt(value[index], `${at}[${index}]`, seen);
+                if (problem !== (void 0)) {
+                    return problem;
+                }
+            }
+            return (void 0);
+        }
+        const prototype = Object.getPrototypeOf(object);
+        if (prototype !== null && prototype !== Object.prototype) {
+            return `${at} is a ${constructorName(object)}, not a plain object`;
+        }
+        if (Object.getOwnPropertySymbols(object).length > 0) {
+            return `${at} has symbol keys`;
+        }
+        const keys = Object.keys(object);
+        for (let index = 0; index < keys.length; index += 1) {
+            const key = keys[index];
+            const descriptor = Object.getOwnPropertyDescriptor(object, key);
+            if (descriptor === (void 0) || !("value" in descriptor)) {
+                return `${at}.${key} is an accessor`;
+            }
+            const problem = problemAt(descriptor.value, `${at}.${key}`, seen);
+            if (problem !== (void 0)) {
+                return problem;
+            }
+        }
+        return (void 0);
+    }
+    finally {
+        seen.delete(object);
+    }
+};
+/**
+ * Describe why `value` is not I-JSON, or `undefined` when it is.
+ */
+export const jsonValueProblem = (value, at = "$") => problemAt(value, at, new Set());
+/**
+ * True when the value is exactly representable as JSON without rewriting.
+ */
+export const isJsonValue = (value) => jsonValueProblem(value) === (void 0);
+/**
+ * Throw a `TypeError` naming the first non-JSON path.
+ */
+export const assertJsonValue = (value, at = "$") => {
+    const problem = jsonValueProblem(value, at);
+    if (problem !== (void 0)) {
+        throw new TypeError(problem);
+    }
+};
+/**
+ * Deep-copy a JSON value. Asserts first, so the result cannot contain values
+ * that `JSON.stringify` would drop or rewrite.
+ */
+export const cloneJson = (value) => {
+    assertJsonValue(value);
+    return JSON.parse(JSON.stringify(value));
+};
+/**
+ * Recursively freeze a JSON value. Assumes the value is acyclic (assert first).
+ */
+export const deepFreezeJson = (value) => {
+    const freeze = (item) => {
+        if (item === null || typeof (item) !== "object" || Object.isFrozen(item)) {
+            return;
+        }
+        Object.freeze(item);
+        if (Array.isArray(item)) {
+            item.forEach(freeze);
+        }
+        else {
+            Object.keys(item).forEach((key) => freeze(item[key]));
+        }
+    };
+    freeze(value);
+    return value;
+};

package/lib/semantic/sha256.js

@@ -11,6 +11,9 @@ const K = new Uint32Array([
 ]);
 const rotr = (x, n) => ((x >>> n) | (x << (32 - n))) >>> 0;
 export const sha256Hex = (input) => {
+    if (typeof (input) !== "string") {
+        throw new TypeError(`sha256Hex expects a string, received ${typeof (input)}`);
+    }
     const bytes = new TextEncoder().encode(input);
     const length = bytes.length;
     const padded = new Uint8Array(((length + 9 + 63) >> 6) << 6);

package/lib/semantic/time.d.ts

@@ -0,0 +1,14 @@
+/**
+ * RFC 3339 `date-time` validation with calendar and range checks.
+ *
+ * `Date.parse()` is deliberately not used: it accepts date-only strings,
+ * offset-less local times and legacy numeric strings, and normalizes impossible
+ * dates such as `2026-02-30` into March. The construction boundary and the
+ * schema validator must agree on exactly one grammar.
+ */
+/**
+ * True for one RFC 3339 date-time with a mandatory offset.
+ *
+ * Leap seconds (`:60`) are accepted only at 23:59, as RFC 3339 permits.
+ */
+export declare const isDateTime: (value: unknown) => boolean;

package/lib/semantic/time.js

@@ -0,0 +1,56 @@
+/**
+ * RFC 3339 `date-time` validation with calendar and range checks.
+ *
+ * `Date.parse()` is deliberately not used: it accepts date-only strings,
+ * offset-less local times and legacy numeric strings, and normalizes impossible
+ * dates such as `2026-02-30` into March. The construction boundary and the
+ * schema validator must agree on exactly one grammar.
+ */
+const DateTimePattern = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:\d{2})$/;
+const daysInMonth = (year, month) => {
+    if (month === 2) {
+        const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+        return leap ? 29 : 28;
+    }
+    return [4, 6, 9, 11].includes(month) ? 30 : 31;
+};
+/**
+ * True for one RFC 3339 date-time with a mandatory offset.
+ *
+ * Leap seconds (`:60`) are accepted only at 23:59, as RFC 3339 permits.
+ */
+export const isDateTime = (value) => {
+    if (typeof (value) !== "string") {
+        return false;
+    }
+    const match = DateTimePattern.exec(value);
+    if (match === null) {
+        return false;
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    if (month < 1 || month > 12) {
+        return false;
+    }
+    if (day < 1 || day > daysInMonth(year, month)) {
+        return false;
+    }
+    if (hour > 23 || minute > 59 || second > 60) {
+        return false;
+    }
+    if (second === 60 && (hour !== 23 || minute !== 59)) {
+        return false;
+    }
+    if (match[8] !== "Z") {
+        const offsetHour = Number(match[8].slice(1, 3));
+        const offsetMinute = Number(match[8].slice(4, 6));
+        if (offsetHour > 23 || offsetMinute > 59) {
+            return false;
+        }
+    }
+    return true;
+};

package/lib/session/context.d.ts

@@ -0,0 +1,76 @@
+import type { SessionClock, SessionContextEntry, SessionContextSnapshot, SessionContextStore, SessionId, SessionJson, SessionRegistryLimits } from "./types.js";
+/**
+ * Construction options for {@link SessionContexts}. Limits are registry-wide so
+ * a caller cannot raise a per-session budget after construction.
+ */
+export interface SessionContextOptions {
+    readonly persistence?: SessionContextStore;
+    readonly clock?: SessionClock;
+    readonly limits?: Pick<SessionRegistryLimits, "maxContextEntries" | "maxContextBytes">;
+}
+export declare class SessionContexts {
+    private readonly persistence?;
+    private readonly clock;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private readonly sessions;
+    private readonly sizes;
+    private readonly loaded;
+    constructor(options?: SessionContextOptions);
+    /**
+     * Load one session's persisted entries exactly once. An absent store, a
+     * store that has no row for the session and an empty result all mean "this
+     * session has no entries yet". A persisted partition that exceeds the
+     * current limits is rejected with `context_quota` rather than silently
+     * bypassing the quota; `clear` and `remove` still work without loading.
+     */
+    ensure(sessionId: SessionId): void;
+    /**
+     * Return one entry, or `undefined`. A missing session is an empty context,
+     * not an error: the registry owns session existence.
+     */
+    get(sessionId: SessionId, namespace: string, key: string): SessionContextEntry | undefined;
+    /**
+     * Canonicalise, quota-check and store one value, returning the stored entry
+     * as a detached copy.
+     */
+    set(sessionId: SessionId, namespace: string, key: string, value: SessionJson, at: string): SessionContextEntry;
+    /**
+     * Remove one entry. Returns `false` when it never existed.
+     */
+    delete(sessionId: SessionId, namespace: string, key: string): boolean;
+    /**
+     * List entries for one session, optionally narrowed to one namespace.
+     * Ordering is deterministic (namespace, then key) so snapshots diff cleanly.
+     */
+    list(sessionId: SessionId, namespace?: string): SessionContextEntry[];
+    /**
+     * Immutable view of one session's whole context.
+     */
+    snapshot(sessionId: SessionId): SessionContextSnapshot;
+    /**
+     * Canonical UTF-8 bytes charged against one session.
+     */
+    bytes(sessionId: SessionId): number;
+    /**
+     * Drop every entry for one session. The empty state is persisted as a
+     * `replace`, which is atomic for an adapter that honours the port. This is
+     * deliberately an overwrite rather than a load-then-clear: a corrupt or
+     * over-quota persisted partition must still be removable by its host.
+     */
+    clear(sessionId: SessionId): void;
+    /**
+     * Copy the source context into the target session. Values are deep copies,
+     * so the two sessions share no mutable object. The target's previous
+     * context, if any, is replaced.
+     */
+    fork(from: SessionId, to: SessionId): void;
+    /**
+     * Remove every entry for one session and its persisted partition.
+     */
+    remove(sessionId: SessionId): void;
+    private partitionOf;
+    private countOf;
+    private storedEntryIsValid;
+    private persistPut;
+}