@native-knowledge/cli 0.1.0-rc.1 → 0.1.0-rc.3

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

@@ -0,0 +1,76 @@
+// Compatibility exports: immutable Reference facts are owned by contracts.
+import { referenceRecordTypeSchema, referenceSelectorKeySchema, referenceSelectorValueSchema, referenceSelectorsSchema, referenceCurrentnessStateSchema, referenceCurrentnessSchema, referenceCorpusSummarySchema, referenceCorpusRecordSchema } from '../contracts/index.js';
+export { referenceRecordTypeSchema, referenceSelectorKeySchema, referenceSelectorValueSchema, referenceSelectorsSchema, referenceCurrentnessStateSchema, referenceCurrentnessSchema, referenceCorpusSummarySchema, referenceCorpusRecordSchema } from '../contracts/index.js';
+import { z } from 'zod';
+import { accessClassificationSchema, artifactKindSchema, artifactStatusSchema, currentnessActionSchema, currentnessStateSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from '../contracts/index.js';
+export const servingActionSchema = z.enum(['ALLOW', 'REVIEW_REQUIRED', 'DENY']);
+export const servingProblemCodeSchema = z.enum([
+    'NOT_FOUND', 'ACCESS_DENIED', 'CONTENT_ACCESS_DENIED', 'ARTIFACT_NOT_APPROVED', 'ARTIFACT_SUPERSEDED',
+    'SEMANTIC_REVIEW_REQUIRED', 'SEMANTIC_DENIED', 'SEMANTIC_ADMISSION_MISSING',
+    'CURRENTNESS_MISSING', 'CURRENTNESS_REVIEW_REQUIRED', 'CURRENTNESS_DENIED', 'STALE', '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',
+    'UNSUPPORTED_RESOURCE', 'GOVERNANCE_NOT_CONFIGURED', 'UNAVAILABLE', 'INTEGRITY_MISMATCH',
+]);
+export const servingDecisionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    action: servingActionSchema,
+    reasonCodes: z.array(servingProblemCodeSchema).max(32),
+    assessedAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.action === 'ALLOW' && value.reasonCodes.length)
+        ctx.addIssue({ code: 'custom', path: ['reasonCodes'], message: 'ALLOW must not carry problem codes' });
+    if (value.action !== 'ALLOW' && !value.reasonCodes.length)
+        ctx.addIssue({ code: 'custom', path: ['reasonCodes'], message: 'Non-ALLOW decision requires a problem code' });
+});
+export const consumerProfileSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    consumerKey: projectKeySchema,
+    acceptedArtifactKinds: z.array(artifactKindSchema).max(16),
+    acceptedAccess: z.array(accessClassificationSchema).max(7),
+    contentAccess: z.array(accessClassificationSchema).max(7),
+    acceptedReferenceTypes: z.array(referenceRecordTypeSchema).max(128),
+}).strict().superRefine((value, ctx) => {
+    if (new Set(value.acceptedArtifactKinds).size !== value.acceptedArtifactKinds.length)
+        ctx.addIssue({ code: 'custom', path: ['acceptedArtifactKinds'], message: 'acceptedArtifactKinds must be unique' });
+    if (new Set(value.acceptedAccess).size !== value.acceptedAccess.length)
+        ctx.addIssue({ code: 'custom', path: ['acceptedAccess'], message: 'acceptedAccess must be unique' });
+    if (new Set(value.contentAccess).size !== value.contentAccess.length)
+        ctx.addIssue({ code: 'custom', path: ['contentAccess'], message: 'contentAccess must be unique' });
+    if (value.contentAccess.some((access) => !value.acceptedAccess.includes(access)))
+        ctx.addIssue({ code: 'custom', path: ['contentAccess'], message: 'contentAccess must be a subset of acceptedAccess' });
+    if (value.contentAccess.some((access) => ['PUBLIC_METADATA', 'ACCESS_CONTROLLED', 'UNKNOWN'].includes(access)))
+        ctx.addIssue({ code: 'custom', path: ['contentAccess'], message: 'Metadata-only, access-controlled and unknown classes cannot grant content access' });
+    if (new Set(value.acceptedReferenceTypes).size !== value.acceptedReferenceTypes.length)
+        ctx.addIssue({ code: 'custom', path: ['acceptedReferenceTypes'], message: 'acceptedReferenceTypes must be unique' });
+});
+export const servingContentDescriptorSchema = z.object({
+    contentHash: sha256Schema, mediaType: z.string().trim().min(1).max(256), byteLength: z.number().int().nonnegative(),
+}).strict();
+export const servingArtifactSummarySchema = z.object({
+    ref: stableUriSchema, identityRef: stableUriSchema, projectKey: projectKeySchema, projectRef: stableUriSchema.nullable().default(null), artifactId: idSchema, kind: artifactKindSchema,
+    version: z.number().int().positive(), status: artifactStatusSchema, access: accessClassificationSchema, title: z.string().max(500).nullable(),
+    createdAt: isoDateTimeSchema, observedAt: isoDateTimeSchema.nullable(), validUntil: isoDateTimeSchema.nullable(), content: servingContentDescriptorSchema,
+}).strict();
+export const servingArtifactDetailSchema = servingArtifactSummarySchema.extend({
+    evidenceRefs: z.array(stableUriSchema).max(256), relatedRefs: z.array(stableUriSchema).max(256), supersedesRef: stableUriSchema.nullable(),
+}).strict();
+export const servingEvidenceSummarySchema = z.object({
+    evidenceRef: stableUriSchema, projectKey: projectKeySchema, sourceId: idSchema, contentHash: sha256Schema, observedAt: isoDateTimeSchema,
+    access: accessClassificationSchema, canonicalUri: stableUriSchema.nullable(), mediaType: z.string().max(256).nullable(), byteLength: z.number().int().nonnegative().nullable(),
+    projectRef: stableUriSchema.nullable().default(null), sourceSetRef: stableUriSchema.nullable(), sourceItemId: idSchema.nullable(), sourceRevisionRef: stableUriSchema.nullable().default(null), collectionBatchRef: stableUriSchema.nullable().default(null), collectionTaskId: idSchema.nullable().default(null),
+}).strict();
+export const servingSourceSummarySchema = z.object({
+    sourceId: idSchema, familyId: idSchema, authority: z.string().min(1).max(512), access: accessClassificationSchema, freshness: z.string().min(1).max(128),
+    declaredState: z.string().min(1).max(128), coverageState: z.string().max(128).nullable(), asOf: isoDateTimeSchema,
+}).strict();
+export const servingProjectIntentSummarySchema = z.object({
+    projectKey: projectKeySchema, projectRef: stableUriSchema, tenantId: idSchema, revisionRef: stableUriSchema, projectName: z.string().trim().min(1).max(256), updatedAt: isoDateTimeSchema,
+}).strict();
+export const servingProjectSourceSummarySchema = z.object({
+    projectKey: projectKeySchema, projectRef: stableUriSchema, projectIntentRef: stableUriSchema.nullable(), sourceId: idSchema, sourceRef: stableUriSchema, sourceRevisionRef: stableUriSchema, targetId: sha256Schema, targetKind: z.enum(['URL', 'FILE', 'EXECUTOR']), locator: stableUriSchema, executorId: idSchema.nullable().default(null), enabled: z.boolean(), access: accessClassificationSchema, refreshMode: z.enum(['MANUAL', 'INTERVAL']), intervalSeconds: z.number().int().min(60).nullable(), updatedAt: isoDateTimeSchema,
+}).strict();
+export const servingGovernanceSourceSummarySchema = servingSourceSummarySchema;
+export const servingCurrentnessSchema = z.object({
+    subjectRef: stableUriSchema, projectRef: stableUriSchema.nullable().default(null), sourceRevisionRef: stableUriSchema.nullable().default(null), state: currentnessStateSchema, action: currentnessActionSchema, assessedAt: isoDateTimeSchema, dueAt: isoDateTimeSchema.nullable(), staleAt: isoDateTimeSchema.nullable(), reasonCode: z.string().min(1).max(128),
+}).strict();

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

