@tangle-network/agent-knowledge 6.1.11 → 7.0.0

package/dist/sources/index.js

@@ -1,4 +1,4 @@
-import { t as sha256 } from "../ids-DRqPZ42_.js";
+import { t as sha256 } from "../ids-Bevz_pXV.js";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 //#region src/sources/html.ts

package/dist/types-BOfmvDe-.d.ts

@@ -0,0 +1,306 @@
+//#region src/types.d.ts
+type KnowledgeId = string;
+interface SourceAnchor {
+  id: string;
+  sourceId: string;
+  label?: string;
+  page?: number;
+  lineStart?: number;
+  lineEnd?: number;
+  charStart?: number;
+  charEnd?: number;
+  timestampMs?: number;
+  metadata?: Record<string, unknown>;
+}
+interface SourceRecord {
+  id: KnowledgeId;
+  uri: string;
+  title?: string;
+  mediaType?: string;
+  contentHash: string;
+  text?: string;
+  anchors?: SourceAnchor[];
+  /** ISO timestamp after which consumers should treat this source as stale. */
+  validUntil?: string;
+  /** ISO timestamp for the last successful source freshness verification. */
+  lastVerifiedAt?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}
+interface SourceRegistry {
+  generatedAt: string;
+  sources: SourceRecord[];
+}
+interface ClaimRef {
+  sourceId: string;
+  anchorId?: string;
+  quote?: string;
+}
+interface KnowledgeClaim {
+  id: KnowledgeId;
+  text: string;
+  refs: ClaimRef[];
+  confidence?: number;
+  status?: 'draft' | 'active' | 'superseded' | 'rejected';
+  metadata?: Record<string, unknown>;
+}
+interface KnowledgeRelation {
+  sourceId: KnowledgeId;
+  targetId: KnowledgeId;
+  predicate: string;
+  weight?: number;
+  metadata?: Record<string, unknown>;
+}
+interface KnowledgeUnit {
+  id: KnowledgeId;
+  title: string;
+  text: string;
+  claims?: KnowledgeClaim[];
+  relations?: KnowledgeRelation[];
+  sourceIds?: string[];
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  updatedAt?: string;
+}
+interface KnowledgePage {
+  id: KnowledgeId;
+  path: string;
+  title: string;
+  text: string;
+  frontmatter: Record<string, unknown>;
+  sourceIds: string[];
+  tags: string[];
+  outLinks: string[];
+}
+interface KnowledgeGraphNode {
+  id: KnowledgeId;
+  title: string;
+  path: string;
+  tags: string[];
+  sourceIds: string[];
+  outDegree: number;
+  inDegree: number;
+}
+interface KnowledgeGraphEdge {
+  source: KnowledgeId;
+  target: KnowledgeId;
+  weight: number;
+  reasons: string[];
+}
+interface KnowledgeGraph {
+  nodes: KnowledgeGraphNode[];
+  edges: KnowledgeGraphEdge[];
+}
+interface KnowledgeIndex {
+  root: string;
+  generatedAt: string;
+  sources: SourceRecord[];
+  pages: KnowledgePage[];
+  graph: KnowledgeGraph;
+}
+interface KnowledgeSearchResult {
+  page: KnowledgePage;
+  /**
+   * Raw reciprocal rank fusion score. Mathematically meaningful for ordering
+   * but not on a [0, 1] confidence scale — typical absolute values are in the
+   * 0.01–0.05 range. Equal to `rrfScore`; preserved as `score` for backward
+   * compatibility with consumers built against earlier releases.
+   */
+  score: number;
+  /** Alias of `score` — the raw RRF value. Use this when intent matters. */
+  rrfScore: number;
+  /**
+   * Score linearly normalized to [0, 1] relative to the top hit *in this
+   * result set*. The top hit is always 1 (when present); subsequent hits are
+   * `score / topScore`. Designed to match human intuition for "how confident
+   * is this match" — safe to compare against fixed thresholds. Note: this is
+   * a within-set ranking, not a cross-query absolute confidence.
+   */
+  normalizedScore: number;
+  rank: number;
+  snippet: string;
+  reasons: string[];
+}
+interface KnowledgeLintFinding {
+  type: 'broken-link' | 'orphan' | 'no-outlinks' | 'uncited-claim' | 'missing-source' | 'duplicate-title' | 'duplicate-page-id' | 'duplicate-source-hash' | 'missing-frontmatter';
+  severity: 'info' | 'warning' | 'error';
+  page?: string;
+  message: string;
+  metadata?: Record<string, unknown>;
+}
+interface KnowledgePolicy {
+  id: string;
+  description?: string;
+  requiredCitationRate?: number;
+  allowedPathPrefixes?: string[];
+  metadata?: Record<string, unknown>;
+}
+interface KnowledgeBaseCandidate {
+  id: KnowledgeId;
+  units: KnowledgeUnit[];
+  retrievalPolicy?: string;
+  synthesisPolicy?: string;
+  questionPolicy?: string;
+  updatePolicy?: string;
+  metadata?: Record<string, unknown>;
+}
+interface KnowledgeWriteBlock {
+  path: string;
+  content: string;
+}
+interface KnowledgeWriteParseResult {
+  blocks: KnowledgeWriteBlock[];
+  warnings: string[];
+}
+/**
+ * The event vocabulary, as a value so the runtime schema is DERIVED from it
+ * rather than restated. A restated copy in `schemas.ts` drifted: it omitted
+ * `research.iteration`, which is the only event `runVerifiedResearchLoop`
+ * produces, so every attempt to store one would have been rejected. Nothing
+ * caught it because nothing ever stored an event. Add a type here and the
+ * schema accepts it in the same edit.
+ */
+declare const KNOWLEDGE_EVENT_TYPES: readonly ['source.added', 'proposal.applied', 'index.built', 'lint.run', 'research.iteration', 'optimization.run', 'release.promoted', 'release.rejected'];
+type KnowledgeEventType = (typeof KNOWLEDGE_EVENT_TYPES)[number];
+interface KnowledgeEvent {
+  id: string;
+  type: KnowledgeEventType;
+  createdAt: string;
+  actor?: string;
+  target?: string;
+  metadata?: Record<string, unknown>;
+}
+/** The four deep sub-question kinds a research driver raises to drive depth. */
+type DeepQuestionKind = 'comparative' | 'mechanism' | 'gap' | 'contradiction';
+/**
+ * A deep sub-question the research driver folds into the worker's next prompt.
+ *
+ * Lives here, next to the other record types, because it is persisted state:
+ * `addressed` is the half of the completion oracle that cannot be recomputed
+ * from the claim ledger alone, so a run that loses it reports "complete" for
+ * questions nobody ever answered.
+ */
+interface DeepQuestion {
+  kind: DeepQuestionKind;
+  text: string;
+  /** sha256-derived stable id, so "addressed" can be tracked across rounds. */
+  id: string;
+  /** Claim id(s) this question interrogates (for contradiction/mechanism kinds). */
+  claimIds: string[];
+  /** True once a later round's evidence addressed it. */
+  addressed: boolean;
+  /** The round this question was raised in. */
+  raisedRound: number;
+}
+/** One live tracked claim exposed by the research-driving API. */
+interface TrackedClaim {
+  id: string;
+  /** The claim text as first extracted (kept for prompts/audit). */
+  text: string;
+  /** Canonical hosts of the INDEPENDENT sources that assert this claim. */
+  supportingHosts: Set<string>;
+  /** Source URIs that assert this claim (provenance; may share a host). */
+  supportingUris: string[];
+  /** Claim ids this claim was found to CONTRADICT (and vice versa). */
+  contradicts: Set<string>;
+  /**
+   * CONTESTED = a contradiction the loop surfaced but could not resolve to a
+   * single supported claim. A contested claim counts as "settled enough to be
+   * done" (we report the disagreement) even with < 2 independent sources.
+   */
+  contested: boolean;
+  firstSeenRound: number;
+}
+/**
+ * JSON-safe form of a tracked claim stored in a research claim ledger.
+ *
+ * The live `TrackedClaim` contract retains its published `Set` fields.
+ * Durable records use sorted arrays because `JSON.stringify` turns a `Set`
+ * into `{}`, which would erase every corroboration count and contradiction.
+ */
+interface ResearchClaimRecord {
+  id: string;
+  text: string;
+  supportingHosts: string[];
+  supportingUris: string[];
+  contradicts: string[];
+  contested: boolean;
+  firstSeenRound: number;
+}
+/** Immutable identity of one exact version of an original source URI. */
+interface ResearchSourceVersion {
+  /** Canonical source-registry id for this URI and content hash. */
+  sourceId: KnowledgeId;
+  /** The URI supplied before the source was copied into the raw-source store. */
+  uri: string;
+  /** SHA-256 of the exact submitted source text. */
+  contentHash: string;
+}
+/**
+ * One immutable claim extraction observed while a source is being verified.
+ *
+ * An observation is deliberately separate from `ResearchClaimRecord`: source
+ * verification happens before source registration, and a process can die in
+ * between. The observation is durable immediately, but it contributes support
+ * to a claim only after its expected registry id, original URI, and content hash
+ * appear together in the ledger's independently confirmed `registeredSources` set.
+ */
+interface ResearchClaimEvidence {
+  /** Stable identity of this claim/source/contradiction observation. */
+  id: string;
+  claimId: string;
+  text: string;
+  /** Canonical source-registry id expected for this source version. */
+  sourceId: KnowledgeId;
+  sourceUri: string;
+  /** SHA-256 of the exact source text from which this observation was extracted. */
+  sourceContentHash: string;
+  /** Existing claim this observation directly contradicts, when reported. */
+  contradictsClaimId?: string;
+  firstSeenRound: number;
+}
+/**
+ * The durable record of one research run's belief state: which claims were
+ * extracted, how independently each is supported, which contradict which, and
+ * which deep sub-questions are still open.
+ *
+ * `id` names the run — one knowledge base can host several, and they must not
+ * overwrite each other, so the store addresses ledgers by this id.
+ */
+interface ResearchClaimLedger {
+  /** Persistent contract version; version 2 binds evidence to source content. */
+  schemaVersion: 2;
+  id: string;
+  /** The research goal this ledger accumulated evidence for. */
+  goal?: string;
+  /** ISO timestamp of the last write. */
+  updatedAt: string;
+  /** How many rounds the driver has folded steer for. */
+  rounds: number;
+  /**
+   * Highest round durably announced before its synchronous question-generation
+   * step began. Greater than `rounds` only while a round needs crash recovery.
+   */
+  preparedRounds?: number;
+  /**
+   * Extracted evidence, including observations whose source registration has
+   * not yet been confirmed. Pending observations never count toward claims.
+   */
+  claimEvidence: ResearchClaimEvidence[];
+  /** Exact source-registry identities confirmed after their raw bytes were stored. */
+  registeredSources: ResearchSourceVersion[];
+  claims: ResearchClaimRecord[];
+  questions: DeepQuestion[];
+}
+interface KnowledgeRelease {
+  id: string;
+  candidateId: string;
+  createdAt: string;
+  promoted: boolean;
+  scorecard?: unknown;
+  runRecordIds?: string[];
+  metadata?: Record<string, unknown>;
+}
+//#endregion
+export { TrackedClaim as A, ResearchClaimEvidence as C, SourceAnchor as D, ResearchSourceVersion as E, SourceRecord as O, KnowledgeWriteParseResult as S, ResearchClaimRecord as T, KnowledgeRelation as _, KnowledgeBaseCandidate as a, KnowledgeUnit as b, KnowledgeEventType as c, KnowledgeGraphNode as d, KnowledgeId as f, KnowledgePolicy as g, KnowledgePage as h, KNOWLEDGE_EVENT_TYPES as i, SourceRegistry as k, KnowledgeGraph as l, KnowledgeLintFinding as m, DeepQuestion as n, KnowledgeClaim as o, KnowledgeIndex as p, DeepQuestionKind as r, KnowledgeEvent as s, ClaimRef as t, KnowledgeGraphEdge as u, KnowledgeRelease as v, ResearchClaimLedger as w, KnowledgeWriteBlock as x, KnowledgeSearchResult as y };
+//# sourceMappingURL=types-BOfmvDe-.d.ts.map

