@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/company-os-objectives.d.ts

@@ -0,0 +1,63 @@
+import type { ObjectiveDefinition, VariableDefinition, FoundationRevision, FoundationTimeCondition } from './ontology-foundation.js';
+import type { FoundationRef } from './foundation-catalog.js';
+import type { FoundationCatalogRecord } from './types.js';
+import type { FoundationRevisionStore, FoundationStoreContext } from './foundation-store.js';
+export interface ObjectiveReadinessIssue {
+    code: string;
+    path: string;
+    message: string;
+}
+export interface ObjectiveReadiness {
+    /** Whether the definition can be used for a judgment or evaluation setup. */
+    ready: boolean;
+    /** Definition and referenced Variable issues; observations are not inferred. */
+    issues: readonly ObjectiveReadinessIssue[];
+}
+/** The canonical read surface needed to check an Objective and its criteria. */
+export interface ObjectiveReadinessReader {
+    read(reference: FoundationRevision, context: FoundationStoreContext): Promise<FoundationCatalogRecord | null>;
+    readLatest?(type: 'objective' | 'variable', id: string, context: FoundationStoreContext): Promise<FoundationCatalogRecord | null>;
+}
+export type StoryObjectiveLinkKind = 'contribution' | 'execution_dependency' | 'time_condition';
+export interface StoryObjectiveLinkInput {
+    storyId: string;
+    storyRevision?: string;
+    objective: FoundationRevision;
+    linkKind: StoryObjectiveLinkKind;
+    timeCondition?: FoundationTimeCondition;
+}
+/**
+ * Typed Story 02 operations over the shared foundation revision port.
+ *
+ * This class owns no storage.  It prevents callers from accidentally using a
+ * Variable as an Objective, while the generic store remains the one canonical
+ * Graph SSOT writer and authorization boundary.
+ */
+export declare class CompanyOsObjectives {
+    private readonly store;
+    constructor(store: FoundationRevisionStore);
+    createObjective(definition: ObjectiveDefinition, context: FoundationStoreContext): Promise<FoundationRef>;
+    readObjective(id: string, context: FoundationStoreContext, revision?: string): Promise<FoundationCatalogRecord | null>;
+    updateObjective(id: string, expectedRevision: string, next: ObjectiveDefinition, context: FoundationStoreContext): Promise<FoundationRef>;
+    checkObjectiveReadiness(id: string, context: FoundationStoreContext, revision?: string): Promise<ObjectiveReadiness>;
+    createVariable(definition: VariableDefinition, context: FoundationStoreContext): Promise<FoundationRef>;
+    readVariable(id: string, context: FoundationStoreContext, revision?: string): Promise<FoundationCatalogRecord | null>;
+    updateVariable(id: string, expectedRevision: string, next: VariableDefinition, context: FoundationStoreContext): Promise<FoundationRef>;
+    /** Exposes typed relation persistence without creating a second relation store. */
+    addRelation(relation: Parameters<FoundationRevisionStore['addRelation']>[0], context: FoundationStoreContext): Promise<void>;
+    /**
+     * Stores one explicitly typed Story/Objective reference.  The relation kind
+     * is required by the caller and is never inferred from the Story text.
+     * Objective revisions are supplied explicitly so a later Objective update
+     * cannot silently rewrite the historical link.
+     */
+    linkObjectiveStory(input: StoryObjectiveLinkInput, context: FoundationStoreContext): Promise<void>;
+    private readTyped;
+}
+/**
+ * Check an Objective and every Variable revision named by its criteria.
+ * Both the Objective service and judgment snapshot providers call this
+ * function so readiness cannot vary by caller.
+ */
+export declare function checkObjectiveReadiness(reader: ObjectiveReadinessReader, id: string, context: FoundationStoreContext, revision?: string): Promise<ObjectiveReadiness>;
+export declare function createCompanyOsObjectives(store: FoundationRevisionStore): CompanyOsObjectives;

package/dist/company-os-objectives.js

