factbag 0.0.0-alpha.0

package/dist/corpus/corpus.d.ts

@@ -0,0 +1,41 @@
+import type { Chunk, Chunker, CorpusDocument, DocumentInput, DocumentReference, Metadata, ResolvedChunk, TextRange } from "./types.js";
+/**
+ * In-memory corpus of immutable documents and addressable source ranges.
+ * {@link Corpus.filter} returns views over the same storage; the filter is evaluated on read.
+ */
+export declare class Corpus<M extends Metadata = Metadata> {
+    #private;
+    /**
+     * Add a document to the shared storage; re-adding identical content is idempotent,
+     * different content throws. On a view, the document is visible only if it matches.
+     */
+    add(input: DocumentInput<M>): CorpusDocument<M>;
+    /** Validate every input, including conflicts, before storing any; then store them in input order. */
+    add(inputs: readonly DocumentInput<M>[]): readonly CorpusDocument<M>[];
+    /** Read a document. Throws when absent or excluded by this view's filter. */
+    document(documentId: string): CorpusDocument<M>;
+    /** List every document matching this view's filter, in insertion order. */
+    documents(): readonly CorpusDocument<M>[];
+    /**
+     * Return a view over the same storage that also requires this predicate. Documents
+     * added later through any view appear when they match.
+     */
+    filter(predicate: (document: CorpusDocument<M>) => boolean): Corpus<M>;
+    /**
+     * Split a document lazily, validating each range as it is consumed. If a later
+     * range is invalid, earlier yielded chunks remain valid and resolvable.
+     */
+    chunk(target: DocumentReference, chunker: Chunker): Iterable<Chunk>;
+    private splitDocument;
+    /** Select an exact range of a document. */
+    slice(target: DocumentReference, selection: TextRange): Chunk;
+    /**
+     * Resolve a chunk ID to its exact text and document. The ID encodes the document and
+     * range, so any valid ID resolves while its document exists; resolution ignores this
+     * view's filter. Throws for malformed IDs, unknown documents and invalid ranges.
+     */
+    resolve(chunkId: string): ResolvedChunk<M>;
+    private store;
+    private requireStored;
+    private requireVisible;
+}

package/dist/corpus/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Immutable documents and exact source chunks.
+ *
+ * @packageDocumentation
+ */
+export { Corpus } from "./corpus.js";
+export * as chunkers from "./chunkers.js";
+export type { Chunk, Chunker, ChunkReference, DocumentInput, CorpusDocument, DocumentReference, DocumentSource, Metadata, RecursiveChunkOptions, ResolvedChunk, TextRange, } from "./types.js";

package/dist/corpus/index.js

