@tangle-network/agent-knowledge 6.1.11 → 6.2.0

package/dist/types-Cd57BPRt.d.ts

@@ -0,0 +1,291 @@
+//#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;
+}
+/**
+ * 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 `sourceUri` appears in the ledger's independently
+ * confirmed `registeredSourceUris` set.
+ */
+interface ResearchClaimEvidence {
+  /** Stable identity of this claim/source/contradiction observation. */
+  id: string;
+  claimId: string;
+  text: string;
+  sourceUri: 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 {
+  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 original source URIs confirmed present in the source registry. */
+  registeredSourceUris: string[];
+  claims: ResearchClaimRecord[];
+  questions: DeepQuestion[];
+}
+interface KnowledgeRelease {
+  id: string;
+  candidateId: string;
+  createdAt: string;
+  promoted: boolean;
+  scorecard?: unknown;
+  runRecordIds?: string[];
+  metadata?: Record<string, unknown>;
+}
+//#endregion
+export { ResearchClaimEvidence as C, SourceRecord as D, SourceAnchor as E, SourceRegistry 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, TrackedClaim 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-Cd57BPRt.d.ts.map

package/dist/{types-DcCCzreS.d.ts.map → types-Cd57BPRt.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-Cd57BPRt.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;;;;;;;;;;;UAYe;;EAEf;EACA;EACA;EACA;;EAEA;EACA;;;;;;;;;;UAWe;EACf;;EAEA;;EAEA;;EAEA;;;;;EAKA;;;;;EAKA,eAAe;;EAEf;EACA,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-Cd57BPRt.js";
 //#region src/viz/index.d.ts
 interface KnowledgeVizNode extends KnowledgeGraphNode {
   degree: number;

package/docs/architecture.md

@@ -28,6 +28,36 @@ 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 first persists a `ResearchClaimEvidence` observation that cannot affect claim support or completion, then `runVerifiedResearchLoop` calls `commitSources` only after the source registry write succeeds.
+The ledger unions those observations with exact confirmed original source URIs and materializes only their intersection, so a crash on either side resumes safely without treating an absent source as evidence or losing a registered source's claim.
+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": "6.2.0",
   "description": "Build, search, evaluate, and improve source-backed knowledge bases.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {