@schift-io/knowledge-scope 0.1.0

package/dist/types/adapters/evidence-policy.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterFailure, CitationFact } from "./types.js";
+export declare const validateCitation: (citation: CitationFact) => AdapterFailure | undefined;
+export declare const validateFreshness: (freshness: string, now: Date, maxAgeSeconds: number | undefined) => AdapterFailure | undefined;

package/dist/types/adapters/gates.d.ts

@@ -0,0 +1,13 @@
+import { type JsonValue } from "../json.js";
+import type { AdapterCapability, AdapterFailure, AdapterSourceBinding, SchemaValidator } from "./types.js";
+export declare const GLOBAL_MAX_RESULT_BYTES: number;
+export declare const GLOBAL_MAX_ROWS = 100;
+export declare const validateBinding: (capability: AdapterCapability, binding: AdapterSourceBinding, expectedProviderRef: string) => AdapterFailure | undefined;
+export declare const validateFilters: (allowed: readonly string[] | undefined, filters: Readonly<Record<string, JsonValue>>) => AdapterFailure | undefined;
+export declare const validateProviderScopes: (required: readonly string[] | undefined, granted: readonly string[]) => AdapterFailure | undefined;
+export declare const validateRowCount: (rows: readonly unknown[], maxRows: number | undefined) => AdapterFailure | undefined;
+export declare const canonicalByteLength: (value: JsonValue) => number;
+export declare const validateByteLength: (value: JsonValue, maxBytes: number | undefined) => AdapterFailure | undefined;
+export declare const validateSchema: (validator: SchemaValidator | undefined, schemaRef: string, value: JsonValue, phase: "input" | "result") => Promise<AdapterFailure | undefined>;
+export declare const validateTimeout: (timeoutMs: number) => AdapterFailure | undefined;
+export declare const failure: (code: AdapterFailure["code"], message: string) => AdapterFailure;

package/dist/types/adapters/http-policy.d.ts

@@ -0,0 +1,10 @@
+import type { AdapterFailure } from "./types.js";
+export type SafeBaseUrlResult = Readonly<{
+    ok: true;
+    url: URL;
+}> | Readonly<{
+    ok: false;
+    error: AdapterFailure;
+}>;
+export declare const parseSafeBaseUrl: (value: string) => SafeBaseUrlResult;
+export declare const requestSignal: (signal: AbortSignal | undefined, timeoutMs: number) => AbortSignal;

package/dist/types/adapters/open-connector.d.ts

@@ -0,0 +1,20 @@
+import type { JsonValue } from "../json.js";
+import type { AdapterResult, AdapterSourceBinding, HttpTransport, OpenConnectorCapability, OpenConnectorInputMapper, OpenConnectorRowNormalizer, OpenConnectorRuntime, ProviderResultFact, SchemaValidator, TrustedEffectiveScope } from "./types.js";
+export type OpenConnectorAdapterInput = Readonly<{
+    capability: OpenConnectorCapability;
+    binding: AdapterSourceBinding;
+    request: Readonly<{
+        input: JsonValue;
+        filters: Readonly<Record<string, JsonValue>>;
+        effectiveScope: TrustedEffectiveScope;
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }>;
+    runtime: OpenConnectorRuntime;
+    transport: HttpTransport;
+    validateSchema: SchemaValidator | undefined;
+    normalizeRow: OpenConnectorRowNormalizer | undefined;
+    mapInput?: OpenConnectorInputMapper;
+    now?: Date;
+}>;
+export declare const runOpenConnectorAction: (input: OpenConnectorAdapterInput) => Promise<AdapterResult<ProviderResultFact>>;

package/dist/types/adapters/provider-port.d.ts

