@schift-io/knowledge-scope 0.1.0

package/dist/types/authorization.d.ts

@@ -0,0 +1,228 @@
+import { CandidateEnvelopeSchema, type AuthorizationDecision } from "@schift-io/knowledge-scope/context-pack";
+export declare const AuthorizationSubjectSchema: import("zod").ZodReadonly<import("zod").ZodObject<Pick<{
+    srn: import("zod").ZodString;
+    sourceId: import("zod").ZodBranded<import("zod").ZodString, "SourceId">;
+    sourceClass: import("zod").ZodEnum<["document", "records", "activity_stream"]>;
+    providerRef: import("zod").ZodString;
+    installationId: import("zod").ZodBranded<import("zod").ZodString, "InstallationId">;
+    definitionDigest: import("zod").ZodBranded<import("zod").ZodString, "Sha256Digest">;
+    mountRevision: import("zod").ZodNumber;
+    operationId: import("zod").ZodString;
+    scopeAuthority: import("zod").ZodReadonly<import("zod").ZodObject<{
+        organizationId: import("zod").ZodString;
+        tenant: import("zod").ZodString;
+    }, "strict", import("zod").ZodTypeAny, {
+        tenant: string;
+        organizationId: string;
+    }, {
+        tenant: string;
+        organizationId: string;
+    }>>;
+    effectiveScope: import("zod").ZodReadonly<import("zod").ZodObject<{
+        tenant: import("zod").ZodString;
+        namespace: import("zod").ZodOptional<import("zod").ZodString>;
+        subject: import("zod").ZodOptional<import("zod").ZodString>;
+        session: import("zod").ZodOptional<import("zod").ZodString>;
+    }, "strict", import("zod").ZodTypeAny, {
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }, {
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }>>;
+    authorizationDecision: import("zod").ZodReadonly<import("zod").ZodObject<{
+        decisionId: import("zod").ZodString;
+        decisionDigest: import("zod").ZodBranded<import("zod").ZodString, "Sha256Digest">;
+        status: import("zod").ZodLiteral<"allowed">;
+    }, "strict", import("zod").ZodTypeAny, {
+        status: "allowed";
+        decisionId: string;
+        decisionDigest: string & import("zod").BRAND<"Sha256Digest">;
+    }, {
+        status: "allowed";
+        decisionId: string;
+        decisionDigest: string;
+    }>>;
+    revision: import("zod").ZodString;
+    permission: import("zod").ZodString;
+    permissionMode: import("zod").ZodEnum<["live", "mirrored", "static"]>;
+    providerScopes: import("zod").ZodReadonly<import("zod").ZodEffects<import("zod").ZodArray<import("zod").ZodString, "many">, string[], string[]>>;
+    providerEvidence: import("zod").ZodReadonly<import("zod").ZodDiscriminatedUnion<"kind", [import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"records_operation">;
+        operationId: import("zod").ZodString;
+    }, "strict", import("zod").ZodTypeAny, {
+        kind: "records_operation";
+        operationId: string;
+    }, {
+        kind: "records_operation";
+        operationId: string;
+    }>, import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"open_connector_action">;
+        connectorRef: import("zod").ZodString;
+        actionId: import("zod").ZodString;
+        connectorRunId: import("zod").ZodString;
+        actionCorrelationId: import("zod").ZodString;
+        auditPersisted: import("zod").ZodBoolean;
+    }, "strict", import("zod").ZodTypeAny, {
+        kind: "open_connector_action";
+        actionId: string;
+        connectorRef: string;
+        connectorRunId: string;
+        actionCorrelationId: string;
+        auditPersisted: boolean;
+    }, {
+        kind: "open_connector_action";
+        actionId: string;
+        connectorRef: string;
+        connectorRunId: string;
+        actionCorrelationId: string;
+        auditPersisted: boolean;
+    }>, import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"schift_search">;
+        indexRef: import("zod").ZodString;
+    }, "strict", import("zod").ZodTypeAny, {
+        kind: "schift_search";
+        indexRef: string;
+    }, {
+        kind: "schift_search";
+        indexRef: string;
+    }>, import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"web_search">;
+        provider: import("zod").ZodEnum<["customer", "schift"]>;
+    }, "strict", import("zod").ZodTypeAny, {
+        kind: "web_search";
+        provider: "customer" | "schift";
+    }, {
+        kind: "web_search";
+        provider: "customer" | "schift";
+    }>]>>;
+    freshness: import("zod").ZodOptional<import("zod").ZodString>;
+    payload: import("zod").ZodEffects<import("zod").ZodType<import("@schift-io/knowledge-scope/context-pack").JsonValue, import("zod").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>;
+    citation: import("zod").ZodOptional<import("zod").ZodReadonly<import("zod").ZodObject<{
+        uri: import("zod").ZodString;
+        label: import("zod").ZodOptional<import("zod").ZodString>;
+    }, "strict", import("zod").ZodTypeAny, {
+        uri: string;
+        label?: string | undefined;
+    }, {
+        uri: string;
+        label?: string | undefined;
+    }>>>;
+}, "operationId" | "srn" | "sourceId" | "sourceClass" | "providerRef" | "installationId" | "definitionDigest" | "mountRevision" | "scopeAuthority" | "effectiveScope" | "revision" | "permission" | "permissionMode" | "providerScopes" | "providerEvidence" | "payload" | "freshness" | "citation">, "strict", import("zod").ZodTypeAny, {
+    operationId: string;
+    srn: string;
+    sourceId: string & import("zod").BRAND<"SourceId">;
+    sourceClass: "document" | "records" | "activity_stream";
+    providerRef: string;
+    installationId: string & import("zod").BRAND<"InstallationId">;
+    definitionDigest: string & import("zod").BRAND<"Sha256Digest">;
+    mountRevision: number;
+    scopeAuthority: Readonly<{
+        tenant: string;
+        organizationId: string;
+    }>;
+    effectiveScope: Readonly<{
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }>;
+    revision: string;
+    permission: string;
+    permissionMode: "live" | "mirrored" | "static";
+    providerScopes: readonly string[];
+    providerEvidence: Readonly<{
+        kind: "records_operation";
+        operationId: string;
+    }> | Readonly<{
+        kind: "open_connector_action";
+        actionId: string;
+        connectorRef: string;
+        connectorRunId: string;
+        actionCorrelationId: string;
+        auditPersisted: boolean;
+    }> | Readonly<{
+        kind: "schift_search";
+        indexRef: string;
+    }> | Readonly<{
+        kind: "web_search";
+        provider: "customer" | "schift";
+    }>;
+    payload: import("@schift-io/knowledge-scope/context-pack").JsonValue;
+    freshness?: string | undefined;
+    citation?: Readonly<{
+        uri: string;
+        label?: string | undefined;
+    }> | undefined;
+}, {
+    operationId: string;
+    srn: string;
+    sourceId: string;
+    sourceClass: "document" | "records" | "activity_stream";
+    providerRef: string;
+    installationId: string;
+    definitionDigest: string;
+    mountRevision: number;
+    scopeAuthority: Readonly<{
+        tenant: string;
+        organizationId: string;
+    }>;
+    effectiveScope: Readonly<{
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }>;
+    revision: string;
+    permission: string;
+    permissionMode: "live" | "mirrored" | "static";
+    providerScopes: readonly string[];
+    providerEvidence: Readonly<{
+        kind: "records_operation";
+        operationId: string;
+    }> | Readonly<{
+        kind: "open_connector_action";
+        actionId: string;
+        connectorRef: string;
+        connectorRunId: string;
+        actionCorrelationId: string;
+        auditPersisted: boolean;
+    }> | Readonly<{
+        kind: "schift_search";
+        indexRef: string;
+    }> | Readonly<{
+        kind: "web_search";
+        provider: "customer" | "schift";
+    }>;
+    payload: import("@schift-io/knowledge-scope/context-pack").JsonValue;
+    freshness?: string | undefined;
+    citation?: Readonly<{
+        uri: string;
+        label?: string | undefined;
+    }> | undefined;
+}>>;
+export type AuthorizationSubject = typeof AuthorizationSubjectSchema._output;
+export declare const authorizationSubjectFromCandidate: (candidate: typeof CandidateEnvelopeSchema._output) => AuthorizationSubject;
+export type KnowledgeScopeAuthorizationOptions = Readonly<{
+    home?: string;
+    environment?: Readonly<Record<string, string | undefined>>;
+    faults?: AuthorizationFaults;
+}>;
+export interface AuthorizationFaults {
+    beforeInstall(): Promise<void>;
+}
+export declare class KnowledgeScopeAuthorization {
+    private readonly home;
+    private readonly keyPath;
+    private readonly faults;
+    constructor(options?: KnowledgeScopeAuthorizationOptions);
+    issue(subject: AuthorizationSubject): Promise<AuthorizationDecision>;
+    verify(subject: AuthorizationSubject, decision: AuthorizationDecision): Promise<boolean>;
+    private digest;
+    private readOrCreateKey;
+    private installKeyIfAbsent;
+}

