@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/knowledge-adapter.d.ts

@@ -0,0 +1,112 @@
+import { type DecisionAdapterConditions, type DecisionAdapterContext } from './decision-adapter.js';
+/** Common contract for attaching exact judgment conditions to old knowledge records. */
+export declare const KNOWLEDGE_ADAPTER_VERSION: "knowledge-condition-adapter.v2";
+/** A read-only compatibility marker for sidecars written by the v1 adapter. */
+export declare const LEGACY_KNOWLEDGE_ADAPTER_VERSION: "knowledge-condition-adapter.v1";
+export declare const KNOWLEDGE_ADAPTER_SIDECAR: "evidence/knowledge-condition-adapter.json";
+export type KnowledgeRecordKind = 'knowledge_event' | 'knowledge_feedback' | 'candidate' | 'candidate_promotion' | 'graph_maintenance_plan' | 'human_gate_receipt' | 'graph_maintenance_receipt' | 'meeting_bridge_event' | 'meeting_bridge_candidate';
+/** A locator only. The adapter never stores a source record body. */
+export interface LegacyKnowledgeRecordRef {
+    readonly kind: KnowledgeRecordKind;
+    readonly id: string;
+    readonly revision?: string;
+    readonly digest?: string;
+}
+/** A provenance locator only. It is intentionally independent of source ACL. */
+export interface KnowledgeEvidenceReference {
+    readonly kind: string;
+    readonly id: string;
+    readonly revision?: string;
+    readonly digest?: string;
+}
+export interface KnowledgeAdoptionReference {
+    readonly id: string;
+    /** Semantic schema of the host adoption record, not a catalog version. */
+    readonly schema: string;
+    /** Canonical digest of the complete host adoption record. */
+    readonly contentDigest: string;
+}
+export type KnowledgeSourceStatus = 'present' | 'quarantined' | 'retracted' | 'not_found' | 'denied';
+export type KnowledgeConditionStatus = 'recorded' | 'unrecorded' | 'denied' | 'unavailable' | 'integrity_mismatch';
+export type KnowledgeAclStatus = 'allowed' | 'denied' | 'unknown';
+export type KnowledgeAdoptionStatus = 'recorded' | 'unrecorded' | 'denied' | 'unavailable';
+/**
+ * Host-owned providers return metadata and exact locators, never a knowledge
+ * body. The provider is responsible for current ACL and source ownership.
+ */
+export interface LegacyKnowledgeRecordRead {
+    readonly source_status: KnowledgeSourceStatus;
+    readonly acl_status: KnowledgeAclStatus;
+    readonly source?: LegacyKnowledgeRecordRef;
+    readonly provenance?: readonly KnowledgeEvidenceReference[];
+}
+export interface LegacyKnowledgeRecordPort {
+    read(input: {
+        readonly source: LegacyKnowledgeRecordRef;
+        readonly context: DecisionAdapterContext;
+    }): Promise<LegacyKnowledgeRecordRead>;
+}
+/** Read-only boundary for host-owned adoption records. No adoption body crosses this port. */
+export interface KnowledgeAdoptionReadPort {
+    read(input: {
+        readonly source: LegacyKnowledgeRecordRef;
+        readonly context: DecisionAdapterContext;
+    }): Promise<{
+        readonly status: KnowledgeAdoptionStatus;
+        readonly adoption?: KnowledgeAdoptionReference;
+    }>;
+}
+export interface KnowledgeConditionAdapterOptions {
+    readonly dataDir: string;
+    readonly recordPort: LegacyKnowledgeRecordPort;
+    /** Optional host-owned read-only adoption port. It is never used for writes. */
+    readonly adoptionPort?: KnowledgeAdoptionReadPort;
+    readonly sidecarPath?: string;
+}
+export interface KnowledgeConditionAttachOptions {
+    /** Caller supplied idempotency key; source kind/id is the default key. */
+    readonly idempotency_key?: string;
+}
+export interface KnowledgeConditionReadResult {
+    readonly source: LegacyKnowledgeRecordRef;
+    readonly resolved_source?: LegacyKnowledgeRecordRef;
+    readonly source_status: KnowledgeSourceStatus;
+    readonly acl_status: KnowledgeAclStatus;
+    readonly condition_status: KnowledgeConditionStatus;
+    readonly conditions?: DecisionAdapterConditions;
+    readonly provenance: readonly KnowledgeEvidenceReference[];
+    readonly adoption_status: KnowledgeAdoptionStatus;
+    readonly adoption?: KnowledgeAdoptionReference;
+}
+export interface KnowledgeConditionAttachReceipt extends KnowledgeConditionReadResult {
+    readonly binding_id: string;
+    readonly operation: 'created' | 'existing';
+}
+export interface KnowledgeConditionReferenceAdapter {
+    attach(source: LegacyKnowledgeRecordRef, conditions: DecisionAdapterConditions, context: DecisionAdapterContext, options?: KnowledgeConditionAttachOptions): Promise<KnowledgeConditionAttachReceipt>;
+    read(source: LegacyKnowledgeRecordRef, context: DecisionAdapterContext): Promise<KnowledgeConditionReadResult>;
+}
+export type KnowledgeAdapterErrorCode = 'validation_error' | 'authorization_denied' | 'source_unavailable' | 'condition_conflict' | 'condition_not_found' | 'integrity_mismatch' | 'store_corrupt' | 'readback_mismatch';
+export declare class KnowledgeAdapterError extends Error {
+    readonly code: KnowledgeAdapterErrorCode;
+    constructor(code: KnowledgeAdapterErrorCode, message: string);
+}
+/**
+ * Personal canonical implementation. Knowledge records remain owned by the
+ * host provider; this store only keeps exact condition/provenance references in
+ * a transactional sidecar next to the canonical aggregate.
+ */
+export declare class GraphKnowledgeConditionAdapter implements KnowledgeConditionReferenceAdapter {
+    private readonly dataDir;
+    private readonly recordPort;
+    private readonly adoptionPort?;
+    private readonly sidecarPath;
+    constructor(options: KnowledgeConditionAdapterOptions);
+    attach(source: LegacyKnowledgeRecordRef, conditions: DecisionAdapterConditions, context: DecisionAdapterContext, options?: KnowledgeConditionAttachOptions): Promise<KnowledgeConditionAttachReceipt>;
+    read(source: LegacyKnowledgeRecordRef, context: DecisionAdapterContext): Promise<KnowledgeConditionReadResult>;
+    private readSource;
+    private readAdoption;
+    private loadSnapshot;
+    private loadSidecar;
+}
+export declare function createKnowledgeConditionAdapter(options: KnowledgeConditionAdapterOptions): KnowledgeConditionReferenceAdapter;