@@ -0,0 +1,64 @@
+import { rawMaterialDirectoryItemSchema } from '../contracts/index.js';
+import { z } from 'zod';
+import { accessClassificationSchema, isoDateTimeSchema, projectKeySchema, richDocumentSchema, schemaVersionSchema, sha256Schema, stableUriSchema } from '../contracts/index.js';
+import { referenceCorpusRecordSchema, referenceCorpusSummarySchema, servingArtifactDetailSchema, servingArtifactSummarySchema, servingCurrentnessSchema, servingDecisionSchema, servingEvidenceSummarySchema, servingSourceSummarySchema, servingProjectIntentSummarySchema, servingProjectSourceSummarySchema, } from './core.js';
+import { consumerProjectRefSchema, consumerReferenceLookupItemSchema } from './consumer.js';
+const decisionArtifactSummarySchema = z.object({ decision: servingDecisionSchema, artifact: servingArtifactSummarySchema }).strict();
+const decisionEvidenceSummarySchema = z.object({ decision: servingDecisionSchema, evidence: servingEvidenceSummarySchema }).strict();
+const decisionProjectSourceSummarySchema = z.object({ decision: servingDecisionSchema, source: servingProjectSourceSummarySchema }).strict();
+const decisionReferenceSummarySchema = z.object({ decision: servingDecisionSchema, record: referenceCorpusSummarySchema }).strict();
+export const servingApiErrorSchema = z.object({ errorCode: z.string().trim().min(1).max(128).regex(/^[A-Z0-9_]+$/) }).strict();
+export const servingHealthResponseSchema = z.object({ schemaVersion: schemaVersionSchema, status: z.literal('ok'), service: z.literal('knowledge-api'), codeRevision: z.string().trim().min(1).max(128) }).strict();
+export const servingArtifactListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionArtifactSummarySchema).max(1000) }).strict();
+/** Live, authorization-scoped page. A cursor is a position hint, never a grant or snapshot. */
+export const servingArtifactPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionArtifactSummarySchema).max(100), nextAfter: z.string().max(4096).nullable(), scanSemantics: z.literal('LIVE_AUTHORIZED'), versionCoverage: z.literal('AUTHORIZED_REFERENCES_ONLY') }).strict();
+/** Raw immutable snapshots remain separate from governed Knowledge decisions. */
+export const servingArtifactMaterialPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('ARTIFACT_SNAPSHOT'), items: z.array(z.object({ decision: servingDecisionSchema, governanceDecision: servingDecisionSchema, artifact: servingArtifactSummarySchema }).strict()).max(100), nextAfter: z.string().max(4096).nullable(), scanSemantics: z.literal('LIVE_AUTHORIZED'), versionCoverage: z.literal('AUTHORIZED_REFERENCES_ONLY') }).strict();
+export const servingArtifactMaterialResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('ARTIFACT_SNAPSHOT'), decision: servingDecisionSchema, governanceDecision: servingDecisionSchema, artifact: servingArtifactDetailSchema.nullable() }).strict();
+export const servingArtifactResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, artifact: servingArtifactDetailSchema.nullable() }).strict();
+export const servingEvidenceListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionEvidenceSummarySchema).max(1000) }).strict();
+// 不把文件可下载误称为结构化正文；状态不包含任何未授权的正文派生文本。
+export const servingEvidenceFormatQualitySchema = z.object({ format: z.enum(['HTML', 'PDF', 'FEED', 'XML', 'MARKDOWN', 'CSV', 'JSON', 'IMAGE', 'VIDEO', 'AUDIO', 'TEXT', 'OTHER']), rawFile: z.enum(['AVAILABLE', 'DENIED']), projection: z.enum(['READY', 'EMPTY', 'MISSING', 'UNSUPPORTED', 'DENIED']), media: z.enum(['COMPLETE', 'PARTIAL', 'NONE', 'UNASSESSED']) }).strict();
+// 通用文件发现页区分原始文件读取权和已审核知识的正文消费权。
+export const servingEvidencePageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionEvidenceSummarySchema.extend({ fileDecision: servingDecisionSchema, contentDecision: servingDecisionSchema, formatQuality: servingEvidenceFormatQualitySchema.optional(), presentation: z.object({ title: z.string().max(1000).nullable(), summary: z.string().max(4000).nullable(), byline: z.string().max(1000).nullable(), publishedAt: isoDateTimeSchema.nullable(), language: z.string().max(64).nullable(), topics: z.array(z.string().max(160)).max(32).optional(), documentRef: stableUriSchema, documentContentHash: sha256Schema, quality: z.object({ bodyCharacters: z.number().int().nonnegative(), mediaTotal: z.number().int().nonnegative(), mediaMirrored: z.number().int().nonnegative(), mediaUnavailable: z.number().int().nonnegative(), mediaTooLarge: z.number().int().nonnegative() }).strict() }).strict().nullable().optional() })).max(100), nextAfter: stableUriSchema.nullable() }).strict().superRefine((value, ctx) => { for (let index = 0; index < value.items.length; index++) {
+    const item = value.items[index];
+    if (item.presentation && item.fileDecision.action !== 'ALLOW')
+        ctx.addIssue({ code: 'custom', path: ['items', index, 'presentation'], message: 'Body-derived presentation requires raw-file authorization' });
+} });
+/** A readable representation of original Evidence, never a reviewed Knowledge artifact. */
+export const servingEvidencePresentationResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, contentClass: z.literal('RAW_EVIDENCE_PRESENTATION'), presentation: z.object({ sourceEvidenceRef: stableUriSchema, sourceContentHash: sha256Schema, documentRef: stableUriSchema, documentContentHash: sha256Schema, document: richDocumentSchema }).strict().nullable() }).strict().superRefine((value, ctx) => {
+    if ((value.decision.action === 'ALLOW') !== Boolean(value.presentation))
+        ctx.addIssue({ code: 'custom', path: ['presentation'], message: 'Presentation must match the current decision' });
+    if (value.presentation && (value.presentation.document.role !== 'SOURCE_MIRROR' || value.presentation.document.sourceContentHash !== value.presentation.sourceContentHash || value.presentation.document.primarySourceEvidenceRef !== value.presentation.sourceEvidenceRef || value.presentation.document.projectKey !== /^evidence:\/\/([^/]+)\//.exec(value.presentation.sourceEvidenceRef)?.[1]))
+        ctx.addIssue({ code: 'custom', path: ['presentation'], message: 'Presentation source identity mismatch' });
+});
+export const oauthMaterialPresentationResponseSchema = servingEvidencePresentationResponseSchema.safeExtend({ projectRef: consumerProjectRefSchema });
+export const servingEvidenceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, evidence: servingEvidenceSummarySchema.nullable() }).strict();
+export const servingProjectIntentResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, project: servingProjectIntentSummarySchema.nullable() }).strict();
+export const servingProjectSourceListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionProjectSourceSummarySchema).max(1000) }).strict();
+export const servingProjectSourceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, source: servingProjectSourceSummarySchema.nullable() }).strict();
+export const servingSourceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, source: servingSourceSummarySchema.nullable() }).strict();
+export const servingCurrentnessResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, currentness: servingCurrentnessSchema.nullable() }).strict();
+export const servingReferenceListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionReferenceSummarySchema).max(1000) }).strict();
+export const servingReferenceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, record: referenceCorpusRecordSchema.nullable() }).strict();
+export const servingReferenceMaterialPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('REFERENCE_SNAPSHOT'), items: z.array(z.object({ decision: servingDecisionSchema, record: referenceCorpusSummarySchema }).strict()).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const servingReferenceMaterialResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('REFERENCE_SNAPSHOT'), decision: servingDecisionSchema, record: referenceCorpusRecordSchema.nullable() }).strict();
+/** Type-neutral discovery over current project references; kind is descriptive, never an admission list. */
+export const servingMaterialDirectoryItemSchema = rawMaterialDirectoryItemSchema;
+export const servingMaterialPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('MATERIAL_DIRECTORY'), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable(), scanSemantics: z.literal('LIVE_AUTHORIZED') }).strict();
+export const servingMaterialRoutePageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, 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 materialRoutePartitionSchema = z.object({ routeId: z.string().regex(/^[a-f0-9]{64}$/), sourceProjectKey: projectKeySchema, matchType: z.enum(['SOURCE_PROJECT', 'SOURCE_SET', 'REF']), matchValue: z.string().min(1).max(4096) }).strict();
+export const servingMaterialPartitionsResponseSchema = z.object({ schemaVersion: schemaVersionSchema, 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 servingMaterialPartitionPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('MATERIAL_DIRECTORY'), partition: z.enum(['OWNER', 'LEGACY']), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const servingMaterialSearchResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, 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 oauthMaterialPageResponseSchema = z.discriminatedUnion('resourceType', [
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('all'), contentClass: z.literal('MATERIAL_DIRECTORY'), items: servingMaterialPageResponseSchema.shape.items, nextAfter: stableUriSchema.nullable() }).strict(),
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('artifact'), contentClass: z.literal('ARTIFACT_SNAPSHOT'), items: servingArtifactMaterialPageResponseSchema.shape.items, nextAfter: z.string().max(4096).nullable() }).strict(),
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('evidence'), contentClass: z.literal('RAW_EVIDENCE'), items: servingEvidencePageResponseSchema.shape.items, nextAfter: stableUriSchema.nullable() }).strict(),
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('reference'), contentClass: z.literal('REFERENCE_SNAPSHOT'), items: servingReferenceMaterialPageResponseSchema.shape.items, nextAfter: stableUriSchema.nullable() }).strict(),
+]);
+export const servingReferenceLookupResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, lookupCoverage: z.literal('AUTHORIZED_REFERENCE_SELECTORS_V1'), items: z.array(consumerReferenceLookupItemSchema).max(100) }).strict();
+export const servingContentDecisionResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, content: z.null() }).strict();
+export const servingContentHeadersSchema = z.object({ contentHash: sha256Schema, mediaType: z.string().trim().min(1).max(256), byteLength: z.number().int().nonnegative(), assessedAt: z.string().datetime({ offset: true }) }).strict();
+/** Recovery checkpoint is captured before bootstrap; incremental replay starts after headSeq. */
+export const materialOutboxWindowSchema = z.object({ schemaVersion: schemaVersionSchema, tenantId: z.string().min(1), retainedThroughSeq: z.number().int().nonnegative().safe(), headSeq: z.number().int().nonnegative().safe() }).strict().refine(value => value.retainedThroughSeq <= value.headSeq, { message: 'Outbox floor must not exceed head' });

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