@@ -0,0 +1,27 @@
+import { type ProviderResult } from "@schift-io/knowledge-scope/context-pack";
+import type { ProviderExecutionContext, ProviderExecutionPort } from "../application.js";
+import type { AdapterFailureCode, HttpTransport, OpenConnectorInputMapper, OpenConnectorRowNormalizer, OpenConnectorRuntime, SchiftSearchRuntime } from "./types.js";
+export declare class HttpProviderAdapterError extends Error {
+    readonly code: AdapterFailureCode;
+    readonly name = "HttpProviderAdapterError";
+    constructor(code: AdapterFailureCode);
+}
+type SearchRuntimeResolution = Omit<SchiftSearchRuntime, "tenant">;
+export declare const bindTrustedSearchAuthority: (runtime: SearchRuntimeResolution, trustedTenant: string, trustedOrganizationId: string) => SchiftSearchRuntime;
+export interface HttpProviderRuntimeResolver {
+    resolveOpenConnector(context: ProviderExecutionContext): OpenConnectorRuntime | Promise<OpenConnectorRuntime>;
+    resolveSchiftSearch(context: ProviderExecutionContext): SearchRuntimeResolution | Promise<SearchRuntimeResolution>;
+}
+export type HttpProviderExecutionOptions = Readonly<{
+    transport: HttpTransport;
+    runtimeResolver: HttpProviderRuntimeResolver;
+    executeRecords?: RecordsOperationExecutor;
+    mapOpenConnectorInput?: OpenConnectorInputMapper;
+    normalizeOpenConnectorRow?: OpenConnectorRowNormalizer;
+    now?: () => Date;
+}>;
+export type RecordsOperationExecutor = (context: ProviderExecutionContext) => Promise<readonly ProviderResult[]>;
+export declare const normalizeDefaultOpenConnectorRow: OpenConnectorRowNormalizer;
+export declare const stableProviderIdempotencyKey: (context: ProviderExecutionContext) => string;
+export declare const createHttpProviderExecutionPort: (options: HttpProviderExecutionOptions) => ProviderExecutionPort;
+export {};

package/dist/types/adapters/response.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { type JsonValue } from "../json.js";
+import type { AdapterFailure, HttpResponseLike } from "./types.js";
+export type ParsedResponse = Readonly<{
+    ok: true;
+    value: JsonValue;
+}> | Readonly<{
+    ok: false;
+    error: AdapterFailure;
+}>;
+export declare const readProviderResponse: (response: HttpResponseLike, maxBytes: number | undefined) => Promise<ParsedResponse>;
+export declare const JsonValueSchema: z.ZodType<JsonValue>;

package/dist/types/adapters/schift-search-headers.d.ts

@@ -0,0 +1,2 @@
+import type { SchiftSearchRuntime } from "./types.js";
+export declare const searchRequestHeaders: (runtime: SchiftSearchRuntime) => Readonly<Record<string, string>>;

package/dist/types/adapters/schift-search-identity.d.ts

@@ -0,0 +1,14 @@
+import { type JsonValue } from "../json.js";
+export type SearchEvidenceIdentity = Readonly<{
+    bucket: string;
+    source: string;
+    document: string;
+    chunk: string;
+    text: string;
+    metadata: Readonly<Record<string, JsonValue>> | null;
+    title: string | null;
+    page: number | null;
+    section: string | null;
+}>;
+export declare const canonicalSearchSrn: (identity: SearchEvidenceIdentity) => string;
+export declare const searchContentRevision: (identity: SearchEvidenceIdentity) => string;

package/dist/types/adapters/schift-search.d.ts

@@ -0,0 +1,17 @@
+import type { JsonValue } from "../json.js";
+import type { AdapterResult, AdapterSourceBinding, HttpTransport, ProviderResultFact, SchemaValidator, SchiftSearchCapability, SchiftSearchRuntime, TrustedEffectiveScope } from "./types.js";
+export type SchiftSearchAdapterInput = Readonly<{
+    capability: SchiftSearchCapability;
+    binding: AdapterSourceBinding;
+    request: Readonly<{
+        input: JsonValue;
+        filters: Readonly<Record<string, JsonValue>>;
+        effectiveScope: TrustedEffectiveScope;
+        signal?: AbortSignal;
+    }>;
+    runtime: SchiftSearchRuntime;
+    transport: HttpTransport;
+    validateSchema: SchemaValidator | undefined;
+    now?: Date;
+}>;
+export declare const runSchiftSearch: (input: SchiftSearchAdapterInput) => Promise<AdapterResult<ProviderResultFact>>;