@@ -0,0 +1,312 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/records.ts
+function record(value) {
+  if (!isRecord(value)) {
+    throw new Error("Expected an object");
+  }
+  return value;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function string(value, name) {
+  if (typeof value !== "string") {
+    throw new Error(`${name} must be a string`);
+  }
+  return value;
+}
+function makeDocument(value) {
+  const input = record(value);
+  const documentId = string(input["documentId"], "documentId");
+  if (documentId.trim().length === 0) {
+    throw new Error("documentId must not be empty");
+  }
+  const rawMetadata = record(input["metadata"] ?? {});
+  if (Object.getPrototypeOf(rawMetadata) !== Object.prototype && Object.getPrototypeOf(rawMetadata) !== null) {
+    throw new Error("Metadata must be a plain object");
+  }
+  const metadata = value.metadata === void 0 ? {} : { ...value.metadata };
+  const rawSource = input["source"] === void 0 ? void 0 : record(input["source"]);
+  const source = rawSource === void 0 ? void 0 : Object.freeze({
+    uri: string(rawSource["uri"], "source.uri"),
+    ...rawSource["mediaType"] === void 0 ? {} : { mediaType: string(rawSource["mediaType"], "source.mediaType") }
+  });
+  return Object.freeze({
+    documentId,
+    text: string(input["text"], "text"),
+    ...input["title"] === void 0 ? {} : { title: string(input["title"], "title") },
+    ...source === void 0 ? {} : { source },
+    metadata: Object.freeze(metadata)
+  });
+}
+function makeChunk(document, range) {
+  return Object.freeze({
+    id: `${encodeURIComponent(document.documentId)}#${range.start}-${range.end}`,
+    documentId: document.documentId,
+    range: Object.freeze({ start: range.start, end: range.end })
+  });
+}
+function parseChunkId(id) {
+  const match = /^([^#]+)#(0|[1-9]\d*)-(0|[1-9]\d*)$/u.exec(id);
+  const [, encoded, start, end] = match ?? [];
+  if (encoded === void 0 || start === void 0 || end === void 0) {
+    throw new Error(`Invalid chunk ID: ${id}`);
+  }
+  let documentId;
+  try {
+    documentId = decodeURIComponent(encoded);
+  } catch {
+    throw new Error(`Invalid chunk ID: ${id}`);
+  }
+  if (encodeURIComponent(documentId) !== encoded) {
+    throw new Error(`Invalid chunk ID: ${id}`);
+  }
+  return { documentId, range: { start: Number(start), end: Number(end) } };
+}
+
+// src/text.ts
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive safe integer`);
+  }
+}
+function nonnegativeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${name} must be a nonnegative safe integer`);
+  }
+}
+function graphemeBoundaries(text) {
+  const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+  return [...Array.from(segmenter.segment(text), (segment) => segment.index), text.length];
+}
+function validateRange(range, boundaries) {
+  if (!Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start >= range.end || !boundaries.has(range.start) || !boundaries.has(range.end)) {
+    throw new Error("Range must be nonempty, within the text, and on grapheme boundaries");
+  }
+}
+function boundaryAt(boundaries, index) {
+  const boundary = boundaries[index];
+  if (boundary === void 0) {
+    throw new Error("Invalid text boundary index");
+  }
+  return boundary;
+}
+
+// src/corpus.ts
+var Corpus = class _Corpus {
+  #storage = { documents: /* @__PURE__ */ new Map() };
+  #filter = () => true;
+  add(input) {
+    if (!isBatch(input)) {
+      const document = makeDocument(input);
+      const existing = this.#storage.documents.get(document.documentId);
+      if (existing !== void 0) {
+        assertSameContent(existing, document);
+        return existing;
+      }
+      return this.store(document);
+    }
+    const pending = /* @__PURE__ */ new Map();
+    const documents = input.map((item) => {
+      const document = makeDocument(item);
+      const existing = pending.get(document.documentId) ?? this.#storage.documents.get(document.documentId);
+      if (existing !== void 0) {
+        assertSameContent(existing, document);
+        return existing;
+      }
+      pending.set(document.documentId, document);
+      return document;
+    });
+    for (const document of pending.values()) {
+      this.store(document);
+    }
+    return Object.freeze(documents);
+  }
+  /** Read a document. Throws when absent or excluded by this view's filter. */
+  document(documentId) {
+    return this.requireVisible({ documentId });
+  }
+  /** List every document matching this view's filter, in insertion order. */
+  documents() {
+    return Object.freeze([...this.#storage.documents.values()].filter(this.#filter));
+  }
+  /**
+   * Return a view over the same storage that also requires this predicate. Documents
+   * added later through any view appear when they match.
+   */
+  filter(predicate) {
+    const parent = this.#filter;
+    const view = new _Corpus();
+    view.#storage = this.#storage;
+    view.#filter = (document) => parent(document) && predicate(document);
+    return view;
+  }
+  /**
+   * Split a document lazily, validating each range as it is consumed. If a later
+   * range is invalid, earlier yielded chunks remain valid and resolvable.
+   */
+  chunk(target, chunker) {
+    return this.splitDocument(this.requireVisible(target), chunker);
+  }
+  *splitDocument(document, chunker) {
+    const boundaries = new Set(graphemeBoundaries(document.text));
+    let previousStart = -1;
+    for (const range of chunker.split(document.text)) {
+      validateRange(range, boundaries);
+      if (range.start <= previousStart) {
+        throw new Error("Chunker ranges must advance in source order");
+      }
+      previousStart = range.start;
+      yield materialize(document, makeChunk(document, range));
+    }
+  }
+  /** Select an exact range of a document. */
+  slice(target, selection) {
+    const document = this.requireVisible(target);
+    validateRange(selection, new Set(graphemeBoundaries(document.text)));
+    return materialize(document, makeChunk(document, selection));
+  }
+  /**
+   * Resolve a chunk ID to its exact text and document. The ID encodes the document and
+   * range, so any valid ID resolves while its document exists; resolution ignores this
+   * view's filter. Throws for malformed IDs, unknown documents and invalid ranges.
+   */
+  resolve(chunkId) {
+    const { documentId, range } = parseChunkId(chunkId);
+    const document = this.requireStored({ documentId });
+    validateRange(range, new Set(graphemeBoundaries(document.text)));
+    return Object.freeze({ chunk: materialize(document, makeChunk(document, range)), document });
+  }
+  store(document) {
+    this.#storage.documents.set(document.documentId, document);
+    return document;
+  }
+  requireStored(reference) {
+    const document = this.#storage.documents.get(reference.documentId);
+    if (document === void 0) {
+      throw new Error(`Unknown document: ${reference.documentId}`);
+    }
+    return document;
+  }
+  requireVisible(reference) {
+    const document = this.requireStored(reference);
+    if (!this.#filter(document)) {
+      throw new Error(`Document "${document.documentId}" is excluded by this corpus view`);
+    }
+    return document;
+  }
+};
+function materialize(document, reference) {
+  return Object.freeze({
+    ...reference,
+    text: document.text.slice(reference.range.start, reference.range.end)
+  });
+}
+function assertSameContent(existing, document) {
+  const keys = Object.keys(existing.metadata);
+  if (existing.text !== document.text || existing.title !== document.title || existing.source?.uri !== document.source?.uri || existing.source?.mediaType !== document.source?.mediaType || keys.length !== Object.keys(document.metadata).length || !keys.every(
+    (key) => Object.hasOwn(document.metadata, key) && Object.is(existing.metadata[key], document.metadata[key])
+  )) {
+    throw new Error(`Document "${document.documentId}" already exists with different content`);
+  }
+}
+function isBatch(input) {
+  return Array.isArray(input);
+}
+
+// src/chunkers.ts
+var chunkers_exports = {};
+__export(chunkers_exports, {
+  recursive: () => recursive
+});
+function recursive(options) {
+  const { size, overlap = 0, measure } = options;
+  const separators = [...options.separators ?? ["\n\n", "\n", " "]];
+  positiveInteger(size, "size");
+  nonnegativeInteger(overlap, "overlap");
+  if (overlap >= size) {
+    throw new RangeError("overlap must be smaller than size");
+  }
+  if (separators.some((separator) => separator.length === 0)) {
+    throw new Error("Separators must be nonempty; grapheme fallback is automatic");
+  }
+  return Object.freeze({
+    name: "recursive",
+    *split(text) {
+      const boundaries = graphemeBoundaries(text);
+      const indices = new Map(boundaries.map((offset, index) => [offset, index]));
+      const last = boundaries.length - 1;
+      function count(start2, end) {
+        if (measure === void 0) {
+          return end - start2;
+        }
+        const value = measure(
+          text.slice(boundaryAt(boundaries, start2), boundaryAt(boundaries, end))
+        );
+        if (!Number.isSafeInteger(value) || value < 0) {
+          throw new RangeError("measure must return a nonnegative safe integer");
+        }
+        return value;
+      }
+      function boundedEnd(start2) {
+        if (measure === void 0) {
+          return Math.min(start2 + size, last);
+        }
+        let end = start2;
+        while (end < last && count(start2, end + 1) <= size) {
+          end += 1;
+        }
+        if (end === start2) {
+          throw new RangeError("A single grapheme exceeds the chunk size");
+        }
+        return end;
+      }
+      function preferredEnd(start2, hardEnd) {
+        if (hardEnd === last) {
+          return hardEnd;
+        }
+        const startOffset = boundaryAt(boundaries, start2);
+        const endOffset = boundaryAt(boundaries, hardEnd);
+        for (const separator of separators) {
+          const offset = text.lastIndexOf(separator, endOffset - separator.length);
+          const candidate = indices.get(offset + separator.length);
+          if (offset >= startOffset && candidate !== void 0 && candidate > start2 && candidate <= hardEnd) {
+            return candidate;
+          }
+        }
+        return hardEnd;
+      }
+      function nextStart(start2, end) {
+        if (overlap === 0) {
+          return end;
+        }
+        if (measure === void 0) {
+          return Math.max(start2 + 1, end - overlap);
+        }
+        let next = end;
+        while (next > start2 + 1 && count(next - 1, end) <= overlap) {
+          next -= 1;
+        }
+        return next;
+      }
+      let start = 0;
+      while (start < last) {
+        const end = preferredEnd(start, boundedEnd(start));
+        yield { start: boundaryAt(boundaries, start), end: boundaryAt(boundaries, end) };
+        if (end === last) {
+          return;
+        }
+        start = nextStart(start, end);
+      }
+    }
+  });
+}
+export {
+  Corpus,
+  chunkers_exports as chunkers
+};

package/dist/corpus/records.d.ts

@@ -0,0 +1,8 @@
+import type { ChunkReference, CorpusDocument, DocumentInput, Metadata, TextRange } from "./types.js";
+export declare function makeDocument<M extends Metadata = Metadata>(value: DocumentInput<M>): CorpusDocument<M>;
+export declare function makeChunk(document: CorpusDocument, range: TextRange): ChunkReference;
+/** Parse a chunk ID back into its document and range. Only the canonical spelling is accepted. */
+export declare function parseChunkId(id: string): Readonly<{
+    documentId: string;
+    range: TextRange;
+}>;

package/dist/corpus/text.d.ts

@@ -0,0 +1,6 @@
+import type { TextRange } from "./types.js";
+export declare function positiveInteger(value: number, name: string): void;
+export declare function nonnegativeInteger(value: number, name: string): void;
+export declare function graphemeBoundaries(text: string): readonly number[];
+export declare function validateRange(range: TextRange, boundaries: ReadonlySet<number>): void;
+export declare function boundaryAt(boundaries: readonly number[], index: number): number;

package/dist/corpus/types.d.ts

@@ -0,0 +1,62 @@
+/** Application-defined metadata. Values may include native objects and functions. */
+export type Metadata = Readonly<Record<string, unknown>>;
+/** A half-open range, measured in JavaScript UTF-16 code units. */
+export type TextRange = Readonly<{
+    start: number;
+    end: number;
+}>;
+/** Location of the original artifact; text offsets refer to the stored text, not file bytes. */
+export type DocumentSource = Readonly<{
+    uri: string;
+    mediaType?: string;
+}>;
+/** Text supplied by the caller, after any file extraction or normalization. */
+export type DocumentInput<M extends Metadata = Metadata> = Readonly<{
+    documentId: string;
+    text: string;
+    title?: string;
+    source?: DocumentSource;
+    metadata?: M;
+}>;
+/** Identifies one immutable document. */
+export type DocumentReference = Readonly<{
+    documentId: string;
+}>;
+/** An immutable document. Re-adding its ID with different content is rejected. */
+export type CorpusDocument<M extends Metadata = Metadata> = DocumentReference & Readonly<{
+    text: string;
+    title?: string;
+    source?: DocumentSource;
+    /** Shallow snapshot; nested values retain identity and remain caller-owned. */
+    metadata: Readonly<Partial<M>>;
+}>;
+/** A stable source range; its ID depends only on the document and absolute range. */
+export type ChunkReference = DocumentReference & Readonly<{
+    id: string;
+    range: TextRange;
+}>;
+/** A source range with text materialized for convenient consumption by models or UIs. */
+export type Chunk = ChunkReference & Readonly<{
+    text: string;
+}>;
+/** A resolved chunk together with its complete document. */
+export type ResolvedChunk<M extends Metadata = Metadata> = Readonly<{
+    chunk: Chunk;
+    document: CorpusDocument<M>;
+}>;
+/** Synchronous segmentation into source-ordered ranges relative to the supplied text. */
+export type Chunker = Readonly<{
+    name: string;
+    split: (text: string) => Iterable<TextRange>;
+}>;
+/** Bounded recursive splitting; size and overlap use grapheme counts unless measure is supplied. */
+export type RecursiveChunkOptions = Readonly<{
+    /** Positive integer maximum size of each emitted substring. */
+    size: number;
+    /** Desired maximum overlap, smaller than size. Defaults to zero. */
+    overlap?: number;
+    /** Deterministic nonnegative integer size of a substring, e.g. an exact tokenizer's count. */
+    measure?: (text: string) => number;
+    /** Preferred separators, in order. Defaults to paragraphs, lines, then words. */
+    separators?: readonly string[];
+}>;

package/dist/guards/guarded-kb.d.ts

@@ -0,0 +1,59 @@
+import type { Atom, GroundAtom, PredicateDeclaration, PredicateSchema } from "../core/dsl/index.js";
+import type { EvidenceMetadata, KnowledgeBase, NegativeLiteral, PositiveLiteral } from "../core/knowledge-base/index.js";
+import type { QueryAllJudgment, QueryJudgment } from "../core/query/index.js";
+import type { AllowedPermission, Operation, PermissionFilter } from "./types.js";
+/**
+ * A permission-enforcing view over one KB. Permission edits return new views;
+ * permitted writes change the shared underlying KB.
+ * Nothing is permitted by default, and blocks override permits regardless of order.
+ * `"*"` matches every operation or predicate and is evaluated when permissions are read.
+ */
+export declare class GuardedKB {
+    #private;
+    /** The underlying, unrestricted KB shared by this view and its branches. */
+    readonly kb: KnowledgeBase;
+    constructor(
+    /** The underlying, unrestricted KB shared by this view and its branches. */
+    kb: KnowledgeBase);
+    /** Return a new view permitting every operation for every predicate; shorthand for `permit("*", "*")`. */
+    permit(operation: "*"): GuardedKB;
+    /** Return a new view permitting the operations for every predicate, including ones the KB references later. */
+    permit(operation: Operation | "*", predicates: "*"): GuardedKB;
+    /** Return a new view additionally permitting these predicates for the operations. */
+    permit(operation: Operation | "*", ...predicates: readonly PredicateDeclaration[]): GuardedKB;
+    /** Return a new view blocking every operation for every predicate; shorthand for `block("*", "*")`. */
+    block(operation: "*"): GuardedKB;
+    /** Return a new view blocking the operations for every predicate, including ones the KB references later. */
+    block(operation: Operation | "*", predicates: "*"): GuardedKB;
+    /** Return a new view blocking these predicates, including any later permits. */
+    block(operation: Operation | "*", ...predicates: readonly PredicateDeclaration[]): GuardedKB;
+    /**
+     * Return a view with the same permissions over a fork of the underlying KB.
+     * Later writes to either KB do not affect the other; wildcards resolve against each KB separately.
+     */
+    fork(): GuardedKB;
+    /** Assert evidence after checking permission; throws before writing when forbidden. */
+    asserts<Schema extends PredicateSchema>(atom: Atom<Schema>, metadata?: EvidenceMetadata): PositiveLiteral<Schema>;
+    /** Deny a fact after checking permission; throws before writing when forbidden. */
+    denies<Schema extends PredicateSchema>(atom: Atom<Schema>, metadata?: EvidenceMetadata): NegativeLiteral<Schema>;
+    /**
+     * Query a permitted ground atom. Permission applies to the requested predicate;
+     * evaluation uses the full KB, including supporting predicates and their proofs.
+     */
+    query<Schema extends PredicateSchema>(atom: GroundAtom<Schema>): QueryJudgment<Schema>;
+    /** Query all matches for a permitted predicate using the full KB. */
+    queryAll<Schema extends PredicateSchema>(pattern: Atom<Schema>): QueryAllJudgment<Schema>;
+    /** Return all effective grants, in first-permitted order. */
+    resolve(): readonly AllowedPermission[];
+    /** Return effective grants for one operation. */
+    resolve(operation: Operation): readonly AllowedPermission[];
+    /** Return effective grants for any of these predicates, including query grants. */
+    resolve(predicate: PredicateDeclaration, ...predicates: readonly PredicateDeclaration[]): readonly AllowedPermission[];
+    /** Filter effective grants without changing their order or bypassing blocks. */
+    resolve(filter: PermissionFilter): readonly AllowedPermission[];
+    private requirePermission;
+    private isBlocked;
+    private withRule;
+}
+/** Wrap a KB with a guard initially permitting no operations. Does not copy the KB. */
+export declare function guard(kb: KnowledgeBase): GuardedKB;

package/dist/guards/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Permission-enforcing views over knowledge bases, using composition.
+ *
+ * @packageDocumentation
+ */
+export { GuardedKB, guard } from "./guarded-kb.js";
+export type { AllowedPermission, Operation, PermissionFilter } from "./types.js";

package/dist/guards/index.js

@@ -0,0 +1,121 @@
+// src/guarded-kb.ts
+import { query, queryAll } from "../core/query/index.js";
+var operations = ["assert", "deny", "query"];
+var GuardedKB = class _GuardedKB {
+  constructor(kb) {
+    this.kb = kb;
+  }
+  kb;
+  #rules = [];
+  permit(operation, ...predicates) {
+    return this.withRule("permit", operation, predicates);
+  }
+  block(operation, ...predicates) {
+    return this.withRule("block", operation, predicates);
+  }
+  /**
+   * Return a view with the same permissions over a fork of the underlying KB.
+   * Later writes to either KB do not affect the other; wildcards resolve against each KB separately.
+   */
+  fork() {
+    const next = new _GuardedKB(this.kb.fork());
+    next.#rules = this.#rules;
+    return next;
+  }
+  /** Assert evidence after checking permission; throws before writing when forbidden. */
+  asserts(atom, metadata) {
+    this.requirePermission("assert", atom.predicate);
+    return this.kb.asserts(atom, metadata);
+  }
+  /** Deny a fact after checking permission; throws before writing when forbidden. */
+  denies(atom, metadata) {
+    this.requirePermission("deny", atom.predicate);
+    return this.kb.denies(atom, metadata);
+  }
+  /**
+   * Query a permitted ground atom. Permission applies to the requested predicate;
+   * evaluation uses the full KB, including supporting predicates and their proofs.
+   */
+  query(atom) {
+    this.requirePermission("query", atom.predicate);
+    return query(this.kb, atom);
+  }
+  /** Query all matches for a permitted predicate using the full KB. */
+  queryAll(pattern) {
+    this.requirePermission("query", pattern.predicate);
+    return queryAll(this.kb, pattern);
+  }
+  resolve(selection, ...predicates) {
+    let filter = {};
+    if (typeof selection === "string") {
+      filter = { operations: [selection] };
+    } else if (selection !== void 0) {
+      filter = "name" in selection ? { predicates: [selection, ...predicates] } : selection;
+    }
+    const known = this.#rules.some((rule) => rule.predicates === "*") ? this.kb.predicates() : [];
+    const subjectsOf = (rule) => rule.predicates === "*" ? known : rule.predicates;
+    const seen = /* @__PURE__ */ new Map();
+    const allowed = [];
+    for (const rule of this.#rules) {
+      if (rule.effect !== "permit") {
+        continue;
+      }
+      for (const operation of rule.operations) {
+        if (filter.operations && !filter.operations.includes(operation)) {
+          continue;
+        }
+        const subjects = seen.get(operation) ?? /* @__PURE__ */ new Set();
+        for (const predicate of subjectsOf(rule)) {
+          if (filter.predicates && !filter.predicates.includes(predicate)) {
+            continue;
+          }
+          if (subjects.has(predicate) || this.isBlocked(operation, predicate)) {
+            continue;
+          }
+          subjects.add(predicate);
+          allowed.push({ operation, predicate });
+        }
+        seen.set(operation, subjects);
+      }
+    }
+    return allowed;
+  }
+  requirePermission(operation, predicate) {
+    const permitted = this.#rules.some(
+      (rule) => rule.effect === "permit" && matches(rule, operation, predicate)
+    );
+    if (!permitted || this.isBlocked(operation, predicate)) {
+      throw new Error(
+        `Operation "${operation}" is not permitted for predicate "${predicate.name}"`
+      );
+    }
+  }
+  isBlocked(operation, predicate) {
+    return this.#rules.some(
+      (rule) => rule.effect === "block" && matches(rule, operation, predicate)
+    );
+  }
+  withRule(effect, operation, predicates) {
+    const wildcard = predicates[0] === "*" || operation === "*" && predicates.length === 0;
+    const next = new _GuardedKB(this.kb);
+    next.#rules = [
+      ...this.#rules,
+      {
+        effect,
+        operations: operation === "*" ? operations : [operation],
+        predicates: wildcard ? "*" : predicates.filter((predicate) => predicate !== "*")
+      }
+    ];
+    return next;
+  }
+};
+function matches(rule, operation, predicate) {
+  return rule.operations.includes(operation) && (rule.predicates === "*" || rule.predicates.includes(predicate));
+}
+function guard(kb) {
+  return new GuardedKB(kb);
+}
+export {
+  GuardedKB,
+  guard
+};

package/dist/guards/types.d.ts

@@ -0,0 +1,15 @@
+import type { PredicateDeclaration } from "../core/dsl/index.js";
+/** Guarded knowledge-base operations that can be permitted independently. */
+export type Operation = "assert" | "deny" | "query";
+/** An effective grant after blocks and duplicates have been removed. */
+export type AllowedPermission = Readonly<{
+    operation: Operation;
+    predicate: PredicateDeclaration;
+}>;
+/** OR within each dimension, AND between dimensions. Empty arrays match nothing. */
+export type PermissionFilter = Readonly<{
+    /** Omit to match every operation. */
+    operations?: readonly Operation[];
+    /** Omit to match every predicate. Predicates are matched by identity. */
+    predicates?: readonly PredicateDeclaration[];
+}>;