package/dist/types/cli-options.d.ts

@@ -0,0 +1,6 @@
+export declare class CliUsageError extends Error {
+    readonly code: string;
+    readonly name = "CliUsageError";
+    constructor(code: string);
+}
+export declare const parseCliOptions: (command: string, args: readonly string[]) => readonly string[];

package/dist/types/cli.d.ts

@@ -0,0 +1,24 @@
+import { type KnowledgeScopeApplicationPort, type MountApplicationRequest, type ServedKnowledgeScopeApi } from "./api.js";
+import { type JsonValue } from "./json.js";
+import { type OnboardingEnvironment } from "./onboarding-config.js";
+export type PortableAuthoringPort = Readonly<{
+    validate: (directory: string) => Promise<JsonValue>;
+    lock: (directory: string) => Promise<JsonValue>;
+    mountPayload: (directory: string, bindingsPath: string) => Promise<MountApplicationRequest>;
+}>;
+export type CliDependencies = Readonly<{
+    environment?: OnboardingEnvironment;
+    authoring: PortableAuthoringPort;
+    embedded: KnowledgeScopeApplicationPort;
+    remote: (apiUrl: string) => KnowledgeScopeApplicationPort;
+    serve: (options: Readonly<{
+        host: string;
+        port: number;
+    }>) => Promise<Pick<ServedKnowledgeScopeApi, "host" | "port">>;
+    readJson: (path: string) => Promise<JsonValue>;
+}>;
+export type CliStreams = Readonly<{
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+}>;
+export declare const runKnowledgeScopeCli: (argv: readonly string[], dependencies: CliDependencies, streams: CliStreams) => Promise<number>;

