@unson/brainbase-mcp 0.44.0 → 0.44.1

package/contracts/canonical-task/operation-schema.sql

@@ -0,0 +1,58 @@
+CREATE TABLE IF NOT EXISTS canonical_task_writer (
+    singleton_id BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton_id),
+    writer_token TEXT NOT NULL,
+    process_identity JSONB NOT NULL DEFAULT '{}'::jsonb,
+    source_head TEXT,
+    claimed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS canonical_task_readiness (
+    singleton_id BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton_id),
+    ready BOOLEAN NOT NULL DEFAULT FALSE,
+    writer_token TEXT,
+    manifest_hash TEXT,
+    schema_version TEXT,
+    source_head TEXT,
+    evidence_hash TEXT,
+    evidence_path TEXT,
+    reason TEXT,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS canonical_task_readiness_audit (
+    id BIGSERIAL PRIMARY KEY,
+    action TEXT NOT NULL CHECK (action IN ('enable', 'disable')),
+    ready BOOLEAN NOT NULL,
+    actor TEXT NOT NULL,
+    change_ref TEXT NOT NULL,
+    source_head TEXT,
+    evidence_hash TEXT,
+    evidence_path TEXT,
+    reason TEXT,
+    process_identity JSONB NOT NULL DEFAULT '{}'::jsonb,
+    session_context JSONB NOT NULL DEFAULT '{}'::jsonb,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS canonical_task_readiness_audit_created_at_idx
+    ON canonical_task_readiness_audit (created_at DESC);
+
+CREATE TABLE IF NOT EXISTS canonical_task_operations (
+    id BIGSERIAL PRIMARY KEY,
+    scope TEXT NOT NULL,
+    operation_key TEXT NOT NULL,
+    fingerprint TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('prepared', 'running', 'completed', 'failed')),
+    writer_token TEXT NOT NULL,
+    result_json JSONB,
+    error_json JSONB,
+    authorization_snapshot JSONB,
+    recovery_checkpoint JSONB NOT NULL DEFAULT '{}'::jsonb,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (scope, operation_key)
+);
+
+CREATE INDEX IF NOT EXISTS canonical_task_operations_state_idx
+    ON canonical_task_operations (state, updated_at);

package/contracts/canonical-task/search-indexes.sql

@@ -0,0 +1,10 @@
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS canonical_tasks_title_trgm_idx
+    ON canonical_tasks USING GIN (title gin_trgm_ops);
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS canonical_tasks_search_cursor_idx
+    ON canonical_tasks (created_at DESC, id DESC);
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS canonical_tasks_source_refs_idx
+    ON canonical_tasks USING GIN (source_refs jsonb_path_ops);

package/contracts/canonical-task/store-schema.sql