package/dist/types/adapters/types.d.ts

@@ -0,0 +1,136 @@
+import type { ProviderResult } from "@schift-io/knowledge-scope/context-pack";
+import type { JsonValue } from "../json.js";
+export type SourceClass = "activity_stream" | "document" | "records";
+export type AdapterCapability = Readonly<{
+    operationId: string;
+    inputSchemaRef: string;
+    resultSchemaRef: string;
+    allowedFilters?: readonly string[] | undefined;
+    limits?: Readonly<{
+        maxRows?: number | undefined;
+        maxResultBytes?: number | undefined;
+    }> | undefined;
+    freshness?: Readonly<{
+        maxAgeSeconds: number;
+    }> | undefined;
+    requiredProviderScopes?: readonly string[] | undefined;
+}>;
+export type OpenConnectorCapability = AdapterCapability & Readonly<{
+    provider: Readonly<{
+        kind: "open_connector_action";
+        actionId: string;
+        connectorRef: string;
+    }>;
+}>;
+export type SchiftSearchCapability = AdapterCapability & Readonly<{
+    provider: Readonly<{
+        kind: "schift_search";
+        indexRef: string;
+    }>;
+}>;
+export type AdapterSourceBinding = Readonly<{
+    sourceId: string;
+    sourceClass: SourceClass;
+    providerRef: string;
+    connectorRef?: string | undefined;
+    operationIds: readonly string[];
+}>;
+export type AdapterExecutionRequest = Readonly<{
+    input: JsonValue;
+    filters: Readonly<Record<string, JsonValue>>;
+    effectiveScope: TrustedEffectiveScope;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}>;
+export type HttpRequest = Readonly<{
+    url: string;
+    method: "GET" | "POST";
+    headers: Readonly<Record<string, string>>;
+    body?: string;
+    signal: AbortSignal;
+    redirect: "error";
+}>;
+export interface HttpResponseLike {
+    readonly status: number;
+    readonly headers: Readonly<{
+        get(name: string): string | null;
+    }>;
+    readonly body: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+}
+export type HttpTransport = (request: HttpRequest) => Promise<HttpResponseLike>;
+export type SchemaValidationResult = Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    code?: string;
+}>;
+export type SchemaValidator = (input: Readonly<{
+    schemaRef: string;
+    value: JsonValue;
+    phase: "input" | "result";
+}>) => SchemaValidationResult | Promise<SchemaValidationResult>;
+export declare const ADAPTER_FAILURE_CODES: readonly ["action_not_read_only", "binding_mismatch", "filter_not_allowed", "input_schema_invalid", "invalid_configuration", "invalid_freshness", "invalid_idempotency_key", "invalid_url", "permission_evidence_missing", "provider_identity_mismatch", "provider_rejected", "provider_response_malformed", "provider_scope_missing", "provider_unavailable", "response_too_large", "result_schema_invalid", "result_stale", "schema_validator_missing", "too_many_rows", "unsafe_citation"];
+export type AdapterFailureCode = (typeof ADAPTER_FAILURE_CODES)[number];
+export type AdapterFailure = Readonly<{
+    code: AdapterFailureCode;
+    message: string;
+}>;
+export type CitationFact = Readonly<{
+    uri: string;
+    label?: string;
+}>;
+export type ProviderResultFact = ProviderResult;
+export type OpenConnectorNormalizedRow = Readonly<{
+    resultId: string;
+    srn?: string;
+    revision: string;
+    freshness?: string;
+    payload: JsonValue;
+    citation?: CitationFact;
+}>;
+export type OpenConnectorRowNormalizer = (input: Readonly<{
+    row: JsonValue;
+    connectorRunId: string;
+    actionCorrelationId: string;
+}>) => OpenConnectorNormalizedRow | Promise<OpenConnectorNormalizedRow>;
+export type OpenConnectorInputMapper = (input: Readonly<{
+    input: JsonValue;
+    filters: Readonly<Record<string, JsonValue>>;
+    effectiveScope: TrustedEffectiveScope;
+    capability: OpenConnectorCapability;
+    binding: AdapterSourceBinding;
+}>) => JsonValue | Promise<JsonValue>;
+export type AdapterResult<TFact> = Readonly<{
+    ok: true;
+    facts: readonly TFact[];
+}> | Readonly<{
+    ok: false;
+    error: AdapterFailure;
+}>;
+export type OpenConnectorRuntime = Readonly<{
+    baseUrl: string;
+    connectorAlias?: string;
+    bearerToken?: string;
+    grantedProviderScopes: readonly string[];
+    readOnlyActions: readonly Readonly<{
+        connectorRef: string;
+        connectorAlias: string;
+        actionId: string;
+    }>[];
+    timeoutMs: number;
+}>;
+export type SchiftSearchRuntime = Readonly<{
+    baseUrl: string;
+    tenant: string;
+    organizationId: string;
+    bearerToken: string;
+    grantedProviderScopes: readonly string[];
+    timeoutMs: number;
+}>;
+export type TrustedEffectiveScope = Readonly<{
+    tenant: string;
+    namespace?: string;
+    subject?: string;
+    session?: string;
+}>;