package/dist/types/client-error.d.ts

@@ -0,0 +1,5 @@
+export declare class KnowledgeScopeClientError extends Error {
+    readonly code: "request_invalid" | "response_invalid" | "identity_mismatch" | "batch_unsupported";
+    readonly name = "KnowledgeScopeClientError";
+    constructor(code: "request_invalid" | "response_invalid" | "identity_mismatch" | "batch_unsupported");
+}

package/dist/types/client-validation.d.ts

@@ -0,0 +1,8 @@
+import type { CandidateEnvelope, ScopeRequirementReceipt } from "@schift-io/knowledge-scope/context-pack";
+import type { KnowledgeScopeInspection } from "./application.js";
+export declare const validateClientReceipt: (receipt: ScopeRequirementReceipt, inspection: KnowledgeScopeInspection) => void;
+export declare const validateClientCandidates: (input: Readonly<{
+    inspection: KnowledgeScopeInspection;
+    candidates: readonly CandidateEnvelope[];
+    receipt: ScopeRequirementReceipt;
+}>) => void;

package/dist/types/client.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { ScopeRequirementReceiptSchema } from "@schift-io/knowledge-scope/context-pack";
+import type { KnowledgeScopeApplicationPort, RunApplicationRequest, RunBatchApplicationRequest } from "./api.js";
+import type { KnowledgeScopeInspection, KnowledgeScopeRunResult } from "./application.js";
+export { KnowledgeScopeClientError } from "./client-error.js";
+export type KnowledgeScopeClient = Readonly<{
+    inspect: (installationId: string) => Promise<KnowledgeScopeInspection>;
+    run: (request: RunApplicationRequest) => Promise<KnowledgeScopeRunResult>;
+    runBatch: (request: RunBatchApplicationRequest) => Promise<KnowledgeScopeRunResult>;
+    admit: (request: Readonly<{
+        installationId: string;
+        candidates: readonly unknown[];
+    }>) => Promise<z.infer<typeof ScopeRequirementReceiptSchema>>;
+}>;
+/** The injected application owns authorization; this boundary checks wire integrity, not its HMAC key. */
+export declare const createKnowledgeScopeClient: (options: Readonly<{
+    application: KnowledgeScopeApplicationPort;
+}>) => KnowledgeScopeClient;

package/dist/types/context-pack/bounded-json.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+import type { JsonValue } from "./canonical.js";
+export declare const BoundedJsonValueSchema: z.ZodEffects<z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>, JsonValue, JsonValue>;

package/dist/types/context-pack/canonical.d.ts

@@ -0,0 +1,12 @@
+import type { Sha256Digest } from "./scalars.js";
+export type JsonPrimitive = boolean | number | string | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export declare class CanonicalJsonError extends Error {
+    readonly value: JsonValue;
+    constructor(message: string, value: JsonValue);
+}
+export declare const canonicalJson: (value: JsonValue) => string;
+export declare const digestCanonicalJson: (value: JsonValue) => Promise<Sha256Digest>;

