@unson/brainbase-mcp 0.28.0 → 0.29.0

package/dist/canonical-document-writer.d.ts

@@ -0,0 +1,140 @@
+declare const SOURCE_CLASS = "owning_repo";
+declare const CONTENT_TYPE = "team_document";
+type Revision = string | number;
+export interface CanonicalDocumentResolution {
+    status?: unknown;
+    source_class?: unknown;
+    content_type?: unknown;
+    project_code?: unknown;
+    canonical_location?: {
+        repository?: string;
+        [key: string]: unknown;
+    } | null;
+    [key: string]: unknown;
+}
+export interface CanonicalDocumentSaveInput {
+    project_code?: unknown;
+    resolution?: CanonicalDocumentResolution | null;
+    content?: unknown;
+    path?: unknown;
+    repository_path?: unknown;
+    base_hash?: unknown;
+    expected_hash?: unknown;
+    base_revision?: unknown;
+    expected_revision?: unknown;
+    idempotency_key?: unknown;
+    access?: unknown;
+    [key: string]: unknown;
+}
+export interface CanonicalDocumentWriteRequest {
+    project_code: string;
+    path: string;
+    content: string;
+    content_hash: string;
+    base_hash: string | null;
+    base_revision: string;
+    idempotency_key: string;
+    request_fingerprint: string;
+    resolution: CanonicalDocumentResolution;
+    access: unknown;
+}
+export interface CanonicalDocumentWriteResult {
+    path?: string;
+    canonical_url?: string | null;
+    revision?: Revision;
+    idempotency_replayed?: boolean;
+    [key: string]: unknown;
+}
+export interface CanonicalDocumentReadResult {
+    path?: string;
+    content?: unknown;
+    content_hash?: unknown;
+    revision?: Revision;
+    canonical_url?: string | null;
+    [key: string]: unknown;
+}
+export interface CanonicalDocumentProvider {
+    write(request: CanonicalDocumentWriteRequest): Promise<CanonicalDocumentWriteResult> | CanonicalDocumentWriteResult;
+    read(request: {
+        project_code: string;
+        path: string;
+        canonical_url: string | null;
+        resolution: CanonicalDocumentResolution;
+        access: unknown;
+    }): Promise<CanonicalDocumentReadResult> | CanonicalDocumentReadResult;
+}
+export interface CanonicalDocumentSaveResult {
+    status: 'saved';
+    project_code: string;
+    source_class: typeof SOURCE_CLASS;
+    content_type: typeof CONTENT_TYPE;
+    path: string;
+    canonical_url: string | null;
+    content_hash: string;
+    revision: string;
+    readback: {
+        path: string;
+        content_hash: string;
+        revision: string;
+        canonical_url: string | null;
+    };
+    search_indexed: 'unknown';
+    idempotency_key: string;
+    idempotency_replayed: boolean;
+    request_fingerprint: string;
+}
+export interface CanonicalDocumentReceiptStore {
+    find?(request: CanonicalDocumentWriteRequest): Promise<{
+        request_fingerprint: string;
+        result: CanonicalDocumentSaveResult;
+    } | null | undefined>;
+    put?(record: CanonicalDocumentWriteRequest & {
+        result: CanonicalDocumentSaveResult;
+    }): Promise<unknown>;
+}
+declare function stableValue(value: unknown): unknown;
+declare function digest(value: string): string;
+export declare class CanonicalDocumentWriterError extends Error {
+    code: string;
+    status: number;
+    details: Record<string, unknown>;
+    constructor(code: string, message: string, status?: number, details?: Record<string, unknown>);
+}
+/**
+ * Canonical document provider contract.
+ *
+ * A provider is intentionally supplied by the caller. It must implement:
+ *   write({ project_code, path, content, base_hash, base_revision,
+ *           idempotency_key, request_fingerprint, resolution, access })
+ *     -> { path?, canonical_url?, revision? }
+ *   read({ project_code, path, canonical_url?, resolution, access })
+ *     -> { path?, content, content_hash?, revision, canonical_url? }
+ *
+ * The provider owns the atomic CAS and durable idempotency boundary. This
+ * adapter validates the request, forwards both CAS values, and verifies the
+ * provider's post-write readback before reporting success.
+ */
+export declare class CanonicalDocumentWriterAdapter {
+    provider: CanonicalDocumentProvider | null;
+    receiptStore: CanonicalDocumentReceiptStore | null;
+    completed: Map<string, {
+        request_fingerprint: string;
+        result: CanonicalDocumentSaveResult;
+    }>;
+    constructor({ provider, receiptStore }?: {
+        provider?: CanonicalDocumentProvider | null;
+        receiptStore?: CanonicalDocumentReceiptStore | null;
+    });
+    save(input?: CanonicalDocumentSaveInput): Promise<CanonicalDocumentSaveResult>;
+    normalizeRequest(input: CanonicalDocumentSaveInput): CanonicalDocumentWriteRequest;
+    assertProvider(): void;
+    assertOwningRepositoryResolution(resolution: CanonicalDocumentResolution | null | undefined, projectCode: string): asserts resolution is CanonicalDocumentResolution;
+    readback(request: CanonicalDocumentWriteRequest, writeResult?: CanonicalDocumentWriteResult): Promise<Omit<CanonicalDocumentSaveResult, 'idempotency_key' | 'idempotency_replayed' | 'request_fingerprint'>>;
+    normalizeProviderError(error: unknown): CanonicalDocumentWriterError;
+}
+export declare function normalizeRepositoryRelativePath(value: unknown): string;
+export declare const canonicalDocumentWriterInternals: {
+    digest: typeof digest;
+    stableValue: typeof stableValue;
+};
+export {};

