@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/graph-corrections.d.ts

@@ -0,0 +1,157 @@
+import type { CanonicalEdge, CanonicalEntity, RelationshipRecord } from './types.js';
+/**
+ * Owner corrections for the canonical local Graph v2.
+ *
+ * Graph entities and edges are stored without revisions, so every correction
+ * carries the digest of the record it was based on, a one-sentence reason and
+ * leaves an append-only history line. The history line, the Graph change and
+ * the relationships.json projection are committed in one SSOT transaction.
+ */
+export declare const GRAPH_CORRECTION_SCHEMA: "brainbase-graph-correction.v1";
+/** Relative to the data directory. Committed as a sidecar of the canonical SSOT transaction. */
+export declare const GRAPH_CORRECTIONS_FILE = "evidence/graph-corrections.jsonl";
+export declare const GRAPH_CORRECTION_ENTITY_FIELDS: readonly ["name", "aliases", "summary", "validFrom", "validTo"];
+export declare const GRAPH_CORRECTION_PROJECT_FIELDS: readonly ["goal", "status"];
+export declare const GRAPH_CORRECTION_EDGE_FIELDS: readonly ["role", "context", "validTo"];
+export declare const GRAPH_CORRECTION_NEW_EDGE_RELATIONS: readonly ["participates_in", "accountable_for", "member_of"];
+/** MCP tools that read the same graph.json on every call and therefore see a saved correction next time. */
+export declare const GRAPH_CORRECTION_APPLIES_TO: readonly ["search", "get_context", "resolve_entity"];
+export type GraphCorrectionKind = 'update_entity' | 'update_edge' | 'create_edge';
+export type GraphNewEdgeRelation = typeof GRAPH_CORRECTION_NEW_EDGE_RELATIONS[number];
+export interface GraphEntityCorrectionChanges {
+    name?: string;
+    aliases?: string[];
+    summary?: string | null;
+    validFrom?: string | null;
+    validTo?: string | null;
+    /** Projects only. Stored as `metadata.goal`. */
+    goal?: string | null;
+    /** Projects only. Stored as `metadata.status`. */
+    status?: string | null;
+}
+export interface GraphEdgeCorrectionChanges {
+    role?: string | null;
+    context?: string | null;
+    /** Ending a relation is expressed with an end date; relations are never deleted. */
+    validTo?: string | null;
+}
+export interface GraphEdgeCreation {
+    fromId: string;
+    relation: GraphNewEdgeRelation;
+    toId: string;
+    role?: string;
+    context?: string;
+    validFrom?: string;
+}
+export type GraphCorrectionInput = {
+    kind: 'update_entity';
+    entityId: string;
+    expectedDigest: string;
+    reason: string;
+    changes: GraphEntityCorrectionChanges;
+} | {
+    kind: 'update_edge';
+    edgeId: string;
+    expectedDigest: string;
+    reason: string;
+    changes: GraphEdgeCorrectionChanges;
+} | {
+    kind: 'create_edge';
+    reason: string;
+    edge: GraphEdgeCreation;
+};
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface GraphProjectionChange {
+    edgeId: string;
+    relationshipId: string | null;
+    action: 'created' | 'updated' | 'removed' | 'shared_unchanged';
+    beforeDigest: string | null;
+    afterDigest: string | null;
+    /** The projection record as it was before this correction, so a removal stays recoverable. */
+    before: RelationshipRecord | null;
+}
+export interface GraphCorrectionRecord {
+    schema: typeof GRAPH_CORRECTION_SCHEMA;
+    id: string;
+    at: string;
+    kind: GraphCorrectionKind;
+    target: {
+        recordType: 'entity' | 'edge';
+        id: string;
+    };
+    reason: string;
+    changedFields: string[];
+    changes: Record<string, {
+        before: JsonValue;
+        after: JsonValue;
+    }>;
+    beforeDigest: string | null;
+    afterDigest: string;
+    projections: GraphProjectionChange[];
+}
+export interface GraphCorrectionResult {
+    status: 'saved';
+    correction: GraphCorrectionRecord;
+    recordType: 'entity' | 'edge';
+    /** The record as read back from graph.json after the commit. */
+    record: CanonicalEntity | CanonicalEdge;
+    digest: string;
+    readback: {
+        verified: true;
+        digest: string;
+        historyRecorded: true;
+    };
+    appliesTo: readonly string[];
+}
+export type GraphCorrectionErrorKind = 'invalid' | 'not_found' | 'conflict' | 'migration_required' | 'readback_mismatch';
+export declare class GraphCorrectionError extends Error {
+    readonly kind: GraphCorrectionErrorKind;
+    readonly code: string;
+    readonly current?: {
+        recordType: "entity" | "edge";
+        record: CanonicalEntity | CanonicalEdge;
+        digest: string;
+    } | undefined;
+    readonly name = "GraphCorrectionError";
+    constructor(kind: GraphCorrectionErrorKind, code: string, message: string, current?: {
+        recordType: "entity" | "edge";
+        record: CanonicalEntity | CanonicalEdge;
+        digest: string;
+    } | undefined);
+}
+/** SHA-256 over canonical JSON (recursively sorted keys) of one stored record. */
+export declare function graphRecordDigest(record: CanonicalEntity | CanonicalEdge | RelationshipRecord): string;
+/**
+ * Validates an untrusted correction request. Only the fields listed in the
+ * correction contract are accepted; ids, types, relation types, provenance and
+ * deletions are rejected with a specific code.
+ */
+export declare function parseGraphCorrectionInput(value: unknown): GraphCorrectionInput;
+/**
+ * Applies one owner correction to the canonical Graph v2 in `dataDir`.
+ *
+ * The Graph write, the relationships.json projection and the history line in
+ * `evidence/graph-corrections.jsonl` are committed together through
+ * `mutatePersonalOsWithSidecar`, so a crash never leaves a Graph change without
+ * its history line (or the reverse). After the commit the record is read back
+ * and its digest must equal the digest computed before saving.
+ */
+export declare function applyGraphCorrection(dataDir: string, input: unknown, options?: {
+    now?: Date;
+}): Promise<GraphCorrectionResult>;
+export interface GraphCorrectionHistoryIssue {
+    file: typeof GRAPH_CORRECTIONS_FILE;
+    line?: number;
+    reason: string;
+}
+/**
+ * Reads the correction history in append order. A missing file means no
+ * correction has been saved; an unreadable line is reported as an issue and
+ * never silently dropped.
+ */
+export declare function readGraphCorrectionHistory(dataDir: string): Promise<{
+    records: GraphCorrectionRecord[];
+    issues: GraphCorrectionHistoryIssue[];
+}>;