@unson/brainbase-mcp 0.5.0 → 0.7.0

package/dist/problem-candidates.js

@@ -0,0 +1,898 @@
+import { createHash } from 'node:crypto';
+import { findFoundationRecord, findLatestFoundationRecord, foundationCatalogOrEmpty } from './foundation-catalog.js';
+import { loadPersonalOs, mutatePersonalOsWithSidecar, readPersonalOsSidecar } from './ssot.js';
+/**
+ * Problem candidates are evidence-sidecar records. They are deliberately not
+ * Graph entities: a candidate is a reviewable input to problem selection, not
+ * an approved problem or a canonical fact.
+ */
+export const PROBLEM_CANDIDATES_CONTRACT_VERSION = 'problem-candidates.v1';
+export const PROBLEM_CANDIDATE_CATALOG_VERSION = 1;
+export const PROBLEM_CANDIDATES_SIDECAR = 'evidence/problem-candidates.json';
+export class ProblemCandidateStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ProblemCandidateStoreError';
+        this.code = code;
+    }
+}
+/**
+ * Validates, clones, and freezes a candidate input. The function is also a
+ * pure contract surface for providers that want to validate before storage.
+ */
+export function normalizeProblemCandidate(input) {
+    if (!isRecord(input))
+        throw invalid('candidate must be an object');
+    assertOnlyKeys(input, [
+        'acl', 'createdAt', 'deadline', 'event', 'expectedEffect', 'id', 'kind',
+        'mergedFrom', 'observedGap', 'objectiveRefs', 'opportunity', 'ownerScope',
+        'requiredResources', 'responsibleId', 'statement', 'status', 'threat', 'uncertainty'
+    ], 'candidate');
+    const id = requireIdentifier(input.id, 'id');
+    const kind = requireCandidateKind(input.kind, 'kind');
+    const statement = requireText(input.statement, 'statement');
+    if (!Array.isArray(input.objectiveRefs) || input.objectiveRefs.length === 0) {
+        throw invalid('objectiveRefs must contain at least one Objective revision');
+    }
+    const objectiveRefs = input.objectiveRefs.map((reference, index) => normalizeObjectiveReference(reference, `objectiveRefs[${index}]`));
+    assertUnique(objectiveRefs.map((reference) => `${reference.id}@${reference.revision}`), 'objectiveRefs');
+    const event = normalizeEvent(input.event);
+    const ownerScope = normalizeScope(input.ownerScope, 'ownerScope', true);
+    const acl = normalizeAcl(input.acl, 'acl');
+    const normalized = {
+        id,
+        kind,
+        statement,
+        objectiveRefs,
+        event,
+        observedGap: normalizeTextField(input.observedGap, 'observedGap'),
+        opportunity: normalizeTextField(input.opportunity, 'opportunity'),
+        threat: normalizeTextField(input.threat, 'threat'),
+        uncertainty: normalizeTextField(input.uncertainty, 'uncertainty'),
+        deadline: normalizeDeadlineField(input.deadline, 'deadline'),
+        expectedEffect: normalizeTextField(input.expectedEffect, 'expectedEffect'),
+        requiredResources: normalizeResourceField(input.requiredResources, 'requiredResources'),
+        responsibleId: normalizeTextField(input.responsibleId, 'responsibleId'),
+        ownerScope,
+        acl,
+        ...(input.mergedFrom === undefined ? {} : { mergedFrom: normalizeIdentifiers(input.mergedFrom, 'mergedFrom') }),
+        ...(input.createdAt === undefined ? {} : { createdAt: requireIsoTimestamp(input.createdAt, 'createdAt') }),
+        ...(input.status === undefined ? {} : { status: normalizeCandidateStatus(input.status, 'status') })
+    };
+    if (normalized.createdAt !== undefined && Date.parse(normalized.createdAt) < Date.parse(event.recordedAt)) {
+        throw invalid('createdAt cannot precede event.recordedAt');
+    }
+    if (normalized.status !== undefined && normalized.status !== 'candidate') {
+        throw invalid('candidate input cannot select or approve a candidate');
+    }
+    return deepFreeze(normalized);
+}
+/** Returns validation without throwing, useful for contract fixtures. */
+export function validateProblemCandidate(input) {
+    try {
+        normalizeProblemCandidate(input);
+        return { valid: true, issues: [] };
+    }
+    catch (error) {
+        return { valid: false, issues: [formatError(error)] };
+    }
+}
+export function createProblemCandidateStore(options) {
+    if (!options || !isNonEmptyString(options.dataDir)) {
+        throw new ProblemCandidateStoreError('invalid_input', 'dataDir is required');
+    }
+    if (!options.foundationStore || typeof options.foundationStore.read !== 'function') {
+        throw new ProblemCandidateStoreError('invalid_input', 'foundationStore with read is required');
+    }
+    if (!options.evidenceAccessProvider || typeof options.evidenceAccessProvider.authorize !== 'function') {
+        throw new ProblemCandidateStoreError('invalid_input', 'evidenceAccessProvider.authorize is required');
+    }
+    return new GraphProblemCandidateStore(options.dataDir, options.foundationStore, options.evidenceAccessProvider);
+}
+class GraphProblemCandidateStore {
+    dataDir;
+    foundationStore;
+    evidenceAccessProvider;
+    constructor(dataDir, foundationStore, evidenceAccessProvider) {
+        this.dataDir = dataDir;
+        this.foundationStore = foundationStore;
+        this.evidenceAccessProvider = evidenceAccessProvider;
+    }
+    async saveCandidate(input, context) {
+        assertContext(context);
+        const candidate = normalizeProblemCandidate(input);
+        if (candidate.mergedFrom !== undefined && candidate.mergedFrom.length > 0) {
+            throw new ProblemCandidateStoreError('invalid_input', 'Use mergeCandidates to retain merge provenance');
+        }
+        const objectiveRecords = await this.readObjectives(candidate.objectiveRefs, context);
+        assertCandidateWrite(candidate, context);
+        let committed;
+        await this.mutateCatalog(async (catalog, current) => {
+            assertObjectivesAtAggregate(current, candidate.objectiveRefs, objectiveRecords, context);
+            await this.authorizeEvidence(candidate.event.sourceRefs, context, 'save');
+            const payloadDigest = digestCandidateInput(candidate);
+            const existingEvent = catalog.events.find((event) => event.eventId === candidate.event.id);
+            if (existingEvent !== undefined) {
+                if (existingEvent.payloadDigest !== payloadDigest) {
+                    throw new ProblemCandidateStoreError('event_conflict', `Event ${candidate.event.id} was already ingested with a different payload`);
+                }
+                const existing = catalog.candidates.find((item) => item.id === existingEvent.candidateId);
+                if (!existing)
+                    throw new ProblemCandidateStoreError('corrupt_record', `Event ${candidate.event.id} points to a missing candidate`);
+                assertCandidateRead(existing, context);
+                await this.authorizeCandidateEvidence(catalog, existing, context, 'read');
+                committed = cloneCandidate(existing);
+                return catalog;
+            }
+            if (catalog.candidates.some((item) => item.id === candidate.id)) {
+                throw new ProblemCandidateStoreError('revision_conflict', `Candidate ${candidate.id} already exists`);
+            }
+            const record = makeCandidateRecord(candidate, payloadDigest, []);
+            committed = record;
+            return {
+                version: PROBLEM_CANDIDATE_CATALOG_VERSION,
+                candidates: [...catalog.candidates, record],
+                events: [...catalog.events, { eventId: candidate.event.id, payloadDigest, candidateId: candidate.id }]
+            };
+        });
+        if (!committed)
+            throw new ProblemCandidateStoreError('readback_mismatch', 'Candidate commit did not produce a record');
+        const readback = await this.readCandidate(committed.id, context);
+        if (!readback)
+            throw new ProblemCandidateStoreError('readback_mismatch', `Candidate ${committed.id} was not readable after commit`);
+        return readback;
+    }
+    async saveProblemCandidate(input, context) {
+        return this.saveCandidate(input, context);
+    }
+    async mergeCandidates(input, context) {
+        assertContext(context);
+        if (!Array.isArray(input.sourceCandidateIds) || input.sourceCandidateIds.length === 0) {
+            throw new ProblemCandidateStoreError('invalid_input', 'sourceCandidateIds must contain at least one candidate');
+        }
+        const sourceCandidateIds = normalizeIdentifiers(input.sourceCandidateIds, 'sourceCandidateIds');
+        const { sourceCandidateIds: _sourceCandidateIds, ...candidateInput } = input;
+        void _sourceCandidateIds;
+        const candidate = normalizeProblemCandidate({ ...candidateInput, mergedFrom: sourceCandidateIds });
+        if (candidate.id && sourceCandidateIds.includes(candidate.id)) {
+            throw new ProblemCandidateStoreError('invalid_input', 'A merged candidate cannot include itself as a source');
+        }
+        const objectiveRecords = await this.readObjectives(candidate.objectiveRefs, context);
+        assertCandidateWrite(candidate, context);
+        let committed;
+        await this.mutateCatalog(async (catalog, current) => {
+            assertObjectivesAtAggregate(current, candidate.objectiveRefs, objectiveRecords, context);
+            await this.authorizeEvidence(candidate.event.sourceRefs, context, 'save');
+            const payloadDigest = digestCandidateInput(candidate);
+            const existingEvent = catalog.events.find((event) => event.eventId === candidate.event.id);
+            if (existingEvent !== undefined) {
+                if (existingEvent.payloadDigest !== payloadDigest) {
+                    throw new ProblemCandidateStoreError('event_conflict', `Event ${candidate.event.id} was already ingested with a different payload`);
+                }
+                const existing = catalog.candidates.find((item) => item.id === existingEvent.candidateId);
+                if (!existing)
+                    throw new ProblemCandidateStoreError('corrupt_record', `Event ${candidate.event.id} points to a missing candidate`);
+                assertCandidateRead(existing, context);
+                await this.authorizeCandidateEvidence(catalog, existing, context, 'read');
+                committed = cloneCandidate(existing);
+                return catalog;
+            }
+            if (catalog.candidates.some((item) => item.id === candidate.id)) {
+                throw new ProblemCandidateStoreError('revision_conflict', `Candidate ${candidate.id} already exists`);
+            }
+            const sources = sourceCandidateIds.map((id) => {
+                const source = catalog.candidates.find((item) => item.id === id);
+                if (!source)
+                    throw new ProblemCandidateStoreError('not_found', `Merge source candidate ${id} was not found`);
+                assertCandidateWrite(source, context);
+                assertCandidateScope(source, context);
+                if (source.status !== 'candidate') {
+                    throw new ProblemCandidateStoreError('invalid_input', `Candidate ${id} is already ${source.status}`);
+                }
+                return source;
+            });
+            for (const source of sources) {
+                await this.authorizeCandidateEvidence(catalog, source, context, 'save');
+            }
+            const record = makeCandidateRecord(candidate, payloadDigest, sourceCandidateIds);
+            committed = record;
+            const mergedAt = candidate.event.recordedAt;
+            const sourceSet = new Set(sourceCandidateIds);
+            const candidates = catalog.candidates.map((source) => sourceSet.has(source.id)
+                ? cloneCandidate({ ...source, status: 'merged', updatedAt: mergedAt })
+                : source);
+            // Keep the source resolution above as a deliberate assertion inside the lock.
+            void sources;
+            return {
+                version: PROBLEM_CANDIDATE_CATALOG_VERSION,
+                candidates: [...candidates, record],
+                events: [...catalog.events, { eventId: candidate.event.id, payloadDigest, candidateId: candidate.id }]
+            };
+        });
+        if (!committed)
+            throw new ProblemCandidateStoreError('readback_mismatch', 'Candidate merge did not produce a record');
+        const readback = await this.readCandidate(committed.id, context);
+        if (!readback)
+            throw new ProblemCandidateStoreError('readback_mismatch', `Candidate ${committed.id} was not readable after merge`);
+        return readback;
+    }
+    async readCandidate(id, context) {
+        assertContext(context);
+        const candidateId = requireIdentifier(id, 'id');
+        const catalog = await this.loadCatalog();
+        const candidate = catalog.candidates.find((item) => item.id === candidateId);
+        if (!candidate)
+            return null;
+        assertCandidateRead(candidate, context);
+        await this.authorizeCandidateEvidence(catalog, candidate, context, 'read');
+        await this.readObjectives(candidate.objectiveRefs, context);
+        return cloneCandidate(candidate);
+    }
+    async listCandidates(query, context) {
+        assertContext(context);
+        const normalizedQuery = normalizeQuery(query);
+        const catalog = await this.loadCatalog();
+        const visible = [];
+        for (const candidate of catalog.candidates) {
+            if (!matchesQuery(candidate, normalizedQuery))
+                continue;
+            try {
+                const readback = await this.readCandidate(candidate.id, context);
+                if (readback)
+                    visible.push(readback);
+            }
+            catch (error) {
+                const code = errorCode(error);
+                if (code === 'authorization_denied' || code === 'scope_violation')
+                    continue;
+                throw error;
+            }
+        }
+        return Object.freeze(visible);
+    }
+    async readObjectives(references, context) {
+        const records = [];
+        for (const reference of references) {
+            let record;
+            try {
+                record = await this.foundationStore.read(reference, context);
+            }
+            catch (error) {
+                throw mapFoundationError(error, reference);
+            }
+            if (!record) {
+                throw new ProblemCandidateStoreError('not_found', `Objective ${reference.id}@${reference.revision} was not found`);
+            }
+            if (record.definition.type !== 'objective') {
+                throw new ProblemCandidateStoreError('corrupt_record', `Candidate references non-Objective ${reference.id}`);
+            }
+            if (record.digest !== reference.digest) {
+                throw new ProblemCandidateStoreError('revision_conflict', `Objective ${reference.id}@${reference.revision} digest does not match the candidate reference`);
+            }
+            records.push({ reference, digest: record.digest });
+        }
+        return records;
+    }
+    async authorizeCandidateEvidence(catalog, candidate, context, operation) {
+        const sources = collectCandidateSourceRefs(catalog, candidate);
+        await this.authorizeEvidence(sources, context, operation);
+    }
+    async authorizeEvidence(sources, context, operation) {
+        for (const source of sources) {
+            try {
+                const allowed = await this.evidenceAccessProvider.authorize({ operation, context, source });
+                if (allowed === false) {
+                    throw new ProblemCandidateStoreError('authorization_denied', `Current evidence access was denied for ${source.kind}/${source.id}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof ProblemCandidateStoreError)
+                    throw error;
+                throw new ProblemCandidateStoreError('authorization_denied', `Current evidence access could not be verified for ${source.kind}/${source.id}`);
+            }
+        }
+    }
+    async loadCatalog() {
+        try {
+            const os = await loadPersonalOs(this.dataDir);
+            if (os.graph.version !== 2) {
+                throw new ProblemCandidateStoreError('unsupported_graph', 'Problem candidates require canonical Graph v2');
+            }
+            return parseCatalog(await readPersonalOsSidecar(this.dataDir, PROBLEM_CANDIDATES_SIDECAR));
+        }
+        catch (error) {
+            if (error instanceof ProblemCandidateStoreError)
+                throw error;
+            throw new ProblemCandidateStoreError('corrupt_record', formatError(error));
+        }
+    }
+    async mutateCatalog(mutator) {
+        await mutatePersonalOsWithSidecar(this.dataDir, PROBLEM_CANDIDATES_SIDECAR, async (current, existingContent) => {
+            if (current.graph.version !== 2) {
+                throw new ProblemCandidateStoreError('unsupported_graph', 'Problem candidates require canonical Graph v2');
+            }
+            // The callback already owns the SSOT lock. Parse the supplied sidecar
+            // content instead of calling readPersonalOsSidecar or FoundationStore.
+            const catalog = parseCatalog(existingContent);
+            const next = await mutator(catalog, current);
+            assertCatalog(next);
+            return {
+                next: current,
+                sidecarContent: `${JSON.stringify(next, null, 2)}\n`,
+                result: undefined
+            };
+        });
+    }
+}
+function assertObjectivesAtAggregate(current, references, expected, context) {
+    if (current.graph.version !== 2) {
+        throw new ProblemCandidateStoreError('unsupported_graph', 'Problem candidates require canonical Graph v2');
+    }
+    const catalog = foundationCatalogOrEmpty(current.graph.foundation);
+    for (const item of expected) {
+        const actual = findFoundationRecord(catalog, item.reference);
+        const latest = findLatestFoundationRecord(catalog, 'objective', item.reference.id);
+        if (!actual)
+            throw new ProblemCandidateStoreError('not_found', `Objective ${item.reference.id}@${item.reference.revision} disappeared before commit`);
+        if (!latest || latest.definition.type !== 'objective') {
+            throw new ProblemCandidateStoreError('corrupt_record', `Objective ${item.reference.id} has no valid latest revision`);
+        }
+        if (actual.definition.type !== 'objective') {
+            throw new ProblemCandidateStoreError('corrupt_record', `Candidate references non-Objective ${item.reference.id}`);
+        }
+        if (actual.digest !== item.digest || actual.digest !== item.reference.digest) {
+            throw new ProblemCandidateStoreError('revision_conflict', `Objective ${item.reference.id}@${item.reference.revision} changed before candidate commit`);
+        }
+        assertAclRead(latest.definition, context.principal);
+        assertScopeAccess(latest.definition, context);
+    }
+    // Keep this check explicit so callers cannot accidentally pass an expectation
+    // for a different Objective set when adding a future resolver.
+    if (references.length !== expected.length) {
+        throw new ProblemCandidateStoreError('corrupt_record', 'Objective resolution set is incomplete');
+    }
+}
+function makeCandidateRecord(input, payloadDigest, mergedFrom) {
+    const recordedAt = input.event.recordedAt;
+    return deepFreeze({
+        contractVersion: PROBLEM_CANDIDATES_CONTRACT_VERSION,
+        id: input.id,
+        kind: input.kind,
+        statement: input.statement,
+        objectiveRefs: input.objectiveRefs,
+        event: input.event,
+        observedGap: input.observedGap,
+        opportunity: input.opportunity,
+        threat: input.threat,
+        uncertainty: input.uncertainty,
+        deadline: input.deadline,
+        expectedEffect: input.expectedEffect,
+        requiredResources: input.requiredResources,
+        responsibleId: input.responsibleId,
+        ownerScope: input.ownerScope,
+        acl: input.acl,
+        status: 'candidate',
+        mergedFrom: [...mergedFrom],
+        createdAt: input.createdAt ?? recordedAt,
+        updatedAt: recordedAt,
+        provenance: {
+            eventIds: [input.event.id],
+            sourceRefs: input.event.sourceRefs,
+            candidateIds: [...mergedFrom]
+        },
+        payloadDigest
+    });
+}
+function digestCandidateInput(input) {
+    return `sha256:${createHash('sha256').update(canonicalJson({
+        id: input.id,
+        kind: input.kind,
+        statement: input.statement,
+        objectiveRefs: input.objectiveRefs,
+        event: input.event,
+        observedGap: input.observedGap,
+        opportunity: input.opportunity,
+        threat: input.threat,
+        uncertainty: input.uncertainty,
+        deadline: input.deadline,
+        expectedEffect: input.expectedEffect,
+        requiredResources: input.requiredResources,
+        responsibleId: input.responsibleId,
+        ownerScope: input.ownerScope,
+        acl: input.acl,
+        mergedFrom: input.mergedFrom ?? []
+    }), 'utf8').digest('hex')}`;
+}
+function parseCatalog(rawText) {
+    if (rawText === undefined)
+        return emptyCatalog();
+    try {
+        const raw = JSON.parse(rawText);
+        assertCatalog(raw);
+        return cloneCatalog(raw);
+    }
+    catch (error) {
+        if (error instanceof ProblemCandidateStoreError)
+            throw error;
+        throw new ProblemCandidateStoreError('corrupt_record', formatError(error));
+    }
+}
+function assertCatalog(value) {
+    if (!isRecord(value) || value.version !== PROBLEM_CANDIDATE_CATALOG_VERSION
+        || !Array.isArray(value.candidates) || !Array.isArray(value.events)) {
+        throw new ProblemCandidateStoreError('corrupt_record', 'Problem candidate sidecar requires version 1 candidates and events arrays');
+    }
+    const candidateIds = new Set();
+    const eventIds = new Set();
+    for (const raw of value.candidates) {
+        const candidate = normalizeStoredCandidate(raw);
+        if (candidateIds.has(candidate.id))
+            throw new ProblemCandidateStoreError('corrupt_record', `Duplicate candidate ${candidate.id}`);
+        candidateIds.add(candidate.id);
+        if (eventIds.has(candidate.event.id))
+            throw new ProblemCandidateStoreError('corrupt_record', `Duplicate event ${candidate.event.id}`);
+        eventIds.add(candidate.event.id);
+    }
+    const ledgerEventIds = new Set();
+    const ledgerCandidateIds = new Set();
+    for (const raw of value.events) {
+        if (!isRecord(raw) || !isNonEmptyString(raw.eventId) || !isNonEmptyString(raw.candidateId) || !isDigest(raw.payloadDigest)) {
+            throw new ProblemCandidateStoreError('corrupt_record', 'Problem candidate event ledger entry is malformed');
+        }
+        if (ledgerEventIds.has(raw.eventId) || ledgerCandidateIds.has(raw.candidateId)) {
+            throw new ProblemCandidateStoreError('corrupt_record', `Duplicate event ledger entry for ${raw.eventId}`);
+        }
+        ledgerEventIds.add(raw.eventId);
+        ledgerCandidateIds.add(raw.candidateId);
+        if (eventIds.has(raw.eventId)) {
+            const candidateRaw = value.candidates.find((item) => isRecord(item) && isRecord(item.event) && item.event.id === raw.eventId);
+            if (!isRecord(candidateRaw) || candidateRaw.id !== raw.candidateId || candidateRaw.payloadDigest !== raw.payloadDigest) {
+                throw new ProblemCandidateStoreError('corrupt_record', `Event ledger mismatch for ${raw.eventId}`);
+            }
+        }
+        else {
+            throw new ProblemCandidateStoreError('corrupt_record', `Event ledger ${raw.eventId} has no candidate`);
+        }
+    }
+    if (value.events.length !== value.candidates.length) {
+        throw new ProblemCandidateStoreError('corrupt_record', 'Every candidate event must have exactly one idempotency ledger entry');
+    }
+    if (ledgerEventIds.size !== eventIds.size || ledgerCandidateIds.size !== candidateIds.size) {
+        throw new ProblemCandidateStoreError('corrupt_record', 'Problem candidate event ledger is incomplete');
+    }
+}
+function normalizeStoredCandidate(value) {
+    if (!isRecord(value))
+        throw new ProblemCandidateStoreError('corrupt_record', 'Problem candidate record is not an object');
+    assertOnlyKeys(value, [
+        'acl', 'contractVersion', 'createdAt', 'deadline', 'event', 'expectedEffect', 'id', 'kind',
+        'mergedFrom', 'observedGap', 'objectiveRefs', 'opportunity', 'ownerScope', 'provenance',
+        'payloadDigest', 'requiredResources', 'responsibleId', 'statement', 'status', 'threat',
+        'uncertainty', 'updatedAt'
+    ], 'stored candidate');
+    if (value.contractVersion !== PROBLEM_CANDIDATES_CONTRACT_VERSION
+        || !isDigest(value.payloadDigest)
+        || !isIsoTimestamp(value.createdAt)
+        || !isIsoTimestamp(value.updatedAt)
+        || !Array.isArray(value.mergedFrom)
+        || !isRecord(value.provenance)
+        || !Array.isArray(value.provenance.eventIds)
+        || !Array.isArray(value.provenance.sourceRefs)
+        || !Array.isArray(value.provenance.candidateIds)) {
+        throw new ProblemCandidateStoreError('corrupt_record', 'Stored problem candidate metadata is malformed');
+    }
+    const input = normalizeProblemCandidate({
+        id: value.id,
+        kind: value.kind,
+        statement: value.statement,
+        objectiveRefs: value.objectiveRefs,
+        event: value.event,
+        observedGap: value.observedGap,
+        opportunity: value.opportunity,
+        threat: value.threat,
+        uncertainty: value.uncertainty,
+        deadline: value.deadline,
+        expectedEffect: value.expectedEffect,
+        requiredResources: value.requiredResources,
+        responsibleId: value.responsibleId,
+        ownerScope: value.ownerScope,
+        acl: value.acl,
+        mergedFrom: value.mergedFrom,
+        createdAt: value.createdAt,
+        // Stored records may be merged/dismissed. The input normalizer validates
+        // the candidate payload; the lifecycle status is checked separately below.
+    });
+    const status = normalizeCandidateStatus(value.status, 'status');
+    if (!isIsoTimestamp(value.updatedAt))
+        throw new ProblemCandidateStoreError('corrupt_record', 'updatedAt is invalid');
+    const sourceRefs = value.provenance.sourceRefs.map((source, index) => normalizeSourceRef(source, `provenance.sourceRefs[${index}]`));
+    const eventIds = normalizeIdentifiers(value.provenance.eventIds, 'provenance.eventIds');
+    const candidateIds = normalizeIdentifiers(value.provenance.candidateIds, 'provenance.candidateIds');
+    if (eventIds.length !== 1 || eventIds[0] !== input.event.id)
+        throw new ProblemCandidateStoreError('corrupt_record', 'Candidate provenance must retain its event id');
+    if (candidateIds.join('\u0000') !== (input.mergedFrom ?? []).join('\u0000'))
+        throw new ProblemCandidateStoreError('corrupt_record', `Candidate ${input.id} merge provenance mismatch`);
+    if (canonicalJson(sourceRefs) !== canonicalJson(input.event.sourceRefs))
+        throw new ProblemCandidateStoreError('corrupt_record', `Candidate ${input.id} source provenance mismatch`);
+    const payloadDigest = digestCandidateInput(input);
+    if (payloadDigest !== value.payloadDigest)
+        throw new ProblemCandidateStoreError('corrupt_record', `Candidate ${input.id} payload digest mismatch`);
+    return deepFreeze({
+        contractVersion: PROBLEM_CANDIDATES_CONTRACT_VERSION,
+        ...input,
+        status,
+        mergedFrom: input.mergedFrom ?? [],
+        createdAt: String(value.createdAt),
+        updatedAt: String(value.updatedAt),
+        provenance: { eventIds, sourceRefs, candidateIds },
+        payloadDigest
+    });
+}
+function cloneCatalog(catalog) {
+    return {
+        version: PROBLEM_CANDIDATE_CATALOG_VERSION,
+        candidates: catalog.candidates.map((candidate) => cloneCandidate(candidate)),
+        events: catalog.events.map((event) => ({ ...event }))
+    };
+}
+function cloneCandidate(candidate) {
+    return deepFreeze(JSON.parse(JSON.stringify(candidate)));
+}
+function emptyCatalog() {
+    return { version: PROBLEM_CANDIDATE_CATALOG_VERSION, candidates: [], events: [] };
+}
+function collectCandidateSourceRefs(catalog, candidate) {
+    const refs = [];
+    const seenSources = new Set();
+    const visitedCandidates = new Set();
+    const visit = (current) => {
+        if (visitedCandidates.has(current.id))
+            return;
+        visitedCandidates.add(current.id);
+        for (const source of current.event.sourceRefs) {
+            const key = `${source.kind}:${source.id}:${source.digest ?? ''}`;
+            if (seenSources.has(key))
+                continue;
+            seenSources.add(key);
+            refs.push(source);
+        }
+        for (const sourceId of current.mergedFrom) {
+            const source = catalog.candidates.find((item) => item.id === sourceId);
+            if (!source) {
+                throw new ProblemCandidateStoreError('corrupt_record', `Candidate ${current.id} points to missing merge source ${sourceId}`);
+            }
+            visit(source);
+        }
+    };
+    visit(candidate);
+    return refs;
+}
+function normalizeEvent(value) {
+    if (!isRecord(value))
+        throw invalid('event must be an object');
+    assertOnlyKeys(value, ['id', 'occurredAt', 'recordedAt', 'sourceRefs'], 'event');
+    const id = requireIdentifier(value.id, 'event.id');
+    const occurredAt = requireIsoTimestamp(value.occurredAt, 'event.occurredAt');
+    const recordedAt = requireIsoTimestamp(value.recordedAt, 'event.recordedAt');
+    if (Date.parse(recordedAt) < Date.parse(occurredAt))
+        throw invalid('event.recordedAt cannot precede event.occurredAt');
+    if (!Array.isArray(value.sourceRefs) || value.sourceRefs.length === 0)
+        throw invalid('event.sourceRefs must contain at least one source reference');
+    const sourceRefs = value.sourceRefs.map((source, index) => normalizeSourceRef(source, `event.sourceRefs[${index}]`));
+    assertUnique(sourceRefs.map((source) => `${source.kind}:${source.id}`), 'event.sourceRefs');
+    return deepFreeze({ id, occurredAt, recordedAt, sourceRefs });
+}
+function normalizeObjectiveReference(value, label) {
+    if (!isRecord(value)
+        || value.type !== 'objective'
+        || !isNonEmptyString(value.id)
+        || !isPositiveRevision(value.revision)
+        || !isDigest(value.digest)) {
+        throw invalid(`${label} must contain objective id, positive revision, and sha256 digest`);
+    }
+    return deepFreeze({ id: String(value.id).trim(), type: 'objective', revision: String(value.revision), digest: value.digest });
+}
+function normalizeSourceRef(value, label) {
+    if (!isRecord(value))
+        throw invalid(`${label} must be an object`);
+    assertOnlyKeys(value, ['digest', 'id', 'kind'], label);
+    if (!isNonEmptyString(value.id) || !isSourceKind(value.kind) || (value.digest !== undefined && !isDigest(value.digest))) {
+        throw invalid(`${label} must contain a source id, supported kind, and optional sha256 digest`);
+    }
+    return deepFreeze({
+        id: String(value.id).trim(),
+        kind: value.kind,
+        ...(value.digest === undefined ? {} : { digest: value.digest })
+    });
+}
+function normalizeTextField(value, label) {
+    if (!isRecord(value) || !['known', 'unknown'].includes(String(value.status)))
+        throw invalid(`${label} must be known or unknown`);
+    assertOnlyKeys(value, ['status', 'value', 'reason'], label);
+    if (value.status === 'unknown')
+        return deepFreeze({ status: 'unknown', reason: requireText(value.reason, `${label}.reason`) });
+    if (!isNonEmptyString(value.value))
+        throw invalid(`${label}.value must be non-empty when known`);
+    return deepFreeze({ status: 'known', value: String(value.value) });
+}
+function normalizeDeadlineField(value, label) {
+    if (!isRecord(value) || !['known', 'unknown'].includes(String(value.status)))
+        throw invalid(`${label} must be known or unknown`);
+    assertOnlyKeys(value, ['status', 'value', 'reason'], label);
+    if (value.status === 'unknown')
+        return deepFreeze({ status: 'unknown', reason: requireText(value.reason, `${label}.reason`) });
+    if (!isRecord(value.value))
+        throw invalid(`${label}.value must be an object when known`);
+    assertOnlyKeys(value.value, ['dueAt', 'evaluationAt'], `${label}.value`);
+    const dueAt = requireIsoTimestamp(value.value.dueAt, `${label}.value.dueAt`);
+    const evaluationAt = value.value.evaluationAt === undefined
+        ? undefined
+        : requireIsoTimestamp(value.value.evaluationAt, `${label}.value.evaluationAt`);
+    return deepFreeze({ status: 'known', value: { dueAt, ...(evaluationAt === undefined ? {} : { evaluationAt }) } });
+}
+function normalizeResourceField(value, label) {
+    if (!isRecord(value) || !['known', 'unknown'].includes(String(value.status)))
+        throw invalid(`${label} must be known or unknown`);
+    assertOnlyKeys(value, ['status', 'value', 'reason'], label);
+    if (value.status === 'unknown')
+        return deepFreeze({ status: 'unknown', reason: requireText(value.reason, `${label}.reason`) });
+    if (!Array.isArray(value.value))
+        throw invalid(`${label}.value must be an array when known`);
+    const resources = value.value.map((resource, index) => {
+        if (!isRecord(resource))
+            throw invalid(`${label}.value[${index}] must be an object`);
+        assertOnlyKeys(resource, ['id', 'kind', 'quantity', 'unit'], `${label}.value[${index}]`);
+        if (!isNonEmptyString(resource.id) || !isNonEmptyString(resource.kind))
+            throw invalid(`${label}.value[${index}] id and kind are required`);
+        if (resource.quantity !== undefined && (typeof resource.quantity !== 'number' || !Number.isFinite(resource.quantity) || resource.quantity < 0)) {
+            throw invalid(`${label}.value[${index}].quantity must be a finite non-negative number`);
+        }
+        if (resource.unit !== undefined && !isNonEmptyString(resource.unit))
+            throw invalid(`${label}.value[${index}].unit must be non-empty`);
+        return {
+            id: String(resource.id).trim(),
+            kind: String(resource.kind).trim(),
+            ...(resource.quantity === undefined ? {} : { quantity: resource.quantity }),
+            ...(resource.unit === undefined ? {} : { unit: String(resource.unit).trim() })
+        };
+    });
+    assertUnique(resources.map((resource) => `${resource.kind}:${resource.id}`), `${label}.value`);
+    return deepFreeze({ status: 'known', value: resources });
+}
+function normalizeScope(value, label, requireSubjects) {
+    if (!isRecord(value) || !Array.isArray(value.subjectIds) || !isIsoTimestamp(value.validFrom)
+        || (value.validUntil !== undefined && !isIsoTimestamp(value.validUntil))) {
+        throw invalid(`${label} is invalid`);
+    }
+    const subjectIds = normalizeIdentifiers(value.subjectIds, `${label}.subjectIds`);
+    if (requireSubjects && subjectIds.length === 0)
+        throw invalid(`${label}.subjectIds must contain at least one subject`);
+    if (value.validUntil !== undefined && Date.parse(value.validUntil) < Date.parse(value.validFrom))
+        throw invalid(`${label}.validUntil precedes validFrom`);
+    return deepFreeze({ subjectIds, validFrom: value.validFrom, ...(value.validUntil === undefined ? {} : { validUntil: value.validUntil }) });
+}
+function normalizeAcl(value, label) {
+    if (!isRecord(value) || !isNonEmptyString(value.ownerId)
+        || !['private', 'project', 'organization', 'public'].includes(String(value.visibility))
+        || !Array.isArray(value.readerIds) || !Array.isArray(value.writerIds)) {
+        throw invalid(`${label} is invalid`);
+    }
+    const readerIds = normalizeIdentifiers(value.readerIds, `${label}.readerIds`);
+    const writerIds = normalizeIdentifiers(value.writerIds, `${label}.writerIds`);
+    const visibility = value.visibility;
+    return deepFreeze({ ownerId: String(value.ownerId).trim(), visibility, readerIds, writerIds });
+}
+function normalizeQuery(query) {
+    if (query === undefined)
+        return {};
+    if (!isRecord(query))
+        throw invalid('query must be an object');
+    assertOnlyKeys(query, ['ownerScope', 'responsibleId', 'status'], 'query');
+    return {
+        ...(query.ownerScope === undefined ? {} : { ownerScope: normalizeScope(query.ownerScope, 'query.ownerScope', true) }),
+        ...(query.responsibleId === undefined ? {} : { responsibleId: requireIdentifier(query.responsibleId, 'query.responsibleId') }),
+        ...(query.status === undefined ? {} : { status: normalizeCandidateStatus(query.status, 'query.status') })
+    };
+}
+function matchesQuery(candidate, query) {
+    if (query.status !== undefined && candidate.status !== query.status)
+        return false;
+    if (query.responsibleId !== undefined && (candidate.responsibleId.status !== 'known' || candidate.responsibleId.value !== query.responsibleId))
+        return false;
+    if (query.ownerScope !== undefined && !scopeContains(query.ownerScope, candidate.ownerScope))
+        return false;
+    return true;
+}
+function assertCandidateWrite(candidate, context) {
+    if (!aclAllowsWrite(candidate.acl, context.principal))
+        throw new ProblemCandidateStoreError('authorization_denied', `Principal ${context.principal} cannot write candidate ${candidate.id}`);
+    assertCandidateScope(candidate, context);
+}
+function assertCandidateRead(candidate, context) {
+    if (!aclAllowsRead(candidate.acl, context.principal))
+        throw new ProblemCandidateStoreError('authorization_denied', `Principal ${context.principal} cannot read candidate ${candidate.id}`);
+    assertCandidateScope(candidate, context);
+}
+function assertCandidateScope(candidate, context) {
+    if (context.scope !== undefined && !scopeContains(context.scope, candidate.ownerScope)) {
+        throw new ProblemCandidateStoreError('scope_violation', `Candidate is outside the trusted scope for ${context.principal}`);
+    }
+}
+function assertAclRead(definition, principal) {
+    if (!aclAllowsRead(definition.acl, principal))
+        throw new ProblemCandidateStoreError('authorization_denied', `Principal ${principal} cannot read Objective ${definition.id}`);
+}
+function assertScopeAccess(definition, context) {
+    if (context.scope !== undefined && !scopeContains(context.scope, definition.scope)) {
+        throw new ProblemCandidateStoreError('scope_violation', `Objective ${definition.id} is outside the trusted scope`);
+    }
+}
+function scopeContains(container, target) {
+    const allowed = new Set(container.subjectIds);
+    if (target.subjectIds.length === 0 || target.subjectIds.some((subjectId) => !allowed.has(subjectId)))
+        return false;
+    if (Date.parse(target.validFrom) < Date.parse(container.validFrom))
+        return false;
+    if (container.validUntil !== undefined) {
+        if (target.validUntil === undefined || Date.parse(target.validUntil) > Date.parse(container.validUntil))
+            return false;
+    }
+    return true;
+}
+function aclAllowsWrite(acl, principal) {
+    return acl.ownerId === principal || acl.writerIds.includes(principal);
+}
+function aclAllowsRead(acl, principal) {
+    return acl.visibility === 'public'
+        || acl.ownerId === principal
+        || acl.readerIds.includes(principal)
+        || acl.writerIds.includes(principal);
+}
+function mapFoundationError(error, reference) {
+    const code = errorCode(error);
+    if (code === 'authorization_denied')
+        return new ProblemCandidateStoreError('authorization_denied', `Objective ${reference.id}@${reference.revision} is not readable`);
+    if (code === 'scope_violation')
+        return new ProblemCandidateStoreError('scope_violation', `Objective ${reference.id}@${reference.revision} is outside the trusted scope`);
+    if (code === 'not_found')
+        return new ProblemCandidateStoreError('not_found', `Objective ${reference.id}@${reference.revision} was not found`);
+    return new ProblemCandidateStoreError('corrupt_record', `Objective resolver failed for ${reference.id}@${reference.revision}: ${formatError(error)}`);
+}
+function assertContext(context) {
+    if (!context || !isNonEmptyString(context.principal))
+        throw new ProblemCandidateStoreError('authorization_denied', 'A trusted principal is required');
+    if (context.scope !== undefined)
+        normalizeScope(context.scope, 'context.scope', false);
+}
+function normalizeCandidateStatus(value, label) {
+    if (value !== 'candidate' && value !== 'merged' && value !== 'dismissed')
+        throw invalid(`${label} must be candidate, merged, or dismissed`);
+    return value;
+}
+function requireCandidateKind(value, label) {
+    if (value !== 'gap' && value !== 'opportunity' && value !== 'threat' && value !== 'uncertainty') {
+        throw invalid(`${label} must be gap, opportunity, threat, or uncertainty`);
+    }
+    return value;
+}
+function isSourceKind(value) {
+    return value === 'event' || value === 'observation' || value === 'document' || value === 'decision'
+        || value === 'import' || value === 'candidate' || value === 'evidence';
+}
+function normalizeIdentifiers(value, label) {
+    if (!Array.isArray(value))
+        throw invalid(`${label} must be an array`);
+    const identifiers = value.map((item, index) => requireIdentifier(item, `${label}[${index}]`));
+    assertUnique(identifiers, label);
+    return identifiers;
+}
+function assertUnique(values, label) {
+    if (new Set(values).size !== values.length)
+        throw invalid(`${label} must not contain duplicates`);
+}
+function assertOnlyKeys(value, allowed, label) {
+    const allowedSet = new Set(allowed);
+    const unexpected = Object.keys(value).filter((key) => !allowedSet.has(key));
+    if (unexpected.length > 0)
+        throw invalid(`${label} contains unsupported field(s): ${unexpected.join(', ')}`);
+}
+function requireIdentifier(value, label) {
+    if (!isNonEmptyString(value) || value.includes('\0'))
+        throw invalid(`${label} must be a non-empty identifier`);
+    return value.trim();
+}
+function requireText(value, label) {
+    if (!isNonEmptyString(value))
+        throw invalid(`${label} must be non-empty text`);
+    return value.trim();
+}
+function requireIsoTimestamp(value, label) {
+    if (!isIsoTimestamp(value))
+        throw invalid(`${label} must be an ISO timestamp`);
+    return value;
+}
+function isIsoTimestamp(value) {
+    if (typeof value !== 'string')
+        return false;
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|[+-](\d{2}):(\d{2}))$/.exec(value);
+    if (!match)
+        return false;
+    const [, yearText, monthText, dayText, hourText, minuteText, secondText, , zone, offsetHourText, offsetMinuteText] = match;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const day = Number(dayText);
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const second = Number(secondText);
+    const offsetHour = zone === 'Z' ? 0 : Number(offsetHourText);
+    const offsetMinute = zone === 'Z' ? 0 : Number(offsetMinuteText);
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] ?? 0;
+    return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth
+        && hour >= 0 && hour <= 23 && minute >= 0 && minute <= 59 && second >= 0 && second <= 59
+        && offsetHour >= 0 && offsetHour <= 23 && offsetMinute >= 0 && offsetMinute <= 59
+        && Number.isFinite(Date.parse(value));
+}
+function isPositiveRevision(value) {
+    return typeof value === 'string' && /^[1-9]\d*$/.test(value);
+}
+function isDigest(value) {
+    return typeof value === 'string' && /^sha256:[0-9a-f]{64}$/.test(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function invalid(message) {
+    return new ProblemCandidateStoreError('invalid_input', message);
+}
+function errorCode(error) {
+    return error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
+        ? error.code
+        : undefined;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function canonicalJson(value) {
+    const serialized = JSON.stringify(canonicalValue(value));
+    if (serialized === undefined)
+        throw invalid('candidate values must be JSON-compatible');
+    return serialized;
+}
+function canonicalValue(value, active = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw invalid('candidate values must contain finite numbers');
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (typeof value !== 'object')
+        throw invalid('candidate values must be JSON-compatible');
+    if (active.has(value))
+        throw invalid('candidate values must not be cyclic');
+    active.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((item) => canonicalValue(item, active));
+        const result = {};
+        for (const key of Object.keys(value).sort())
+            result[key] = canonicalValue(value[key], active);
+        return result;
+    }
+    finally {
+        active.delete(value);
+    }
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}