@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/world-model.js

@@ -0,0 +1,955 @@
+import { validateFoundationDefinition } from './ontology-foundation.js';
+import { digestFoundationDefinition, findFoundationRecord, findLatestFoundationRecord, foundationCatalogOrEmpty } from './foundation-catalog.js';
+import { loadPersonalOs, mutatePersonalOsWithSidecar, readPersonalOsSidecar } from './ssot.js';
+/**
+ * The world-model helpers are deliberately independent of storage.  Definitions
+ * belong to the shared foundation catalog; observations and adoption records are
+ * values that reference an exact definition revision. A caller can therefore
+ * pass these records through the canonical SSOT transaction without introducing
+ * a second lock or definition authority.
+ */
+export const WORLD_MODEL_CONTRACT_VERSION = '0.1.0';
+export const WORLD_MODEL_RECORD_CATALOG_VERSION = 1;
+/** Evidence records are sidecar data committed with the canonical aggregate. */
+export const WORLD_MODEL_EVIDENCE_SIDECAR = 'evidence/world-model.json';
+export class WorldModelStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'WorldModelStoreError';
+        this.code = code;
+    }
+}
+export class WorldModelValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`World model validation failed: ${issues.map((issue) => `${issue.path} (${issue.code}): ${issue.message}`).join(', ')}`);
+        this.name = 'WorldModelValidationError';
+        this.issues = issues;
+    }
+}
+/**
+ * Validates and clones an observation before it crosses a storage boundary.
+ * The returned value is deeply frozen, while the input remains untouched.
+ */
+export function normalizeWorldModelObservation(input) {
+    const issues = observationShapeIssues(input);
+    if (issues.length > 0)
+        throw new WorldModelValidationError(issues);
+    const normalized = {
+        id: input.id.trim(),
+        variableRef: freezeCloneRevision(input.variableRef),
+        subjectId: input.subjectId.trim(),
+        value: cloneWorldModelValue(input.value, 'value'),
+        occurredAt: input.occurredAt,
+        period: freezeClonePeriod(input.period),
+        recordedAt: input.recordedAt,
+        sourceRef: freezeCloneProvenance(input.sourceRef),
+        ...(input.supersedes === undefined ? {} : { supersedes: input.supersedes.trim() })
+    };
+    return deepFreeze(normalized);
+}
+/**
+ * Checks whether an already normalized observation is compatible with the
+ * exact Variable definition it references.  This does not infer a value or
+ * upgrade an observation from inferred to observed.
+ */
+export function validateWorldModelObservation(observation, variable) {
+    const issues = [];
+    if (observation.variableRef.type !== 'variable'
+        || observation.variableRef.id !== variable.id
+        || observation.variableRef.revision !== variable.revision) {
+        issues.push({
+            code: 'INVALID_VARIABLE_REFERENCE',
+            path: 'variableRef',
+            message: `Observation references ${observation.variableRef.id}@${observation.variableRef.revision}, expected ${variable.id}@${variable.revision}.`
+        });
+    }
+    if (variable.scope.subjectIds.length > 0 && !variable.scope.subjectIds.includes(observation.subjectId)) {
+        issues.push({
+            code: 'OBSERVATION_SCOPE_MISMATCH',
+            path: 'subjectId',
+            message: `Subject ${observation.subjectId} is outside Variable ${variable.id} scope.`
+        });
+    }
+    if (!valueMatchesKind(observation.value, variable.valueKind)) {
+        issues.push({
+            code: 'VARIABLE_VALUE_KIND_MISMATCH',
+            path: 'value',
+            message: `Observation value does not match Variable valueKind ${variable.valueKind}.`
+        });
+    }
+    const validFrom = parseIsoTimestamp(variable.scope.validFrom);
+    const validUntil = variable.scope.validUntil === undefined ? undefined : parseIsoTimestamp(variable.scope.validUntil);
+    const periodFrom = parseIsoTimestamp(observation.period.from);
+    const periodUntil = parseIsoTimestamp(observation.period.until);
+    if (validFrom !== undefined && periodFrom !== undefined && periodFrom < validFrom) {
+        issues.push({
+            code: 'OBSERVATION_PERIOD_MISMATCH',
+            path: 'period.from',
+            message: 'Observation period begins before the Variable scope becomes valid.'
+        });
+    }
+    if (validUntil !== undefined && periodUntil !== undefined && periodUntil > validUntil) {
+        issues.push({
+            code: 'OBSERVATION_PERIOD_MISMATCH',
+            path: 'period.until',
+            message: 'Observation period ends after the Variable scope expires.'
+        });
+    }
+    return validationResult(issues);
+}
+/**
+ * Delegates Model validation to the shared ontology contract.  The wrapper
+ * keeps world-model callers from importing ontology internals while retaining
+ * the contract's distinction between draft, judgment, evaluation, and
+ * execution use.
+ */
+export function validateWorldModelModel(model, use = 'judgment') {
+    return validateFoundationDefinition(model, { use });
+}
+/**
+ * Creates a durable adoption record without mutating the candidate or Model.
+ * A candidate may only produce an unverified/hypothesis Model record; adopting
+ * it cannot silently turn it into a verified claim.
+ */
+export function retainCandidateModel(candidate, model, adoption) {
+    const issues = [];
+    if (!isNonEmptyString(adoption.adoptionId))
+        issues.push(missing('adoptionId'));
+    if (!['proposed', 'approved'].includes(String(adoption.adoptionState))) {
+        issues.push({ code: 'INVALID_FIELD', path: 'adoptionState', message: 'Adoption state must be proposed or approved.' });
+    }
+    if (!isFoundationUse(adoption.authorizedUse)) {
+        issues.push({ code: 'INVALID_FIELD', path: 'authorizedUse', message: 'Adoption authorizedUse must be a valid Foundation use.' });
+    }
+    if (!isIsoTimestamp(adoption.adoptedAt))
+        issues.push(invalidTimestamp('adoptedAt'));
+    if (!candidate.candidateId.trim())
+        issues.push(missing('candidate.candidateId'));
+    if (!candidate.hypothesis.trim())
+        issues.push(missing('candidate.hypothesis'));
+    if (!Array.isArray(candidate.evidenceIds) || candidate.evidenceIds.length === 0) {
+        issues.push({ code: 'MISSING_SOURCE', path: 'candidate.evidenceIds', message: 'Candidate adoption must retain at least one evidence reference.' });
+    }
+    else if (candidate.evidenceIds.some((evidenceId) => !isNonEmptyString(evidenceId))) {
+        issues.push({ code: 'MISSING_SOURCE', path: 'candidate.evidenceIds', message: 'Candidate evidence references must be non-empty strings.' });
+    }
+    if (!isRecord(candidate.acl) || !isNonEmptyString(candidate.acl.ownerId)) {
+        issues.push(missing('candidate.acl.ownerId'));
+    }
+    if (!['unverified', 'hypothesis'].includes(candidate.epistemicState)) {
+        issues.push({ code: 'INVALID_FIELD', path: 'candidate.epistemicState', message: 'Candidate adoption only retains unverified or hypothesis state.' });
+    }
+    if (model.type !== 'model') {
+        issues.push({ code: 'MODEL_CONTRACT_INVALID', path: 'model.type', message: 'Candidate adoption requires a Model definition.' });
+    }
+    const modelValidation = validateWorldModelModel(model, adoption.authorizedUse);
+    if (!modelValidation.valid) {
+        issues.push(...modelValidation.issues.map((issue) => ({
+            code: 'MODEL_CONTRACT_INVALID',
+            path: issue.path,
+            message: issue.message
+        })));
+    }
+    if (model.epistemicState === 'verified' || model.validationState === 'verified') {
+        issues.push({
+            code: 'INVALID_FIELD',
+            path: 'model.epistemicState',
+            message: 'A candidate adoption cannot be represented as a verified Model.'
+        });
+    }
+    if (adoption.modelRef !== undefined
+        && (adoption.modelRef.type !== 'model'
+            || adoption.modelRef.id !== model.id
+            || adoption.modelRef.revision !== model.revision)) {
+        issues.push({
+            code: 'INVALID_VARIABLE_REFERENCE',
+            path: 'modelRef',
+            message: `Adoption modelRef must match ${model.id}@${model.revision}.`
+        });
+    }
+    if (adoption.approvalRef !== undefined && !isDecisionRevision(adoption.approvalRef)) {
+        issues.push({
+            code: 'INVALID_APPROVAL_REFERENCE',
+            path: 'approvalRef',
+            message: 'approvalRef must contain a decision id and positive revision.'
+        });
+    }
+    if (adoption.adoptionState === 'approved' && !isDecisionRevision(adoption.approvalRef)) {
+        issues.push({
+            code: adoption.approvalRef === undefined ? 'MISSING_APPROVAL_REFERENCE' : 'INVALID_APPROVAL_REFERENCE',
+            path: 'approvalRef',
+            message: 'Approved adoption requires a valid approvalRef decision revision.'
+        });
+    }
+    const canonicalModelDigest = digestFoundationDefinition(model);
+    if (adoption.modelDigest !== undefined
+        && (!isDigest(adoption.modelDigest) || adoption.modelDigest !== canonicalModelDigest)) {
+        issues.push({
+            code: 'MODEL_DIGEST_MISMATCH',
+            path: 'modelDigest',
+            message: 'modelDigest must match the canonical digest of the adopted Model definition.'
+        });
+    }
+    if (issues.length > 0)
+        throw new WorldModelValidationError(issues);
+    const modelRef = freezeCloneRevision(adoption.modelRef ?? {
+        id: model.id,
+        type: 'model',
+        revision: model.revision
+    });
+    const retainedCandidate = {
+        candidateId: candidate.candidateId.trim(),
+        hypothesis: candidate.hypothesis,
+        evidenceIds: [...candidate.evidenceIds],
+        acl: freezeCloneAcl(candidate.acl),
+        epistemicState: candidate.epistemicState
+    };
+    const record = {
+        adoptionId: adoption.adoptionId.trim(),
+        modelRef,
+        candidate: retainedCandidate,
+        adoptionState: adoption.adoptionState,
+        authorizedUse: adoption.authorizedUse,
+        adoptedAt: adoption.adoptedAt,
+        modelDigest: canonicalModelDigest,
+        ...(adoption.approvalRef === undefined ? {} : { approvalRef: freezeCloneDecisionRevision(adoption.approvalRef) })
+    };
+    return deepFreeze(record);
+}
+/**
+ * Creates a world-model record store over the existing canonical aggregate.
+ * Foundation definitions are delegated to the shared revision store. The
+ * observation/adoption evidence catalog is committed as a sidecar in the same
+ * SSOT transaction, so the canonical Graph remains definition-only.
+ */
+export function createWorldModelStore(options) {
+    if (!options || !isNonEmptyString(options.dataDir)) {
+        throw new WorldModelStoreError('invalid_input', 'dataDir is required');
+    }
+    if (!options.foundationStore || typeof options.foundationStore.read !== 'function'
+        || typeof options.foundationStore.create !== 'function') {
+        throw new WorldModelStoreError('invalid_input', 'foundationStore with create/read is required');
+    }
+    if (options.approvalReader !== undefined && typeof options.approvalReader.isApproved !== 'function') {
+        throw new WorldModelStoreError('invalid_input', 'approvalReader.isApproved is required when approvalReader is provided');
+    }
+    return new GraphWorldModelRecordStore(options.dataDir, options.foundationStore, options.approvalReader);
+}
+class GraphWorldModelRecordStore {
+    dataDir;
+    foundationStore;
+    approvalReader;
+    constructor(dataDir, foundationStore, approvalReader) {
+        this.dataDir = dataDir;
+        this.foundationStore = foundationStore;
+        this.approvalReader = approvalReader;
+    }
+    async createVariable(variable, context) {
+        assertStoreContext(context);
+        assertFoundationForJudgment(variable, 'Variable');
+        return this.foundationStore.create(variable, context);
+    }
+    async createModel(model, context) {
+        assertStoreContext(context);
+        assertFoundationForJudgment(model, 'Model');
+        return this.foundationStore.create(model, context);
+    }
+    async readModel(reference, context) {
+        assertStoreContext(context);
+        assertModelReference(reference, 'reference');
+        const record = await this.foundationStore.read(reference, context);
+        if (!record)
+            return null;
+        if (record.definition.type !== 'model') {
+            throw new WorldModelStoreError('corrupt_record', `Expected Model at ${reference.id}@${reference.revision}`);
+        }
+        assertFoundationAclRead(record.definition, context.principal);
+        return cloneModel(record.definition);
+    }
+    async saveObservation(input, context) {
+        assertStoreContext(context);
+        const observation = normalizeStoreInput(input, 'observation');
+        const variableRecord = await this.foundationStore.read(observation.variableRef, context);
+        if (!variableRecord) {
+            throw new WorldModelStoreError('not_found', `Variable ${observation.variableRef.id}@${observation.variableRef.revision} was not found`);
+        }
+        if (variableRecord.definition.type !== 'variable') {
+            throw new WorldModelStoreError('corrupt_record', `Observation references non-Variable ${observation.variableRef.id}`);
+        }
+        assertFoundationAclWrite(variableRecord.definition, context.principal);
+        assertObservationCompatible(observation, variableRecord.definition);
+        await this.mutateCatalog((catalog, current) => {
+            const currentVariable = resolveFoundationAtAggregate(current, observation.variableRef, variableRecord, context.principal, 'write');
+            if (currentVariable.definition.type !== 'variable') {
+                throw new WorldModelStoreError('corrupt_record', `Variable ${observation.variableRef.id} changed type during commit`);
+            }
+            assertFoundationAclWrite(currentVariable.definition, context.principal);
+            assertObservationCompatible(observation, currentVariable.definition);
+            if (catalog.observations.some((existing) => existing.id === observation.id)) {
+                throw new WorldModelStoreError('revision_conflict', `Observation ${observation.id} already exists`);
+            }
+            if (observation.supersedes !== undefined) {
+                const superseded = catalog.observations.find((existing) => existing.id === observation.supersedes);
+                if (!superseded) {
+                    throw new WorldModelStoreError('not_found', `Superseded observation ${observation.supersedes} was not found`);
+                }
+                if (superseded.variableRef.id !== observation.variableRef.id
+                    || superseded.variableRef.revision !== observation.variableRef.revision
+                    || superseded.subjectId !== observation.subjectId) {
+                    throw new WorldModelStoreError('invalid_input', `Correction ${observation.id} must retain the Variable revision and subject of ${superseded.id}`);
+                }
+            }
+            return {
+                ...catalog,
+                observations: [...catalog.observations, observation]
+            };
+        });
+        const readback = await this.readObservation(observation.id, context);
+        if (!readback)
+            throw new WorldModelStoreError('readback_mismatch', `Observation ${observation.id} was not readable after commit`);
+        return readback;
+    }
+    async readObservation(id, context) {
+        assertStoreContext(context);
+        if (!isNonEmptyString(id))
+            throw new WorldModelStoreError('invalid_input', 'observation id is required');
+        const catalog = await this.loadCatalog();
+        const observation = catalog.observations.find((item) => item.id === id);
+        if (!observation)
+            return null;
+        const variableRecord = await this.foundationStore.read(observation.variableRef, context);
+        if (!variableRecord) {
+            throw new WorldModelStoreError('corrupt_record', `Variable for observation ${id} is missing`);
+        }
+        if (variableRecord.definition.type !== 'variable') {
+            throw new WorldModelStoreError('corrupt_record', `Observation ${id} references a non-Variable definition`);
+        }
+        assertFoundationAclRead(variableRecord.definition, context.principal);
+        assertObservationCompatible(observation, variableRecord.definition);
+        return freezeObservation(observation);
+    }
+    async listObservations(query, context) {
+        assertStoreContext(context);
+        const catalog = await this.loadCatalog();
+        const filtered = catalog.observations.filter((observation) => matchesObservationQuery(observation, query));
+        const visible = [];
+        for (const observation of filtered) {
+            const readback = await this.readObservation(observation.id, context);
+            if (readback)
+                visible.push(readback);
+        }
+        return Object.freeze(visible);
+    }
+    async saveModelAdoption(candidate, modelRef, adoption, context) {
+        assertStoreContext(context);
+        assertModelReference(modelRef, 'modelRef');
+        const modelRecord = await this.foundationStore.read(modelRef, context);
+        if (!modelRecord) {
+            throw new WorldModelStoreError('not_found', `Model ${modelRef.id}@${modelRef.revision} was not found`);
+        }
+        if (modelRecord.definition.type !== 'model') {
+            throw new WorldModelStoreError('corrupt_record', `Adoption references non-Model ${modelRef.id}`);
+        }
+        assertFoundationAclWrite(modelRecord.definition, context.principal);
+        assertCandidateAclWrite(candidate, context.principal);
+        let record;
+        await this.mutateCatalog(async (catalog, current) => {
+            const currentModel = resolveFoundationAtAggregate(current, modelRef, modelRecord, context.principal, 'write');
+            if (currentModel.definition.type !== 'model') {
+                throw new WorldModelStoreError('corrupt_record', `Model ${modelRef.id} changed type during commit`);
+            }
+            assertFoundationAclWrite(currentModel.definition, context.principal);
+            assertCandidateAclWrite(candidate, context.principal);
+            if (catalog.adoptions.some((existing) => existing.adoptionId === adoption.adoptionId)) {
+                throw new WorldModelStoreError('revision_conflict', `Model adoption ${adoption.adoptionId} already exists`);
+            }
+            // Resolve approval while the SSOT mutation lock is held and before the
+            // sidecar is returned for commit. A post-commit approval read could
+            // fail after the approved record was already persisted.
+            await this.assertApprovalReference(modelRef, adoption, context);
+            const retained = retainCandidateModel(candidate, currentModel.definition, { ...adoption, modelRef });
+            record = retained;
+            return {
+                ...catalog,
+                adoptions: [...catalog.adoptions, retained]
+            };
+        });
+        if (!record)
+            throw new WorldModelStoreError('readback_mismatch', 'Model adoption commit did not produce a record');
+        // Approval was checked before the atomic append. This structural readback
+        // deliberately avoids a second provider call that could report failure
+        // while leaving the successful commit in place.
+        const readback = await this.readModelAdoptionRecord(record.adoptionId, context, { verifyApproval: false });
+        if (!readback)
+            throw new WorldModelStoreError('readback_mismatch', `Model adoption ${record.adoptionId} was not readable after commit`);
+        return readback;
+    }
+    async readModelAdoption(adoptionId, context) {
+        return this.readModelAdoptionRecord(adoptionId, context, { verifyApproval: true });
+    }
+    async readModelAdoptionRecord(adoptionId, context, options) {
+        assertStoreContext(context);
+        if (!isNonEmptyString(adoptionId))
+            throw new WorldModelStoreError('invalid_input', 'adoptionId is required');
+        const catalog = await this.loadCatalog();
+        const record = catalog.adoptions.find((item) => item.adoptionId === adoptionId);
+        if (!record)
+            return null;
+        assertCandidateAclRead(record.candidate, context.principal);
+        const modelRecord = await this.foundationStore.read(record.modelRef, context);
+        if (!modelRecord || modelRecord.definition.type !== 'model') {
+            throw new WorldModelStoreError('corrupt_record', `Model for adoption ${adoptionId} is missing`);
+        }
+        assertFoundationAclRead(modelRecord.definition, context.principal);
+        if (options.verifyApproval)
+            await this.assertApprovalReference(record.modelRef, record, context);
+        if (record.modelDigest !== modelRecord.digest) {
+            throw new WorldModelStoreError('readback_mismatch', `Model adoption ${adoptionId} digest does not match ${record.modelRef.id}@${record.modelRef.revision}`);
+        }
+        const verified = retainCandidateModel(record.candidate, modelRecord.definition, {
+            adoptionId: record.adoptionId,
+            adoptionState: record.adoptionState,
+            authorizedUse: record.authorizedUse,
+            adoptedAt: record.adoptedAt,
+            modelRef: record.modelRef,
+            modelDigest: record.modelDigest,
+            ...(record.approvalRef === undefined ? {} : { approvalRef: record.approvalRef })
+        });
+        return verified;
+    }
+    async listModelAdoptions(context) {
+        assertStoreContext(context);
+        const catalog = await this.loadCatalog();
+        const visible = [];
+        for (const record of catalog.adoptions) {
+            const readback = await this.readModelAdoption(record.adoptionId, context);
+            if (readback)
+                visible.push(readback);
+        }
+        return Object.freeze(visible);
+    }
+    async loadCatalog() {
+        try {
+            // Loading the aggregate first performs the canonical recovery/read
+            // under the SSOT lock. The sidecar is then read from the committed
+            // evidence path; writes use the same lock and transaction below.
+            const os = await loadPersonalOs(this.dataDir);
+            if (os.graph.version !== 2) {
+                throw new WorldModelStoreError('unsupported_graph', 'World-model records require canonical Graph v2');
+            }
+            return await readWorldModelCatalog(this.dataDir);
+        }
+        catch (error) {
+            if (error instanceof WorldModelStoreError)
+                throw error;
+            throw new WorldModelStoreError('corrupt_record', formatError(error));
+        }
+    }
+    async assertApprovalReference(modelRef, adoption, context) {
+        if (adoption.adoptionState !== 'approved')
+            return;
+        if (!isDecisionRevision(adoption.approvalRef)) {
+            throw new WorldModelStoreError('approval_reference_unresolved', 'Approved model adoption requires a valid approvalRef decision revision');
+        }
+        if (!this.approvalReader) {
+            throw new WorldModelStoreError('approval_reference_unresolved', 'Approved model adoption requires an approval reader that verifies the decision binding');
+        }
+        let approved = false;
+        try {
+            approved = await this.approvalReader.isApproved({
+                approvalRef: adoption.approvalRef,
+                modelRef,
+                context
+            });
+        }
+        catch {
+            approved = false;
+        }
+        if (!approved) {
+            throw new WorldModelStoreError('approval_reference_unresolved', `Approval ${adoption.approvalRef.id}@${adoption.approvalRef.revision} does not approve Model ${modelRef.id}@${modelRef.revision}`);
+        }
+    }
+    async mutateCatalog(mutator) {
+        await mutatePersonalOsWithSidecar(this.dataDir, WORLD_MODEL_EVIDENCE_SIDECAR, async (current, existingContent) => {
+            if (current.graph.version !== 2) {
+                throw new WorldModelStoreError('unsupported_graph', 'World-model records require canonical Graph v2');
+            }
+            // This callback already owns the canonical SSOT lock. Reading the
+            // existing evidence sidecar here avoids a lock re-entry and makes the
+            // read-modify-write sequence atomic with the Graph aggregate.
+            const catalog = parseWorldModelCatalog(existingContent);
+            const next = await mutator(catalog, current);
+            assertWorldModelCatalog(next);
+            return {
+                next: current,
+                sidecarContent: serializeWorldModelCatalog(next),
+                result: undefined
+            };
+        });
+    }
+}
+function resolveFoundationAtAggregate(current, reference, expected, principal, action) {
+    if (current.graph.version !== 2) {
+        throw new WorldModelStoreError('unsupported_graph', 'World-model records require canonical Graph v2');
+    }
+    let actual;
+    let latest;
+    try {
+        const catalog = foundationCatalogOrEmpty(current.graph.foundation);
+        actual = findFoundationRecord(catalog, reference);
+        latest = findLatestFoundationRecord(catalog, reference.type, reference.id);
+    }
+    catch (error) {
+        if (error instanceof WorldModelStoreError)
+            throw error;
+        throw new WorldModelStoreError('corrupt_record', formatError(error));
+    }
+    if (!actual) {
+        throw new WorldModelStoreError('not_found', `Foundation ${reference.type}/${reference.id}@${reference.revision} was not found in the commit aggregate`);
+    }
+    if (!latest) {
+        throw new WorldModelStoreError('corrupt_record', `Latest pointer is missing for ${reference.type}/${reference.id}`);
+    }
+    const readable = aclAllowsRead(latest.definition.acl, principal);
+    const authorized = action === 'read' ? readable : aclAllowsWrite(latest.definition.acl, principal);
+    if (!authorized) {
+        throw new WorldModelStoreError('authorization_denied', `Principal ${principal} cannot ${action} ${reference.type}/${reference.id}`);
+    }
+    if (actual.digest !== expected.digest) {
+        throw new WorldModelStoreError('revision_conflict', `Foundation ${reference.type}/${reference.id}@${reference.revision} changed before commit`);
+    }
+    return { definition: actual.definition, digest: actual.digest };
+}
+function assertFoundationForJudgment(definition, label) {
+    const result = validateFoundationDefinition(definition, { use: 'judgment' });
+    if (!result.valid) {
+        throw new WorldModelStoreError('invalid_input', `${label} is not valid for judgment: ${result.issues.map((issue) => `${issue.path}: ${issue.message}`).join('; ')}`);
+    }
+}
+function normalizeStoreInput(input, label) {
+    try {
+        return normalizeWorldModelObservation(input);
+    }
+    catch (error) {
+        if (error instanceof WorldModelValidationError) {
+            throw new WorldModelStoreError('invalid_input', `${label} is invalid: ${error.message}`);
+        }
+        throw error;
+    }
+}
+function assertObservationCompatible(observation, variable) {
+    const result = validateWorldModelObservation(observation, variable);
+    if (!result.valid) {
+        throw new WorldModelStoreError('invalid_input', result.issues.map((issue) => `${issue.path}: ${issue.message}`).join('; '));
+    }
+}
+function assertStoreContext(context) {
+    if (!context || !isNonEmptyString(context.principal)) {
+        throw new WorldModelStoreError('authorization_denied', 'A trusted principal is required');
+    }
+}
+function assertModelReference(reference, label) {
+    if (!isVariableOrModelRevision(reference, 'model')) {
+        throw new WorldModelStoreError('invalid_input', `${label} must contain a model id and positive revision`);
+    }
+}
+function isVariableOrModelRevision(value, type) {
+    return isRecord(value)
+        && value.type === type
+        && isNonEmptyString(value.id)
+        && /^[1-9]\d*$/.test(String(value.revision));
+}
+function assertFoundationAclWrite(definition, principal) {
+    if (!aclAllowsWrite(definition.acl, principal)) {
+        throw new WorldModelStoreError('authorization_denied', `Principal ${principal} cannot write ${definition.type}/${definition.id}`);
+    }
+}
+function assertFoundationAclRead(definition, principal) {
+    if (!aclAllowsRead(definition.acl, principal)) {
+        throw new WorldModelStoreError('authorization_denied', `Principal ${principal} cannot read ${definition.type}/${definition.id}`);
+    }
+}
+function assertCandidateAclWrite(candidate, principal) {
+    if (!aclAllowsWrite(candidate.acl, principal)) {
+        throw new WorldModelStoreError('authorization_denied', `Principal ${principal} cannot write candidate ${candidate.candidateId}`);
+    }
+}
+function assertCandidateAclRead(candidate, principal) {
+    if (!aclAllowsRead(candidate.acl, principal)) {
+        throw new WorldModelStoreError('authorization_denied', `Principal ${principal} cannot read candidate ${candidate.candidateId}`);
+    }
+}
+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 matchesObservationQuery(observation, query) {
+    if (!query)
+        return true;
+    if (query.subjectId !== undefined && observation.subjectId !== query.subjectId)
+        return false;
+    if (query.supersedes !== undefined && observation.supersedes !== query.supersedes)
+        return false;
+    if (query.variableRef !== undefined && (observation.variableRef.id !== query.variableRef.id
+        || observation.variableRef.type !== query.variableRef.type
+        || observation.variableRef.revision !== query.variableRef.revision))
+        return false;
+    return true;
+}
+async function readWorldModelCatalog(dataDir) {
+    try {
+        return parseWorldModelCatalog(await readPersonalOsSidecar(dataDir, WORLD_MODEL_EVIDENCE_SIDECAR));
+    }
+    catch (error) {
+        if (error instanceof WorldModelStoreError)
+            throw error;
+        throw new WorldModelStoreError('corrupt_record', formatError(error));
+    }
+}
+function parseWorldModelCatalog(rawText) {
+    if (rawText === undefined)
+        return emptyWorldModelCatalog();
+    try {
+        const raw = JSON.parse(rawText);
+        assertWorldModelCatalog(raw);
+        return cloneWorldModelCatalog(raw);
+    }
+    catch (error) {
+        if (error instanceof WorldModelStoreError)
+            throw error;
+        throw new WorldModelStoreError('corrupt_record', formatError(error));
+    }
+}
+function serializeWorldModelCatalog(catalog) {
+    return `${JSON.stringify(catalog, null, 2)}\n`;
+}
+function emptyWorldModelCatalog() {
+    return { version: WORLD_MODEL_RECORD_CATALOG_VERSION, observations: [], adoptions: [] };
+}
+function cloneWorldModelCatalog(catalog) {
+    return {
+        version: WORLD_MODEL_RECORD_CATALOG_VERSION,
+        observations: catalog.observations.map((observation) => freezeObservation(observation)),
+        adoptions: catalog.adoptions.map((adoption) => freezeAdoption(adoption))
+    };
+}
+function assertWorldModelCatalog(value) {
+    if (!isRecord(value) || value.version !== WORLD_MODEL_RECORD_CATALOG_VERSION
+        || !Array.isArray(value.observations) || !Array.isArray(value.adoptions)) {
+        throw new WorldModelStoreError('corrupt_record', 'world-model evidence must contain version 1 observations and adoptions arrays');
+    }
+    const observationIds = new Set();
+    for (const item of value.observations) {
+        const normalized = normalizeWorldModelObservation(item);
+        if (observationIds.has(normalized.id)) {
+            throw new WorldModelStoreError('corrupt_record', `Duplicate observation ${normalized.id}`);
+        }
+        observationIds.add(normalized.id);
+    }
+    const adoptionIds = new Set();
+    for (const item of value.adoptions) {
+        const normalized = normalizeStoredAdoption(item);
+        if (adoptionIds.has(normalized.adoptionId)) {
+            throw new WorldModelStoreError('corrupt_record', `Duplicate model adoption ${normalized.adoptionId}`);
+        }
+        adoptionIds.add(normalized.adoptionId);
+    }
+}
+function normalizeStoredAdoption(value) {
+    if (!isRecord(value)
+        || !isNonEmptyString(value.adoptionId)
+        || !isVariableOrModelRevision(value.modelRef, 'model')
+        || !isDigest(value.modelDigest)
+        || !isRecord(value.candidate)
+        || !isNonEmptyString(value.candidate.candidateId)
+        || !isNonEmptyString(value.candidate.hypothesis)
+        || !Array.isArray(value.candidate.evidenceIds)
+        || value.candidate.evidenceIds.length === 0
+        || value.candidate.evidenceIds.some((item) => !isNonEmptyString(item))
+        || !isCandidateAcl(value.candidate.acl)
+        || !['unverified', 'hypothesis'].includes(String(value.candidate.epistemicState))
+        || !['proposed', 'approved'].includes(String(value.adoptionState))
+        || !isFoundationUse(String(value.authorizedUse))
+        || !isIsoTimestamp(value.adoptedAt)
+        || (value.adoptionState === 'approved' && !isDecisionRevision(value.approvalRef))
+        || (value.approvalRef !== undefined && !isDecisionRevision(value.approvalRef))) {
+        throw new WorldModelStoreError('corrupt_record', 'world-model adoption record is malformed');
+    }
+    const candidate = {
+        candidateId: String(value.candidate.candidateId).trim(),
+        hypothesis: String(value.candidate.hypothesis),
+        evidenceIds: [...value.candidate.evidenceIds].map(String),
+        acl: freezeCloneAcl(value.candidate.acl),
+        epistemicState: value.candidate.epistemicState
+    };
+    return freezeAdoption({
+        adoptionId: String(value.adoptionId).trim(),
+        modelRef: freezeCloneRevision(value.modelRef),
+        candidate,
+        adoptionState: value.adoptionState,
+        authorizedUse: value.authorizedUse,
+        adoptedAt: String(value.adoptedAt),
+        modelDigest: String(value.modelDigest),
+        ...(value.approvalRef === undefined ? {} : { approvalRef: freezeCloneDecisionRevision(value.approvalRef) })
+    });
+}
+function isFoundationUse(value) {
+    return value === 'draft' || value === 'judgment' || value === 'evaluation' || value === 'execution';
+}
+function isDecisionRevision(value) {
+    return isRecord(value)
+        && value.type === 'decision'
+        && isNonEmptyString(value.id)
+        && /^[1-9]\d*$/.test(String(value.revision));
+}
+function isDigest(value) {
+    return typeof value === 'string' && /^sha256:[0-9a-f]{64}$/.test(value);
+}
+function isCandidateAcl(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.ownerId)
+        && ['private', 'project', 'organization', 'public'].includes(String(value.visibility))
+        && Array.isArray(value.readerIds)
+        && Array.isArray(value.writerIds)
+        && value.readerIds.every((item) => isNonEmptyString(item))
+        && value.writerIds.every((item) => isNonEmptyString(item));
+}
+function freezeObservation(observation) {
+    return deepFreeze({
+        id: observation.id,
+        variableRef: freezeCloneRevision(observation.variableRef),
+        subjectId: observation.subjectId,
+        value: cloneWorldModelValue(observation.value, 'value'),
+        occurredAt: observation.occurredAt,
+        period: freezeClonePeriod(observation.period),
+        recordedAt: observation.recordedAt,
+        sourceRef: freezeCloneProvenance(observation.sourceRef),
+        ...(observation.supersedes === undefined ? {} : { supersedes: observation.supersedes })
+    });
+}
+function freezeAdoption(adoption) {
+    return deepFreeze({
+        adoptionId: adoption.adoptionId,
+        modelRef: freezeCloneRevision(adoption.modelRef),
+        candidate: {
+            candidateId: adoption.candidate.candidateId,
+            hypothesis: adoption.candidate.hypothesis,
+            evidenceIds: [...adoption.candidate.evidenceIds],
+            acl: freezeCloneAcl(adoption.candidate.acl),
+            epistemicState: adoption.candidate.epistemicState
+        },
+        adoptionState: adoption.adoptionState,
+        authorizedUse: adoption.authorizedUse,
+        adoptedAt: adoption.adoptedAt,
+        modelDigest: adoption.modelDigest,
+        ...(adoption.approvalRef === undefined ? {} : { approvalRef: freezeCloneDecisionRevision(adoption.approvalRef) })
+    });
+}
+function cloneModel(model) {
+    return JSON.parse(JSON.stringify(model));
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function observationShapeIssues(input) {
+    const issues = [];
+    if (!isRecord(input))
+        return [invalid('observation', 'Observation must be a plain object.')];
+    if (!isNonEmptyString(input.id))
+        issues.push(missing('id'));
+    if (!isNonEmptyString(input.subjectId))
+        issues.push(missing('subjectId'));
+    if (!isVariableRevision(input.variableRef))
+        issues.push({
+            code: 'INVALID_VARIABLE_REFERENCE',
+            path: 'variableRef',
+            message: 'Observation variableRef requires a variable id and revision.'
+        });
+    if (input.value === null || input.value === undefined || !isWorldModelValue(input.value)) {
+        issues.push(invalid('value', 'Observation value must be a finite JSON scalar, array, or object; null is reserved for missing data.'));
+    }
+    if (!isIsoTimestamp(input.occurredAt))
+        issues.push(invalidTimestamp('occurredAt'));
+    if (!isValidPeriod(input.period))
+        issues.push({
+            code: 'INVALID_PERIOD',
+            path: 'period',
+            message: 'Observation period requires valid ISO from/until timestamps with until at or after from.'
+        });
+    if (!isIsoTimestamp(input.recordedAt))
+        issues.push(invalidTimestamp('recordedAt'));
+    if (!isProvenance(input.sourceRef))
+        issues.push({
+            code: 'MISSING_SOURCE',
+            path: 'sourceRef',
+            message: 'Observation requires a source id, source kind, and evidence reference list.'
+        });
+    if (isIsoTimestamp(input.occurredAt) && isIsoTimestamp(input.recordedAt)
+        && Date.parse(input.recordedAt) < Date.parse(input.occurredAt)) {
+        issues.push({
+            code: 'RECORDED_BEFORE_OCCURRED',
+            path: 'recordedAt',
+            message: 'recordedAt cannot precede occurredAt for an observation.'
+        });
+    }
+    if (input.supersedes !== undefined
+        && (!isNonEmptyString(input.supersedes) || input.supersedes.trim() === input.id?.trim())) {
+        issues.push({
+            code: 'INVALID_CORRECTION_REFERENCE',
+            path: 'supersedes',
+            message: 'A correction must reference a different non-empty observation id.'
+        });
+    }
+    return issues;
+}
+function valueMatchesKind(value, kind) {
+    switch (kind) {
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'string':
+        case 'state':
+            return typeof value === 'string' && value.length > 0;
+        default:
+            return false;
+    }
+}
+function isWorldModelValue(value, seen = new Set()) {
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return false;
+        seen.add(value);
+        const valid = value.every((item) => isWorldModelValue(item, seen));
+        seen.delete(value);
+        return valid;
+    }
+    if (!isRecord(value))
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    const valid = Object.values(value).every((item) => isWorldModelValue(item, seen));
+    seen.delete(value);
+    return valid;
+}
+function cloneWorldModelValue(value, path) {
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new WorldModelValidationError([invalid(path, 'Numbers must be finite.')]);
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map((item, index) => cloneWorldModelValue(item, `${path}[${index}]`));
+    const result = {};
+    for (const [key, item] of Object.entries(value))
+        result[key] = cloneWorldModelValue(item, `${path}.${key}`);
+    return result;
+}
+function isVariableRevision(value) {
+    return isRecord(value)
+        && value.type === 'variable'
+        && isNonEmptyString(value.id)
+        && /^[1-9]\d*$/.test(String(value.revision));
+}
+function isProvenance(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.sourceId)
+        && ['candidate', 'document', 'observation', 'decision', 'import'].includes(String(value.sourceKind))
+        && Array.isArray(value.evidenceIds)
+        && value.evidenceIds.length > 0
+        && value.evidenceIds.every((item) => isNonEmptyString(item));
+}
+function isValidPeriod(value) {
+    return isRecord(value)
+        && isIsoTimestamp(value.from)
+        && isIsoTimestamp(value.until)
+        && Date.parse(value.until) >= Date.parse(value.from);
+}
+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 parseIsoTimestamp(value) {
+    return isIsoTimestamp(value) ? Date.parse(value) : undefined;
+}
+function freezeCloneRevision(value) {
+    return deepFreeze({ id: value.id, type: value.type, revision: value.revision });
+}
+function freezeCloneDecisionRevision(value) {
+    return deepFreeze({ id: value.id, type: 'decision', revision: value.revision });
+}
+function freezeClonePeriod(value) {
+    return deepFreeze({ from: value.from, until: value.until });
+}
+function freezeCloneProvenance(value) {
+    return deepFreeze({ sourceId: value.sourceId, sourceKind: value.sourceKind, evidenceIds: [...value.evidenceIds] });
+}
+function freezeCloneAcl(value) {
+    return deepFreeze({
+        ownerId: value.ownerId,
+        visibility: value.visibility,
+        readerIds: [...value.readerIds],
+        writerIds: [...value.writerIds]
+    });
+}
+function validationResult(issues) {
+    return { valid: issues.length === 0, status: issues.length === 0 ? 'valid' : 'invalid', issues: deepFreeze([...issues]) };
+}
+function missing(path) {
+    return { code: 'MISSING_FIELD', path, message: `${path} is required.` };
+}
+function invalid(path, message) {
+    return { code: 'INVALID_FIELD', path, message };
+}
+function invalidTimestamp(path) {
+    return { code: 'INVALID_TIMESTAMP', path, message: `${path} must be an ISO 8601 timestamp with timezone.` };
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}