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

package/dist/internal/serving-contracts/mcp.js

@@ -0,0 +1,140 @@
+import { materialCapabilityResponseSchema, materialMediaCapabilityPageSchema } from './material-capabilities.js';
+import { materialIndexStatusSchema } from './material-index-status.js';
+import { materialResourceTypeSchema } from '../contracts/index.js';
+import { z } from 'zod';
+import { projectKeySchema, schemaVersionSchema, stableUriSchema, sha256Schema } from '../contracts/index.js';
+import { consumerCurrentnessResponseSchema, consumerEvidencePageResponseSchema, consumerProjectRefSchema, consumerReadResponseSchema, consumerReferenceLookupResponseSchema, consumerSearchResponseSchema } from './consumer.js';
+import { materialOutboxWindowSchema, materialRoutePartitionSchema, servingMaterialDirectoryItemSchema } from './http.js';
+export const knowledgeMcpProtocolVersion = '2026-07-28';
+export const knowledgeMcpToolNameSchema = z.enum(['knowledge_search', 'knowledge_read', 'knowledge_currentness', 'knowledge_reference_lookup']);
+export const knowledgeMcpToolNameV2Schema = z.enum(['knowledge_search', 'knowledge_read', 'knowledge_currentness', 'knowledge_reference_lookup', 'knowledge_list_evidence']);
+export const knowledgeMcpScopeSchema = z.enum(['knowledge.search', 'knowledge.read', 'knowledge.currentness']);
+export const knowledgeMcpProviderContractSchema = z.object({
+    schemaVersion: schemaVersionSchema, provider: z.literal('knowledge-v2'), revision: z.string().trim().min(7).max(64), protocolVersion: z.literal(knowledgeMcpProtocolVersion),
+    validationStatus: z.enum(['NOT_VERIFIED', 'RUNTIME_CONFIGURED']), externalReachability: z.literal('NOT_VERIFIED'), endpoint: z.string().url().nullable(), mediaEndpoint: z.string().url().nullable(), resource: z.string().url().nullable(), protectedResourceMetadataUrl: z.string().url().nullable(), authorizationServerMetadataUrl: z.string().url().nullable(), authorizationEndpoint: z.string().url().nullable(), tokenEndpoint: z.string().url().nullable(), revocationEndpoint: z.string().url().nullable(),
+    authorizationMode: z.literal('OAUTH_2_1_AUTHORIZATION_CODE_PKCE_S256_USER_DELEGATED'), clientRegistration: z.literal('PRE_REGISTERED'), clientId: z.null(), authorizationMapping: z.object({ oauthResourceParameter: z.literal('resource'), externalTenantParameter: z.literal('external_tenant_id'), projectRefParameter: z.literal('project_ref'), externalSystemSource: z.literal('client_id'), grantBinding: z.literal('RESOURCE_EXTERNAL_TENANT_PROJECT_REF_SCOPES') }).strict(), searchCoverage: z.enum(['AUTHORIZED_METADATA_V1', 'AUTHORIZED_PRESENTATION_V1']),
+    scopes: z.array(knowledgeMcpScopeSchema).length(3), tools: z.array(z.object({ name: knowledgeMcpToolNameSchema, requiredScope: knowledgeMcpScopeSchema, inputSchema: z.json() }).strict()).length(4),
+}).strict();
+/** 版本化元数据只声明实际启用的协议；保留严格 v1，避免旧消费者误认新增生命周期。 */
+const providerV2BaseSchema = knowledgeMcpProviderContractSchema.omit({ schemaVersion: true, protocolVersion: true }).extend({
+    schemaVersion: z.literal(2), defaultProtocolVersion: z.literal(knowledgeMcpProtocolVersion),
+    protocols: z.array(z.discriminatedUnion('version', [
+        z.object({ version: z.literal('2026-07-28'), lifecycle: z.literal('STATELESS_DISCOVERY'), transport: z.literal('STREAMABLE_HTTP') }).strict(),
+        z.object({ version: z.literal('2025-06-18'), lifecycle: z.literal('INITIALIZE'), transport: z.literal('STREAMABLE_HTTP') }).strict(),
+    ])).min(1).max(2),
+}).strict();
+export const knowledgeMcpProviderContractV2Schema = providerV2BaseSchema.superRefine((value, ctx) => {
+    const versions = value.protocols.map(p => p.version);
+    if (new Set(versions).size !== versions.length || !versions.includes(value.defaultProtocolVersion))
+        ctx.addIssue({ code: 'custom', message: 'Protocols must be unique and include the default version' });
+});
+/** v3 区分原始 Evidence 文件和受治理正文端点，旧 provider 合同仍保持原样。 */
+export const knowledgeMcpProviderContractV3Schema = providerV2BaseSchema.omit({ schemaVersion: true, tools: true }).extend({
+    schemaVersion: z.literal(3), contentEndpoint: z.string().url().nullable(), evidenceFileEndpoint: z.string().url().nullable(),
+    tools: z.array(z.object({ name: knowledgeMcpToolNameV2Schema, requiredScope: knowledgeMcpScopeSchema, inputSchema: z.json() }).strict()).length(5),
+}).strict().superRefine((value, ctx) => {
+    const versions = value.protocols.map(p => p.version);
+    if (new Set(versions).size !== versions.length || !versions.includes(value.defaultProtocolVersion))
+        ctx.addIssue({ code: 'custom', message: 'Protocols must be unique and include the default version' });
+});
+// 五个工具的成功结构直接取通用消费 DTO；失败只返回错误码，不泄露被拒绝正文。
+const toolErrorOutput = { type: 'object', properties: { errorCode: { type: 'string' } }, required: ['errorCode'], additionalProperties: false };
+const toolOutput = (success) => ({ type: 'object', oneOf: [z.toJSONSchema(success, { target: 'draft-07' }), toolErrorOutput] });
+export const knowledgeMaterialListInputSchema = z.object({ projectRef: consumerProjectRefSchema, after: stableUriSchema.optional(), limit: z.number().int().min(1).max(20).optional(), resourceType: materialResourceTypeSchema.optional(), sourceProjectKey: projectKeySchema.optional(), refPrefix: z.string().regex(/^[a-z][a-z0-9+.-]*:\/\/[!-~]*$/i).max(256).optional() }).strict();
+export const knowledgeMaterialRefInputSchema = z.object({ projectRef: consumerProjectRefSchema, ref: stableUriSchema }).strict();
+export const knowledgeMaterialWindowInputSchema = z.object({ projectRef: consumerProjectRefSchema }).strict();
+export const knowledgeMaterialWindowResponseSchema = materialOutboxWindowSchema.safeExtend({ projectRef: consumerProjectRefSchema });
+export const knowledgeMaterialChangesInputSchema = z.object({ projectRef: consumerProjectRefSchema, afterSeq: z.number().int().nonnegative().safe().optional(), limit: z.number().int().min(1).max(20).optional() }).strict();
+export const knowledgeMaterialSearchInputSchema = z.object({ projectRef: consumerProjectRefSchema, query: z.string().min(2).max(200), afterId: z.number().int().nonnegative().safe().optional(), limit: z.number().int().min(1).max(20).optional(), resourceType: materialResourceTypeSchema.optional(), sourceProjectKey: projectKeySchema.optional() }).strict();
+export const knowledgeMaterialPartitionsInputSchema = z.object({ projectRef: consumerProjectRefSchema, afterRouteId: z.string().regex(/^[a-f0-9]{64}$/).optional(), limit: z.number().int().min(1).max(20).optional() }).strict();
+export const knowledgeMaterialPartitionPageInputSchema = z.object({ projectRef: consumerProjectRefSchema, partition: z.enum(['OWNER', 'LEGACY']), after: stableUriSchema.optional(), limit: z.number().int().min(1).max(20).optional() }).strict();
+export const knowledgeMaterialRoutePageInputSchema = z.object({ projectRef: consumerProjectRefSchema, routeId: z.string().regex(/^[a-f0-9]{64}$/), after: stableUriSchema.optional(), limit: z.number().int().min(1).max(20).optional() }).strict();
+export const knowledgeMaterialMediaInputSchema = knowledgeMaterialRefInputSchema.extend({ afterOrdinal: z.number().int().min(-1).safe().optional(), limit: z.number().int().min(1).max(20).optional(), documentRef: stableUriSchema.optional() }).strict();
+export const knowledgeMaterialIndexStatusInputSchema = z.object({ projectRef: consumerProjectRefSchema, afterSourceKey: projectKeySchema.optional(), afterNodeId: z.string().min(1).max(128).optional(), sourceProjectKey: projectKeySchema.optional(), limit: z.number().int().min(1).max(20).optional() }).strict();
+export const knowledgeMaterialCapabilitiesResponseSchema = materialCapabilityResponseSchema.omit({ projectKey: true }).extend({ projectRef: consumerProjectRefSchema, downloadUrl: z.string().url() }).strict();
+export const knowledgeMaterialMediaResponseSchema = materialMediaCapabilityPageSchema.omit({ projectKey: true }).extend({ projectRef: consumerProjectRefSchema }).strict();
+export const knowledgeMaterialIndexStatusResponseSchema = materialIndexStatusSchema.omit({ projectKey: true }).extend({ projectRef: consumerProjectRefSchema }).strict();
+export const knowledgeMaterialToolInputSchemas = {
+    knowledge_material_capabilities: z.toJSONSchema(knowledgeMaterialRefInputSchema, { target: 'draft-07' }),
+    knowledge_material_media: z.toJSONSchema(knowledgeMaterialMediaInputSchema, { target: 'draft-07' }),
+    knowledge_material_index_status: z.toJSONSchema(knowledgeMaterialIndexStatusInputSchema, { target: 'draft-07' }),
+    knowledge_material_window: z.toJSONSchema(knowledgeMaterialWindowInputSchema, { target: 'draft-07' }),
+    knowledge_material_list: z.toJSONSchema(knowledgeMaterialListInputSchema, { target: 'draft-07' }),
+    knowledge_material_describe: z.toJSONSchema(knowledgeMaterialRefInputSchema, { target: 'draft-07' }),
+    knowledge_material_read: z.toJSONSchema(knowledgeMaterialRefInputSchema, { target: 'draft-07' }),
+    knowledge_material_changes: z.toJSONSchema(knowledgeMaterialChangesInputSchema, { target: 'draft-07' }),
+    knowledge_material_search: z.toJSONSchema(knowledgeMaterialSearchInputSchema, { target: 'draft-07' }),
+    knowledge_material_partitions: z.toJSONSchema(knowledgeMaterialPartitionsInputSchema, { target: 'draft-07' }),
+    knowledge_material_partition_page: z.toJSONSchema(knowledgeMaterialPartitionPageInputSchema, { target: 'draft-07' }),
+    knowledge_material_route_page: z.toJSONSchema(knowledgeMaterialRoutePageInputSchema, { target: 'draft-07' }),
+};
+export const knowledgeMaterialListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, contentClass: z.literal('MATERIAL_DIRECTORY'), queryCoverage: z.literal('INDEXED_REF_SOURCE_TYPE_V1'), order: z.literal('REF_ASC'), items: z.array(servingMaterialDirectoryItemSchema).max(20), nextAfter: stableUriSchema.nullable() }).strict();
+export const knowledgeMaterialDescribeResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, contentClass: z.literal('MATERIAL_DESCRIPTOR'), item: servingMaterialDirectoryItemSchema, metadataByteLength: z.number().int().nonnegative().nullable(), downloadUrl: z.string().url() }).strict();
+export const knowledgeMaterialReadResponseSchema = knowledgeMaterialDescribeResponseSchema.omit({ contentClass: true }).extend({ contentClass: z.literal('MATERIAL_READ'), inlineComplete: z.boolean(), byteVerification: z.enum(['VERIFIED', 'ON_DOWNLOAD']), contentBase64: z.string().nullable(), fileDescriptor: z.object({ contentHash: sha256Schema, mediaType: z.string().min(1).max(256), byteLength: z.number().int().nonnegative() }).strict().nullable() }).strict();
+export const knowledgeMaterialChangesResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, tenantId: z.string().min(1), items: z.array(z.object({ seq: z.number().int().positive(), eventType: z.enum(['MATERIAL_REGISTERED', 'MATERIAL_LINEAGE_CHANGED', 'ROUTE_CHANGED', 'PROJECT_SCOPE_CHANGED']), artifactRef: stableUriSchema.nullable(), contentHash: sha256Schema.nullable(), routeId: z.string().nullable(), createdAt: z.string().datetime({ offset: true }) }).strict()).max(20), nextAfter: z.number().int().positive().nullable() }).strict();
+export const knowledgeMaterialSearchResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, queryCoverage: z.literal('DESCRIPTIVE_METADATA_V1'), order: z.literal('INDEX_ROWID_ASC'), indexState: z.enum(['PARTIAL_BACKFILL', 'SYNCED_AS_OF_LAST_OBSERVATION']), configuredSourceCount: z.number().int().nonnegative(), items: z.array(z.object({ item: servingMaterialDirectoryItemSchema, title: z.string().max(512), summary: z.string().max(1024) }).strict()).max(20), nextAfterId: z.number().int().positive().nullable() }).strict();
+export const oauthMaterialRoutePageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, routeId: z.string().regex(/^[a-f0-9]{64}$/), contentClass: z.literal('MATERIAL_DIRECTORY'), routeState: z.enum(['ACTIVE', 'REVOKED', 'UNBOUND']), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const oauthMaterialPartitionsResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, coverage: z.literal('OWNER_LEGACY_AND_ACTIVE_ROUTES'), items: z.array(materialRoutePartitionSchema).max(100), nextAfterRouteId: z.string().regex(/^[a-f0-9]{64}$/).nullable() }).strict();
+export const oauthMaterialPartitionPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, contentClass: z.literal('MATERIAL_DIRECTORY'), partition: z.enum(['OWNER', 'LEGACY']), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const knowledgeMaterialPartitionsResponseSchema = oauthMaterialPartitionsResponseSchema.extend({ items: z.array(materialRoutePartitionSchema).max(20) }).omit({ projectKey: true }).strict();
+export const knowledgeMaterialPartitionPageResponseSchema = oauthMaterialPartitionPageResponseSchema.extend({ items: z.array(servingMaterialDirectoryItemSchema).max(20) }).omit({ projectKey: true }).strict();
+export const knowledgeMaterialRoutePageResponseSchema = oauthMaterialRoutePageResponseSchema.extend({ items: z.array(servingMaterialDirectoryItemSchema).max(20) }).omit({ projectKey: true }).strict();
+export const knowledgeMcpToolOutputSchemas = {
+    knowledge_material_capabilities: toolOutput(knowledgeMaterialCapabilitiesResponseSchema),
+    knowledge_material_media: toolOutput(knowledgeMaterialMediaResponseSchema),
+    knowledge_material_index_status: toolOutput(knowledgeMaterialIndexStatusResponseSchema),
+    knowledge_material_window: toolOutput(knowledgeMaterialWindowResponseSchema),
+    knowledge_search: toolOutput(consumerSearchResponseSchema),
+    knowledge_read: toolOutput(consumerReadResponseSchema),
+    knowledge_list_evidence: toolOutput(consumerEvidencePageResponseSchema),
+    knowledge_currentness: toolOutput(consumerCurrentnessResponseSchema),
+    knowledge_reference_lookup: toolOutput(consumerReferenceLookupResponseSchema),
+    knowledge_material_list: toolOutput(knowledgeMaterialListResponseSchema),
+    knowledge_material_describe: toolOutput(knowledgeMaterialDescribeResponseSchema),
+    knowledge_material_read: toolOutput(knowledgeMaterialReadResponseSchema),
+    knowledge_material_changes: toolOutput(knowledgeMaterialChangesResponseSchema),
+    knowledge_material_search: toolOutput(knowledgeMaterialSearchResponseSchema),
+    knowledge_material_partitions: toolOutput(knowledgeMaterialPartitionsResponseSchema),
+    knowledge_material_partition_page: toolOutput(knowledgeMaterialPartitionPageResponseSchema),
+    knowledge_material_route_page: toolOutput(knowledgeMaterialRoutePageResponseSchema),
+};
+/** v4 在独立发现版本中公布工具输出合同，v1 至 v3 的严格结构不变。 */
+export const knowledgeMcpProviderContractV4Schema = providerV2BaseSchema.omit({ schemaVersion: true, tools: true }).extend({
+    schemaVersion: z.literal(4), contentEndpoint: z.string().url().nullable(), evidenceFileEndpoint: z.string().url().nullable(),
+    tools: z.array(z.object({ name: knowledgeMcpToolNameV2Schema, requiredScope: knowledgeMcpScopeSchema, inputSchema: z.json(), outputSchema: z.json() }).strict()).length(5),
+}).strict().superRefine((value, ctx) => {
+    const versions = value.protocols.map(p => p.version);
+    if (new Set(versions).size !== versions.length || !versions.includes(value.defaultProtocolVersion))
+        ctx.addIssue({ code: 'custom', message: 'Protocols must be unique and include the default version' });
+});
+/** v5 单独声明受治理写入工具；旧版本继续只描述只读消费合同。 */
+export const knowledgeMcpProviderContractV5Schema = providerV2BaseSchema.omit({ schemaVersion: true, tools: true, scopes: true }).extend({
+    schemaVersion: z.literal(5), contentEndpoint: z.string().url().nullable(), evidenceFileEndpoint: z.string().url().nullable(), managementMode: z.literal('EXPLICIT_CLIENT_PROJECT_SCOPE'), managementEnabled: z.boolean(),
+    scopes: z.array(z.enum(['knowledge.search', 'knowledge.read', 'knowledge.currentness', 'knowledge.compose', 'knowledge.review', 'knowledge.approve'])).min(3).max(6),
+    tools: z.array(z.object({ name: z.enum(['knowledge_search', 'knowledge_read', 'knowledge_currentness', 'knowledge_reference_lookup', 'knowledge_list_evidence', 'knowledge_compose', 'knowledge_submit_review', 'knowledge_review', 'knowledge_finalize_review']), requiredScope: z.enum(['knowledge.search', 'knowledge.read', 'knowledge.currentness', 'knowledge.compose', 'knowledge.review', 'knowledge.approve']), inputSchema: z.json(), outputSchema: z.json() }).strict()).min(5).max(9),
+}).strict();
+/** v6 advertises tenant-scoped, immutable material discovery and byte reads. */
+export const knowledgeMcpProviderContractV6Schema = knowledgeMcpProviderContractV5Schema.omit({ schemaVersion: true }).extend({ schemaVersion: z.literal(6), materialPageEndpoint: z.string().url(), materialEndpoint: z.string().url(), materialPresentationEndpoint: z.string().url() }).strict();
+/** v7 publishes independent raw-material consent without changing older provider contracts. */
+export const knowledgeMcpProviderContractV7Schema = knowledgeMcpProviderContractV6Schema.omit({ schemaVersion: true, scopes: true, tools: true }).extend({
+    schemaVersion: z.literal(7), materialReadMode: z.literal('OAUTH_SCOPE_AND_CLIENT_PROJECT_BINDING'),
+    scopes: z.array(z.enum(['knowledge.search', 'knowledge.read', 'knowledge.currentness', 'knowledge.material.read', 'knowledge.compose', 'knowledge.review', 'knowledge.approve', 'knowledge.material.route'])).min(4).max(8),
+    tools: z.array(z.object({ name: z.enum(['knowledge_search', 'knowledge_read', 'knowledge_currentness', 'knowledge_reference_lookup', 'knowledge_list_evidence', 'knowledge_material_list', 'knowledge_material_describe', 'knowledge_material_read', 'knowledge_material_changes', 'knowledge_compose', 'knowledge_submit_review', 'knowledge_review', 'knowledge_finalize_review', 'knowledge_material_route']), requiredScope: z.enum(['knowledge.search', 'knowledge.read', 'knowledge.currentness', 'knowledge.material.read', 'knowledge.compose', 'knowledge.review', 'knowledge.approve', 'knowledge.material.route']), inputSchema: z.json(), outputSchema: z.json() }).strict()).min(9).max(14),
+}).strict();
+/** v8 adds descriptive metadata search with an explicit index-coverage state. */
+export const knowledgeMcpProviderContractV8Schema = knowledgeMcpProviderContractV7Schema.omit({ schemaVersion: true, tools: true }).extend({
+    schemaVersion: z.literal(8), materialSearchMode: z.literal('INDEXED_DESCRIPTIVE_METADATA'), materialSearchEndpoint: z.string().url(),
+    tools: z.array(z.object({ name: z.enum(['knowledge_search', 'knowledge_read', 'knowledge_currentness', 'knowledge_reference_lookup', 'knowledge_list_evidence', 'knowledge_material_list', 'knowledge_material_describe', 'knowledge_material_read', 'knowledge_material_changes', 'knowledge_material_search', 'knowledge_compose', 'knowledge_submit_review', 'knowledge_review', 'knowledge_finalize_review', 'knowledge_material_route']), requiredScope: z.enum(['knowledge.search', 'knowledge.read', 'knowledge.currentness', 'knowledge.material.read', 'knowledge.compose', 'knowledge.review', 'knowledge.approve', 'knowledge.material.route']), inputSchema: z.json(), outputSchema: z.json() }).strict()).min(10).max(15),
+}).strict();
+/** v9 advertises bounded per-route replay for null-ref change events. */
+export const knowledgeMcpProviderContractV9Schema = knowledgeMcpProviderContractV8Schema.omit({ schemaVersion: true }).extend({ schemaVersion: z.literal(9), materialRoutePageEndpoint: z.string().url() }).strict();
+/** v10 publishes route-count-independent partitioned material discovery. */
+export const knowledgeMcpProviderContractV10Schema = knowledgeMcpProviderContractV9Schema.omit({ schemaVersion: true, tools: true }).extend({ schemaVersion: z.literal(10), materialPartitionsEndpoint: z.string().url(), materialPartitionPageEndpoint: z.string().url(), tools: z.array(z.object({ name: z.enum(['knowledge_search', 'knowledge_read', 'knowledge_currentness', 'knowledge_reference_lookup', 'knowledge_list_evidence', 'knowledge_material_list', 'knowledge_material_describe', 'knowledge_material_read', 'knowledge_material_changes', 'knowledge_material_search', 'knowledge_material_partitions', 'knowledge_material_partition_page', 'knowledge_material_route_page', 'knowledge_compose', 'knowledge_submit_review', 'knowledge_review', 'knowledge_finalize_review', 'knowledge_material_route']), requiredScope: z.enum(['knowledge.search', 'knowledge.read', 'knowledge.currentness', 'knowledge.material.read', 'knowledge.compose', 'knowledge.review', 'knowledge.approve', 'knowledge.material.route']), inputSchema: z.json(), outputSchema: z.json() }).strict()).min(13).max(18) }).strict();
+/** v11 adds an Agent-native checkpoint for initial synchronization and retention-gap recovery. */
+export const knowledgeMcpProviderContractV11Schema = knowledgeMcpProviderContractV10Schema.omit({ schemaVersion: true, tools: true }).extend({ schemaVersion: z.literal(11), materialOutboxWindowEndpoint: z.string().url(), tools: z.array(knowledgeMcpProviderContractV10Schema.shape.tools.element.extend({ name: knowledgeMcpProviderContractV10Schema.shape.tools.element.shape.name.or(z.literal('knowledge_material_window')) })).min(14).max(19) }).strict();
+/** v12 exposes representation capabilities independently of raw authorization and search coverage. */
+export const knowledgeMcpProviderContractV12Schema = knowledgeMcpProviderContractV11Schema.omit({ schemaVersion: true, tools: true }).extend({ schemaVersion: z.literal(12), materialCapabilitySchemaVersion: z.literal(2), materialCapabilitiesEndpoint: z.string().url(), materialCapabilityPageEndpoint: z.string().url(), materialMediaPageEndpoint: z.string().url(), materialIndexStatusEndpoint: z.string().url(), tools: z.array(knowledgeMcpProviderContractV11Schema.shape.tools.element.extend({ name: knowledgeMcpProviderContractV11Schema.shape.tools.element.shape.name.or(z.enum(['knowledge_material_capabilities', 'knowledge_material_media', 'knowledge_material_index_status'])) })).min(17).max(22) }).strict();
+/** v13 adds explicit material production; older versions keep their scope and tool enums. */
+export const knowledgeMcpProviderContractV13Schema = knowledgeMcpProviderContractV12Schema.omit({ schemaVersion: true, tools: true, scopes: true }).extend({ schemaVersion: z.literal(13), scopes: z.array(knowledgeMcpProviderContractV12Schema.shape.scopes.element.or(z.literal('knowledge.material.write'))).min(4).max(9), tools: z.array(knowledgeMcpProviderContractV12Schema.shape.tools.element.extend({ name: knowledgeMcpProviderContractV12Schema.shape.tools.element.shape.name.or(z.literal('knowledge_material_register')), requiredScope: knowledgeMcpProviderContractV12Schema.shape.tools.element.shape.requiredScope.or(z.literal('knowledge.material.write')) })).min(17).max(23), materialRegistration: z.object({ maxInlineBytes: z.literal(65536), retry: z.literal('EXACT_IMMUTABLE_REF'), phases: z.tuple([z.literal('PERSISTED'), z.literal('CATALOG_PROJECTED'), z.literal('REGISTERED')]) }).strict() }).strict();
+/** v15 才扩展 Agent 治理工具和 scope；v1–v14 的严格枚举保持原样。 */
+export const knowledgeMcpProviderContractV15Schema = knowledgeMcpProviderContractV13Schema.omit({ schemaVersion: true, tools: true, scopes: true }).extend({ schemaVersion: z.literal(15), workflowSchemaVersion: z.literal(1), managementEndpoint: z.string().url(), scopes: z.array(knowledgeMcpProviderContractV13Schema.shape.scopes.element.or(z.literal('knowledge.workflow.read'))).min(4).max(10), tools: z.array(knowledgeMcpProviderContractV13Schema.shape.tools.element.extend({ name: knowledgeMcpProviderContractV13Schema.shape.tools.element.shape.name.or(z.enum(['knowledge_workflow_guide', 'knowledge_workflow_plan', 'knowledge_workflow_advance', 'knowledge_agent_submit'])), requiredScope: knowledgeMcpProviderContractV13Schema.shape.tools.element.shape.requiredScope.or(z.literal('knowledge.workflow.read')) })).min(17).max(27) }).strict();