package/dist/canonical-document-writer.js

@@ -0,0 +1,276 @@
+/**
+ * Saves a team document into its owning repository through a caller-supplied
+ * provider. The adapter validates the request, forwards both CAS values and the
+ * idempotency key, and reports success only after the provider's readback
+ * matches the requested content and write revision.
+ *
+ * Moved unchanged from brainbase-unson server/services/canonical-document-writer-adapter.js
+ * (story-document-and-meeting-source-exits-v1).
+ */
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+const SOURCE_CLASS = 'owning_repo';
+const CONTENT_TYPE = 'team_document';
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (value && typeof value === 'object') {
+        const record = value;
+        return Object.fromEntries(Object.keys(record).sort().map((key) => [key, stableValue(record[key])]));
+    }
+    return value;
+}
+function digest(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function requiredString(value, name) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new CanonicalDocumentWriterError('canonical_document_input_invalid', `${name} is required`, 400, { field: name });
+    }
+    return value.trim();
+}
+function normalizeRevision(value, name) {
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0)
+        return String(value);
+    return requiredString(value, name);
+}
+function errorField(error, field) {
+    return error && typeof error === 'object' ? error[field] : undefined;
+}
+export class CanonicalDocumentWriterError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, status = 400, details = {}) {
+        super(message);
+        this.name = 'CanonicalDocumentWriterError';
+        this.code = code;
+        this.status = status;
+        this.details = details;
+    }
+}
+/**
+ * Canonical document provider contract.
+ *
+ * A provider is intentionally supplied by the caller. It must implement:
+ *   write({ project_code, path, content, base_hash, base_revision,
+ *           idempotency_key, request_fingerprint, resolution, access })
+ *     -> { path?, canonical_url?, revision? }
+ *   read({ project_code, path, canonical_url?, resolution, access })
+ *     -> { path?, content, content_hash?, revision, canonical_url? }
+ *
+ * The provider owns the atomic CAS and durable idempotency boundary. This
+ * adapter validates the request, forwards both CAS values, and verifies the
+ * provider's post-write readback before reporting success.
+ */
+export class CanonicalDocumentWriterAdapter {
+    provider;
+    receiptStore;
+    completed;
+    constructor({ provider = null, receiptStore = null } = {}) {
+        this.provider = provider;
+        this.receiptStore = receiptStore;
+        this.completed = new Map();
+    }
+    async save(input = {}) {
+        const request = this.normalizeRequest(input);
+        this.assertProvider();
+        let durable = null;
+        if (typeof this.receiptStore?.find === 'function') {
+            try {
+                durable = await this.receiptStore.find(request);
+            }
+            catch (error) {
+                if (error?.name === 'CanonicalDocumentWriterError')
+                    throw error;
+                throw new CanonicalDocumentWriterError('canonical_document_receipt_unavailable', 'canonical document write receipt could not be read', 503, { cause: errorField(error, 'code') || errorField(error, 'message') || 'unknown' });
+            }
+        }
+        if (durable) {
+            if (durable.request_fingerprint !== request.request_fingerprint) {
+                throw new CanonicalDocumentWriterError('canonical_document_idempotency_conflict', 'idempotency_key was already used with different document content', 409, { idempotency_key: request.idempotency_key });
+            }
+            return { ...durable.result, idempotency_replayed: true };
+        }
+        const previous = this.completed.get(request.idempotency_key);
+        if (previous) {
+            if (previous.request_fingerprint !== request.request_fingerprint) {
+                throw new CanonicalDocumentWriterError('canonical_document_idempotency_conflict', 'idempotency_key was already used with different document content', 409, { idempotency_key: request.idempotency_key });
+            }
+            return { ...previous.result, idempotency_replayed: true };
+        }
+        const provider = this.provider;
+        let result;
+        try {
+            const writeResult = await provider.write(request);
+            if (!writeResult || typeof writeResult !== 'object' || !writeResult.revision) {
+                throw new CanonicalDocumentWriterError('canonical_document_write_invalid', 'canonical document provider did not return the write revision', 503);
+            }
+            const readback = await this.readback(request, writeResult);
+            result = {
+                ...readback,
+                idempotency_key: request.idempotency_key,
+                idempotency_replayed: Boolean(writeResult.idempotency_replayed),
+                request_fingerprint: request.request_fingerprint,
+            };
+        }
+        catch (error) {
+            throw this.normalizeProviderError(error);
+        }
+        if (typeof this.receiptStore?.put === 'function') {
+            try {
+                await this.receiptStore.put({
+                    ...request,
+                    result,
+                });
+            }
+            catch (error) {
+                throw this.normalizeProviderError(new CanonicalDocumentWriterError('canonical_document_receipt_unavailable', 'canonical document write receipt could not be stored', 503, { cause: errorField(error, 'code') || errorField(error, 'message') || 'unknown' }));
+            }
+        }
+        this.completed.set(request.idempotency_key, {
+            request_fingerprint: request.request_fingerprint,
+            result,
+        });
+        return result;
+    }
+    normalizeRequest(input) {
+        const projectCode = requiredString(input.project_code, 'project_code');
+        const resolution = input.resolution;
+        this.assertOwningRepositoryResolution(resolution, projectCode);
+        const content = input.content;
+        if (typeof content !== 'string' || !content.trim()) {
+            throw new CanonicalDocumentWriterError('canonical_document_input_invalid', 'content is required', 400, { field: 'content' });
+        }
+        const repositoryPath = normalizeRepositoryRelativePath(input.path ?? input.repository_path);
+        const rawBaseHash = input.base_hash ?? input.expected_hash;
+        const baseHash = rawBaseHash === undefined || rawBaseHash === null || rawBaseHash === ''
+            ? null
+            : requiredString(rawBaseHash, 'base_hash');
+        const baseRevision = normalizeRevision(input.base_revision ?? input.expected_revision, 'base_revision');
+        const idempotencyKey = requiredString(input.idempotency_key, 'idempotency_key');
+        const contentHash = digest(content);
+        const fingerprint = digest(JSON.stringify(stableValue({
+            project_code: projectCode,
+            path: repositoryPath,
+            content_hash: contentHash,
+            base_hash: baseHash,
+            base_revision: baseRevision,
+            idempotency_key: idempotencyKey,
+            source_class: SOURCE_CLASS,
+            content_type: CONTENT_TYPE,
+            canonical_location: resolution.canonical_location || null,
+        })));
+        return {
+            project_code: projectCode,
+            path: repositoryPath,
+            content,
+            content_hash: contentHash,
+            base_hash: baseHash,
+            base_revision: baseRevision,
+            idempotency_key: idempotencyKey,
+            request_fingerprint: fingerprint,
+            resolution,
+            access: input.access || null,
+        };
+    }
+    assertProvider() {
+        if (!this.provider || typeof this.provider.write !== 'function' || typeof this.provider.read !== 'function') {
+            throw new CanonicalDocumentWriterError('canonical_document_writer_not_configured', 'canonical document writer is not configured', 503);
+        }
+    }
+    assertOwningRepositoryResolution(resolution, projectCode) {
+        if (!resolution
+            || resolution.status !== 'resolved'
+            || resolution.source_class !== SOURCE_CLASS
+            || resolution.content_type !== CONTENT_TYPE
+            || resolution.project_code !== projectCode) {
+            throw new CanonicalDocumentWriterError('canonical_document_route_invalid', 'team_document must resolve to the owning repository before it can be saved', 422, { required_source_class: SOURCE_CLASS, required_content_type: CONTENT_TYPE });
+        }
+        const expectedRepository = `project:${projectCode}`;
+        const repository = resolution.canonical_location?.repository;
+        if (repository && repository !== expectedRepository) {
+            throw new CanonicalDocumentWriterError('canonical_document_route_invalid', 'resolution repository does not match project_code', 422, { expected_repository: expectedRepository, repository });
+        }
+    }
+    async readback(request, writeResult = {}) {
+        if (!writeResult || typeof writeResult !== 'object') {
+            throw new CanonicalDocumentWriterError('canonical_document_write_invalid', 'canonical document provider returned an invalid write result', 503);
+        }
+        const pathFromWrite = normalizeRepositoryRelativePath(writeResult.path ?? request.path);
+        const readback = await this.provider.read({
+            project_code: request.project_code,
+            path: pathFromWrite,
+            canonical_url: writeResult.canonical_url || null,
+            resolution: request.resolution,
+            access: request.access,
+        });
+        if (!readback || typeof readback !== 'object' || typeof readback.content !== 'string') {
+            throw new CanonicalDocumentWriterError('canonical_document_readback_unavailable', 'canonical document could not be read back after save', 503);
+        }
+        const readbackPath = normalizeRepositoryRelativePath(readback.path ?? pathFromWrite);
+        const readbackHash = digest(readback.content);
+        const declaredReadbackHash = typeof readback.content_hash === 'string' ? readback.content_hash.trim() : null;
+        if (readbackPath !== request.path
+            || (declaredReadbackHash && declaredReadbackHash !== readbackHash)
+            || readbackHash !== request.content_hash
+            || readback.content !== request.content) {
+            throw new CanonicalDocumentWriterError('canonical_document_readback_mismatch', 'canonical document readback does not match the requested content', 502, {
+                path: request.path,
+                expected_content_hash: request.content_hash,
+                actual_content_hash: readbackHash,
+                ...(declaredReadbackHash ? { declared_content_hash: declaredReadbackHash } : {}),
+                actual_path: readbackPath,
+            });
+        }
+        const writeRevision = normalizeRevision(writeResult.revision, 'writeResult.revision');
+        const revision = normalizeRevision(readback.revision, 'readback.revision');
+        if (revision !== writeRevision) {
+            throw new CanonicalDocumentWriterError('canonical_document_readback_revision_mismatch', 'canonical document readback revision does not match the write commit', 502, { expected_revision: writeRevision, actual_revision: revision });
+        }
+        return {
+            status: 'saved',
+            project_code: request.project_code,
+            source_class: SOURCE_CLASS,
+            content_type: CONTENT_TYPE,
+            path: request.path,
+            canonical_url: readback.canonical_url || writeResult.canonical_url || null,
+            content_hash: request.content_hash,
+            revision,
+            readback: {
+                path: readbackPath,
+                content_hash: readbackHash,
+                revision,
+                canonical_url: readback.canonical_url || writeResult.canonical_url || null,
+            },
+            search_indexed: 'unknown',
+        };
+    }
+    normalizeProviderError(error) {
+        if (error instanceof CanonicalDocumentWriterError)
+            return error;
+        const rawStatus = errorField(error, 'status');
+        const status = Number.isInteger(rawStatus) ? rawStatus : 503;
+        const rawCode = errorField(error, 'code');
+        const code = typeof rawCode === 'string' && rawCode
+            ? rawCode
+            : 'canonical_document_writer_failed';
+        return new CanonicalDocumentWriterError(code, status === 409 ? 'canonical document write conflicts with the current version' : 'canonical document writer is unavailable', status, status === 409 ? { provider_code: code } : {});
+    }
+}
+export function normalizeRepositoryRelativePath(value) {
+    const raw = requiredString(value, 'path');
+    if (raw.includes('\0') || raw.includes('\\') || raw.startsWith('/') || raw.startsWith('~') || /^[A-Za-z]:[\\/]/.test(raw)) {
+        throw new CanonicalDocumentWriterError('canonical_document_path_invalid', 'path must be a repository-relative POSIX path', 400, { field: 'path' });
+    }
+    const segments = raw.split('/');
+    if (segments.some((segment) => !segment || segment === '.' || segment === '..')) {
+        throw new CanonicalDocumentWriterError('canonical_document_path_invalid', 'path must not contain empty, dot, or parent segments', 400, { field: 'path' });
+    }
+    const normalized = path.posix.normalize(raw);
+    if (normalized !== raw || normalized === '.' || normalized === '..' || normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
+        throw new CanonicalDocumentWriterError('canonical_document_path_invalid', 'path must be a normalized repository-relative path', 400, { field: 'path' });
+    }
+    return normalized;
+}
+export const canonicalDocumentWriterInternals = { digest, stableValue };