package/dist/types/api-contract.d.ts

@@ -0,0 +1,164 @@
+import { z } from "zod";
+import { type CapabilityBatchExecutionRequest } from "@schift-io/knowledge-scope/context-pack";
+import type { JsonValue } from "./json.js";
+export declare const RemoteMountRequestSchema: z.ZodReadonly<z.ZodObject<{
+    definition: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    files: z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>;
+    lock: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    sourceBindings: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+}, "strict", z.ZodTypeAny, {
+    files: Record<string, JsonValue>;
+    definition: JsonValue;
+    lock: JsonValue;
+    sourceBindings: JsonValue;
+}, {
+    files: Record<string, JsonValue>;
+    definition: JsonValue;
+    lock: JsonValue;
+    sourceBindings: JsonValue;
+}>>;
+declare const MountRequestSchema: z.ZodReadonly<z.ZodObject<{
+    definition: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    files: z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>;
+    lock: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    scopeAuthority: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    sourceBindings: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+}, "strict", z.ZodTypeAny, {
+    scopeAuthority: JsonValue;
+    files: Record<string, JsonValue>;
+    definition: JsonValue;
+    lock: JsonValue;
+    sourceBindings: JsonValue;
+}, {
+    scopeAuthority: JsonValue;
+    files: Record<string, JsonValue>;
+    definition: JsonValue;
+    lock: JsonValue;
+    sourceBindings: JsonValue;
+}>>;
+export declare const RunBodySchema: z.ZodReadonly<z.ZodObject<{
+    effectiveScope: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    input: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    filters: z.ZodOptional<z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>;
+    expectedRevision: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    effectiveScope: JsonValue;
+    input: JsonValue;
+    filters?: JsonValue | undefined;
+    expectedRevision?: number | undefined;
+}, {
+    effectiveScope: JsonValue;
+    input: JsonValue;
+    filters?: JsonValue | undefined;
+    expectedRevision?: number | undefined;
+}>>;
+export declare const RunBatchBodySchema: z.ZodReadonly<z.ZodObject<Omit<{
+    installationId: z.ZodBranded<z.ZodString, "InstallationId">;
+    effectiveScope: z.ZodReadonly<z.ZodObject<{
+        tenant: z.ZodString;
+        namespace: z.ZodOptional<z.ZodString>;
+        subject: z.ZodOptional<z.ZodString>;
+        session: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }, {
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }>>;
+    expectedRevision: z.ZodOptional<z.ZodNumber>;
+    operations: z.ZodReadonly<z.ZodEffects<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        operationId: z.ZodString;
+        input: z.ZodEffects<z.ZodType<import("@schift-io/knowledge-scope/context-pack").JsonValue, z.ZodTypeDef, import("@schift-io/knowledge-scope/context-pack").JsonValue>, import("@schift-io/knowledge-scope/context-pack").JsonValue, import("@schift-io/knowledge-scope/context-pack").JsonValue>;
+        filters: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodType<import("@schift-io/knowledge-scope/context-pack").JsonValue, z.ZodTypeDef, import("@schift-io/knowledge-scope/context-pack").JsonValue>, import("@schift-io/knowledge-scope/context-pack").JsonValue, import("@schift-io/knowledge-scope/context-pack").JsonValue>>>>;
+    }, "strict", z.ZodTypeAny, {
+        operationId: string;
+        input: import("../dist/types/context-pack/canonical.js").JsonValue;
+        filters?: Readonly<Record<string, import("@schift-io/knowledge-scope/context-pack").JsonValue>> | undefined;
+    }, {
+        operationId: string;
+        input: import("../dist/types/context-pack/canonical.js").JsonValue;
+        filters?: Readonly<Record<string, import("@schift-io/knowledge-scope/context-pack").JsonValue>> | undefined;
+    }>>, "many">, Readonly<{
+        operationId: string;
+        input: import("@schift-io/knowledge-scope/context-pack").JsonValue;
+        filters?: Readonly<Record<string, import("@schift-io/knowledge-scope/context-pack").JsonValue>> | undefined;
+    }>[], Readonly<{
+        operationId: string;
+        input: import("@schift-io/knowledge-scope/context-pack").JsonValue;
+        filters?: Readonly<Record<string, import("@schift-io/knowledge-scope/context-pack").JsonValue>> | undefined;
+    }>[]>>;
+}, "installationId">, "strict", z.ZodTypeAny, {
+    effectiveScope: Readonly<{
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }>;
+    operations: readonly Readonly<{
+        operationId: string;
+        input: import("@schift-io/knowledge-scope/context-pack").JsonValue;
+        filters?: Readonly<Record<string, import("@schift-io/knowledge-scope/context-pack").JsonValue>> | undefined;
+    }>[];
+    expectedRevision?: number | undefined;
+}, {
+    effectiveScope: Readonly<{
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }>;
+    operations: readonly Readonly<{
+        operationId: string;
+        input: import("@schift-io/knowledge-scope/context-pack").JsonValue;
+        filters?: Readonly<Record<string, import("@schift-io/knowledge-scope/context-pack").JsonValue>> | undefined;
+    }>[];
+    expectedRevision?: number | undefined;
+}>>;
+export declare const AdmitBodySchema: z.ZodUnion<[z.ZodReadonly<z.ZodObject<{
+    candidates: z.ZodReadonly<z.ZodArray<z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    candidates: readonly JsonValue[];
+}, {
+    candidates: readonly JsonValue[];
+}>>, z.ZodReadonly<z.ZodObject<{
+    candidate: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+}, "strict", z.ZodTypeAny, {
+    candidate: JsonValue;
+}, {
+    candidate: JsonValue;
+}>>]>;
+export declare const UnmountBodySchema: z.ZodReadonly<z.ZodObject<{
+    expectedRevision: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    expectedRevision: number;
+}, {
+    expectedRevision: number;
+}>>;
+export type MountApplicationRequest = z.infer<typeof MountRequestSchema>;
+export type RunApplicationRequest = Readonly<z.infer<typeof RunBodySchema> & {
+    installationId: string;
+    operationId: string;
+}>;
+export type RunBatchApplicationRequest = CapabilityBatchExecutionRequest;
+export type AdmitApplicationRequest = Readonly<{
+    installationId: string;
+    candidates: readonly JsonValue[];
+}>;
+export type UnmountApplicationRequest = Readonly<{
+    installationId: string;
+    expectedRevision: number;
+}>;
+export interface KnowledgeScopeApplicationPort {
+    readonly mount: (request: MountApplicationRequest) => Promise<JsonValue>;
+    readonly inspect: (installationId: string) => Promise<JsonValue>;
+    readonly run: (request: RunApplicationRequest) => Promise<JsonValue>;
+    readonly admit: (request: AdmitApplicationRequest) => Promise<JsonValue>;
+    readonly unmount: (request: UnmountApplicationRequest) => Promise<JsonValue>;
+    readonly runBatch?: (request: RunBatchApplicationRequest) => Promise<JsonValue>;
+}
+export {};

