agent-protocols 0.9.0 → 0.10.1

package/dist/knowledge.js

@@ -0,0 +1,796 @@
+/**
+ * Agent Knowledge 1.0. Signatures establish attribution, never scientific truth.
+ * Knowledge events are immutable, portable objects: acceptance never consults a
+ * live-write nonce cache, and nothing is fetched or executed implicitly.
+ */
+import { sha3_256 } from "@noble/hashes/sha3.js";
+import canonicalize from "canonicalize";
+import { Validator } from "@cfworker/json-schema";
+import { base64UrlDecodeCanonical, base64UrlEncode } from "./encoding.js";
+import { protocolError } from "./errors.js";
+import { createEvent, parseStrictJson, validateOrigin, verifyEnvelope, } from "./identity.js";
+import { KNOWLEDGE_SCHEMA } from "./knowledge-schema.js";
+export { KNOWLEDGE_SCHEMA } from "./knowledge-schema.js";
+export const KNOWLEDGE_PROTOCOL = "agent-knowledge/1.0";
+export const KNOWLEDGE_ERROR_CODES = [
+    "missing_dependency",
+    "invalid_target",
+    "invalid_cursor",
+    "query_too_broad",
+    "query_unavailable",
+    "unsupported_search_mode",
+];
+export const KNOWLEDGE_EVENT_TYPES = [
+    "knowledge.publish",
+    "knowledge.assess",
+    "knowledge.retract",
+];
+export const KNOWLEDGE_KINDS = [
+    "question",
+    "hypothesis",
+    "definition",
+    "observation",
+    "inference",
+    "procedure",
+    "resource",
+    "negative_result",
+    "synthesis",
+    "collection",
+];
+export const KNOWLEDGE_RELATIONS = [
+    "derived_from",
+    "addresses",
+    "tests",
+    "extends",
+    "supports",
+    "contradicts",
+    "supersedes",
+    "contains",
+];
+export const KNOWLEDGE_VERDICTS = [
+    "supports",
+    "challenges",
+    "reproduced",
+    "not_reproduced",
+    "applied",
+    "inconclusive",
+];
+export const KNOWLEDGE_SEARCH_MODES = [
+    "lexical",
+    "semantic",
+    "hybrid",
+];
+/** Default allowance for `created_at` ahead of the receiver clock. */
+export const DEFAULT_FUTURE_SKEW_MS = 300_000;
+export const DEFAULT_MAX_ENVELOPE_BYTES = 262_144;
+/** Relationships that may point at an assessment as well as a publication. */
+const ASSESSMENT_RELATIONS = [
+    "derived_from",
+    "supports",
+    "contradicts",
+];
+export function knowledgePublishEvent(actor, createdAt, nonce, payload) {
+    return createEvent(KNOWLEDGE_PROTOCOL, "knowledge.publish", actor, createdAt, nonce, payload);
+}
+export function knowledgeAssessEvent(actor, createdAt, nonce, payload) {
+    return createEvent(KNOWLEDGE_PROTOCOL, "knowledge.assess", actor, createdAt, nonce, payload);
+}
+export function knowledgeRetractEvent(actor, createdAt, nonce, payload) {
+    return createEvent(KNOWLEDGE_PROTOCOL, "knowledge.retract", actor, createdAt, nonce, payload);
+}
+const validators = new Map();
+/** Structure only. Signatures, canonical encodings and references are separate checks. */
+export function validateKnowledgeSchema(value, definition = "signedEnvelope", code = "invalid_event") {
+    let validator = validators.get(definition);
+    if (!validator) {
+        if (!Object.hasOwn(KNOWLEDGE_SCHEMA.$defs, definition))
+            throw protocolError(code, "unknown schema definition");
+        validator = new Validator({
+            $ref: `#/$defs/${definition}`,
+            $defs: KNOWLEDGE_SCHEMA.$defs,
+        }, "2020-12", true);
+        validators.set(definition, validator);
+    }
+    jsonCheck(value, code);
+    if (!validator.validate(value).valid)
+        throw protocolError(code, `invalid ${definition} structure`);
+}
+function jsonCheck(value, code = "invalid_event") {
+    try {
+        const visited = new Set();
+        const inspect = (input, depth) => {
+            if (depth > 256)
+                throw new Error("nesting limit");
+            if (input === null ||
+                typeof input === "boolean" ||
+                typeof input === "string")
+                return;
+            if (typeof input === "number") {
+                if (!Number.isFinite(input) ||
+                    (Number.isInteger(input) && !Number.isSafeInteger(input)))
+                    throw new Error("invalid number");
+                return;
+            }
+            if (typeof input !== "object" || visited.has(input))
+                throw new Error("non-JSON value");
+            const prototype = Object.getPrototypeOf(input);
+            if (!Array.isArray(input) &&
+                prototype !== null &&
+                prototype !== Object.prototype)
+                throw new Error("non-JSON object");
+            visited.add(input);
+            if (Array.isArray(input))
+                for (let i = 0; i < input.length; i++)
+                    inspect(input[i], depth + 1);
+            else
+                for (const key of Reflect.ownKeys(input)) {
+                    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+                    if (typeof key !== "string" ||
+                        !descriptor.enumerable ||
+                        !("value" in descriptor))
+                        throw new Error("non-JSON member");
+                    inspect(descriptor.value, depth + 1);
+                }
+            visited.delete(input);
+        };
+        inspect(value, 0);
+        const text = JSON.stringify(value);
+        if (text === undefined)
+            throw new Error();
+        parseStrictJson(text);
+    }
+    catch {
+        throw protocolError(code, "value violates strict I-JSON");
+    }
+}
+export function validateKnowledgeId(value, code = "invalid_event") {
+    if (typeof value !== "string" ||
+        !/^[A-Za-z0-9_-]{43}$/.test(value) ||
+        base64UrlDecodeCanonical(value) === undefined)
+        throw protocolError(code, "ID must canonically encode 32 bytes");
+}
+function https(value, code = "invalid_event") {
+    try {
+        const u = new URL(value);
+        if (u.protocol !== "https:" ||
+            !u.hostname ||
+            u.username ||
+            u.password ||
+            /[\\\x00-\x20]/.test(value))
+            throw new Error();
+        return u;
+    }
+    catch {
+        throw protocolError(code, "URL requires absolute HTTPS, a host and no userinfo");
+    }
+}
+const sha3 = (bytes) => base64UrlEncode(sha3_256(typeof bytes === "string" ? new TextEncoder().encode(bytes) : bytes));
+/** Sorted, distinct direct dependencies. */
+export function knowledgeDependencies(item) {
+    return item.event.type === "knowledge.publish"
+        ? [
+            ...new Set(item.event.payload.relations?.map((link) => link.target) ?? []),
+        ].sort()
+        : [
+            item.event.payload
+                .target,
+        ];
+}
+/** Structure, Identity hash/signature, URLs, canonical IDs and profile uniqueness. Dependencies are separate. */
+export function validateKnowledgeEnvelope(value) {
+    validateKnowledgeSchema(value);
+    const item = value;
+    verifyEnvelope(item);
+    validateKnowledgeId(item.hash);
+    const payload = item.event.payload;
+    https(payload.license);
+    if ("evidence" in payload)
+        for (const ref of payload.evidence ?? []) {
+            https(ref.url);
+            if (ref.digest !== undefined)
+                validateKnowledgeId(ref.digest);
+        }
+    if ("profiles" in payload) {
+        const seen = new Set();
+        for (const binding of payload.profiles ?? []) {
+            https(binding.profile.url);
+            validateKnowledgeId(binding.profile.digest);
+            if (seen.has(binding.profile.digest))
+                throw protocolError("invalid_event", "duplicate profile digest");
+            seen.add(binding.profile.digest);
+        }
+    }
+    for (const target of knowledgeDependencies(item))
+        validateKnowledgeId(target);
+}
+export function parseKnowledgeEnvelope(text) {
+    const value = parseStrictJson(text);
+    validateKnowledgeEnvelope(value);
+    return value;
+}
+function knownMap(known) {
+    return known instanceof Map ? known : new Map(Object.entries(known));
+}
+/** Check target rules against retained envelopes that already passed validation. */
+export function validateKnowledgeDependencies(item, known) {
+    const retained = knownMap(known);
+    checkDependencies(item, (id) => retained.get(id));
+}
+function checkDependencies(item, lookup) {
+    const missing = knowledgeDependencies(item).filter((id) => lookup(id) === undefined);
+    if (missing.length)
+        throw protocolError("missing_dependency", "unresolved dependencies", {
+            missing,
+        });
+    const links = item.event.type === "knowledge.publish"
+        ? (item.event.payload.relations ?? [])
+        : [
+            {
+                relation: item.event.type,
+                target: item.event.payload.target,
+            },
+        ];
+    for (const link of links) {
+        const target = lookup(link.target).event;
+        const allowed = link.relation === "knowledge.retract" ||
+            ASSESSMENT_RELATIONS.includes(link.relation)
+            ? ["knowledge.publish", "knowledge.assess"]
+            : ["knowledge.publish"];
+        if (!allowed.includes(target.type))
+            throw protocolError("invalid_target", "wrong target type");
+        const kind = link.relation === "addresses"
+            ? "question"
+            : link.relation === "tests"
+                ? "hypothesis"
+                : undefined;
+        if (kind && target.payload.kind !== kind)
+            throw protocolError("invalid_target", "wrong target contribution kind");
+        if (["supersedes", "knowledge.retract"].includes(link.relation) &&
+            (target.actor !== item.event.actor || target.nonce >= item.event.nonce))
+            throw protocolError("invalid_target", "target requires same actor and smaller nonce");
+    }
+}
+/** Validates a dependency-closed dataset, then derives order-independent local facts. */
+export function materializeKnowledge(known) {
+    const retained = knownMap(known);
+    for (const [id, item] of retained) {
+        validateKnowledgeEnvelope(item);
+        if (id !== item.hash)
+            throw protocolError("invalid_event", "dataset ID mismatch");
+    }
+    for (const item of retained.values())
+        validateKnowledgeDependencies(item, retained);
+    const withdrawn = new Set();
+    const successors = new Map();
+    const assessments = new Map();
+    const append = (index, target, id) => {
+        let ids = index.get(target);
+        if (!ids) {
+            ids = new Set();
+            index.set(target, ids);
+        }
+        ids.add(id);
+    };
+    for (const [id, item] of retained) {
+        if (item.event.type === "knowledge.retract")
+            withdrawn.add(item.event.payload.target);
+        else if (item.event.type === "knowledge.assess")
+            append(assessments, item.event.payload.target, id);
+        else
+            for (const link of item.event.payload
+                .relations ?? [])
+                if (link.relation === "supersedes")
+                    append(successors, link.target, id);
+    }
+    const result = {};
+    for (const [id, item] of [...retained.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+        if (item.event.type === "knowledge.retract")
+            continue;
+        const view = {
+            status: withdrawn.has(id) ? "retracted" : "active",
+        };
+        if (item.event.type === "knowledge.publish") {
+            view.successors = [...(successors.get(id) ?? [])].sort();
+            view.assessments = [...(assessments.get(id) ?? [])].sort();
+            view.active_assessments = view.assessments.filter((key) => !withdrawn.has(key));
+        }
+        result[id] = view;
+    }
+    return result;
+}
+/**
+ * Compare a digest with complete representation bytes (after transfer/content
+ * decoding, before text conversion). Pass `null` or `undefined` bytes when the
+ * complete representation could not be obtained. No fetching occurs.
+ */
+export function verifyKnowledgeEvidence(digest, bytes) {
+    if (digest === undefined)
+        return "unchecked";
+    validateKnowledgeId(digest);
+    if (bytes == null)
+        return "unavailable";
+    return sha3(bytes) === digest ? "matched" : "mismatched";
+}
+const fold = (value) => value.replace(/[A-Z]/g, (char) => char.toLowerCase());
+export function knowledgeTextTerms(value, lexical = true) {
+    if (typeof value !== "string" ||
+        [...value].length < 1 ||
+        [...value].length > 1024 ||
+        /[\uD800-\uDFFF]/u.test(value))
+        throw protocolError("invalid_request", "text requires 1..1024 Unicode scalars");
+    const terms = value.split(/[\x09-\x0d\x20]+/).filter(Boolean);
+    if (!terms.length || (lexical && terms.length > 16))
+        throw protocolError("invalid_request", "empty text or too many lexical terms");
+    return terms.map(fold);
+}
+export function knowledgeTextMatches(item, text) {
+    const p = item.event.payload;
+    let fields;
+    if (item.event.type === "knowledge.retract")
+        fields = [p.reason];
+    else {
+        const r = p;
+        fields =
+            item.event.type === "knowledge.publish"
+                ? [
+                    p.title,
+                    p.statement,
+                    r.basis,
+                ]
+                : [p.summary, r.basis];
+        fields.push(r.context.scope, ...r.context.conditions, ...r.context.limitations);
+    }
+    const folded = fields.map(fold);
+    return knowledgeTextTerms(text).every((term) => folded.some((field) => field.includes(term)));
+}
+function filterCheck(filters) {
+    validateKnowledgeSchema(filters, "searchFilters", "invalid_request");
+    for (const key of ["actor", "target", "profile"])
+        if (filters[key] !== undefined)
+            validateKnowledgeId(key === "actor" ? filters[key].slice(10) : filters[key], "invalid_request");
+    if (filters.created_from !== undefined &&
+        filters.created_before !== undefined &&
+        filters.created_from >= filters.created_before)
+        throw protocolError("invalid_request", "time range must be nonempty");
+}
+export function validateKnowledgeQuery(value) {
+    validateKnowledgeSchema(value, "queryRequest", "invalid_request");
+    const { q, limit: _l, cursor: _c, after_seq: _a, ...filters } = value;
+    filterCheck(filters);
+    if (q !== undefined)
+        knowledgeTextTerms(q);
+}
+const INTEGER_PARAMETERS = [
+    "created_from",
+    "created_before",
+    "after_seq",
+    "limit",
+];
+/** Parse decoded HTTP pairs without discarding duplicate parameter names. */
+export function parseKnowledgeQuery(parameters) {
+    const result = {};
+    for (const [key, input] of parameters) {
+        if (Object.hasOwn(result, key) ||
+            !Object.hasOwn(KNOWLEDGE_SCHEMA.$defs.queryRequest.properties, key))
+            throw protocolError("invalid_request", "unknown or repeated query parameter");
+        let value = input;
+        if (INTEGER_PARAMETERS.includes(key)) {
+            if (!/^[0-9]+$/.test(input) || input.replace(/^0+/, "").length > 16)
+                throw protocolError("invalid_request", "HTTP integers require decimal digits");
+            value = Number(input);
+        }
+        Object.defineProperty(result, key, { value, enumerable: true });
+    }
+    validateKnowledgeQuery(result);
+    return result;
+}
+/** Exact filter and text predicate; `after_seq`, `limit` and `cursor` are not payload filters. */
+export function knowledgeQueryMatches(item, filters) {
+    const event = item.event, p = event.payload, publication = event.type === "knowledge.publish", pub = p;
+    if ((filters.actor !== undefined && event.actor !== filters.actor) ||
+        (filters.type !== undefined && event.type !== filters.type))
+        return false;
+    if ("q" in filters &&
+        filters.q !== undefined &&
+        !knowledgeTextMatches(item, filters.q))
+        return false;
+    if (filters.language !== undefined &&
+        (!publication || fold(pub.language) !== fold(filters.language)))
+        return false;
+    if (filters.verdict !== undefined &&
+        (event.type !== "knowledge.assess" ||
+            p.verdict !== filters.verdict))
+        return false;
+    if ((filters.created_from !== undefined &&
+        event.created_at < filters.created_from) ||
+        (filters.created_before !== undefined &&
+            event.created_at >= filters.created_before))
+        return false;
+    if (filters.kind !== undefined && (!publication || pub.kind !== filters.kind))
+        return false;
+    if (filters.tag !== undefined &&
+        (!publication || !pub.tags?.includes(filters.tag)))
+        return false;
+    if (filters.profile !== undefined &&
+        !p.profiles?.some((b) => b.profile.digest === filters.profile))
+        return false;
+    if (filters.relation !== undefined) {
+        if (!publication ||
+            !pub.relations?.some((r) => r.relation === filters.relation &&
+                (filters.target === undefined || r.target === filters.target)))
+            return false;
+    }
+    else if (filters.target !== undefined &&
+        !knowledgeDependencies(item).includes(filters.target))
+        return false;
+    return true;
+}
+export function parseKnowledgeReadJson(raw) {
+    try {
+        return parseStrictJson(raw);
+    }
+    catch {
+        throw protocolError("invalid_request", "read body violates strict I-JSON");
+    }
+}
+export function validateKnowledgeBatchRequest(value) {
+    validateKnowledgeSchema(value, "batchRequest", "invalid_request");
+    for (const id of value.hashes)
+        validateKnowledgeId(id, "invalid_request");
+}
+/** An unadvertised mode is `unsupported_search_mode` and is never substituted. */
+export function validateKnowledgeSearchRequest(value, modes = KNOWLEDGE_SEARCH_MODES) {
+    jsonCheck(value, "invalid_request");
+    const mode = value?.mode;
+    if (typeof mode === "string" &&
+        (!KNOWLEDGE_SEARCH_MODES.includes(mode) ||
+            !modes.includes(mode)))
+        throw protocolError("unsupported_search_mode", "requested mode is not advertised");
+    validateKnowledgeSchema(value, "searchRequest", "invalid_request");
+    const request = value;
+    knowledgeTextTerms(request.text, mode === "lexical");
+    filterCheck(request.filters ?? {});
+}
+export function validateKnowledgeRecord(value, expectedId) {
+    validateKnowledgeSchema(value, "acceptanceRecord", "invalid_response");
+    const record = value;
+    try {
+        validateKnowledgeEnvelope(record.envelope);
+    }
+    catch {
+        throw protocolError("invalid_response", "invalid returned envelope");
+    }
+    if (expectedId !== undefined && record.envelope.hash !== expectedId)
+        throw protocolError("invalid_response", "returned envelope ID does not match request");
+}
+function responseRecords(value, definition, service) {
+    validateKnowledgeSchema(value, definition, "invalid_response");
+    const response = value;
+    try {
+        validateOrigin(response.service);
+    }
+    catch {
+        throw protocolError("invalid_response", "noncanonical service origin");
+    }
+    if (response.service !== service)
+        throw protocolError("invalid_response", "response service differs from receiving origin");
+    const records = definition === "searchResponse"
+        ? response.result.map((hit) => hit.record)
+        : response.result;
+    const ids = new Set();
+    for (const record of records) {
+        if (record.seq > response.checkpoint || ids.has(record.envelope.hash))
+            throw protocolError("invalid_response", "duplicate event or record beyond checkpoint");
+        ids.add(record.envelope.hash);
+        validateKnowledgeRecord(record);
+    }
+    return records;
+}
+export function validateKnowledgeQueryResponse(value, request, service) {
+    const records = responseRecords(value, "queryResponse", service);
+    if (records.length > (request.limit ?? 100))
+        throw protocolError("invalid_response", "query page exceeds limit");
+    let previous = request.after_seq ?? 0;
+    for (const record of records) {
+        if (record.seq <= previous ||
+            !knowledgeQueryMatches(record.envelope, request))
+            throw protocolError("invalid_response", "query violated order or exact filters");
+        previous = record.seq;
+    }
+}
+export function validateKnowledgeBatchResponse(value, hashes, service) {
+    const result = responseRecords(value, "batchResponse", service).map((r) => r.envelope.hash), missing = value.missing;
+    if (result.some((id) => missing.includes(id)) ||
+        new Set([...result, ...missing]).size !== hashes.length ||
+        [...result, ...missing].some((id) => !hashes.includes(id)) ||
+        canonicalize(result) !==
+            canonicalize(hashes.filter((id) => result.includes(id))) ||
+        canonicalize(missing) !==
+            canonicalize(hashes.filter((id) => missing.includes(id))))
+        throw protocolError("invalid_response", "batch must form complete ordered partition");
+}
+export function validateKnowledgeSearchResponse(value, request, service) {
+    const records = responseRecords(value, "searchResponse", service);
+    const response = value;
+    if (records.length > (request.limit ?? 20) ||
+        response.ranking.mode !== request.mode)
+        throw protocolError("invalid_response", "search limit or mode mismatch");
+    for (const record of records)
+        if (!knowledgeQueryMatches(record.envelope, request.filters ?? {}) ||
+            (request.mode === "lexical" &&
+                !knowledgeTextMatches(record.envelope, request.text)))
+            throw protocolError("invalid_response", "search violated exact filters or lexical text");
+}
+export function validateKnowledgeDiscovery(value, origin) {
+    validateKnowledgeSchema(value, "discoveryDocument", "invalid_discovery");
+    const d = value;
+    try {
+        validateOrigin(origin);
+        validateOrigin(d.service);
+        if (d.service !== origin)
+            throw new Error();
+        for (const endpoint of Object.values(d.endpoints ?? {})) {
+            const url = https(endpoint);
+            if (url.origin !== origin || url.search || url.hash)
+                throw new Error();
+        }
+        for (const peer of d.peers ?? []) {
+            validateOrigin(peer);
+            if (peer === origin)
+                throw new Error();
+        }
+    }
+    catch {
+        throw protocolError("invalid_discovery", "invalid service, endpoint or peer");
+    }
+}
+/** Effective request for cursor binding: no cursor, defaults applied. */
+function queryBinding(request) {
+    const { cursor: _c, ...rest } = request;
+    return canonicalize({
+        ...rest,
+        limit: request.limit ?? 100,
+        after_seq: request.after_seq ?? 0,
+    });
+}
+/** Verifies that query pages form one complete, consistent enumeration. */
+export class KnowledgePageTracker {
+    service;
+    binding;
+    scope;
+    last = 0;
+    next;
+    seen = new Set();
+    constructor(service) {
+        this.service = service;
+        validateOrigin(service);
+    }
+    get complete() {
+        return this.binding !== undefined && this.next === undefined;
+    }
+    /** The next poll's `after_seq`, available only after every page was consumed. */
+    get checkpoint() {
+        return this.complete ? JSON.parse(this.scope).checkpoint : undefined;
+    }
+    accept(request, response) {
+        validateKnowledgeQuery(request);
+        validateKnowledgeQueryResponse(response, request, this.service);
+        const binding = queryBinding(request);
+        const scope = canonicalize({
+            service: response.service,
+            checkpoint: response.checkpoint,
+            as_of: response.as_of,
+        });
+        if (this.binding === undefined) {
+            if (request.cursor !== undefined)
+                throw protocolError("invalid_response", "a traversal must start without a cursor");
+            this.last = request.after_seq ?? 0;
+        }
+        else if (this.next === undefined ||
+            request.cursor !== this.next ||
+            binding !== this.binding ||
+            scope !== this.scope)
+            throw protocolError("invalid_response", "pagination request or checkpoint scope changed");
+        const first = response.result[0];
+        if ((first !== undefined && first.seq <= this.last) ||
+            response.result.some((record) => this.seen.has(record.envelope.hash)))
+            throw protocolError("invalid_response", "pagination repeated an event or moved backwards");
+        for (const record of response.result)
+            this.seen.add(record.envelope.hash);
+        if (response.result.length)
+            this.last = response.result.at(-1).seq;
+        this.binding = binding;
+        this.scope = scope;
+        this.next = response.next_cursor;
+    }
+}
+/**
+ * Synchronous in-memory reference service engine with checkpoint-bound,
+ * stateless query cursors. Applications supply persistence and HTTP policy.
+ */
+export class KnowledgeStore {
+    service;
+    clock;
+    futureSkewMs;
+    maxEnvelopeBytes;
+    admit;
+    /** Insertion order is ascending seq: new records always get a larger seq. */
+    records = new Map();
+    hidden = new Set();
+    highWater = 0;
+    constructor(options) {
+        validateOrigin(options.service);
+        this.service = options.service;
+        this.clock = options.clock ?? Date.now;
+        this.futureSkewMs = options.futureSkewMs ?? DEFAULT_FUTURE_SKEW_MS;
+        this.maxEnvelopeBytes =
+            options.maxEnvelopeBytes ?? DEFAULT_MAX_ENVELOPE_BYTES;
+        this.admit = options.admit;
+        for (const [name, value] of [
+            ["futureSkewMs", this.futureSkewMs],
+            ["maxEnvelopeBytes", this.maxEnvelopeBytes],
+        ])
+            if (!Number.isSafeInteger(value) || value < 0)
+                throw protocolError("invalid_request", `invalid store option ${name}`);
+    }
+    get checkpoint() {
+        return this.highWater;
+    }
+    now() {
+        const now = this.clock();
+        if (!Number.isSafeInteger(now) || now < 0)
+            throw protocolError("invalid_request", "invalid service clock");
+        return now;
+    }
+    visible(id) {
+        return this.records.has(id) && !this.hidden.has(id);
+    }
+    /** Publicly visible envelopes keyed by event ID; copies cannot mutate storage. */
+    knownEnvelopes() {
+        return new Map([...this.records]
+            .filter(([id]) => this.visible(id))
+            .map(([id, record]) => [id, structuredClone(record.envelope)]));
+    }
+    /** Accept a signed event, or return the original record of an exact resubmission. */
+    submit(envelope, now = this.now()) {
+        if (!Number.isSafeInteger(now) || now < 0)
+            throw protocolError("invalid_request", "invalid service clock");
+        const copy = structuredClone(envelope);
+        validateKnowledgeEnvelope(copy);
+        const retained = this.records.get(copy.hash);
+        if (retained)
+            return structuredClone(retained);
+        if (copy.event.created_at > now + this.futureSkewMs)
+            throw protocolError("timestamp_out_of_window", "created_at is too far in the future");
+        checkDependencies(copy, (id) => this.records.get(id)?.envelope);
+        if (new TextEncoder().encode(JSON.stringify(copy)).length > this.maxEnvelopeBytes)
+            throw protocolError("payload_too_large", "envelope exceeds configured byte limit");
+        if (this.highWater === Number.MAX_SAFE_INTEGER)
+            throw protocolError("permission_denied", "sequence space exhausted");
+        this.admit?.(structuredClone(copy));
+        const record = {
+            envelope: copy,
+            accepted_at: now,
+            seq: ++this.highWater,
+        };
+        this.records.set(copy.hash, record);
+        return structuredClone(record);
+    }
+    event(id) {
+        validateKnowledgeId(id, "invalid_request");
+        if (!this.visible(id))
+            throw protocolError("not_found", "event unavailable");
+        return structuredClone(this.records.get(id));
+    }
+    /** Withhold from public reads; the record still answers exact retries and resolves dependencies. */
+    hide(id) {
+        if (this.records.has(id))
+            this.hidden.add(id);
+    }
+    unhide(id) {
+        this.hidden.delete(id);
+    }
+    /** Drop content and record; the sequence high-water mark is preserved. */
+    prune(id) {
+        this.records.delete(id);
+        this.hidden.delete(id);
+    }
+    scope(checkpoint, asOf) {
+        return { service: this.service, checkpoint, as_of: asOf };
+    }
+    batch(request) {
+        validateKnowledgeBatchRequest(request);
+        const response = {
+            result: [],
+            missing: [],
+            ...this.scope(this.highWater, this.now()),
+        };
+        for (const id of request.hashes)
+            if (this.visible(id))
+                response.result.push(structuredClone(this.records.get(id)));
+            else
+                response.missing.push(id);
+        return response;
+    }
+    query(request = {}) {
+        validateKnowledgeQuery(request);
+        const digest = sha3(queryBinding(request));
+        const after = request.after_seq ?? 0, limit = request.limit ?? 100;
+        let checkpoint, asOf, last;
+        if (request.cursor !== undefined)
+            [checkpoint, asOf, last] = this.decodeCursor(request.cursor, digest, after);
+        else {
+            if (after > this.highWater)
+                throw protocolError("invalid_request", "after_seq is greater than the current checkpoint");
+            [checkpoint, asOf, last] = [this.highWater, this.now(), after];
+        }
+        const response = {
+            result: [],
+            ...this.scope(checkpoint, asOf),
+        };
+        for (const [id, record] of this.records) {
+            if (record.seq <= last || record.seq > checkpoint || this.hidden.has(id))
+                continue;
+            if (!knowledgeQueryMatches(record.envelope, request))
+                continue;
+            if (response.result.length === limit) {
+                response.next_cursor = `${checkpoint}.${asOf}.${response.result.at(-1).seq}.${digest}`;
+                break;
+            }
+            response.result.push(structuredClone(record));
+        }
+        return response;
+    }
+    decodeCursor(cursor, digest, after) {
+        const parts = cursor.split(".");
+        if (parts.length !== 4 ||
+            parts[3] !== digest ||
+            parts.slice(0, 3).some((part) => !/^[0-9]{1,16}$/.test(part)))
+            throw protocolError("invalid_cursor", "malformed cursor or different request");
+        const [checkpoint, asOf, last] = parts.slice(0, 3).map(Number);
+        if (!(after <= last && last <= checkpoint && checkpoint <= this.highWater) ||
+            !Number.isSafeInteger(asOf))
+            throw protocolError("invalid_cursor", "cursor does not belong to this service state");
+        return [checkpoint, asOf, last];
+    }
+    /**
+     * Return one page of caller-ranked candidates; no ranking model is implied.
+     * Only a lexical page containing every match may claim exhaustive coverage.
+     */
+    search(request, selection, modes = KNOWLEDGE_SEARCH_MODES) {
+        validateKnowledgeSearchRequest(request, modes);
+        const limit = request.limit ?? 20;
+        const eligible = new Set();
+        for (const [id, record] of this.records)
+            if (!this.hidden.has(id) &&
+                knowledgeQueryMatches(record.envelope, request.filters ?? {}) &&
+                (request.mode !== "lexical" ||
+                    knowledgeTextMatches(record.envelope, request.text)))
+                eligible.add(id);
+        const ids = selection.candidates;
+        if (new Set(ids).size !== ids.length || ids.some((id) => !eligible.has(id)))
+            throw protocolError("invalid_response", "candidate list repeats IDs or violates exact filters");
+        if (selection.coverage.exhaustive &&
+            (ids.length !== eligible.size || ids.length > limit))
+            throw protocolError("invalid_response", "false exhaustive coverage");
+        const response = {
+            result: ids.slice(0, limit).map((id) => {
+                const hit = {
+                    record: structuredClone(this.records.get(id)),
+                };
+                const explanation = selection.explanations?.[id];
+                if (explanation !== undefined)
+                    hit.explanation = explanation;
+                return hit;
+            }),
+            ...this.scope(this.highWater, this.now()),
+            ranking: structuredClone(selection.ranking),
+            coverage: structuredClone(selection.coverage),
+        };
+        validateKnowledgeSchema(response, "searchResponse", "invalid_response");
+        if (response.ranking.mode !== request.mode)
+            throw protocolError("invalid_response", "ranking mode differs from requested mode");
+        return response;
+    }
+}
+//# sourceMappingURL=knowledge.js.map