@unson/brainbase-mcp 0.21.2 → 0.22.0

package/dist/meeting-minutes-lineage-http.js

@@ -0,0 +1,221 @@
+import { assertSameOrigin, LocalWebHttpError, readJsonObjectBody, requestUrl, writeHttpError, writeJson, } from './local-web-security.js';
+import { MeetingMinutesLineageError, } from './meeting-minutes-lineage.js';
+/** HTTP seam mounted beside the native `/api/meeting-minutes` routes. */
+export const MEETING_MINUTES_LINEAGE_HTTP_VERSION = 'brainbase.meeting-minutes-lineage-http.v1';
+export const MEETING_MINUTES_LINEAGE_HTTP_PREFIX = '/api/meeting-minutes-lineage';
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+export function createMeetingMinutesLineageHttpHandler(options) {
+    if (!options?.store || typeof options.store.readByMinutesVersion !== 'function'
+        || typeof options.store.readByTarget !== 'function')
+        throw new TypeError('a complete lineage store is required');
+    if (typeof options.resolveAccess !== 'function')
+        throw new TypeError('resolveAccess is required');
+    const basePath = normalizeBasePath(options.basePath);
+    const bodyLimitBytes = options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES;
+    if (!Number.isInteger(bodyLimitBytes) || bodyLimitBytes <= 0)
+        throw new TypeError('bodyLimitBytes must be a positive integer');
+    return async (request, response) => {
+        const path = requestUrl(request).pathname;
+        if (path !== basePath && !path.startsWith(`${basePath}/`))
+            return false;
+        try {
+            const access = await options.resolveAccess(request);
+            if (!access || typeof access.principal !== 'string' || access.principal.trim() === '') {
+                throw new LocalWebHttpError(403, 'authorization_denied', 'A trusted principal is required');
+            }
+            const route = routeFor(path, basePath, request.method);
+            if (!route) {
+                writeJson(response, 404, { error: { code: 'not_found', message: 'Lineage route was not found' } });
+                return true;
+            }
+            const body = request.method === 'GET' ? undefined : await readJsonObjectBody(request, bodyLimitBytes);
+            if (request.method !== 'GET')
+                assertSameOrigin(request);
+            if (route.write) {
+                if (options.assertWriteAllowed)
+                    await options.assertWriteAllowed(request, access);
+            }
+            const actor = route.write
+                ? await (options.resolveActor?.(request, access) ?? { type: 'person', id: access.principal })
+                : undefined;
+            const result = await execute(route, body, access, actor);
+            writeJson(response, result.statusCode, result.body);
+        }
+        catch (error) {
+            if (error instanceof LocalWebHttpError)
+                writeHttpError(response, error);
+            else if (error instanceof MeetingMinutesLineageError) {
+                const status = lineageStatus(error.code);
+                writeJson(response, status, { error: { code: error.code, message: publicLineageMessage(error) } });
+            }
+            else {
+                writeJson(response, 500, { error: { code: 'internal_error', message: 'Meeting minutes lineage request failed' } });
+            }
+        }
+        return true;
+    };
+    async function execute(route, body, access, actor) {
+        switch (route.kind) {
+            case 'candidate_read': {
+                requireMethod(route.method, 'GET');
+                const candidate = await options.store.readCandidate(route.candidateId, access);
+                if (!candidate)
+                    return { statusCode: 404, body: { error: { code: 'not_found', message: 'Candidate was not found' } } };
+                return { statusCode: 200, body: candidate };
+            }
+            case 'by_version': {
+                requireMethod(route.method, 'POST');
+                return { statusCode: 200, body: await options.store.readByMinutesVersion(requireBody(body).reference, access) };
+            }
+            case 'by_target': {
+                requireMethod(route.method, 'POST');
+                return { statusCode: 200, body: await options.store.readByTarget(requireBody(body).target, access) };
+            }
+            case 'candidate_create': {
+                requireMethod(route.method, 'POST');
+                const value = requireBody(body);
+                const request = {
+                    id: value.id,
+                    idempotencyKey: stringValue(value.idempotencyKey ?? value.idempotency_key, 'idempotencyKey'),
+                    actor: requireTrustedActor(actor),
+                    evidence: value.evidence,
+                    kind: value.kind,
+                    proposal: value.proposal,
+                    epistemicStatus: value.epistemicStatus,
+                    access,
+                };
+                const candidate = await options.store.createCandidate(request);
+                return { statusCode: 201, body: candidate };
+            }
+            case 'candidate_confirm': {
+                requireMethod(route.method, 'POST');
+                const value = requireBody(body);
+                const request = {
+                    id: value.id,
+                    idempotencyKey: stringValue(value.idempotencyKey ?? value.idempotency_key, 'idempotencyKey'),
+                    candidateId: route.candidateId,
+                    actor: requireTrustedActor(actor),
+                    evidenceDigest: value.evidenceDigest,
+                    access,
+                };
+                return { statusCode: 201, body: await options.store.confirmCandidate(request) };
+            }
+            case 'candidate_adopt': {
+                requireMethod(route.method, 'POST');
+                const value = requireBody(body);
+                const request = {
+                    id: value.id,
+                    idempotencyKey: stringValue(value.idempotencyKey ?? value.idempotency_key, 'idempotencyKey'),
+                    candidateId: route.candidateId,
+                    actor: requireTrustedActor(actor),
+                    access,
+                };
+                const adoption = route.targetKind === 'judgment'
+                    ? await options.store.adoptJudgment(request)
+                    : await options.store.adoptTask(request);
+                return { statusCode: 201, body: adoption };
+            }
+            case 'correction': {
+                requireMethod(route.method, 'POST');
+                const value = requireBody(body);
+                const request = {
+                    id: value.id,
+                    idempotencyKey: stringValue(value.idempotencyKey ?? value.idempotency_key, 'idempotencyKey'),
+                    previousVersion: value.previousVersion,
+                    replacementVersion: value.replacementVersion,
+                    actor: requireTrustedActor(actor),
+                    reason: value.reason,
+                    access,
+                };
+                return { statusCode: 201, body: await options.store.markCorrection(request) };
+            }
+            default:
+                throw new LocalWebHttpError(404, 'not_found', 'Lineage route was not found');
+        }
+    }
+}
+function routeFor(pathname, basePath, method) {
+    if (pathname === `${basePath}/by-version`)
+        return { kind: 'by_version', method: method ?? '', write: false };
+    if (pathname === `${basePath}/by-target`)
+        return { kind: 'by_target', method: method ?? '', write: false };
+    if (pathname === `${basePath}/candidates`)
+        return { kind: 'candidate_create', method: method ?? '', write: true };
+    if (pathname === `${basePath}/corrections`)
+        return { kind: 'correction', method: method ?? '', write: true };
+    if (!pathname.startsWith(`${basePath}/candidates/`))
+        return undefined;
+    const segments = pathname.slice(`${basePath}/candidates/`.length).split('/').map(decodePathSegment);
+    if (segments.some((segment) => segment === undefined || segment === ''))
+        return undefined;
+    const candidateId = segments[0];
+    if (segments.length === 1)
+        return { kind: 'candidate_read', method: method ?? '', candidateId, write: false };
+    if (segments.length === 2 && segments[1] === 'confirm')
+        return { kind: 'candidate_confirm', method: method ?? '', candidateId, write: true };
+    if (segments.length === 3 && segments[1] === 'adopt' && (segments[2] === 'judgment' || segments[2] === 'task')) {
+        return { kind: 'candidate_adopt', method: method ?? '', candidateId, targetKind: segments[2], write: true };
+    }
+    return undefined;
+}
+function normalizeBasePath(path) {
+    const value = (path ?? MEETING_MINUTES_LINEAGE_HTTP_PREFIX).trim().replace(/\/+$/u, '');
+    if (!value.startsWith('/') || value === '')
+        throw new TypeError('basePath must be an absolute path');
+    return value;
+}
+function decodePathSegment(value) {
+    try {
+        const decoded = decodeURIComponent(value);
+        return decoded === '' || decoded.includes('/') ? undefined : decoded;
+    }
+    catch {
+        return undefined;
+    }
+}
+function requireBody(body) {
+    if (!body)
+        throw new LocalWebHttpError(400, 'invalid_json', 'Request body is required');
+    return body;
+}
+function requireMethod(actual, expected) {
+    if (actual !== expected)
+        throw new LocalWebHttpError(405, 'method_not_allowed', `Use ${expected}`);
+}
+function stringValue(value, label) {
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new LocalWebHttpError(422, 'invalid_input', `${label} is required`);
+    return value;
+}
+function requireTrustedActor(value) {
+    if (!value || (value.type !== 'person' && value.type !== 'agent' && value.type !== 'service' && value.type !== 'system')
+        || typeof value.id !== 'string' || value.id.trim() === '') {
+        throw new LocalWebHttpError(403, 'authorization_denied', 'A trusted actor is required');
+    }
+    return { type: value.type, id: value.id.trim() };
+}
+function lineageStatus(code) {
+    switch (code) {
+        case 'invalid_input': return 422;
+        case 'not_found':
+        case 'source_not_found':
+        case 'target_unavailable': return 404;
+        case 'authorization_denied': return 403;
+        case 'revision_conflict': return 409;
+        case 'provider_unavailable': return 503;
+        case 'integrity_mismatch':
+        case 'corrupt_record':
+        case 'readback_mismatch':
+        case 'source_unavailable': return 500;
+        default: return 500;
+    }
+}
+function publicLineageMessage(error) {
+    if (error.code === 'provider_unavailable' || error.code === 'source_unavailable' || error.code === 'target_unavailable') {
+        return 'Meeting minutes lineage provider is unavailable';
+    }
+    if (error.code === 'corrupt_record' || error.code === 'integrity_mismatch' || error.code === 'readback_mismatch') {
+        return 'Meeting minutes lineage record could not be verified';
+    }
+    return error.message;
+}