package/dist/types/api.d.ts

@@ -0,0 +1,30 @@
+import { type KnowledgeScopeApplicationPort } from "./api-contract.js";
+export type { MountApplicationRequest, RunApplicationRequest, RunBatchApplicationRequest, AdmitApplicationRequest, UnmountApplicationRequest, KnowledgeScopeApplicationPort } from "./api-contract.js";
+import { type JsonValue } from "./json.js";
+export declare class KnowledgeScopeApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly name = "KnowledgeScopeApiError";
+    constructor(code: string, status: number);
+}
+type ApiOptions = Readonly<{
+    application: KnowledgeScopeApplicationPort;
+    mountAuthority: JsonValue | (() => Promise<JsonValue>);
+    maxBodyBytes?: number;
+    apiToken?: string;
+}>;
+type Api = Readonly<{
+    fetch: (request: Request) => Promise<Response>;
+}>;
+export declare const createKnowledgeScopeApi: (options: ApiOptions) => Api;
+export type ServedKnowledgeScopeApi = Readonly<{
+    host: string;
+    port: number;
+    stop: () => void;
+}>;
+export declare const serveKnowledgeScopeApi: (options: ApiOptions & Readonly<{
+    host?: string;
+    port?: number;
+}>) => Promise<ServedKnowledgeScopeApi>;
+type RequestFunction = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare const createRemoteKnowledgeScopeApplication: (apiUrl: string, request?: RequestFunction, apiToken?: string) => KnowledgeScopeApplicationPort;