@@ -0,0 +1,25 @@
+export * from './core.js';
+export * from './http.js';
+export * from './consumer.js';
+export * from './mcp.js';
+export * from './management.js';
+export * from './material-capabilities.js';
+export * from './material-index-status.js';
+// CLI、MCP 与 HTTPS 共享同一 Agent 治理合同，避免各入口自行解释状态。
+export * from './workflow.js';
+export * from './tenant-governance.js';
+export * from './tenant-management.js';
+export * from './tenant-workspace.js';
+export * from './tenant-project.js';
+export * from './tenant-runtime.js';
+export * from './tenant-web.js';
+export * from './tenant-web-crawl.js';
+export * from './tenant-web-dynamic.js';
+export * from './tenant-web-content.js';
+export * from './tenant-web-workflow.js';
+export * from './tenant-session.js';
+export * from './agent-entry.js';
+export * from './agent-catalog.js';
+export * from './body-search.js';
+export * from './agent-guidance-shapes.js';
+export * from './agent-input-hints.js';

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

@@ -0,0 +1,15 @@
+/** 管理 MCP 的参数只携带项目引用和治理输入；项目 Key、Tenant 和节点均由服务端绑定解析。 */
+import { z } from 'zod';
+import { artifactIdSchema, isoDateTimeSchema, publicationProfileSchema, richCompositionDraftSchema, stableUriSchema } from '../contracts/index.js';
+import { consumerProjectRefSchema } from './consumer.js';
+const version = z.number().int().nonnegative();
+const base = z.object({ projectRef: consumerProjectRefSchema }).strict();
+export const managementComposeInputSchema = base.extend({ sourceEvidenceRefs: z.array(stableUriSchema).min(1).max(64), primarySourceEvidenceRef: stableUriSchema.optional(), artifactId: artifactIdSchema, expectedVersion: version, composedAt: isoDateTimeSchema, validUntil: isoDateTimeSchema.optional(), outputKind: z.enum(['KNOWLEDGE', 'INSIGHT']), publicationProfile: publicationProfileSchema.optional(), title: z.string().trim().min(1).max(1000).optional(), composition: richCompositionDraftSchema.optional() }).strict();
+export const managementSubmitInputSchema = base.extend({ ref: stableUriSchema, expectedVersion: version, createdAt: isoDateTimeSchema }).strict();
+export const managementReviewInputSchema = base.extend({ targetRef: stableUriSchema, expectedVersion: version, decision: z.enum(['PASS', 'REWORK', 'REJECT']), reviewedAt: isoDateTimeSchema, summary: z.string().trim().min(1).max(8000), evidenceRefs: z.array(stableUriSchema).max(64).optional() }).strict();
+export const managementFinalizeInputSchema = base.extend({ ref: stableUriSchema, expectedVersion: version, nextStatus: z.enum(['APPROVED', 'REWORK_REQUIRED', 'REJECTED']), reviewRef: stableUriSchema, createdAt: isoDateTimeSchema }).strict();
+export const managementResultSchema = z.object({ schemaVersion: z.literal(1), projectRef: consumerProjectRefSchema, ref: stableUriSchema, kind: z.enum(['KNOWLEDGE', 'INSIGHT', 'REVIEW']), version: z.number().int().positive(), status: z.enum(['DRAFT', 'READY_FOR_REVIEW', 'APPROVED', 'REWORK_REQUIRED', 'REJECTED']), contentHash: z.string().regex(/^sha256:[a-f0-9]{64}$/), inserted: z.boolean() }).strict();
+// MCP 公告和服务端参数校验从同一组合同生成，避免工具描述与实际输入漂移。
+export const managementToolInputSchemas = { knowledge_compose: z.toJSONSchema(managementComposeInputSchema, { target: 'draft-07' }), knowledge_submit_review: z.toJSONSchema(managementSubmitInputSchema, { target: 'draft-07' }), knowledge_review: z.toJSONSchema(managementReviewInputSchema, { target: 'draft-07' }), knowledge_finalize_review: z.toJSONSchema(managementFinalizeInputSchema, { target: 'draft-07' }) };
+export const managementToolErrorOutputSchema = { type: 'object', properties: { errorCode: { type: 'string' }, completedPhase: { type: 'string', enum: ['VALIDATED', 'PERSISTED', 'CATALOG_PROJECTED'] }, ref: z.toJSONSchema(stableUriSchema, { target: 'draft-07' }) }, required: ['errorCode'], additionalProperties: false };
+export const managementToolOutputSchema = { type: 'object', oneOf: [z.toJSONSchema(managementResultSchema, { target: 'draft-07' }), managementToolErrorOutputSchema] };

