@tryvira/mcp 0.0.0-stage → 0.1.1

package/dist/domain/src/scope-composer.d.ts

@@ -0,0 +1,138 @@
+export declare function scopeDigest(scope: unknown): string;
+export type ScopeLevel = 'platform' | 'organization' | 'project' | 'application' | 'workspace' | 'user' | 'session';
+export interface HierarchicalScope {
+    level: ScopeLevel;
+    id: string;
+    parentId?: string;
+}
+export interface ScopeDelegation {
+    id: string;
+    issuerId: string;
+    subjectId: string;
+    fromLevel: ScopeLevel;
+    toLevel: ScopeLevel;
+    permissions: readonly string[];
+    expiresAt: string;
+}
+export interface CanonicalOrganizationScopeInput {
+    applicationId?: string | null;
+    workspaceId?: string | null;
+    userId?: string | null;
+    sessionId?: string | null;
+}
+/** Canonical serializer shared by organization intelligence and Teach boundaries. */
+export declare function canonicalOrganizationScopeKeys(input: CanonicalOrganizationScopeInput): string[];
+export interface ReferenceScopeDelegation extends ScopeDelegation {
+    stableKey: string;
+    parentAuthorityLevel: ScopeLevel;
+    childScopeKind: ScopeLevel;
+    childScopeDigest: string;
+    parentRevisionDigest: string;
+    /** Reference programs may narrow an exception to explicit effect kinds. */
+    exceptionEffectTypes?: readonly string[];
+    when: {
+        kind: 'all';
+        expressions: readonly [];
+    };
+}
+export interface ScopeCompositionConflict {
+    code: 'SCOPE_CHAIN_INVALID' | 'SCOPE_DELEGATION_CONFLICT' | 'SCOPE_REVISION_LEVEL_CONFLICT' | 'TEMPORAL_INVARIANT_CONFLICT' | 'TEMPORAL_TRANSITION_CONFLICT' | 'RECOVERY_CONFLICT' | 'ACTOR_OWNERSHIP_CONFLICT' | 'DEADLINE_CONFLICT';
+    delegationIds: readonly string[];
+    hard: true;
+}
+export interface EffectiveRevisionBinding {
+    id: string;
+    digest: string;
+    sourceRevisionSetDigest?: string;
+    ancestorHardAuthorityDigest?: string;
+}
+export interface ScopeBehaviorRevision {
+    id: string;
+    digest: string;
+    level: ScopeLevel;
+    hard: boolean;
+    source: string;
+    temporalInvariantDigest?: string;
+    temporalTransitionDigest?: string;
+    recoveryDigest?: string;
+    temporalInvariantKeys?: Readonly<Record<string, string>>;
+    temporalTransitionKeys?: Readonly<Record<string, string>>;
+    recoveryKeys?: Readonly<Record<string, string>>;
+    actorOwnershipDigest?: string;
+    deadlineDigest?: string;
+}
+export interface ScopeCompositionExplanation {
+    revisionId: string;
+    level: ScopeLevel;
+    disposition: 'inherited' | 'overridden' | 'rejected';
+    reason: string;
+}
+export interface ComposedScope {
+    chain: readonly HierarchicalScope[];
+    permissions: readonly string[];
+    delegationIds?: readonly string[];
+    compositionDigest: string;
+    conflictSetDigest: string;
+    conflictSummary: {
+        total: number;
+        hard: number;
+        soft: number;
+        byCategory: Record<string, number>;
+    };
+    conflicts: readonly ScopeCompositionConflict[];
+    serveable: boolean;
+    effectiveRevision?: EffectiveRevisionBinding;
+    sourceRevisions?: readonly ScopeBehaviorRevision[];
+    sourceRevisionSetDigest?: string;
+    ancestorHardAuthorityDigest?: string;
+    effectiveProgramDigest?: string;
+    explanations?: readonly ScopeCompositionExplanation[];
+}
+export declare function projectComposedScope(composed: ComposedScope): import('./vnext.ts').Scope;
+export declare function assertComposedScopeIntegrity(composed: ComposedScope): true;
+/** Re-seals the existing canonical scope authority with effective-program lineage. */
+export declare function bindEffectiveProgramAuthority(composed: ComposedScope, input: {
+    effectiveProgramDigest: string;
+    sourceRevisionSetDigest: string;
+    ancestorHardAuthorityDigest: string;
+}): ComposedScope;
+export interface ScopeCompositionRevalidation {
+    stale: boolean;
+    sourceRevisionSetChanged: boolean;
+    ancestorHardAuthorityChanged: boolean;
+    effectiveProgramChanged: boolean;
+    effectiveRevisionChanged: boolean;
+    conflictSetChanged: boolean;
+    compatible: boolean;
+    taintRequired: boolean;
+}
+/** Reference-equivalent dependency check for an already materialized scope. */
+export declare function compositionDependencyStale(previous: ComposedScope, next: ComposedScope): boolean;
+/** Revalidation must be explicit before a changed composition can be served. */
+export declare function revalidateScopeComposition(previous: ComposedScope, next: ComposedScope): ScopeCompositionRevalidation;
+export declare function composeScope(input: {
+    chain: readonly HierarchicalScope[];
+    delegation?: ScopeDelegation | null;
+    now?: string;
+    availablePermissions?: readonly string[];
+    effectiveRevision?: EffectiveRevisionBinding;
+    sourceRevisions?: readonly ScopeBehaviorRevision[];
+}): ComposedScope;
+/** Compose all supplied delegations, rejecting duplicate ids and preserving one digest for runtime checks. */
+export declare function composeDelegatedScope(input: {
+    chain: readonly HierarchicalScope[];
+    delegations: readonly ScopeDelegation[];
+    now?: string;
+    availablePermissions?: readonly string[];
+    effectiveRevision?: EffectiveRevisionBinding;
+    sourceRevisions?: readonly ScopeBehaviorRevision[];
+}): ComposedScope;
+/** Reference-shaped exception delegation: parent-authored, exact-child and digest-bound. */
+export declare function composeReferenceDelegatedScope(input: {
+    chain: readonly HierarchicalScope[];
+    delegation: ReferenceScopeDelegation;
+    now?: string;
+    availablePermissions?: readonly string[];
+    effectiveRevision?: EffectiveRevisionBinding;
+    sourceRevisions?: readonly ScopeBehaviorRevision[];
+}): ComposedScope;

