@unson/brainbase-mcp 0.6.0 → 0.7.0

package/dist/problem-candidates.d.ts

@@ -0,0 +1,149 @@
+import type { FoundationRevisionStore } from './foundation-store.js';
+import type { FoundationAcl, FoundationRevision, FoundationScope } from './ontology-foundation.js';
+/**
+ * Problem candidates are evidence-sidecar records. They are deliberately not
+ * Graph entities: a candidate is a reviewable input to problem selection, not
+ * an approved problem or a canonical fact.
+ */
+export declare const PROBLEM_CANDIDATES_CONTRACT_VERSION: "problem-candidates.v1";
+export declare const PROBLEM_CANDIDATE_CATALOG_VERSION: 1;
+export declare const PROBLEM_CANDIDATES_SIDECAR: "evidence/problem-candidates.json";
+export type ProblemCandidateKind = 'gap' | 'opportunity' | 'threat' | 'uncertainty';
+export type ProblemCandidateStatus = 'candidate' | 'merged' | 'dismissed';
+export type ProblemCandidateSourceKind = 'event' | 'observation' | 'document' | 'decision' | 'import' | 'candidate' | 'evidence';
+export interface ProblemCandidateKnown<T> {
+    readonly status: 'known';
+    readonly value: T;
+}
+export interface ProblemCandidateUnknown {
+    readonly status: 'unknown';
+    readonly reason: string;
+}
+/** Unknown is explicit so missing data cannot become zero, empty, or success. */
+export type ProblemCandidateField<T> = ProblemCandidateKnown<T> | ProblemCandidateUnknown;
+export interface ProblemCandidateSourceRef {
+    readonly id: string;
+    readonly kind: ProblemCandidateSourceKind;
+    /** Optional immutable source digest. Evidence content is never embedded. */
+    readonly digest?: string;
+}
+export interface ProblemCandidateEventInput {
+    readonly id: string;
+    readonly occurredAt: string;
+    readonly recordedAt: string;
+    readonly sourceRefs: readonly ProblemCandidateSourceRef[];
+}
+export interface ProblemCandidateEvent extends ProblemCandidateEventInput {
+    readonly id: string;
+    readonly occurredAt: string;
+    readonly recordedAt: string;
+    readonly sourceRefs: readonly ProblemCandidateSourceRef[];
+}
+/** Exact Objective revision plus its canonical definition digest. */
+export interface ProblemCandidateObjectiveReference extends FoundationRevision {
+    readonly type: 'objective';
+    readonly digest: string;
+}
+export interface ProblemCandidateDeadline {
+    readonly dueAt: string;
+    readonly evaluationAt?: string;
+}
+export interface ProblemCandidateResource {
+    readonly id: string;
+    readonly kind: string;
+    readonly quantity?: number;
+    readonly unit?: string;
+}
+export interface ProblemCandidateInput {
+    readonly id: string;
+    readonly kind: ProblemCandidateKind;
+    readonly statement: string;
+    readonly objectiveRefs: readonly ProblemCandidateObjectiveReference[];
+    readonly event: ProblemCandidateEventInput;
+    readonly observedGap: ProblemCandidateField<string>;
+    readonly opportunity: ProblemCandidateField<string>;
+    readonly threat: ProblemCandidateField<string>;
+    readonly uncertainty: ProblemCandidateField<string>;
+    readonly deadline: ProblemCandidateField<ProblemCandidateDeadline>;
+    readonly expectedEffect: ProblemCandidateField<string>;
+    readonly requiredResources: ProblemCandidateField<readonly ProblemCandidateResource[]>;
+    readonly responsibleId: ProblemCandidateField<string>;
+    readonly ownerScope: FoundationScope;
+    readonly acl: FoundationAcl;
+    /** Only mergeCandidates may set this field. */
+    readonly mergedFrom?: readonly string[];
+    /** Optional creation time; defaults to event.recordedAt. */
+    readonly createdAt?: string;
+    /** Runtime input may carry candidate only; selection states are rejected. */
+    readonly status?: ProblemCandidateStatus;
+}
+export interface ProblemCandidateProvenance {
+    readonly eventIds: readonly string[];
+    readonly sourceRefs: readonly ProblemCandidateSourceRef[];
+    readonly candidateIds: readonly string[];
+}
+export interface ProblemCandidateRecord extends Omit<ProblemCandidateInput, 'mergedFrom' | 'createdAt' | 'status'> {
+    readonly contractVersion: typeof PROBLEM_CANDIDATES_CONTRACT_VERSION;
+    readonly status: ProblemCandidateStatus;
+    readonly mergedFrom: readonly string[];
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly provenance: ProblemCandidateProvenance;
+    readonly payloadDigest: string;
+}
+export interface ProblemCandidateQuery {
+    readonly ownerScope?: FoundationScope;
+    readonly responsibleId?: string;
+    readonly status?: ProblemCandidateStatus;
+}
+export interface ProblemCandidateMergeInput extends ProblemCandidateInput {
+    readonly sourceCandidateIds: readonly string[];
+}
+export interface ProblemCandidateStoreContext {
+    /** Identity and optional scope must come from a trusted caller boundary. */
+    readonly principal: string;
+    readonly scope?: FoundationScope;
+}
+export type ProblemCandidateEvidenceOperation = 'save' | 'read';
+/**
+ * Trusted current-access boundary for source evidence. Candidate ACLs are not
+ * evidence ACLs: every source reference, including roots reached through a
+ * merge, must be authorized by this provider before candidate text is exposed.
+ * The provider must fail closed when a source is missing or its digest is no
+ * longer readable for the principal.
+ */
+export interface ProblemCandidateEvidenceAccessProvider {
+    authorize(input: {
+        readonly operation: ProblemCandidateEvidenceOperation;
+        readonly context: ProblemCandidateStoreContext;
+        readonly source: ProblemCandidateSourceRef;
+    }): void | boolean | Promise<void | boolean>;
+}
+export type ProblemCandidateStoreErrorCode = 'invalid_input' | 'not_found' | 'revision_conflict' | 'event_conflict' | 'authorization_denied' | 'scope_violation' | 'unsupported_graph' | 'corrupt_record' | 'readback_mismatch';
+export declare class ProblemCandidateStoreError extends Error {
+    readonly code: ProblemCandidateStoreErrorCode;
+    constructor(code: ProblemCandidateStoreErrorCode, message: string);
+}
+export interface ProblemCandidateStore {
+    saveCandidate(input: ProblemCandidateInput, context: ProblemCandidateStoreContext): Promise<ProblemCandidateRecord>;
+    /** Alias kept explicit for callers that name the resource in the method. */
+    saveProblemCandidate(input: ProblemCandidateInput, context: ProblemCandidateStoreContext): Promise<ProblemCandidateRecord>;
+    mergeCandidates(input: ProblemCandidateMergeInput, context: ProblemCandidateStoreContext): Promise<ProblemCandidateRecord>;
+    readCandidate(id: string, context: ProblemCandidateStoreContext): Promise<ProblemCandidateRecord | null>;
+    listCandidates(query: ProblemCandidateQuery | undefined, context: ProblemCandidateStoreContext): Promise<readonly ProblemCandidateRecord[]>;
+}
+/**
+ * Validates, clones, and freezes a candidate input. The function is also a
+ * pure contract surface for providers that want to validate before storage.
+ */
+export declare function normalizeProblemCandidate(input: ProblemCandidateInput): ProblemCandidateInput;
+/** Returns validation without throwing, useful for contract fixtures. */
+export declare function validateProblemCandidate(input: ProblemCandidateInput): {
+    readonly valid: boolean;
+    readonly issues: readonly string[];
+};
+export declare function createProblemCandidateStore(options: {
+    readonly dataDir: string;
+    readonly foundationStore: FoundationRevisionStore;
+    readonly evidenceAccessProvider: ProblemCandidateEvidenceAccessProvider;
+}): ProblemCandidateStore;