@unson/brainbase-mcp 0.5.0 → 0.7.0

package/dist/knowledge-adapter.js

@@ -0,0 +1,691 @@
+import { createHash } from 'node:crypto';
+import { DecisionAdapterError, validateDecisionAdapterConditions } from './decision-adapter.js';
+import { initializePersonalOs, loadPersonalOs, mutatePersonalOsWithSidecar, readPersonalOsSidecar } from './ssot.js';
+/** Common contract for attaching exact judgment conditions to old knowledge records. */
+export const KNOWLEDGE_ADAPTER_VERSION = 'knowledge-condition-adapter.v2';
+/** A read-only compatibility marker for sidecars written by the v1 adapter. */
+export const LEGACY_KNOWLEDGE_ADAPTER_VERSION = 'knowledge-condition-adapter.v1';
+export const KNOWLEDGE_ADAPTER_SIDECAR = 'evidence/knowledge-condition-adapter.json';
+export class KnowledgeAdapterError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'KnowledgeAdapterError';
+        this.code = code;
+    }
+}
+/**
+ * Personal canonical implementation. Knowledge records remain owned by the
+ * host provider; this store only keeps exact condition/provenance references in
+ * a transactional sidecar next to the canonical aggregate.
+ */
+export class GraphKnowledgeConditionAdapter {
+    dataDir;
+    recordPort;
+    adoptionPort;
+    sidecarPath;
+    constructor(options) {
+        if (!options || !options.dataDir)
+            throw new KnowledgeAdapterError('validation_error', 'dataDir is required');
+        if (!options.recordPort || typeof options.recordPort.read !== 'function') {
+            throw new KnowledgeAdapterError('validation_error', 'recordPort with read is required');
+        }
+        this.dataDir = options.dataDir;
+        this.recordPort = options.recordPort;
+        this.adoptionPort = options.adoptionPort;
+        this.sidecarPath = options.sidecarPath ?? KNOWLEDGE_ADAPTER_SIDECAR;
+        assertSidecarPath(this.sidecarPath);
+    }
+    async attach(source, conditions, context, options = {}) {
+        const requestedSource = normalizeSourceReference(source, 'source');
+        const normalizedConditions = normalizeConditions(conditions);
+        assertContext(context);
+        const idempotencyKey = normalizeText(options.idempotency_key ?? `knowledge:${requestedSource.kind}:${requestedSource.id}`, 'idempotency_key', 512);
+        await initializePersonalOs(this.dataDir);
+        const snapshot = await this.loadSnapshot();
+        const sourceRead = await this.readSource(requestedSource, context, 'attach');
+        if (sourceRead.source_status === 'denied' || sourceRead.acl_status !== 'allowed') {
+            throw new KnowledgeAdapterError('authorization_denied', `Knowledge source ${sourceKey(requestedSource)} is not readable`);
+        }
+        if (sourceRead.source_status === 'not_found' || sourceRead.source_status === 'retracted') {
+            throw new KnowledgeAdapterError('source_unavailable', `Knowledge source ${sourceKey(requestedSource)} cannot receive a binding`);
+        }
+        if (sourceRead.source_status !== 'present' && sourceRead.source_status !== 'quarantined') {
+            throw new KnowledgeAdapterError('source_unavailable', `Knowledge source ${sourceKey(requestedSource)} cannot receive a binding`);
+        }
+        const sourceStatusAtAttach = sourceRead.source_status;
+        const exactSource = sourceRead.source;
+        if (!exactSource || !hasExactSourceLocator(exactSource)) {
+            throw new KnowledgeAdapterError('source_unavailable', `Knowledge source ${sourceKey(requestedSource)} did not provide an exact revision and digest`);
+        }
+        assertExpectedSourceLocator(requestedSource, exactSource);
+        const adoption = await this.readAdoption(exactSource, context, 'attach');
+        if (adoption.status === 'denied') {
+            throw new KnowledgeAdapterError('authorization_denied', `Adoption record for ${sourceKey(exactSource)} is not readable`);
+        }
+        const attachedAt = new Date().toISOString();
+        const bindingId = bindingIdFor(exactSource);
+        try {
+            return await mutatePersonalOsWithSidecar(this.dataDir, this.sidecarPath, (current, sidecarContent) => {
+                assertSnapshotUnchanged(snapshot, current, sidecarContent);
+                const sidecar = parseSidecar(sidecarContent);
+                const key = sourceKey(exactSource);
+                const existing = sidecar.bindings[key];
+                if (existing) {
+                    if (!sameBindingPayload(existing, {
+                        idempotency_key: idempotencyKey,
+                        source: exactSource,
+                        conditions: normalizedConditions,
+                        provenance: sourceRead.provenance,
+                        ...(adoption.adoption ? { adoption: adoption.adoption } : {})
+                    })) {
+                        throw new KnowledgeAdapterError('condition_conflict', `Knowledge source ${key} already has a different condition binding`);
+                    }
+                    return {
+                        next: current,
+                        sidecarContent: serializeSidecar(sidecar),
+                        result: makeAttachReceipt(existing, sourceRead, adoption, 'existing')
+                    };
+                }
+                const conflictingKey = Object.keys(sidecar.bindings).find((candidate) => (sidecar.bindings[candidate]?.idempotency_key === idempotencyKey));
+                if (conflictingKey !== undefined) {
+                    throw new KnowledgeAdapterError('condition_conflict', `Idempotency key ${idempotencyKey} is already bound to ${conflictingKey}`);
+                }
+                const stored = {
+                    binding_id: bindingId,
+                    idempotency_key: idempotencyKey,
+                    source: clone(exactSource),
+                    source_status_at_attach: sourceStatusAtAttach,
+                    conditions: clone(normalizedConditions),
+                    provenance: clone(sourceRead.provenance),
+                    ...(adoption.adoption ? { adoption: clone(adoption.adoption) } : {}),
+                    attached_at: attachedAt
+                };
+                const nextSidecar = {
+                    ...sidecar,
+                    bindings: { ...sidecar.bindings, [key]: stored }
+                };
+                assertStagedBinding(nextSidecar, key, stored);
+                return {
+                    next: current,
+                    sidecarContent: serializeSidecar(nextSidecar),
+                    result: makeAttachReceipt(stored, sourceRead, adoption, 'created')
+                };
+            });
+        }
+        catch (error) {
+            if (error instanceof KnowledgeAdapterError)
+                throw error;
+            throw new KnowledgeAdapterError('store_corrupt', formatError(error));
+        }
+    }
+    async read(source, context) {
+        const requestedSource = normalizeSourceReference(source, 'source');
+        assertContext(context);
+        await initializePersonalOs(this.dataDir);
+        let sourceRead;
+        try {
+            sourceRead = await this.readSource(requestedSource, context, 'read');
+        }
+        catch (error) {
+            if (error instanceof KnowledgeAdapterError)
+                throw error;
+            throw new KnowledgeAdapterError('source_unavailable', formatError(error));
+        }
+        if (sourceRead.source_status === 'denied' || sourceRead.acl_status === 'denied') {
+            return {
+                source: requestedSource,
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'denied',
+                provenance: [],
+                adoption_status: 'denied'
+            };
+        }
+        if (sourceRead.acl_status === 'unknown') {
+            return {
+                source: requestedSource,
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'unavailable',
+                provenance: [],
+                adoption_status: 'unavailable'
+            };
+        }
+        if (sourceRead.source_status === 'not_found' || sourceRead.source_status === 'retracted' || !sourceRead.source) {
+            return {
+                source: requestedSource,
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'unavailable',
+                provenance: [],
+                adoption_status: 'unavailable'
+            };
+        }
+        const exactSource = sourceRead.source;
+        if (!hasExactSourceLocator(exactSource)) {
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'unavailable',
+                provenance: clone(sourceRead.provenance),
+                adoption_status: 'unavailable'
+            };
+        }
+        try {
+            assertExpectedSourceLocator(requestedSource, exactSource);
+        }
+        catch {
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'integrity_mismatch',
+                provenance: clone(sourceRead.provenance),
+                adoption_status: 'unavailable'
+            };
+        }
+        const sidecar = await this.loadSidecar();
+        const stored = sidecar.bindings[sourceKey(exactSource)];
+        if (!stored) {
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'unrecorded',
+                provenance: clone(sourceRead.provenance),
+                adoption_status: this.adoptionPort ? 'unrecorded' : 'unavailable'
+            };
+        }
+        validateStoredBinding(stored, sourceKey(exactSource));
+        if (!sameJson(stored.source, exactSource) || !sameJson(stored.provenance, sourceRead.provenance)) {
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'integrity_mismatch',
+                provenance: clone(sourceRead.provenance),
+                adoption_status: 'unavailable'
+            };
+        }
+        if (stored.legacy_adoption) {
+            // The v1 shape has no semantic schema/contentDigest contract. Preserve
+            // it for an explicit migration, but never treat its revision as the
+            // current adoption locator or claim this binding is verified.
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'unavailable',
+                provenance: clone(stored.provenance),
+                adoption_status: 'unavailable'
+            };
+        }
+        // An adoption locator is part of the historical binding snapshot. A
+        // provider may record adoption after this binding was attached, but that
+        // later record belongs to a new binding/revision and must not be surfaced
+        // as if it had been saved here.
+        const storedAdoption = stored.adoption;
+        if (!storedAdoption) {
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'recorded',
+                conditions: clone(stored.conditions),
+                provenance: clone(stored.provenance),
+                adoption_status: this.adoptionPort ? 'unrecorded' : 'unavailable'
+            };
+        }
+        const adoption = await this.readAdoption(exactSource, context, 'read');
+        if (adoption.status === 'denied') {
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'denied',
+                provenance: clone(stored.provenance),
+                adoption_status: 'denied'
+            };
+        }
+        if (adoption.status === 'unavailable') {
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'unavailable',
+                provenance: clone(stored.provenance),
+                adoption_status: 'unavailable'
+            };
+        }
+        if (adoption.status === 'unrecorded') {
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'integrity_mismatch',
+                provenance: clone(stored.provenance),
+                adoption_status: 'unrecorded'
+            };
+        }
+        if (adoption.status === 'recorded'
+            && (!adoption.adoption || !sameJson(storedAdoption, adoption.adoption))) {
+            return {
+                source: requestedSource,
+                resolved_source: clone(exactSource),
+                source_status: sourceRead.source_status,
+                acl_status: sourceRead.acl_status,
+                condition_status: 'integrity_mismatch',
+                provenance: clone(stored.provenance),
+                adoption_status: adoption.status
+            };
+        }
+        return {
+            source: requestedSource,
+            resolved_source: clone(exactSource),
+            source_status: sourceRead.source_status,
+            acl_status: sourceRead.acl_status,
+            condition_status: 'recorded',
+            conditions: clone(stored.conditions),
+            provenance: clone(stored.provenance),
+            adoption_status: adoption.status,
+            adoption: clone(storedAdoption)
+        };
+    }
+    async readSource(source, context, operation) {
+        try {
+            const result = await this.recordPort.read({ source: clone(source), context: clone(context) });
+            return normalizeSourceRead(result, source);
+        }
+        catch (error) {
+            if (error instanceof KnowledgeAdapterError)
+                throw error;
+            throw new KnowledgeAdapterError('source_unavailable', formatError(error));
+        }
+    }
+    async readAdoption(source, context, operation) {
+        if (!this.adoptionPort)
+            return { status: 'unavailable' };
+        try {
+            const result = await this.adoptionPort.read({ source: clone(source), context: clone(context) });
+            if (!result || typeof result !== 'object')
+                return { status: 'unavailable' };
+            if (result.status !== 'recorded' && result.status !== 'unrecorded'
+                && result.status !== 'denied' && result.status !== 'unavailable') {
+                return { status: 'unavailable' };
+            }
+            if (result.adoption === undefined) {
+                return result.status === 'recorded' ? { status: 'unavailable' } : { status: result.status };
+            }
+            if (result.status !== 'recorded')
+                return { status: 'unavailable' };
+            return { status: 'recorded', adoption: normalizeAdoptionReference(result.adoption, 'adoption') };
+        }
+        catch (error) {
+            if (operation === 'read')
+                return { status: 'unavailable' };
+            if (error instanceof KnowledgeAdapterError)
+                throw error;
+            return { status: 'unavailable' };
+        }
+    }
+    async loadSnapshot() {
+        try {
+            return {
+                current: await loadPersonalOs(this.dataDir),
+                sidecarContent: await readPersonalOsSidecar(this.dataDir, this.sidecarPath)
+            };
+        }
+        catch (error) {
+            throw new KnowledgeAdapterError('store_corrupt', formatError(error));
+        }
+    }
+    async loadSidecar() {
+        try {
+            return parseSidecar(await readPersonalOsSidecar(this.dataDir, this.sidecarPath));
+        }
+        catch (error) {
+            if (error instanceof KnowledgeAdapterError)
+                throw error;
+            throw new KnowledgeAdapterError('store_corrupt', formatError(error));
+        }
+    }
+}
+export function createKnowledgeConditionAdapter(options) {
+    return new GraphKnowledgeConditionAdapter(options);
+}
+function normalizeSourceReference(value, field) {
+    if (!value || typeof value !== 'object')
+        throw new KnowledgeAdapterError('validation_error', `${field} is required`);
+    const input = value;
+    if (!KNOWLEDGE_RECORD_KINDS.includes(input.kind)) {
+        throw new KnowledgeAdapterError('validation_error', `${field}.kind is unsupported`);
+    }
+    const normalized = {
+        kind: input.kind,
+        id: normalizeText(input.id, `${field}.id`, 512),
+        ...(input.revision === undefined ? {} : { revision: normalizeRevision(input.revision, `${field}.revision`) }),
+        ...(input.digest === undefined ? {} : { digest: normalizeDigest(input.digest, `${field}.digest`) })
+    };
+    return normalized;
+}
+function normalizeEvidenceReference(value, field) {
+    if (!value || typeof value !== 'object')
+        throw new KnowledgeAdapterError('store_corrupt', `${field} is invalid`);
+    const input = value;
+    return {
+        kind: normalizeText(input.kind, `${field}.kind`, 256),
+        id: normalizeText(input.id, `${field}.id`, 2_048),
+        ...(input.revision === undefined ? {} : { revision: normalizeRevision(input.revision, `${field}.revision`) }),
+        ...(input.digest === undefined ? {} : { digest: normalizeDigest(input.digest, `${field}.digest`) })
+    };
+}
+function normalizeAdoptionReference(value, field) {
+    if (!value || typeof value !== 'object')
+        throw new KnowledgeAdapterError('source_unavailable', `${field} is invalid`);
+    const input = value;
+    return {
+        id: normalizeText(input.id, `${field}.id`, 512),
+        schema: normalizeSchema(input.schema, `${field}.schema`),
+        contentDigest: normalizeDigest(input.contentDigest, `${field}.contentDigest`)
+    };
+}
+function normalizeSchema(value, field) {
+    const schema = normalizeText(value, field, 128);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(schema)) {
+        throw new KnowledgeAdapterError('validation_error', `${field} must be a semantic schema identifier`);
+    }
+    return schema;
+}
+function normalizeConditions(value) {
+    if (!value || typeof value !== 'object')
+        throw new KnowledgeAdapterError('validation_error', 'conditions are required');
+    const input = value;
+    const snapshot = input.problem_snapshot;
+    const method = input.method;
+    const refs = input.objective_refs;
+    const normalized = {
+        problem_snapshot: {
+            snapshot_id: normalizeSnapshotId(snapshot?.snapshot_id, 'conditions.problem_snapshot.snapshot_id'),
+            problem_id: String(snapshot?.problem_id ?? ''),
+            revision: String(snapshot?.revision ?? '')
+        },
+        method: {
+            id: String(method?.id ?? ''),
+            version: String(method?.version ?? '')
+        },
+        objective_refs: Array.isArray(refs) ? refs.map((value) => {
+            const ref = value;
+            return {
+                id: String(ref?.id ?? ''),
+                type: 'objective',
+                revision: String(ref?.revision ?? '')
+            };
+        }) : []
+    };
+    try {
+        validateDecisionAdapterConditions(normalized);
+    }
+    catch (error) {
+        if (error instanceof DecisionAdapterError) {
+            throw new KnowledgeAdapterError('validation_error', error.message);
+        }
+        throw error;
+    }
+    return normalized;
+}
+function normalizeSnapshotId(value, field) {
+    const snapshotId = normalizeText(value, field, 128);
+    if (!/^sha256:[0-9a-f]{64}$/u.test(snapshotId)) {
+        throw new KnowledgeAdapterError('validation_error', `${field} must be sha256:<64 lowercase hex>`);
+    }
+    return snapshotId;
+}
+function normalizeSourceRead(value, requested) {
+    if (!value || typeof value !== 'object')
+        throw new KnowledgeAdapterError('source_unavailable', 'Knowledge provider returned an invalid result');
+    const input = value;
+    const sourceStatus = input.source_status;
+    if (!KNOWLEDGE_SOURCE_STATUSES.includes(sourceStatus)) {
+        throw new KnowledgeAdapterError('source_unavailable', 'Knowledge provider returned an invalid source status');
+    }
+    const aclStatus = input.acl_status;
+    if (!KNOWLEDGE_ACL_STATUSES.includes(aclStatus)) {
+        throw new KnowledgeAdapterError('source_unavailable', 'Knowledge provider returned an invalid ACL status');
+    }
+    const source = input.source === undefined ? undefined : normalizeSourceReference(input.source, 'provider.source');
+    if (source && (source.kind !== requested.kind || source.id !== requested.id)) {
+        throw new KnowledgeAdapterError('integrity_mismatch', 'Knowledge provider returned a different source identity');
+    }
+    const rawProvenance = input.provenance;
+    if (rawProvenance !== undefined && !Array.isArray(rawProvenance)) {
+        throw new KnowledgeAdapterError('source_unavailable', 'Knowledge provider returned invalid provenance');
+    }
+    const provenance = (rawProvenance ?? []).map((entry, index) => normalizeEvidenceReference(entry, `provider.provenance[${index}]`));
+    return {
+        source_status: sourceStatus,
+        acl_status: aclStatus,
+        ...(source ? { source } : {}),
+        provenance
+    };
+}
+function assertExpectedSourceLocator(requested, resolved) {
+    if (requested.revision !== undefined && requested.revision !== resolved.revision) {
+        throw new KnowledgeAdapterError('integrity_mismatch', 'Knowledge source revision changed');
+    }
+    if (requested.digest !== undefined && requested.digest !== resolved.digest) {
+        throw new KnowledgeAdapterError('integrity_mismatch', 'Knowledge source digest changed');
+    }
+}
+function hasExactSourceLocator(source) {
+    return source.revision !== undefined && source.digest !== undefined;
+}
+function sourceKey(source) {
+    return `${source.kind}\u0000${source.id}`;
+}
+function bindingIdFor(source) {
+    return `sha256:${createHash('sha256').update(sourceKey(source), 'utf8').digest('hex')}`;
+}
+function assertSnapshotUnchanged(snapshot, current, sidecarContent) {
+    if (!sameJson(snapshot.current, current) || snapshot.sidecarContent !== sidecarContent) {
+        throw new KnowledgeAdapterError('condition_conflict', 'Canonical aggregate or knowledge sidecar changed while the provider was read');
+    }
+}
+function assertStagedBinding(sidecar, key, expected) {
+    const staged = sidecar.bindings[key];
+    if (!staged || !sameBindingPayload(staged, expected)) {
+        throw new KnowledgeAdapterError('readback_mismatch', `Staged knowledge binding ${key} is incomplete`);
+    }
+}
+function sameBindingPayload(left, right) {
+    return left.idempotency_key === right.idempotency_key
+        && sameJson(left.source, right.source)
+        && sameJson(left.conditions, right.conditions)
+        && sameJson(left.provenance, right.provenance)
+        && sameJson(left.adoption, right.adoption)
+        && sameJson(left.legacy_adoption, right.legacy_adoption);
+}
+function makeAttachReceipt(binding, sourceRead, adoption, operation) {
+    const legacy = binding.legacy_adoption !== undefined;
+    return {
+        binding_id: binding.binding_id,
+        operation,
+        source: clone(binding.source),
+        resolved_source: clone(binding.source),
+        source_status: sourceRead.source_status,
+        acl_status: sourceRead.acl_status,
+        condition_status: legacy ? 'unavailable' : 'recorded',
+        conditions: clone(binding.conditions),
+        provenance: clone(binding.provenance),
+        adoption_status: legacy ? 'unavailable' : adoption.status,
+        ...(!legacy && adoption.adoption ? { adoption: clone(adoption.adoption) } : {})
+    };
+}
+function parseSidecar(content) {
+    if (content === undefined || content.trim() === '')
+        return { version: KNOWLEDGE_ADAPTER_VERSION, bindings: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter sidecar is not valid JSON: ${formatError(error)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new KnowledgeAdapterError('store_corrupt', 'Knowledge adapter sidecar must be an object');
+    }
+    const value = parsed;
+    if ((value.version !== KNOWLEDGE_ADAPTER_VERSION && value.version !== LEGACY_KNOWLEDGE_ADAPTER_VERSION)
+        || !value.bindings || typeof value.bindings !== 'object' || Array.isArray(value.bindings)) {
+        throw new KnowledgeAdapterError('store_corrupt', 'Knowledge adapter sidecar has an unsupported schema');
+    }
+    const bindings = {};
+    for (const [key, raw] of Object.entries(value.bindings)) {
+        if (value.version === LEGACY_KNOWLEDGE_ADAPTER_VERSION) {
+            bindings[key] = migrateLegacyBinding(raw, key);
+        }
+        else {
+            validateStoredBinding(raw, key);
+            bindings[key] = clone(raw);
+        }
+    }
+    return { version: KNOWLEDGE_ADAPTER_VERSION, bindings };
+}
+function migrateLegacyBinding(value, key) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} is invalid`);
+    }
+    const raw = value;
+    validateLegacyStoredBinding(raw, key);
+    const { adoption, ...rest } = raw;
+    const migrated = {
+        ...rest,
+        ...(adoption === undefined ? {} : { legacy_adoption: clone(adoption) })
+    };
+    validateStoredBinding(migrated, key);
+    return migrated;
+}
+function validateStoredBinding(value, key) {
+    if (!value || typeof value !== 'object' || value.binding_id !== bindingIdFor(value.source) || key !== sourceKey(value.source)) {
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} has an invalid identity`);
+    }
+    normalizeText(value.idempotency_key, `bindings.${key}.idempotency_key`, 512);
+    const source = normalizeSourceReference(value.source, `bindings.${key}.source`);
+    if (!hasExactSourceLocator(source))
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} has no exact source locator`);
+    if (value.source_status_at_attach !== 'present' && value.source_status_at_attach !== 'quarantined') {
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} has an invalid source status`);
+    }
+    normalizeConditions(value.conditions);
+    if (!Array.isArray(value.provenance))
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} has invalid provenance`);
+    value.provenance.forEach((entry, index) => normalizeEvidenceReference(entry, `bindings.${key}.provenance[${index}]`));
+    if (value.adoption !== undefined && value.legacy_adoption !== undefined) {
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} mixes adoption locator schemas`);
+    }
+    if (value.adoption !== undefined)
+        normalizeAdoptionReference(value.adoption, `bindings.${key}.adoption`);
+    if (value.legacy_adoption !== undefined)
+        validateLegacyAdoptionReference(value.legacy_adoption, `bindings.${key}.legacy_adoption`);
+    normalizeTimestamp(value.attached_at, `bindings.${key}.attached_at`);
+}
+function validateLegacyStoredBinding(value, key) {
+    const source = normalizeSourceReference(value.source, `bindings.${key}.source`);
+    if (value.binding_id !== bindingIdFor(source) || key !== sourceKey(source)) {
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} has an invalid identity`);
+    }
+    normalizeText(value.idempotency_key, `bindings.${key}.idempotency_key`, 512);
+    if (!hasExactSourceLocator(source))
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} has no exact source locator`);
+    if (value.source_status_at_attach !== 'present' && value.source_status_at_attach !== 'quarantined') {
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} has an invalid source status`);
+    }
+    normalizeConditions(value.conditions);
+    if (!Array.isArray(value.provenance))
+        throw new KnowledgeAdapterError('store_corrupt', `Knowledge adapter binding ${key} has invalid provenance`);
+    value.provenance.forEach((entry, index) => normalizeEvidenceReference(entry, `bindings.${key}.provenance[${index}]`));
+    if (value.adoption !== undefined) {
+        validateLegacyAdoptionReference(value.adoption, `bindings.${key}.adoption`);
+    }
+    normalizeTimestamp(value.attached_at, `bindings.${key}.attached_at`);
+}
+function validateLegacyAdoptionReference(value, field) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new KnowledgeAdapterError('store_corrupt', `${field} is invalid`);
+    }
+    const input = value;
+    normalizeText(input.id, `${field}.id`, 512);
+    normalizeRevision(input.revision, `${field}.revision`);
+    normalizeDigest(input.digest, `${field}.digest`);
+}
+function serializeSidecar(sidecar) {
+    const bindings = Object.fromEntries(Object.entries(sidecar.bindings).sort(([left], [right]) => left.localeCompare(right, 'en')));
+    return `${JSON.stringify({ version: KNOWLEDGE_ADAPTER_VERSION, bindings }, null, 2)}\n`;
+}
+function normalizeRevision(value, field) {
+    const revision = normalizeText(value, field, 512);
+    if (!/^[1-9][0-9]*$/u.test(revision))
+        throw new KnowledgeAdapterError('validation_error', `${field} must be a positive decimal revision`);
+    return revision;
+}
+function normalizeDigest(value, field) {
+    const digest = normalizeText(value, field, 128);
+    if (!/^sha256:[0-9a-f]{64}$/u.test(digest))
+        throw new KnowledgeAdapterError('validation_error', `${field} must be sha256:<64 lowercase hex>`);
+    return digest;
+}
+function normalizeTimestamp(value, field) {
+    const timestamp = normalizeText(value, field, 64);
+    if (!Number.isFinite(Date.parse(timestamp)))
+        throw new KnowledgeAdapterError('store_corrupt', `${field} must be an ISO timestamp`);
+    return timestamp;
+}
+function normalizeText(value, field, max) {
+    if (typeof value !== 'string')
+        throw new KnowledgeAdapterError('validation_error', `${field} is required`);
+    const normalized = value.normalize('NFKC').trim();
+    if (!normalized || normalized.length > max || /[\u0000-\u001f\u007f-\u009f]/u.test(normalized)) {
+        throw new KnowledgeAdapterError('validation_error', `${field} must be bounded text`);
+    }
+    return normalized;
+}
+function assertContext(context) {
+    normalizeText(context?.principal, 'context.principal', 512);
+}
+function assertSidecarPath(path) {
+    if (!path || path.startsWith('/') || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..')) {
+        throw new KnowledgeAdapterError('validation_error', 'sidecarPath must remain relative to the SSOT root');
+    }
+}
+function clone(value) {
+    return structuredClone(value);
+}
+function sameJson(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+const KNOWLEDGE_RECORD_KINDS = [
+    'knowledge_event',
+    'knowledge_feedback',
+    'candidate',
+    'candidate_promotion',
+    'graph_maintenance_plan',
+    'human_gate_receipt',
+    'graph_maintenance_receipt',
+    'meeting_bridge_event',
+    'meeting_bridge_candidate'
+];
+const KNOWLEDGE_SOURCE_STATUSES = ['present', 'quarantined', 'retracted', 'not_found', 'denied'];
+const KNOWLEDGE_ACL_STATUSES = ['allowed', 'denied', 'unknown'];