package/dist/domain/src/vnext.d.ts

@@ -0,0 +1,53 @@
+export interface Scope {
+    organizationId: string;
+    projectId: string;
+    environmentId: string;
+    /** Optional hierarchy identities carried when a composed authority is in scope. */
+    applicationId?: string | null;
+    workspaceId?: string | null;
+    userId?: string | null;
+    sessionId?: string | null;
+    /** Optional composed-authority binding carried by persistence boundaries. */
+    authorityDigest?: string | null;
+}
+export interface ScopedEntity extends Scope {
+    id: string;
+}
+export interface Policy extends ScopedEntity {
+    effect: 'allow' | 'deny';
+    revision: string;
+}
+/**
+ * The governed behavior boundary exposed by Vira's product model.
+ *
+ * `ControlPoint` was the pre-product name. Keep the type alias for persisted
+ * legacy adapters, but new domain code must use BehaviorPoint.
+ */
+export interface BehaviorPoint extends ScopedEntity {
+}
+/** @deprecated Use BehaviorPoint. This alias exists only at compatibility boundaries. */
+export type ControlPoint = BehaviorPoint;
+export interface BehaviorVariant extends ScopedEntity {
+}
+export interface Revision extends Scope {
+    id: string;
+    controlPointId: string;
+    variantId: string;
+    policyRevision: string;
+    immutable: true;
+}
+export interface ExecutionReceipt extends Scope {
+    id: string;
+    revisionId: string;
+    actorId: string;
+    idempotencyKey: string;
+    decision: string;
+    reason: string;
+    createdAt: string;
+    semanticTaskRef?: string;
+    semanticTaskVersion?: number;
+    semanticTaskDigest?: string;
+}
+export declare function assertSameScope(...items: readonly Scope[]): void;
+export declare function issueRevision(scope: Scope, behaviorPoint: BehaviorPoint, policy: Policy, variant: BehaviorVariant, id: string): Revision;
+export declare function makeReceipt(scope: Scope, revision: Revision, actorId: string, idempotencyKey: string, decision: string, reason: string): ExecutionReceipt;