package/dist/types/context-pack/index.d.ts

@@ -0,0 +1,73 @@
+export {
+  InstallationIdSchema,
+  PackIdSchema,
+  RevisionIdSchema,
+  SemanticVersionSchema,
+  Sha256DigestSchema,
+  SourceIdSchema,
+} from "./scalars.js";
+export type {
+  InstallationId,
+  PackId,
+  RevisionId,
+  SemanticVersion,
+  Sha256Digest,
+  SourceId,
+} from "./scalars.js";
+export { CanonicalJsonError, canonicalJson, digestCanonicalJson } from "./canonical.js";
+export type { JsonObject, JsonPrimitive, JsonValue } from "./canonical.js";
+export {
+  AuthorizationDecisionSchema,
+  CandidateEnvelopeSchema,
+  CitationSchema,
+  EffectiveScopeSchema,
+  KnowledgeScopeDefinitionSchema,
+  QueryCapabilitySchema,
+  QueryProviderSchema,
+  ScopeAuthoritySchema,
+} from "./knowledge-scope.js";
+export type {
+  AuthorizationDecision,
+  CandidateEnvelope,
+  KnowledgeScopeDefinition,
+  QueryCapability,
+  QueryProvider,
+} from "./knowledge-scope.js";
+export {
+  KnowledgeScopeMountSchema,
+  KnowledgeScopePackSchema,
+  materializeKnowledgeScopePack,
+} from "./knowledge-scope-mount.js";
+export type { KnowledgeScopeMount, KnowledgeScopePack } from "./knowledge-scope-mount.js";
+export {
+  KnowledgeScopeLockSchema,
+  buildKnowledgeScopeLock,
+  digestKnowledgeScopeDefinition,
+  verifyKnowledgeScopeLock,
+} from "./knowledge-scope-lock.js";
+export type { KnowledgeScopeLock } from "./knowledge-scope-lock.js";
+export {
+  CandidateAdmissionReceiptSchema,
+  CapabilityExecutionRequestSchema,
+  ProviderResultSchema,
+  ScopeRequirementReceiptSchema,
+} from "./knowledge-scope-execution.js";
+export type {
+  AdmissionDenialReason,
+  CandidateAdmissionReceipt,
+  CapabilityExecutionRequest,
+  ProviderResult,
+  ScopeRequirementReceipt,
+} from "./knowledge-scope-execution.js";
+export { CapabilityBatchOperationSchema, CapabilityBatchExecutionRequestSchema } from "./knowledge-scope-batch.js";
+export type { CapabilityBatchOperation, CapabilityBatchExecutionRequest } from "./knowledge-scope-batch.js";
+export {
+  ADMISSION_DENIAL_REASONS,
+  admitKnowledgeScopeCandidate,
+  admitKnowledgeScopeCandidates,
+} from "./knowledge-scope-admission.js";
+export type {
+  AdmissionResult,
+  KnowledgeScopeAdmissionInput,
+  KnowledgeScopeBatchAdmissionInput,
+} from "./knowledge-scope-admission.js";

package/dist/types/context-pack/knowledge-scope-admission.d.ts

@@ -0,0 +1,23 @@
+import type { CandidateAdmissionReceipt, ScopeRequirementReceipt } from "./knowledge-scope-execution.js";
+import type { KnowledgeScopeMount } from "./knowledge-scope-mount.js";
+import type { AuthorizationDecision, CandidateEnvelope, KnowledgeScopeDefinition } from "./knowledge-scope.js";
+export declare const ADMISSION_DENIAL_REASONS: readonly ["installation_not_mounted", "installation_id_mismatch", "definition_digest_mismatch", "mount_revision_mismatch", "authorization_decision_untrusted", "scope_authority_mismatch", "effective_scope_invalid", "source_binding_not_found", "source_class_mismatch", "provider_ref_mismatch", "operation_not_bound", "capability_not_found", "permission_mode_unsupported", "permission_mode_mismatch", "source_authority_not_allowed", "must_not_use", "context_policy_no_match", "provider_scopes_missing", "provider_evidence_mismatch", "connector_ref_mismatch", "connector_action_mismatch", "connector_run_missing", "connector_audit_missing", "citation_required", "freshness_required", "freshness_in_future", "source_stale"];
+export type KnowledgeScopeAdmissionInput = Readonly<{
+    definition: KnowledgeScopeDefinition;
+    mount: KnowledgeScopeMount;
+    candidate: CandidateEnvelope;
+    evaluatedAt: Date;
+    trustedAuthorizationDecision: AuthorizationDecision;
+}>;
+export type KnowledgeScopeBatchAdmissionInput = Readonly<{
+    definition: KnowledgeScopeDefinition;
+    mount: KnowledgeScopeMount;
+    candidates: readonly Readonly<{
+        candidate: CandidateEnvelope;
+        trustedAuthorizationDecision: AuthorizationDecision;
+    }>[];
+    evaluatedAt: Date;
+}>;
+export declare const admitKnowledgeScopeCandidate: (input: KnowledgeScopeAdmissionInput) => CandidateAdmissionReceipt;
+export declare const admitKnowledgeScopeCandidates: (input: KnowledgeScopeBatchAdmissionInput) => ScopeRequirementReceipt;
+export type AdmissionResult = CandidateAdmissionReceipt;