@@ -0,0 +1,77 @@
+CREATE TABLE IF NOT EXISTS canonical_tasks (
+    id UUID PRIMARY KEY,
+    legacy_nocodb_id TEXT UNIQUE,
+    title TEXT NOT NULL,
+    description TEXT,
+    status TEXT NOT NULL CHECK (status IN ('pending', 'in_progress', 'waiting', 'completed', 'cancelled')),
+    priority TEXT NOT NULL CHECK (priority IN ('low', 'medium', 'high', 'urgent')),
+    assignee_person_id TEXT,
+    assignee_display_name TEXT,
+    due_at TIMESTAMPTZ,
+    waiting_on TEXT,
+    review_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ,
+    source_refs JSONB NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(source_refs) = 'array'),
+    project_codes TEXT[] NOT NULL DEFAULT '{}'::text[],
+    purpose_label TEXT,
+    completion_contract JSONB,
+    version INTEGER NOT NULL DEFAULT 1 CHECK (version > 0),
+    idempotency_key TEXT NOT NULL UNIQUE,
+    payload_fingerprint TEXT,
+    last_operation_key TEXT,
+    last_operation_fingerprint TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+ALTER TABLE canonical_tasks
+    ADD COLUMN IF NOT EXISTS project_codes TEXT[] NOT NULL DEFAULT '{}'::text[];
+
+-- 何のための仕事か（例: 口コミ）。1 Taskに1つ、未分類はNULL。
+ALTER TABLE canonical_tasks
+    ADD COLUMN IF NOT EXISTS purpose_label TEXT;
+
+-- 確認待ちのTaskが待っている相手のGraph person ID。条件や特定の人でない待ちはNULL。
+-- 待っている相手・条件の自由記述（waiting_on）とは別に持つ。
+ALTER TABLE canonical_tasks
+    ADD COLUMN IF NOT EXISTS waiting_on_person_id TEXT;
+
+-- Structured Task goal and completion criteria. Validation of the contract's
+-- exact fields belongs to the public Task API; storage only requires an object.
+ALTER TABLE canonical_tasks
+    ADD COLUMN IF NOT EXISTS completion_contract JSONB;
+
+ALTER TABLE canonical_tasks
+    DROP CONSTRAINT IF EXISTS canonical_tasks_completion_contract_shape_check;
+ALTER TABLE canonical_tasks
+    ADD CONSTRAINT canonical_tasks_completion_contract_shape_check
+    CHECK (
+        completion_contract IS NULL
+        OR jsonb_typeof(completion_contract) = 'object'
+    );
+
+ALTER TABLE canonical_tasks
+    DROP CONSTRAINT IF EXISTS canonical_tasks_purpose_label_check;
+ALTER TABLE canonical_tasks
+    ADD CONSTRAINT canonical_tasks_purpose_label_check
+    CHECK (
+        purpose_label IS NULL
+        OR (
+            char_length(purpose_label) BETWEEN 1 AND 30
+            AND purpose_label = btrim(purpose_label)
+            AND purpose_label !~ '[[:cntrl:]]'
+        )
+    );
+
+ALTER TABLE canonical_tasks
+    DROP CONSTRAINT IF EXISTS canonical_tasks_status_check;
+ALTER TABLE canonical_tasks
+    ADD CONSTRAINT canonical_tasks_status_check
+    CHECK (status IN ('pending', 'in_progress', 'waiting', 'completed', 'cancelled'));
+
+CREATE INDEX IF NOT EXISTS canonical_tasks_status_priority_idx
+    ON canonical_tasks (status, priority);
+CREATE INDEX IF NOT EXISTS canonical_tasks_assignee_due_idx
+    ON canonical_tasks (assignee_person_id, due_at);
+CREATE INDEX IF NOT EXISTS canonical_tasks_project_codes_idx
+    ON canonical_tasks USING GIN (project_codes);

package/dist/automation-run.d.ts