package/dist/index.d.ts

@@ -0,0 +1,306 @@
+declare module "domain/src/vnext" {
+    export interface Scope {
+        organizationId: string;
+        projectId: string;
+        environmentId: string;
+        /** Optional hierarchy identities carried when a composed authority is in scope. */
+        applicationId?: string | null;
+        workspaceId?: string | null;
+        userId?: string | null;
+        sessionId?: string | null;
+        /** Optional composed-authority binding carried by persistence boundaries. */
+        authorityDigest?: string | null;
+    }
+    export interface ScopedEntity extends Scope {
+        id: string;
+    }
+    export interface Policy extends ScopedEntity {
+        effect: 'allow' | 'deny';
+        revision: string;
+    }
+    /**
+     * The governed behavior boundary exposed by Vira's product model.
+     *
+     * `ControlPoint` was the pre-product name. Keep the type alias for persisted
+     * legacy adapters, but new domain code must use BehaviorPoint.
+     */
+    export interface BehaviorPoint extends ScopedEntity {
+    }
+    /** @deprecated Use BehaviorPoint. This alias exists only at compatibility boundaries. */
+    export type ControlPoint = BehaviorPoint;
+    export interface BehaviorVariant extends ScopedEntity {
+    }
+    export interface Revision extends Scope {
+        id: string;
+        controlPointId: string;
+        variantId: string;
+        policyRevision: string;
+        immutable: true;
+    }
+    export interface ExecutionReceipt extends Scope {
+        id: string;
+        revisionId: string;
+        actorId: string;
+        idempotencyKey: string;
+        decision: string;
+        reason: string;
+        createdAt: string;
+        semanticTaskRef?: string;
+        semanticTaskVersion?: number;
+        semanticTaskDigest?: string;
+    }
+    export function assertSameScope(...items: readonly Scope[]): void;
+    export function issueRevision(scope: Scope, behaviorPoint: BehaviorPoint, policy: Policy, variant: BehaviorVariant, id: string): Revision;
+    export function makeReceipt(scope: Scope, revision: Revision, actorId: string, idempotencyKey: string, decision: string, reason: string): ExecutionReceipt;
+}
+declare module "domain/src/scope-composer" {
+    export function scopeDigest(scope: unknown): string;
+    export type ScopeLevel = 'platform' | 'organization' | 'project' | 'application' | 'workspace' | 'user' | 'session';
+    export interface HierarchicalScope {
+        level: ScopeLevel;
+        id: string;
+        parentId?: string;
+    }
+    export interface ScopeDelegation {
+        id: string;
+        issuerId: string;
+        subjectId: string;
+        fromLevel: ScopeLevel;
+        toLevel: ScopeLevel;
+        permissions: readonly string[];
+        expiresAt: string;
+    }
+    export interface CanonicalOrganizationScopeInput {
+        applicationId?: string | null;
+        workspaceId?: string | null;
+        userId?: string | null;
+        sessionId?: string | null;
+    }
+    /** Canonical serializer shared by organization intelligence and Teach boundaries. */
+    export function canonicalOrganizationScopeKeys(input: CanonicalOrganizationScopeInput): string[];
+    export interface ReferenceScopeDelegation extends ScopeDelegation {
+        stableKey: string;
+        parentAuthorityLevel: ScopeLevel;
+        childScopeKind: ScopeLevel;
+        childScopeDigest: string;
+        parentRevisionDigest: string;
+        /** Reference programs may narrow an exception to explicit effect kinds. */
+        exceptionEffectTypes?: readonly string[];
+        when: {
+            kind: 'all';
+            expressions: readonly [];
+        };
+    }
+    export interface ScopeCompositionConflict {
+        code: 'SCOPE_CHAIN_INVALID' | 'SCOPE_DELEGATION_CONFLICT' | 'SCOPE_REVISION_LEVEL_CONFLICT' | 'TEMPORAL_INVARIANT_CONFLICT' | 'TEMPORAL_TRANSITION_CONFLICT' | 'RECOVERY_CONFLICT' | 'ACTOR_OWNERSHIP_CONFLICT' | 'DEADLINE_CONFLICT';
+        delegationIds: readonly string[];
+        hard: true;
+    }
+    export interface EffectiveRevisionBinding {
+        id: string;
+        digest: string;
+        sourceRevisionSetDigest?: string;
+        ancestorHardAuthorityDigest?: string;
+    }
+    export interface ScopeBehaviorRevision {
+        id: string;
+        digest: string;
+        level: ScopeLevel;
+        hard: boolean;
+        source: string;
+        temporalInvariantDigest?: string;
+        temporalTransitionDigest?: string;
+        recoveryDigest?: string;
+        temporalInvariantKeys?: Readonly<Record<string, string>>;
+        temporalTransitionKeys?: Readonly<Record<string, string>>;
+        recoveryKeys?: Readonly<Record<string, string>>;
+        actorOwnershipDigest?: string;
+        deadlineDigest?: string;
+    }
+    export interface ScopeCompositionExplanation {
+        revisionId: string;
+        level: ScopeLevel;
+        disposition: 'inherited' | 'overridden' | 'rejected';
+        reason: string;
+    }
+    export interface ComposedScope {
+        chain: readonly HierarchicalScope[];
+        permissions: readonly string[];
+        delegationIds?: readonly string[];
+        compositionDigest: string;
+        conflictSetDigest: string;
+        conflictSummary: {
+            total: number;
+            hard: number;
+            soft: number;
+            byCategory: Record<string, number>;
+        };
+        conflicts: readonly ScopeCompositionConflict[];
+        serveable: boolean;
+        effectiveRevision?: EffectiveRevisionBinding;
+        sourceRevisions?: readonly ScopeBehaviorRevision[];
+        sourceRevisionSetDigest?: string;
+        ancestorHardAuthorityDigest?: string;
+        effectiveProgramDigest?: string;
+        explanations?: readonly ScopeCompositionExplanation[];
+    }
+    export function projectComposedScope(composed: ComposedScope): import("domain/src/vnext").Scope;
+    export function assertComposedScopeIntegrity(composed: ComposedScope): true;
+    /** Re-seals the existing canonical scope authority with effective-program lineage. */
+    export function bindEffectiveProgramAuthority(composed: ComposedScope, input: {
+        effectiveProgramDigest: string;
+        sourceRevisionSetDigest: string;
+        ancestorHardAuthorityDigest: string;
+    }): ComposedScope;
+    export interface ScopeCompositionRevalidation {
+        stale: boolean;
+        sourceRevisionSetChanged: boolean;
+        ancestorHardAuthorityChanged: boolean;
+        effectiveProgramChanged: boolean;
+        effectiveRevisionChanged: boolean;
+        conflictSetChanged: boolean;
+        compatible: boolean;
+        taintRequired: boolean;
+    }
+    /** Reference-equivalent dependency check for an already materialized scope. */
+    export function compositionDependencyStale(previous: ComposedScope, next: ComposedScope): boolean;
+    /** Revalidation must be explicit before a changed composition can be served. */
+    export function revalidateScopeComposition(previous: ComposedScope, next: ComposedScope): ScopeCompositionRevalidation;
+    export function composeScope(input: {
+        chain: readonly HierarchicalScope[];
+        delegation?: ScopeDelegation | null;
+        now?: string;
+        availablePermissions?: readonly string[];
+        effectiveRevision?: EffectiveRevisionBinding;
+        sourceRevisions?: readonly ScopeBehaviorRevision[];
+    }): ComposedScope;
+    /** Compose all supplied delegations, rejecting duplicate ids and preserving one digest for runtime checks. */
+    export function composeDelegatedScope(input: {
+        chain: readonly HierarchicalScope[];
+        delegations: readonly ScopeDelegation[];
+        now?: string;
+        availablePermissions?: readonly string[];
+        effectiveRevision?: EffectiveRevisionBinding;
+        sourceRevisions?: readonly ScopeBehaviorRevision[];
+    }): ComposedScope;
+    /** Reference-shaped exception delegation: parent-authored, exact-child and digest-bound. */
+    export function composeReferenceDelegatedScope(input: {
+        chain: readonly HierarchicalScope[];
+        delegation: ReferenceScopeDelegation;
+        now?: string;
+        availablePermissions?: readonly string[];
+        effectiveRevision?: EffectiveRevisionBinding;
+        sourceRevisions?: readonly ScopeBehaviorRevision[];
+    }): ComposedScope;
+}
+declare module "runtime/src/mcp-gateway" {
+    export const MCP_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25", "2025-03-26"];
+    export function negotiateMcpProtocolVersion(offered: unknown): string;
+    import { type ComposedScope } from "domain/src/scope-composer";
+    import type { Scope } from "domain/src/vnext";
+    export interface McpInvocation extends Scope {
+        id: string;
+        server: string;
+        tool: string;
+        arguments: Record<string, unknown>;
+        receiptId: string;
+        idempotencyKey: string;
+        authorityDigest?: string;
+        composedScope?: ComposedScope;
+    }
+    export interface McpResult extends Scope {
+        invocationId: string;
+        ok: boolean;
+        result?: unknown;
+        error?: string;
+        provenanceDigest: string;
+        server: string;
+        tool: string;
+        receiptId: string;
+        idempotencyKey: string;
+        argumentsDigest: string;
+        authorityDecisionDigest: string;
+        authorityDigest?: string | null;
+    }
+    export interface McpTransport {
+        call(input: {
+            server: string;
+            tool: string;
+            arguments: Record<string, unknown>;
+            signal?: AbortSignal;
+        }): Promise<{
+            result?: unknown;
+            error?: string;
+        }>;
+    }
+    export interface McpToolDefinition {
+        name: string;
+        description?: string;
+        inputSchema: Record<string, unknown>;
+        effectful?: boolean;
+    }
+    export interface McpResourceDefinition {
+        uri: string;
+        name: string;
+        description?: string;
+        mimeType?: string;
+    }
+    export interface McpPromptDefinition {
+        name: string;
+        description?: string;
+        arguments?: readonly Record<string, unknown>[];
+    }
+    export interface McpAuthorityDecision {
+        allowed: boolean;
+        decisionDigest: string;
+        reason?: string;
+    }
+    export interface McpCancellationRegistry {
+        register(requestId: string): AbortSignal;
+        cancel(requestId: string): boolean;
+        unregister(requestId: string, signal?: AbortSignal): void;
+    }
+    export function canonicalMcpJson(value: unknown): string;
+    export function verifyMcpResult(result: McpResult): true;
+    export function createMcpCancellationRegistry(): McpCancellationRegistry;
+    export function parseMcpEventStream(body: string, expectedId?: string): readonly string[];
+    export function createRegisteredMcpTransport(input: {
+        endpoint: string;
+        allowedHosts: readonly string[];
+        fetcher?: typeof fetch;
+        timeoutMs?: number;
+        protocolVersion?: string;
+        headers?: Readonly<Record<string, string>>;
+    }): McpTransport;
+    export function handleMcpJsonRpc(input: {
+        request: {
+            jsonrpc: '2.0';
+            id?: string | number;
+            method: string;
+            params?: Record<string, unknown>;
+        };
+        server: string;
+        tools: readonly McpToolDefinition[];
+        resources?: readonly McpResourceDefinition[];
+        prompts?: readonly McpPromptDefinition[];
+        readResource?: (uri: string) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
+        getPrompt?: (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
+        invocation: Omit<McpInvocation, 'server' | 'tool' | 'arguments'>;
+        transport: McpTransport;
+        signal?: AbortSignal;
+        cancellationRegistry?: McpCancellationRegistry;
+        authorize?: (input: {
+            invocation: McpInvocation;
+            definition: McpToolDefinition;
+        }) => Promise<McpAuthorityDecision> | McpAuthorityDecision;
+    }): Promise<Record<string, unknown> | null>;
+    export function invokeMcpTool(input: {
+        invocation: McpInvocation;
+        transport: McpTransport;
+        authority?: McpAuthorityDecision;
+        signal?: AbortSignal;
+    }): Promise<McpResult>;
+}
+declare module "mcp/src/index" {
+    export * from "runtime/src/mcp-gateway";
+}