@native-knowledge/knowledge-sdk 0.0.0-stage → 0.1.0-rc.1

package/dist/types/sdk/oauth.d.ts

@@ -0,0 +1,268 @@
+import { type SdkTransportOptions } from './transport.js';
+import { type MaterialStreamOptions } from './material-stream.js';
+import { type KnowledgeMcpProviderContractV12 } from '../serving-contracts/index.js';
+import { type KnowledgeMcpProviderContractV11, type MaterialOutboxWindow, type KnowledgeMcpProviderContractV3, type KnowledgeMcpProviderContractV6, type KnowledgeMcpProviderContractV7, type KnowledgeMcpProviderContractV8, type KnowledgeMcpProviderContractV9, type KnowledgeMcpProviderContractV10, type OAuthMaterialPageResponse, type OAuthMaterialRoutePageResponse, type OAuthMaterialPartitionsResponse, type OAuthMaterialPartitionPageResponse, type OAuthMaterialPresentationResponse, type ServingDecision } from '../serving-contracts/index.js';
+export interface KnowledgeOAuthFileClientOptions extends SdkTransportOptions {
+    baseUrl: string;
+    token: string;
+    projectRef: string;
+    fetchImpl?: typeof fetch;
+    allowInsecureHttp?: boolean;
+}
+export interface OAuthFileDescriptor {
+    contentHash: string;
+    mediaType: string;
+    byteLength: number;
+}
+export type OAuthFileResult = {
+    decision: ServingDecision;
+    descriptor: OAuthFileDescriptor;
+    content: Buffer;
+} | {
+    decision: ServingDecision;
+    error: string;
+};
+export declare class KnowledgeOAuthFileClient {
+    private readonly limits;
+    readonly projectRef: string;
+    private readonly root;
+    private readonly token;
+    private readonly fetchImpl;
+    private providerPromise;
+    private materialProviderPromise;
+    private agentMaterialProviderPromise;
+    private searchMaterialProviderPromise;
+    private routeMaterialProviderPromise;
+    private syncMaterialProviderPromise;
+    private capabilityProviderPromise;
+    private partitionMaterialProviderPromise;
+    constructor(options: KnowledgeOAuthFileClientOptions);
+    /** 公开 v3 元数据无需凭据；读取失败时清除缓存以便下次重试。 */
+    discover(): Promise<KnowledgeMcpProviderContractV3>;
+    discoverMaterials(): Promise<KnowledgeMcpProviderContractV6>;
+    /** Explicit v7 Agent discovery leaves the stable v6 HTTP file contract untouched. */
+    discoverAgentMaterials(): Promise<KnowledgeMcpProviderContractV7>;
+    /** v8 only describes the bounded descriptive index; result coverage is reported per query. */
+    discoverSearchMaterials(): Promise<KnowledgeMcpProviderContractV8>;
+    discoverRouteMaterials(): Promise<KnowledgeMcpProviderContractV9>;
+    discoverPartitionedMaterials(): Promise<KnowledgeMcpProviderContractV10>;
+    discoverMaterialSync(): Promise<KnowledgeMcpProviderContractV11>;
+    discoverMaterialCapabilities(): Promise<KnowledgeMcpProviderContractV12>;
+    private capabilityGet;
+    getMaterialCapabilities(ref: string): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        material: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                mediaType: string;
+                decision: {
+                    schemaVersion: 1;
+                    action: "ALLOW" | "DENY";
+                    reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    assessedAt: string;
+                };
+            };
+            materialAccess: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY";
+                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                assessedAt: string;
+            };
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("HEAD" | "GET")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            };
+        };
+        projectRef: string;
+    }>;
+    pageMaterialCapabilities(options?: {
+        limit?: number;
+        after?: string;
+        resourceType?: string;
+        sourceProjectKey?: string;
+        refPrefix?: string;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        items: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                mediaType: string;
+                decision: {
+                    schemaVersion: 1;
+                    action: "ALLOW" | "DENY";
+                    reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    assessedAt: string;
+                };
+            };
+            materialAccess: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY";
+                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                assessedAt: string;
+            };
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("HEAD" | "GET")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            };
+        }[];
+        nextAfter: string | null;
+        projectRef: string;
+    }>;
+    pageMaterialMedia(ref: string, options?: {
+        afterOrdinal?: number;
+        limit?: number;
+        documentRef?: string;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        ref: string;
+        sourceContentHash: string;
+        documentRef: string | null;
+        documentContentHash: string | null;
+        state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+        items: {
+            ordinal: number;
+            kind: "IMAGE" | "AUDIO" | "VIDEO";
+            sourceUrl: string;
+            canonicalUrl: string | null;
+            availability: "UNAVAILABLE" | "MIRRORED" | "REMOTE_ONLY";
+            mediaRef: string | null;
+            contentHash: string | null;
+            mediaType: string | null;
+            byteLength: number | null;
+            state: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "READY" | "DENIED" | "REMOTE_ONLY";
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("HEAD" | "GET")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            } | null;
+        }[];
+        nextAfterOrdinal: number | null;
+        projectRef: string;
+    }>;
+    getMaterialIndexStatus(options?: {
+        afterSourceKey?: string;
+        afterNodeId?: string;
+        sourceProjectKey?: string;
+        limit?: number;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        queryCoverage: "DESCRIPTIVE_METADATA_V1";
+        indexedFields: ["TITLE", "SUMMARY"];
+        bodyIndexed: false;
+        semanticIndexed: false;
+        items: {
+            sourceProjectKey: string;
+            nodeId: string;
+            directoryThroughSeq: number;
+            searchThroughSeq: number | null;
+            observedMaxSeq: number | null;
+            checkpointUpdatedAt: string | null;
+            state: "PARTIAL_BACKFILL" | "SYNCED_AS_OF_CHECKPOINT";
+        }[];
+        nextAfter: {
+            sourceProjectKey: string;
+            nodeId: string;
+        } | null;
+        projectRef: string;
+    }>;
+    openMaterialStream(ref: string, options?: MaterialStreamOptions): Promise<import("./material-stream.js").MaterialStreamResponse>;
+    getMaterialOutboxWindow(): Promise<MaterialOutboxWindow>;
+    private partitionGet;
+    pageMaterialPartitions(options?: {
+        afterRouteId?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialPartitionsResponse>;
+    pageMaterialPartition(partition: 'OWNER' | 'LEGACY', options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialPartitionPageResponse>;
+    searchMaterials(query: string, options?: {
+        afterId?: number;
+        limit?: number;
+        resourceType?: string;
+        sourceProjectKey?: string;
+    }): Promise<{
+        schemaVersion: 1;
+        projectRef: string;
+        queryCoverage: "DESCRIPTIVE_METADATA_V1";
+        order: "INDEX_ROWID_ASC";
+        indexState: "PARTIAL_BACKFILL" | "SYNCED_AS_OF_LAST_OBSERVATION";
+        configuredSourceCount: number;
+        items: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                mediaType: string;
+                decision: {
+                    schemaVersion: 1;
+                    action: "ALLOW" | "DENY";
+                    reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    assessedAt: string;
+                };
+            };
+            title: string;
+            summary: string;
+        }[];
+        nextAfterId: number | null;
+    }>;
+    pageMaterials(resourceType: 'all' | 'artifact' | 'evidence' | 'reference', options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialPageResponse>;
+    pageAllMaterials(options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialPageResponse>;
+    pageRouteMaterials(routeId: string, options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<OAuthMaterialRoutePageResponse>;
+    getMaterialPresentation(ref: string): Promise<OAuthMaterialPresentationResponse>;
+    getMaterial(ref: string, expected?: OAuthFileDescriptor): Promise<OAuthFileResult>;
+    private read;
+    getContent(ref: string, expected?: OAuthFileDescriptor): Promise<OAuthFileResult>;
+    /** 原始 Evidence 文件只代表已采集证据，不自动获得知识审核或 currentness 许可。 */
+    getEvidenceFile(ref: string, expected?: OAuthFileDescriptor): Promise<OAuthFileResult>;
+    getMedia(ref: string, expected?: OAuthFileDescriptor): Promise<OAuthFileResult>;
+}

package/dist/types/sdk/resource-integrity.d.ts

@@ -0,0 +1,21 @@
+import { type ResourceToolName } from '../contracts/index.js';
+export declare const contentHash: (bytes: Uint8Array | string) => string;
+export declare function transferBinding(response: Response): {
+    schemaVersion: 1;
+    context: {
+        type: "TENANT";
+        tenantId: string;
+        tenantRef: string;
+    } | {
+        type: "PROJECT";
+        tenantId: string;
+        projectKey: string;
+        projectRef: string;
+    };
+    policy: "LEGACY_PROJECT" | "TENANT_NATIVE" | "TENANT_PROJECT_SCOPE";
+    refHash: string;
+};
+export declare function resourceIntegrity(name: ResourceToolName, input: {
+    ref?: string | undefined;
+    projectRef?: string | undefined;
+}, raw: unknown): void;

package/dist/types/sdk/resource.d.ts

@@ -0,0 +1,88 @@
+/** Provider 16 客户端：Tenant 默认，Project 仅为显式收窄；正文复用既有有界流合同。 */
+import { resourceToolSchemas, resourceDataSchemas, type ResourceToolName, type MaterialContext, type MaterialAuthorityPolicy } from '../contracts/index.js';
+import { type SdkTransportOptions } from './transport.js';
+import { type MaterialStreamOptions } from './material-stream.js';
+type SharedOptions = SdkTransportOptions & {
+    baseUrl: string;
+    token: string;
+    fetchImpl?: typeof fetch;
+    allowInsecureHttp?: boolean;
+    expectedTenantId?: string;
+};
+export type KnowledgeResourceClientOptions = SharedOptions & ({
+    authentication: 'API_KEY';
+    tenantId: string;
+} | {
+    authentication?: 'OAUTH';
+    tenantId?: never;
+});
+export type ResourceToolInput<K extends ResourceToolName> = ReturnType<(typeof resourceToolSchemas)[K]['parse']>;
+export type ResourceToolResponse<K extends ResourceToolName> = {
+    schemaVersion: 2;
+    context: MaterialContext;
+    policy: MaterialAuthorityPolicy;
+    data: ReturnType<(typeof resourceDataSchemas)[K]['parse']>;
+};
+export declare class ResourceSdkError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly recovery: 'CAPTURE_WINDOW_AND_REBOOTSTRAP' | null;
+    constructor(code: string, status: number);
+}
+export declare class KnowledgeResourceClient {
+    private readonly options;
+    private readonly limits;
+    private readonly root;
+    private readonly basePath;
+    private readonly fetchImpl;
+    constructor(options: KnowledgeResourceClientOptions);
+    private url;
+    private request;
+    private json;
+    private context;
+    tool<K extends ResourceToolName>(name: K, raw: ResourceToolInput<K>): Promise<ResourceToolResponse<K>>;
+    contract(projectRef?: string): Promise<{
+        schemaVersion: 2;
+        context: {
+            type: "TENANT";
+            tenantId: string;
+            tenantRef: string;
+        } | {
+            type: "PROJECT";
+            tenantId: string;
+            projectKey: string;
+            projectRef: string;
+        };
+        policy: "LEGACY_PROJECT" | "TENANT_NATIVE" | "TENANT_PROJECT_SCOPE";
+        capabilities: ["TENANT_RESOURCE_V1", "TENANT_AUTHORITY_V1"];
+        callEndpoint: string;
+        fileEndpoint: string;
+        tools: string[];
+        inlineMaxBytes: 32768;
+        readBufferMaxBytes: 16777216;
+        fileMethods: ["GET", "HEAD", "POST"];
+        verificationChunkBytes: 65536;
+        requestMaxBytes: 131072;
+        resultMaxBytes: 524288;
+    }>;
+    list(input?: ResourceToolInput<'knowledge_resource_list'>): Promise<ResourceToolResponse<"knowledge_resource_list">>;
+    describe(ref: string, input?: {
+        projectRef?: string;
+    }): Promise<ResourceToolResponse<"knowledge_resource_describe">>;
+    read(ref: string, input?: {
+        projectRef?: string;
+    }): Promise<ResourceToolResponse<"knowledge_resource_read">>;
+    capabilities(ref: string, input?: {
+        projectRef?: string;
+    }): Promise<ResourceToolResponse<"knowledge_resource_capabilities">>;
+    search(query: string, input?: Omit<ResourceToolInput<'knowledge_resource_search'>, 'query'>): Promise<ResourceToolResponse<"knowledge_resource_search">>;
+    window(input?: ResourceToolInput<'knowledge_resource_window'>): Promise<ResourceToolResponse<"knowledge_resource_window">>;
+    changes(input?: ResourceToolInput<'knowledge_resource_changes'>): Promise<ResourceToolResponse<"knowledge_resource_changes">>;
+    counts(input?: ResourceToolInput<'knowledge_resource_counts'>): Promise<ResourceToolResponse<"knowledge_resource_counts">>;
+    indexStatus(input?: ResourceToolInput<'knowledge_resource_index_status'>): Promise<ResourceToolResponse<"knowledge_resource_index_status">>;
+    media(ref: string, input?: Omit<ResourceToolInput<'knowledge_resource_media'>, 'ref'>): Promise<ResourceToolResponse<"knowledge_resource_media">>;
+    stream(ref: string, options?: MaterialStreamOptions & {
+        projectRef?: string;
+    }): Promise<import("./material-stream.js").MaterialStreamResponse>;
+}
+export {};

package/dist/types/sdk/tenant-management.d.ts

@@ -0,0 +1,240 @@
+import { type SdkTransportOptions } from './transport.js';
+import { tenantManagementErrorSchema, type TenantManagementToolName, type TenantManagementToolInput, type TenantManagementToolResponse } from '../serving-contracts/index.js';
+import { type MaterialStreamOptions } from './material-stream.js';
+type Failure = ReturnType<typeof tenantManagementErrorSchema.parse>;
+export interface KnowledgeTenantManagementClientOptions extends SdkTransportOptions {
+    baseUrl: string;
+    token: string;
+    expectedTenantId: string;
+    allowInsecureHttp?: boolean;
+    fetchImpl?: typeof fetch;
+}
+export declare class TenantManagementSdkError<Phase extends string = NonNullable<Failure['completedPhase']>> extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly completedPhase: Phase | undefined;
+    readonly ref: string | undefined;
+    constructor(code: string, status: number, details?: {
+        completedPhase?: Phase | undefined;
+        ref?: string | undefined;
+    });
+}
+export declare class KnowledgeTenantManagementClient {
+    protected readonly options: KnowledgeTenantManagementClientOptions;
+    private readonly limits;
+    private readonly root;
+    private readonly path;
+    private readonly fetchImpl;
+    constructor(options: KnowledgeTenantManagementClientOptions);
+    protected protocolVersion(): 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26;
+    protected url(operation: 'provider' | 'call' | 'content', version?: 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26): import("url").URL;
+    protected request(url: URL, init?: RequestInit): Promise<Response>;
+    protected failure(raw: unknown, status: number): TenantManagementSdkError<string> | null;
+    protected json(response: Response): Promise<unknown>;
+    tool<K extends TenantManagementToolName>(name: K, raw: TenantManagementToolInput<K>, options?: {
+        signal?: AbortSignal;
+    }): Promise<TenantManagementToolResponse<K>>;
+    provider(): Promise<{
+        schemaVersion: 17;
+        provider: "knowledge-v2";
+        codeRevision: string;
+        authorityVersion: 2;
+        context: "TENANT_EXPLICIT_MANAGEMENT_V1";
+        managementConfigured: boolean;
+        resource: string;
+        issuer: string;
+        authorizationEndpoint: string;
+        tokenEndpoint: string;
+        revocationEndpoint: string;
+        mcpEndpoint: string;
+        callEndpoint: string;
+        contentEndpoint: string;
+        contentContextHeader: "x-knowledge-tenant-id";
+        legacyProviderEndpoint: string;
+        protocols: ("2026-07-28" | "2025-06-18")[];
+        tools: string[];
+        requestMaxBytes: 131072;
+        resultMaxBytes: 524288;
+        submissionMaxBytes: 65536;
+        inlineContentMaxBytes: 32768;
+        contentReadMaxBytes: 16777216;
+        collectionMode: "MANUAL_ONLY_OAUTH";
+        capabilities: ["TENANT_MANAGEMENT_V1", "TENANT_WORKFLOW_V1", "TENANT_CURRENTNESS_V2", "TENANT_SOURCE_V1"];
+    }>;
+    guide(): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "tenant_workflow_guide";
+        data: {
+            schemaVersion: 2;
+            tenantId: string;
+            authorityVersion: 2;
+            scopes: string[];
+            tools: {
+                name: string;
+                authorization: {
+                    selection: "NEXT_STATUS" | "WORKFLOW_ACTION" | "FIXED";
+                    scopeAlternatives: string[][];
+                };
+                inputSchema: import("zod").JSONType;
+                outputSchema: import("zod").JSONType;
+            }[];
+            rules: string[];
+            limits: {
+                requestMaxBytes: 131072;
+                resultMaxBytes: 524288;
+                submissionMaxBytes: 65536;
+            };
+        };
+    }>;
+    plan(ref: string): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "tenant_workflow_plan";
+        data: {
+            schemaVersion: 2;
+            tenantId: string;
+            ref: string;
+            contentHash: string;
+            resourceType: string;
+            kind: string;
+            version: number;
+            status: "RAW_EVIDENCE" | "REFERENCE_SNAPSHOT" | "REGISTERED_MATERIAL" | "READY_FOR_REVIEW" | "REWORK_REQUIRED" | "APPROVED" | "REJECTED" | "DRAFT" | "GENERATED" | "SUPERSEDED" | "RAW_MATERIAL";
+            productionPhase: "REGISTERED";
+            readiness: {
+                schemaVersion: 2;
+                profile: "HUMAN_ARTICLE_V1" | "KNOWLEDGE_CARD_V1";
+                ready: boolean;
+                reasons: ("ROLE_MISMATCH" | "TITLE_REQUIRED" | "SUMMARY_REQUIRED" | "TEXT_TOO_SHORT" | "STRUCTURE_TOO_THIN" | "CITATION_COVERAGE_REQUIRED" | "MEDIA_UNAVAILABLE" | "SOURCE_REQUIRED" | "SOURCE_MISMATCH")[];
+                metrics: {
+                    textCharacters: number;
+                    blockCount: number;
+                    textBlockCount: number;
+                    mediaBlockCount: number;
+                    sourceCount: number;
+                    mediaEvidenceCount: number;
+                    citationCount: number;
+                    citedBlockCount: number;
+                };
+            } | null;
+            currentness: {
+                observedAt: string | null;
+                lastAttemptAt: string | null;
+                assessedAt: string;
+                state: "UNKNOWN" | "DUE" | "CURRENT" | "STALE" | "BLOCKED";
+                action: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                reasonCode: "CURRENT_WITHIN_CADENCE" | "REFRESH_DUE" | "STALE_AFTER_THRESHOLD" | "SOURCE_BLOCKED" | "SOURCE_CONTENT_CHANGED" | "NO_SUCCESSFUL_OBSERVATION";
+                policy: {
+                    schemaVersion: 1;
+                    dueAfterSeconds: number;
+                    staleAfterSeconds: number;
+                    staleAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                    unknownAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                    blockedAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                };
+                lastSuccessAt: string | null;
+                dueAt: string | null;
+                staleAt: string | null;
+                ageSeconds: number | null;
+                basis: "RETAINED_SNAPSHOT";
+                basisRef: string;
+                declarationRef: string;
+                tenantId: string;
+                subjectRef: string;
+                resourceType: string;
+                contentHash: string;
+                schemaVersion: 2;
+                subjectKind: "MATERIAL";
+                sourceRevisionRef?: string | undefined;
+            } | null;
+            governedPolicyReady: boolean;
+            consumerReadDecision: {
+                action: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                reasonCodes: string[];
+                authority: "AUTHENTICATED_READER" | "LOCAL_PROFILE_SIMULATION";
+            } | null;
+            externalReady: boolean;
+            successorRef: string | null;
+            blockers: string[];
+            nextActions: {
+                id: string;
+                tool: string | null;
+                arguments: Record<string, import("zod").JSONType>;
+                requiredScopes: string[];
+                missingScopes: string[];
+                missingFields: string[];
+                canExecute: boolean;
+                automatic: boolean;
+                reasonCode: string;
+            }[];
+        };
+    }>;
+    read(ref: string): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "tenant_knowledge_read";
+        data: {
+            schemaVersion: 2;
+            tenantId: string;
+            ref: string;
+            decision: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE" | "STALE" | "ACCESS_DENIED" | "ARTIFACT_NOT_APPROVED" | "ARTIFACT_SUPERSEDED" | "SEMANTIC_REVIEW_REQUIRED" | "SEMANTIC_DENIED" | "SEMANTIC_ADMISSION_MISSING" | "CURRENTNESS_MISSING" | "CURRENTNESS_REVIEW_REQUIRED" | "CURRENTNESS_DENIED" | "VALIDITY_EXPIRED" | "CLAIM_REVIEW_REQUIRED" | "CLAIM_DENIED" | "CLAIM_NOT_EFFECTIVE" | "REFERENCE_NOT_COVERED" | "REFERENCE_NOT_EFFECTIVE" | "REFERENCE_VALIDITY_EXPIRED" | "REFERENCE_STALE" | "REFERENCE_UNAVAILABLE" | "REFERENCE_REVIEW_REQUIRED" | "REFERENCE_DENIED" | "GOVERNANCE_NOT_CONFIGURED")[];
+                assessedAt: string;
+            };
+            descriptor: {
+                contentHash: string;
+                mediaType: string;
+                byteLength: number;
+            } | null;
+            contentBase64: string | null;
+            truncated: boolean;
+            continuation: {
+                kind: "AUTHENTICATED_TENANT_GOVERNED_CONTENT";
+                ref: string;
+            } | null;
+        };
+    }>;
+    snapshot(ref: string): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "tenant_snapshot_status";
+        data: {
+            subjectRef: string;
+            state: "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "READY" | "NOT_AVAILABLE" | "NOT_DECLARED" | "PROJECTION_PENDING";
+            assessment: {
+                observedAt: string | null;
+                lastAttemptAt: string | null;
+                assessedAt: string;
+                state: "UNKNOWN" | "DUE" | "CURRENT" | "STALE" | "BLOCKED";
+                action: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                reasonCode: "CURRENT_WITHIN_CADENCE" | "REFRESH_DUE" | "STALE_AFTER_THRESHOLD" | "SOURCE_BLOCKED" | "SOURCE_CONTENT_CHANGED" | "NO_SUCCESSFUL_OBSERVATION";
+                policy: {
+                    schemaVersion: 1;
+                    dueAfterSeconds: number;
+                    staleAfterSeconds: number;
+                    staleAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                    unknownAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                    blockedAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                };
+                lastSuccessAt: string | null;
+                dueAt: string | null;
+                staleAt: string | null;
+                ageSeconds: number | null;
+                basis: "RETAINED_SNAPSHOT";
+                basisRef: string;
+                declarationRef: string;
+                tenantId: string;
+                subjectRef: string;
+                resourceType: string;
+                contentHash: string;
+                schemaVersion: 2;
+                subjectKind: "MATERIAL";
+                sourceRevisionRef?: string | undefined;
+            } | null;
+        };
+    }>;
+    stream(ref: string, options?: MaterialStreamOptions): Promise<import("./material-stream.js").MaterialStreamResponse>;
+}
+export {};

