@unson/brainbase-mcp 0.10.11 → 0.10.13

package/dist/knowledge-lookup.js

@@ -640,6 +640,25 @@ function unsupported(input, action, error) {
         error: { code: error.code, message: error.message },
     };
 }
+function lookupActionVariant(kind, properties, required) {
+    return {
+        type: 'object',
+        properties: {
+            kind: { const: kind },
+            ...properties,
+            required_fields: {
+                type: 'array',
+                minItems: 1,
+                maxItems: MAX_FIELDS,
+                description: 'Must contain the same public field paths as the top-level required_fields.',
+                items: { type: 'string', minLength: 1, maxLength: MAX_FIELD_LENGTH },
+            },
+            why_different: { type: 'string', minLength: 1, maxLength: MAX_HINT_LENGTH },
+        },
+        required: ['kind', ...required],
+        additionalProperties: false,
+    };
+}
 export const knowledgeLookupTools = [{
         name: 'brainbase_knowledge_lookup',
         description: 'Find and read authorized Graph knowledge by purpose. Each call performs one bounded search, read, relation follow, or finish proposal; project hints never change authorization scope.',
@@ -664,57 +683,49 @@ export const knowledgeLookupTools = [{
                 missing_information: { type: 'array', maxItems: MAX_FIELDS, items: { type: 'string', minLength: 1, maxLength: MAX_HINT_LENGTH } },
                 based_on_attempt_ids: { type: 'array', maxItems: MAX_IDS, items: { type: 'string', minLength: 1, maxLength: 300 } },
                 why_different: { type: 'string', minLength: 1, maxLength: MAX_HINT_LENGTH },
+                // Each variant lists its own properties. Codex renders only the oneOf
+                // variants into the model-facing declaration, so properties declared
+                // beside oneOf are invisible and read/finish calls cannot be written.
                 next_action: {
                     type: 'object',
-                    properties: {
-                        kind: { type: 'string', enum: ['search', 'read', 'follow_relation', 'finish'] },
-                        query: { type: 'string', minLength: 1, maxLength: MAX_TEXT_LENGTH },
-                        entity_types: { type: 'array', maxItems: 10, items: { type: 'string', minLength: 1, maxLength: 100 } },
-                        seed_ids: { type: 'array', minItems: 1, maxItems: MAX_IDS, items: { type: 'string', minLength: 1, maxLength: 1_000 } },
-                        entity_id: { type: 'string', minLength: 1, maxLength: 1_000 },
-                        entity_type: { type: 'string', minLength: 1, maxLength: 100 },
-                        required_fields: {
-                            type: 'array',
-                            minItems: 1,
-                            maxItems: MAX_FIELDS,
-                            description: 'Must contain the same public field paths as the top-level required_fields.',
-                            items: { type: 'string', minLength: 1, maxLength: MAX_FIELD_LENGTH },
-                        },
-                        relation: { type: 'string', minLength: 1, maxLength: MAX_RELATION_LENGTH },
-                        direction: { type: 'string', enum: ['incoming', 'outgoing'] },
-                        target_types: { type: 'array', maxItems: 10, items: { type: 'string', minLength: 1, maxLength: 100 } },
-                        why_different: { type: 'string', minLength: 1, maxLength: MAX_HINT_LENGTH },
-                        assessment: { type: 'string', enum: ['sufficient', 'insufficient'] },
-                        status: { type: 'string', enum: ['satisfied', 'unresolved', 'needs_user_input'] },
-                        reference_ids: { type: 'array', maxItems: MAX_IDS, items: { type: 'string', minLength: 1, maxLength: 1_000 } },
-                        field_evidence: {
-                            type: 'array',
-                            maxItems: MAX_FIELDS,
-                            items: {
-                                type: 'object',
-                                properties: {
-                                    field: { type: 'string', minLength: 1, maxLength: MAX_FIELD_LENGTH },
-                                    reference_id: { type: 'string', minLength: 1, maxLength: 1_000 },
-                                    attempt_id: { type: 'string', minLength: 1, maxLength: 300 },
+                    oneOf: [
+                        lookupActionVariant('search', {
+                            query: { type: 'string', minLength: 1, maxLength: MAX_TEXT_LENGTH },
+                            entity_types: { type: 'array', maxItems: 10, items: { type: 'string', minLength: 1, maxLength: 100 } },
+                            seed_ids: { type: 'array', minItems: 1, maxItems: MAX_IDS, items: { type: 'string', minLength: 1, maxLength: 1_000 } },
+                        }, []),
+                        lookupActionVariant('read', {
+                            entity_id: { type: 'string', minLength: 1, maxLength: 1_000 },
+                            entity_type: { type: 'string', minLength: 1, maxLength: 100 },
+                        }, ['entity_id', 'entity_type']),
+                        lookupActionVariant('follow_relation', {
+                            seed_ids: { type: 'array', minItems: 1, maxItems: MAX_IDS, items: { type: 'string', minLength: 1, maxLength: 1_000 } },
+                            relation: { type: 'string', minLength: 1, maxLength: MAX_RELATION_LENGTH },
+                            direction: { type: 'string', enum: ['incoming', 'outgoing'] },
+                            target_types: { type: 'array', maxItems: 10, items: { type: 'string', minLength: 1, maxLength: 100 } },
+                        }, ['seed_ids', 'relation', 'direction']),
+                        lookupActionVariant('finish', {
+                            assessment: { type: 'string', enum: ['sufficient', 'insufficient'] },
+                            status: { type: 'string', enum: ['satisfied', 'unresolved', 'needs_user_input'] },
+                            reference_ids: { type: 'array', maxItems: MAX_IDS, items: { type: 'string', minLength: 1, maxLength: 1_000 } },
+                            field_evidence: {
+                                type: 'array',
+                                maxItems: MAX_FIELDS,
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        field: { type: 'string', minLength: 1, maxLength: MAX_FIELD_LENGTH },
+                                        reference_id: { type: 'string', minLength: 1, maxLength: 1_000 },
+                                        attempt_id: { type: 'string', minLength: 1, maxLength: 300 },
+                                    },
+                                    required: ['field', 'reference_id', 'attempt_id'],
+                                    additionalProperties: false,
                                 },
-                                required: ['field', 'reference_id', 'attempt_id'],
-                                additionalProperties: false,
                             },
-                        },
-                        unresolved_items: { type: 'array', maxItems: MAX_FIELDS, items: { type: 'string', minLength: 1, maxLength: MAX_HINT_LENGTH } },
-                        termination_reason: { type: 'string', minLength: 1, maxLength: MAX_HINT_LENGTH },
-                    },
-                    oneOf: [
-                        { properties: { kind: { const: 'search' } }, required: ['kind'] },
-                        { properties: { kind: { const: 'read' } }, required: ['kind', 'entity_id', 'entity_type'] },
-                        { properties: { kind: { const: 'follow_relation' } }, required: ['kind', 'seed_ids', 'relation', 'direction'] },
-                        {
-                            properties: { kind: { const: 'finish' } },
-                            required: ['kind', 'assessment', 'status', 'reference_ids', 'field_evidence', 'unresolved_items', 'termination_reason'],
-                        },
+                            unresolved_items: { type: 'array', maxItems: MAX_FIELDS, items: { type: 'string', minLength: 1, maxLength: MAX_HINT_LENGTH } },
+                            termination_reason: { type: 'string', minLength: 1, maxLength: MAX_HINT_LENGTH },
+                        }, ['assessment', 'status', 'reference_ids', 'field_evidence', 'unresolved_items', 'termination_reason']),
                     ],
-                    required: ['kind'],
-                    additionalProperties: false,
                 },
             },
             required: ['question', 'target_hint', 'required_fields'],

package/dist/knowledge-promotion.d.ts

@@ -0,0 +1,410 @@
+export declare const KNOWLEDGE_PROMOTION_CONTRACT_VERSION: "knowledge_promotion.v1";
+/** Kept byte-compatible with brainbase-unson so stored hashes and receipts still verify. */
+export declare const NORMALIZED_PROMOTION_SCHEMA_VERSION: "personal_knowledge_normalized.v1";
+export type PromotionApprovalKind = 'personal_share' | 'organization_candidate';
+export type PromotionSourceKind = 'personal_knowledge_v1' | 'organization_candidate';
+export type PromotionStatus = 'pending_owner_approval' | 'pending_org_review' | 'owner_rejected' | 'org_rejected' | 'org_accepted' | 'source_stale';
+export type PromotionDecision = 'approve' | 'reject';
+export type PromotionReviewAction = 'request' | 'owner_consent' | 'organization_review';
+export declare class KnowledgePromotionError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, status?: number, details?: Record<string, unknown>);
+}
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface NormalizedPromotionEntity {
+    id: string;
+    type: string;
+    payload: Record<string, JsonValue>;
+}
+export interface NormalizedPromotionEdge {
+    from_id: string;
+    to_id: string;
+    relation: string;
+    payload: Record<string, JsonValue>;
+}
+export interface NormalizedPromotionPayload {
+    schema_version: typeof NORMALIZED_PROMOTION_SCHEMA_VERSION;
+    kind: 'decision' | 'entity' | 'relation';
+    entity: NormalizedPromotionEntity;
+    edges: NormalizedPromotionEdge[];
+    context_entities: Array<{
+        id: string;
+        type: string;
+    }>;
+    decision_domain?: string;
+    sensitivity: string;
+    role_min: string;
+}
+export interface NormalizedPromotionResult {
+    normalized: NormalizedPromotionPayload;
+    normalized_payload_hash: string;
+    summary: string;
+}
+export declare function promotionSha256(value: unknown): string;
+/** Validate and canonicalize the structured content a person approves for the organization. */
+export declare function normalizePromotionPayload(input: unknown): NormalizedPromotionResult;
+/** Owner consent receipt, identical to brainbase-unson's `pkoc_` receipt. */
+export declare function ownerConsentReceipt(request: {
+    request_id: string;
+    owner_person_id: string | null;
+    owner_decided_by: string | null;
+    owner_decided_at: string | Date | null;
+    normalized_payload_hash: string;
+}): string;
+/** Organization review receipt of a personal share, identical to brainbase-unson's `pkor_` receipt. */
+export declare function organizationReviewReceipt(request: {
+    request_id: string;
+}, normalizedPayloadHash: string, reviewerPersonId: string, reviewedAt: string): string;
+/** Organization approval receipt of an organization candidate. */
+export declare function candidateApprovalReceipt(request: {
+    request_id: string;
+    source: PromotionSourceRef;
+    normalized_payload_hash: string;
+}, reviewerPersonId: string, reviewedAt: string): string;
+export interface PromotionSourceRef {
+    kind: PromotionSourceKind;
+    id: string;
+    version: string;
+    evidence_hash: string;
+}
+export interface PromotionDecisionRecord {
+    action: 'owner_consent' | 'organization_review';
+    decision: PromotionDecision;
+    actor_person_id: string;
+    decided_at: string;
+    receipt_id: string | null;
+    reason: string | null;
+}
+export interface KnowledgePromotionRequest {
+    request_id: string;
+    contract_version: typeof KNOWLEDGE_PROMOTION_CONTRACT_VERSION;
+    approval_kind: PromotionApprovalKind;
+    source: PromotionSourceRef;
+    source_event_ids: string[];
+    organization_id: string;
+    project_code: string;
+    owner_person_id: string | null;
+    requested_by_person_id: string;
+    status: PromotionStatus;
+    revision: number;
+    subject: {
+        type: string;
+        id: string;
+    };
+    sanitized_preview: string | null;
+    preview_hash: string | null;
+    normalized_payload: NormalizedPromotionPayload;
+    normalized_payload_hash: string;
+    normalization_contract_version: typeof NORMALIZED_PROMOTION_SCHEMA_VERSION;
+    owner_decided_by: string | null;
+    owner_decided_at: string | null;
+    owner_consent_receipt_id: string | null;
+    organization_review_receipt_id: string | null;
+    organization_event_id: string | null;
+    graph_entity_id: string | null;
+    decisions: PromotionDecisionRecord[];
+    created_at: string;
+    updated_at: string;
+}
+export interface KnowledgePromotionPrincipal {
+    personId: string;
+    /** The person who acts, when a service acts for `personId`. Defaults to `personId`. */
+    actorPersonId?: string;
+    organizationId: string;
+    projectCodes: string[];
+    role?: string;
+    principalType: 'person' | 'service';
+}
+/** Opaque signed authority. When present, the store records its single use. */
+export interface KnowledgePromotionAuthority {
+    operationId: string;
+    idempotencyKey: string;
+    [key: string]: unknown;
+}
+export interface PromotionContext {
+    tx: unknown;
+    principal: KnowledgePromotionPrincipal;
+}
+export interface PersonalKnowledgeSourceRecord {
+    event_id: string;
+    owner_person_id: string;
+    organization_id: string;
+    body_hash: string;
+    version: string;
+    active: boolean;
+}
+export interface OrganizationCandidateSourceRecord {
+    candidate_id: string;
+    organization_id: string;
+    project_code: string;
+    version: string;
+    active: boolean;
+    evidence_hash: string;
+    source_event_ids?: string[];
+}
+export interface OrganizationCandidateOutcome {
+    candidate_id: string;
+    outcome: 'promoted' | 'rejected';
+    request_id: string;
+    actor_person_id: string;
+    receipt_id: string;
+    graph_entity_id: string | null;
+    organization_event_id: string | null;
+    decided_at: string;
+}
+export interface KnowledgePromotionLineage {
+    lineage_id: string;
+    contract_version: typeof KNOWLEDGE_PROMOTION_CONTRACT_VERSION;
+    approval_kind: PromotionApprovalKind;
+    promotion_request_id: string;
+    source: PromotionSourceRef;
+    source_event_ids: string[];
+    owner_person_id: string | null;
+    organization_id: string;
+    project_code: string;
+    organization_event_id: string;
+    graph_entity_id: string;
+    normalized_payload_hash: string;
+    receipts: {
+        owner_consent_receipt_id: string | null;
+        organization_review_receipt_id: string;
+    };
+    approved_by_person_id: string;
+    sanitization: {
+        raw_copied: false;
+        personal_body_copied: false;
+        sanitized_preview_copied: false;
+    };
+    created_at: string;
+}
+export interface KnowledgePromotionStore {
+    transaction<T>(work: (tx: unknown) => Promise<T>, options?: {
+        principal: KnowledgePromotionPrincipal;
+    }): Promise<T>;
+    /** Insert, or return the existing request with the same `request_id`. */
+    createRequest(request: KnowledgePromotionRequest, ctx: PromotionContext): Promise<KnowledgePromotionRequest>;
+    findRequest(requestId: string, ctx: PromotionContext): Promise<KnowledgePromotionRequest | null>;
+    /** Apply `patch` and increment `revision` only when the stored revision equals `expectedRevision`; otherwise `null`. */
+    updateRequest(requestId: string, patch: Partial<KnowledgePromotionRequest>, options: {
+        expectedRevision: number;
+    }, ctx: PromotionContext): Promise<KnowledgePromotionRequest | null>;
+    createLineage(lineage: KnowledgePromotionLineage, ctx: PromotionContext): Promise<void>;
+    claimAuthorityUse?(use: {
+        operation_id: string;
+        idempotency_key: string;
+        request_id: string;
+        action: PromotionReviewAction;
+        actor_person_id: string;
+        organization_id: string;
+        project_code: string;
+    }, ctx: PromotionContext): Promise<void>;
+}
+export interface KnowledgePromotionSources {
+    readPersonalKnowledgeEvent?(eventId: string, ctx: PromotionContext): Promise<PersonalKnowledgeSourceRecord | null>;
+    readOrganizationCandidate?(candidateId: string, ctx: PromotionContext): Promise<OrganizationCandidateSourceRecord | null>;
+    recordOrganizationCandidateOutcome?(outcome: OrganizationCandidateOutcome, ctx: PromotionContext): Promise<void>;
+}
+export type PromotionReviewDecisionResult = {
+    allowed: true;
+    decider_person_id?: string;
+} | {
+    allowed: false;
+    code: string;
+    status?: number;
+    details?: Record<string, unknown>;
+};
+export interface PromotionReviewInput {
+    action: PromotionReviewAction;
+    approvalKind: PromotionApprovalKind;
+    request: KnowledgePromotionRequest;
+    normalized: NormalizedPromotionPayload;
+    principal: KnowledgePromotionPrincipal;
+    authority: KnowledgePromotionAuthority | null;
+}
+/** Organization-owned review rules (brainbase-organization). */
+export interface PromotionReviewPolicy {
+    authorize(input: PromotionReviewInput, ctx: PromotionContext): Promise<PromotionReviewDecisionResult>;
+}
+export interface KnowledgeEventRecordResult {
+    event_id: string;
+    candidate_id?: string | null;
+    semantic_state?: string;
+    quarantine_reason?: string | null;
+}
+export interface KnowledgePromotionEventSink {
+    recordOrganizationEvent(event: OrganizationKnowledgeEvent, ctx: PromotionContext): Promise<KnowledgeEventRecordResult>;
+    reconcileGraphProjection?(input: {
+        candidate_id: string;
+        graph_entity_id: string;
+        event_id: string;
+        actor_person_id: string;
+        decision_owner_person_id: string;
+    }, ctx: PromotionContext): Promise<void>;
+}
+export interface KnowledgePromotionGraphWriter {
+    commitNormalizedPromotion(mutation: NormalizedGraphMutation, ctx: PromotionContext): Promise<{
+        id: string;
+    } | null>;
+}
+export interface KnowledgePromotionPorts {
+    store: KnowledgePromotionStore;
+    sources: KnowledgePromotionSources;
+    reviewPolicy: PromotionReviewPolicy | null;
+    knowledgeEvents: KnowledgePromotionEventSink;
+    graph: KnowledgePromotionGraphWriter;
+    now?: () => Date;
+}
+export interface PromotionEvidence {
+    contract_version: typeof NORMALIZED_PROMOTION_SCHEMA_VERSION;
+    approval_kind: PromotionApprovalKind;
+    promotion_request_id: string;
+    source_kind: PromotionSourceKind;
+    source_version: string;
+    source_evidence_hash: string;
+    normalized_payload_hash: string;
+    owner_consent_receipt_id: string | null;
+    organization_review_receipt_id: string;
+    source_pointer: {
+        uri: string;
+        digest: string;
+    };
+}
+export interface OrganizationKnowledgeEvent {
+    schema_version: 'knowledge_event.v1';
+    event_id: string;
+    occurred_at: string;
+    captured_at: string;
+    source: {
+        type: string;
+        venue: string;
+        contract_version: string;
+    };
+    subject: {
+        type: string;
+        id: string;
+    };
+    decision?: {
+        statement: JsonValue;
+    };
+    decision_authority: {
+        authorized: true;
+        decider_id: string;
+        domain: string;
+    };
+    applicability_scope: {
+        scope: 'organization';
+        organization_id: string;
+        project_code: string;
+    };
+    permission_snapshot: Record<string, unknown>;
+    source_pointer: {
+        uri: string;
+        digest: string;
+    };
+    body_hash: string;
+    parent_episode_id: string;
+    payload: {
+        summary: string;
+        normalized_kind: string;
+        promotion_evidence: PromotionEvidence;
+    };
+    promotion_evidence: PromotionEvidence;
+    organization_id: string;
+    project_code: string;
+    sensitivity: string;
+    role_min: string;
+    venue: string;
+}
+export interface NormalizedGraphMutation {
+    project_code: string;
+    entity: {
+        id: string;
+        type: string;
+        payload: Record<string, unknown>;
+    };
+    edges: Array<NormalizedPromotionEdge & {
+        payload: Record<string, unknown>;
+    }>;
+    context_entities: Array<{
+        id: string;
+        type: string;
+    }>;
+    role_min: string;
+    sensitivity: string;
+    evidence: PromotionEvidence & {
+        organization_event_id: string;
+        candidate_id: string | null;
+    };
+}
+export declare function buildPromotionEvidence(request: KnowledgePromotionRequest, organizationReviewReceiptId: string): PromotionEvidence;
+/** The organization knowledge event that records the approval. The approval kind is never disguised. */
+export declare function buildOrganizationKnowledgeEvent(request: KnowledgePromotionRequest, normalized: NormalizedPromotionPayload, summary: string, evidence: PromotionEvidence, approverPersonId: string, occurredAt: string): OrganizationKnowledgeEvent;
+/** Graph mutation carrying only normalized content and provenance pointers. */
+export declare function buildNormalizedGraphMutation(request: KnowledgePromotionRequest, normalized: NormalizedPromotionPayload, evidence: PromotionEvidence, eventResult: KnowledgeEventRecordResult, organizationEvent: OrganizationKnowledgeEvent): NormalizedGraphMutation;
+export declare function promotionRequestId(input: {
+    approval_kind: PromotionApprovalKind;
+    source: PromotionSourceRef;
+    project_code: string;
+    normalized_payload_hash: string;
+}): string;
+export declare class KnowledgePromotionService {
+    readonly ports: KnowledgePromotionPorts;
+    private readonly now;
+    constructor(ports: KnowledgePromotionPorts);
+    /** D4: request sharing a Personal Knowledge v1 event owned by the authenticated person. */
+    requestPersonalShare(input: {
+        personal_event_id: string;
+        project_code: string;
+        summary: string;
+        subject?: {
+            type: string;
+            id: string;
+        };
+        normalized_payload: unknown;
+    }, context: {
+        principal: KnowledgePromotionPrincipal;
+        authority?: KnowledgePromotionAuthority | null;
+    }): Promise<KnowledgePromotionRequest>;
+    /** D12: request promoting an organization candidate waiting for the Graph promotion review. */
+    requestOrganizationCandidate(input: {
+        candidate_id: string;
+        project_code: string;
+        normalized_payload: unknown;
+    }, context: {
+        principal: KnowledgePromotionPrincipal;
+        authority?: KnowledgePromotionAuthority | null;
+    }): Promise<KnowledgePromotionRequest>;
+    /** D4: the owner approves or rejects sharing the exact normalized content. */
+    decideOwnerConsent(requestId: string, input: {
+        decision: PromotionDecision;
+        normalized_payload_hash?: string;
+        expected_revision: number;
+    }, context: {
+        principal: KnowledgePromotionPrincipal;
+        authority?: KnowledgePromotionAuthority | null;
+    }): Promise<KnowledgePromotionRequest>;
+    /**
+     * D4: organization review of an owner-approved personal share.
+     * D12: organization approval of an organization candidate.
+     * Only an approval commits the event, the Graph mutation, the lineage, and the request in one transaction.
+     */
+    reviewOrganization(requestId: string, input: {
+        decision: PromotionDecision;
+        reason?: string;
+        expected_revision: number;
+    }, context: {
+        principal: KnowledgePromotionPrincipal;
+        authority?: KnowledgePromotionAuthority | null;
+    }): Promise<KnowledgePromotionRequest>;
+    private requirePolicy;
+    private draftRequest;
+    private authorize;
+    private claimAuthority;
+    private sourceIsCurrent;
+    private recordCandidateOutcome;
+}
+export {};