package/dist/meeting-minutes-lineage-lifecycle.d.ts

@@ -0,0 +1,58 @@
+import { type NativeMeetingMinutesVersionRecord } from './meeting-minutes-lineage-adapters.js';
+import { type MinutesLineageAccess, type MinutesLineageActor, type MinutesLineageCorrection, type MinutesLineageStore, type MinutesVersionReference } from './meeting-minutes-lineage.js';
+/**
+ * Lifecycle bridge between the native minutes save transaction and the
+ * lineage correction ledger.  The native store remains the owner of version
+ * records; this module only records the relationship after a successful
+ * save.
+ */
+export declare const MEETING_MINUTES_LINEAGE_LIFECYCLE_CONTRACT_VERSION: "brainbase.meeting-minutes-lineage-lifecycle.v1";
+export interface MeetingMinutesLineageVersionSavedEvent {
+    /** The exact version that the saved version supersedes. */
+    readonly previousVersion: NativeMeetingMinutesVersionRecord;
+    /** The exact version returned by the native save readback. */
+    readonly replacementVersion: NativeMeetingMinutesVersionRecord;
+    readonly access: MinutesLineageAccess;
+    readonly actor: MinutesLineageActor;
+    readonly reason: string;
+}
+/**
+ * The retry payload intentionally contains no resolved access context.  A
+ * host must re-resolve current authorization before retrying a failed
+ * lineage write; it must never replay a stale authorization decision.
+ */
+export interface MeetingMinutesLineageCorrectionRetry {
+    readonly id: string;
+    readonly idempotencyKey: string;
+    readonly previousVersion: MinutesVersionReference;
+    readonly replacementVersion: MinutesVersionReference;
+    readonly reason: string;
+}
+export interface MeetingMinutesLineageCorrectionHookSuccess {
+    readonly status: 'recorded';
+    readonly correction: MinutesLineageCorrection;
+    readonly retry: MeetingMinutesLineageCorrectionRetry;
+}
+export interface MeetingMinutesLineageCorrectionHookFailure {
+    readonly status: 'failed';
+    readonly retry: MeetingMinutesLineageCorrectionRetry;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+export type MeetingMinutesLineageCorrectionHookResult = MeetingMinutesLineageCorrectionHookSuccess | MeetingMinutesLineageCorrectionHookFailure;
+export interface MeetingMinutesLineageCorrectionHook {
+    /**
+     * Call only after the native minutes save has read back successfully.
+     * Failure is returned as data so the host can show a retry action while
+     * keeping the saved version, adopted target, and Task state unchanged.
+     */
+    onVersionSaved(event: MeetingMinutesLineageVersionSavedEvent): Promise<MeetingMinutesLineageCorrectionHookResult>;
+}
+export interface MeetingMinutesLineageCorrectionHookOptions {
+    readonly store: Pick<MinutesLineageStore, 'markCorrection'>;
+    /** Organizations may preserve provider-specific source provenance here. */
+    readonly referenceFor?: (record: NativeMeetingMinutesVersionRecord) => MinutesVersionReference;
+}
+export declare function createMeetingMinutesLineageCorrectionHook(options: MeetingMinutesLineageCorrectionHookOptions): MeetingMinutesLineageCorrectionHook;

package/dist/meeting-minutes-lineage-lifecycle.js

@@ -0,0 +1,146 @@
+import { createHash } from 'node:crypto';
+import { nativeMeetingMinutesVersionReference, } from './meeting-minutes-lineage-adapters.js';
+import { MeetingMinutesLineageError, } from './meeting-minutes-lineage.js';
+/**
+ * Lifecycle bridge between the native minutes save transaction and the
+ * lineage correction ledger.  The native store remains the owner of version
+ * records; this module only records the relationship after a successful
+ * save.
+ */
+export const MEETING_MINUTES_LINEAGE_LIFECYCLE_CONTRACT_VERSION = 'brainbase.meeting-minutes-lineage-lifecycle.v1';
+export function createMeetingMinutesLineageCorrectionHook(options) {
+    if (!options?.store || typeof options.store.markCorrection !== 'function') {
+        throw new TypeError('store.markCorrection is required');
+    }
+    const referenceFor = options.referenceFor ?? nativeMeetingMinutesVersionReference;
+    return {
+        async onVersionSaved(event) {
+            const retry = buildRetry(event, referenceFor);
+            try {
+                validateVersionSavedEvent(event, retry);
+                const correction = await options.store.markCorrection({
+                    id: retry.id,
+                    idempotencyKey: retry.idempotencyKey,
+                    previousVersion: retry.previousVersion,
+                    replacementVersion: retry.replacementVersion,
+                    actor: event.actor,
+                    reason: retry.reason,
+                    access: event.access,
+                });
+                return { status: 'recorded', correction, retry };
+            }
+            catch (error) {
+                return { status: 'failed', retry, error: publicLifecycleError(error) };
+            }
+        },
+    };
+}
+function buildRetry(event, referenceFor) {
+    // Build the key from both full exact references, rather than a transport
+    // request key.  A host retry after a network failure therefore cannot
+    // create a second correction by choosing a different request key.
+    let previousVersion;
+    let replacementVersion;
+    try {
+        previousVersion = referenceFor(event.previousVersion);
+    }
+    catch {
+        previousVersion = invalidReference('previous');
+    }
+    try {
+        replacementVersion = referenceFor(event.replacementVersion);
+    }
+    catch {
+        replacementVersion = invalidReference('replacement');
+    }
+    const pairDigest = digestJson({ previousVersion, replacementVersion });
+    const idempotencyKey = `meeting-minutes:correction:${pairDigest}`;
+    return {
+        id: idempotencyKey,
+        idempotencyKey,
+        previousVersion,
+        replacementVersion,
+        reason: typeof event?.reason === 'string' ? event.reason : '',
+    };
+}
+function validateVersionSavedEvent(event, retry) {
+    if (!event || typeof event !== 'object')
+        throw new MeetingMinutesLineageError('invalid_input', 'A saved version event is required');
+    if (!event.previousVersion || !event.replacementVersion) {
+        throw new MeetingMinutesLineageError('invalid_input', 'Both previous and replacement versions are required');
+    }
+    requireRecordString(event.previousVersion.meeting_id, 'previousVersion.meeting_id');
+    requireRecordString(event.previousVersion.minutes_id, 'previousVersion.minutes_id');
+    requireRecordString(event.previousVersion.version_id, 'previousVersion.version_id');
+    requireRecordString(event.replacementVersion.meeting_id, 'replacementVersion.meeting_id');
+    requireRecordString(event.replacementVersion.minutes_id, 'replacementVersion.minutes_id');
+    requireRecordString(event.replacementVersion.version_id, 'replacementVersion.version_id');
+    if (event.previousVersion.meeting_id !== event.replacementVersion.meeting_id
+        || event.previousVersion.minutes_id !== event.replacementVersion.minutes_id) {
+        throw new MeetingMinutesLineageError('invalid_input', 'A correction must use versions from the same minutes document');
+    }
+    if (event.previousVersion.version_id === event.replacementVersion.version_id) {
+        throw new MeetingMinutesLineageError('invalid_input', 'A correction must point to different exact versions');
+    }
+    if (event.replacementVersion.predecessor_version_id !== event.previousVersion.version_id) {
+        throw new MeetingMinutesLineageError('invalid_input', 'The replacement version must directly supersede the previous version');
+    }
+    if (!event.access || typeof event.access.principal !== 'string' || event.access.principal.trim() === '') {
+        throw new MeetingMinutesLineageError('authorization_denied', 'A current lineage access context is required');
+    }
+    if (!event.actor || typeof event.actor.id !== 'string' || event.actor.id.trim() === '') {
+        throw new MeetingMinutesLineageError('invalid_input', 'A saved version actor is required');
+    }
+    if (!event.reason || typeof event.reason !== 'string' || event.reason.trim() === '') {
+        throw new MeetingMinutesLineageError('invalid_input', 'A correction reason is required');
+    }
+    if (!isValidReference(retry.previousVersion) || !isValidReference(retry.replacementVersion)) {
+        throw new MeetingMinutesLineageError('integrity_mismatch', 'Saved versions did not produce exact lineage references');
+    }
+}
+function isValidReference(value) {
+    return Boolean(value && typeof value.meetingId === 'string' && value.meetingId.trim()
+        && typeof value.minutesId === 'string' && value.minutesId.trim()
+        && typeof value.versionId === 'string' && value.versionId.trim()
+        && (value.contentDigest === null || typeof value.contentDigest === 'string')
+        && value.provenance && typeof value.provenance.providerKind === 'string'
+        && typeof value.provenance.providerId === 'string');
+}
+function invalidReference(label) {
+    return {
+        meetingId: '',
+        minutesId: '',
+        versionId: `invalid-${label}`,
+        contentDigest: null,
+        locator: null,
+        provenance: { providerKind: '', providerId: '' },
+    };
+}
+function requireRecordString(value, label) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new MeetingMinutesLineageError('invalid_input', `${label} is required`);
+    }
+    return value;
+}
+function publicLifecycleError(error) {
+    if (error instanceof MeetingMinutesLineageError) {
+        return { code: error.code, message: error.message };
+    }
+    return {
+        code: 'provider_unavailable',
+        message: 'The minutes version was saved, but its lineage correction could not be recorded. Retry after the lineage provider is available.',
+    };
+}
+function digestJson(value) {
+    return `sha256:${createHash('sha256').update(canonicalJson(value), 'utf8').digest('hex')}`;
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    return `{${Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+        .join(',')}}`;
+}