@unson/brainbase-mcp 0.6.0 → 0.7.0

package/dist/company-os-impact-review.d.ts

@@ -0,0 +1,248 @@
+import type { DurableWaitStore } from './durable-waits.js';
+import type { FoundationAcl } from './ontology-foundation.js';
+/**
+ * Story 15 keeps impact review at the port boundary.  It reads adopted
+ * references and plans, records an idempotent notification, and asks a
+ * durable-wait/rejudgment adapter to continue.  It never owns a canonical
+ * Objective, Model, Constraint, run, reservation, or external effect.
+ */
+export declare const COMPANY_OS_IMPACT_REVIEW_VERSION: "company-os-impact-review.v1";
+export declare const COMPANY_OS_IMPACT_REVIEW_NOTIFICATION_SIDECAR: "impact-review/notifications.json";
+export type ImpactReviewReferenceKind = 'objective' | 'model' | 'constraint' | 'method' | 'dag';
+export type ImpactReviewChangeSource = 'world_model' | 'objective' | 'constraint' | 'judgment_method';
+export type ImpactReviewChangeSignificance = 'minor' | 'material' | 'premise_refuted' | 'unknown';
+export type ImpactReviewRelationDomain = 'world_model' | 'execution';
+export type ImpactReviewRelationKind = 'uses_as_input' | 'predicts' | 'adopted' | 'applies_to' | 'execution_depends_on' | 'selected_method';
+export interface ImpactReviewScope {
+    readonly type: 'personal' | 'project' | 'organization';
+    readonly id: string;
+}
+export interface ImpactReviewAccessContext {
+    readonly principal: string;
+    readonly scope?: ImpactReviewScope;
+}
+export interface ImpactReviewReference {
+    readonly kind: ImpactReviewReferenceKind;
+    readonly id: string;
+    readonly revision: string;
+    readonly digest: string;
+    readonly scope: ImpactReviewScope;
+}
+export interface ImpactReviewChange {
+    readonly change_id: string;
+    readonly source: ImpactReviewChangeSource;
+    readonly previous?: ImpactReviewReference;
+    readonly current: ImpactReviewReference;
+    readonly significance: ImpactReviewChangeSignificance;
+    readonly reason: string;
+}
+export interface ImpactReviewProblemReference {
+    readonly snapshot_id: string;
+    readonly problem_id: string;
+    readonly revision: string;
+}
+export interface ImpactReviewResponsible {
+    readonly principal: string;
+    readonly scope?: string;
+}
+export interface ImpactReviewPlan {
+    readonly plan_id: string;
+    readonly owner_scope: ImpactReviewScope;
+    readonly read_policy: FoundationAcl;
+    readonly problem_snapshot: ImpactReviewProblemReference;
+    readonly run_id: string;
+    readonly references?: readonly ImpactReviewReference[];
+    readonly execution_state: 'planned' | 'running' | 'completed' | 'effect_unknown';
+    readonly authority_state: 'valid' | 'expired' | 'revoked' | 'unknown';
+    readonly constraint_state: 'valid' | 'violated' | 'expired' | 'unknown';
+    readonly responsible: ImpactReviewResponsible;
+    readonly due_at?: string;
+}
+export interface ImpactReviewPlanMatch {
+    readonly change_id: string;
+    readonly relation: ImpactReviewRelationKind;
+    readonly domain: ImpactReviewRelationDomain;
+    readonly evidence: string;
+}
+export interface ImpactReviewAffectedPlan {
+    readonly plan: ImpactReviewPlan;
+    readonly matches: readonly ImpactReviewPlanMatch[];
+}
+/** Read-only current-reference lookup. A null result is unresolved, not no impact. */
+export interface ImpactReviewCurrentReferencePort {
+    readCurrent(reference: ImpactReviewReference, access: ImpactReviewAccessContext): Promise<ImpactReviewReference | null>;
+}
+/** Read-only reverse lookup. It must not change a plan, run, reservation, or effect. */
+export interface ImpactReviewIndexPort {
+    findAffectedPlans(input: {
+        readonly changes: readonly ImpactReviewChange[];
+        readonly current_references: readonly ImpactReviewReference[];
+        readonly access: ImpactReviewAccessContext;
+    }): Promise<readonly ImpactReviewAffectedPlan[]>;
+}
+export interface ImpactReviewDurableWaitCreateInput {
+    readonly wait_id: string;
+    readonly principal: string;
+    readonly owner_scope: ImpactReviewScope;
+    readonly read_policy: FoundationAcl;
+    readonly problem_snapshot: ImpactReviewProblemReference;
+    readonly condition: {
+        readonly event?: {
+            readonly event_type: string;
+            readonly event_id?: string;
+        };
+        readonly expression?: string;
+    };
+    readonly deadline?: {
+        readonly due_at?: string;
+        readonly review_interval_ms?: number;
+    };
+    readonly responsible: ImpactReviewResponsible;
+    readonly resume_method: 'new_problem' | 'reconcile_external_effect' | 'manual_review';
+    readonly failure_policy: 'new_problem' | 'reconciliation_wait' | 'handoff' | 'fail';
+    readonly run_ref: {
+        readonly run_id: string;
+    };
+}
+/** Structural compatibility with Story 13; this package does not import it before it is merged. */
+export interface ImpactReviewWaitPort {
+    /** The adapter must treat wait_id as an idempotency key. */
+    create(input: ImpactReviewDurableWaitCreateInput): Promise<unknown>;
+    /** Read the canonical wait with current ACL and snapshot checks. */
+    readonly read?: (input: {
+        readonly wait_id: string;
+        readonly principal: string;
+    }) => Promise<unknown>;
+    markPremiseChanged(input: {
+        readonly wait_id: string;
+        readonly principal: string;
+        readonly new_problem_snapshot: ImpactReviewProblemReference;
+        readonly responsible?: ImpactReviewResponsible;
+        readonly reason: string;
+    }): Promise<unknown>;
+}
+/**
+ * Adapt Story 13's canonical durable-wait ledger to the impact-review port.
+ * The coordinator remains independent from the ledger implementation; this
+ * boundary only forwards the wait operations it is allowed to request.
+ */
+export declare function createCompanyOsImpactReviewDurableWaitPort(store: Pick<DurableWaitStore, 'create' | 'get' | 'markPremiseChanged'>): ImpactReviewWaitPort;
+export interface ImpactReviewNewProblemAndRun {
+    readonly problem: ImpactReviewProblemReference;
+    readonly run_id: string;
+}
+export interface ImpactReviewRejudgmentPort {
+    createNewProblemAndRun(input: {
+        readonly access: ImpactReviewAccessContext;
+        readonly plan: ImpactReviewPlan;
+        readonly changes: readonly ImpactReviewChange[];
+        readonly reason: string;
+        /** Stable across retries so the provider can make Problem/run creation idempotent. */
+        readonly operation_id: string;
+    }): Promise<ImpactReviewNewProblemAndRun>;
+}
+export type ImpactReviewDisposition = 'continue' | 'hold' | 'stop';
+export interface ImpactReviewNotificationInput {
+    readonly plan_id: string;
+    readonly disposition: ImpactReviewDisposition;
+    readonly change_ids: readonly string[];
+    readonly reason: string;
+    readonly references: readonly ImpactReviewReference[];
+    readonly wait_id?: string;
+    readonly created_at?: string;
+}
+export interface ImpactReviewNotificationRecord extends Omit<ImpactReviewNotificationInput, 'created_at'> {
+    readonly version: typeof COMPANY_OS_IMPACT_REVIEW_VERSION;
+    readonly notification_id: string;
+    readonly created_at: string;
+}
+export interface ImpactReviewNotificationReceipt {
+    readonly record: ImpactReviewNotificationRecord;
+    readonly status: 'created' | 'existing';
+}
+export interface ImpactReviewNotificationStore {
+    record(input: ImpactReviewNotificationInput): Promise<ImpactReviewNotificationReceipt>;
+    read(): Promise<readonly ImpactReviewNotificationRecord[]>;
+    list(): Promise<readonly ImpactReviewNotificationRecord[]>;
+}
+export declare class CompanyOsImpactReviewError extends Error {
+    readonly code: 'invalid_request' | 'invalid_provider_result' | 'unresolved_reference' | 'notification_conflict' | 'wait_conflict' | 'corrupt_sidecar' | 'missing_dependency' | 'rejudgment_not_allowed';
+    constructor(code: CompanyOsImpactReviewError['code'], message: string);
+}
+export interface CompanyOsImpactReviewNotificationStoreOptions {
+    readonly dataDir: string;
+    readonly sidecarPath?: string;
+    readonly clock?: () => Date;
+}
+/**
+ * Transactional, reference-only notification storage. The sidecar never
+ * stores an Objective/Model/Constraint body and never changes canonical SSOT.
+ */
+export declare class AtomicCompanyOsImpactReviewNotificationStore implements ImpactReviewNotificationStore {
+    private readonly dataDir;
+    private readonly sidecarPath;
+    private readonly clock;
+    constructor(options: CompanyOsImpactReviewNotificationStoreOptions);
+    record(input: ImpactReviewNotificationInput): Promise<ImpactReviewNotificationReceipt>;
+    read(): Promise<readonly ImpactReviewNotificationRecord[]>;
+    list(): Promise<readonly ImpactReviewNotificationRecord[]>;
+}
+export declare function createCompanyOsImpactReviewNotificationStore(options: CompanyOsImpactReviewNotificationStoreOptions): ImpactReviewNotificationStore;
+export interface ImpactReviewPlanDecision {
+    readonly plan: ImpactReviewPlan;
+    readonly matches: readonly ImpactReviewPlanMatch[];
+    readonly disposition: ImpactReviewDisposition;
+    readonly reason: string;
+    readonly notification: ImpactReviewNotificationRecord;
+    readonly wait_id?: string;
+}
+export interface ImpactReviewUnresolvedChange {
+    readonly change: ImpactReviewChange;
+    readonly reason: string;
+}
+export interface ImpactReviewResult {
+    readonly outcome: 'affected' | 'no_affected_plans' | 'unresolved' | 'affected_and_unresolved';
+    readonly decisions: readonly ImpactReviewPlanDecision[];
+    readonly resolved_change_ids: readonly string[];
+    readonly unresolved_changes: readonly ImpactReviewUnresolvedChange[];
+}
+export interface ImpactReviewRequest {
+    readonly access: ImpactReviewAccessContext;
+    readonly changes: readonly ImpactReviewChange[];
+}
+export interface ImpactReviewReassessRequest {
+    readonly access: ImpactReviewAccessContext;
+    readonly plan: ImpactReviewPlan;
+    readonly changes: readonly ImpactReviewChange[];
+    readonly reason: string;
+    readonly wait_id?: string;
+}
+export interface ImpactReviewReassessResult extends ImpactReviewNewProblemAndRun {
+    readonly wait_id?: string;
+}
+export interface CompanyOsImpactReviewCoordinatorOptions {
+    readonly currentReferences: ImpactReviewCurrentReferencePort;
+    readonly index: ImpactReviewIndexPort;
+    readonly notifications: ImpactReviewNotificationStore;
+    readonly waits?: ImpactReviewWaitPort;
+    readonly rejudgment?: ImpactReviewRejudgmentPort;
+}
+export declare class CompanyOsImpactReviewCoordinator {
+    private readonly currentReferences;
+    private readonly index;
+    private readonly notifications;
+    private readonly waits?;
+    private readonly rejudgment?;
+    constructor(options: CompanyOsImpactReviewCoordinatorOptions);
+    review(request: ImpactReviewRequest): Promise<ImpactReviewResult>;
+    reassess(request: ImpactReviewReassessRequest): Promise<ImpactReviewReassessResult>;
+}
+export declare function computeImpactReviewNotificationId(input: ImpactReviewNotificationInput): string;
+export declare function computeImpactReviewWaitId(planId: string, changeIds: readonly string[], reason: string, references?: readonly ImpactReviewReference[]): string;
+export declare function computeImpactReviewRejudgmentOperationId(input: {
+    readonly access: ImpactReviewAccessContext;
+    readonly plan: ImpactReviewPlan;
+    readonly changes: readonly ImpactReviewChange[];
+    readonly reason: string;
+    readonly wait_id?: string;
+}): string;