package/dist/internal/serving-contracts/material-capabilities.js

@@ -0,0 +1,14 @@
+import { rawRetrievalDecisionSchema } from '../contracts/index.js';
+import { z } from 'zod';
+import { projectKeySchema, stableUriSchema, sha256Schema } from '../contracts/index.js';
+import { servingMaterialDirectoryItemSchema } from './http.js';
+import { materialReadStateSchema, materialCapabilitySchema } from '../contracts/index.js';
+export { materialReadStateSchema, materialCapabilitySchema } from '../contracts/index.js';
+export const materialCapabilityResponseSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, material: materialCapabilitySchema }).strict();
+export const materialCapabilityPageSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, items: z.array(materialCapabilitySchema).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const materialMediaCapabilityPageSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, ref: stableUriSchema, sourceContentHash: sha256Schema, documentRef: stableUriSchema.nullable(), documentContentHash: sha256Schema.nullable(), state: z.enum(['READY', 'MISSING', 'DENIED', 'UNSUPPORTED', 'INTEGRITY_MISMATCH']), items: z.array(z.object({ ordinal: z.number().int().nonnegative(), kind: z.enum(['IMAGE', 'VIDEO', 'AUDIO']), sourceUrl: z.string().url(), canonicalUrl: z.string().url().nullable(), availability: z.enum(['MIRRORED', 'REMOTE_ONLY', 'UNAVAILABLE']), mediaRef: stableUriSchema.nullable(), contentHash: sha256Schema.nullable(), mediaType: z.string().nullable(), byteLength: z.number().int().nonnegative().safe().nullable(), state: z.enum(['READY', 'REMOTE_ONLY', 'UNAVAILABLE', 'MISSING', 'DENIED', 'INTEGRITY_MISMATCH']), representation: materialCapabilitySchema.shape.representation.nullable() }).strict()).max(100), nextAfterOrdinal: z.number().int().nonnegative().nullable() }).strict();
+export const oauthMaterialCapabilityResponseSchema = materialCapabilityResponseSchema.extend({ projectRef: stableUriSchema }).strict();
+export const oauthMaterialCapabilityPageSchema = materialCapabilityPageSchema.extend({ projectRef: stableUriSchema }).strict();
+export const oauthMaterialMediaCapabilityPageSchema = materialMediaCapabilityPageSchema.extend({ projectRef: stableUriSchema }).strict();
+/** Authenticated API-key discovery uses service-relative paths and never substitutes OAuth authority. */
+export const apiKeyMaterialContractSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, authentication: z.literal('API_KEY'), resourceTypeMode: z.literal('OPEN_IDENTIFIER'), capabilitiesEndpoint: z.literal('/v3/material-capabilities'), capabilityPageEndpoint: z.literal('/v3/material-page'), fileEndpoint: z.literal('/v2/material-file'), mediaPageEndpoint: z.literal('/v3/material-media-page'), indexStatusEndpoint: z.literal('/v3/material-index-status'), fileMethods: z.tuple([z.literal('GET'), z.literal('HEAD')]), fileRange: z.literal('SINGLE') }).strict();