package/dist/types/context-pack/knowledge-scope-batch.d.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+export declare const CapabilityBatchOperationSchema: z.ZodReadonly<z.ZodObject<{
+    operationId: z.ZodString;
+    input: z.ZodEffects<z.ZodType<import("./canonical.js").JsonValue, z.ZodTypeDef, import("./canonical.js").JsonValue>, import("./canonical.js").JsonValue, import("./canonical.js").JsonValue>;
+    filters: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodType<import("./canonical.js").JsonValue, z.ZodTypeDef, import("./canonical.js").JsonValue>, import("./canonical.js").JsonValue, import("./canonical.js").JsonValue>>>>;
+}, "strict", z.ZodTypeAny, {
+    operationId: string;
+    input: import("./canonical.js").JsonValue;
+    filters?: Readonly<Record<string, import("./canonical.js").JsonValue>> | undefined;
+}, {
+    operationId: string;
+    input: import("./canonical.js").JsonValue;
+    filters?: Readonly<Record<string, import("./canonical.js").JsonValue>> | undefined;
+}>>;
+export declare const CapabilityBatchExecutionRequestSchema: z.ZodReadonly<z.ZodObject<{
+    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("./canonical.js").JsonValue, z.ZodTypeDef, import("./canonical.js").JsonValue>, import("./canonical.js").JsonValue, import("./canonical.js").JsonValue>;
+        filters: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodType<import("./canonical.js").JsonValue, z.ZodTypeDef, import("./canonical.js").JsonValue>, import("./canonical.js").JsonValue, import("./canonical.js").JsonValue>>>>;
+    }, "strict", z.ZodTypeAny, {
+        operationId: string;
+        input: import("./canonical.js").JsonValue;
+        filters?: Readonly<Record<string, import("./canonical.js").JsonValue>> | undefined;
+    }, {
+        operationId: string;
+        input: import("./canonical.js").JsonValue;
+        filters?: Readonly<Record<string, import("./canonical.js").JsonValue>> | undefined;
+    }>>, "many">, Readonly<{
+        operationId: string;
+        input: import("./canonical.js").JsonValue;
+        filters?: Readonly<Record<string, import("./canonical.js").JsonValue>> | undefined;
+    }>[], Readonly<{
+        operationId: string;
+        input: import("./canonical.js").JsonValue;
+        filters?: Readonly<Record<string, import("./canonical.js").JsonValue>> | undefined;
+    }>[]>>;
+}, "strict", z.ZodTypeAny, {
+    installationId: string & z.BRAND<"InstallationId">;
+    effectiveScope: Readonly<{
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }>;
+    operations: readonly Readonly<{
+        operationId: string;
+        input: import("./canonical.js").JsonValue;
+        filters?: Readonly<Record<string, import("./canonical.js").JsonValue>> | undefined;
+    }>[];
+    expectedRevision?: number | undefined;
+}, {
+    installationId: string;
+    effectiveScope: Readonly<{
+        tenant: string;
+        namespace?: string | undefined;
+        subject?: string | undefined;
+        session?: string | undefined;
+    }>;
+    operations: readonly Readonly<{
+        operationId: string;
+        input: import("./canonical.js").JsonValue;
+        filters?: Readonly<Record<string, import("./canonical.js").JsonValue>> | undefined;
+    }>[];
+    expectedRevision?: number | undefined;
+}>>;
+export type CapabilityBatchOperation = z.infer<typeof CapabilityBatchOperationSchema>;
+export type CapabilityBatchExecutionRequest = z.infer<typeof CapabilityBatchExecutionRequestSchema>;