package/dist/knowledge-capture-preview.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Contracts shared by the local knowledge capture and preview adapters.
+ *
+ * The adapter is deliberately provider-agnostic.  Production bootstrap does
+ * not create one; callers must inject an explicit implementation.  This file
+ * only normalizes and validates the boundary so an adapter cannot turn
+ * missing evidence or an unverified version into a successful result.
+ *
+ * Moved unchanged from brainbase-unson server/services/knowledge-capture-preview-adapter.js
+ * (story-document-and-meeting-source-exits-v1).
+ */
+export type KnowledgeVersion = string | {
+    state: string;
+    value: string | null;
+};
+type Details = Record<string, unknown>;
+type Entry = Record<string, unknown>;
+export declare class KnowledgeAIAdapterContractError extends Error {
+    code: string;
+    status: number;
+    details: Details;
+    constructor(message: string, details?: Details);
+}
+export declare function normalizeVersion(value: unknown, field?: string): KnowledgeVersion;
+export declare function versionValue(value: KnowledgeVersion): string | null;
+export declare function normalizeUnknown(value: unknown, field?: string): Array<string | Entry>;
+export declare function normalizeReadback(value: unknown, field?: string): Entry & {
+    state: string;
+    verified: boolean;
+};
+/**
+ * Resolve only explicitly injected adapter methods.  There is intentionally
+ * no environment or default-provider lookup here.
+ */
+export declare function resolveKnowledgeAdapter(adapter: unknown, method: string): ((...args: any[]) => any) | null;
+export declare function normalizeEvidence(value: unknown, { field, allowedReferences, requireExactReference, }?: {
+    field?: string;
+    allowedReferences?: Set<string> | null;
+    requireExactReference?: boolean;
+}): Array<Entry & {
+    id: string | null;
+    version: KnowledgeVersion;
+    source_ref: string | null;
+}>;
+export declare function referenceKey(id: unknown, version: KnowledgeVersion): string;
+export declare function normalizeCitations(value: unknown, { field, allowedReferences, }?: {
+    field?: string;
+    allowedReferences?: Set<string> | null;
+}): Array<Entry & {
+    id: string;
+    version: string;
+}>;
+export declare function validateCaptureProposal(value: unknown, { allowedReferences }?: {
+    allowedReferences?: Set<string> | null;
+}): {
+    proposal: {
+        kind: unknown;
+        summary: unknown;
+        scope: unknown;
+        owner_candidate: unknown;
+        relations: unknown;
+    };
+    evidence: (Entry & {
+        id: string | null;
+        version: KnowledgeVersion;
+        source_ref: string | null;
+    })[];
+    unknown: (string | Entry)[];
+    version: KnowledgeVersion;
+    readback: Entry & {
+        state: string;
+        verified: boolean;
+    };
+};
+export declare function validatePreviewAnswer(value: unknown, { allowedReferences }: {
+    allowedReferences?: Set<string> | null;
+}): {
+    answer: string;
+    citations: (Entry & {
+        id: string;
+        version: string;
+    })[];
+    evidence: (Entry & {
+        id: string | null;
+        version: KnowledgeVersion;
+        source_ref: string | null;
+    })[];
+    exclusions: {
+        [x: string]: unknown;
+    }[];
+    unknown: (string | Entry)[];
+    version: KnowledgeVersion;
+    readback: Entry & {
+        state: string;
+        verified: boolean;
+    };
+};
+export {};