@@ -0,0 +1,213 @@
+import { type NormalizedRunReceipt } from './run-receipt.js';
+import { type Awaitable, type RuntimeHostContext, type RuntimeHostPorts } from './runtime-host.js';
+export type AutomationRunOperation = 'automation.start' | 'automation.retry';
+export type AutomationRunPhase = 'claimed' | 'runner_started' | 'receipt_persisted' | 'completed' | 'retryable' | 'uncertain' | 'unknown';
+export interface AutomationRunRequest {
+    workflowId: string;
+    automationId?: string;
+    projectId?: string;
+    organizationId?: string;
+    orgId?: string;
+    actorId?: string;
+    sourceType?: string;
+    /** Stable source identity used for the durable claim. */
+    externalRunId: string;
+    payload?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface AutomationRunNamespace {
+    tenantId: string;
+    projectId: string;
+    organizationId: string;
+    actorId: string;
+}
+export interface AutomationRunIdentity {
+    operation: AutomationRunOperation;
+    key: string;
+    fingerprint: string;
+    runnerIdempotencyKey: string;
+    namespace: AutomationRunNamespace;
+}
+export interface AutomationRunnerStartInput {
+    request: AutomationRunRequest;
+    context: RuntimeHostContext;
+    /** External runner must use this key for its own idempotent execution. */
+    idempotencyKey: string;
+}
+export interface AutomationRunnerRetryInput extends AutomationRunnerStartInput {
+    previousRunId: string;
+}
+export interface AutomationRunnerResult {
+    /** Canonical run_receipt.v1 payload. */
+    receipt: unknown;
+    result?: unknown;
+}
+export interface AutomationRunnerPort {
+    start(input: AutomationRunnerStartInput): Awaitable<AutomationRunnerResult>;
+    retry?(input: AutomationRunnerRetryInput): Awaitable<AutomationRunnerResult>;
+}
+export interface AutomationReceiptPersistenceInput {
+    payload: unknown;
+    normalized: NormalizedRunReceipt;
+    context: RuntimeHostContext;
+}
+export interface AutomationReceiptPort {
+    persist(input: AutomationReceiptPersistenceInput): Awaitable<unknown>;
+    query(input: {
+        request: AutomationRunRequest;
+        context: RuntimeHostContext;
+    }): Awaitable<unknown>;
+}
+export type AutomationRunClaim = {
+    status: 'claimed';
+    claimToken: string;
+    attempt?: number;
+    phase: 'claimed';
+} | {
+    status: 'replay';
+    payload: unknown;
+    normalized?: NormalizedRunReceipt;
+    runnerResult?: unknown;
+    persistedReceipt?: unknown;
+    phase: 'completed';
+} | {
+    status: 'in_progress';
+    claimToken?: string;
+    attempt?: number;
+    phase: Exclude<AutomationRunPhase, 'completed' | 'retryable'>;
+} | {
+    status: 'conflict';
+    reason: 'identity_mismatch' | 'uncertain';
+    phase?: AutomationRunPhase;
+};
+export interface AutomationRunStoreClaimInput extends AutomationRunIdentity {
+    request: AutomationRunRequest;
+    context: RuntimeHostContext;
+}
+export interface AutomationRunStoreCompletionInput extends AutomationRunStoreClaimInput {
+    claimToken: string;
+    payload: unknown;
+    normalized: NormalizedRunReceipt;
+    runnerResult: unknown;
+    persistedReceipt: unknown;
+}
+export interface AutomationRunStoreRunnerStartedInput extends AutomationRunStoreClaimInput {
+    claimToken: string;
+}
+export interface AutomationRunStoreReceiptPersistedInput extends AutomationRunStoreClaimInput {
+    claimToken: string;
+    payload: unknown;
+    normalized: NormalizedRunReceipt;
+    runnerResult: unknown;
+    persistedReceipt: unknown;
+}
+export interface AutomationRunStoreReleaseInput extends AutomationRunStoreClaimInput {
+    claimToken: string;
+    /** retryable is safe only before runner invocation; uncertain is fail-closed. */
+    outcome: 'retryable' | 'uncertain';
+    phase: AutomationRunPhase;
+    error: unknown;
+}
+export interface AutomationRunStoreReadInput extends AutomationRunStoreClaimInput {
+}
+export type AutomationRunStoredState = {
+    status: 'completed';
+    phase: 'completed';
+    payload: unknown;
+    normalized?: NormalizedRunReceipt;
+    runnerResult?: unknown;
+    persistedReceipt?: unknown;
+} | {
+    status: 'in_progress' | 'retryable' | 'uncertain' | 'missing';
+    phase: Exclude<AutomationRunPhase, 'completed'>;
+    attempt?: number;
+    error?: unknown;
+};
+/**
+ * Durable consumer-owned store for the external run identity. The claim and
+ * every phase transition must be atomic in the backing store; a process-local
+ * mutex is insufficient. The store compares key, namespace, operation, and
+ * fingerprint before accepting a claim, and must never turn uncertain into a
+ * retryable record automatically.
+ */
+export interface AutomationRunStorePort {
+    claim(input: AutomationRunStoreClaimInput): Awaitable<AutomationRunClaim>;
+    markRunnerStarted(input: AutomationRunStoreRunnerStartedInput): Awaitable<unknown>;
+    markReceiptPersisted(input: AutomationRunStoreReceiptPersistedInput): Awaitable<unknown>;
+    complete(input: AutomationRunStoreCompletionInput): Awaitable<unknown>;
+    release(input: AutomationRunStoreReleaseInput): Awaitable<unknown>;
+    read(input: AutomationRunStoreReadInput): Awaitable<AutomationRunStoredState>;
+}
+/**
+ * Host-owned workflow composition around the portable run state machine.
+ *
+ * The consumer keeps workflow lookup, authorization/design policy, HITL and
+ * database persistence in its own repository. The OSS core only invokes the
+ * supplied ports in a deterministic order around the durable run phases.
+ */
+export type AutomationWorkflowGateDecision = true | false | {
+    allowed: boolean;
+    context?: unknown;
+    reason?: string;
+};
+export type AutomationWorkflowLifecyclePhase = 'prepared' | 'claimed' | 'runner_started' | 'receipt_persisted' | 'completed';
+export interface AutomationWorkflowLifecycleInput {
+    request: AutomationRunRequest;
+    context: RuntimeHostContext;
+    identity: AutomationRunIdentity;
+    phase: AutomationWorkflowLifecyclePhase;
+    workflow?: unknown;
+    claimToken?: string;
+    previousRunId?: string;
+}
+export interface AutomationWorkflowTransitionInput extends AutomationWorkflowLifecycleInput {
+    from: AutomationWorkflowLifecyclePhase;
+    to: AutomationWorkflowLifecyclePhase;
+}
+export interface AutomationWorkflowLifecyclePort {
+    /** Consumer-owned lookup. A nullish result is a failed lookup. */
+    lookup?(input: AutomationWorkflowLifecycleInput): Awaitable<unknown>;
+    /** Consumer-owned workflow design/authorization decision. */
+    designGate?(input: AutomationWorkflowLifecycleInput): Awaitable<AutomationWorkflowGateDecision>;
+    /** Consumer-owned durable checkpoint (usually a DB write). */
+    checkpoint?(input: AutomationWorkflowLifecycleInput): Awaitable<unknown>;
+    /** Consumer-owned human approval/HITL decision. */
+    humanGate?(input: AutomationWorkflowLifecycleInput): Awaitable<AutomationWorkflowGateDecision>;
+    /** Consumer-owned transition record or state update. */
+    transition?(input: AutomationWorkflowTransitionInput): Awaitable<unknown>;
+}
+export interface AutomationRunPorts extends RuntimeHostPorts {
+    runner: AutomationRunnerPort;
+    receipt: AutomationReceiptPort;
+    runStore: AutomationRunStorePort;
+    /** Optional until a consumer opts its existing workflow ports into the core. */
+    lifecycle?: AutomationWorkflowLifecyclePort;
+}
+export interface AutomationRunResult {
+    runnerResult: unknown;
+    normalizedReceipt: NormalizedRunReceipt;
+    persistedReceipt: unknown;
+    context: RuntimeHostContext;
+    replayed?: boolean;
+}
+export declare class AutomationRunService {
+    private readonly ports;
+    constructor(ports: AutomationRunPorts);
+    start(request: AutomationRunRequest): Promise<AutomationRunResult>;
+    run(request: AutomationRunRequest): Promise<AutomationRunResult>;
+    retry(request: AutomationRunRequest, previousRunId: string): Promise<AutomationRunResult>;
+    rerun(request: AutomationRunRequest, previousRunId: string): Promise<AutomationRunResult>;
+    history(request: AutomationRunRequest): Promise<unknown>;
+    getRun(request: AutomationRunRequest): Promise<unknown>;
+    private execute;
+}
+/** Thin compatibility facade for hosts that previously composed a control runtime. */
+export declare class AutomationControlRuntime {
+    private readonly service;
+    constructor(service: AutomationRunService);
+    start(request: AutomationRunRequest): Promise<AutomationRunResult>;
+    retry(request: AutomationRunRequest, previousRunId: string): Promise<AutomationRunResult>;
+    history(request: AutomationRunRequest): Promise<unknown>;
+    getRun(request: AutomationRunRequest): Promise<unknown>;
+}
+export declare function createAutomationRunService(ports: AutomationRunPorts): AutomationRunService;