@@ -0,0 +1,234 @@
+import { validateFoundationDefinition } from './ontology-foundation.js';
+/**
+ * Typed Story 02 operations over the shared foundation revision port.
+ *
+ * This class owns no storage.  It prevents callers from accidentally using a
+ * Variable as an Objective, while the generic store remains the one canonical
+ * Graph SSOT writer and authorization boundary.
+ */
+export class CompanyOsObjectives {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    createObjective(definition, context) {
+        assertType(definition, 'objective');
+        return this.store.create(definition, context);
+    }
+    readObjective(id, context, revision) {
+        return this.readTyped('objective', id, context, revision);
+    }
+    updateObjective(id, expectedRevision, next, context) {
+        assertType(next, 'objective');
+        return this.store.update({
+            reference: { id, type: 'objective', revision: expectedRevision },
+            next,
+            expectedRevision
+        }, context);
+    }
+    async checkObjectiveReadiness(id, context, revision) {
+        return checkObjectiveReadiness(this.store, id, context, revision);
+    }
+    createVariable(definition, context) {
+        assertType(definition, 'variable');
+        return this.store.create(definition, context);
+    }
+    readVariable(id, context, revision) {
+        return this.readTyped('variable', id, context, revision);
+    }
+    updateVariable(id, expectedRevision, next, context) {
+        assertType(next, 'variable');
+        return this.store.update({
+            reference: { id, type: 'variable', revision: expectedRevision },
+            next,
+            expectedRevision
+        }, context);
+    }
+    /** Exposes typed relation persistence without creating a second relation store. */
+    addRelation(relation, context) {
+        return this.store.addRelation(relation, context);
+    }
+    /**
+     * Stores one explicitly typed Story/Objective reference.  The relation kind
+     * is required by the caller and is never inferred from the Story text.
+     * Objective revisions are supplied explicitly so a later Objective update
+     * cannot silently rewrite the historical link.
+     */
+    linkObjectiveStory(input, context) {
+        if (!input || typeof input.storyId !== 'string' || input.storyId.length === 0) {
+            throw new TypeError('A Story id is required');
+        }
+        if (!input.objective || input.objective.type !== 'objective') {
+            throw new TypeError('A versioned Objective reference is required');
+        }
+        const relationByKind = {
+            contribution: 'contributes_to',
+            execution_dependency: 'execution_depends_on',
+            time_condition: 'time_condition'
+        };
+        return this.addRelation({
+            relation: relationByKind[input.linkKind],
+            source: {
+                id: input.storyId,
+                type: 'story',
+                ...(input.storyRevision === undefined ? {} : { revision: input.storyRevision })
+            },
+            target: input.objective,
+            ...(input.timeCondition === undefined ? {} : { timeCondition: input.timeCondition })
+        }, context);
+    }
+    readTyped(type, id, context, revision) {
+        if (revision !== undefined) {
+            return this.store.read({ id, type, revision }, context);
+        }
+        return this.store.readLatest(type, id, context);
+    }
+}
+/**
+ * Check an Objective and every Variable revision named by its criteria.
+ * Both the Objective service and judgment snapshot providers call this
+ * function so readiness cannot vary by caller.
+ */
+export async function checkObjectiveReadiness(reader, id, context, revision) {
+    const record = revision === undefined
+        ? reader.readLatest === undefined ? null : await reader.readLatest('objective', id, context)
+        : await reader.read({ id, type: 'objective', revision }, context);
+    if (!record) {
+        return {
+            ready: false,
+            issues: [{ code: 'NOT_FOUND', path: 'id', message: `Objective ${id} was not found.` }]
+        };
+    }
+    if (record.definition.type !== 'objective') {
+        return {
+            ready: false,
+            issues: [{ code: 'INVALID_OBJECTIVE_REFERENCE', path: 'type', message: `Foundation ${id} is not an Objective.` }]
+        };
+    }
+    const objective = record.definition;
+    const issues = validationIssues(objective, 'judgment');
+    const criteria = Array.isArray(objective.criteria) ? objective.criteria : [];
+    for (const [index, criterion] of criteria.entries()) {
+        if (!criterion || typeof criterion !== 'object' || !criterion.variableRef)
+            continue;
+        if (!isVariableRevisionReference(criterion.variableRef)) {
+            issues.push({
+                code: 'INVALID_VARIABLE_REFERENCE',
+                path: `criteria[${index}].variableRef`,
+                message: 'Criterion must reference a Variable with a positive revision.'
+            });
+            continue;
+        }
+        const variable = await reader.read(criterion.variableRef, context);
+        if (!variable) {
+            issues.push({
+                code: 'MISSING_VARIABLE_REVISION',
+                path: `criteria[${index}].variableRef`,
+                message: `Variable ${criterion.variableRef.id}@${criterion.variableRef.revision} was not found.`
+            });
+            continue;
+        }
+        if (variable.definition.type !== 'variable') {
+            issues.push({
+                code: 'INVALID_VARIABLE_REFERENCE',
+                path: `criteria[${index}].variableRef`,
+                message: `Criterion ${criterion.variableRef.id}@${criterion.variableRef.revision} is not a Variable.`
+            });
+            continue;
+        }
+        for (const issue of validationIssues(variable.definition, 'judgment')) {
+            issues.push({
+                ...issue,
+                path: `criteria[${index}].variableRef.${issue.path}`
+            });
+        }
+        issues.push(...criterionCompatibilityIssues(criterion, variable.definition, index));
+        issues.push(...criterionPeriodIssues(objective, variable.definition, index));
+    }
+    return { ready: issues.length === 0, issues };
+}
+export function createCompanyOsObjectives(store) {
+    return new CompanyOsObjectives(store);
+}
+function assertType(definition, type) {
+    if (!definition || definition.type !== type) {
+        throw new TypeError(`Expected a ${type} definition`);
+    }
+}
+function validationIssues(definition, use) {
+    try {
+        const result = validateFoundationDefinition(definition, { use });
+        return result.issues.map((issue) => ({
+            code: issue.code,
+            path: issue.path,
+            message: issue.message
+        }));
+    }
+    catch (error) {
+        return [{
+                code: 'INVALID_FIELD',
+                path: 'definition',
+                message: error instanceof Error ? error.message : String(error)
+            }];
+    }
+}
+function isVariableRevisionReference(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return candidate.type === 'variable'
+        && typeof candidate.id === 'string'
+        && candidate.id.length > 0
+        && typeof candidate.revision === 'string'
+        && /^[1-9]\d*$/.test(candidate.revision);
+}
+function criterionCompatibilityIssues(criterion, variable, index) {
+    const path = `criteria[${index}]`;
+    if (criterion.target === undefined)
+        return [];
+    if (criterion.operator === 'at_least' || criterion.operator === 'at_most') {
+        if (variable.valueKind !== 'number' || typeof criterion.target !== 'number' || !Number.isFinite(criterion.target)) {
+            return [{
+                    code: 'CRITERION_TYPE_MISMATCH',
+                    path,
+                    message: `${criterion.operator} requires a numeric Variable and a finite number target.`
+                }];
+        }
+        return [];
+    }
+    if (criterion.operator !== 'equals')
+        return [];
+    const targetMatches = variable.valueKind === 'number'
+        ? typeof criterion.target === 'number' && Number.isFinite(criterion.target)
+        : variable.valueKind === 'boolean'
+            ? typeof criterion.target === 'boolean'
+            : (variable.valueKind === 'string' || variable.valueKind === 'state') && typeof criterion.target === 'string';
+    if (!targetMatches) {
+        return [{
+                code: 'CRITERION_TYPE_MISMATCH',
+                path,
+                message: `equals target type does not match Variable valueKind ${variable.valueKind}.`
+            }];
+    }
+    return [];
+}
+function criterionPeriodIssues(objective, variable, index) {
+    const objectiveFrom = Date.parse(objective.evaluationPeriod?.from ?? '');
+    const objectiveUntil = Date.parse(objective.evaluationPeriod?.until ?? '');
+    const variableFrom = Date.parse(variable.scope?.validFrom ?? '');
+    const variableUntil = variable.scope?.validUntil === undefined
+        ? Number.POSITIVE_INFINITY
+        : Date.parse(variable.scope.validUntil);
+    if (!Number.isFinite(objectiveFrom) || !Number.isFinite(objectiveUntil)
+        || !Number.isFinite(variableFrom)
+        || (variable.scope?.validUntil !== undefined && !Number.isFinite(variableUntil))) {
+        return [];
+    }
+    if (variableFrom <= objectiveFrom && variableUntil >= objectiveUntil)
+        return [];
+    return [{
+            code: 'CRITERION_PERIOD_MISMATCH',
+            path: `criteria[${index}].variableRef`,
+            message: `Variable ${variable.id}@${variable.revision} does not cover the Objective evaluation period.`
+        }];
+}

