@unson/brainbase-mcp 0.35.0 → 0.37.0

package/dist/canonical-task-service.d.ts

@@ -65,6 +65,7 @@ export interface CanonicalTaskUpdateInput extends JsonRecord {
     waiting_on?: string | null;
     review_at?: string | null;
     source_refs?: unknown[];
+    source_refs_append?: unknown[];
     project_codes?: unknown;
     purpose_label?: string | null;
 }

package/dist/canonical-task-service.js

@@ -24,6 +24,7 @@ const MAX_TITLE_LENGTH = 200;
 const MAX_SEARCH_LENGTH = 200;
 const DEFAULT_LIMIT = 20;
 const MAX_LIMIT = 100;
+const MAX_SOURCE_REFS_APPEND_JSON_DEPTH = 128;
 const RESERVED_IDEMPOTENCY_PREFIXES = ['api:', 'workflow:'];
 const CREATE_FIELDS = new Set([
     'completion_contract',
@@ -49,6 +50,7 @@ const MUTABLE_FIELDS = new Set([
     'waiting_on',
     'review_at',
     'source_refs',
+    'source_refs_append',
     'project_codes',
     'purpose_label',
 ]);
@@ -164,6 +166,90 @@ function normalizeSourceRefs(value) {
         fail('validation_error', 'source_refs must be an array', 400, { field: 'source_refs' });
     return value;
 }
+function isPlainJsonObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertJsonValue(value, field, ancestors = new Set(), depth = 0) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (Number.isFinite(value))
+            return;
+        fail('validation_error', `${field} must contain JSON-serializable values`, 400, { field });
+    }
+    if (typeof value !== 'object') {
+        fail('validation_error', `${field} must contain JSON-serializable values`, 400, { field });
+    }
+    if (depth >= MAX_SOURCE_REFS_APPEND_JSON_DEPTH) {
+        fail('validation_error', `${field} exceeds the maximum JSON nesting depth`, 400, { field });
+    }
+    if (ancestors.has(value)) {
+        fail('validation_error', `${field} must contain JSON-serializable values`, 400, { field });
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        for (const key of Reflect.ownKeys(value)) {
+            if (key === 'length')
+                continue;
+            if (typeof key !== 'string' || !/^(?:0|[1-9]\d*)$/u.test(key)
+                || Number(key) >= value.length
+                || !Object.prototype.propertyIsEnumerable.call(value, key)) {
+                fail('validation_error', `${field} must contain JSON-serializable values`, 400, { field });
+            }
+        }
+        for (let index = 0; index < value.length; index += 1) {
+            if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                fail('validation_error', `${field} must contain JSON-serializable values`, 400, { field });
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor || !('value' in descriptor)) {
+                fail('validation_error', `${field} must contain JSON-serializable values`, 400, { field });
+            }
+            assertJsonValue(descriptor.value, `${field}[${index}]`, ancestors, depth + 1);
+        }
+    }
+    else if (isPlainJsonObject(value)) {
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string' || !Object.prototype.propertyIsEnumerable.call(value, key)) {
+                fail('validation_error', `${field} must contain JSON-serializable values`, 400, { field });
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !('value' in descriptor)) {
+                fail('validation_error', `${field} must contain JSON-serializable values`, 400, { field });
+            }
+            assertJsonValue(descriptor.value, `${field}.${key}`, ancestors, depth + 1);
+        }
+    }
+    else {
+        fail('validation_error', `${field} must contain plain JSON objects`, 400, { field });
+    }
+    ancestors.delete(value);
+}
+function normalizeSourceRefsAppend(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        fail('validation_error', 'source_refs_append must be an array of plain JSON objects', 400, { field: 'source_refs_append' });
+    }
+    // Validate the array container itself so sparse, symbol-keyed, accessor, or
+    // otherwise non-JSON properties cannot bypass the per-reference checks.
+    assertJsonValue(value, 'source_refs_append');
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.prototype.hasOwnProperty.call(value, index)) {
+            fail('validation_error', 'source_refs_append must be an array of plain JSON objects', 400, { field: 'source_refs_append' });
+        }
+        const ref = value[index];
+        const field = `source_refs_append[${index}]`;
+        if (!isPlainJsonObject(ref)) {
+            fail('validation_error', 'source_refs_append must be an array of plain JSON objects', 400, { field: 'source_refs_append' });
+        }
+        assertJsonValue(ref, field);
+    }
+    return value;
+}
 function canonicalize(value) {
     if (Array.isArray(value))
         return value.map(canonicalize);
@@ -178,6 +264,50 @@ function canonicalize(value) {
 function fingerprint(value) {
     return createHash('sha256').update(JSON.stringify(canonicalize(value))).digest('hex');
 }
+/**
+ * Appended source references use code-unit key ordering so the same JSON
+ * object has one fingerprint across runtimes and locale settings. Keep the
+ * existing canonicalizer above unchanged because its fingerprints are already
+ * persisted for older create/update/transition operations.
+ */
+function canonicalizeSourceRefsAppend(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeSourceRefsAppend);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+            .map(([key, entry]) => [key, canonicalizeSourceRefsAppend(entry)]));
+    }
+    return value;
+}
+function sourceRefsAppendFingerprint(value) {
+    return createHash('sha256').update(JSON.stringify(canonicalizeSourceRefsAppend(value))).digest('hex');
+}
+function mergeSourceRefs(existing, additions) {
+    if (existing != null && !Array.isArray(existing)) {
+        fail('validation_error', 'source_refs must be an array', 400, { field: 'source_refs' });
+    }
+    const existingRefs = Array.isArray(existing) ? existing : [];
+    const merged = [...existingRefs];
+    const known = new Set();
+    for (const ref of existingRefs) {
+        try {
+            known.add(sourceRefsAppendFingerprint(ref));
+        }
+        catch {
+            // Preserve legacy references exactly, but do not block valid additions.
+        }
+    }
+    for (const addition of additions) {
+        const key = sourceRefsAppendFingerprint(addition);
+        if (known.has(key))
+            continue;
+        known.add(key);
+        merged.push(addition);
+    }
+    return merged;
+}
 function validHttpUrl(value) {
     if (typeof value !== 'string' || !value.trim())
         return null;
@@ -570,7 +700,11 @@ export class CanonicalTaskService {
         // Keep this fingerprint independent of the wall clock. A restart may
         // reconstruct the same command at a different instant, while the marker
         // must still identify the already-applied mutation.
-        const operationFingerprint = fingerprint({
+        const fingerprintOperation = input.action === 'update'
+            && Object.prototype.hasOwnProperty.call(input.patch, 'source_refs_append')
+            ? sourceRefsAppendFingerprint
+            : fingerprint;
+        const operationFingerprint = fingerprintOperation({
             action: input.action,
             taskId,
             expectedVersion,
@@ -620,8 +754,17 @@ export class CanonicalTaskService {
                     to: input.transitionStatus,
                 }, { currentTask: this.normalizeResponse(latest) });
             }
+            const persistedPatch = { ...patch };
+            if (input.action === 'update' && 'source_refs_append' in input.patch) {
+                const additions = input.patch.source_refs_append;
+                if (!Array.isArray(additions)) {
+                    fail('validation_error', 'source_refs_append must be an array of plain JSON objects', 400, { field: 'source_refs_append' });
+                }
+                delete persistedPatch.source_refs_append;
+                persistedPatch.source_refs = mergeSourceRefs(latest.source_refs, additions);
+            }
             const updated = await this.read(() => this.repository.update(taskId, {
-                ...patch,
+                ...persistedPatch,
                 _last_operation_key: operation,
                 _last_operation_fingerprint: operationFingerprint,
             }, ...this.scopeArgs(input.context)));
@@ -689,6 +832,13 @@ export class CanonicalTaskService {
     normalizeUpdateInput(input) {
         if (!input || typeof input !== 'object')
             fail('validation_error', 'Task update is required');
+        const hasSourceRefsAppend = Object.prototype.hasOwnProperty.call(input, 'source_refs_append');
+        if ('source_refs_append' in input) {
+            const descriptor = Object.getOwnPropertyDescriptor(input, 'source_refs_append');
+            if (!hasSourceRefsAppend || !descriptor || !('value' in descriptor)) {
+                fail('validation_error', 'source_refs_append must be an own data property', 400, { field: 'source_refs_append' });
+            }
+        }
         const unknownFields = Object.keys(input).filter((field) => !MUTABLE_FIELDS.has(field));
         if (unknownFields.length > 0)
             fail('validation_error', 'Task update contains unsupported fields', 400, { fields: unknownFields });
@@ -713,8 +863,19 @@ export class CanonicalTaskService {
             patch.waiting_on = normalizeString(input.waiting_on, 'waiting_on', { max: 500 });
         if ('review_at' in input)
             patch.review_at = normalizeIsoDate(input.review_at, 'review_at');
+        if ('source_refs' in input && hasSourceRefsAppend) {
+            fail('validation_error', 'source_refs and source_refs_append cannot be combined', 400, {
+                fields: ['source_refs', 'source_refs_append'],
+            });
+        }
         if ('source_refs' in input)
             patch.source_refs = normalizeSourceRefs(input.source_refs) ?? [];
+        if (hasSourceRefsAppend) {
+            const descriptor = Object.getOwnPropertyDescriptor(input, 'source_refs_append');
+            // The descriptor was checked above before any value access. Reuse its
+            // data value so a getter cannot run between validation and normalization.
+            patch.source_refs_append = normalizeSourceRefsAppend(descriptor?.value) ?? [];
+        }
         if ('project_codes' in input)
             patch.project_codes = normalizeProjectCodes(input.project_codes) ?? [];
         if ('purpose_label' in input)

package/dist/meeting-minutes.d.ts

@@ -66,6 +66,12 @@ export interface MinutesDocumentRecord {
     readonly created_actor_id: string;
     readonly updated_at: string;
     readonly revision: number;
+    /** Set when the document was taken back from its readers.  Versions and bodies are kept. */
+    readonly withdrawal?: MinutesWithdrawalReceipt;
+}
+export interface MinutesWithdrawalReceipt {
+    readonly actor_id: string;
+    readonly withdrawn_at: string;
 }
 export interface MeetingMinutesSnapshot {
     readonly schema_version: typeof MEETING_MINUTES_SNAPSHOT_VERSION;
@@ -76,7 +82,7 @@ export interface MeetingMinutesSnapshot {
     readonly versions: readonly MinutesVersionRecord[];
     readonly idempotency: readonly MeetingMinutesIdempotencyRecord[];
 }
-export type MeetingMinutesIdempotencyOperation = 'create_meeting' | 'create_minutes' | 'save_version' | 'confirm_version';
+export type MeetingMinutesIdempotencyOperation = 'create_meeting' | 'create_minutes' | 'save_version' | 'confirm_version' | 'withdraw_minutes';
 /** Durable write receipt.  It lets a retried mutation find its exact target after restart. */
 export interface MeetingMinutesIdempotencyRecord {
     readonly key: string;
@@ -144,6 +150,12 @@ export interface ConfirmMinutesVersionInput {
     readonly idempotency_key?: string;
     readonly idempotency_fingerprint?: string;
 }
+export interface WithdrawMinutesInput {
+    readonly minutes_id: MinutesId;
+    readonly expected_revision: number;
+    readonly idempotency_key?: string;
+    readonly idempotency_fingerprint?: string;
+}
 export interface MeetingMinutesSummary {
     readonly meeting: MeetingRecord;
     readonly minutes: readonly MinutesDocumentRecord[];
@@ -186,6 +198,8 @@ export interface MeetingMinutesStore {
     get_version(meeting_id: MeetingId, minutes_id: MinutesId, version_id: MinutesVersionId, context: MeetingMinutesRequestContext): Promise<MinutesVersionRecord>;
     save_version(input: SaveMinutesVersionInput, context: MeetingMinutesRequestContext): Promise<MeetingMinutesDetail>;
     confirm_version(input: ConfirmMinutesVersionInput, context: MeetingMinutesRequestContext): Promise<MeetingMinutesDetail>;
+    /** Takes a document back from its readers (story-meeting-minutes-withdraw-v1).  Nothing is deleted. */
+    withdraw_minutes(input: WithdrawMinutesInput, context: MeetingMinutesRequestContext): Promise<MeetingMinutesDetail>;
 }
 /**
  * Provider-neutral exact-version seam used by lineage and other read-only

package/dist/meeting-minutes.js

@@ -289,6 +289,12 @@ function assertSnapshotShape(value) {
         checkDate(raw.updated_at, `Minutes document ${minutesId}.updated_at`);
         if (typeof raw.created_actor_id !== 'string' || !raw.created_actor_id.trim())
             throw new MeetingMinutesError('corrupt_record', `Minutes document ${minutesId}.created_actor_id is invalid`);
+        if (raw.withdrawal !== undefined) {
+            if (!isRecord(raw.withdrawal) || typeof raw.withdrawal.actor_id !== 'string' || !raw.withdrawal.actor_id.trim()) {
+                throw new MeetingMinutesError('corrupt_record', `Minutes document ${minutesId}.withdrawal is invalid`);
+            }
+            checkDate(raw.withdrawal.withdrawn_at, `Minutes document ${minutesId}.withdrawal.withdrawn_at`);
+        }
     }
     const versionIds = new Set();
     const versionById = new Map();
@@ -401,7 +407,8 @@ function assertSnapshotShape(value) {
         if (typeof key !== 'string' || key.trim() === '' || key.length > 200
             || typeof principalId !== 'string' || principalId.trim() === ''
             || typeof fingerprint !== 'string' || fingerprint.trim() === '' || fingerprint.length > 512
-            || (operation !== 'create_meeting' && operation !== 'create_minutes' && operation !== 'save_version' && operation !== 'confirm_version')
+            || (operation !== 'create_meeting' && operation !== 'create_minutes' && operation !== 'save_version' && operation !== 'confirm_version'
+                && operation !== 'withdraw_minutes')
             || typeof meetingId !== 'string' || !meetingIds.has(meetingId)) {
             throw new MeetingMinutesError('corrupt_record', 'Idempotency record is invalid');
         }
@@ -421,9 +428,9 @@ function assertSnapshotShape(value) {
             || documentById.get(minutesId)?.meeting_id !== meetingId) {
             throw new MeetingMinutesError('corrupt_record', 'Idempotency record minutes_id is invalid');
         }
-        if (operation === 'create_minutes') {
+        if (operation === 'create_minutes' || operation === 'withdraw_minutes') {
             if (versionId !== undefined)
-                throw new MeetingMinutesError('corrupt_record', 'create_minutes idempotency record has an unexpected version_id');
+                throw new MeetingMinutesError('corrupt_record', `${operation} idempotency record has an unexpected version_id`);
             continue;
         }
         if (typeof versionId !== 'string' || !versionIds.has(versionId)
@@ -601,7 +608,15 @@ function detail(snapshot, meeting) {
     return freezeClone({ meeting, minutes, versions, snapshot_revision: snapshot.revision });
 }
 function summary(snapshot, meeting) {
-    return freezeClone({ meeting, minutes: snapshot.documents.filter((candidate) => candidate.meeting_id === meeting.meeting_id) });
+    // A withdrawn document is taken back from listings; its detail stays readable for history.
+    return freezeClone({
+        meeting,
+        minutes: snapshot.documents.filter((candidate) => candidate.meeting_id === meeting.meeting_id && !candidate.withdrawal)
+    });
+}
+function assertNotWithdrawn(document) {
+    if (document.withdrawal)
+        throw invalid(`Minutes document ${document.minutes_id} was withdrawn`);
 }
 function ensureRevision(actual, expected) {
     if (!Number.isInteger(expected) || expected < 1)
@@ -974,6 +989,7 @@ export function createMeetingMinutesStore(options) {
         const meeting = findMeeting(snapshot, document.meeting_id);
         await authorized(authorizer, 'write', meeting, context);
         await authorized(authorizer, 'write', document, context);
+        assertNotWithdrawn(document);
         ensureRevision(document.revision, input.expected_revision);
         const predecessor = input.predecessor_version_id === undefined ? document.current_version_id : nonEmptyString(input.predecessor_version_id, 'predecessor_version_id');
         if (predecessor !== document.current_version_id)
@@ -1046,6 +1062,7 @@ export function createMeetingMinutesStore(options) {
         const version = snapshot.versions.find((candidate) => candidate.version_id === versionId && candidate.minutes_id === minutesId);
         if (!version)
             throw new MeetingMinutesError('not_found', `Minutes version ${versionId} was not found`);
+        assertNotWithdrawn(document);
         ensureRevision(document.revision, input.expected_revision);
         if (version.confirmation) {
             if (!idempotency.token)
@@ -1102,7 +1119,52 @@ export function createMeetingMinutesStore(options) {
             throw new MeetingMinutesError('readback_mismatch', 'Confirmation did not read back');
         return detailForCaller(readback, savedMeeting, context);
     }
-    return { list_meetings, create_meeting, create_minutes, get_meeting, get_version, save_version, confirm_version };
+    async function withdraw_minutes(input, context) {
+        const principal = assertPrincipal(context);
+        if (!isRecord(input))
+            throw invalid('withdrawal input must be an object');
+        const minutesId = nonEmptyString(input.minutes_id, 'minutes_id');
+        const snapshot = await readSnapshot();
+        const idempotency = await resolveIdempotency(snapshot, principal, input, 'withdraw_minutes', context, { minutes_id: minutesId });
+        if (idempotency.replay)
+            return idempotency.replay;
+        const document = findDocument(snapshot, minutesId);
+        const meeting = findMeeting(snapshot, document.meeting_id);
+        await authorized(authorizer, 'write', meeting, context);
+        await authorized(authorizer, 'write', document, context);
+        // Withdrawing twice keeps the first record; a retry is not a second withdrawal.
+        if (document.withdrawal && !idempotency.token)
+            return detailForCaller(snapshot, meeting, context);
+        if (!document.withdrawal)
+            ensureRevision(document.revision, input.expected_revision);
+        const timestamp = isoNow(now);
+        const next = snapshotMutable(snapshot);
+        next.revision += 1;
+        if (!document.withdrawal) {
+            next.documents = next.documents.map((candidate) => candidate.minutes_id === minutesId
+                ? { ...candidate, withdrawal: { actor_id: principal, withdrawn_at: timestamp }, updated_at: timestamp, revision: candidate.revision + 1 }
+                : candidate);
+        }
+        addIdempotencyRecord(next, idempotency.token, 'withdraw_minutes', {
+            meeting_id: meeting.meeting_id,
+            minutes_id: minutesId
+        }, principal);
+        let readback;
+        try {
+            readback = await writeSnapshot(next, snapshot.revision);
+        }
+        catch (error) {
+            const replay = await replayAfterConflict(error, idempotency.token, principal, 'withdraw_minutes', context, { minutes_id: minutesId });
+            if (replay)
+                return replay;
+            throw error;
+        }
+        const saved = findDocument(readback, minutesId);
+        if (!saved.withdrawal)
+            throw new MeetingMinutesError('readback_mismatch', 'Withdrawal did not read back');
+        return detailForCaller(readback, findMeeting(readback, meeting.meeting_id), context);
+    }
+    return { list_meetings, create_meeting, create_minutes, get_meeting, get_version, save_version, confirm_version, withdraw_minutes };
 }
 function participantIdsInput(value) {
     return participantIds(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unson/brainbase-mcp",
-  "version": "0.35.0",
+  "version": "0.37.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",
@@ -479,5 +479,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "e343d28419451fde27b9d35b1c226fc769e68420"
+  "gitHead": "55c2d213cafd20800d51c9669f4d7c8d727f7968"
 }