package/dist/knowledge-capture-preview.js

@@ -0,0 +1,236 @@
+/**
+ * Contracts shared by the local knowledge capture and preview adapters.
+ *
+ * The adapter is deliberately provider-agnostic.  Production bootstrap does
+ * not create one; callers must inject an explicit implementation.  This file
+ * only normalizes and validates the boundary so an adapter cannot turn
+ * missing evidence or an unverified version into a successful result.
+ *
+ * Moved unchanged from brainbase-unson server/services/knowledge-capture-preview-adapter.js
+ * (story-document-and-meeting-source-exits-v1).
+ */
+export class KnowledgeAIAdapterContractError extends Error {
+    code;
+    status;
+    details;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = 'KnowledgeAIAdapterContractError';
+        this.code = 'knowledge_ai_adapter_contract_invalid';
+        this.status = 502;
+        this.details = details;
+    }
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function hasOwn(value, key) {
+    return Boolean(value && Object.prototype.hasOwnProperty.call(value, key));
+}
+function fail(message, details = {}) {
+    throw new KnowledgeAIAdapterContractError(message, details);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export function normalizeVersion(value, field = 'version') {
+    if (typeof value === 'string' && value.trim())
+        return value.trim();
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (isRecord(value)) {
+        const state = text(value.state) || text(value.status);
+        if (!state)
+            fail(`${field} must include an explicit state`, { field });
+        return {
+            state,
+            value: typeof value.value === 'string' && value.value.trim()
+                ? value.value.trim()
+                : typeof value.value === 'number' && Number.isFinite(value.value)
+                    ? String(value.value)
+                    : null,
+        };
+    }
+    fail(`${field} is required`, { field });
+}
+export function versionValue(value) {
+    return typeof value === 'string' ? value : null;
+}
+function versionKey(value) {
+    return typeof value === 'string' ? `known:${value}` : `unknown:${value.state}:${value.value || ''}`;
+}
+export function normalizeUnknown(value, field = 'unknown') {
+    if (!Array.isArray(value))
+        fail(`${field} must be an array`, { field });
+    return value.map((entry, index) => {
+        if (typeof entry === 'string' && entry.trim())
+            return entry.trim();
+        if (isRecord(entry))
+            return { ...entry };
+        fail(`${field}[${index}] must be text or an object`, { field, index });
+    });
+}
+export function normalizeReadback(value, field = 'readback') {
+    if (!isRecord(value)) {
+        fail(`${field} is required`, { field });
+    }
+    const state = text(value.state) || text(value.status);
+    if (!state)
+        fail(`${field}.state is required`, { field });
+    if (typeof value.verified !== 'boolean') {
+        fail(`${field}.verified must be explicit`, { field });
+    }
+    return { ...value, state, verified: value.verified };
+}
+/**
+ * Resolve only explicitly injected adapter methods.  There is intentionally
+ * no environment or default-provider lookup here.
+ */
+export function resolveKnowledgeAdapter(adapter, method) {
+    if (typeof adapter === 'function')
+        return adapter;
+    if (!adapter || typeof adapter !== 'object')
+        return null;
+    const candidate = adapter[method];
+    if (typeof candidate === 'function')
+        return candidate.bind(adapter);
+    return null;
+}
+export function normalizeEvidence(value, { field = 'evidence', allowedReferences = null, requireExactReference = false, } = {}) {
+    if (!Array.isArray(value))
+        fail(`${field} must be an array`, { field });
+    return value.map((entry, index) => {
+        if (!isRecord(entry)) {
+            fail(`${field}[${index}] must be an object`, { field, index });
+        }
+        const id = text(entry.id) || text(entry.candidate_id) || null;
+        const sourceRef = text(entry.source_ref) || text(entry.pointer) || text(entry.source) || null;
+        if (requireExactReference && !id) {
+            fail(`${field}[${index}].id is required`, { field, index });
+        }
+        if (!id && !sourceRef) {
+            fail(`${field}[${index}] needs an id or source_ref`, { field, index });
+        }
+        if (!hasOwn(entry, 'version')) {
+            fail(`${field}[${index}].version is required`, { field, index });
+        }
+        const version = normalizeVersion(entry.version, `${field}[${index}].version`);
+        if (allowedReferences && id) {
+            const key = `${id}\u0000${versionKey(version)}`;
+            if (!allowedReferences.has(key)) {
+                fail(`${field}[${index}] references an unavailable candidate`, {
+                    field,
+                    index,
+                    id,
+                    version,
+                });
+            }
+        }
+        return {
+            ...entry,
+            id,
+            version,
+            source_ref: sourceRef,
+        };
+    });
+}
+export function referenceKey(id, version) {
+    return `${text(id) || ''}\u0000${versionKey(version)}`;
+}
+export function normalizeCitations(value, { field = 'citations', allowedReferences, } = {}) {
+    if (!Array.isArray(value))
+        fail(`${field} must be an array`, { field });
+    return value.map((entry, index) => {
+        if (!isRecord(entry)) {
+            fail(`${field}[${index}] must be an object`, { field, index });
+        }
+        const id = text(entry.id) || text(entry.candidate_id);
+        if (!id)
+            fail(`${field}[${index}].id is required`, { field, index });
+        if (!hasOwn(entry, 'version'))
+            fail(`${field}[${index}].version is required`, { field, index });
+        const version = normalizeVersion(entry.version, `${field}[${index}].version`);
+        if (typeof version !== 'string') {
+            fail(`${field}[${index}].version must be an exact value`, { field, index, id });
+        }
+        const key = referenceKey(id, version);
+        if (allowedReferences && !allowedReferences.has(key)) {
+            fail(`${field}[${index}] references a candidate outside the isolated set`, {
+                field,
+                index,
+                id,
+                version,
+            });
+        }
+        return {
+            ...entry,
+            id,
+            version,
+        };
+    });
+}
+export function validateCaptureProposal(value, { allowedReferences = null } = {}) {
+    if (!isRecord(value)) {
+        fail('capture adapter must return an object');
+    }
+    const proposal = isRecord(value.proposal)
+        ? value.proposal
+        : value;
+    for (const field of ['kind', 'summary', 'scope', 'owner_candidate', 'relations']) {
+        if (!hasOwn(proposal, field))
+            fail(`capture proposal.${field} is required`, { field });
+    }
+    const version = normalizeVersion(value.version, 'capture proposal.version');
+    const unknown = normalizeUnknown(value.unknown, 'capture proposal.unknown');
+    const evidence = normalizeEvidence(value.evidence, {
+        field: 'capture proposal.evidence',
+        allowedReferences,
+    });
+    const readback = normalizeReadback(value.readback, 'capture proposal.readback');
+    return {
+        proposal: {
+            kind: proposal.kind,
+            summary: proposal.summary,
+            scope: proposal.scope,
+            owner_candidate: proposal.owner_candidate,
+            relations: proposal.relations,
+        },
+        evidence,
+        unknown,
+        version,
+        readback,
+    };
+}
+export function validatePreviewAnswer(value, { allowedReferences }) {
+    if (!isRecord(value)) {
+        fail('preview adapter must return an object');
+    }
+    const answer = text(value.answer);
+    if (!answer)
+        fail('preview answer is required', { field: 'answer' });
+    const rawCitations = value.citations ?? value.cited_refs ?? value.selected_refs;
+    const citations = normalizeCitations(rawCitations, {
+        field: 'preview citations',
+        allowedReferences,
+    });
+    const unknown = normalizeUnknown(value.unknown, 'preview unknown');
+    const evidence = normalizeEvidence(value.evidence, {
+        field: 'preview evidence',
+        allowedReferences,
+        requireExactReference: true,
+    });
+    const readback = normalizeReadback(value.readback, 'preview readback');
+    const version = normalizeVersion(value.version, 'preview version');
+    const exclusions = Array.isArray(value.exclusions)
+        ? value.exclusions.map((entry) => ({ ...entry }))
+        : [];
+    return {
+        answer,
+        citations,
+        evidence,
+        exclusions,
+        unknown,
+        version,
+        readback,
+    };
+}

package/dist/meeting-source-connection.js

@@ -293,7 +293,16 @@ export class NativeMcpRuntime {
         await this.options.credentials.remove(connection.connectionId);
     }
 }
