@unson/brainbase-mcp 0.5.0 → 0.7.0

package/dist/constraint-exception-store.js

@@ -0,0 +1,108 @@
+import { ConstraintError, validateConstraintExceptionRecord, } from './constraint-resolution.js';
+import { mutatePersonalOsWithSidecar, readPersonalOsSidecar } from './ssot.js';
+/** The shared SSOT evidence area used for rich exception metadata. */
+export const CONSTRAINT_EXCEPTION_EVIDENCE_PATH = 'evidence/constraint-exceptions.jsonl';
+/**
+ * Durable exception evidence stored through the common SSOT transaction
+ * writer.  Constraint definitions remain in GraphFoundationRevisionStore;
+ * this evidence adapter only supplies the approval metadata missing from the
+ * shared ontology reference.  Authorization is intentionally performed by
+ * ConstraintService's injected provider before this storage port is called.
+ */
+export class AtomicConstraintExceptionStore {
+    dataDir;
+    evidencePath;
+    constructor(options) {
+        if (!options.dataDir) {
+            throw new ConstraintError('constraint_store_unavailable', 'exception evidence dataDir is required', 503);
+        }
+        this.dataDir = options.dataDir;
+        this.evidencePath = options.evidencePath ?? CONSTRAINT_EXCEPTION_EVIDENCE_PATH;
+    }
+    async append(exception, _context) {
+        validateConstraintExceptionRecord(exception);
+        try {
+            const stored = await mutatePersonalOsWithSidecar(this.dataDir, this.evidencePath, async (current, existingContent) => {
+                const records = parseEvidence(existingContent ?? '');
+                if (records.some((record) => record.id === exception.id)) {
+                    throw new ConstraintError('revision_conflict', 'exception id already exists', 409, { id: exception.id });
+                }
+                const next = [...records, clone(exception)].sort((left, right) => left.id.localeCompare(right.id, 'en'));
+                return {
+                    next: current,
+                    sidecarContent: serializeEvidence(next),
+                    result: clone(exception),
+                };
+            });
+            return stored;
+        }
+        catch (error) {
+            if (error instanceof ConstraintError)
+                throw error;
+            throw new ConstraintError('constraint_store_unavailable', 'exception evidence could not be persisted', 503, {
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async list(query, _context) {
+        let content;
+        try {
+            content = await readPersonalOsSidecar(this.dataDir, this.evidencePath);
+        }
+        catch (error) {
+            if (error instanceof ConstraintError)
+                throw error;
+            throw new ConstraintError('constraint_store_unavailable', 'exception evidence could not be read', 503, {
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (content === undefined)
+            return [];
+        return parseEvidence(content)
+            .filter((record) => query.constraintId === undefined || record.constraintRef.id === query.constraintId)
+            .filter((record) => query.constraintRevision === undefined || record.constraintRef.revision === query.constraintRevision)
+            .map(clone);
+    }
+}
+export function createAtomicConstraintExceptionStore(options) {
+    return new AtomicConstraintExceptionStore(options);
+}
+function parseEvidence(content) {
+    const records = [];
+    for (const [index, line] of content.split(/\r?\n/u).map((value) => value.trim()).filter(Boolean).entries()) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            throw new ConstraintError('constraint_store_corrupt', `exception evidence line ${index + 1} is not valid JSON`, 500, {
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        try {
+            validateConstraintExceptionRecord(parsed);
+        }
+        catch (error) {
+            if (error instanceof ConstraintError)
+                throw error;
+            throw new ConstraintError('constraint_store_corrupt', `exception evidence line ${index + 1} is invalid`, 500, {
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        records.push(clone(parsed));
+    }
+    const ids = new Set();
+    for (const record of records) {
+        if (ids.has(record.id)) {
+            throw new ConstraintError('constraint_store_corrupt', 'exception evidence contains duplicate ids', 500, { id: record.id });
+        }
+        ids.add(record.id);
+    }
+    return records;
+}
+function serializeEvidence(records) {
+    return records.length === 0 ? '' : `${records.map((record) => JSON.stringify(record)).join('\n')}\n`;
+}
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/constraint-resolution.d.ts

@@ -0,0 +1,175 @@
+import type { ConstraintDefinition, ConstraintException, DecisionRevision, FoundationAcl, FoundationAdoptionState, FoundationEpistemicState, FoundationProvenance, FoundationScope, FoundationStorage, FoundationUse } from './ontology-foundation.js';
+export type ConstraintUse = FoundationUse;
+export type ConstraintEpistemicState = FoundationEpistemicState;
+export type ConstraintAdoptionState = FoundationAdoptionState;
+export type ConstraintStorage = FoundationStorage;
+export type ConstraintVisibility = FoundationAcl['visibility'];
+export type ConstraintProvenanceKind = FoundationProvenance['sourceKind'];
+export type ConstraintScope = FoundationScope;
+export type ConstraintAcl = FoundationAcl;
+export type ConstraintProvenance = FoundationProvenance;
+export type ConstraintDecisionReference = DecisionRevision;
+export type ConstraintExceptionReference = ConstraintException;
+export type ConstraintProjection = ConstraintDefinition;
+export interface ConstraintRef {
+    readonly id: string;
+    readonly revision: string;
+}
+/** A durable exception record kept by the canonical store adapter. */
+export interface ConstraintExceptionRecord {
+    readonly id: string;
+    readonly constraintRef: ConstraintRef;
+    readonly decisionRef: ConstraintDecisionReference;
+    readonly approverId: string;
+    readonly scope: ConstraintScope;
+    readonly expiresAt: string;
+    readonly rationale: string;
+}
+export interface ConstraintStoreQuery {
+    readonly ownerId?: string;
+    readonly id?: string;
+    readonly revision?: string;
+}
+export interface ConstraintExceptionQuery {
+    readonly constraintId?: string;
+    readonly constraintRevision?: string;
+}
+export interface ConstraintStore<TConstraint extends ConstraintProjection = ConstraintProjection> {
+    /**
+     * Append one immutable revision.  `null` means that the id must not exist;
+     * a string is an atomic compare-and-swap against the current revision.
+     */
+    append(input: {
+        record: TConstraint;
+        expectedPreviousRevision?: string | null;
+    }, context?: ConstraintAuthorizationContext): Promise<TConstraint>;
+    get(ref: {
+        id: string;
+        revision: string;
+    }, context?: ConstraintAuthorizationContext): Promise<TConstraint | null>;
+    getLatest(id: string, context?: ConstraintAuthorizationContext): Promise<TConstraint | null>;
+    list(query: ConstraintStoreQuery, context?: ConstraintAuthorizationContext): Promise<readonly TConstraint[]>;
+    appendException(exception: ConstraintExceptionRecord, context?: ConstraintAuthorizationContext): Promise<ConstraintExceptionRecord>;
+    listExceptions(query: ConstraintExceptionQuery, context?: ConstraintAuthorizationContext): Promise<readonly ConstraintExceptionRecord[]>;
+}
+export type ConstraintAction = 'create' | 'update' | 'read' | 'resolve' | 'adopt' | 'exception';
+export interface ConstraintAuthorizationContext {
+    readonly actorId: string;
+    readonly ownerId: string;
+    readonly [key: string]: unknown;
+}
+export interface ConstraintAuthorizationRequest {
+    readonly action: ConstraintAction;
+    readonly context: ConstraintAuthorizationContext;
+    readonly ownerId?: string;
+    readonly constraint?: ConstraintProjection | null;
+    readonly input?: unknown;
+}
+export interface ConstraintAuthorizationPort {
+    authorize(request: ConstraintAuthorizationRequest): void | Promise<void>;
+}
+export interface DecisionRevisionReader {
+    exists(reference: ConstraintDecisionReference, context: ConstraintAuthorizationContext): Promise<boolean>;
+}
+export type ConstraintEvaluationResult = {
+    readonly status: 'resolved';
+    readonly applies: boolean;
+    readonly reason?: string;
+} | {
+    readonly status: 'unknown';
+    readonly reason: string;
+} | {
+    readonly status: 'conflict';
+    readonly reason: string;
+    readonly conflictingRefs?: readonly ConstraintRef[];
+};
+export interface ConstraintResolutionQuery {
+    readonly ownerId: string;
+    readonly subjectId?: string;
+    readonly targetId?: string;
+    readonly asOf: string;
+    readonly use?: ConstraintUse;
+}
+export interface ConstraintEvaluationInput<TConstraint extends ConstraintProjection = ConstraintProjection> {
+    readonly constraint: TConstraint;
+    readonly candidates: readonly TConstraint[];
+    readonly query: ConstraintResolutionQuery;
+    readonly activeExceptions: readonly ConstraintExceptionRecord[];
+}
+export interface ConstraintEvaluationProvider<TConstraint extends ConstraintProjection = ConstraintProjection> {
+    evaluate(input: ConstraintEvaluationInput<TConstraint>): Promise<ConstraintEvaluationResult> | ConstraintEvaluationResult;
+}
+export interface ConstraintResolutionIssue {
+    readonly code: 'scope_violation' | 'constraint_store_unavailable' | 'scope_unknown' | 'target_scope_unknown' | 'decision_reference_missing' | 'decision_reference_unresolved' | 'retired_constraint' | 'unauthorized_use' | 'exception_invalid' | 'exception_store_unavailable' | 'evaluation_unknown' | 'constraint_conflict' | 'evaluation_invalid' | 'evaluation_unavailable';
+    readonly message: string;
+    readonly constraintRef?: ConstraintRef;
+    readonly conflictingRefs?: readonly ConstraintRef[];
+}
+export interface ConstraintResolution<TConstraint extends ConstraintProjection = ConstraintProjection> {
+    readonly status: 'resolved' | 'unresolved';
+    readonly constraints: readonly TConstraint[];
+    readonly unresolvedReasons: readonly ConstraintResolutionIssue[];
+    /** Resolution never grants permission to perform an external action. */
+    readonly executionAuthority: 'not_granted';
+}
+export interface ConstraintRevisionSequence {
+    next(currentRevision: string): string;
+    compare(left: string, right: string): number;
+}
+export interface ConstraintServiceOptions<TConstraint extends ConstraintProjection = ConstraintProjection> {
+    readonly store: ConstraintStore<TConstraint>;
+    readonly authorization: ConstraintAuthorizationPort;
+    readonly decisionReader: DecisionRevisionReader;
+    readonly evaluator: ConstraintEvaluationProvider<TConstraint>;
+    readonly revisionSequence?: ConstraintRevisionSequence;
+}
+export type ConstraintPatch<TConstraint extends ConstraintProjection = ConstraintProjection> = Partial<Omit<TConstraint, 'id' | 'type' | 'revision'>>;
+export declare class ConstraintError extends Error {
+    readonly code: ConstraintErrorCode;
+    readonly status: number;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: ConstraintErrorCode, message: string, status?: number, details?: Readonly<Record<string, unknown>>);
+}
+export type ConstraintErrorCode = 'invalid_constraint' | 'invalid_scope' | 'invalid_revision' | 'revision_conflict' | 'constraint_not_found' | 'decision_reference_unresolved' | 'authorization_denied' | 'scope_violation' | 'exception_invalid' | 'exception_not_found' | 'constraint_store_unavailable' | 'constraint_store_corrupt' | 'unsupported_revision_sequence';
+export declare const numericConstraintRevisionSequence: ConstraintRevisionSequence;
+export interface InMemoryConstraintStoreOptions {
+    readonly compareRevisions?: (left: string, right: string) => number;
+}
+/** In-memory adapter used by contract tests; production uses the injected canonical store. */
+export declare class InMemoryConstraintStore<TConstraint extends ConstraintProjection = ConstraintProjection> implements ConstraintStore<TConstraint> {
+    private readonly records;
+    private readonly exceptions;
+    private readonly compareRevisions;
+    constructor(options?: InMemoryConstraintStoreOptions);
+    append(input: {
+        record: TConstraint;
+        expectedPreviousRevision?: string | null;
+    }): Promise<TConstraint>;
+    get(ref: {
+        id: string;
+        revision: string;
+    }): Promise<TConstraint | null>;
+    getLatest(id: string): Promise<TConstraint | null>;
+    list(query: ConstraintStoreQuery): Promise<readonly TConstraint[]>;
+    appendException(exception: ConstraintExceptionRecord): Promise<ConstraintExceptionRecord>;
+    listExceptions(query: ConstraintExceptionQuery): Promise<readonly ConstraintExceptionRecord[]>;
+}
+/** Validate a durable exception before a persistence adapter writes it. */
+export declare function validateConstraintExceptionRecord(exception: ConstraintExceptionRecord): void;
+export declare function createSingleOwnerConstraintAuthorization(): ConstraintAuthorizationPort;
+export declare class ConstraintService<TConstraint extends ConstraintProjection = ConstraintProjection> {
+    private readonly options;
+    private readonly revisionSequence;
+    constructor(options: ConstraintServiceOptions<TConstraint>);
+    createConstraint(record: TConstraint, context: ConstraintAuthorizationContext): Promise<TConstraint>;
+    getConstraint(ref: ConstraintRef, context: ConstraintAuthorizationContext): Promise<TConstraint | null>;
+    updateConstraint(id: string, expectedRevision: string, patch: ConstraintPatch<TConstraint>, context: ConstraintAuthorizationContext): Promise<TConstraint>;
+    adoptConstraint(id: string, expectedRevision: string, decisionRef: ConstraintDecisionReference, context: ConstraintAuthorizationContext): Promise<TConstraint>;
+    registerException(exception: ConstraintExceptionRecord, context: ConstraintAuthorizationContext): Promise<ConstraintExceptionRecord>;
+    resolveConstraints(query: ConstraintResolutionQuery, context: ConstraintAuthorizationContext): Promise<ConstraintResolution<TConstraint>>;
+    private requireLatest;
+    private assertOwner;
+    private authorize;
+    private authorizationIssue;
+    private appendAndReadback;
+}