package/dist/internal/serving-contracts/material-index-status.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import { projectKeySchema, idSchema, stableUriSchema } from '../contracts/index.js';
+export const materialIndexPositionSchema = z.object({ sourceProjectKey: projectKeySchema, nodeId: idSchema }).strict();
+export const materialIndexStatusSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, queryCoverage: z.literal('DESCRIPTIVE_METADATA_V1'), indexedFields: z.tuple([z.literal('TITLE'), z.literal('SUMMARY')]), bodyIndexed: z.literal(false), semanticIndexed: z.literal(false), items: z.array(materialIndexPositionSchema.extend({ directoryThroughSeq: z.number().int().nonnegative().safe(), searchThroughSeq: z.number().int().nonnegative().safe().nullable(), observedMaxSeq: z.number().int().nonnegative().safe().nullable(), checkpointUpdatedAt: z.string().datetime({ offset: true }).nullable(), state: z.enum(['PARTIAL_BACKFILL', 'SYNCED_AS_OF_CHECKPOINT']) }).strict()).max(100), nextAfter: materialIndexPositionSchema.nullable() }).strict();
+export const oauthMaterialIndexStatusSchema = materialIndexStatusSchema.extend({ projectRef: stableUriSchema }).strict();

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

@@ -0,0 +1,137 @@
+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.object({ version: z.literal('2026-07-28'), lifecycle: z.literal('STATELESS_DISCOVERY'), transport: z.literal('STREAMABLE_HTTP') }).strict()).length(1),
+}).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.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();

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