package/dist/internal/serving-contracts/tenant-governance.d.ts

@@ -0,0 +1,236 @@
+/** 显式 native consumer；旧 profile/Provider/Workflow schema 1 不自动升级。 */
+import { z } from 'zod';
+export declare const tenantConsumerProfileSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    acceptedCurrentnessBases: z.ZodArray<z.ZodLiteral<"RETAINED_SNAPSHOT">>;
+    legacySourcePolicy: z.ZodOptional<z.ZodLiteral<"PROJECT_POLICY_V1">>;
+    consumerKey: z.ZodString;
+    acceptedArtifactKinds: z.ZodArray<z.ZodEnum<{
+        SIGNAL_GENERATION: "SIGNAL_GENERATION";
+        RESEARCH: "RESEARCH";
+        REVIEW: "REVIEW";
+        KNOWLEDGE: "KNOWLEDGE";
+        INSIGHT: "INSIGHT";
+    }>>;
+    acceptedAccess: z.ZodArray<z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>>;
+    contentAccess: z.ZodArray<z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>>;
+    acceptedReferenceTypes: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type TenantConsumerProfile = z.infer<typeof tenantConsumerProfileSchema>;
+export declare const tenantWorkflowPlanInputSchema: z.ZodObject<{
+    ref: z.ZodString;
+}, z.core.$strict>;
+export declare const tenantWorkflowAdvanceInputSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    ref: z.ZodString;
+    expectedVersion: z.ZodNumber;
+    action: z.ZodEnum<{
+        SUBMIT_REVIEW: "SUBMIT_REVIEW";
+        FINALIZE_REVIEW: "FINALIZE_REVIEW";
+    }>;
+    reviewRef: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const tenantWorkflowPlanSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    tenantId: z.ZodString;
+    ref: z.ZodString;
+    contentHash: z.ZodString;
+    resourceType: z.ZodString;
+    kind: z.ZodString;
+    version: z.ZodNumber;
+    status: z.ZodUnion<[z.ZodEnum<{
+        GENERATED: "GENERATED";
+        DRAFT: "DRAFT";
+        READY_FOR_REVIEW: "READY_FOR_REVIEW";
+        REWORK_REQUIRED: "REWORK_REQUIRED";
+        APPROVED: "APPROVED";
+        REJECTED: "REJECTED";
+        SUPERSEDED: "SUPERSEDED";
+    }>, z.ZodEnum<{
+        RAW_MATERIAL: "RAW_MATERIAL";
+        RAW_EVIDENCE: "RAW_EVIDENCE";
+        REFERENCE_SNAPSHOT: "REFERENCE_SNAPSHOT";
+        REGISTERED_MATERIAL: "REGISTERED_MATERIAL";
+    }>]>;
+    productionPhase: z.ZodLiteral<"REGISTERED">;
+    readiness: z.ZodNullable<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<2>;
+        profile: z.ZodEnum<{
+            HUMAN_ARTICLE_V1: "HUMAN_ARTICLE_V1";
+            KNOWLEDGE_CARD_V1: "KNOWLEDGE_CARD_V1";
+        }>;
+        ready: z.ZodBoolean;
+        reasons: z.ZodArray<z.ZodEnum<{
+            ROLE_MISMATCH: "ROLE_MISMATCH";
+            TITLE_REQUIRED: "TITLE_REQUIRED";
+            SUMMARY_REQUIRED: "SUMMARY_REQUIRED";
+            TEXT_TOO_SHORT: "TEXT_TOO_SHORT";
+            STRUCTURE_TOO_THIN: "STRUCTURE_TOO_THIN";
+            CITATION_COVERAGE_REQUIRED: "CITATION_COVERAGE_REQUIRED";
+            MEDIA_UNAVAILABLE: "MEDIA_UNAVAILABLE";
+            SOURCE_REQUIRED: "SOURCE_REQUIRED";
+            SOURCE_MISMATCH: "SOURCE_MISMATCH";
+        }>>;
+        metrics: z.ZodObject<{
+            textCharacters: z.ZodNumber;
+            blockCount: z.ZodNumber;
+            textBlockCount: z.ZodNumber;
+            mediaBlockCount: z.ZodNumber;
+            sourceCount: z.ZodNumber;
+            mediaEvidenceCount: z.ZodNumber;
+            citationCount: z.ZodNumber;
+            citedBlockCount: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    currentness: z.ZodNullable<z.ZodObject<{
+        observedAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        sourceRevisionRef: z.ZodOptional<z.ZodString>;
+        lastAttemptAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        assessedAt: z.ZodISODateTime;
+        state: z.ZodEnum<{
+            UNKNOWN: "UNKNOWN";
+            DUE: "DUE";
+            CURRENT: "CURRENT";
+            STALE: "STALE";
+            BLOCKED: "BLOCKED";
+        }>;
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        reasonCode: z.ZodEnum<{
+            CURRENT_WITHIN_CADENCE: "CURRENT_WITHIN_CADENCE";
+            REFRESH_DUE: "REFRESH_DUE";
+            STALE_AFTER_THRESHOLD: "STALE_AFTER_THRESHOLD";
+            SOURCE_BLOCKED: "SOURCE_BLOCKED";
+            SOURCE_CONTENT_CHANGED: "SOURCE_CONTENT_CHANGED";
+            NO_SUCCESSFUL_OBSERVATION: "NO_SUCCESSFUL_OBSERVATION";
+        }>;
+        policy: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            dueAfterSeconds: z.ZodNumber;
+            staleAfterSeconds: z.ZodNumber;
+            staleAction: z.ZodDefault<z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>>;
+            unknownAction: z.ZodDefault<z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>>;
+            blockedAction: z.ZodDefault<z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>>;
+        }, z.core.$strict>;
+        lastSuccessAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        dueAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        staleAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        ageSeconds: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        basis: z.ZodLiteral<"RETAINED_SNAPSHOT">;
+        basisRef: z.ZodString;
+        declarationRef: z.ZodString;
+        tenantId: z.ZodString;
+        subjectRef: z.ZodString;
+        resourceType: z.ZodString;
+        contentHash: z.ZodString;
+        schemaVersion: z.ZodLiteral<2>;
+        subjectKind: z.ZodLiteral<"MATERIAL">;
+    }, z.core.$strict>>;
+    governedPolicyReady: z.ZodBoolean;
+    consumerReadDecision: z.ZodNullable<z.ZodObject<{
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        reasonCodes: z.ZodArray<z.ZodString>;
+        authority: z.ZodEnum<{
+            AUTHENTICATED_READER: "AUTHENTICATED_READER";
+            LOCAL_PROFILE_SIMULATION: "LOCAL_PROFILE_SIMULATION";
+        }>;
+    }, z.core.$strict>>;
+    externalReady: z.ZodBoolean;
+    successorRef: z.ZodNullable<z.ZodString>;
+    blockers: z.ZodArray<z.ZodString>;
+    nextActions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tool: z.ZodNullable<z.ZodString>;
+        arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        requiredScopes: z.ZodArray<z.ZodString>;
+        missingScopes: z.ZodArray<z.ZodString>;
+        missingFields: z.ZodArray<z.ZodString>;
+        canExecute: z.ZodBoolean;
+        automatic: z.ZodBoolean;
+        reasonCode: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TenantWorkflowPlan = z.infer<typeof tenantWorkflowPlanSchema>;
+export declare const tenantGovernedReadResultSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    tenantId: z.ZodString;
+    ref: z.ZodString;
+    decision: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        reasonCodes: z.ZodArray<z.ZodEnum<{
+            NOT_FOUND: "NOT_FOUND";
+            ACCESS_DENIED: "ACCESS_DENIED";
+            CONTENT_ACCESS_DENIED: "CONTENT_ACCESS_DENIED";
+            ARTIFACT_NOT_APPROVED: "ARTIFACT_NOT_APPROVED";
+            ARTIFACT_SUPERSEDED: "ARTIFACT_SUPERSEDED";
+            SEMANTIC_REVIEW_REQUIRED: "SEMANTIC_REVIEW_REQUIRED";
+            SEMANTIC_DENIED: "SEMANTIC_DENIED";
+            SEMANTIC_ADMISSION_MISSING: "SEMANTIC_ADMISSION_MISSING";
+            CURRENTNESS_MISSING: "CURRENTNESS_MISSING";
+            CURRENTNESS_REVIEW_REQUIRED: "CURRENTNESS_REVIEW_REQUIRED";
+            CURRENTNESS_DENIED: "CURRENTNESS_DENIED";
+            STALE: "STALE";
+            VALIDITY_EXPIRED: "VALIDITY_EXPIRED";
+            CLAIM_REVIEW_REQUIRED: "CLAIM_REVIEW_REQUIRED";
+            CLAIM_DENIED: "CLAIM_DENIED";
+            CLAIM_NOT_EFFECTIVE: "CLAIM_NOT_EFFECTIVE";
+            REFERENCE_NOT_COVERED: "REFERENCE_NOT_COVERED";
+            REFERENCE_NOT_EFFECTIVE: "REFERENCE_NOT_EFFECTIVE";
+            REFERENCE_VALIDITY_EXPIRED: "REFERENCE_VALIDITY_EXPIRED";
+            REFERENCE_STALE: "REFERENCE_STALE";
+            REFERENCE_UNAVAILABLE: "REFERENCE_UNAVAILABLE";
+            REFERENCE_REVIEW_REQUIRED: "REFERENCE_REVIEW_REQUIRED";
+            REFERENCE_DENIED: "REFERENCE_DENIED";
+            UNSUPPORTED_RESOURCE: "UNSUPPORTED_RESOURCE";
+            GOVERNANCE_NOT_CONFIGURED: "GOVERNANCE_NOT_CONFIGURED";
+            UNAVAILABLE: "UNAVAILABLE";
+            INTEGRITY_MISMATCH: "INTEGRITY_MISMATCH";
+        }>>;
+        assessedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    descriptor: z.ZodNullable<z.ZodObject<{
+        contentHash: z.ZodString;
+        mediaType: z.ZodString;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/internal/serving-contracts/tenant-governance.js

@@ -0,0 +1,13 @@
+/** 显式 native consumer；旧 profile/Provider/Workflow schema 1 不自动升级。 */
+import { z } from 'zod';
+import { tenantResourceRefSchema, tenantManagementRequestIdSchema, materialTenantIdSchema, artifactStatusSchema, sha256Schema, tenantMaterialCurrentnessSchema, tenantPublicationReadinessSchema } from '../contracts/index.js';
+import { consumerProfileSchema, servingDecisionSchema } from './core.js';
+export const tenantConsumerProfileSchema = z.object({ ...consumerProfileSchema.shape, schemaVersion: z.literal(2), acceptedCurrentnessBases: z.array(z.literal('RETAINED_SNAPSHOT')).max(1), legacySourcePolicy: z.literal('PROJECT_POLICY_V1').optional() }).strict().superRefine((v, ctx) => { const { acceptedCurrentnessBases, legacySourcePolicy, schemaVersion, ...base } = v, checked = consumerProfileSchema.safeParse({ ...base, schemaVersion: 1 }); if (!checked.success)
+    for (const issue of checked.error.issues)
+        ctx.addIssue({ code: 'custom', path: issue.path, message: issue.message }); if (new Set(v.acceptedCurrentnessBases).size !== v.acceptedCurrentnessBases.length)
+    ctx.addIssue({ code: 'custom', message: 'currentness bases must be unique' }); });
+const readDecision = z.object({ action: z.enum(['ALLOW', 'REVIEW_REQUIRED', 'DENY']), reasonCodes: z.array(z.string()).max(32), authority: z.enum(['AUTHENTICATED_READER', 'LOCAL_PROFILE_SIMULATION']) }).strict();
+export const tenantWorkflowPlanInputSchema = z.object({ ref: tenantResourceRefSchema }).strict();
+export const tenantWorkflowAdvanceInputSchema = z.object({ requestId: tenantManagementRequestIdSchema, ref: tenantResourceRefSchema, expectedVersion: z.number().int().positive().safe(), action: z.enum(['SUBMIT_REVIEW', 'FINALIZE_REVIEW']), reviewRef: tenantResourceRefSchema.optional() }).strict();
+export const tenantWorkflowPlanSchema = z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, ref: tenantResourceRefSchema, contentHash: sha256Schema, resourceType: z.string(), kind: z.string(), version: z.number().int().positive(), status: artifactStatusSchema.or(z.enum(['RAW_MATERIAL', 'RAW_EVIDENCE', 'REFERENCE_SNAPSHOT', 'REGISTERED_MATERIAL'])), productionPhase: z.literal('REGISTERED'), readiness: tenantPublicationReadinessSchema.nullable(), currentness: tenantMaterialCurrentnessSchema.nullable(), governedPolicyReady: z.boolean(), consumerReadDecision: readDecision.nullable(), externalReady: z.boolean(), successorRef: tenantResourceRefSchema.nullable(), blockers: z.array(z.string()).max(64), nextActions: z.array(z.object({ id: z.string(), tool: z.string().nullable(), arguments: z.record(z.string(), z.json()), requiredScopes: z.array(z.string()), missingScopes: z.array(z.string()), missingFields: z.array(z.string()), canExecute: z.boolean(), automatic: z.boolean(), reasonCode: z.string() }).strict()).max(16) }).strict();
+export const tenantGovernedReadResultSchema = z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, ref: tenantResourceRefSchema, decision: servingDecisionSchema, descriptor: z.object({ contentHash: sha256Schema, mediaType: z.string(), byteLength: z.number().int().nonnegative() }).strict().nullable() }).strict();