package/dist/types/sdk/tenant-project.d.ts

@@ -0,0 +1,57 @@
+import { type TenantProjectToolName, type TenantProjectToolInput, type TenantProjectToolResponse } from '../serving-contracts/index.js';
+import { KnowledgeTenantWorkspaceClient } from './tenant-workspace.js';
+import { TenantManagementSdkError } from './tenant-management.js';
+import { type MaterialStreamOptions } from './material-stream.js';
+export declare class KnowledgeTenantProjectClient extends KnowledgeTenantWorkspaceClient {
+    protected protocolVersion(): 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25;
+    protected failure(raw: unknown, status: number): TenantManagementSdkError<string> | null;
+    projectTool<K extends TenantProjectToolName>(name: K, raw: TenantProjectToolInput<K>, options?: {
+        signal?: AbortSignal;
+    }): Promise<TenantProjectToolResponse<K>>;
+    projectProvider(): Promise<{
+        provider: "knowledge-v2";
+        codeRevision: string;
+        authorityVersion: 2;
+        context: "TENANT_EXPLICIT_MANAGEMENT_V1";
+        managementConfigured: boolean;
+        resource: string;
+        issuer: string;
+        authorizationEndpoint: string;
+        tokenEndpoint: string;
+        revocationEndpoint: string;
+        mcpEndpoint: string;
+        callEndpoint: string;
+        contentEndpoint: string;
+        contentContextHeader: "x-knowledge-tenant-id";
+        legacyProviderEndpoint: string;
+        protocols: ("2026-07-28" | "2025-06-18")[];
+        requestMaxBytes: 131072;
+        resultMaxBytes: 524288;
+        submissionMaxBytes: 65536;
+        inlineContentMaxBytes: 32768;
+        contentReadMaxBytes: 16777216;
+        collectionMode: "MANUAL_ONLY_OAUTH";
+        schemaVersion: 19;
+        projectContentEndpoint: string;
+        projectContentPolicyHeader: "x-knowledge-authority-policy";
+        projectContentProjectHeader: "x-knowledge-project-key";
+        projectControlIdentitySchemaVersion: 19;
+        tools: string[];
+        capabilities: ["TENANT_MANAGEMENT_V1", "TENANT_WORKFLOW_V1", "TENANT_CURRENTNESS_V2", "TENANT_SOURCE_V1", "TENANT_WORKSPACE_METADATA_V1", "TENANT_PROJECT_CONTEXT_V1"];
+    }>;
+    projectStream(projectKey: string, ref: string, options?: MaterialStreamOptions): Promise<{
+        context: {
+            tenantId: string;
+            projectKey: string;
+            policy: "TENANT_PROJECT_SCOPE";
+        };
+        status: 200 | 206;
+        contentClass: string;
+        contentHash: string;
+        mediaType: string;
+        contentLength: number;
+        contentRange: string | null;
+        body: ReadableStream<Uint8Array> | null;
+        verification: "SERVER_VERIFIED_BEFORE_HEADERS";
+    }>;
+}