package/dist/company-os-receipt-adapter.d.ts

@@ -0,0 +1,109 @@
+import type { FoundationScope } from './ontology-foundation.js';
+import type { OutcomeCasePort } from './company-os-evaluation.js';
+export declare const COMPANY_OS_RECEIPT_ADAPTER_CONTRACT_VERSION: "0.1.1";
+export declare const COMPANY_OS_RECEIPT_LINK_CATALOG_VERSION: 2;
+export declare const COMPANY_OS_RECEIPT_LINK_SIDECAR: "evidence/company-os-receipt-links.json";
+export type ReceiptSourceKind = 'run_receipt' | 'outcome_case' | 'meeting_context_receipt' | 'decision_event';
+export type ReceiptUnknownOwnerReason = 'not_recorded' | 'legacy_untyped' | 'source_unavailable';
+export interface ReceiptEntityReference {
+    readonly id: string;
+    readonly type: string;
+    readonly revision?: string;
+    readonly digest?: string;
+}
+export interface ReceiptTypedOwnerReference {
+    readonly status: 'typed';
+    readonly ref: ReceiptEntityReference;
+}
+export interface ReceiptUnknownOwnerReference {
+    readonly status: 'unknown';
+    readonly reason: ReceiptUnknownOwnerReason;
+}
+export type ReceiptOwnerReference = ReceiptTypedOwnerReference | ReceiptUnknownOwnerReference;
+export type ReceiptSourceConditionValue = string | number | boolean | null | readonly ReceiptSourceConditionValue[] | {
+    readonly [key: string]: ReceiptSourceConditionValue;
+};
+export type ReceiptSourceConditions = Readonly<Record<string, ReceiptSourceConditionValue>>;
+/**
+ * The source's original identity and state.  `hash: null` means the source
+ * did not record a hash; the adapter never computes one as a replacement.
+ */
+export interface ReceiptSourceReference {
+    readonly kind: ReceiptSourceKind;
+    readonly id: string;
+    readonly revision?: string;
+    readonly hash: string | null;
+    readonly state: string;
+    readonly owner_refs: readonly ReceiptOwnerReference[];
+    /** Optional source-owned conditions that are part of the stable identity. */
+    readonly conditions?: ReceiptSourceConditions;
+}
+export type ReceiptJudgmentReferenceKind = 'problem' | 'objective' | 'model' | 'constraint' | 'dag' | 'decision' | 'evaluation' | 'evidence';
+export interface ReceiptJudgmentReference {
+    readonly kind: ReceiptJudgmentReferenceKind;
+    readonly id: string;
+    readonly revision?: string;
+    readonly digest?: string;
+}
+export interface ReceiptAccessContext {
+    /** Identity resolved by a trusted caller boundary. */
+    readonly principal: string;
+    readonly scope?: FoundationScope;
+}
+/** A source-owner read port. It must enforce its current ACL before returning. */
+export interface ReceiptSourcePort {
+    read(reference: ReceiptSourceReference, access: ReceiptAccessContext): Promise<ReceiptSourceProjection | null>;
+}
+export interface ReceiptSourceProjection {
+    /** Current source identity/state; the stored link remains immutable. */
+    readonly reference: ReceiptSourceReference;
+}
+export interface ReceiptLinkRequest {
+    readonly id: string;
+    readonly source: ReceiptSourceReference;
+    readonly judgment_refs: readonly ReceiptJudgmentReference[];
+    readonly recorded_at: string;
+    readonly access: ReceiptAccessContext;
+}
+export interface ReceiptLinkRecord {
+    readonly version: typeof COMPANY_OS_RECEIPT_LINK_CATALOG_VERSION;
+    readonly id: string;
+    /** The source reference captured at link time, not a mutable source copy. */
+    readonly source: ReceiptSourceReference;
+    /** Digest of the immutable source snapshot; source.hash remains source-owned metadata. */
+    readonly source_digest: string;
+    readonly judgment_refs: readonly ReceiptJudgmentReference[];
+    readonly recorded_at: string;
+    /** These statuses are intentionally not derived from source execution state. */
+    readonly objective_status: 'unrecorded';
+    readonly judgment_quality_status: 'unrecorded';
+}
+export interface ReceiptSourceRead {
+    readonly reference: ReceiptSourceReference;
+    readonly state_changed: boolean;
+}
+export interface ReceiptProjection {
+    readonly link: ReceiptLinkRecord;
+    readonly source_read: ReceiptSourceRead;
+}
+export interface ReceiptAdapterPort {
+    link(request: ReceiptLinkRequest): Promise<ReceiptProjection>;
+    read(id: string, access: ReceiptAccessContext): Promise<ReceiptProjection | null>;
+    list(access: ReceiptAccessContext): Promise<readonly ReceiptProjection[]>;
+}
+export interface CompanyOsReceiptAdapterOptions {
+    readonly dataDir: string;
+    readonly sourcePorts: Partial<Record<ReceiptSourceKind, ReceiptSourcePort>>;
+}
+export type ReceiptAdapterErrorCode = 'invalid_input' | 'not_found' | 'authorization_denied' | 'source_unavailable' | 'source_not_found' | 'integrity_mismatch' | 'revision_conflict' | 'corrupt_record' | 'readback_mismatch';
+export declare class CompanyOsReceiptAdapterError extends Error {
+    readonly code: ReceiptAdapterErrorCode;
+    constructor(code: ReceiptAdapterErrorCode, message: string);
+}
+export declare function createCompanyOsReceiptAdapter(options: CompanyOsReceiptAdapterOptions): ReceiptAdapterPort;
+/**
+ * Reuses the existing read-only OutcomeCasePort without importing any
+ * organization runtime. OutcomeCase closure and evaluation remain owned by
+ * that provider; this adapter only exposes a source projection.
+ */
+export declare function createOutcomeCaseReceiptSourcePort(port: OutcomeCasePort): ReceiptSourcePort;