package/dist/types/application-batch.d.ts

@@ -0,0 +1,4 @@
+import type { CandidateEnvelope, CapabilityBatchExecutionRequest } from "@schift-io/knowledge-scope/context-pack";
+import type { KnowledgeScopeApplicationOptions } from "./application.js";
+import type { StoredKnowledgeScope } from "./state-contract.js";
+export declare const executeBatch: (options: Pick<KnowledgeScopeApplicationOptions, "provider" | "authorization">, stored: StoredKnowledgeScope, request: CapabilityBatchExecutionRequest) => Promise<readonly CandidateEnvelope[]>;

package/dist/types/application-execution.d.ts

@@ -0,0 +1,30 @@
+import { type CandidateEnvelope, type CapabilityExecutionRequest, type KnowledgeScopeDefinition, type KnowledgeScopeMount, type QueryCapability } from "@schift-io/knowledge-scope/context-pack";
+import { type KnowledgeScopeAuthorization } from "./authorization.js";
+import { type JsonValue } from "./json.js";
+import { type ExecutionBudget } from "./limits.js";
+import { type SchemaValidationResult } from "./schema-subset.js";
+import type { StoredKnowledgeScope } from "./state-contract.js";
+type SourceBinding = KnowledgeScopeMount["sourceBindings"][number];
+type SchemaValidator = (value: JsonValue) => SchemaValidationResult;
+export type ProviderExecutionContext = Readonly<{
+    definition: KnowledgeScopeDefinition;
+    mount: KnowledgeScopeMount;
+    capability: QueryCapability;
+    binding: SourceBinding;
+    request: CapabilityExecutionRequest;
+    validateInput: SchemaValidator;
+    validateResult: SchemaValidator;
+}>;
+export interface ProviderExecutionPort {
+    execute(context: ProviderExecutionContext): Promise<readonly unknown[]>;
+}
+export type PreparedExecution = Readonly<{
+    budget?: ExecutionBudget;
+    capability: QueryCapability;
+    bindings: readonly SourceBinding[];
+    validateInput: SchemaValidator;
+    validateResult: SchemaValidator;
+}>;
+export declare const prepareExecution: (stored: StoredKnowledgeScope, request: CapabilityExecutionRequest) => PreparedExecution;
+export declare const executeAndNormalize: (provider: ProviderExecutionPort, authorization: KnowledgeScopeAuthorization, stored: StoredKnowledgeScope, request: CapabilityExecutionRequest, prepared: PreparedExecution) => Promise<readonly CandidateEnvelope[]>;
+export {};

