@unson/brainbase-mcp 0.7.0 → 0.9.0

package/dist/judgment-problem-snapshot.d.ts

@@ -1,4 +1,4 @@
-import { type FoundationDefinition, type FoundationAcl, type FoundationRevision } from './ontology-foundation.js';
+import { type FoundationDefinition, type FoundationAcl, type FoundationEvaluationDescriptor, type FoundationRevision } from './ontology-foundation.js';
 /**
  * An immutable input bundle for one judgment.
  *
@@ -8,7 +8,7 @@ import { type FoundationDefinition, type FoundationAcl, type FoundationRevision
  */
 export declare const JUDGMENT_PROBLEM_SNAPSHOT_VERSION: "judgment-problem-snapshot.v1";
 export type JudgmentProblemSnapshotId = `sha256:${string}`;
-export type JudgmentProblemReferenceKind = 'objective' | 'criterion' | 'variable' | 'observation' | 'model' | 'constraint' | 'authority' | 'resource' | 'deadline' | 'dag' | 'evidence';
+export type JudgmentProblemReferenceKind = 'entity' | 'edge' | 'objective' | 'criterion' | 'variable' | 'observation' | 'model' | 'constraint' | 'philosophy' | 'authority' | 'resource' | 'deadline' | 'dag' | 'evidence';
 export type JudgmentProblemScopeType = 'personal' | 'project' | 'organization';
 export interface JudgmentProblemScope {
     readonly type: JudgmentProblemScopeType;
@@ -35,8 +35,15 @@ export interface JudgmentProblemReference {
     readonly scope: JudgmentProblemScope;
     readonly valid_from: string;
     readonly valid_to?: string | null;
+    /**
+     * Source-owned measurement conditions for an Observation reference.  The
+     * descriptor is checked against the canonical Variable and Objective
+     * before a current judgment can use the observation.
+     */
+    readonly measurement?: JudgmentProblemObservationMeasurementDescriptor;
     readonly evidence?: JudgmentProblemEvidenceBinding;
 }
+export type JudgmentProblemObservationMeasurementDescriptor = FoundationEvaluationDescriptor;
 /**
  * Stable name shared by sub-DAG and reservation consumers.  A ProblemRef is
  * intentionally only a versioned, scoped reference; it never carries an
@@ -90,6 +97,10 @@ export interface JudgmentProblemReferenceResolution {
     /** The provider must return the digest of the exact revision it resolved. */
     readonly digest?: JudgmentProblemSnapshotId;
     readonly message?: string;
+    /** Canonical Observation metadata returned by the source-owned resolver. */
+    readonly canonical?: {
+        readonly measurement?: JudgmentProblemObservationMeasurementDescriptor;
+    };
 }
 /**
  * A provider is the only place that knows how an Observation, authority,
@@ -104,6 +115,8 @@ export interface JudgmentProblemReferenceProvider {
         readonly reference: JudgmentProblemReference;
         readonly phase: JudgmentProblemReferenceResolutionPhase;
         readonly context: JudgmentProblemSnapshotAccessContext;
+        /** The full bundle enables cross-reference coherence checks. */
+        readonly snapshot?: JudgmentProblemSnapshot;
     }): JudgmentProblemReferenceResolution | Promise<JudgmentProblemReferenceResolution>;
 }
 export interface SaveJudgmentProblemSnapshotRequest {
@@ -124,6 +137,19 @@ export interface LoadJudgmentProblemSnapshotRequest {
     readonly reference_resolution?: JudgmentProblemReferenceResolutionMode;
     readonly referenceProvider?: JudgmentProblemReferenceProvider;
 }
+/**
+ * Validate a not-yet-persisted snapshot through the same read and reference
+ * boundaries used by load.  This is intentionally read-only: callers cannot
+ * turn validation into publication by passing an artifact root.
+ */
+export interface ValidateJudgmentProblemSnapshotRequest {
+    readonly snapshot: JudgmentProblemSnapshot;
+    readonly access: JudgmentProblemSnapshotAccessContext;
+    readonly accessProvider?: JudgmentProblemSnapshotAccessProvider;
+    /** Defaults to `current`; historical validation only rechecks ACL/digest. */
+    readonly reference_resolution?: JudgmentProblemReferenceResolutionMode;
+    readonly referenceProvider: JudgmentProblemReferenceProvider;
+}
 export interface JudgmentProblemSnapshotReceipt {
     readonly snapshot_id: JudgmentProblemSnapshotId;
     readonly snapshot_version: typeof JUDGMENT_PROBLEM_SNAPSHOT_VERSION;
@@ -147,6 +173,7 @@ export declare const defaultJudgmentProblemSnapshotAccessProvider: JudgmentProbl
 export declare function computeJudgmentProblemSnapshotId(value: JudgmentProblemSnapshot): JudgmentProblemSnapshotId;
 export declare function saveJudgmentProblemSnapshot(request: SaveJudgmentProblemSnapshotRequest): Promise<JudgmentProblemSnapshotReceipt>;
 export declare function loadJudgmentProblemSnapshot(request: LoadJudgmentProblemSnapshotRequest): Promise<JudgmentProblemSnapshot>;
+export declare function validateJudgmentProblemSnapshot(request: ValidateJudgmentProblemSnapshotRequest): Promise<void>;
 /** Structural adapter for FoundationRevisionStore-like readers. */
 export interface JudgmentProblemFoundationReferenceReader {
     read(reference: FoundationRevision, context: {
@@ -181,5 +208,6 @@ export declare function createJudgmentProblemFoundationReferenceProvider(options
         readonly reference: JudgmentProblemReference;
         readonly phase: JudgmentProblemReferenceResolutionPhase;
         readonly context: JudgmentProblemSnapshotAccessContext;
+        readonly snapshot?: JudgmentProblemSnapshot;
     }) => JudgmentProblemReferenceResolution | Promise<JudgmentProblemReferenceResolution>;
 }): JudgmentProblemReferenceProvider;

package/dist/judgment-problem-snapshot.js

@@ -1,7 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { link, open, lstat, mkdir, readdir, readFile, unlink } from 'node:fs/promises';
 import path from 'node:path';
-import { validateFoundationDefinition } from './ontology-foundation.js';
+import { validateFoundationDefinition, validateEvaluationCompatibility } from './ontology-foundation.js';
+import { checkObjectiveReadiness } from './company-os-objectives.js';
 /**
  * An immutable input bundle for one judgment.
  *
@@ -24,12 +25,15 @@ const SNAPSHOT_ID_PATTERN = /^sha256:([0-9a-f]{64})$/u;
 const POSITIVE_REVISION_PATTERN = /^[1-9]\d*$/u;
 const SCOPE_TYPES = ['personal', 'project', 'organization'];
 const REFERENCE_KINDS = [
+    'entity',
+    'edge',
     'objective',
     'criterion',
     'variable',
     'observation',
     'model',
     'constraint',
+    'philosophy',
     'authority',
     'resource',
     'deadline',
@@ -48,7 +52,7 @@ const SNAPSHOT_KEYS = [
     'snapshot_version'
 ];
 const ENVELOPE_KEYS = ['snapshot', 'snapshot_id', 'snapshot_version'];
-const REFERENCE_KEYS = ['digest', 'evidence', 'id', 'kind', 'revision', 'scope', 'valid_from', 'valid_to'];
+const REFERENCE_KEYS = ['digest', 'evidence', 'id', 'kind', 'measurement', 'revision', 'scope', 'valid_from', 'valid_to'];
 const EVIDENCE_KEYS = ['access', 'content', 'digest', 'mode', 'reference_id', 'reference_revision'];
 const SCOPE_KEYS = ['id', 'type'];
 const ACL_KEYS = ['ownerId', 'readerIds', 'visibility', 'writerIds'];
@@ -254,6 +258,9 @@ function validateReference(value, index) {
     if (validTo !== undefined && Date.parse(validTo) < Date.parse(validFrom)) {
         fail('invalid_request', `${label}.valid_to precedes valid_from`);
     }
+    const measurement = value.measurement === undefined
+        ? undefined
+        : validateMeasurementDescriptor(value.measurement, `${label}.measurement`);
     const evidence = value.evidence === undefined ? undefined : validateEvidence(value.evidence, `${label}.evidence`);
     return deepFreeze({
         kind: value.kind,
@@ -263,9 +270,73 @@ function validateReference(value, index) {
         scope: { type: value.scope.type, id: value.scope.id },
         valid_from: validFrom,
         ...(validTo === undefined ? {} : { valid_to: validTo }),
+        ...(measurement === undefined ? {} : { measurement }),
         ...(evidence === undefined ? {} : { evidence })
     });
 }
+function validateMeasurementDescriptor(value, label) {
+    const aggregations = [
+        'none',
+        'sum',
+        'average',
+        'count',
+        'min',
+        'max',
+        'last',
+        'custom'
+    ];
+    const keys = ['aggregation', 'granularity', 'period', 'scope', 'unit', 'variableRef'];
+    if (!isPlainRecord(value) || !hasOnlyKeys(value, keys)
+        || !Object.prototype.hasOwnProperty.call(value, 'variableRef')
+        || !Object.prototype.hasOwnProperty.call(value, 'aggregation')
+        || !Object.prototype.hasOwnProperty.call(value, 'granularity')
+        || !Object.prototype.hasOwnProperty.call(value, 'scope')
+        || !Object.prototype.hasOwnProperty.call(value, 'period')) {
+        fail('invalid_request', `${label} is invalid`);
+    }
+    if (!isPlainRecord(value.variableRef)
+        || !hasExactKeys(value.variableRef, ['id', 'revision', 'type'])
+        || value.variableRef.type !== 'variable') {
+        fail('invalid_request', `${label}.variableRef must reference a Variable revision`);
+    }
+    const variableId = requireString(value.variableRef.id, `${label}.variableRef.id`);
+    const variableRevision = requireRevision(value.variableRef.revision, `${label}.variableRef.revision`);
+    if (typeof value.aggregation !== 'string' || !aggregations.includes(value.aggregation)) {
+        fail('invalid_request', `${label}.aggregation is invalid`);
+    }
+    const granularity = requireString(value.granularity, `${label}.granularity`);
+    if (value.unit !== undefined && typeof value.unit !== 'string') {
+        fail('invalid_request', `${label}.unit must be a string when provided`);
+    }
+    if (!isPlainRecord(value.scope)
+        || !Array.isArray(value.scope.subjectIds)
+        || value.scope.subjectIds.some((subjectId) => typeof subjectId !== 'string' || subjectId.trim().length === 0)
+        || typeof value.scope.validFrom !== 'string'
+        || Number.isNaN(Date.parse(value.scope.validFrom))
+        || (value.scope.validUntil !== undefined && (typeof value.scope.validUntil !== 'string' || Number.isNaN(Date.parse(value.scope.validUntil))))) {
+        fail('invalid_request', `${label}.scope is invalid`);
+    }
+    if (!isPlainRecord(value.period)
+        || typeof value.period.from !== 'string'
+        || typeof value.period.until !== 'string'
+        || Number.isNaN(Date.parse(value.period.from))
+        || Number.isNaN(Date.parse(value.period.until))
+        || Date.parse(value.period.until) < Date.parse(value.period.from)) {
+        fail('invalid_request', `${label}.period is invalid`);
+    }
+    return deepFreeze({
+        variableRef: { id: variableId, type: 'variable', revision: variableRevision },
+        ...(value.unit === undefined ? {} : { unit: value.unit }),
+        aggregation: value.aggregation,
+        granularity,
+        scope: {
+            subjectIds: [...value.scope.subjectIds],
+            validFrom: value.scope.validFrom,
+            ...(value.scope.validUntil === undefined ? {} : { validUntil: value.scope.validUntil })
+        },
+        period: { from: value.period.from, until: value.period.until }
+    });
+}
 function validateSnapshot(value) {
     if (!isPlainRecord(value) || !hasExactKeys(value, SNAPSHOT_KEYS) ||
         value.snapshot_version !== JUDGMENT_PROBLEM_SNAPSHOT_VERSION ||
@@ -299,6 +370,10 @@ function requiredKinds(references) {
 }
 function validateRequiredReferences(snapshot) {
     const kinds = requiredKinds(snapshot.references);
+    const objectiveCount = snapshot.references.filter((reference) => reference.kind === 'objective').length;
+    if (objectiveCount !== 1) {
+        fail('invalid_request', `snapshot must contain exactly one objective reference; found ${objectiveCount}`);
+    }
     const required = [
         'objective',
         'criterion',
@@ -353,10 +428,10 @@ function evidenceReference(owner, evidence) {
         ...(owner.valid_to === undefined ? {} : { valid_to: owner.valid_to })
     };
 }
-async function resolveOneReference(reference, phase, context, provider, errorReference = reference) {
+async function resolveOneReference(reference, phase, context, provider, snapshot, errorReference = reference) {
     let result;
     try {
-        result = await provider.resolve({ reference, phase, context });
+        result = await provider.resolve({ reference, phase, context, snapshot });
     }
     catch (error) {
         if (error instanceof JudgmentProblemSnapshotError)
@@ -383,9 +458,9 @@ async function resolveOneReference(reference, phase, context, provider, errorRef
 }
 async function resolveReferences(snapshot, phase, context, provider) {
     for (const reference of snapshot.references) {
-        await resolveOneReference(reference, phase, context, provider);
+        await resolveOneReference(reference, phase, context, provider, snapshot);
         if (reference.evidence?.mode === 'immutable_reference') {
-            await resolveOneReference(evidenceReference(reference, reference.evidence), phase, context, provider, reference);
+            await resolveOneReference(evidenceReference(reference, reference.evidence), phase, context, provider, snapshot, reference);
         }
     }
 }
@@ -682,6 +757,43 @@ export async function loadJudgmentProblemSnapshot(request) {
     await resolveReferences(envelope.snapshot, referenceResolution === 'current' ? 'read' : 'historical_read', context, request.referenceProvider);
     return envelope.snapshot;
 }
+export async function validateJudgmentProblemSnapshot(request) {
+    if (!isPlainRecord(request))
+        fail('invalid_request', 'validation request must be a plain object');
+    const snapshot = validateSnapshot(request.snapshot);
+    validateRequiredReferences(snapshot);
+    const context = validateAccessContext(request.access);
+    const referenceResolution = request.reference_resolution ?? 'current';
+    if (referenceResolution !== 'current' && referenceResolution !== 'historical') {
+        fail('invalid_request', 'reference_resolution must be current or historical');
+    }
+    if (!request.referenceProvider || typeof request.referenceProvider.resolve !== 'function') {
+        fail('invalid_request', `referenceProvider.resolve is required for ${referenceResolution} reference resolution`);
+    }
+    const accessProvider = request.accessProvider ?? defaultJudgmentProblemSnapshotAccessProvider;
+    await authorize('read', snapshot, context, accessProvider);
+    for (const reference of snapshot.references) {
+        if (reference.evidence === undefined)
+            continue;
+        try {
+            const allowed = await accessProvider.authorize({
+                action: 'read',
+                context,
+                acl: reference.evidence.access,
+                snapshot,
+                reference
+            });
+            if (allowed === false)
+                fail('unauthorized', `evidence access was denied for ${reference.kind}/${reference.id}@${reference.revision}`, reference);
+        }
+        catch (error) {
+            if (error instanceof JudgmentProblemSnapshotError)
+                throw error;
+            fail('unauthorized', `evidence access was denied for ${reference.kind}/${reference.id}@${reference.revision}`, reference);
+        }
+    }
+    await resolveReferences(snapshot, referenceResolution === 'current' ? 'read' : 'historical_read', context, request.referenceProvider);
+}
 function validateAccessContext(value) {
     if (!isPlainRecord(value) || typeof value.principal !== 'string' || value.principal.trim().length === 0 || value.principal.includes('\0')) {
         fail('unauthorized', 'a trusted principal is required');
@@ -699,8 +811,16 @@ function validateAccessContext(value) {
  * bypass the canonical store or digest check.
  */
 export function createJudgmentProblemFoundationReferenceProvider(options) {
+    const objectiveReader = {
+        async read(reference, context) {
+            return await options.store.read(reference, { principal: context.principal });
+        }
+    };
     return {
         async resolve(input) {
+            if (input.reference.kind === 'observation') {
+                return resolveObservationReference(input, options, objectiveReader);
+            }
             if (!['objective', 'variable', 'model', 'constraint'].includes(input.reference.kind)) {
                 if (options.resolveOther)
                     return options.resolveOther(input);
@@ -733,6 +853,26 @@ export function createJudgmentProblemFoundationReferenceProvider(options) {
                     return { status: 'not_applicable', message: applicability.message };
                 }
             }
+            if (definition.type === 'objective') {
+                if (input.phase === 'historical_read') {
+                    const dependencyResult = await validateObjectiveDependencies(definition, input, options);
+                    if (dependencyResult)
+                        return dependencyResult;
+                }
+                else {
+                    const readiness = await checkObjectiveReadiness(objectiveReader, input.reference.id, { principal: input.context.principal }, input.reference.revision);
+                    if (!readiness.ready)
+                        return objectiveReadinessResult(readiness.issues);
+                    const dependencyResult = await validateObjectiveDependencies(definition, input, options);
+                    if (dependencyResult)
+                        return dependencyResult;
+                }
+            }
+            if (definition.type === 'model') {
+                const dependencyResult = await validateModelDependencies(definition, input, options);
+                if (dependencyResult)
+                    return dependencyResult;
+            }
             if (options.validate) {
                 return options.validate({
                     ...input,
@@ -743,6 +883,162 @@ export function createJudgmentProblemFoundationReferenceProvider(options) {
         }
     };
 }
+function objectiveReadinessResult(issues) {
+    const notApplicable = issues.some((issue) => (issue.code === 'UNAUTHORIZED_USE' || issue.code === 'CRITERION_PERIOD_MISMATCH'));
+    return {
+        status: notApplicable ? 'not_applicable' : 'unresolved',
+        message: issues.map((issue) => issue.message).join('; ')
+    };
+}
+async function validateObjectiveDependencies(definition, input, options) {
+    for (const criterion of definition.criteria) {
+        const dependency = criterion?.variableRef;
+        if (!isVariableRevision(dependency)) {
+            return { status: 'unresolved', message: 'Objective criterion does not reference a valid Variable revision' };
+        }
+        const resolved = await options.store.read(dependency, { principal: input.context.principal });
+        if (!resolved)
+            return { status: 'missing', message: `Objective Variable ${dependency.id}@${dependency.revision} was not found` };
+        if (!matchingFoundationRecord(resolved, dependency, 'variable')) {
+            return { status: 'unresolved', message: `Objective Variable ${dependency.id}@${dependency.revision} is not the requested revision` };
+        }
+        const pinned = findSnapshotReference(input.snapshot, dependency);
+        if (pinned && pinned.digest !== resolved.digest) {
+            return { status: 'unresolved', message: `Objective Variable ${dependency.id}@${dependency.revision} digest changed` };
+        }
+    }
+    return undefined;
+}
+async function validateModelDependencies(definition, input, options) {
+    const dependencies = [...definition.inputVariableRefs, ...definition.outputVariableRefs];
+    const seen = new Set();
+    for (const dependency of dependencies) {
+        if (!isVariableRevision(dependency)) {
+            return { status: 'unresolved', message: 'Model input/output must reference a valid Variable revision' };
+        }
+        const key = `${dependency.id}@${dependency.revision}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const resolved = await options.store.read(dependency, { principal: input.context.principal });
+        if (!resolved)
+            return { status: 'missing', message: `Model Variable ${dependency.id}@${dependency.revision} was not found` };
+        if (!matchingFoundationRecord(resolved, dependency, 'variable')) {
+            return { status: 'unresolved', message: `Model Variable ${dependency.id}@${dependency.revision} is not the requested revision` };
+        }
+        const pinned = findSnapshotReference(input.snapshot, dependency);
+        if (pinned && pinned.digest !== resolved.digest) {
+            return { status: 'unresolved', message: `Model Variable ${dependency.id}@${dependency.revision} digest changed` };
+        }
+        if (input.phase === 'historical_read')
+            continue;
+        const definitionResult = validateFoundationDefinition(resolved.definition, { use: 'judgment' });
+        if (!definitionResult.valid) {
+            const notApplicable = definitionResult.issues.some((issue) => issue.code === 'UNAUTHORIZED_USE');
+            return {
+                status: notApplicable ? 'not_applicable' : 'unresolved',
+                message: definitionResult.issues.map((issue) => issue.message).join('; ')
+            };
+        }
+        const applicability = validateFoundationReferenceApplicability(input.reference, resolved.definition);
+        if (!applicability.valid)
+            return { status: 'not_applicable', message: applicability.message };
+    }
+    return undefined;
+}
+function isVariableRevision(value) {
+    return isPlainRecord(value)
+        && value.type === 'variable'
+        && typeof value.id === 'string'
+        && value.id.length > 0
+        && typeof value.revision === 'string'
+        && /^[1-9]\d*$/u.test(value.revision);
+}
+function matchingFoundationRecord(record, reference, type) {
+    return typeof record.digest === 'string'
+        && isPlainRecord(record.definition)
+        && record.definition.type === type
+        && record.definition.id === reference.id
+        && record.definition.revision === reference.revision;
+}
+function findSnapshotReference(snapshot, reference) {
+    return snapshot?.references.find((candidate) => (candidate.kind === reference.type
+        && candidate.id === reference.id
+        && candidate.revision === reference.revision));
+}
+async function resolveObservationReference(input, options, objectiveReader) {
+    if (!options.resolveOther)
+        return { status: 'unresolved', message: 'No canonical Observation provider is registered' };
+    const resolved = await options.resolveOther(input);
+    if (resolved.status !== 'resolved')
+        return resolved;
+    const descriptor = input.reference.measurement;
+    const canonical = resolved.canonical?.measurement;
+    if (input.phase === 'historical_read') {
+        if (descriptor !== undefined && canonical !== undefined && !sameMeasurementDescriptor(descriptor, canonical)) {
+            return { status: 'unresolved', message: 'Historical Observation measurement metadata changed' };
+        }
+        return resolved;
+    }
+    if (descriptor === undefined || canonical === undefined) {
+        return { status: 'unresolved', message: 'Current Observation requires canonical measurement metadata and a pinned descriptor' };
+    }
+    if (!sameMeasurementDescriptor(descriptor, canonical)) {
+        return { status: 'unresolved', message: 'Observation measurement descriptor does not match canonical metadata' };
+    }
+    const snapshot = input.snapshot;
+    if (!snapshot)
+        return { status: 'unresolved', message: 'Current Observation validation requires the complete snapshot bundle' };
+    const objectiveReference = snapshot.references.find((candidate) => candidate.kind === 'objective');
+    if (!objectiveReference)
+        return { status: 'unresolved', message: 'Current Observation requires an Objective reference' };
+    const objectiveRecord = await options.store.read({ id: objectiveReference.id, type: 'objective', revision: objectiveReference.revision }, { principal: input.context.principal });
+    if (!objectiveRecord)
+        return { status: 'missing', message: 'Objective for Observation measurement was not found' };
+    const objectiveRevision = {
+        id: objectiveReference.id,
+        type: 'objective',
+        revision: objectiveReference.revision
+    };
+    if (!matchingFoundationRecord(objectiveRecord, objectiveRevision, 'objective')) {
+        return { status: 'unresolved', message: 'Objective for Observation measurement is not the requested revision' };
+    }
+    if (objectiveRecord.digest !== objectiveReference.digest) {
+        return { status: 'unresolved', message: 'Objective for Observation measurement digest changed' };
+    }
+    const objectiveDefinition = objectiveRecord.definition;
+    const objectiveApplicability = validateFoundationReferenceApplicability(objectiveReference, objectiveDefinition);
+    if (!objectiveApplicability.valid)
+        return { status: 'not_applicable', message: objectiveApplicability.message };
+    const readiness = await checkObjectiveReadiness(objectiveReader, objectiveReference.id, { principal: input.context.principal }, objectiveReference.revision);
+    if (!readiness.ready)
+        return objectiveReadinessResult(readiness.issues);
+    const variableRecord = await options.store.read(descriptor.variableRef, { principal: input.context.principal });
+    if (!variableRecord)
+        return { status: 'missing', message: 'Observation measurement Variable was not found' };
+    if (!matchingFoundationRecord(variableRecord, descriptor.variableRef, 'variable')) {
+        return { status: 'unresolved', message: 'Observation measurement Variable is not the requested revision' };
+    }
+    const pinnedVariable = findSnapshotReference(snapshot, descriptor.variableRef);
+    if (pinnedVariable && pinnedVariable.digest !== variableRecord.digest) {
+        return { status: 'unresolved', message: 'Observation measurement Variable digest changed' };
+    }
+    const compatibility = validateEvaluationCompatibility(variableRecord.definition, descriptor, { period: objectiveDefinition.evaluationPeriod });
+    if (!compatibility.valid) {
+        const notApplicable = compatibility.issues.some((issue) => issue.code === 'UNAUTHORIZED_USE');
+        return {
+            status: notApplicable ? 'not_applicable' : 'unresolved',
+            message: compatibility.issues.map((issue) => issue.message).join('; ')
+        };
+    }
+    if (!scopeContainsReference(descriptor.scope, input.reference)) {
+        return { status: 'not_applicable', message: 'Observation measurement scope does not cover the Observation reference' };
+    }
+    return resolved;
+}
+function sameMeasurementDescriptor(left, right) {
+    return canonicalJson(left) === canonicalJson(right);
+}
 function validateFoundationReferenceApplicability(reference, definition) {
     const scopes = definition.type === 'model'
         ? [definition.scope, definition.applicability]

package/dist/judgment-value-proof-review.d.ts

@@ -0,0 +1,166 @@
+import { type JudgmentValueProof } from './judgment-value-proof.js';
+export declare const JUDGMENT_VALUE_PROOF_FILE_SUFFIX = ".value-proof.json";
+export declare const JUDGMENT_VALUE_PROOF_FEEDBACK_SCHEMA = "brainbase-judgment-value-proof-feedback-v1";
+export declare const JUDGMENT_VALUE_PROOF_FEEDBACK_FILE = "judgment-value-proof-feedback.jsonl";
+export type JudgmentValueProofReviewSection = 'needs_human' | 'blocked' | 'continued' | 'other';
+export type JudgmentValueProofFeedbackStatus = 'accepted' | 'corrected' | 'next_time_ask' | 'reverted';
+/** What the owner's feedback asks to change. `delegation` is the ask/continue boundary. */
+export type JudgmentValueProofFeedbackLayer = 'delegation' | 'method' | 'objective' | 'world_model' | 'philosophy' | 'other';
+export declare const JUDGMENT_VALUE_PROOF_FEEDBACK_LAYERS: readonly JudgmentValueProofFeedbackLayer[];
+export interface JudgmentValueProofJournalEntry {
+    readonly file: string;
+    readonly proof: JudgmentValueProof;
+}
+export interface JudgmentValueProofJournalRejection {
+    readonly file: string;
+    readonly reason: string;
+}
+export type JudgmentValueProofJournalRead = {
+    readonly status: 'unavailable';
+    readonly root: string;
+    readonly reason: string;
+} | {
+    readonly status: 'available';
+    readonly root: string;
+    readonly entries: readonly JudgmentValueProofJournalEntry[];
+    readonly rejected: readonly JudgmentValueProofJournalRejection[];
+    readonly latest_recorded_at: string | null;
+};
+export interface JudgmentValueProofFeedbackRecord {
+    readonly schema_version: typeof JUDGMENT_VALUE_PROOF_FEEDBACK_SCHEMA;
+    readonly feedback_id: string;
+    readonly intent_id: string;
+    readonly decision_attempt_id: string;
+    readonly status: JudgmentValueProofFeedbackStatus;
+    readonly summary: string | null;
+    /** Absent on records written before the layer was introduced. */
+    readonly target_layer?: JudgmentValueProofFeedbackLayer | null;
+    readonly recorded_at: string;
+}
+export interface JudgmentValueProofFeedbackInput {
+    readonly dataDir?: string;
+    readonly intent_id: string;
+    readonly decision_attempt_id: string;
+    readonly status: JudgmentValueProofFeedbackStatus;
+    readonly summary?: string | null;
+    readonly target_layer?: JudgmentValueProofFeedbackLayer | null;
+    readonly now?: Date;
+}
+export interface JudgmentValueProofReviewItem {
+    readonly file: string;
+    readonly section: JudgmentValueProofReviewSection;
+    readonly proof: JudgmentValueProof;
+    readonly feedback_history: readonly JudgmentValueProofFeedbackRecord[];
+}
+export type JudgmentValueProofReviewHome = {
+    readonly status: 'unavailable';
+    readonly root: string;
+    readonly reason: string;
+} | {
+    readonly status: 'available';
+    readonly root: string;
+    readonly coverage: {
+        readonly saved: number;
+        readonly rejected: number;
+        readonly latest_recorded_at: string | null;
+        readonly possibly_stalled: boolean;
+    };
+    readonly sections: Readonly<Record<JudgmentValueProofReviewSection, readonly JudgmentValueProofReviewItem[]>>;
+    readonly delegation_map: JudgmentDelegationMap;
+    readonly rejected: readonly JudgmentValueProofJournalRejection[];
+};
+/** Whether Brainbase currently proceeds on a kind of judgment, is being checked, or asks the owner. */
+export type JudgmentDelegationState = 'delegated' | 'verifying' | 'returned';
+/** Rows are kinds when recorded; otherwise the reason code, which is not a kind and is shown apart. */
+export type JudgmentDelegationRowSource = 'judgment_kind' | 'reason_code' | 'unrecorded';
+export type JudgmentDelegationStateBasis = {
+    readonly reason: 'latest_judgment_returned';
+    readonly at: string;
+} | {
+    readonly reason: 'latest_feedback';
+    readonly status: JudgmentValueProofFeedbackStatus;
+    readonly target_layer: JudgmentValueProofFeedbackLayer | null;
+    readonly at: string;
+} | {
+    readonly reason: 'no_feedback';
+};
+export interface JudgmentDelegationItemRef {
+    readonly intent_id: string;
+    readonly decision_attempt_id: string;
+    readonly row_key: string;
+}
+export interface JudgmentDelegationRow {
+    readonly key: string;
+    readonly source: JudgmentDelegationRowSource;
+    /** Kind label or reason code; null for judgments that recorded neither. */
+    readonly label: string | null;
+    readonly state: JudgmentDelegationState;
+    readonly state_basis: JudgmentDelegationStateBasis;
+    readonly counts: {
+        readonly continued: number;
+        readonly returned: number;
+        readonly rated: number;
+        readonly by_feedback: Readonly<Record<JudgmentValueProofFeedbackStatus, number>>;
+        readonly corrected_or_reverted: number;
+        readonly inherited: number;
+    };
+    readonly latest_recorded_at: string;
+    /** Newest first. */
+    readonly items: readonly JudgmentDelegationItemRef[];
+}
+export interface JudgmentDelegationMap {
+    readonly judged: number;
+    readonly kind_recorded: number;
+    readonly rated: number;
+    /** Kind rows first, then reason-code rows, then the unrecorded row. */
+    readonly rows: readonly JudgmentDelegationRow[];
+    /** Continued without asking, then corrected or reverted by the owner (P14). */
+    readonly corrected_after_continue: readonly JudgmentDelegationItemRef[];
+    /** Continued without asking after the owner asked to be asked for that row. */
+    readonly continued_after_ask: readonly JudgmentDelegationItemRef[];
+}
+export declare function defaultJudgmentJournalRoot(dataDir?: string): string;
+/**
+ * Reads saved judgment value proofs from `<root>/*.value-proof.json` and
+ * `<root>/<session>/*.value-proof.json`. The journal is read-only here.
+ */
+export declare function readJudgmentValueProofJournal(options?: {
+    readonly root?: string;
+}): Promise<JudgmentValueProofJournalRead>;
+export declare function classifyJudgmentValueProof(proof: JudgmentValueProof): JudgmentValueProofReviewSection;
+/** Reads all recorded feedback in append order. A missing file means no feedback has been recorded. */
+export declare function readJudgmentValueProofFeedback(options?: {
+    readonly dataDir?: string;
+}): Promise<readonly JudgmentValueProofFeedbackRecord[]>;
+/**
+ * Appends one owner feedback record without touching the judgment journal.
+ * Re-sending the same attempt, status and summary returns the existing record.
+ */
+export declare function recordJudgmentValueProofFeedback(input: JudgmentValueProofFeedbackInput): Promise<{
+    readonly record: JudgmentValueProofFeedbackRecord;
+    readonly created: boolean;
+}>;
+/** Returns the proof with its latest owner feedback applied, plus the feedback history for that attempt. */
+export declare function applyJudgmentValueProofFeedback(proof: JudgmentValueProof, records: readonly JudgmentValueProofFeedbackRecord[]): {
+    readonly proof: JudgmentValueProof;
+    readonly history: readonly JudgmentValueProofFeedbackRecord[];
+};
+export declare function buildJudgmentValueProofReviewHome(journal: JudgmentValueProofJournalRead, feedback: readonly JudgmentValueProofFeedbackRecord[], options?: {
+    readonly now?: Date;
+    readonly staleAfterMs?: number;
+}): JudgmentValueProofReviewHome;
+/**
+ * Groups reviewable judgments by kind and decides, per kind, whether Brainbase is trusted to
+ * proceed, is still being checked, or returns the judgment to the owner. Deterministic: the state
+ * follows only the newest judgment and the newest owner feedback in the row.
+ */
+export declare function buildJudgmentDelegationMap(items: readonly JudgmentValueProofReviewItem[], feedback: readonly JudgmentValueProofFeedbackRecord[]): JudgmentDelegationMap;
+export interface JudgmentValueProofFeedbackSummary {
+    /** Decisions with at least one feedback record; each counts once, by its latest feedback. */
+    readonly rated: number;
+    readonly by_status: Readonly<Record<JudgmentValueProofFeedbackStatus, number>>;
+    /** Latest `corrected` and `next_time_ask` feedback by the layer they ask to change. */
+    readonly by_layer: Readonly<Record<JudgmentValueProofFeedbackLayer | 'unrecorded', number>>;
+}
+/** Counts the latest feedback per decision, for deciding where revisions should live. */
+export declare function summarizeJudgmentValueProofFeedback(records: readonly JudgmentValueProofFeedbackRecord[]): JudgmentValueProofFeedbackSummary;