package/dist/{types-DcCCzreS.d.ts.map → types-BOfmvDe-.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"types-DcCCzreS.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";KAAY;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ;EACA;EACA;EACA;EACA;EACA,UAAU;;EAEV;;EAEA;EACA,WAAW;EACX;;UAGe;EACf;EACA,SAAS;;UAGM;EACf;EACA;EACA;;UAGe;EACf,IAAI;EACJ;EACA,MAAM;EACN;EACA;EACA,WAAW;;UAGI;EACf,UAAU;EACV,UAAU;EACV;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ;EACA;EACA,SAAS;EACT,YAAY;EACZ;EACA;EACA,WAAW;EACX;;UAGe;EACf,IAAI;EACJ;EACA;EACA;EACA,aAAa;EACb;EACA;EACA;;UAGe;EACf,IAAI;EACJ;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf,QAAQ;EACR,QAAQ;EACR;EACA;;UAGe;EACf,OAAO;EACP,OAAO;;UAGQ;EACf;EACA;EACA,SAAS;EACT,OAAO;EACP,OAAO;;UAGQ;EACf,MAAM;;;;;;;EAON;;EAEA;;;;;;;;EAQA;EACA;EACA;EACA;;UAGe;EACf;EAUA;EACA;EACA;EACA,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ,OAAO;EACP;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf;EACA;;UAGe;EACf,QAAQ;EACR;;KAGU;UAUK;EACf;EACA,MAAM;EACN;EACA;EACA;EACA,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA;EACA;EACA,WAAW"}
+{"version":3,"file":"types-BOfmvDe-.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";KAAY;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ;EACA;EACA;EACA;EACA;EACA,UAAU;;EAEV;;EAEA;EACA,WAAW;EACX;;UAGe;EACf;EACA,SAAS;;UAGM;EACf;EACA;EACA;;UAGe;EACf,IAAI;EACJ;EACA,MAAM;EACN;EACA;EACA,WAAW;;UAGI;EACf,UAAU;EACV,UAAU;EACV;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ;EACA;EACA,SAAS;EACT,YAAY;EACZ;EACA;EACA,WAAW;EACX;;UAGe;EACf,IAAI;EACJ;EACA;EACA;EACA,aAAa;EACb;EACA;EACA;;UAGe;EACf,IAAI;EACJ;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf,QAAQ;EACR,QAAQ;EACR;EACA;;UAGe;EACf,OAAO;EACP,OAAO;;UAGQ;EACf;EACA;EACA,SAAS;EACT,OAAO;EACP,OAAO;;UAGQ;EACf,MAAM;;;;;;;EAON;;EAEA;;;;;;;;EAQA;EACA;EACA;EACA;;UAGe;EACf;EAUA;EACA;EACA;EACA,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ,OAAO;EACP;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf;EACA;;UAGe;EACf,QAAQ;EACR;;;;;;;;;;cAWW;KAWD,6BAA6B;UAExB;EACf;EACA,MAAM;EACN;EACA;EACA;EACA,WAAW;;;KAID;;;;;;;;;UAUK;EACf,MAAM;EACN;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIe;EACf;;EAEA;;EAEA,iBAAiB;;EAEjB;;EAEA,aAAa;;;;;;EAMb;EACA;;;;;;;;;UAUe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;UAIe;;EAEf,UAAU;;EAEV;;EAEA;;;;;;;;;;;UAYe;;EAEf;EACA;EACA;;EAEA,UAAU;EACV;;EAEA;;EAEA;EACA;;;;;;;;;;UAWe;;EAEf;EACA;;EAEA;;EAEA;;EAEA;;;;;EAKA;;;;;EAKA,eAAe;;EAEf,mBAAmB;EACnB,QAAQ;EACR,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA;EACA;EACA,WAAW"}

package/dist/viz/index.d.ts

@@ -1,4 +1,4 @@
-import { c as KnowledgeGraphNode, o as KnowledgeGraph, s as KnowledgeGraphEdge } from "../types-DcCCzreS.js";
+import { d as KnowledgeGraphNode, l as KnowledgeGraph, u as KnowledgeGraphEdge } from "../types-BOfmvDe-.js";
 //#region src/viz/index.d.ts
 interface KnowledgeVizNode extends KnowledgeGraphNode {
   degree: number;

package/docs/architecture.md

@@ -28,6 +28,38 @@ Product apps own domain policies, provider accounts, vector stores, source adapt
 
 Core does not own a D1 schema or fleet dispatcher. Apps wire `KbStore` and `KnowledgeDiscoveryDispatcher` to their tenancy, queue, budget, auth, and sandbox systems.
 
+## On-disk layout
+
+`new FileSystemKbStore({ root })` is the explicit knowledge-base-root form and owns everything under `<root>/.agent-knowledge/`.
+The published `new FileSystemKbStore(directory)` form remains a direct record directory, so upgrading does not silently move an existing store.
+When that string is the canonical `<root>/.agent-knowledge` directory, both forms use the root's one mutation lock; retaining the path must not create a second lock for the same files.
+
+| Path | Record |
+| --- | --- |
+| `.agent-knowledge/index.json` | the built knowledge index (`writeKnowledgeIndex` writes it through this store) |
+| `.agent-knowledge/events.json` | the knowledge event log, including one `research.iteration` per research-loop round |
+| `.agent-knowledge/claim-ledgers/<id>.json` | one research run's claim ledger — corroboration counts, contradiction edges, open deep questions |
+| `.agent-knowledge/sources.json` | the immutable source registry |
+| `.agent-knowledge/mutation.lock.durable`, `mutation-epoch.json`, `file-transactions/` | the cross-process mutation lock and its crash-recovery state |
+
+The root is also the directory `withKnowledgeMutation` locks, so every record above is written under one lock and one epoch.
+There is exactly one writer per file: a second index writer alongside this one is a defect, not a variation.
+
+A claim ledger is the one record several writers legitimately share — a resumed run beside a live one, or several workers researching one goal in parallel.
+They reach it through `mergeClaimLedger(id, merge)`, which holds the mutation lock across the read, the merge, and the write, so no writer can build its record from a value another writer has already replaced.
+`putClaimLedger` writes the whole record and is correct only for a single writer.
+The combining rule is `mergeClaimLedgers`: support and contradiction edges union, `contested` and `addressed` latch on, `firstSeenRound` moves earlier, and every collection is sorted — so the merge is commutative, associative, and idempotent, and the bytes on disk depend on the evidence rather than on scheduling.
+Ledgers for two different goals refuse to merge (`ClaimLedgerGoalConflictError`) rather than pooling unrelated evidence into one corroboration count.
+The live driver exposes the published Set-based `TrackedClaim`; the ledger stores a separate `ResearchClaimRecord` with sorted arrays so JSON serialization cannot erase those sets.
+Source verification snapshots the proposal and persists a `ResearchClaimEvidence` observation containing the expected registry id, original URI, and full content hash; that observation cannot affect claim support or completion by itself.
+After the exact submitted bytes are durable, `runVerifiedResearchLoop` passes the resulting `SourceRecord` to `commitSources`.
+The ledger materializes only observations whose complete source identity matches a confirmed record, so reusing one URI for different bytes cannot activate the wrong claims and a crash on either side resumes safely.
+Unversioned URI-only ledgers cannot prove which bytes produced their observations; reads and writes fail with `ClaimLedgerMigrationRequiredError` and preserve the original file for an explicit archive-and-reverify migration.
+Before synchronous question generation, the persistent driver records `preparedRounds`; a resume reconstructs and checkpoints any prepared round whose questions were interrupted, and the loop publishes its `research.iteration` event only after that checkpoint succeeds.
+
+Every write in this layer goes through `durable-fs` (`writeFileDurable`, `writeJsonDurableWithinRoot`) — temp file, fsync, atomic rename, fsync parent, through `O_NOFOLLOW` descriptors anchored via `/proc/self/fd` so a directory swapped for a symlink mid-write cannot redirect it outside the root.
+These are exported from the package entrypoint; consumers that keep their own journals should use them rather than reimplement them.
+
 ## Runtime Loop
 
 1. Normalize sources into immutable source records.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-knowledge",
-  "version": "6.1.11",
+  "version": "7.0.0",
   "description": "Build, search, evaluate, and improve source-backed knowledge bases.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {

package/dist/ids-DRqPZ42_.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ids-DRqPZ42_.js","names":[],"sources":["../src/ids.ts"],"sourcesContent":["import { createHash } from 'node:crypto'\n\nexport function sha256(text: string): string {\n  return createHash('sha256').update(text).digest('hex')\n}\n\nexport function slugify(input: string): string {\n  const out = input\n    .trim()\n    .toLowerCase()\n    .normalize('NFKD')\n    .replace(/[\\u0300-\\u036f]/g, '')\n    .replace(/[^a-z0-9\\u4e00-\\u9fff]+/g, '-')\n    .replace(/^-+|-+$/g, '')\n  return out || 'untitled'\n}\n\nexport function stableId(prefix: string, content: string): string {\n  return `${prefix}_${sha256(content).slice(0, 16)}`\n}\n"],"mappings":";;AAEA,SAAgB,OAAO,MAAsB;CAC3C,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK;AACvD;AAEA,SAAgB,QAAQ,OAAuB;CAQ7C,OAPY,MACT,KAAK,CAAC,CACN,YAAY,CAAC,CACb,UAAU,MAAM,CAAC,CACjB,QAAQ,oBAAoB,EAAE,CAAC,CAC/B,QAAQ,4BAA4B,GAAG,CAAC,CACxC,QAAQ,YAAY,EACd,KAAK;AAChB;AAEA,SAAgB,SAAS,QAAgB,SAAyB;CAChE,OAAO,GAAG,OAAO,GAAG,OAAO,OAAO,CAAC,CAAC,MAAM,GAAG,EAAE;AACjD"}