package/dist/types/application.d.ts

@@ -0,0 +1,47 @@
+import { type CandidateEnvelope, type KnowledgeScopeDefinition, type KnowledgeScopeMount, type ScopeRequirementReceipt } from "@schift-io/knowledge-scope/context-pack";
+import { type KnowledgeScopeAuthorization } from "./authorization.js";
+import type { PortableKnowledgeScope } from "./portable.js";
+import { type ProviderExecutionPort } from "./application-execution.js";
+import type { StoredKnowledgeScope } from "./state-contract.js";
+import type { KnowledgeScopeStateStore } from "./state-store.js";
+export type { ProviderExecutionContext, ProviderExecutionPort } from "./application-execution.js";
+export { GLOBAL_MAX_RESULT_BYTES, GLOBAL_MAX_RESULT_ROWS, MAX_BINDINGS, MAX_CANDIDATES, } from "./limits.js";
+export type MountKnowledgeScopeInput = Readonly<{
+    portable: PortableKnowledgeScope;
+    scopeAuthority: unknown;
+    sourceBindings: unknown;
+}>;
+export type KnowledgeScopeInspection = Readonly<{
+    definition: KnowledgeScopeDefinition;
+    lock: StoredKnowledgeScope["lock"];
+    mount: KnowledgeScopeMount;
+}>;
+export type KnowledgeScopeRunResult = Readonly<{
+    status: "ready";
+    candidates: readonly CandidateEnvelope[];
+    receipt: ScopeRequirementReceipt;
+}> | Readonly<{
+    status: "insufficient_evidence";
+    candidates: readonly [];
+    receipt: ScopeRequirementReceipt;
+}>;
+export type KnowledgeScopeApplicationOptions = Readonly<{
+    store: KnowledgeScopeStateStore;
+    authorization: KnowledgeScopeAuthorization;
+    provider: ProviderExecutionPort;
+    now?: () => Date;
+}>;
+export declare class KnowledgeScopeApplication {
+    private readonly store;
+    private readonly authorization;
+    private readonly provider;
+    private readonly now;
+    constructor(options: KnowledgeScopeApplicationOptions);
+    mount(input: MountKnowledgeScopeInput): Promise<KnowledgeScopeMount>;
+    inspect(installationId: string): Promise<KnowledgeScopeInspection>;
+    unmount(installationId: string, expectedRevision: number): Promise<KnowledgeScopeMount>;
+    run(rawRequest: unknown): Promise<KnowledgeScopeRunResult>;
+    runBatch(rawRequest: unknown): Promise<KnowledgeScopeRunResult>;
+    admit(installationId: string, rawCandidates: readonly unknown[]): Promise<ScopeRequirementReceipt>;
+    private findStored;
+}