@@ -0,0 +1,89 @@
+/** 新 Tenant 管理工具共同合同；认证 context/actor/authority 只由 adapter 注入。 */
+import { z } from 'zod';
+import { parseTenantResourceRef, tenantStorageKey, tenantRawSubmissionSchema, tenantArtifactDraftSchema, tenantComposeInputSchema, tenantReviewInputSchema, tenantPromoteInputSchema, tenantSnapshotInputSchema, tenantShareInputSchema, tenantRevokeShareInputSchema, tenantResourceManifestSchema, tenantMaterialCurrentnessSchema, tenantSourceSemanticsSchema, tenantSourceIdSchema, tenantSourceSnapshotSchema, collectionRefreshSchema, tenantCollectionCycleSchema, tenantCollectionRequestSchema, tenantCollectionBatchSchema, tenantCollectionCompletionSchema, tenantCollectionFailureSchema, tenantResourceRefSchema, materialTenantIdSchema, sha256Schema, isoDateTimeSchema, stableUriSchema } from '../contracts/index.js';
+import { tenantWorkflowPlanSchema, tenantWorkflowPlanInputSchema, tenantWorkflowAdvanceInputSchema, tenantGovernedReadResultSchema } from './tenant-governance.js';
+const base64 = z.string().min(4).max(87384).regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/), ref = z.object({ ref: tenantResourceRefSchema }).strict(), page = z.object({ after: z.string().min(1).max(128).optional(), limit: z.number().int().min(1).max(100).optional() }).strict(), source = z.object({ sourceId: tenantSourceIdSchema }).strict();
+export const tenantManagementToolSchemas = {
+    tenant_material_submit: tenantRawSubmissionSchema.extend({ contentBase64: base64 }).strict(),
+    tenant_artifact_draft: tenantArtifactDraftSchema.extend({ contentBase64: base64 }).strict(),
+    tenant_knowledge_compose: tenantComposeInputSchema,
+    tenant_knowledge_review: tenantReviewInputSchema,
+    tenant_artifact_promote: tenantPromoteInputSchema,
+    tenant_snapshot_declare: tenantSnapshotInputSchema,
+    tenant_snapshot_status: ref,
+    tenant_material_share: tenantShareInputSchema,
+    tenant_material_revoke: tenantRevokeShareInputSchema,
+    tenant_material_routes: page,
+    tenant_workflow_guide: z.object({}).strict(),
+    tenant_workflow_plan: tenantWorkflowPlanInputSchema,
+    tenant_workflow_advance: tenantWorkflowAdvanceInputSchema,
+    tenant_knowledge_read: ref,
+    tenant_source_define: z.object({ definition: z.object({ schemaVersion: z.literal(1), sourceId: tenantSourceIdSchema, title: z.string().trim().min(1).max(512), semantics: tenantSourceSemanticsSchema }).strict(), expectedGeneration: z.number().int().positive().safe().nullable() }).strict(),
+    tenant_source_configure: source.extend({ expectedGeneration: z.number().int().positive().safe(), paused: z.boolean(), tenantEnabled: z.boolean(), refresh: collectionRefreshSchema }).strict(),
+    tenant_source_get: source,
+    tenant_source_list: page,
+    tenant_collection_request: z.object({ requestId: tenantCollectionCycleSchema, sourceId: tenantSourceIdSchema, expectedSourceRevisionRef: stableUriSchema.optional(), cycleId: tenantCollectionCycleSchema.optional() }).strict(),
+    tenant_collection_status: z.object({ requestId: tenantCollectionCycleSchema }).strict(),
+};
+/** 固定能力索引；promote/advance 的调用鉴权必须使用 scopesForInput，发现使用 Authorization。 */
+export const tenantManagementToolScopes = { tenant_material_submit: 'knowledge.material.write', tenant_artifact_draft: 'knowledge.material.write', tenant_knowledge_compose: 'knowledge.compose', tenant_knowledge_review: 'knowledge.review', tenant_artifact_promote: 'knowledge.material.write', tenant_snapshot_declare: 'knowledge.review', tenant_snapshot_status: 'knowledge.workflow.read', tenant_material_share: 'knowledge.material.route', tenant_material_revoke: 'knowledge.material.route', tenant_material_routes: 'knowledge.material.route', tenant_workflow_guide: 'knowledge.workflow.read', tenant_workflow_plan: 'knowledge.workflow.read', tenant_workflow_advance: 'knowledge.workflow.read', tenant_knowledge_read: 'knowledge.read', tenant_source_define: 'knowledge.source.manage', tenant_source_configure: 'knowledge.source.manage', tenant_source_get: 'knowledge.source.manage', tenant_source_list: 'knowledge.source.manage', tenant_collection_request: 'knowledge.collect', tenant_collection_status: 'knowledge.collect' };
+/** 初始动作能力来自同一输入合同；依赖原件读取等附加检查仍在 application。 */
+export function tenantManagementScopesForInput(name, raw) {
+    const input = tenantManagementToolSchemas[name].parse(raw);
+    if (name === 'tenant_artifact_promote')
+        return [tenantPromoteInputSchema.parse(input).nextStatus === 'READY_FOR_REVIEW' ? 'knowledge.material.write' : 'knowledge.approve'];
+    if (name === 'tenant_workflow_advance')
+        return ['knowledge.workflow.read', tenantWorkflowAdvanceInputSchema.parse(input).action === 'SUBMIT_REVIEW' ? 'knowledge.material.write' : 'knowledge.approve'];
+    return [tenantManagementToolScopes[name]];
+}
+export function tenantManagementAuthorization(name) {
+    if (name === 'tenant_artifact_promote')
+        return { selection: 'NEXT_STATUS', scopeAlternatives: [['knowledge.material.write'], ['knowledge.approve']] };
+    if (name === 'tenant_workflow_advance')
+        return { selection: 'WORKFLOW_ACTION', scopeAlternatives: [['knowledge.workflow.read', 'knowledge.material.write'], ['knowledge.workflow.read', 'knowledge.approve']] };
+    return { selection: 'FIXED', scopeAlternatives: [[tenantManagementToolScopes[name]]] };
+}
+// advance/promote 的实际动作、来源/审核读取能力继续由 application/context 逐项复核。
+const production = z.object({ phase: z.literal('REGISTERED'), ref: tenantResourceRefSchema, registered: z.boolean(), seq: z.number().int().positive(), manifestRevision: sha256Schema }).strict();
+const write = z.object({ inserted: z.boolean(), manifest: tenantResourceManifestSchema, production }).strict();
+const projection = z.object({ changed: z.boolean(), seq: z.number().int().positive(), assessmentRevision: sha256Schema }).strict();
+const route = z.object({ routeId: z.string().regex(/^[a-f0-9]{64}$/), ownerTenantId: materialTenantIdSchema, recipientTenantId: materialTenantIdSchema, sourceProjectKey: z.null(), matchType: z.enum(['SOURCE', 'REF']), matchValue: stableUriSchema, effect: z.enum(['ALLOW', 'DENY']), revokedAt: isoDateTimeSchema.nullable() }).strict();
+const routeChange = z.object({ changed: z.boolean(), route, completedPhase: z.literal('ROUTE_COMMITTED'), operationRef: stableUriSchema }).strict();
+const sourceHead = z.object({ tenantId: materialTenantIdSchema, sourceId: tenantSourceIdSchema, revisionRef: stableUriSchema, semanticKey: sha256Schema, generation: z.number().int().positive().safe(), paused: z.boolean(), tenantEnabled: z.boolean(), refresh: collectionRefreshSchema, snapshot: tenantSourceSnapshotSchema }).strict().superRefine((v, ctx) => { if (v.tenantId !== v.snapshot.tenantId || v.sourceId !== v.snapshot.sourceId || v.revisionRef !== v.snapshot.revisionRef || v.semanticKey !== v.snapshot.semanticKey)
+    ctx.addIssue({ code: 'custom', message: 'Source head preserves its exact snapshot identity' }); });
+const governedRead = tenantGovernedReadResultSchema.extend({ contentBase64: base64.max(43692).nullable(), truncated: z.boolean(), continuation: z.object({ kind: z.literal('AUTHENTICATED_TENANT_GOVERNED_CONTENT'), ref: tenantResourceRefSchema }).strict().nullable() }).strict().superRefine((v, ctx) => {
+    const length = v.contentBase64 === null ? 0 : v.contentBase64.length / 4 * 3 - (v.contentBase64.endsWith('==') ? 2 : v.contentBase64.endsWith('=') ? 1 : 0);
+    if (v.decision.action === 'ALLOW' ? (!v.descriptor || v.contentBase64 === null || length > 32768 || (v.truncated ? (!v.continuation || v.continuation.ref !== v.ref || v.descriptor.byteLength <= length) : (v.continuation !== null || v.descriptor.byteLength !== length))) : (v.descriptor !== null || v.contentBase64 !== null || v.truncated || v.continuation !== null))
+        ctx.addIssue({ code: 'custom', message: 'Governed inline data and continuation must match the actual content decision and full length' });
+});
+const guide = z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, authorityVersion: z.literal(2), scopes: z.array(z.string()).max(32), tools: z.array(z.object({ name: z.string(), authorization: z.object({ selection: z.enum(['FIXED', 'NEXT_STATUS', 'WORKFLOW_ACTION']), scopeAlternatives: z.array(z.array(z.string()).min(1).max(8)).min(1).max(4) }).strict(), inputSchema: z.json(), outputSchema: z.json() }).strict()).max(64), rules: z.array(z.string()).max(32), limits: z.object({ requestMaxBytes: z.literal(131072), resultMaxBytes: z.literal(524288), submissionMaxBytes: z.literal(65536) }).strict() }).strict();
+export const tenantManagementDataSchemas = {
+    tenant_material_submit: write, tenant_artifact_draft: write, tenant_knowledge_compose: write, tenant_knowledge_review: write, tenant_artifact_promote: write,
+    tenant_snapshot_declare: z.object({ subjectRef: tenantResourceRefSchema, declared: z.boolean(), declarationRef: stableUriSchema, assessment: tenantMaterialCurrentnessSchema, projection, completedPhase: z.literal('CURRENTNESS_NOTIFIED'), operationRef: stableUriSchema }).strict(),
+    tenant_snapshot_status: z.object({ subjectRef: tenantResourceRefSchema, state: z.enum(['NOT_AVAILABLE', 'NOT_DECLARED', 'PROJECTION_PENDING', 'READY', 'INTEGRITY_MISMATCH', 'UNAVAILABLE']), assessment: tenantMaterialCurrentnessSchema.nullable() }).strict(),
+    tenant_material_share: routeChange, tenant_material_revoke: routeChange, tenant_material_routes: z.object({ items: z.array(route).max(100), nextAfter: z.string().nullable() }).strict(),
+    tenant_workflow_guide: guide, tenant_workflow_plan: tenantWorkflowPlanSchema,
+    tenant_workflow_advance: z.object({ schemaVersion: z.literal(2), action: z.enum(['SUBMIT_REVIEW', 'FINALIZE_REVIEW']), previousRef: tenantResourceRefSchema, inserted: z.boolean(), production, plan: tenantWorkflowPlanSchema }).strict(),
+    tenant_knowledge_read: governedRead,
+    tenant_source_define: z.object({ changed: z.boolean(), reused: z.boolean(), phase: z.literal('SOURCE_REGISTERED'), head: sourceHead }).strict(),
+    tenant_source_configure: z.object({ changed: z.boolean(), head: sourceHead }).strict(), tenant_source_get: sourceHead.nullable(), tenant_source_list: z.object({ items: z.array(sourceHead).max(100), nextAfter: tenantSourceIdSchema.nullable() }).strict(),
+    tenant_collection_request: z.object({ inserted: z.boolean(), request: tenantCollectionRequestSchema, batch: tenantCollectionBatchSchema, phase: z.literal('BATCH_PERSISTED') }).strict(),
+    tenant_collection_status: z.object({ request: tenantCollectionRequestSchema, completion: tenantCollectionCompletionSchema.nullable(), failure: tenantCollectionFailureSchema.nullable().optional() }).strict().nullable(),
+};
+export const tenantManagementErrorCodeSchema = z.enum(['TENANT_MANAGEMENT_INVALID_INPUT', 'TENANT_MANAGEMENT_FORBIDDEN', 'TENANT_MANAGEMENT_AUTHORITY_CHANGED', 'TENANT_MANAGEMENT_RUNTIME_OWNER_REQUIRED', 'TENANT_MANAGEMENT_IDEMPOTENCY_CONFLICT', 'TENANT_MANAGEMENT_VERSION_CONFLICT', 'TENANT_MANAGEMENT_SOURCE_FORBIDDEN', 'TENANT_MANAGEMENT_REVIEW_REQUIRED', 'TENANT_MANAGEMENT_POLICY_BLOCKED', 'TENANT_MANAGEMENT_UNAVAILABLE', 'TENANT_MANAGEMENT_INCOMPLETE', 'TENANT_MANAGEMENT_INPUT_BUDGET', 'TENANT_MANAGEMENT_NOT_FOUND']);
+export const tenantManagementErrorSchema = z.object({ errorCode: tenantManagementErrorCodeSchema, completedPhase: z.enum(['VALIDATED', 'PERSISTED', 'CATALOG_PROJECTED', 'REGISTERED', 'ROUTE_COMMITTED', 'DECLARATION_PERSISTED', 'CURRENTNESS_RECORDED', 'CURRENTNESS_NOTIFIED', 'SOURCE_PERSISTED', 'SOURCE_REGISTERED', 'REQUEST_PERSISTED', 'BATCH_PERSISTED']).optional(), ref: stableUriSchema.optional() }).strict();
+export function tenantManagementEnvelopeSchema(tool) { return z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, tool: z.literal(tool), data: tenantManagementDataSchemas[tool] }).strict(); }
+export const tenantManagementInputJsonSchemas = Object.fromEntries(Object.entries(tenantManagementToolSchemas).map(([name, schema]) => [name, z.toJSONSchema(schema, { target: 'draft-07' })]));
+export const tenantManagementOutputJsonSchemas = Object.fromEntries(Object.keys(tenantManagementToolSchemas).map(name => [name, { type: 'object', oneOf: [z.toJSONSchema(tenantManagementEnvelopeSchema(name), { target: 'draft-07' }), z.toJSONSchema(tenantManagementErrorSchema, { target: 'draft-07' })] }]));
+export const tenantManagementProviderBaseSchema = z.object({ schemaVersion: z.literal(17), provider: z.literal('knowledge-v2'), codeRevision: z.string().min(1).max(128), authorityVersion: z.literal(2), context: z.literal('TENANT_EXPLICIT_MANAGEMENT_V1'), managementConfigured: z.boolean(), resource: stableUriSchema, issuer: stableUriSchema, authorizationEndpoint: stableUriSchema, tokenEndpoint: stableUriSchema, revocationEndpoint: stableUriSchema, mcpEndpoint: stableUriSchema, callEndpoint: stableUriSchema, contentEndpoint: stableUriSchema, contentContextHeader: z.literal('x-knowledge-tenant-id'), legacyProviderEndpoint: stableUriSchema, protocols: z.array(z.literal('2026-07-28')).length(1), tools: z.array(z.string()).length(Object.keys(tenantManagementToolSchemas).length), requestMaxBytes: z.literal(131072), resultMaxBytes: z.literal(524288), submissionMaxBytes: z.literal(65536), inlineContentMaxBytes: z.literal(32768), contentReadMaxBytes: z.literal(16777216), collectionMode: z.literal('MANUAL_ONLY_OAUTH'), capabilities: z.tuple([z.literal('TENANT_MANAGEMENT_V1'), z.literal('TENANT_WORKFLOW_V1'), z.literal('TENANT_CURRENTNESS_V2'), z.literal('TENANT_SOURCE_V1')]) }).strict();
+export const tenantManagementProviderSchema = tenantManagementProviderBaseSchema.superRefine((v, ctx) => { if (new Set(v.tools).size !== Object.keys(tenantManagementToolSchemas).length || v.tools.some(name => !Object.hasOwn(tenantManagementToolSchemas, name)))
+    ctx.addIssue({ code: 'custom', message: 'Provider tools must match the exact native tool contract' }); });
+/** 诊断 ref 只允许当前访问 Tenant 的 canonical 原生身份；不接受 URL/本机路径。 */
+export function tenantManagementSafeErrorRef(ref, tenantId) {
+    if (typeof ref !== 'string' || ref.length > 2048)
+        return undefined;
+    const key = tenantStorageKey(tenantId), resource = parseTenantResourceRef(ref);
+    if (resource?.storageKey === key)
+        return ref;
+    return new RegExp(`^(?:tenant-operation://${key}/[a-f0-9]{64}|tenant-collection-request://${key}/[a-f0-9]{64}|tenant-currentness://${key}/snapshot/[a-f0-9]{64}|tenant-source://${key}/[A-Za-z0-9][A-Za-z0-9._-]{0,127}(?:/v/[a-f0-9]{64})?)$`).test(ref) ? ref : undefined;
+}

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

