@unson/brainbase-mcp 0.21.2 → 0.22.0

package/dist/meeting-minutes-lineage.js

@@ -0,0 +1,1030 @@
+import { createHash } from 'node:crypto';
+import { initializePersonalOs, mutatePersonalOsWithSidecar, readPersonalOsSidecar } from './ssot.js';
+/**
+ * The minutes lineage ledger stores references and lifecycle events only.
+ * Meeting body content, judgment state, Task state, and execution receipts
+ * remain owned by their existing providers.
+ */
+export const MEETING_MINUTES_LINEAGE_CONTRACT_VERSION = '0.1.0';
+export const MEETING_MINUTES_LINEAGE_CATALOG_VERSION = 1;
+export const MEETING_MINUTES_LINEAGE_SIDECAR = 'evidence/meeting-minutes-lineage.json';
+export class MeetingMinutesLineageError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'MeetingMinutesLineageError';
+        this.code = code;
+    }
+}
+const EMPTY_LEDGER = {
+    version: MEETING_MINUTES_LINEAGE_CATALOG_VERSION,
+    candidates: [],
+    confirmations: [],
+    adoptions: [],
+    executions: [],
+    results: [],
+    corrections: [],
+};
+export function createMeetingMinutesLineageStore(options) {
+    if (!options || !isNonEmptyString(options.dataDir))
+        throw new MeetingMinutesLineageError('invalid_input', 'dataDir is required');
+    if (!options.minutes || typeof options.minutes.readExact !== 'function') {
+        throw new MeetingMinutesLineageError('invalid_input', 'minutes.readExact is required');
+    }
+    return new GraphMeetingMinutesLineageStore(options);
+}
+class GraphMeetingMinutesLineageStore {
+    options;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date().toISOString());
+    }
+    async createCandidate(request) {
+        const access = assertAccess(request.access);
+        const input = normalizeCandidateRequest(request);
+        await this.readExactMinutes(input.evidence, access);
+        const requestDigest = digestJson({
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            actor: input.actor,
+            principal: access.principal,
+            evidence: input.evidence,
+            kind: input.kind,
+            proposal: input.proposal,
+            epistemicStatus: input.epistemicStatus,
+        });
+        const candidate = {
+            version: MEETING_MINUTES_LINEAGE_CATALOG_VERSION,
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            requestDigest,
+            actor: cloneJson(input.actor),
+            evidence: cloneJson(input.evidence),
+            evidenceDigest: digestJson(input.evidence),
+            kind: input.kind,
+            proposal: cloneJson(input.proposal),
+            proposalDigest: digestJson(input.proposal),
+            epistemicStatus: input.epistemicStatus,
+            createdAt: this.now(),
+            digest: '',
+        };
+        const complete = withDigest(candidate);
+        let committed;
+        await this.mutateLedger((ledger) => {
+            const byId = ledger.candidates.find((item) => item.id === complete.id);
+            const byKey = ledger.candidates.find((item) => item.idempotencyKey === complete.idempotencyKey);
+            if (byId || byKey) {
+                const existing = byId ?? byKey;
+                if (existing.requestDigest !== complete.requestDigest) {
+                    throw new MeetingMinutesLineageError('revision_conflict', `Candidate ${existing.id} already exists with different content`);
+                }
+                committed = cloneJson(existing);
+                return { ledger, result: committed };
+            }
+            committed = complete;
+            return { ledger: { ...ledger, candidates: [...ledger.candidates, complete] }, result: complete };
+        });
+        if (!committed)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Candidate ${input.id} was not committed`);
+        const readback = await this.readCandidate(committed.id, access);
+        if (!readback || readback.digest !== committed.digest) {
+            throw new MeetingMinutesLineageError('readback_mismatch', `Candidate ${input.id} was not readable after commit`);
+        }
+        return readback;
+    }
+    async readCandidate(id, access) {
+        const context = assertAccess(access);
+        const candidateId = requireId(id, 'candidate id');
+        const ledger = await this.readLedger();
+        const candidate = ledger.candidates.find((item) => item.id === candidateId);
+        if (!candidate)
+            return null;
+        assertDigest(candidate, 'candidate');
+        await this.readExactMinutes(candidate.evidence, context);
+        return cloneJson(candidate);
+    }
+    async confirmCandidate(request) {
+        const access = assertAccess(request.access);
+        const input = normalizeConfirmationRequest(request);
+        const candidate = await this.requireCandidate(input.candidateId, access);
+        if (input.evidenceDigest !== candidate.evidenceDigest) {
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Candidate ${candidate.id} evidence digest does not match`);
+        }
+        const requestDigest = digestJson({
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            candidateId: input.candidateId,
+            candidateDigest: candidate.digest,
+            actor: input.actor,
+            principal: access.principal,
+            evidenceDigest: input.evidenceDigest,
+        });
+        const confirmation = {
+            version: MEETING_MINUTES_LINEAGE_CATALOG_VERSION,
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            requestDigest,
+            candidateId: candidate.id,
+            candidateDigest: candidate.digest,
+            actor: cloneJson(input.actor),
+            evidenceDigest: input.evidenceDigest,
+            confirmedAt: this.now(),
+            digest: '',
+        };
+        const complete = withDigest(confirmation);
+        let committed;
+        await this.mutateLedger((ledger) => {
+            const existing = ledger.confirmations.find((item) => item.idempotencyKey === complete.idempotencyKey || item.id === complete.id);
+            if (existing) {
+                if (existing.requestDigest !== complete.requestDigest)
+                    throw new MeetingMinutesLineageError('revision_conflict', `Confirmation ${existing.id} already exists with different content`);
+                committed = cloneJson(existing);
+                return { ledger, result: committed };
+            }
+            const existingForCandidate = ledger.confirmations.find((item) => item.candidateId === complete.candidateId);
+            if (existingForCandidate) {
+                if (existingForCandidate.candidateDigest !== complete.candidateDigest)
+                    throw new MeetingMinutesLineageError('integrity_mismatch', `Candidate ${candidate.id} changed before confirmation`);
+                committed = cloneJson(existingForCandidate);
+                return { ledger, result: committed };
+            }
+            committed = complete;
+            return { ledger: { ...ledger, confirmations: [...ledger.confirmations, complete] }, result: complete };
+        });
+        if (!committed)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Confirmation ${input.id} was not committed`);
+        return committed;
+    }
+    async adoptJudgment(request) {
+        return this.adopt(request, 'judgment');
+    }
+    async adoptTask(request) {
+        return this.adopt(request, 'task');
+    }
+    async adopt(request, kind) {
+        const access = assertAccess(request.access);
+        const input = normalizeAdoptionRequest(request);
+        const candidate = await this.requireCandidate(input.candidateId, access);
+        if (candidate.kind !== kind)
+            throw new MeetingMinutesLineageError('invalid_input', `Candidate ${candidate.id} is not a ${kind} candidate`);
+        const confirmation = await this.readConfirmation(candidate.id, access);
+        if (!confirmation)
+            throw new MeetingMinutesLineageError('invalid_input', `Candidate ${candidate.id} requires explicit confirmation before adoption`);
+        const requestDigest = digestJson({
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            candidateId: candidate.id,
+            candidateDigest: candidate.digest,
+            kind,
+            actor: input.actor,
+            principal: access.principal,
+        });
+        const ledger = await this.readLedger();
+        const existingByKey = ledger.adoptions.find((item) => item.idempotencyKey === input.idempotencyKey);
+        if (existingByKey) {
+            if (existingByKey.requestDigest !== requestDigest)
+                throw new MeetingMinutesLineageError('revision_conflict', `Adoption key ${input.idempotencyKey} was used with different content`);
+            await this.assertTargetReadable(existingByKey.target, access);
+            return cloneJson(existingByKey);
+        }
+        // A candidate is the unit of adoption idempotency. The same minutes
+        // version may intentionally produce several candidates and targets, but
+        // retrying one candidate with a new transport key must not call the
+        // provider a second time.
+        const existingForCandidate = ledger.adoptions.find((item) => item.candidateId === candidate.id);
+        if (existingForCandidate) {
+            if (existingForCandidate.kind !== kind)
+                throw new MeetingMinutesLineageError('revision_conflict', `Candidate ${candidate.id} already has a different adoption kind`);
+            await this.assertTargetReadable(existingForCandidate.target, access);
+            return cloneJson(existingForCandidate);
+        }
+        let adopted;
+        try {
+            if (kind === 'judgment') {
+                const provider = this.options.judgment;
+                if (!provider)
+                    throw new MeetingMinutesLineageError('provider_unavailable', 'judgment adoption provider is not connected');
+                adopted = await provider.adopt({ candidate, idempotencyKey: providerIdempotencyKey(kind, candidate), actor: input.actor, access });
+            }
+            else {
+                const provider = this.options.task;
+                if (!provider)
+                    throw new MeetingMinutesLineageError('provider_unavailable', 'task adoption provider is not connected');
+                adopted = await provider.create({ candidate, idempotencyKey: providerIdempotencyKey(kind, candidate), actor: input.actor, access });
+            }
+        }
+        catch (error) {
+            throw mapProviderError(error, `${kind} adoption provider is unavailable`, 'target_unavailable');
+        }
+        const target = normalizeTarget(adopted?.target);
+        if (target.kind !== kind)
+            throw new MeetingMinutesLineageError('integrity_mismatch', `${kind} adoption returned a different target kind`);
+        const adoptionReference = normalizeAdoptionReference(adopted?.adoption, kind);
+        await this.assertTargetReadable(target, access);
+        const record = {
+            version: MEETING_MINUTES_LINEAGE_CATALOG_VERSION,
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            requestDigest,
+            candidateId: candidate.id,
+            candidateDigest: candidate.digest,
+            kind,
+            target,
+            adoption: adoptionReference,
+            actor: cloneJson(input.actor),
+            adoptedAt: this.now(),
+            digest: '',
+        };
+        const complete = withDigest(record);
+        let committed;
+        await this.mutateLedger((nextLedger) => {
+            const sameKey = nextLedger.adoptions.find((item) => item.idempotencyKey === complete.idempotencyKey);
+            if (sameKey) {
+                if (sameKey.requestDigest !== complete.requestDigest)
+                    throw new MeetingMinutesLineageError('revision_conflict', `Adoption key ${input.idempotencyKey} was used with different content`);
+                committed = cloneJson(sameKey);
+                return { ledger: nextLedger, result: committed };
+            }
+            const sameCandidate = nextLedger.adoptions.find((item) => item.candidateId === complete.candidateId);
+            if (sameCandidate) {
+                if (sameCandidate.target.kind !== complete.target.kind || !sameTarget(sameCandidate.target, complete.target)) {
+                    throw new MeetingMinutesLineageError('revision_conflict', `Candidate ${candidate.id} already has a different adoption`);
+                }
+                committed = cloneJson(sameCandidate);
+                return { ledger: nextLedger, result: committed };
+            }
+            committed = complete;
+            return { ledger: { ...nextLedger, adoptions: [...nextLedger.adoptions, complete] }, result: complete };
+        });
+        if (!committed)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Adoption ${input.id} was not committed`);
+        const readback = await this.readAdoption(committed.id, access);
+        if (!readback || readback.digest !== committed.digest)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Adoption ${input.id} was not readable after commit`);
+        void confirmation;
+        return readback;
+    }
+    async recordExecution(request) {
+        const access = assertAccess(request.access);
+        const input = normalizeExecutionRequest(request);
+        const candidate = await this.requireCandidate(input.candidateId, access);
+        const adoption = await this.requireAdoption(candidate.id, access);
+        if (!this.options.receipt)
+            throw new MeetingMinutesLineageError('provider_unavailable', 'Execution receipt provider is not connected');
+        let receipt;
+        try {
+            receipt = await this.options.receipt.read(input.receiptRef, access);
+        }
+        catch (error) {
+            throw mapProviderError(error, 'Execution receipt provider is unavailable', 'target_unavailable');
+        }
+        if (!receipt)
+            throw new MeetingMinutesLineageError('target_unavailable', `Execution receipt ${input.receiptRef.id} is unavailable`);
+        const receiptReference = normalizeReceiptReference(receipt.reference);
+        if (!sameJson(receiptReference, input.receiptRef))
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Execution receipt ${input.receiptRef.id} changed`);
+        const receiptTarget = normalizeTarget(receipt.target);
+        if (!sameTarget(receiptTarget, adoption.target))
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Execution receipt ${input.receiptRef.id} used a different target version`);
+        const runId = requireId(receipt.runId, 'receipt runId');
+        const requestDigest = digestJson({
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            candidateId: input.candidateId,
+            adoptionId: adoption.id,
+            target: adoption.target,
+            receiptRef: input.receiptRef,
+            runId,
+            actor: input.actor,
+            principal: access.principal,
+        });
+        const record = {
+            version: MEETING_MINUTES_LINEAGE_CATALOG_VERSION,
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            requestDigest,
+            candidateId: candidate.id,
+            adoptionId: adoption.id,
+            target: cloneJson(adoption.target),
+            receiptRef: receiptReference,
+            runId,
+            actor: cloneJson(input.actor),
+            executedAt: this.now(),
+            digest: '',
+        };
+        const complete = withDigest(record);
+        let committed;
+        await this.mutateLedger((ledger) => {
+            const existing = ledger.executions.find((item) => item.idempotencyKey === complete.idempotencyKey || item.id === complete.id);
+            if (existing) {
+                if (existing.requestDigest !== complete.requestDigest)
+                    throw new MeetingMinutesLineageError('revision_conflict', `Execution ${existing.id} already exists with different content`);
+                committed = cloneJson(existing);
+                return { ledger, result: committed };
+            }
+            committed = complete;
+            return { ledger: { ...ledger, executions: [...ledger.executions, complete] }, result: complete };
+        });
+        if (!committed)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Execution ${input.id} was not committed`);
+        const readback = await this.readExecution(committed.id, access);
+        if (!readback || readback.digest !== committed.digest)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Execution ${input.id} was not readable after commit`);
+        return readback;
+    }
+    async acceptResult(request) {
+        const access = assertAccess(request.access);
+        const input = normalizeResultRequest(request);
+        const execution = await this.requireExecution(input.executionId, access);
+        if (!this.options.result)
+            throw new MeetingMinutesLineageError('provider_unavailable', 'Result provider is not connected');
+        let result;
+        try {
+            result = await this.options.result.read(input.resultRef, access);
+        }
+        catch (error) {
+            throw mapProviderError(error, 'Result provider is unavailable', 'target_unavailable');
+        }
+        if (!result)
+            throw new MeetingMinutesLineageError('target_unavailable', `Result ${input.resultRef.id} is unavailable`);
+        const resultReference = normalizeResultReference(result.reference);
+        if (!sameJson(resultReference, input.resultRef))
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Result ${input.resultRef.id} changed`);
+        const resultTarget = normalizeTarget(result.target);
+        if (!sameTarget(resultTarget, execution.target))
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Result ${input.resultRef.id} points to a different target version`);
+        const requestDigest = digestJson({
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            executionId: input.executionId,
+            resultRef: input.resultRef,
+            target: execution.target,
+            actor: input.actor,
+            principal: access.principal,
+        });
+        const record = {
+            version: MEETING_MINUTES_LINEAGE_CATALOG_VERSION,
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            requestDigest,
+            executionId: execution.id,
+            resultRef: resultReference,
+            target: cloneJson(execution.target),
+            actor: cloneJson(input.actor),
+            acceptedAt: this.now(),
+            digest: '',
+        };
+        const complete = withDigest(record);
+        let committed;
+        await this.mutateLedger((ledger) => {
+            const existing = ledger.results.find((item) => item.idempotencyKey === complete.idempotencyKey || item.id === complete.id);
+            if (existing) {
+                if (existing.requestDigest !== complete.requestDigest)
+                    throw new MeetingMinutesLineageError('revision_conflict', `Result ${existing.id} already exists with different content`);
+                committed = cloneJson(existing);
+                return { ledger, result: committed };
+            }
+            const existingExecution = ledger.results.find((item) => item.executionId === complete.executionId);
+            if (existingExecution) {
+                if (!sameJson(existingExecution.resultRef, complete.resultRef))
+                    throw new MeetingMinutesLineageError('revision_conflict', `Execution ${complete.executionId} already has a different accepted result`);
+                committed = cloneJson(existingExecution);
+                return { ledger, result: committed };
+            }
+            committed = complete;
+            return { ledger: { ...ledger, results: [...ledger.results, complete] }, result: complete };
+        });
+        if (!committed)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Result ${input.id} was not committed`);
+        const readback = await this.readResult(committed.id, access);
+        if (!readback || readback.digest !== committed.digest)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Result ${input.id} was not readable after commit`);
+        return readback;
+    }
+    async markCorrection(request) {
+        const access = assertAccess(request.access);
+        const input = normalizeCorrectionRequest(request);
+        await this.readExactMinutes(input.previousVersion, access);
+        await this.readExactMinutes(input.replacementVersion, access);
+        if (sameMinutesReference(input.previousVersion, input.replacementVersion)) {
+            throw new MeetingMinutesLineageError('invalid_input', 'A correction must point to a different exact minutes version');
+        }
+        const ledger = await this.readLedger();
+        const affectedCandidateIds = ledger.candidates
+            .filter((candidate) => sameMinutesReference(candidate.evidence, input.previousVersion))
+            .map((candidate) => candidate.id);
+        const requestDigest = digestJson({
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            previousVersion: input.previousVersion,
+            replacementVersion: input.replacementVersion,
+            affectedCandidateIds,
+            actor: input.actor,
+            principal: access.principal,
+            reason: input.reason,
+        });
+        const record = {
+            version: MEETING_MINUTES_LINEAGE_CATALOG_VERSION,
+            id: input.id,
+            idempotencyKey: input.idempotencyKey,
+            requestDigest,
+            previousVersion: cloneJson(input.previousVersion),
+            replacementVersion: cloneJson(input.replacementVersion),
+            affectedCandidateIds: [...affectedCandidateIds],
+            actor: cloneJson(input.actor),
+            reason: input.reason,
+            correctedAt: this.now(),
+            digest: '',
+        };
+        const complete = withDigest(record);
+        let committed;
+        await this.mutateLedger((nextLedger) => {
+            const existing = nextLedger.corrections.find((item) => item.idempotencyKey === complete.idempotencyKey || item.id === complete.id);
+            if (existing) {
+                if (existing.requestDigest !== complete.requestDigest)
+                    throw new MeetingMinutesLineageError('revision_conflict', `Correction ${existing.id} already exists with different content`);
+                committed = cloneJson(existing);
+                return { ledger: nextLedger, result: committed };
+            }
+            committed = complete;
+            return { ledger: { ...nextLedger, corrections: [...nextLedger.corrections, complete] }, result: complete };
+        });
+        if (!committed)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Correction ${input.id} was not committed`);
+        return committed;
+    }
+    async readByMinutesVersion(reference, access) {
+        const context = assertAccess(access);
+        const evidence = normalizeMinutesReference(reference);
+        await this.readExactMinutes(evidence, context);
+        const ledger = await this.readLedger();
+        const candidates = ledger.candidates.filter((candidate) => sameMinutesReference(candidate.evidence, evidence));
+        const views = await Promise.all(candidates.map((candidate) => this.projectCandidate(candidate, ledger, context)));
+        const corrections = ledger.corrections.filter((correction) => sameMinutesReference(correction.previousVersion, evidence) || sameMinutesReference(correction.replacementVersion, evidence));
+        return { evidence: cloneJson(evidence), candidates: views, corrections: cloneJson(corrections) };
+    }
+    async readByTarget(target, access) {
+        const context = assertAccess(access);
+        const normalizedTarget = normalizeTarget(target);
+        await this.assertTargetReadable(normalizedTarget, context);
+        const ledger = await this.readLedger();
+        const adoptions = ledger.adoptions.filter((item) => sameTarget(item.target, normalizedTarget));
+        const candidates = [];
+        const sourceStatuses = {};
+        for (const adoption of adoptions) {
+            const candidate = ledger.candidates.find((item) => item.id === adoption.candidateId);
+            if (!candidate)
+                throw new MeetingMinutesLineageError('integrity_mismatch', `Adoption ${adoption.id} points to missing candidate`);
+            try {
+                await this.readExactMinutes(candidate.evidence, context);
+                sourceStatuses[candidate.id] = { status: 'available' };
+            }
+            catch (error) {
+                // Reverse lookup must not become a side channel after a source ACL is
+                // revoked.  The candidate contains the proposal, exact source ids,
+                // and provider locator, so returning it alongside a denied status
+                // would disclose the very records that the source denied.
+                if (error instanceof MeetingMinutesLineageError && error.code === 'authorization_denied') {
+                    throw new MeetingMinutesLineageError('authorization_denied', 'Meeting minutes source is not available for this principal');
+                }
+                sourceStatuses[candidate.id] = statusFromError(error);
+            }
+            candidates.push(await this.projectCandidate(candidate, ledger, context, { targetAlreadyRead: true }));
+        }
+        return { target: normalizedTarget, adoptions: cloneJson(adoptions), candidates, sourceStatuses };
+    }
+    async projectCandidate(candidate, ledger, access, options = {}) {
+        assertDigest(candidate, 'candidate');
+        const confirmation = ledger.confirmations.find((item) => item.candidateId === candidate.id);
+        if (confirmation)
+            assertDigest(confirmation, 'confirmation');
+        const adoption = ledger.adoptions.find((item) => item.candidateId === candidate.id);
+        if (adoption)
+            assertDigest(adoption, 'adoption');
+        const storedExecution = adoption ? ledger.executions.find((item) => item.adoptionId === adoption.id) : undefined;
+        if (storedExecution)
+            assertDigest(storedExecution, 'execution');
+        let execution;
+        let executionStatus = 'unrecorded';
+        if (storedExecution) {
+            try {
+                execution = (await this.readExecution(storedExecution.id, access)) ?? undefined;
+                if (execution)
+                    executionStatus = 'actual';
+            }
+            catch {
+                // An execution is actual only while its exact receipt and target can
+                // be read under the current ACL.  A stale sidecar entry must never
+                // make a projection look successful after the provider changes.
+                execution = undefined;
+            }
+        }
+        const storedResult = execution ? ledger.results.find((item) => item.executionId === execution.id) : undefined;
+        if (storedResult)
+            assertDigest(storedResult, 'result');
+        let result;
+        let resultStatus = 'unrecorded';
+        if (execution && storedResult) {
+            try {
+                result = (await this.readResult(storedResult.id, access, execution)) ?? undefined;
+                if (result)
+                    resultStatus = 'accepted';
+            }
+            catch {
+                // Results are accepted only while their exact provider record remains
+                // readable and points at the same execution target.
+                result = undefined;
+            }
+        }
+        const reviewRequired = ledger.corrections.some((correction) => correction.affectedCandidateIds.includes(candidate.id));
+        let targetStatus;
+        if (adoption && !options.targetAlreadyRead)
+            targetStatus = await this.targetStatus(adoption.target, access);
+        return {
+            candidate: cloneJson(candidate),
+            ...(confirmation ? { confirmation: cloneJson(confirmation) } : {}),
+            ...(adoption ? { adoption: cloneJson(adoption) } : {}),
+            ...(execution ? { execution: cloneJson(execution) } : {}),
+            ...(result ? { result: cloneJson(result) } : {}),
+            confirmationStatus: confirmation ? 'confirmed' : 'unconfirmed',
+            adoptionStatus: adoption ? 'adopted' : 'not_adopted',
+            executionStatus,
+            resultStatus,
+            reviewStatus: reviewRequired ? 'review_required' : 'clear',
+            ...(targetStatus ? { targetStatus } : {}),
+        };
+    }
+    async readConfirmation(candidateId, access) {
+        const ledger = await this.readLedger();
+        const confirmation = ledger.confirmations.find((item) => item.candidateId === candidateId);
+        if (!confirmation)
+            return null;
+        const candidate = await this.requireCandidate(candidateId, access);
+        if (confirmation.candidateDigest !== candidate.digest)
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Confirmation ${confirmation.id} points to an old candidate`);
+        assertDigest(confirmation, 'confirmation');
+        return cloneJson(confirmation);
+    }
+    async readAdoption(id, access) {
+        const adoptionId = requireId(id, 'adoption id');
+        const ledger = await this.readLedger();
+        const adoption = ledger.adoptions.find((item) => item.id === adoptionId);
+        if (!adoption)
+            return null;
+        const candidate = await this.requireCandidate(adoption.candidateId, access);
+        if (adoption.candidateDigest !== candidate.digest)
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Adoption ${adoption.id} points to an old candidate`);
+        await this.assertTargetReadable(adoption.target, access);
+        assertDigest(adoption, 'adoption');
+        return cloneJson(adoption);
+    }
+    async readExecution(id, access) {
+        const executionId = requireId(id, 'execution id');
+        const ledger = await this.readLedger();
+        const execution = ledger.executions.find((item) => item.id === executionId);
+        if (!execution)
+            return null;
+        const adoption = await this.requireAdoption(execution.candidateId, access);
+        if (adoption.id !== execution.adoptionId || !sameTarget(adoption.target, execution.target))
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Execution ${execution.id} points to a different adoption`);
+        await this.assertTargetReadable(execution.target, access);
+        if (!this.options.receipt)
+            throw new MeetingMinutesLineageError('provider_unavailable', 'Execution receipt provider is not connected');
+        let receipt;
+        try {
+            receipt = await this.options.receipt.read(execution.receiptRef, access);
+        }
+        catch (error) {
+            throw mapProviderError(error, 'Execution receipt provider is unavailable', 'target_unavailable');
+        }
+        if (!receipt || !sameJson(normalizeReceiptReference(receipt.reference), execution.receiptRef) || !sameTarget(normalizeTarget(receipt.target), execution.target)) {
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Execution receipt ${execution.receiptRef.id} is not readable at the exact version`);
+        }
+        assertDigest(execution, 'execution');
+        return cloneJson(execution);
+    }
+    async readResult(id, access, verifiedExecution) {
+        const resultId = requireId(id, 'result id');
+        const ledger = await this.readLedger();
+        const result = ledger.results.find((item) => item.id === resultId);
+        if (!result)
+            return null;
+        assertDigest(result, 'result');
+        const execution = verifiedExecution ?? await this.requireExecution(result.executionId, access);
+        if (execution.id !== result.executionId || !sameTarget(execution.target, result.target)) {
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Result ${result.id} points to a different execution target`);
+        }
+        if (!this.options.result)
+            throw new MeetingMinutesLineageError('provider_unavailable', 'Result provider is not connected');
+        let providerResult;
+        try {
+            providerResult = await this.options.result.read(result.resultRef, access);
+        }
+        catch (error) {
+            throw mapProviderError(error, 'Result provider is unavailable', 'target_unavailable');
+        }
+        if (!providerResult ||
+            !sameJson(normalizeResultReference(providerResult.reference), result.resultRef) ||
+            !sameTarget(normalizeTarget(providerResult.target), execution.target)) {
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Result ${result.resultRef.id} is not readable at the exact version`);
+        }
+        return cloneJson(result);
+    }
+    async requireExecution(id, access) {
+        const execution = await this.readExecution(id, access);
+        if (!execution)
+            throw new MeetingMinutesLineageError('not_found', `Execution ${id} was not found`);
+        return execution;
+    }
+    async requireCandidate(id, access) {
+        const candidate = await this.readCandidate(id, access);
+        if (!candidate)
+            throw new MeetingMinutesLineageError('not_found', `Candidate ${id} was not found`);
+        return candidate;
+    }
+    async requireAdoption(candidateId, access) {
+        const ledger = await this.readLedger();
+        const adoption = ledger.adoptions.find((item) => item.candidateId === candidateId);
+        if (!adoption)
+            throw new MeetingMinutesLineageError('not_found', `Candidate ${candidateId} has no adopted target`);
+        const readback = await this.readAdoption(adoption.id, access);
+        if (!readback)
+            throw new MeetingMinutesLineageError('readback_mismatch', `Adoption ${adoption.id} was not readable`);
+        return readback;
+    }
+    async assertTargetReadable(target, access) {
+        const provider = target.kind === 'judgment' ? this.options.judgment : this.options.task;
+        if (!provider)
+            throw new MeetingMinutesLineageError('provider_unavailable', `${target.kind} provider is not connected`);
+        try {
+            const record = await provider.readExact(target, access);
+            if (!record)
+                throw new MeetingMinutesLineageError('target_unavailable', `${target.kind} ${target.id} is unavailable`);
+        }
+        catch (error) {
+            if (error instanceof MeetingMinutesLineageError)
+                throw error;
+            throw mapProviderError(error, `${target.kind} ${target.id} is unavailable`, 'target_unavailable');
+        }
+    }
+    async targetStatus(target, access) {
+        try {
+            await this.assertTargetReadable(target, access);
+            return { status: 'available' };
+        }
+        catch (error) {
+            return statusFromError(error);
+        }
+    }
+    async readExactMinutes(reference, access) {
+        let resolved;
+        try {
+            resolved = await this.options.minutes.readExact(reference, access);
+        }
+        catch (error) {
+            throw mapProviderError(error, `Minutes version ${reference.versionId} is unavailable`);
+        }
+        if (!resolved)
+            throw new MeetingMinutesLineageError('source_not_found', `Minutes version ${reference.versionId} was not found`);
+        const actual = normalizeMinutesReference(resolved.reference);
+        if (!sameMinutesReference(actual, reference)) {
+            throw new MeetingMinutesLineageError('integrity_mismatch', `Minutes version ${reference.versionId} was not returned at the requested exact version`);
+        }
+        return { reference: actual };
+    }
+    async readLedger() {
+        const content = await readPersonalOsSidecar(this.options.dataDir, MEETING_MINUTES_LINEAGE_SIDECAR);
+        return parseLedger(content);
+    }
+    async mutateLedger(mutator) {
+        let result;
+        let completed = false;
+        await mutatePersonalOsWithSidecar(this.options.dataDir, MEETING_MINUTES_LINEAGE_SIDECAR, (current, content) => {
+            const ledger = parseLedger(content);
+            const outcome = mutator(ledger);
+            assertLedger(outcome.ledger);
+            result = cloneJson(outcome.result);
+            completed = true;
+            return { next: current, sidecarContent: serializeLedger(outcome.ledger), result: outcome.result };
+        });
+        if (!completed)
+            throw new MeetingMinutesLineageError('readback_mismatch', 'Lineage mutation did not complete');
+        return result;
+    }
+}
+export async function initializeMeetingMinutesLineageStore(dataDir) {
+    await initializePersonalOs(dataDir);
+    const content = await readPersonalOsSidecar(dataDir, MEETING_MINUTES_LINEAGE_SIDECAR);
+    if (content === undefined) {
+        await mutatePersonalOsWithSidecar(dataDir, MEETING_MINUTES_LINEAGE_SIDECAR, (current) => ({
+            next: current,
+            sidecarContent: serializeLedger(EMPTY_LEDGER),
+            result: undefined,
+        }));
+    }
+    else {
+        parseLedger(content);
+    }
+}
+function normalizeCandidateRequest(request) {
+    if (!request || typeof request !== 'object')
+        throw new MeetingMinutesLineageError('invalid_input', 'candidate request is required');
+    return {
+        id: requireId(request.id, 'candidate id'),
+        idempotencyKey: requireId(request.idempotencyKey, 'candidate idempotencyKey'),
+        actor: normalizeActor(request.actor),
+        evidence: normalizeMinutesReference(request.evidence),
+        kind: requireEnum(request.kind, ['judgment', 'task'], 'candidate kind'),
+        proposal: cloneJson(request.proposal),
+        epistemicStatus: requireEnum(request.epistemicStatus, ['confirmed', 'inferred'], 'epistemicStatus'),
+    };
+}
+function normalizeConfirmationRequest(request) {
+    return {
+        id: requireId(request?.id, 'confirmation id'),
+        idempotencyKey: requireId(request?.idempotencyKey, 'confirmation idempotencyKey'),
+        candidateId: requireId(request?.candidateId, 'candidate id'),
+        actor: normalizeActor(request?.actor),
+        evidenceDigest: requireDigest(request?.evidenceDigest, 'evidenceDigest'),
+    };
+}
+function normalizeAdoptionRequest(request) {
+    return {
+        id: requireId(request?.id, 'adoption id'),
+        idempotencyKey: requireId(request?.idempotencyKey, 'adoption idempotencyKey'),
+        candidateId: requireId(request?.candidateId, 'candidate id'),
+        actor: normalizeActor(request?.actor),
+    };
+}
+function normalizeExecutionRequest(request) {
+    return {
+        id: requireId(request?.id, 'execution id'),
+        idempotencyKey: requireId(request?.idempotencyKey, 'execution idempotencyKey'),
+        candidateId: requireId(request?.candidateId, 'candidate id'),
+        receiptRef: normalizeReceiptReference(request?.receiptRef),
+        actor: normalizeActor(request?.actor),
+    };
+}
+function normalizeResultRequest(request) {
+    return {
+        id: requireId(request?.id, 'result id'),
+        idempotencyKey: requireId(request?.idempotencyKey, 'result idempotencyKey'),
+        executionId: requireId(request?.executionId, 'execution id'),
+        resultRef: normalizeResultReference(request?.resultRef),
+        actor: normalizeActor(request?.actor),
+    };
+}
+function normalizeCorrectionRequest(request) {
+    const reason = requireString(request?.reason, 'correction reason');
+    if (reason.length > 4000)
+        throw new MeetingMinutesLineageError('invalid_input', 'correction reason is too long');
+    return {
+        id: requireId(request?.id, 'correction id'),
+        idempotencyKey: requireId(request?.idempotencyKey, 'correction idempotencyKey'),
+        previousVersion: normalizeMinutesReference(request?.previousVersion),
+        replacementVersion: normalizeMinutesReference(request?.replacementVersion),
+        actor: normalizeActor(request?.actor),
+        reason,
+    };
+}
+function normalizeMinutesReference(value) {
+    if (!value || typeof value !== 'object')
+        throw new MeetingMinutesLineageError('invalid_input', 'exact minutes reference is required');
+    return {
+        meetingId: requireId(value.meetingId, 'meetingId'),
+        minutesId: requireId(value.minutesId, 'minutesId'),
+        versionId: requireId(value.versionId, 'versionId'),
+        contentDigest: value.contentDigest === null ? null : requireDigest(value.contentDigest, 'contentDigest'),
+        locator: cloneJson(value.locator),
+        provenance: normalizeProvenance(value.provenance),
+    };
+}
+function normalizeProvenance(value) {
+    if (!value || typeof value !== 'object')
+        throw new MeetingMinutesLineageError('invalid_input', 'minutes provenance is required');
+    return {
+        providerKind: requireString(value.providerKind, 'provenance.providerKind'),
+        providerId: requireString(value.providerId, 'provenance.providerId'),
+        ...(value.revision === undefined ? {} : { revision: requireString(value.revision, 'provenance.revision') }),
+        ...(value.digest === undefined ? {} : { digest: requireDigest(value.digest, 'provenance.digest') }),
+    };
+}
+function normalizeActor(value) {
+    if (!value || typeof value !== 'object')
+        throw new MeetingMinutesLineageError('invalid_input', 'actor is required');
+    return {
+        type: requireEnum(value.type, ['person', 'agent', 'service', 'system'], 'actor.type'),
+        id: requireId(value.id, 'actor.id'),
+    };
+}
+function normalizeTarget(value) {
+    if (!value || typeof value !== 'object')
+        throw new MeetingMinutesLineageError('invalid_input', 'exact target reference is required');
+    if (value.kind === 'judgment') {
+        return {
+            kind: 'judgment',
+            id: requireId(value.id, 'judgment target id'),
+            revision: requireId(value.revision, 'judgment target revision'),
+            digest: requireDigest(value.digest, 'judgment target digest'),
+        };
+    }
+    if (value.kind === 'task') {
+        if (!Number.isInteger(value.version) || value.version < 1)
+            throw new MeetingMinutesLineageError('invalid_input', 'task target version must be a positive integer');
+        return {
+            kind: 'task',
+            id: requireId(value.id, 'task target id'),
+            version: value.version,
+            ...(value.digest === undefined ? {} : { digest: requireDigest(value.digest, 'task target digest') }),
+        };
+    }
+    throw new MeetingMinutesLineageError('invalid_input', 'target kind must be judgment or task');
+}
+function normalizeAdoptionReference(value, kind) {
+    if (!value || typeof value !== 'object')
+        throw new MeetingMinutesLineageError('invalid_input', 'adoption provider must return an exact adoption reference');
+    const expected = kind === 'judgment' ? 'judgment_adoption' : 'task_adoption';
+    if (value.kind !== expected)
+        throw new MeetingMinutesLineageError('integrity_mismatch', `Adoption reference kind must be ${expected}`);
+    return { kind: expected, id: requireId(value.id, 'adoption reference id'), revision: requireId(value.revision, 'adoption reference revision'), digest: requireDigest(value.digest, 'adoption reference digest') };
+}
+function normalizeReceiptReference(value) {
+    if (!value || typeof value !== 'object')
+        throw new MeetingMinutesLineageError('invalid_input', 'receipt reference is required');
+    return { id: requireId(value.id, 'receipt id'), digest: requireDigest(value.digest, 'receipt digest') };
+}
+function normalizeResultReference(value) {
+    if (!value || typeof value !== 'object')
+        throw new MeetingMinutesLineageError('invalid_input', 'result reference is required');
+    return { id: requireId(value.id, 'result id'), digest: requireDigest(value.digest, 'result digest') };
+}
+function parseLedger(content) {
+    if (content === undefined)
+        return EMPTY_LEDGER;
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new MeetingMinutesLineageError('corrupt_record', 'Meeting minutes lineage sidecar is not valid JSON');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new MeetingMinutesLineageError('corrupt_record', 'Meeting minutes lineage sidecar must be an object');
+    const value = parsed;
+    if (value.version !== MEETING_MINUTES_LINEAGE_CATALOG_VERSION)
+        throw new MeetingMinutesLineageError('corrupt_record', 'Unsupported meeting minutes lineage catalog version');
+    for (const field of ['candidates', 'confirmations', 'adoptions', 'executions', 'results', 'corrections']) {
+        if (!Array.isArray(value[field]))
+            throw new MeetingMinutesLineageError('corrupt_record', `Lineage sidecar field ${field} must be an array`);
+    }
+    const ledger = {
+        version: MEETING_MINUTES_LINEAGE_CATALOG_VERSION,
+        candidates: cloneJson(value.candidates),
+        confirmations: cloneJson(value.confirmations),
+        adoptions: cloneJson(value.adoptions),
+        executions: cloneJson(value.executions),
+        results: cloneJson(value.results),
+        corrections: cloneJson(value.corrections),
+    };
+    assertLedger(ledger);
+    return ledger;
+}
+function assertLedger(ledger) {
+    if (!ledger || ledger.version !== MEETING_MINUTES_LINEAGE_CATALOG_VERSION)
+        throw new MeetingMinutesLineageError('corrupt_record', 'Invalid meeting minutes lineage ledger version');
+    for (const collection of [ledger.candidates, ledger.confirmations, ledger.adoptions, ledger.executions, ledger.results, ledger.corrections]) {
+        if (!Array.isArray(collection))
+            throw new MeetingMinutesLineageError('corrupt_record', 'Invalid meeting minutes lineage ledger collection');
+        for (const record of collection)
+            assertDigest(record, 'lineage record');
+    }
+}
+function serializeLedger(ledger) {
+    return `${JSON.stringify(ledger, null, 2)}\n`;
+}
+function withDigest(record) {
+    return { ...record, digest: digestJson({ ...record, digest: '' }) };
+}
+function assertDigest(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.digest !== 'string') {
+        throw new MeetingMinutesLineageError('corrupt_record', `${label} is malformed`);
+    }
+    const record = value;
+    if (digestJson({ ...record, digest: '' }) !== record.digest)
+        throw new MeetingMinutesLineageError('corrupt_record', `${label} digest does not match`);
+}
+function sameMinutesReference(left, right) {
+    return sameJson(normalizeMinutesReference(left), normalizeMinutesReference(right));
+}
+function sameTarget(left, right) {
+    return sameJson(normalizeTarget(left), normalizeTarget(right));
+}
+function digestJson(value) {
+    return `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+}
+function sameJson(left, right) {
+    return canonicalJson(left) === canonicalJson(right);
+}
+function canonicalJson(value) {
+    assertJsonValue(value);
+    return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortJson);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, sortJson(entry)]));
+    }
+    return value;
+}
+function assertJsonValue(value, path = 'value') {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (Number.isFinite(value))
+            return;
+        throw new MeetingMinutesLineageError('invalid_input', `${path} must be finite`);
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => assertJsonValue(entry, `${path}[${index}]`));
+        return;
+    }
+    if (typeof value === 'object') {
+        if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+            throw new MeetingMinutesLineageError('invalid_input', `${path} must be JSON data`);
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === undefined)
+                throw new MeetingMinutesLineageError('invalid_input', `${path}.${key} cannot be undefined`);
+            assertJsonValue(entry, `${path}.${key}`);
+        }
+        return;
+    }
+    throw new MeetingMinutesLineageError('invalid_input', `${path} must be JSON data`);
+}
+function cloneJson(value) {
+    assertJsonValue(value);
+    return JSON.parse(JSON.stringify(value));
+}
+function assertAccess(value) {
+    if (!value || typeof value !== 'object')
+        throw new MeetingMinutesLineageError('authorization_denied', 'Current access context is required');
+    return { ...value, principal: requireId(value.principal, 'access principal') };
+}
+function statusFromError(error) {
+    if (error instanceof MeetingMinutesLineageError) {
+        if (error.code === 'authorization_denied')
+            return { status: 'denied', reason: error.code };
+        return { status: 'unavailable', reason: error.code };
+    }
+    return { status: 'unavailable', reason: 'provider_unavailable' };
+}
+function mapProviderError(error, fallback, notFoundCode = 'source_not_found') {
+    if (error instanceof MeetingMinutesLineageError)
+        return error;
+    const code = typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : '';
+    if (code === 'authorization_denied' || code === 'forbidden' || code === 'permission_denied')
+        return new MeetingMinutesLineageError('authorization_denied', fallback);
+    if (code === 'not_found' || code === 'source_not_found' || code === 'task_not_found')
+        return new MeetingMinutesLineageError(notFoundCode, fallback);
+    if (code === 'integrity_mismatch' || code === 'revision_conflict' || code === 'readback_mismatch')
+        return new MeetingMinutesLineageError(code, fallback);
+    return new MeetingMinutesLineageError(notFoundCode === 'target_unavailable' ? 'target_unavailable' : 'source_unavailable', fallback);
+}
+/**
+ * Provider calls use the candidate identity as their idempotency boundary.
+ * The request key belongs to the HTTP/transport attempt and may change when a
+ * caller retries after a lost response.  Reusing the candidate key lets a
+ * provider recover the same canonical target instead of creating a second
+ * judgment or Task during that retry window.
+ */
+function providerIdempotencyKey(kind, candidate) {
+    return `meeting-minutes:${kind}:${candidate.id}`;
+}
+function requireId(value, label) {
+    return requireString(value, label, true);
+}
+function requireString(value, label, trim = false) {
+    if (typeof value !== 'string')
+        throw new MeetingMinutesLineageError('invalid_input', `${label} must be a string`);
+    const result = trim ? value.normalize('NFKC').trim() : value;
+    if (!result)
+        throw new MeetingMinutesLineageError('invalid_input', `${label} is required`);
+    if (/^[\u0000-\u001f\u007f]/u.test(result))
+        throw new MeetingMinutesLineageError('invalid_input', `${label} contains control characters`);
+    return result;
+}
+function requireDigest(value, label) {
+    const result = requireString(value, label, true);
+    if (!/^[a-z0-9][a-z0-9._:-]{3,}$/iu.test(result))
+        throw new MeetingMinutesLineageError('invalid_input', `${label} must be a stable digest`);
+    return result;
+}
+function requireEnum(value, allowed, label) {
+    if (typeof value !== 'string' || !allowed.includes(value))
+        throw new MeetingMinutesLineageError('invalid_input', `${label} is invalid`);
+    return value;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}