@unson/brainbase-mcp 0.43.0 → 0.44.1

package/dist/meeting-minutes-context-receipt.js

@@ -0,0 +1,280 @@
+import { createHash } from 'node:crypto';
+// Keep the persisted schema identifier byte-for-byte compatible with the
+// existing Unson service.  The package export has its own version constant.
+export const MEETING_MINUTES_CONTEXT_RECEIPT_VERSION = 'meeting_minutes_context_receipt.v1';
+export const MEETING_MINUTES_CONTEXT_RECEIPT_MAX_BYTES = 128 * 1024;
+export class MeetingMinutesContextReceiptError extends Error {
+    code;
+    statusCode;
+    details;
+    constructor(code, message, statusCode = 400, details = {}) {
+        super(message);
+        this.name = 'MeetingMinutesContextReceiptError';
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+    }
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+}
+export function digestMeetingMinutesContext(value) {
+    return createHash('sha256').update(JSON.stringify(stable(value))).digest('hex');
+}
+function compact(value, depth = 0) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string')
+        return value.slice(0, 4000);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (depth >= 4)
+        return String(value).slice(0, 500);
+    if (Array.isArray(value))
+        return value.slice(0, 50).map((item) => compact(item, depth + 1));
+    if (typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).slice(0, 40).map(([key, item]) => [key, compact(item, depth + 1)]));
+    return String(value).slice(0, 500);
+}
+export function normalizeMeetingMinutesContextIdentity(input = {}) {
+    const identity = {
+        run_id: typeof input.run_id === 'string' ? input.run_id.trim() : '',
+        project_code: typeof input.project_code === 'string' ? input.project_code.trim() : '',
+        transcript_sha256: typeof input.transcript_sha256 === 'string' ? input.transcript_sha256.trim().toLowerCase() : '',
+    };
+    if (!/^[a-zA-Z0-9._:-]{1,200}$/.test(identity.run_id))
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_input_invalid', 'run_id is invalid');
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$/.test(identity.project_code))
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_input_invalid', 'project_code is invalid');
+    if (!/^[a-f0-9]{64}$/.test(identity.transcript_sha256))
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_input_invalid', 'transcript_sha256 must be a lowercase SHA-256 digest');
+    return identity;
+}
+export function normalizeMeetingMinutesRetrievalContext(input = {}) {
+    const retrieval = input.retrieval_context ?? input.retrievalContext ?? {};
+    const raw = retrieval && typeof retrieval === 'object'
+        ? retrieval.mention_candidates ?? retrieval.mentionCandidates ?? retrieval.mentions
+        : undefined;
+    const mentions = (Array.isArray(raw)
+        ? raw.map((candidate) => {
+            if (typeof candidate === 'string')
+                return { surface_form: candidate.trim().slice(0, 160), entity_types: ['person', 'org', 'brand', 'glossary_term'] };
+            if (!candidate || typeof candidate !== 'object')
+                return null;
+            const item = candidate;
+            const surface = String(item.surface_form ?? item.surfaceForm ?? item.text ?? item.term ?? item.value ?? '').trim().slice(0, 160);
+            if (!surface)
+                return null;
+            const rawTypes = item.entity_types ?? item.entityTypes ?? item.types;
+            const types = Array.isArray(rawTypes) ? rawTypes.map((type) => String(type).trim().toLowerCase()).filter(Boolean) : ['person', 'org', 'brand', 'glossary_term'];
+            return { surface_form: surface, entity_types: [...new Set(types)].slice(0, 4) };
+        }).filter((candidate) => Boolean(candidate && typeof candidate === 'object' && 'surface_form' in candidate && candidate.surface_form))
+        : []);
+    const seen = new Set();
+    return {
+        mention_candidates: mentions.filter((mention) => {
+            const key = `${String(mention.surface_form).toLocaleLowerCase('ja-JP')}|${mention.entity_types.join(',')}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        }).slice(0, 12),
+    };
+}
+function flattenEntities(graph) {
+    if (!graph)
+        return [];
+    const entities = graph.entities;
+    if (Array.isArray(entities))
+        return entities.map((item) => compact(item));
+    if (!entities || typeof entities !== 'object')
+        return [];
+    return Object.values(entities).flatMap((items) => Array.isArray(items) ? items.map((item) => compact(item)) : []);
+}
+function normalizeTasks(tasks) {
+    const taskRecord = tasks && !Array.isArray(tasks) ? tasks : null;
+    const items = Array.isArray(tasks)
+        ? tasks
+        : (Array.isArray(taskRecord?.items) ? taskRecord.items : []);
+    return items.filter((task) => task.status !== 'completed').slice(0, 50).map((task) => compact(task));
+}
+function sourceRefs(entities, tasks, minutes) {
+    return [
+        ...entities.map((entity) => ({ type: 'graph_entity', id: entity.id ?? entity.entity_id ?? null })),
+        ...tasks.map((task) => ({ type: 'canonical_task', id: task.id ?? task.task_id ?? null })),
+        ...minutes.map((minute) => ({ type: 'meeting_minutes', id: minute.id ?? minute.entity_id ?? null })),
+    ].filter((item) => Boolean(item.id));
+}
+function approvedMinutes(entities) {
+    return entities
+        .filter((entity) => entity.entity_type === 'meeting_minutes' && Boolean(entity.id ?? entity.entity_id))
+        .slice(0, 3)
+        .map((entity) => ({ id: entity.id ?? entity.entity_id, title: entity.title ?? entity.name ?? null }));
+}
+function boundedReceipt(receipt) {
+    const candidate = structuredClone(receipt);
+    const context = candidate.context;
+    while (Buffer.byteLength(JSON.stringify(candidate), 'utf8') > MEETING_MINUTES_CONTEXT_RECEIPT_MAX_BYTES) {
+        const entities = Array.isArray(context.entities) ? context.entities : [];
+        const tasks = Array.isArray(context.open_tasks) ? context.open_tasks : [];
+        const refs = Array.isArray(context.source_refs) ? context.source_refs : [];
+        if (entities.length)
+            entities.pop();
+        else if (tasks.length)
+            tasks.pop();
+        else if (refs.length)
+            refs.pop();
+        else
+            throw new MeetingMinutesContextReceiptError('meeting_minutes_context_too_large', 'meeting minutes context receipt exceeds 128 KiB', 503);
+    }
+    return candidate;
+}
+async function persistWithRetry(receipt, ports) {
+    const maxAttempts = Math.max(1, Math.min(5, ports.max_attempts ?? 2));
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            const saved = await ports.repository.put(receipt, ports.scope);
+            return saved ?? receipt;
+        }
+        catch (error) {
+            if (!(ports.is_retryable?.(error) ?? Boolean(error?.retryable)) || attempt >= maxAttempts)
+                throw error;
+        }
+    }
+    throw new MeetingMinutesContextReceiptError('persist_failed', 'meeting minutes context receipt could not be persisted', 503);
+}
+export async function createMeetingMinutesContextReceipt(input, ports) {
+    const identity = normalizeMeetingMinutesContextIdentity(input);
+    const retrievalContext = normalizeMeetingMinutesRetrievalContext(input);
+    if (!ports?.actor?.resolve || !ports?.auth?.authorize || !ports?.tenant?.authorize || !ports?.project?.authorize) {
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_invalid_ports', 'actor, auth, tenant, and project ports are required', 500);
+    }
+    if (!ports?.repository?.claimOrReplay || !ports?.repository?.get || !ports?.repository?.put) {
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_invalid_ports', 'repository claimOrReplay, put, and durable get ports are required', 500);
+    }
+    const actor = await ports.actor.resolve({ identity, request: input });
+    await ports.auth.authorize({ actor, identity });
+    await ports.tenant.authorize({ actor, identity });
+    await ports.project.authorize({ actor, identity });
+    const errors = [];
+    const scope = ports.scope ?? null;
+    const receiptId = `mmctx_${digestMeetingMinutesContext({ identity, scope }).slice(0, 32)}`;
+    const fingerprint = digestMeetingMinutesContext({ identity, scope });
+    const claim = await ports.repository.claimOrReplay({
+        receipt_id: receiptId,
+        fingerprint,
+        scope,
+        execute: async () => {
+            let graph = null;
+            let graphRetrieval = null;
+            let graphStatus = 'unavailable';
+            let graphFetched = false;
+            let tasks = null;
+            let tasksFetched = false;
+            try {
+                graphFetched = typeof ports.graph === 'function';
+                const graphResult = await ports.graph?.({ identity, retrieval_context: retrievalContext }) ?? null;
+                if (graphResult && typeof graphResult === 'object' && 'graph' in graphResult) {
+                    graph = (graphResult.graph && typeof graphResult.graph === 'object' ? graphResult.graph : null);
+                    graphRetrieval = (graphResult.retrieval && typeof graphResult.retrieval === 'object' ? graphResult.retrieval : null);
+                    graphStatus = typeof graphResult.status === 'string' ? graphResult.status : (graph ? 'resolved' : 'unavailable');
+                    if (Array.isArray(graphResult.errors))
+                        errors.push(...graphResult.errors.filter((item) => Boolean(item && typeof item === 'object')));
+                }
+                else {
+                    graph = graphResult;
+                    graphStatus = graph ? 'resolved' : 'unavailable';
+                }
+            }
+            catch (error) {
+                errors.push({ source: 'graph', code: 'graph_context_unavailable', message: error instanceof Error ? error.message : String(error) });
+            }
+            try {
+                tasksFetched = typeof ports.tasks === 'function';
+                tasks = await ports.tasks?.({ identity }) ?? null;
+            }
+            catch (error) {
+                errors.push({ source: 'tasks', code: 'canonical_tasks_unavailable', message: error instanceof Error ? error.message : String(error) });
+            }
+            const entities = flattenEntities(graph);
+            const openTasks = normalizeTasks(tasks);
+            const minutes = approvedMinutes(entities);
+            const context = {
+                project: entities.filter((entity) => entity.entity_type === 'project'),
+                people: entities.filter((entity) => entity.entity_type === 'person'),
+                organizations: entities.filter((entity) => entity.entity_type === 'org'),
+                decisions: entities.filter((entity) => entity.entity_type === 'decision'),
+                glossary: entities.filter((entity) => entity.entity_type === 'glossary_term'),
+                entities,
+                edges: compact(graph?.edges ?? []),
+                open_tasks: openTasks,
+                source_refs: sourceRefs(entities, openTasks, minutes),
+                approved_minutes_refs: minutes,
+                retrieval: graphRetrieval ?? retrievalContext,
+            };
+            const graphAvailable = graphFetched && Boolean(graph) && graphStatus !== 'unavailable';
+            const tasksAvailable = tasksFetched && tasks !== null;
+            const sourceStatus = {
+                graph: graphAvailable ? graphStatus : 'unavailable',
+                tasks: tasksAvailable ? 'resolved' : 'unavailable',
+            };
+            // Empty is a positive result only when both host sources were fetched
+            // successfully. Missing ports and unavailable responses must remain
+            // observable as unavailable/partial rather than confirmed_empty.
+            const status = !graphAvailable && !tasksAvailable
+                ? 'unavailable'
+                : errors.length || !graphAvailable || !tasksAvailable
+                    ? 'partial'
+                    : (entities.length || openTasks.length) ? 'resolved' : 'confirmed_empty';
+            const base = {
+                schema_version: MEETING_MINUTES_CONTEXT_RECEIPT_VERSION,
+                receipt_id: receiptId,
+                identity,
+                status,
+                source_status: sourceStatus,
+                searched_scope: {
+                    project_code: identity.project_code,
+                    entity_types: ['project', 'person', 'org', 'brand', 'decision', 'glossary_term', 'document'],
+                    entity_limit: 80,
+                    task_limit: 50,
+                    approved_minutes_limit: 3,
+                },
+                resolved_at: (ports.now ?? (() => new Date()))().toISOString(),
+                context,
+                errors,
+            };
+            const bounded = boundedReceipt({ ...base, checksum: digestMeetingMinutesContext(base) });
+            const receipt = { ...bounded, checksum: digestMeetingMinutesContext({ ...bounded, checksum: undefined }) };
+            return persistWithRetry(receipt, ports);
+        },
+    });
+    const persisted = claim.receipt;
+    const readback = await ports.repository.get(persisted.receipt_id, ports.scope);
+    if (!readback || readback.checksum !== persisted.checksum) {
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_readback_mismatch', 'meeting minutes context receipt readback did not match the persisted receipt', 503, { receipt_id: persisted.receipt_id });
+    }
+    return readback;
+}
+export async function readMeetingMinutesContextReceipt(receiptId, input, ports) {
+    const identity = normalizeMeetingMinutesContextIdentity(input);
+    if (!ports?.actor?.resolve || !ports?.auth?.authorize || !ports?.tenant?.authorize || !ports?.project?.authorize) {
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_invalid_ports', 'actor, auth, tenant, and project ports are required', 500);
+    }
+    const actor = await ports.actor.resolve({ identity, request: input });
+    await ports.auth.authorize({ actor, identity });
+    await ports.tenant.authorize({ actor, identity });
+    await ports.project.authorize({ actor, identity });
+    if (!ports?.repository?.get) {
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_invalid_ports', 'repository get port is required', 500);
+    }
+    const receipt = await ports.repository.get(receiptId, ports.scope);
+    if (!receipt)
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_receipt_not_found', 'meeting minutes context receipt was not found', 404);
+    if (JSON.stringify(receipt.identity) !== JSON.stringify(identity))
+        throw new MeetingMinutesContextReceiptError('meeting_minutes_context_identity_mismatch', 'meeting minutes context receipt identity does not match', 409);
+    return receipt;
+}

package/dist/meeting-source-sync.d.ts

@@ -0,0 +1,89 @@
+export declare const MEETING_SOURCE_SYNC_VERSION: "brainbase.meeting-source-sync.v1";
+export declare const SUPPORTED_MEETING_SOURCE_PROVIDERS: readonly ["tactiq", "plaud"];
+export type MeetingSourceProvider = typeof SUPPORTED_MEETING_SOURCE_PROVIDERS[number];
+type UnknownRecord = Record<string, unknown>;
+type MaybePromise<T> = T | Promise<T>;
+export interface MeetingSourceArtifact extends UnknownRecord {
+    readonly provider: MeetingSourceProvider;
+    readonly external_id: string;
+    readonly title: string;
+    readonly meeting_mode: string;
+    readonly started_at: string | null;
+    readonly ended_at: string | null;
+    readonly updated_at: string | null;
+    readonly participants: readonly unknown[];
+    readonly mcp_resource_uri: string;
+    readonly transcript_hash: string | null;
+    readonly has_text: boolean;
+    readonly source_text: string;
+    readonly source_text_kind: string;
+    readonly source_text_length: number;
+    readonly text_preview: string;
+    readonly raw_metadata: UnknownRecord;
+    readonly dedupe_key: string;
+}
+export interface MeetingSourceCluster {
+    readonly source_cluster_id: string;
+    readonly dedupe_key: string;
+    readonly primary_source: MeetingSourceArtifact;
+    readonly supporting_sources: readonly MeetingSourceArtifact[];
+    readonly providers: readonly MeetingSourceProvider[];
+    readonly title: string;
+    readonly started_at: string | null;
+    readonly meeting_mode: string;
+}
+export interface MeetingSourceSyncClaimRequest {
+    readonly idempotency_key: string;
+    /** Fingerprint of the provider/window request, computed before provider I/O. */
+    readonly fingerprint: string;
+    readonly execute: () => MaybePromise<MeetingSourceSyncResult>;
+}
+export interface MeetingSourceSyncClaimResult {
+    readonly status: 'persisted' | 'replayed';
+    readonly result: MeetingSourceSyncResult;
+}
+export interface MeetingSourceSyncPorts {
+    readonly provider: (input: {
+        provider: MeetingSourceProvider;
+        cursor: UnknownRecord;
+        since?: string | null;
+        until?: string | null;
+    }) => MaybePromise<readonly UnknownRecord[]>;
+    readonly sink: {
+        /** Durable idempotency claim enclosing provider fetch, save and retry. */
+        readonly claimOrReplay: (request: MeetingSourceSyncClaimRequest) => MaybePromise<MeetingSourceSyncClaimResult>;
+        findByIdempotencyKey?: (key: string) => MaybePromise<MeetingSourceSyncResult | null>;
+        save: (result: MeetingSourceSyncResult) => MaybePromise<MeetingSourceSyncResult | void>;
+        readonly readback: (idempotencyKey: string) => MaybePromise<MeetingSourceSyncResult | null>;
+    };
+    readonly now?: () => Date;
+    readonly max_attempts?: number;
+    readonly is_retryable?: (error: unknown) => boolean;
+}
+export interface MeetingSourceSyncResult {
+    readonly schema_version: typeof MEETING_SOURCE_SYNC_VERSION;
+    readonly idempotency_key: string;
+    /** Fingerprint of provider/window input; excludes wall-clock ingestion time. */
+    readonly input_fingerprint?: string;
+    readonly provider: MeetingSourceProvider;
+    readonly artifacts: readonly MeetingSourceArtifact[];
+    readonly clusters: readonly MeetingSourceCluster[];
+    readonly cursor: UnknownRecord;
+    readonly synced_at: string;
+    readonly fingerprint: string;
+}
+export declare function stableMeetingSourceHash(value: string): string;
+export declare function transcriptSegmentsToText(value: unknown): unknown;
+export declare function normalizeMeetingSourceArtifact(raw?: UnknownRecord, providerInput?: unknown, _options?: {
+    readonly now?: () => Date;
+}): MeetingSourceArtifact;
+export declare function dedupeMeetingSourceArtifacts(artifacts: readonly MeetingSourceArtifact[]): MeetingSourceCluster[];
+export declare function providerCursorAfterArtifacts(artifacts: readonly MeetingSourceArtifact[], previousCursor?: UnknownRecord): UnknownRecord;
+export declare function runMeetingSourceSync(input: {
+    provider: MeetingSourceProvider;
+    cursor?: UnknownRecord;
+    since?: string | null;
+    until?: string | null;
+    idempotency_key?: string | null;
+}, ports: MeetingSourceSyncPorts): Promise<MeetingSourceSyncResult>;
+export {};

package/dist/meeting-source-sync.js

@@ -0,0 +1,230 @@
+import { createHash } from 'node:crypto';
+export const MEETING_SOURCE_SYNC_VERSION = 'brainbase.meeting-source-sync.v1';
+export const SUPPORTED_MEETING_SOURCE_PROVIDERS = Object.freeze(['tactiq', 'plaud']);
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+}
+export function stableMeetingSourceHash(value) {
+    if (typeof value !== 'string') {
+        throw new TypeError('stableMeetingSourceHash accepts text only; use stableMeetingSourceFingerprint for objects');
+    }
+    return createHash('sha256').update(value).digest('hex');
+}
+function stableMeetingSourceFingerprint(value) {
+    return createHash('sha256').update(JSON.stringify(stable(value))).digest('hex');
+}
+function normalizeWhitespace(value) { return String(value || '').replace(/\s+/g, ' ').trim(); }
+function normalizeMultilineText(value) { return String(value || '').replace(/\r\n/g, '\n').replace(/\r/g, '\n').replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim(); }
+export function transcriptSegmentsToText(value) {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('[') || !trimmed.endsWith(']'))
+        return value;
+    let segments;
+    try {
+        segments = JSON.parse(trimmed);
+    }
+    catch {
+        return value;
+    }
+    if (!Array.isArray(segments) || segments.length === 0)
+        return value;
+    const lines = [];
+    for (const segment of segments) {
+        if (!segment || typeof segment !== 'object' || Array.isArray(segment))
+            return value;
+        const item = segment;
+        const content = typeof item.content === 'string' ? item.content : (typeof item.text === 'string' ? item.text : null);
+        if (content === null)
+            return value;
+        const speaker = normalizeWhitespace(item.speaker ?? item.original_speaker);
+        const line = normalizeWhitespace(content);
+        if (line)
+            lines.push(speaker ? `${speaker}: ${line}` : line);
+    }
+    return lines.length ? lines.join('\n') : value;
+}
+function safeProvider(input) {
+    const provider = String(input ?? '').toLowerCase();
+    if (!SUPPORTED_MEETING_SOURCE_PROVIDERS.includes(provider))
+        throw new Error(`unsupported meeting source provider: ${input}`);
+    return provider;
+}
+function minuteBucket(value) {
+    if (!value)
+        return '';
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return value.slice(0, 16);
+    date.setSeconds(0, 0);
+    return date.toISOString().slice(0, 16);
+}
+function participantKey(participants) {
+    return participants.map((participant) => normalizeWhitespace(typeof participant === 'string' ? participant : participant?.name ?? participant?.email ?? participant?.id).toLowerCase()).filter(Boolean).sort().join('|');
+}
+function inferMeetingMode(raw) {
+    const explicit = String(raw.meeting_mode ?? raw.mode ?? raw.kind ?? '').toLowerCase();
+    if (['online', 'offline', 'call'].includes(explicit))
+        return explicit;
+    if (raw.calendar_event_id || raw.conference_url || raw.meet_url || raw.zoom_url)
+        return 'online';
+    if (raw.phone_number || raw.call_id || raw.is_call)
+        return 'call';
+    if (raw.location && !raw.conference_url)
+        return 'offline';
+    return 'unknown';
+}
+function sourcePriority(artifact) {
+    if (artifact.meeting_mode === 'online' && artifact.provider === 'tactiq')
+        return 100;
+    if (['offline', 'call'].includes(artifact.meeting_mode) && artifact.provider === 'plaud')
+        return 100;
+    if (artifact.provider === 'tactiq')
+        return 70;
+    if (artifact.provider === 'plaud')
+        return 60;
+    return 10;
+}
+function completenessScore(artifact) {
+    return (artifact.has_text ? 4 : 0) + (artifact.started_at ? 2 : 0) + (artifact.ended_at ? 1 : 0) + (artifact.participants.length ? 1 : 0) + (artifact.title ? 1 : 0) + (artifact.mcp_resource_uri ? 1 : 0);
+}
+export function normalizeMeetingSourceArtifact(raw = {}, providerInput = raw.provider, _options = {}) {
+    const provider = safeProvider(providerInput);
+    const transcript = transcriptSegmentsToText(raw.text ?? raw.transcript ?? raw.transcript_text ?? '');
+    const normalizedText = normalizeMultilineText(transcript);
+    const providerNote = normalizeWhitespace(raw.note_text ?? raw.content ?? raw.markdown ?? raw.summary ?? raw.ai_summary ?? raw.meeting_summary ?? '');
+    const startedAt = typeof (raw.started_at ?? raw.start_time ?? raw.created_at ?? raw.recorded_at) === 'string' ? String(raw.started_at ?? raw.start_time ?? raw.created_at ?? raw.recorded_at) : null;
+    const title = normalizeWhitespace(raw.title ?? raw.meeting_title ?? raw.name ?? 'Untitled meeting source');
+    const participants = Array.isArray(raw.participants) ? raw.participants : [];
+    const resourceUri = String(raw.mcp_resource_uri ?? raw.resource_uri ?? raw.url ?? raw.permalink ?? raw.file_url ?? `${provider}:${raw.id ?? raw.external_id ?? stableMeetingSourceFingerprint(raw).slice(0, 16)}`);
+    const externalId = String(raw.external_id ?? raw.id ?? stableMeetingSourceHash(`${provider}:${resourceUri}`).slice(0, 24));
+    const transcriptHash = normalizedText ? stableMeetingSourceHash(normalizedText) : null;
+    const sourceTextKind = normalizedText ? 'transcript' : (providerNote ? 'provider_note_available' : 'empty');
+    // A wall-clock fallback makes identical provider payloads conflict on a
+    // retry.  Preserve provider/start timestamps and use a stable null when no
+    // source timestamp exists; the sync result's synced_at remains clock-owned.
+    const updatedAtValue = raw.updated_at ?? raw.modified_at ?? raw.created_at ?? startedAt ?? null;
+    const updatedAt = typeof updatedAtValue === 'string' && updatedAtValue.trim() ? updatedAtValue : null;
+    return {
+        provider,
+        external_id: externalId,
+        title,
+        meeting_mode: inferMeetingMode(raw),
+        started_at: startedAt,
+        ended_at: typeof raw.ended_at === 'string' ? raw.ended_at : (typeof raw.end_time === 'string' ? raw.end_time : null),
+        updated_at: updatedAt,
+        participants,
+        mcp_resource_uri: resourceUri,
+        transcript_hash: transcriptHash,
+        has_text: Boolean(normalizedText),
+        source_text: normalizedText,
+        source_text_kind: sourceTextKind,
+        source_text_length: normalizedText.length,
+        text_preview: normalizedText.slice(0, 280),
+        raw_metadata: {
+            calendar_event_id: raw.calendar_event_id ?? null,
+            source_url: raw.url ?? raw.permalink ?? null,
+            slack_permalink: raw.slack_permalink ?? raw.slack_permalink_url ?? null,
+            provider_role: provider === 'tactiq' ? 'online_primary' : 'offline_or_call_primary',
+            source_text_kind: sourceTextKind,
+            provider_note_authoritative: false,
+            provider_note_preview: providerNote ? providerNote.slice(0, 280) : null,
+        },
+        dedupe_key: transcriptHash ? `hash:${transcriptHash}` : `shape:${stableMeetingSourceHash(`${title.toLowerCase()}|${minuteBucket(startedAt)}|${participantKey(participants)}`)}`,
+    };
+}
+export function dedupeMeetingSourceArtifacts(artifacts) {
+    const groups = new Map();
+    for (const artifact of artifacts) {
+        const key = artifact.dedupe_key || `${artifact.provider}:${artifact.external_id}`;
+        groups.set(key, [...(groups.get(key) ?? []), artifact]);
+    }
+    return [...groups.entries()].map(([dedupeKey, members]) => {
+        const sorted = [...members].sort((left, right) => sourcePriority(right) - sourcePriority(left) || completenessScore(right) - completenessScore(left) || String(right.updated_at).localeCompare(String(left.updated_at)));
+        const primary = sorted[0];
+        return {
+            source_cluster_id: `msrc_${stableMeetingSourceHash(`${dedupeKey}:${primary.provider}:${primary.external_id}`).slice(0, 24)}`,
+            dedupe_key: dedupeKey,
+            primary_source: primary,
+            supporting_sources: sorted.slice(1),
+            providers: sorted.map((item) => item.provider),
+            title: primary.title,
+            started_at: primary.started_at,
+            meeting_mode: primary.meeting_mode,
+        };
+    });
+}
+export function providerCursorAfterArtifacts(artifacts, previousCursor = {}) {
+    const latest = [...artifacts].map((artifact) => ({ timestamp: artifact.updated_at || artifact.started_at, external_id: artifact.external_id })).filter((item) => item.timestamp).sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)) || String(a.external_id).localeCompare(String(b.external_id))).at(-1);
+    const updatedSince = [previousCursor.updated_since, latest?.timestamp].filter(Boolean).sort().at(-1) ?? null;
+    return { ...previousCursor, updated_since: updatedSince, last_seen_external_id: latest && updatedSince === latest.timestamp ? latest.external_id : previousCursor.last_seen_external_id ?? null };
+}
+export async function runMeetingSourceSync(input, ports) {
+    const provider = safeProvider(input.provider);
+    const cursor = input.cursor ?? {};
+    if (!ports?.sink?.claimOrReplay || !ports?.sink?.readback || !ports?.sink?.save) {
+        throw new Error('meeting source sync requires durable claimOrReplay, save and readback ports');
+    }
+    // The request key is deterministic without reading the provider.  Provider
+    // I/O therefore runs inside the durable claim and cannot be duplicated by
+    // two workers racing on the same cursor window.
+    const idempotencyKey = input.idempotency_key?.trim()
+        || `meeting-source:${provider}:${stableMeetingSourceFingerprint({ cursor, since: input.since ?? null, until: input.until ?? null })}`;
+    const inputFingerprint = stableMeetingSourceFingerprint({
+        provider,
+        cursor,
+        since: input.since ?? null,
+        until: input.until ?? null,
+    });
+    const claim = await ports.sink.claimOrReplay({
+        idempotency_key: idempotencyKey,
+        fingerprint: inputFingerprint,
+        execute: async () => {
+            const rawArtifacts = await ports.provider({ provider, cursor, since: input.since, until: input.until });
+            const artifacts = rawArtifacts.map((raw) => normalizeMeetingSourceArtifact(raw, provider, { now: ports.now }));
+            const clusters = dedupeMeetingSourceArtifacts(artifacts);
+            const nextCursor = providerCursorAfterArtifacts(artifacts, cursor);
+            // updated_at may be null when the provider does not expose a timestamp;
+            // it is intentionally excluded from a separate identity projection so
+            // a retry at a different wall-clock time keeps the same fingerprint.
+            const fingerprint = stableMeetingSourceFingerprint({ provider, artifacts, clusters, cursor: nextCursor });
+            const result = {
+                schema_version: MEETING_SOURCE_SYNC_VERSION,
+                idempotency_key: idempotencyKey,
+                input_fingerprint: inputFingerprint,
+                provider,
+                artifacts,
+                clusters,
+                cursor: nextCursor,
+                synced_at: (ports.now ?? (() => new Date()))().toISOString(),
+                fingerprint,
+            };
+            const maxAttempts = Math.max(1, Math.min(5, ports.max_attempts ?? 2));
+            let saved = undefined;
+            for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+                try {
+                    saved = await ports.sink.save(result);
+                    break;
+                }
+                catch (error) {
+                    if (!(ports.is_retryable?.(error) ?? Boolean(error?.retryable)) || attempt >= maxAttempts)
+                        throw error;
+                }
+            }
+            return saved ?? result;
+        },
+    });
+    const persisted = claim.result;
+    if (persisted.input_fingerprint && persisted.input_fingerprint !== inputFingerprint) {
+        throw new Error('meeting source sync idempotency conflict');
+    }
+    const readback = await ports.sink.readback(idempotencyKey);
+    if (!readback || readback.fingerprint !== persisted.fingerprint)
+        throw new Error('meeting source sync readback mismatch');
+    return readback;
+}

package/dist/mesh.d.ts

@@ -0,0 +1,58 @@
+/** Portable mesh envelope and host-port contracts. No network or auth dependency. */
+export declare const MESH_CONTRACT_VERSION: "mesh.v1";
+export declare const MESH_ENVELOPE_TYPES: readonly ["query", "response", "ping", "pong", "peer_joined", "peer_left"];
+export type MeshEnvelopeType = typeof MESH_ENVELOPE_TYPES[number];
+export type MeshJson = Record<string, unknown> | unknown[] | string | number | boolean | null;
+export interface MeshEnvelope {
+    id: string;
+    from: string;
+    to: string;
+    type: MeshEnvelopeType;
+    payload: MeshJson;
+    ts: number;
+    nonce: string;
+}
+export interface MeshEnvelopeInput {
+    from: string;
+    to: string;
+    type: MeshEnvelopeType;
+    payload?: MeshJson;
+}
+export declare class MeshContractError extends Error {
+    readonly code = "mesh_contract_invalid";
+    constructor(field: string, message?: string);
+}
+export declare function createMeshEnvelope(input: MeshEnvelopeInput, options?: {
+    now?: number;
+    idFactory?: () => string;
+    nonceFactory?: () => string;
+}): MeshEnvelope;
+export declare function normalizeMeshEnvelope(value: unknown): MeshEnvelope;
+export interface MeshProjectPort {
+    projectId: string;
+    localPath?: string;
+    globInclude?: string[];
+    ports?: Record<string, string | number>;
+}
+export interface MeshNodeProfile {
+    nodeId: string;
+    principalRef: string;
+    roleRank?: number;
+    agentRuntime?: string;
+    projects: MeshProjectPort[];
+}
+export declare function normalizeMeshNodeProfile(value: unknown): MeshNodeProfile;
+export interface MeshQueryRequest {
+    queryId: string;
+    from: string;
+    to: string;
+    question: string;
+    scope?: string;
+}
+export declare function normalizeMeshQueryRequest(value: unknown): MeshQueryRequest;
+export declare function createMeshSendReceipt(queryId: string): {
+    queryId: string;
+    status: 'sent';
+    receipt_kind: 'send_ack';
+    answer_status: 'unknown';
+};