@@ -0,0 +1,39 @@
+/** Provider19 extends Project context without changing the exact v17/v18 registries. */
+import { z } from 'zod';
+import { projectKeySchema, sha256Schema, stableUriSchema, isoDateTimeSchema, materialTenantIdSchema, resourceDirectoryItemSchema, tenantProjectScopeChangeSchema, tenantProjectLifecycleChangeSchema, tenantProjectControlResultSchema, tenantManagementRequestIdSchema } from '../contracts/index.js';
+import { tenantWorkspaceToolSchemas, tenantWorkspaceDataSchemas, tenantWorkspaceScopesForInput, tenantWorkspaceAuthorization } from './tenant-workspace.js';
+import { tenantManagementErrorSchema, tenantManagementProviderBaseSchema } from './tenant-management.js';
+const cursor = z.string().min(1).max(4096), page = { after: cursor.optional(), limit: z.number().int().min(1).max(100).optional() };
+export const tenantProjectToolSchemas = {
+    tenant_project_list: z.object(page).strict(),
+    tenant_project_get: z.object({ projectKey: projectKeySchema, purposeAfter: cursor.optional(), selectionAfter: cursor.optional(), requestId: tenantManagementRequestIdSchema.optional() }).strict(),
+    tenant_project_materials: z.object({ projectKey: projectKeySchema, ...page }).strict(),
+    tenant_project_scope_set: tenantProjectScopeChangeSchema,
+    tenant_project_lifecycle_set: tenantProjectLifecycleChangeSchema,
+};
+const result = tenantProjectControlResultSchema, receipt = z.object({ operationRef: stableUriSchema, action: z.enum(['SET_SCOPE', 'SET_LIFECYCLE']), result, committedAt: isoDateTimeSchema }).strict();
+const purpose = z.object({ state: z.enum(['READY', 'NOT_REGISTERED', 'UNAVAILABLE', 'INTEGRITY_MISMATCH']), revisionRef: stableUriSchema.nullable(), identity: z.object({ name: z.string().max(256), summary: z.string().max(4000), domains: z.array(z.string().max(256)).max(32), domainTotal: z.number().int().min(0).max(256), notes: z.string().max(1000).nullable(), notesTruncated: z.boolean() }).strict().nullable(), scopes: z.array(z.object({ scopeId: z.string().max(128), title: z.string().max(256), description: z.string().max(512), descriptionTruncated: z.boolean(), sourceRequirementCount: z.number().int().min(0).max(256), sourceFamilyCount: z.number().int().min(0).max(256) }).strict()).max(20), scopeTotal: z.number().int().min(0).max(1000).nullable(), nextAfter: cursor.nullable() }).strict();
+const selection = z.object({ state: z.enum(['READY', 'NOT_AUTHORIZED', 'UNAVAILABLE', 'BUDGET_EXCEEDED']), mode: z.enum(['TENANT', 'EXPLICIT']).nullable(), revision: sha256Schema.nullable(), selectors: z.array(z.object({ type: z.enum(['REF', 'SOURCE_PROJECT']), value: z.string().min(1).max(4096) }).strict()).max(20), nextAfter: cursor.nullable() }).strict();
+export const tenantProjectDataSchemas = {
+    tenant_project_list: z.object({ items: z.array(z.object({ projectKey: projectKeySchema, state: z.enum(['ACTIVE', 'ARCHIVED']) }).strict()).max(100), nextAfter: cursor.nullable(), coverage: z.literal('OWN_TENANT_PROJECTS') }).strict(),
+    tenant_project_get: z.object({ projectKey: projectKeySchema, state: z.enum(['ACTIVE', 'ARCHIVED']), lifecycleRevision: sha256Schema, controlReady: z.boolean(), purpose, selection, receipt: receipt.nullable() }).strict(),
+    tenant_project_materials: z.object({ projectKey: projectKeySchema, policy: z.literal('TENANT_PROJECT_SCOPE'), items: z.array(resourceDirectoryItemSchema).max(100), nextAfter: cursor.nullable() }).strict(),
+    tenant_project_scope_set: z.object({ projectKey: projectKeySchema, replayed: z.boolean(), receipt, current: result, completedPhase: z.literal('PROJECT_CONTROL_COMMITTED'), operationRef: stableUriSchema }).strict(),
+    tenant_project_lifecycle_set: z.object({ projectKey: projectKeySchema, replayed: z.boolean(), receipt, current: result, completedPhase: z.literal('PROJECT_CONTROL_COMMITTED'), operationRef: stableUriSchema }).strict(),
+};
+export const tenantProjectErrorSchema = tenantManagementErrorSchema.extend({ completedPhase: z.enum([...tenantManagementErrorSchema.shape.completedPhase.unwrap().options, 'PROJECT_CONTROL_COMMITTED']).optional() }).strict();
+export const tenantProjectWorkspaceToolSchemas = { ...tenantWorkspaceToolSchemas, ...tenantProjectToolSchemas };
+export const tenantProjectWorkspaceDataSchemas = { ...tenantWorkspaceDataSchemas, ...tenantProjectDataSchemas };
+export function tenantProjectScopesForInput(name, raw) { if (Object.hasOwn(tenantProjectToolSchemas, name)) {
+    tenantProjectToolSchemas[name].parse(raw);
+    return name === 'tenant_project_scope_set' ? ['knowledge.workflow.read', 'knowledge.material.scope'] : name === 'tenant_project_lifecycle_set' ? ['knowledge.workflow.read', 'knowledge.project.manage'] : name === 'tenant_project_materials' ? ['knowledge.material.read'] : ['knowledge.workflow.read'];
+} return tenantWorkspaceScopesForInput(name, raw); }
+export function tenantProjectAuthorization(name) { if (Object.hasOwn(tenantProjectToolSchemas, name)) {
+    const scopes = name === 'tenant_project_scope_set' ? ['knowledge.workflow.read', 'knowledge.material.scope'] : name === 'tenant_project_lifecycle_set' ? ['knowledge.workflow.read', 'knowledge.project.manage'] : name === 'tenant_project_materials' ? ['knowledge.material.read'] : ['knowledge.workflow.read'];
+    return { selection: 'FIXED', scopeAlternatives: [scopes] };
+} return tenantWorkspaceAuthorization(name); }
+export function tenantProjectEnvelopeSchema(tool) { return z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, tool: z.literal(tool), data: tenantProjectWorkspaceDataSchemas[tool] }).strict(); }
+export const tenantProjectInputJsonSchemas = Object.fromEntries(Object.entries(tenantProjectWorkspaceToolSchemas).map(([name, schema]) => [name, z.toJSONSchema(schema, { target: 'draft-07' })]));
+export const tenantProjectOutputJsonSchemas = Object.fromEntries(Object.keys(tenantProjectWorkspaceToolSchemas).map(name => [name, { type: 'object', oneOf: [z.toJSONSchema(tenantProjectEnvelopeSchema(name), { target: 'draft-07' }), z.toJSONSchema(tenantProjectErrorSchema, { target: 'draft-07' })] }]));
+export const tenantProjectProviderSchema = tenantManagementProviderBaseSchema.extend({ schemaVersion: z.literal(19), projectContentEndpoint: stableUriSchema, projectContentPolicyHeader: z.literal('x-knowledge-authority-policy'), projectContentProjectHeader: z.literal('x-knowledge-project-key'), projectControlIdentitySchemaVersion: z.literal(19), tools: z.array(z.string()).length(Object.keys(tenantProjectWorkspaceToolSchemas).length), capabilities: z.tuple([z.literal('TENANT_MANAGEMENT_V1'), z.literal('TENANT_WORKFLOW_V1'), z.literal('TENANT_CURRENTNESS_V2'), z.literal('TENANT_SOURCE_V1'), z.literal('TENANT_WORKSPACE_METADATA_V1'), z.literal('TENANT_PROJECT_CONTEXT_V1')]) }).strict().superRefine((value, ctx) => { if (new Set(value.tools).size !== Object.keys(tenantProjectWorkspaceToolSchemas).length || value.tools.some(name => !Object.hasOwn(tenantProjectWorkspaceToolSchemas, name)))
+    ctx.addIssue({ code: 'custom', message: 'Project workspace tools must match the exact version19 contract' }); });