-/** The SDK's OAuth provider for one connection. It never starts an interactive authorization. */
+/**
+ * Marks this provider as an authorization-code client without a reachable redirect. The SDK
+ * treats a provider with no redirect URL as a non-interactive (client-credentials) client and
+ * then never uses the refresh token, so an expired access token could not be renewed.
+ */
+const NO_INTERACTIVE_REDIRECT = 'urn:brainbase:meeting-source:no-interactive-redirect';
+/**
+ * The SDK's OAuth provider for one connection. It renews tokens with the stored refresh token
+ * and never starts an interactive authorization: that path ends in `reauth_required`.
+ */
 class ConnectionOAuthProvider {
     store;
     connection;
@@ -302,7 +311,7 @@ class ConnectionOAuthProvider {
         this.connection = connection;
     }
     get redirectUrl() {
-        return undefined;
+        return NO_INTERACTIVE_REDIRECT;
     }
     get clientMetadata() {
         return { redirect_uris: [], client_name: 'Brainbase Meeting Source' };

package/dist/meeting-source-integration-catalog.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The meeting source providers Brainbase treats as effective (Tactiq for
+ * online meetings, Plaud.ai for offline recordings and calls), with an
+ * optional live check of their public integration surfaces on integrations.sh.
+ *
+ * Moved unchanged from brainbase-unson server/services/meeting-source/meeting-source-integration-catalog.js
+ * (story-document-and-meeting-source-exits-v1).
+ */
+export interface MeetingSourceCatalogSurface {
+    type: string;
+    transport: string;
+    configured_by: string;
+    confidence: string;
+    purpose: string;
+}
+export interface MeetingSourceCatalogProvider {
+    provider: string;
+    domain: string;
+    label: string;
+    role: string;
+    source_role: string;
+    catalog_source: string;
+    catalog_status: string;
+    surfaces: readonly MeetingSourceCatalogSurface[];
+    auth: {
+        managed_by: string;
+        credential_ref_required: boolean;
+        local_secret_storage: boolean;
+        user_action: string;
+    };
+    notes: readonly string[];
+}
+export interface MeetingSourceUpstreamDetect {
+    ok: boolean;
+    status?: number;
+    found?: unknown[];
+    mcp?: unknown[];
+    integrations_json?: unknown;
+    auth?: unknown[];
+    error?: string;
+}
+export interface MeetingSourceCatalogEntry extends MeetingSourceCatalogProvider {
+    effective: true;
+    upstream: {
+        name: 'integrations.sh';
+        domain: string;
+        detect_url: string;
+        detect_status: 'pending' | 'not_queried';
+    };
+    upstream_detect: MeetingSourceUpstreamDetect | null;
+}
+export interface MeetingSourceCatalog {
+    version: 1;
+    generated_at: string;
+    upstream: {
+        name: 'integrations.sh';
+        base_url: string;
+        purpose: string;
+    };
+    providers: MeetingSourceCatalogEntry[];
+}
+type FetchLike = (url: string, init: {
+    headers: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface MeetingSourceIntegrationCatalogOptions {
+    baseURL?: string;
+    fetchImpl?: FetchLike | null;
+    clock?: () => string;
+}
+export declare class MeetingSourceIntegrationCatalogService {
+    baseURL: string;
+    fetchImpl: FetchLike | null | undefined;
+    clock: () => string;
+    constructor({ baseURL, fetchImpl, clock, }?: MeetingSourceIntegrationCatalogOptions);
+    listCatalog({ includeLiveDetect }?: {
+        includeLiveDetect?: boolean;
+    }): Promise<MeetingSourceCatalog>;
+    getCatalogEntry(provider: unknown, { includeLiveDetect }?: {
+        includeLiveDetect?: boolean;
+    }): Promise<MeetingSourceCatalogEntry>;
+    refreshProvider(provider: unknown): Promise<MeetingSourceCatalogEntry>;
+    detectUpstream(domain: string): Promise<MeetingSourceUpstreamDetect>;
+}
+export declare function createMeetingSourceIntegrationCatalogService(options?: MeetingSourceIntegrationCatalogOptions): MeetingSourceIntegrationCatalogService;
+export {};

package/dist/meeting-source-integration-catalog.js

@@ -0,0 +1,161 @@
+/**
+ * The meeting source providers Brainbase treats as effective (Tactiq for
+ * online meetings, Plaud.ai for offline recordings and calls), with an
+ * optional live check of their public integration surfaces on integrations.sh.
+ *
+ * Moved unchanged from brainbase-unson server/services/meeting-source/meeting-source-integration-catalog.js
+ * (story-document-and-meeting-source-exits-v1).
+ */
+const INTEGRATIONS_SH_BASE_URL = 'https://integrations.sh';
+const MEETING_SOURCE_PROVIDER_CATALOG = Object.freeze({
+    tactiq: Object.freeze({
+        provider: 'tactiq',
+        domain: 'tactiq.io',
+        label: 'Tactiq',
+        role: 'online_primary',
+        source_role: 'online meetings',
+        catalog_source: 'brainbase_override',
+        catalog_status: 'override_required',
+        surfaces: Object.freeze([
+            Object.freeze({
+                type: 'mcp',
+                transport: 'brainbase_runtime',
+                configured_by: 'brainbase_mcp_runtime',
+                confidence: 'manual_override',
+                purpose: 'online meeting transcripts and speaker timeline',
+            }),
+        ]),
+        auth: Object.freeze({
+            managed_by: 'brainbase_runtime',
+            credential_ref_required: true,
+            local_secret_storage: false,
+            user_action: 'provider login is completed outside Mac Companion and stored by Brainbase runtime',
+        }),
+        notes: Object.freeze([
+            'integrations.sh may not detect a published MCP surface yet; Brainbase keeps Tactiq as an effective provider override.',
+            'Calendar data is context only. Tactiq is the primary source for online meetings.',
+        ]),
+    }),
+    plaud: Object.freeze({
+        provider: 'plaud',
+        domain: 'plaud.ai',
+        label: 'Plaud.ai',
+        role: 'offline_or_call_primary',
+        source_role: 'offline recordings, calls, and online meetings without Tactiq',
+        catalog_source: 'brainbase_override',
+        catalog_status: 'override_required',
+        surfaces: Object.freeze([
+            Object.freeze({
+                type: 'mcp',
+                transport: 'brainbase_runtime',
+                configured_by: 'brainbase_mcp_runtime',
+                confidence: 'manual_override',
+                purpose: 'offline recordings, calls, and fallback meeting transcripts',
+            }),
+        ]),
+        auth: Object.freeze({
+            managed_by: 'brainbase_runtime',
+            credential_ref_required: true,
+            local_secret_storage: false,
+            user_action: 'provider login is completed outside Mac Companion and stored by Brainbase runtime',
+        }),
+        notes: Object.freeze([
+            'integrations.sh may not detect a published MCP surface yet; Brainbase keeps Plaud.ai as an effective provider override.',
+            'Calendar data is context only. Plaud.ai is the primary source for offline meetings and calls.',
+        ]),
+    }),
+});
+function nowIso() {
+    return new Date().toISOString();
+}
+function normalizeProvider(provider) {
+    return String(provider || '').trim().toLowerCase();
+}
+function providerEntry(provider) {
+    const key = normalizeProvider(provider);
+    const entry = MEETING_SOURCE_PROVIDER_CATALOG[key];
+    if (!entry) {
+        const error = new Error(`unsupported meeting source provider: ${provider}`);
+        error.statusCode = 404;
+        throw error;
+    }
+    return structuredClone(entry);
+}
+function integrationDetectURL(baseURL, domain) {
+    return `${String(baseURL).replace(/\/$/, '')}/api/${encodeURIComponent(domain)}/detect`;
+}
+export class MeetingSourceIntegrationCatalogService {
+    baseURL;
+    fetchImpl;
+    clock;
+    constructor({ baseURL = INTEGRATIONS_SH_BASE_URL, fetchImpl = globalThis.fetch, clock = nowIso, } = {}) {
+        this.baseURL = baseURL;
+        this.fetchImpl = fetchImpl;
+        this.clock = clock;
+    }
+    async listCatalog({ includeLiveDetect = false } = {}) {
+        const providers = Object.keys(MEETING_SOURCE_PROVIDER_CATALOG);
+        const entries = [];
+        for (const provider of providers) {
+            entries.push(await this.getCatalogEntry(provider, { includeLiveDetect }));
+        }
+        return {
+            version: 1,
+            generated_at: this.clock(),
+            upstream: {
+                name: 'integrations.sh',
+                base_url: this.baseURL,
+                purpose: 'detect public integration surfaces; Brainbase override decides effective meeting-source providers',
+            },
+            providers: entries,
+        };
+    }
+    async getCatalogEntry(provider, { includeLiveDetect = false } = {}) {
+        const entry = providerEntry(provider);
+        return {
+            ...entry,
+            effective: true,
+            upstream: {
+                name: 'integrations.sh',
+                domain: entry.domain,
+                detect_url: integrationDetectURL(this.baseURL, entry.domain),
+                detect_status: includeLiveDetect ? 'pending' : 'not_queried',
+            },
+            upstream_detect: includeLiveDetect ? await this.detectUpstream(entry.domain) : null,
+        };
+    }
+    async refreshProvider(provider) {
+        return this.getCatalogEntry(provider, { includeLiveDetect: true });
+    }
+    async detectUpstream(domain) {
+        if (typeof this.fetchImpl !== 'function') {
+            return {
+                ok: false,
+                error: 'fetch_not_available',
+            };
+        }
+        try {
+            const response = await this.fetchImpl(integrationDetectURL(this.baseURL, domain), {
+                headers: { accept: 'application/json' },
+            });
+            const body = await response.json();
+            return {
+                ok: response.ok,
+                status: response.status,
+                found: body?.found || [],
+                mcp: body?.mcp || [],
+                integrations_json: body?.integrationsJson || null,
+                auth: body?.auth || [],
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error?.message || 'upstream_detect_failed',
+            };
+        }
+    }
+}
+export function createMeetingSourceIntegrationCatalogService(options = {}) {
+    return new MeetingSourceIntegrationCatalogService(options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unson/brainbase-mcp",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Local-first Brainbase judgment OS that lets supported AI agents reuse a user's approved goals, priorities, decisions, and judgment criteria.",
   "type": "module",
   "license": "MIT",
@@ -183,6 +183,18 @@
       "types": "./dist/knowledge-resolution-service.d.ts",
       "import": "./dist/knowledge-resolution-service.js"
     },
+    "./canonical-document-writer": {
+      "types": "./dist/canonical-document-writer.d.ts",
+      "import": "./dist/canonical-document-writer.js"
+    },
+    "./knowledge-capture-preview": {
+      "types": "./dist/knowledge-capture-preview.d.ts",
+      "import": "./dist/knowledge-capture-preview.js"
+    },
+    "./meeting-source-integration-catalog": {
+      "types": "./dist/meeting-source-integration-catalog.d.ts",
+      "import": "./dist/meeting-source-integration-catalog.js"
+    },
     "./knowledge-adapter": {
       "types": "./dist/knowledge-adapter.d.ts",
       "import": "./dist/knowledge-adapter.js"
@@ -439,5 +451,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "b8d86d3e394b94cd77bcfe71e8cb6c8703abce4b"
+  "gitHead": "6a77b6883ff11a89306f168ae2c79a6bb0606b70"
 }