@native-knowledge/knowledge-sdk 0.1.0-rc.1 → 0.1.0-rc.2

package/dist/internal/contracts/tenant-collection.js

@@ -0,0 +1,66 @@
+/** 新批次只冻结真实 Tenant/Source/执行输入；用途和请求归因留在管理审计，collector 看不到它们。 */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { isoDateTimeSchema, sha256Schema, stableUriSchema } from './common.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantStorageKey, tenantResourceRefs } from './resource-scope.js';
+import { tenantSourceSnapshotSchema, tenantSourceIdSchema, parseTenantSourceRevisionRef } from './tenant-source.js';
+export const tenantCollectionCycleSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/);
+export const tenantCollectionMaxBytesSchema = z.number().int().min(1024).max(64 * 1024 * 1024);
+const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function planIdentity(tenantId, sourceRevisionRef, semanticKey, maxResourceBytes) {
+    const revision = 'sha256:' + hash(['TENANT_COLLECTION_PLAN_V1', sourceRevisionRef, semanticKey, maxResourceBytes]), key = tenantStorageKey(tenantId);
+    return { revision, planRef: `tenant-collection-plan://${key}/${revision.slice(7)}`, workloadId: `tenant:${key}:collect:${revision.slice(7)}` };
+}
+export const tenantCollectionPlanSchema = z.object({ schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, source: tenantSourceSnapshotSchema, maxResourceBytes: tenantCollectionMaxBytesSchema, revision: sha256Schema, planRef: stableUriSchema, workloadId: z.string().min(1).max(256) }).strict().superRefine((value, ctx) => {
+    const expected = planIdentity(value.tenantId, value.source.revisionRef, value.source.semanticKey, value.maxResourceBytes);
+    if (value.source.tenantId !== value.tenantId)
+        ctx.addIssue({ code: 'custom', path: ['tenantId'], message: 'Plan Source must belong to the exact Tenant' });
+    for (const key of ['revision', 'planRef', 'workloadId'])
+        if (value[key] !== expected[key])
+            ctx.addIssue({ code: 'custom', path: [key], message: 'Frozen plan identity mismatch' });
+});
+export function createTenantCollectionPlan(raw, maxBytes = 16 * 1024 * 1024) {
+    const source = tenantSourceSnapshotSchema.parse(raw), maxResourceBytes = tenantCollectionMaxBytesSchema.parse(maxBytes);
+    return tenantCollectionPlanSchema.parse({ schemaVersion: 1, tenantId: source.tenantId, source, maxResourceBytes, ...planIdentity(source.tenantId, source.revisionRef, source.semanticKey, maxResourceBytes) });
+}
+export function parseTenantCollectionPlanRef(ref) { const match = /^tenant-collection-plan:\/\/([a-f0-9]{64})\/([a-f0-9]{64})$/.exec(ref); return match ? { storageKey: match[1], revision: 'sha256:' + match[2] } : null; }
+export function tenantCollectionBatchIdentity(tenantId, planRevision, trigger, cycleId) {
+    const batchId = 'batch_' + hash(['TENANT_COLLECTION_BATCH_V1', tenantId, sha256Schema.parse(planRevision), trigger, tenantCollectionCycleSchema.parse(cycleId)]);
+    return { batchId, batchRef: `tenant-collection-batch://${tenantStorageKey(tenantId)}/${batchId}` };
+}
+export function parseTenantCollectionBatchRef(ref) { const match = /^tenant-collection-batch:\/\/([a-f0-9]{64})\/(batch_[a-f0-9]{64})$/.exec(ref); return match ? { storageKey: match[1], batchId: match[2] } : null; }
+export function tenantCapturedEvidenceIdentity(input) {
+    const batch = parseTenantCollectionBatchRef(input.batchRef), source = parseTenantSourceRevisionRef(input.sourceRevisionRef), key = tenantStorageKey(input.tenantId);
+    if (!batch || !source || batch.storageKey !== key || source.storageKey !== key)
+        throw new Error('TENANT_CAPTURE_IDENTITY_MISMATCH');
+    const resourceId = 'ev_' + hash(['TENANT_CAPTURE_V1', input.batchRef, input.sourceRevisionRef]);
+    return { resourceId, ...tenantResourceRefs({ tenantId: input.tenantId, resourceType: 'evidence', resourceId, version: 1 }) };
+}
+export const tenantCollectionBatchSchema = z.object({
+    schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, sourceId: tenantSourceIdSchema, sourceRevisionRef: stableUriSchema,
+    planRef: stableUriSchema, planRevision: sha256Schema, cycleId: tenantCollectionCycleSchema, trigger: z.enum(['MANUAL', 'DUE']), createdAt: isoDateTimeSchema,
+    batchId: z.string().regex(/^batch_[a-f0-9]{64}$/), batchRef: stableUriSchema,
+}).strict().superRefine((value, ctx) => {
+    const source = parseTenantSourceRevisionRef(value.sourceRevisionRef), plan = parseTenantCollectionPlanRef(value.planRef), key = tenantStorageKey(value.tenantId), expected = tenantCollectionBatchIdentity(value.tenantId, value.planRevision, value.trigger, value.cycleId);
+    if (!source || source.storageKey !== key || source.sourceId !== value.sourceId || !plan || plan.storageKey !== key || plan.revision !== value.planRevision)
+        ctx.addIssue({ code: 'custom', path: ['sourceRevisionRef'], message: 'Batch must retain exact Tenant Source and plan identity' });
+    if (value.batchId !== expected.batchId || value.batchRef !== expected.batchRef)
+        ctx.addIssue({ code: 'custom', path: ['batchRef'], message: 'Batch identity mismatch' });
+});
+/** ACQUIRED 是原件事实；Catalog、登记和派生状态由各自阶段回执报告。 */
+export const tenantCollectionCaptureSchema = z.object({
+    schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, batchRef: stableUriSchema, sourceRevisionRef: stableUriSchema, taskId: z.string().regex(/^task_[a-f0-9]{64}$/),
+    evidenceRef: stableUriSchema, contentHash: sha256Schema, byteLength: z.number().int().nonnegative().max(64 * 1024 * 1024), mediaType: z.string().trim().min(1).max(256),
+    observedAt: isoDateTimeSchema, finalLocator: stableUriSchema, httpStatus: z.number().int().min(100).max(599).nullable(), acquisitionRevision: z.string().max(4096).nullable(), headersRecorded: z.boolean(),
+}).strict().superRefine((value, ctx) => {
+    try {
+        if (tenantCapturedEvidenceIdentity(value).ref !== value.evidenceRef)
+            ctx.addIssue({ code: 'custom', path: ['evidenceRef'], message: 'Capture must retain exact batch/source Evidence identity' });
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', path: ['batchRef'], message: 'Capture Tenant identity mismatch' });
+    }
+    if (!value.headersRecorded && (value.httpStatus !== null || value.acquisitionRevision !== null))
+        ctx.addIssue({ code: 'custom', path: ['headersRecorded'], message: 'Recovery cannot invent missing acquisition headers' });
+});

package/dist/internal/contracts/tenant-currentness.js

@@ -0,0 +1,26 @@
+/** 原生资料的快照时效不把 raw carrier 冒充 Evidence，也不证明外部业务事实。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { currentnessAssessmentSchema, currentnessPolicySchema } from './currentness.js';
+import { knowledgeActorContextSchema } from './project-intent.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantStorageKey, tenantResourceRefSchema, parseTenantResourceRef } from './resource-scope.js';
+import { sha256Schema, isoDateTimeSchema, stableUriSchema } from './common.js';
+import { tenantInvocationAuthoritySchema, tenantManagementRequestIdSchema } from './tenant-management.js';
+export function tenantSnapshotDeclarationRef(tenantId, subjectRef) { return `tenant-currentness://${tenantStorageKey(tenantId)}/snapshot/${createHash('sha256').update(tenantResourceRefSchema.parse(subjectRef)).digest('hex')}`; }
+const identity = { tenantId: materialTenantIdSchema, subjectRef: tenantResourceRefSchema, resourceType: z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/), contentHash: sha256Schema };
+const identityValid = (value) => { const ref = parseTenantResourceRef(value.subjectRef); return ref?.storageKey === tenantStorageKey(value.tenantId) && ref.resourceType === value.resourceType; };
+export const tenantSnapshotDeclarationSchema = z.object({ schemaVersion: z.literal(1), ref: stableUriSchema, ...identity, basis: z.literal('RETAINED_SNAPSHOT'), snapshotAt: isoDateTimeSchema, sourceRevisionRef: stableUriSchema.optional(), policy: currentnessPolicySchema, declaredAt: isoDateTimeSchema, actor: knowledgeActorContextSchema, authority: tenantInvocationAuthoritySchema }).strict().superRefine((v, ctx) => {
+    if (!identityValid(v) || v.ref !== tenantSnapshotDeclarationRef(v.tenantId, v.subjectRef) || v.actor.tenantId !== v.tenantId || !v.actor.userId || Date.parse(v.snapshotAt) > Date.parse(v.declaredAt))
+        ctx.addIssue({ code: 'custom', message: 'Snapshot declaration retains actual resource, actor and original observation time' });
+    if ([v.policy.staleAction, v.policy.unknownAction, v.policy.blockedAction].includes('ALLOW'))
+        ctx.addIssue({ code: 'custom', message: 'Unknown, blocked and stale snapshots cannot become ALLOW' });
+});
+export const tenantMaterialCurrentnessSchema = z.object({ ...currentnessAssessmentSchema.shape }).omit({ schemaVersion: true, subjectKind: true, projectRef: true }).extend({ schemaVersion: z.literal(2), subjectKind: z.literal('MATERIAL'), ...identity, basis: z.literal('RETAINED_SNAPSHOT'), basisRef: tenantResourceRefSchema, declarationRef: stableUriSchema }).strict().superRefine((v, ctx) => {
+    if (!identityValid(v) || v.basisRef !== v.subjectRef || v.declarationRef !== tenantSnapshotDeclarationRef(v.tenantId, v.subjectRef) || v.lastSuccessAt === null || v.observedAt !== v.lastSuccessAt || v.lastAttemptAt !== v.lastSuccessAt || Date.parse(v.lastSuccessAt) > Date.parse(v.assessedAt))
+        ctx.addIssue({ code: 'custom', message: 'Currentness retains exact saved snapshot identity and original time' });
+    if ([v.policy.staleAction, v.policy.unknownAction, v.policy.blockedAction].includes('ALLOW'))
+        ctx.addIssue({ code: 'custom', message: 'Snapshot policy fails closed' });
+});
+export const tenantSnapshotInputSchema = z.object({ requestId: tenantManagementRequestIdSchema, subjectRef: tenantResourceRefSchema, expectedContentHash: sha256Schema, freshnessSeconds: z.number().int().min(60).max(86400) }).strict();
+export function tenantMaterialCurrentnessRevision(raw) { return 'sha256:' + createHash('sha256').update(JSON.stringify(tenantMaterialCurrentnessSchema.parse(raw))).digest('hex'); }

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

@@ -0,0 +1,27 @@
+/** 新 Tenant 管理输入与操作归因；身份/actor/来源 origin 不能由正文注入。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { artifactIdSchema, reviewDecisionSchema } from './artifact.js';
+import { accessClassificationSchema, isoDateTimeSchema, sha256Schema, stableUriSchema } from './common.js';
+import { knowledgeActorContextSchema } from './project-intent.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantStorageKey, tenantResourceRefSchema } from './resource-scope.js';
+import { tenantCollectionRequestAuthoritySchema } from './tenant-collection-request.js';
+import { tenantCompositionDraftSchema } from './tenant-rich-document.js';
+import { publicationProfileSchema } from './rich-document.js';
+export const tenantManagementRequestIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/);
+export const tenantInvocationAuthoritySchema = tenantCollectionRequestAuthoritySchema;
+export function tenantOperationRef(tenantId, requestId) { return `tenant-operation://${tenantStorageKey(tenantId)}/${createHash('sha256').update(tenantManagementRequestIdSchema.parse(requestId)).digest('hex')}`; }
+export const tenantManagementIntentSchema = z.object({ schemaVersion: z.literal(1), requestId: tenantManagementRequestIdSchema, tenantId: materialTenantIdSchema, ref: stableUriSchema, action: z.string().min(1).max(64), inputHash: sha256Schema, actor: knowledgeActorContextSchema, authority: tenantInvocationAuthoritySchema, receivedAt: isoDateTimeSchema }).strict().superRefine((v, ctx) => { if (v.actor.tenantId !== v.tenantId || v.ref !== tenantOperationRef(v.tenantId, v.requestId))
+    ctx.addIssue({ code: 'custom', message: 'Operation retains exact Tenant, actor and request identity' }); });
+const request = { requestId: tenantManagementRequestIdSchema }, version = { expectedVersion: z.number().int().nonnegative().safe() }, refs = z.array(stableUriSchema).max(256);
+export const tenantRawSubmissionSchema = z.object({ ...request, title: z.string().trim().min(1).max(512), summary: z.string().max(1024).default(''), mediaType: z.string().trim().min(1).max(256), access: accessClassificationSchema.default('INTERNAL'), claimedSourceRefs: z.array(stableUriSchema).max(127).default([]) }).strict();
+export const tenantArtifactDraftSchema = z.object({ ...request, ...version, artifactId: artifactIdSchema, kind: z.enum(['RESEARCH', 'KNOWLEDGE', 'INSIGHT']), title: z.string().trim().min(1).max(500), mediaType: z.string().trim().min(1).max(256), access: accessClassificationSchema.default('INTERNAL'), observedAt: isoDateTimeSchema.nullable().default(null), validUntil: isoDateTimeSchema.nullable().default(null), sourceRefs: refs.default([]), evidenceRefs: refs.default([]), relatedRefs: refs.default([]) }).strict();
+export const tenantReviewInputSchema = z.object({ ...request, targetRef: tenantResourceRefSchema, expectedVersion: z.number().int().positive().safe(), decision: reviewDecisionSchema.shape.decision, reviewedAt: isoDateTimeSchema, summary: reviewDecisionSchema.shape.summary, sourceRefs: refs.default([]) }).strict();
+export const tenantPromoteInputSchema = z.object({ ...request, targetRef: tenantResourceRefSchema, expectedVersion: z.number().int().positive().safe(), nextStatus: z.enum(['READY_FOR_REVIEW', 'APPROVED', 'REWORK_REQUIRED', 'REJECTED']), reviewRef: tenantResourceRefSchema.optional() }).strict();
+export const tenantComposeInputSchema = z.object({ ...request, ...version, artifactId: artifactIdSchema, sourceRefs: z.array(stableUriSchema).min(1).max(64), primarySourceRef: stableUriSchema.optional(), title: z.string().trim().min(1).max(500).optional(), outputKind: z.enum(['KNOWLEDGE', 'INSIGHT']).default('KNOWLEDGE'), publicationProfile: publicationProfileSchema.default('KNOWLEDGE_CARD_V1'), validUntil: isoDateTimeSchema.nullable().default(null), composition: tenantCompositionDraftSchema.optional(), sourceDocuments: z.array(z.object({ sourceRef: stableUriSchema, documentRef: stableUriSchema }).strict()).max(64).default([]) }).strict().superRefine((v, ctx) => { if (new Set(v.sourceRefs).size !== v.sourceRefs.length || v.primarySourceRef && !v.sourceRefs.includes(v.primarySourceRef) || new Set(v.sourceDocuments.map(row => row.sourceRef)).size !== v.sourceDocuments.length || v.sourceDocuments.some(row => !v.sourceRefs.includes(row.sourceRef)))
+    ctx.addIssue({ code: 'custom', message: 'Source selection must be unique and exact' }); });
+export const tenantReviewDecisionSchema = z.object({ schemaVersion: z.literal(2), format: z.literal('TENANT_REVIEW_DECISION_V1'), targetRef: tenantResourceRefSchema, decision: reviewDecisionSchema.shape.decision, reviewedAt: isoDateTimeSchema, summary: reviewDecisionSchema.shape.summary, sourceRefs: refs }).strict();
+export const tenantShareInputSchema = z.object({ requestId: tenantManagementRequestIdSchema, recipientTenantId: materialTenantIdSchema, matchType: z.enum(['SOURCE', 'REF']), matchValue: stableUriSchema, effect: z.enum(['ALLOW', 'DENY']).default('ALLOW') }).strict().superRefine((v, ctx) => { if (v.effect === 'DENY' && v.matchType !== 'REF')
+    ctx.addIssue({ code: 'custom', message: 'DENY requires an exact resource ref' }); });
+export const tenantRevokeShareInputSchema = z.object({ requestId: tenantManagementRequestIdSchema, routeId: z.string().regex(/^[a-f0-9]{64}$/) }).strict();

package/dist/internal/contracts/tenant-material-api.js

@@ -0,0 +1,46 @@
+/** Tenant material wire contract. Project selection is explicit; provenance is never an authorization context. */
+import { z } from 'zod';
+import { tenantMaterialLegacyJsonSchema } from './tenant-material-json-schema.js';
+import { stableUriSchema, projectKeySchema, sha256Schema } from './common.js';
+import { rawRetrievalDecisionSchema, rawContentDescriptorSchema, rawMaterialDirectoryItemSchema } from './material-read.js';
+import { materialCapabilitySchema } from './material-capability.js';
+import { materialContextSchema } from './material-context.js';
+import { materialResourceTypeSchema } from './material-carrier.js';
+const context = { projectRef: stableUriSchema.optional() }, limit = z.number().int().min(1).max(20).optional(), after = stableUriSchema.optional(), filters = { resourceType: materialResourceTypeSchema.optional(), sourceProjectKey: projectKeySchema.optional() };
+const ref = z.object({ ...context, ref: stableUriSchema }).strict();
+export const tenantMaterialToolSchemas = {
+    knowledge_material_list: z.object({ ...context, after, limit, ...filters, refPrefix: z.string().regex(/^[a-z][a-z0-9+.-]*:\/\/[!-~]*$/i).max(256).optional() }).strict(),
+    knowledge_material_describe: ref,
+    knowledge_material_read: ref,
+    knowledge_material_capabilities: ref,
+    knowledge_material_changes: z.object({ ...context, afterSeq: z.number().int().nonnegative().safe().optional(), limit }).strict(),
+    knowledge_material_window: z.object(context).strict(),
+    knowledge_material_search: z.object({ ...context, query: z.string().min(2).max(200), afterId: z.number().int().nonnegative().safe().optional(), limit, ...filters }).strict(),
+    knowledge_material_partitions: z.object({ ...context, afterRouteId: z.string().regex(/^[a-f0-9]{64}$/).optional(), limit }).strict(),
+    knowledge_material_partition_page: z.object({ ...context, partition: z.enum(['OWNER']), after, limit }).strict(),
+    knowledge_material_route_page: z.object({ ...context, routeId: z.string().regex(/^[a-f0-9]{64}$/), after, limit }).strict(),
+    knowledge_material_media: ref.extend({ afterOrdinal: z.number().int().min(-1).safe().optional(), limit, documentRef: stableUriSchema.optional() }).strict(),
+    knowledge_material_index_status: z.object({ ...context, afterSourceKey: projectKeySchema.optional(), afterNodeId: z.string().min(1).max(128).optional(), sourceProjectKey: projectKeySchema.optional(), limit }).strict(),
+};
+export const tenantMaterialEnvelopeSchema = z.object({ schemaVersion: z.literal(1), context: materialContextSchema, data: z.unknown() }).strict();
+export const tenantMaterialToolInputSchemas = Object.fromEntries(Object.entries(tenantMaterialToolSchemas).map(([name, schema]) => [name, tenantMaterialLegacyJsonSchema(schema)]));
+const nonnegative = z.number().int().nonnegative().safe(), refPosition = stableUriSchema.nullable(), items = z.array(rawMaterialDirectoryItemSchema).max(100), description = z.object({ item: rawMaterialDirectoryItemSchema.nullable(), byteLength: nonnegative.nullable(), downloadUrl: z.string().max(8192).nullable() }).strict();
+const read = z.object({ item: rawMaterialDirectoryItemSchema.nullable(), byteLength: nonnegative.nullable(), decision: rawRetrievalDecisionSchema, descriptor: rawContentDescriptorSchema.nullable(), delivery: z.enum(['INLINE_BASE64', 'DOWNLOAD', 'UNAVAILABLE']), contentBase64: z.string().max(43692).nullable(), downloadUrl: z.string().max(8192).nullable(), verification: z.enum(['VERIFIED', 'NOT_VERIFIED']) }).strict();
+const route = 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();
+const representation = materialCapabilitySchema.shape.representation;
+export const tenantMaterialDataSchemas = {
+    knowledge_material_list: z.object({ items, nextAfter: refPosition }).strict(),
+    knowledge_material_describe: description,
+    knowledge_material_read: read,
+    knowledge_material_capabilities: materialCapabilitySchema.nullable(),
+    knowledge_material_changes: z.object({ items: z.array(z.object({ seq: nonnegative, eventType: z.enum(['MATERIAL_REGISTERED', 'MATERIAL_LINEAGE_CHANGED', 'ROUTE_CHANGED', 'PROJECT_SCOPE_CHANGED']), artifactRef: stableUriSchema.nullable(), contentHash: sha256Schema.nullable(), routeId: z.string().regex(/^[a-f0-9]{64}$/).nullable(), createdAt: z.string().datetime() }).strict()).max(100), nextAfter: nonnegative.nullable() }).strict(),
+    knowledge_material_window: z.object({ retainedThroughSeq: nonnegative, headSeq: nonnegative }).strict(),
+    knowledge_material_search: z.object({ items: z.array(z.object({ item: rawMaterialDirectoryItemSchema, title: z.string().max(512), summary: z.string().max(1024) }).strict()).max(20), nextAfterId: nonnegative.nullable(), indexState: z.enum(['PARTIAL_BACKFILL', 'SYNCED_AS_OF_LAST_OBSERVATION']), configuredSourceCount: nonnegative, sourceCountIsLowerBound: z.boolean(), queryCoverage: z.literal('DESCRIPTIVE_METADATA_V1'), order: z.literal('INDEX_ROWID_ASC') }).strict(),
+    knowledge_material_partitions: z.object({ owner: z.literal('OWNER'), items: z.array(route).max(100), nextAfterRouteId: z.string().regex(/^[a-f0-9]{64}$/).nullable() }).strict(),
+    knowledge_material_partition_page: z.object({ partition: z.literal('OWNER'), items, nextAfter: refPosition }).strict(),
+    knowledge_material_route_page: z.object({ routeState: z.enum(['ACTIVE', 'REVOKED', 'UNBOUND']), items, nextAfter: refPosition }).strict().nullable(),
+    knowledge_material_media: z.object({ 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: 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: nonnegative.nullable(), state: z.enum(['READY', 'REMOTE_ONLY', 'UNAVAILABLE', 'MISSING', 'DENIED', 'INTEGRITY_MISMATCH']), representation: representation.nullable() }).strict()).max(100), nextAfterOrdinal: nonnegative.nullable() }).strict().nullable(),
+    knowledge_material_index_status: z.object({ 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(z.object({ sourceProjectKey: projectKeySchema, nodeId: z.string().min(1).max(128), directoryThroughSeq: nonnegative, searchThroughSeq: nonnegative.nullable(), observedMaxSeq: nonnegative.nullable(), checkpointUpdatedAt: z.string().datetime().nullable(), state: z.enum(['SYNCED_AS_OF_CHECKPOINT', 'PARTIAL_BACKFILL']) }).strict()).max(100), nextAfter: z.object({ sourceProjectKey: projectKeySchema, nodeId: z.string().min(1).max(128) }).strict().nullable() }).strict(),
+};
+export const tenantMaterialToolOutputSchemas = Object.fromEntries(Object.entries(tenantMaterialDataSchemas).map(([name, data]) => [name, tenantMaterialLegacyJsonSchema(tenantMaterialEnvelopeSchema.extend({ data }))]));
+export const tenantMaterialProviderSchema = z.object({ schemaVersion: z.literal(14), provider: z.literal('knowledge-v2'), codeRevision: z.string().min(1).max(256), context: z.literal('TENANT_DEFAULT_PROJECT_EXPLICIT'), scope: z.literal('knowledge.material.read'), mcpEndpoint: stableUriSchema, resource: stableUriSchema, issuer: stableUriSchema, tokenEndpoint: stableUriSchema, revocationEndpoint: stableUriSchema, protocols: z.array(z.string().max(32)).min(1).max(2), tenantReadEnabled: z.boolean(), projectScopeEnabled: z.boolean(), externalTenantParameter: z.literal('external_tenant_id'), materialEndpoint: stableUriSchema, authorizationEndpoint: stableUriSchema, authorizationContextParameters: z.tuple([z.literal('tenant_ref'), z.literal('project_ref')]), tools: z.array(z.string()).max(32), projectScopeManagement: z.literal('knowledge.material.scope'), inlineMaxBytes: z.literal(32768), rawUsagePolicy: z.literal('CONSUMER_DECIDES'), referenceReadMaxBytes: z.literal(16777216) }).strict();

package/dist/internal/contracts/tenant-material-json-schema.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/** Preserve Provider14 discovery bytes; validation still uses the patched Zod schemas. */
+export function tenantMaterialLegacyJsonSchema(schema) {
+    return z.toJSONSchema(schema, { target: 'draft-07', override: ({ zodSchema, jsonSchema }) => {
+            const def = zodSchema._zod.def;
+            if (def.type !== 'number')
+                return;
+            const last = def.checks?.at(-1)?._zod.def;
+            // Zod4.5 .safe() replaced advertised bounds; newer Zod correctly intersects them.
+            // Only this frozen discovery envelope retains that historical representation.
+            if (last?.check === 'number_format' && 'format' in last && last.format === 'safeint') {
+                jsonSchema.minimum = Number.MIN_SAFE_INTEGER;
+                jsonSchema.maximum = Number.MAX_SAFE_INTEGER;
+            }
+        } });
+}

package/dist/internal/contracts/tenant-pdf-text.js

@@ -0,0 +1,13 @@
+/** Bounded PDF text projection, with real page locators; OCR is a distinct capability. */
+import { z } from 'zod';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { parseTenantResourceRef, tenantStorageKey } from './resource-scope.js';
+export const TENANT_PDF_TEXT_MEDIA_TYPE = 'application/vnd.native-knowledge.pdf-text+json';
+export const tenantPdfTextSchema = z.object({ schemaVersion: z.literal(1), format: z.literal('TENANT_PDF_TEXT_V1'), tenantId: materialTenantIdSchema, parentEvidenceRef: z.string().max(1024), sourceContentHash: sha256Schema, sourceByteLength: z.number().int().min(5).max(8 * 1024 * 1024), sourceMediaType: z.string().min(1).max(256), sourceUri: z.string().url().max(2048), observedAt: isoDateTimeSchema, extractedAt: isoDateTimeSchema, extractor: z.object({ id: z.literal('native-knowledge.pdf-text'), version: z.literal('1.0.0') }).strict(), pages: z.array(z.object({ page: z.number().int().min(1).max(100), locator: z.string().url().max(2080), text: z.string().max(64000) }).strict()).min(1).max(100), gaps: z.array(z.enum(['TENANT_PDF_OCR_REQUIRED'])).max(1) }).strict().superRefine((v, c) => {
+    const p = parseTenantResourceRef(v.parentEvidenceRef);
+    if (!p || p.storageKey !== tenantStorageKey(v.tenantId) || p.resourceType !== 'evidence')
+        c.addIssue({ code: 'custom', message: 'Exact Tenant PDF parent required' });
+    if (v.pages.some((p, i) => p.page !== i + 1 || p.locator !== v.sourceUri + '#page=' + p.page) || v.pages.reduce((n, p) => n + p.text.length, 0) > 2000000 || !v.pages.some(p => p.text.trim()) || v.pages.some(p => !p.text.trim()) !== v.gaps.includes('TENANT_PDF_OCR_REQUIRED'))
+        c.addIssue({ code: 'custom', message: 'Page identity, text budget or OCR gap mismatch' });
+});

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

@@ -0,0 +1,19 @@
+/** Project controls select purpose/context; receipts do not own Tenant assets or lifecycle state. */
+import { z } from 'zod';
+import { sha256Schema, stableUriSchema, isoDateTimeSchema, projectKeySchema } from './common.js';
+import { materialTenantIdSchema, materialProjectScopeInputSchema } from './material-context.js';
+import { knowledgeActorContextSchema } from './project-intent.js';
+import { tenantManagementRequestIdSchema, tenantInvocationAuthoritySchema, tenantOperationRef } from './tenant-management.js';
+import { tenantStorageKey } from './resource-scope.js';
+export const tenantProjectScopeChangeSchema = z.object({ requestId: tenantManagementRequestIdSchema, projectKey: projectKeySchema, expectedRevision: sha256Schema, changes: materialProjectScopeInputSchema }).strict();
+export const tenantProjectLifecycleChangeSchema = z.object({ requestId: tenantManagementRequestIdSchema, projectKey: projectKeySchema, expectedRevision: sha256Schema, state: z.enum(['ACTIVE', 'ARCHIVED']) }).strict();
+export const tenantProjectControlResultSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('SCOPE'), changed: z.boolean(), mode: z.enum(['TENANT', 'EXPLICIT']), revision: sha256Schema }).strict(),
+    z.object({ type: z.literal('LIFECYCLE'), changed: z.boolean(), state: z.enum(['ACTIVE', 'ARCHIVED']), revision: sha256Schema }).strict(),
+]);
+export const tenantProjectControlReceiptSchema = z.object({ schemaVersion: z.literal(1), operationRef: stableUriSchema, tenantId: materialTenantIdSchema, projectKey: projectKeySchema, action: z.enum(['SET_SCOPE', 'SET_LIFECYCLE']), inputHash: sha256Schema, actor: knowledgeActorContextSchema, authority: tenantInvocationAuthoritySchema, result: tenantProjectControlResultSchema, committedAt: isoDateTimeSchema }).strict().superRefine((value, ctx) => {
+    const prefix = `tenant-operation://${tenantStorageKey(value.tenantId)}/`;
+    if (value.actor.tenantId !== value.tenantId || !value.operationRef.startsWith(prefix) || !/^[a-f0-9]{64}$/.test(value.operationRef.slice(prefix.length)) || value.action !== (value.result.type === 'SCOPE' ? 'SET_SCOPE' : 'SET_LIFECYCLE'))
+        ctx.addIssue({ code: 'custom', message: 'Project control receipt preserves exact Tenant, action and operation identity' });
+});
+export { tenantOperationRef as tenantProjectOperationRef };

package/dist/internal/contracts/tenant-public-reference.js

@@ -0,0 +1,26 @@
+/** 原生公共 Reference 候选/receipt 格式3；不改旧 Project release 和 publication wire。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { projectKeySchema, sha256Schema, isoDateTimeSchema } from './common.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantResourceRefSchema, parseTenantResourceRef, tenantStorageKey } from './resource-scope.js';
+import { publicReferenceCatalogueScopeSchema, publicReferenceLegacyReviewSchema } from './public-reference.js';
+export const TENANT_PUBLIC_REFERENCE_LIMITS = { records: 256, sources: 256, totalBytes: 16 * 1024 * 1024, recordBytes: 1024 * 1024 };
+export const tenantPublicReferenceRecordIdentitySchema = z.object({ ref: tenantResourceRefSchema, digest: sha256Schema, contentHash: sha256Schema }).strict();
+const records = z.array(tenantPublicReferenceRecordIdentitySchema).min(1).max(TENANT_PUBLIC_REFERENCE_LIMITS.records).superRefine((rows, ctx) => { if (new Set(rows.map(row => row.ref)).size !== rows.length || rows.some(row => parseTenantResourceRef(row.ref)?.resourceType !== 'reference'))
+    ctx.addIssue({ code: 'custom', message: 'Unique exact native Reference versions required' }); });
+export const tenantPublicReferenceReviewSchema = publicReferenceLegacyReviewSchema.safeExtend({ approvedSources: z.array(z.object({ sourceRef: tenantResourceRefSchema.refine(ref => parseTenantResourceRef(ref)?.resourceType === 'evidence'), contentHash: sha256Schema }).strict()).min(1).max(TENANT_PUBLIC_REFERENCE_LIMITS.sources) });
+export const tenantPublicReferencePublishInputSchema = z.object({ schemaVersion: z.literal(3), publicationKey: projectKeySchema, corpusKey: projectKeySchema, records, catalogue: publicReferenceCatalogueScopeSchema, review: tenantPublicReferenceReviewSchema }).strict();
+export const tenantPublicReferencePublicationBasisSchema = z.object({ schemaVersion: z.literal(3), visibility: z.literal('PUBLIC_REFERENCE'), source: z.object({ type: z.literal('TENANT'), tenantId: materialTenantIdSchema }).strict(), corpusKey: projectKeySchema, records, recordsContentHash: sha256Schema, recordsByteLength: z.number().int().positive().max(TENANT_PUBLIC_REFERENCE_LIMITS.totalBytes), recordCount: z.number().int().positive().max(TENANT_PUBLIC_REFERENCE_LIMITS.records), recordTypes: z.array(projectKeySchema).min(1).max(128), sourceCreatedAt: isoDateTimeSchema, catalogue: publicReferenceCatalogueScopeSchema, review: tenantPublicReferenceReviewSchema, publishedAt: isoDateTimeSchema, checkedAt: isoDateTimeSchema, validUntil: isoDateTimeSchema }).strict();
+export function tenantPublicReferencePublicationDigest(raw) { return 'sha256:' + createHash('sha256').update(JSON.stringify(tenantPublicReferencePublicationBasisSchema.parse(raw))).digest('hex'); }
+export const tenantPublicReferencePublicationSchema = tenantPublicReferencePublicationBasisSchema.extend({ publicationId: sha256Schema, publicationRef: z.string().regex(/^public-reference:\/\/[a-f0-9]{64}$/) }).strict().superRefine((v, ctx) => {
+    const { publicationId, publicationRef, ...basis } = v, key = tenantStorageKey(v.source.tenantId);
+    if (publicationId !== tenantPublicReferencePublicationDigest(basis) || publicationRef !== 'public-reference://' + publicationId.slice(7) || v.records.length !== v.recordCount || v.records.some(row => parseTenantResourceRef(row.ref)?.storageKey !== key))
+        ctx.addIssue({ code: 'custom', message: 'Tenant publication identity mismatch' });
+    if (v.records.some((row, index) => index > 0 && row.ref <= v.records[index - 1].ref) || new Set(v.recordTypes).size !== v.recordTypes.length || v.review.approvedSources.some(row => parseTenantResourceRef(row.sourceRef)?.storageKey !== key))
+        ctx.addIssue({ code: 'custom', message: 'Canonical publication records and same-Tenant sources required' });
+    if (Date.parse(v.validUntil) <= Date.parse(v.publishedAt) || Date.parse(v.checkedAt) > Date.parse(v.publishedAt) || Date.parse(v.review.reviewedAt) > Date.parse(v.publishedAt) || Date.parse(v.review.reviewedAt) < Math.max(Date.parse(v.sourceCreatedAt), Date.parse(v.checkedAt)))
+        ctx.addIssue({ code: 'custom', message: 'Tenant publication chronology invalid' });
+});
+const directoryPublication = z.object({ ...tenantPublicReferencePublicationBasisSchema.shape }).omit({ review: true, records: true }).extend({ publicationId: sha256Schema, publicationRef: tenantPublicReferencePublicationSchema.shape.publicationRef, reviewedAt: isoDateTimeSchema }).strict();
+export const tenantPublicReferenceDirectorySchema = z.object({ schemaVersion: z.literal(3), contentClass: z.literal('PUBLIC_REFERENCE_DIRECTORY'), coverageProof: z.literal(false), items: z.array(z.object({ publication: directoryPublication, manifestRequired: z.literal(true), availability: z.enum(['NOT_YET_PUBLISHED', 'AVAILABLE', 'STALE']) }).strict()).max(100), nextAfter: sha256Schema.nullable() }).strict();

package/dist/internal/contracts/tenant-resource-api.js

@@ -0,0 +1,70 @@
+/** Provider 16 的格式 2 资源读取合同；旧 Project/Tenant wire 保持其严格 schema。 */
+import { z } from 'zod';
+import { stableUriSchema, projectKeySchema, sha256Schema, accessClassificationSchema } from './common.js';
+import { materialContextSchema } from './material-context.js';
+import { materialAuthorityPolicySchema, resourceScopeSchema, parseTenantResourceRef, tenantStorageKey } from './resource-scope.js';
+import { tenantResourceOriginSchema } from './tenant-resource.js';
+import { rawRetrievalDecisionSchema, rawContentDescriptorSchema } from './material-read.js';
+import { materialResourceTypeSchema } from './material-carrier.js';
+import { tenantMaterialProviderSchema, tenantMaterialDataSchemas } from './tenant-material-api.js';
+export const resourceOriginSchema = z.union([tenantResourceOriginSchema, z.object({ type: z.literal('LEGACY_PROJECT'), projectKey: projectKeySchema, projectRef: stableUriSchema }).strict()]);
+export const resourceDirectoryItemSchema = z.object({
+    ref: stableUriSchema, ownerTenantId: resourceScopeSchema.options[0].shape.tenantId, resourceType: materialResourceTypeSchema,
+    origin: resourceOriginSchema, identityHash: sha256Schema, identityKind: z.enum(['CAS_BYTES', 'REFERENCE_RECORD_DIGEST']),
+    kind: z.string().min(1).max(128), classification: accessClassificationSchema, mediaType: z.string().min(1).max(256),
+    title: z.string().max(512), summary: z.string().max(1024), decision: rawRetrievalDecisionSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.origin.type === 'LEGACY_PROJECT') {
+        if (value.origin.projectRef !== `knowledge-project://${value.origin.projectKey}/tenant/${encodeURIComponent(value.ownerTenantId)}` || value.identityKind !== (value.resourceType === 'reference' ? 'REFERENCE_RECORD_DIGEST' : 'CAS_BYTES'))
+            ctx.addIssue({ code: 'custom', path: ['origin'], message: 'Legacy origin/identity mismatch' });
+    }
+    else {
+        const ref = parseTenantResourceRef(value.ref), key = tenantStorageKey(value.ownerTenantId);
+        if (!ref || ref.storageKey !== key || ref.resourceType !== value.resourceType || value.identityKind !== 'CAS_BYTES')
+            ctx.addIssue({ code: 'custom', path: ['ref'], message: 'Native owner/resource identity mismatch' });
+        if (value.origin.type === 'TENANT_AUTHOR' && value.origin.actor.tenantId !== value.ownerTenantId)
+            ctx.addIssue({ code: 'custom', path: ['origin'], message: 'Author Tenant mismatch' });
+        if (value.origin.type === 'TENANT_SOURCE') {
+            const prefix = `tenant-source://${key}/${encodeURIComponent(value.origin.sourceId)}`;
+            if (value.origin.sourceRef !== prefix || !value.origin.sourceRevisionRef.startsWith(prefix + '/v/') || !/^[a-f0-9]{64}$/.test(value.origin.sourceRevisionRef.slice(prefix.length + 3)))
+                ctx.addIssue({ code: 'custom', path: ['origin'], message: 'Source Tenant/revision mismatch' });
+        }
+    }
+});
+const context = { projectRef: stableUriSchema.optional() }, position = z.string().min(1).max(4096).optional(), limit = z.number().int().min(1).max(100).optional();
+const filters = { resourceType: materialResourceTypeSchema.optional(), sourceProjectKey: projectKeySchema.optional(), refPrefix: z.string().max(256).regex(/^[a-z][a-z0-9+.-]*:\/\/[!-~]*$/i).optional() };
+const ref = z.object({ ...context, ref: stableUriSchema }).strict();
+export const resourceToolSchemas = {
+    knowledge_resource_list: z.object({ ...context, after: position, limit, ...filters }).strict(),
+    knowledge_resource_describe: ref, knowledge_resource_read: ref, knowledge_resource_capabilities: ref,
+    knowledge_resource_search: z.object({ ...context, after: position, limit, ...filters, query: z.string().min(2).max(200) }).strict(),
+    knowledge_resource_window: z.object(context).strict(),
+    knowledge_resource_changes: z.object({ ...context, after: position, limit }).strict(),
+    knowledge_resource_counts: z.object({ ...context, after: position, limit }).strict(),
+    knowledge_resource_index_status: z.object(context).strict(),
+    knowledge_resource_media: ref.extend({ afterOrdinal: z.number().int().min(-1).safe().optional(), limit, documentRef: stableUriSchema.optional() }).strict(),
+};
+const count = z.number().int().nonnegative().safe(), cursor = z.string().max(4096).nullable(), item = resourceDirectoryItemSchema.nullable(), items = z.array(resourceDirectoryItemSchema).max(100);
+const representation = z.object({ state: z.enum(['READY', 'UNSUPPORTED', 'MISSING', 'INTEGRITY_MISMATCH', 'DENIED']), format: z.enum(['JSON', 'BYTES']), transfer: z.enum(['BUFFERED_JSON', 'VERIFIED_STREAM', 'UNSUPPORTED']), contentHash: sha256Schema.nullable(), mediaType: z.string().min(1).max(256), byteLength: count.nullable(), methods: z.array(z.enum(['GET', 'HEAD', 'POST'])).max(3), range: z.enum(['SINGLE', 'NONE']), verification: z.literal('ON_READ'), verificationChunkBytes: count.nullable() }).strict();
+export const resourceDataSchemas = {
+    knowledge_resource_list: z.object({ items, nextAfter: cursor }).strict(),
+    knowledge_resource_describe: z.object({ item, byteLength: count.nullable(), downloadUrl: z.string().max(8192).nullable() }).strict(),
+    knowledge_resource_read: z.object({ item, byteLength: count.nullable(), decision: rawRetrievalDecisionSchema, descriptor: rawContentDescriptorSchema.nullable(), delivery: z.enum(['INLINE_BASE64', 'DOWNLOAD', 'UNAVAILABLE']), contentBase64: z.string().max(43692).nullable(), downloadUrl: z.string().max(8192).nullable(), verification: z.enum(['VERIFIED', 'NOT_VERIFIED']) }).strict(),
+    knowledge_resource_capabilities: z.object({ item, materialAccess: rawRetrievalDecisionSchema, representation: representation.nullable() }).strict(),
+    knowledge_resource_search: z.object({ items, nextAfter: cursor, coverage: z.literal('INDEXED_DESCRIPTIONS_ONLY') }).strict(),
+    knowledge_resource_window: z.object({ headSeq: count, retainedThroughSeq: count, headCursor: z.string().max(4096), retentionCursor: z.string().max(4096), epoch: z.literal('TENANT_RESOURCE_V1') }).strict(),
+    knowledge_resource_changes: z.object({ items: z.array(z.object({ seq: count, eventType: z.string().min(1).max(128), artifactRef: stableUriSchema.nullable(), contentHash: sha256Schema.nullable(), routeId: z.string().max(128).nullable(), createdAt: z.string().datetime({ offset: true }) }).strict()).max(100), nextAfter: cursor }).strict(),
+    knowledge_resource_counts: z.object({ owned: count, granted: count, available: count, resourceTypes: z.array(z.object({ resourceType: materialResourceTypeSchema, total: count }).strict()).max(100), nextAfter: cursor, coverage: z.literal('CURRENT_AUTHORIZED_DIRECTORY') }).strict(),
+    knowledge_resource_index_status: z.object({ registered: count, indexed: count, unindexed: count, state: z.enum(['SYNCED_AS_OF_LAST_OBSERVATION', 'PARTIAL_BACKFILL']), canonicalInventory: z.literal('NOT_SCANNED'), coverage: z.literal('CURRENT_AUTHORIZED_DIRECTORY') }).strict(),
+    knowledge_resource_media: tenantMaterialDataSchemas.knowledge_material_media,
+};
+export const resourceEnvelopeSchema = z.object({ schemaVersion: z.literal(2), context: materialContextSchema, policy: materialAuthorityPolicySchema, data: z.unknown() }).strict().superRefine((value, ctx) => {
+    const c = value.context, expected = c.type === 'TENANT' ? `knowledge-tenant://tenant/${encodeURIComponent(c.tenantId)}` : `knowledge-project://${c.projectKey}/tenant/${encodeURIComponent(c.tenantId)}`;
+    if ((value.policy === 'TENANT_NATIVE') !== (c.type === 'TENANT') || (c.type === 'TENANT' ? c.tenantRef : c.projectRef) !== expected)
+        ctx.addIssue({ code: 'custom', path: ['context'], message: 'Context/policy identity mismatch' });
+});
+export const resourceToolInputSchemas = Object.fromEntries(Object.entries(resourceToolSchemas).map(([name, schema]) => [name, z.toJSONSchema(schema, { target: 'draft-07' })]));
+export const resourceToolOutputSchemas = Object.fromEntries(Object.entries(resourceDataSchemas).map(([name, data]) => [name, z.toJSONSchema(resourceEnvelopeSchema.safeExtend({ data }), { target: 'draft-07' })]));
+export const tenantResourceProviderSchema = tenantMaterialProviderSchema.extend({ schemaVersion: z.literal(16), materialSchemaVersion: z.literal(2), capabilities: z.tuple([z.literal('TENANT_RESOURCE_V1'), z.literal('TENANT_AUTHORITY_V1')]), legacyProviderEndpoint: stableUriSchema });
+export const resourceHttpContractSchema = z.object({ schemaVersion: z.literal(2), context: materialContextSchema, policy: materialAuthorityPolicySchema, capabilities: z.tuple([z.literal('TENANT_RESOURCE_V1'), z.literal('TENANT_AUTHORITY_V1')]), callEndpoint: z.string().min(1).max(8192), fileEndpoint: z.string().min(1).max(8192), tools: z.array(z.string()).max(32), inlineMaxBytes: z.literal(32768), readBufferMaxBytes: z.literal(16777216), fileMethods: z.tuple([z.literal('GET'), z.literal('HEAD'), z.literal('POST')]), verificationChunkBytes: z.literal(65536), requestMaxBytes: z.literal(131072), resultMaxBytes: z.literal(524288) }).strict().superRefine((value, ctx) => { if (!resourceEnvelopeSchema.safeParse({ schemaVersion: 2, context: value.context, policy: value.policy, data: null }).success)
+    ctx.addIssue({ code: 'custom', path: ['context'], message: 'Context/policy identity mismatch' }); });

package/dist/internal/contracts/tenant-resource.js

@@ -0,0 +1,118 @@
+/** 租户原生不可变信封保留类型事实；不以项目占位或审核状态判断原文读取。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, sha256Schema, stableUriSchema } from './common.js';
+import { artifactManifestSchema } from './artifact.js';
+import { evidenceRefSchema } from './evidence.js';
+import { referenceCorpusSummarySchema } from './reference-record.js';
+import { knowledgeActorContextSchema } from './project-intent.js';
+import { materialResourceTypeSchema } from './material-carrier.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantResourceIdentitySchema, tenantResourceRefs, tenantStorageKey, tenantResourceRefSchema } from './resource-scope.js';
+// 取原有字段验证器，旧 schema/DTO 原样保留；新信封的身份关系在下方集中验证。
+const artifactFacts = z.object({ ...artifactManifestSchema.shape }).omit({ schemaVersion: true, projectKey: true, projectRef: true, ref: true, identityRef: true, contentHash: true, mediaType: true, byteLength: true, access: true, createdAt: true }).extend({ sourceMaterialRefs: z.array(stableUriSchema).max(256).optional() }).strict();
+const evidenceFacts = z.object({ ...evidenceRefSchema.shape }).omit({ schemaVersion: true, projectKey: true, projectRef: true, recoveryProvenance: true, contentHash: true, mediaType: true, byteLength: true, access: true }).extend({ parentEvidenceRef: tenantResourceRefSchema.optional() }).strict();
+const referenceFacts = z.object({ ...referenceCorpusSummarySchema.shape }).omit({ schemaVersion: true, projectKey: true, projectRef: true, recordRef: true, access: true }).strict();
+export const tenantResourceFactsSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('ARTIFACT'), metadata: artifactFacts }).strict(),
+    z.object({ type: z.literal('EVIDENCE'), metadata: evidenceFacts }).strict(),
+    z.object({ type: z.literal('REFERENCE'), metadata: referenceFacts }).strict(),
+    z.object({ type: z.literal('CARRIER'), metadata: z.object({ kind: z.string().min(1).max(128), title: z.string().max(512), summary: z.string().max(1024), sourceRefs: z.array(stableUriSchema).min(1).max(128), observedAt: isoDateTimeSchema }).strict() }).strict(),
+]);
+export const tenantResourceOriginSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('TENANT_AUTHOR'), actor: knowledgeActorContextSchema, submittedAt: isoDateTimeSchema }).strict(),
+    z.object({ type: z.literal('TENANT_SOURCE'), sourceId: idSchema, sourceRef: stableUriSchema, sourceRevisionRef: stableUriSchema, collector: evidenceRefSchema.shape.collector, runtimeNodeId: idSchema, observedAt: isoDateTimeSchema }).strict(),
+]);
+export const tenantResourceManifestSchema = z.object({
+    schemaVersion: z.literal(2), ownerTenantId: materialTenantIdSchema,
+    resourceId: tenantResourceIdentitySchema.shape.resourceId, resourceType: materialResourceTypeSchema,
+    version: tenantResourceIdentitySchema.shape.version, ref: stableUriSchema, identityRef: stableUriSchema,
+    contentHash: sha256Schema, byteLength: z.number().int().nonnegative().safe(), mediaType: z.string().trim().min(1).max(256),
+    access: accessClassificationSchema, createdAt: isoDateTimeSchema,
+    origin: tenantResourceOriginSchema, facts: tenantResourceFactsSchema,
+}).strict().superRefine((value, ctx) => {
+    const expected = tenantResourceRefs({ tenantId: value.ownerTenantId, resourceType: value.resourceType, resourceId: value.resourceId, version: value.version });
+    for (const name of ['ref', 'identityRef'])
+        if (value[name] !== expected[name])
+            ctx.addIssue({ code: 'custom', path: [name], message: 'Tenant resource identity mismatch' });
+    const kind = value.facts.type.toLowerCase();
+    if (value.facts.type === 'CARRIER' ? ['artifact', 'evidence', 'reference', 'media'].includes(value.resourceType) : value.resourceType !== kind)
+        ctx.addIssue({ code: 'custom', path: ['resourceType'], message: 'Resource type must retain its factual carrier' });
+    if (value.origin.type === 'TENANT_AUTHOR') {
+        if (value.origin.actor.tenantId !== value.ownerTenantId)
+            ctx.addIssue({ code: 'custom', path: ['origin'], message: 'Author must belong to the resource Tenant' });
+    }
+    else {
+        const prefix = `tenant-source://${tenantStorageKey(value.ownerTenantId)}/${encodeURIComponent(value.origin.sourceId)}`;
+        if (value.origin.sourceRef !== prefix || !value.origin.sourceRevisionRef.startsWith(prefix + '/v/') || !/^[a-f0-9]{64}$/.test(value.origin.sourceRevisionRef.slice(prefix.length + 3)))
+            ctx.addIssue({ code: 'custom', path: ['origin'], message: 'Source must retain exact Tenant/source/revision identity' });
+    }
+    if (value.facts.type === 'ARTIFACT') {
+        const m = value.facts.metadata;
+        if (m.artifactId !== value.resourceId || m.version !== value.version)
+            ctx.addIssue({ code: 'custom', path: ['facts'], message: 'Artifact identity/version mismatch' });
+        if (m.validUntil && m.observedAt && Date.parse(m.validUntil) < Date.parse(m.observedAt))
+            ctx.addIssue({ code: 'custom', path: ['facts'], message: 'Invalid Artifact validity interval' });
+        if (m.kind === 'SIGNAL_GENERATION' && (m.version !== 1 || m.status !== 'GENERATED') || ['KNOWLEDGE', 'INSIGHT'].includes(m.kind) && m.status === 'GENERATED')
+            ctx.addIssue({ code: 'custom', path: ['facts'], message: 'Invalid Artifact lifecycle' });
+        const previous = value.version > 1 ? tenantResourceRefs({ tenantId: value.ownerTenantId, resourceType: value.resourceType, resourceId: value.resourceId, version: value.version - 1 }).ref : null;
+        if (m.supersedesRef !== previous)
+            ctx.addIssue({ code: 'custom', path: ['facts'], message: 'Artifact must retain immediate predecessor' });
+    }
+    if (value.facts.type === 'EVIDENCE') {
+        const m = value.facts.metadata;
+        if (m.parentEvidenceRef) {
+            const parent = new URL(m.parentEvidenceRef);
+            if (parent.hostname !== tenantStorageKey(value.ownerTenantId) || !parent.pathname.startsWith('/evidence/') || m.parentEvidenceRef === value.ref)
+                ctx.addIssue({ code: 'custom', path: ['facts'], message: 'Media parent must be another native Tenant Evidence' });
+        }
+        if (m.evidenceId !== value.resourceId || value.version !== 1 || Boolean(m.sourceSetRef) !== Boolean(m.sourceItemId) || Boolean(m.collectionBatchRef) !== Boolean(m.collectionTaskId))
+            ctx.addIssue({ code: 'custom', path: ['facts'], message: 'Evidence identity/bindings mismatch' });
+        if (value.origin.type === 'TENANT_SOURCE' && (m.sourceId !== value.origin.sourceId || m.runtimeNodeId !== value.origin.runtimeNodeId || m.observedAt !== value.origin.observedAt || m.sourceRevisionRef !== value.origin.sourceRevisionRef || JSON.stringify(m.collector) !== JSON.stringify(value.origin.collector)))
+            ctx.addIssue({ code: 'custom', path: ['facts'], message: 'Evidence must preserve acquisition provenance' });
+    }
+    if (value.facts.type === 'REFERENCE') {
+        const m = value.facts.metadata;
+        if (m.version !== value.version || m.effectiveFrom && m.effectiveUntil && Date.parse(m.effectiveUntil) <= Date.parse(m.effectiveFrom))
+            ctx.addIssue({ code: 'custom', path: ['facts'], message: 'Reference version/validity mismatch' });
+        const previous = value.version > 1 ? tenantResourceRefs({ tenantId: value.ownerTenantId, resourceType: value.resourceType, resourceId: value.resourceId, version: value.version - 1 }).ref : null;
+        if (m.supersedesRef !== previous)
+            ctx.addIssue({ code: 'custom', path: ['facts'], message: 'Reference must retain immediate predecessor' });
+    }
+});
+export const tenantProjectionIntentSchema = z.object({ schemaVersion: z.literal(2), ref: tenantResourceRefSchema, manifestRevision: sha256Schema, createdAt: isoDateTimeSchema }).strict();
+/** 存储、Catalog 与 Identity 共用同一 manifest 身份；undefined 等价于 JSON 省略。 */
+export function tenantResourceManifestRevision(raw) {
+    const json = JSON.stringify(tenantResourceManifestSchema.parse(raw));
+    if (Buffer.byteLength(json + '\n') > 64 * 1024)
+        throw new Error('TENANT_RESOURCE_MANIFEST_TOO_LARGE');
+    const canonical = (value) => { if (value === null || typeof value !== 'object')
+        return JSON.stringify(value); if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']'; const row = value; return '{' + Object.keys(row).sort().map(key => JSON.stringify(key) + ':' + canonical(row[key])).join(',') + '}'; };
+    return 'sha256:' + createHash('sha256').update(canonical(JSON.parse(json))).digest('hex');
+}
+/** Reference 语义摘要与 CAS 字节摘要分开；只正规化集合字段，不改原始 payload 字节。 */
+export function tenantReferenceRecordDigest(tenantId, access, metadata, payload) {
+    const parsed = tenantResourceFactsSchema.parse({ type: 'REFERENCE', metadata });
+    if (parsed.type !== 'REFERENCE')
+        throw new Error('TENANT_REFERENCE_FACTS_REQUIRED');
+    const m = parsed.metadata, selectors = m.selectors ? Object.fromEntries(Object.keys(m.selectors).sort().map(key => [key, [...new Set(m.selectors[key])].sort()])) : undefined;
+    const basis = { tenantId: materialTenantIdSchema.parse(tenantId), corpusKey: m.corpusKey, recordKey: m.recordKey, recordType: m.recordType, access: accessClassificationSchema.parse(access), authority: m.authority, jurisdiction: m.jurisdiction, ...(selectors ? { selectors } : {}), sourceRefs: [...new Set(m.sourceRefs)].sort(), effectiveFrom: m.effectiveFrom, effectiveUntil: m.effectiveUntil, payload };
+    let nodes = 0;
+    const canonical = (value, depth = 0) => {
+        if (++nodes > 1_000_000 || depth > 64)
+            throw new Error('TENANT_REFERENCE_JSON_BUDGET_EXCEEDED');
+        if (value === null || typeof value === 'string' || typeof value === 'boolean')
+            return JSON.stringify(value);
+        if (typeof value === 'number' && Number.isFinite(value))
+            return JSON.stringify(value);
+        if (Array.isArray(value))
+            return '[' + value.map(item => canonical(item, depth + 1)).join(',') + ']';
+        if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+            const row = value;
+            return '{' + Object.keys(row).sort().map(key => JSON.stringify(key) + ':' + canonical(row[key], depth + 1)).join(',') + '}';
+        }
+        throw new Error('TENANT_REFERENCE_JSON_INVALID');
+    };
+    return 'sha256:' + createHash('sha256').update(canonical(basis)).digest('hex');
+}

package/dist/internal/contracts/tenant-rich-document.js

@@ -0,0 +1,17 @@
+/** 原生受治理正文引用真实资料类型；Reference/开放载体不被伪装为 Evidence。 */
+import { z } from 'zod';
+import { richDocumentSchema, publicationProfileSchema, validateRichDocumentContent } from './rich-document.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { stableUriSchema } from './common.js';
+export const TENANT_RICH_DOCUMENT_MEDIA_TYPE = 'application/vnd.knowledge-v2.tenant-rich-document+json';
+export const tenantDocumentCitationSchema = z.object({ blockOrdinal: z.number().int().nonnegative(), sourceRefs: z.array(stableUriSchema).min(1).max(32) }).strict().superRefine((value, ctx) => { if (new Set(value.sourceRefs).size !== value.sourceRefs.length)
+    ctx.addIssue({ code: 'custom', path: ['sourceRefs'], message: 'Citation refs must be unique' }); });
+export const tenantCompositionDraftSchema = z.object({ ...richDocumentSchema.shape }).pick({ summary: true, byline: true, language: true, blocks: true }).extend({ summary: z.string().trim().min(1).max(4000), byline: richDocumentSchema.shape.byline.optional(), language: richDocumentSchema.shape.language.optional(), blocks: richDocumentSchema.shape.blocks.min(1), citations: z.array(tenantDocumentCitationSchema).min(1).max(10000) }).strict();
+const base = z.object({ ...richDocumentSchema.shape }).omit({ projectKey: true, projectRef: true, format: true, role: true, publicationProfile: true, sourceEvidenceRefs: true, primarySourceEvidenceRef: true, citations: true });
+export const tenantRichDocumentSchema = base.extend({ format: z.literal('TENANT_RICH_DOCUMENT_V1'), tenantId: materialTenantIdSchema, role: z.enum(['KNOWLEDGE', 'INSIGHT']), publicationProfile: publicationProfileSchema, sourceRefs: z.array(stableUriSchema).min(1).max(256), primarySourceRef: stableUriSchema, representationRefs: z.array(stableUriSchema).max(64).default([]), citations: z.array(tenantDocumentCitationSchema).max(10000).default([]) }).strict().superRefine((value, ctx) => {
+    // 只把字段适配到共同结构规则；身份、真实载体类型与权限由应用层逐 ref 验证。
+    validateRichDocumentContent({ sourceEvidenceRefs: value.sourceRefs, primarySourceEvidenceRef: value.primarySourceRef, mediaEvidenceRefs: value.mediaEvidenceRefs, blocks: value.blocks, citations: value.citations.map(citation => ({ blockOrdinal: citation.blockOrdinal, evidenceRefs: citation.sourceRefs })) }, ctx, { primary: 'primarySourceRef', citation: 'sourceRefs' });
+    if (new Set(value.sourceRefs).size !== value.sourceRefs.length)
+        ctx.addIssue({ code: 'custom', path: ['sourceRefs'], message: 'Sources must be unique' });
+});
+export const tenantPublicationReadinessSchema = z.object({ schemaVersion: z.literal(2), profile: publicationProfileSchema, ready: z.boolean(), reasons: z.array(z.enum(['ROLE_MISMATCH', 'TITLE_REQUIRED', 'SUMMARY_REQUIRED', 'TEXT_TOO_SHORT', 'STRUCTURE_TOO_THIN', 'SOURCE_REQUIRED', 'CITATION_COVERAGE_REQUIRED', 'SOURCE_MISMATCH', 'MEDIA_UNAVAILABLE'])).max(16), metrics: z.object({ textCharacters: z.number().int().nonnegative(), blockCount: z.number().int().nonnegative(), textBlockCount: z.number().int().nonnegative(), mediaBlockCount: z.number().int().nonnegative(), sourceCount: z.number().int().nonnegative(), mediaEvidenceCount: z.number().int().nonnegative(), citationCount: z.number().int().nonnegative(), citedBlockCount: z.number().int().nonnegative() }).strict() }).strict();

package/dist/internal/contracts/tenant-source-binding.js

@@ -0,0 +1,33 @@
+/** 项目用途上下文不参与来源获取等价，不是授权 grant 或可执行过滤 DSL。 */
+import { z } from 'zod';
+import { idSchema, stableUriSchema } from './common.js';
+export const tenantSourceBindingContextSchema = z.object({
+    schemaVersion: z.literal(1), projectIntentRef: stableUriSchema.nullable().default(null),
+    scopeIds: z.array(idSchema).max(256).default([]), sourceFamilies: z.array(idSchema).max(256).default([]), attentionNotes: z.string().max(4000).nullable().default(null),
+}).strict().superRefine((value, ctx) => {
+    for (const key of ['scopeIds', 'sourceFamilies'])
+        if (new Set(value[key]).size !== value[key].length)
+            ctx.addIssue({ code: 'custom', path: [key], message: 'Project demand selectors must be unique' });
+    if ((value.scopeIds.length || value.sourceFamilies.length) && !value.projectIntentRef)
+        ctx.addIssue({ code: 'custom', path: ['projectIntentRef'], message: 'Scoped demand must retain an exact Project Intent revision' });
+    if (value.projectIntentRef && !/^project-intent:\/\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\/[a-f0-9]{64}$/.test(value.projectIntentRef))
+        ctx.addIssue({ code: 'custom', path: ['projectIntentRef'], message: 'Exact Project Intent revision required' });
+});
+import { projectKeySchema, isoDateTimeSchema } from './common.js';
+import { knowledgeActorContextSchema, collectionRefreshSchema } from './project-intent.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantSourceIdSchema } from './tenant-source.js';
+import { tenantStorageKey } from './resource-scope.js';
+export const tenantSourceBindingRevisionSchema = z.object({
+    schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, projectKey: projectKeySchema, sourceId: tenantSourceIdSchema, revisionRef: stableUriSchema,
+    generation: z.number().int().positive().safe(), purpose: z.string().max(4000), refresh: collectionRefreshSchema, enabled: z.boolean(), demandContext: tenantSourceBindingContextSchema,
+    origin: z.enum(['MIGRATED_V13', 'EXPLICIT_V14']), actor: knowledgeActorContextSchema.nullable(), changedAt: isoDateTimeSchema.nullable(),
+}).strict().superRefine((v, ctx) => {
+    const prefix = `tenant-source://${tenantStorageKey(v.tenantId)}/${v.sourceId}/v/`;
+    if (!v.revisionRef.startsWith(prefix) || !/^[a-f0-9]{64}$/.test(v.revisionRef.slice(prefix.length)))
+        ctx.addIssue({ code: 'custom', path: ['revisionRef'], message: 'Binding must retain exact Tenant Source identity' });
+    if (v.demandContext.projectIntentRef && !v.demandContext.projectIntentRef.startsWith(`project-intent://${v.projectKey}/`))
+        ctx.addIssue({ code: 'custom', path: ['demandContext'], message: 'Demand context Project mismatch' });
+    if (v.origin === 'MIGRATED_V13' ? (v.actor !== null || v.changedAt !== null) : (!v.actor || v.actor.tenantId !== v.tenantId || !v.changedAt))
+        ctx.addIssue({ code: 'custom', path: ['origin'], message: 'Migration cannot invent actor/time; explicit changes require attribution' });
+});

package/dist/internal/contracts/tenant-source-bridge.js

@@ -0,0 +1,9 @@
+/** 显式桥接预检确认获取语义；该请求不授予启停或修改工作归属的权限。 */
+import { z } from 'zod';
+import { projectKeySchema, stableUriSchema } from './common.js';
+import { tenantSourceIdSchema, tenantSourceSemanticsSchema } from './tenant-source.js';
+export const tenantSourceBridgePreviewInputSchema = z.object({
+    projectKey: projectKeySchema, legacySourceId: tenantSourceIdSchema, expectedLegacyRevisionRef: stableUriSchema,
+    nativeSourceId: tenantSourceIdSchema, expectedNativeRevisionRef: stableUriSchema,
+    confirmAcquisitionSemantics: tenantSourceSemanticsSchema, maxResourceBytes: z.number().int().min(1024).max(64 * 1024 * 1024),
+}).strict();

package/dist/internal/contracts/tenant-source-cutover.js

@@ -0,0 +1,26 @@
+/** Host 维护切换的冻结事实；不从回执推断真实进程已退出。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { idSchema, isoDateTimeSchema, stableUriSchema } from './common.js';
+import { projectSourceSnapshotSchema, knowledgeActorContextSchema } from './project-intent.js';
+import { tenantCollectionPlanSchema } from './tenant-collection.js';
+import { tenantSourceBindingRevisionSchema, tenantSourceBindingContextSchema } from './tenant-source-binding.js';
+import { tenantStorageKey } from './resource-scope.js';
+import { materialTenantIdSchema } from './material-context.js';
+export const SOURCE_CUTOVER_FENCE_CAPABILITY = 'SOURCE_CUTOVER_FENCE_V1';
+export const sourceCutoverIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/);
+export const sourceCutoverKey = (id) => createHash('sha256').update(sourceCutoverIdSchema.parse(id)).digest('hex');
+export const sourceCutoverRef = (tenantId, id) => `tenant-source-cutover://${tenantStorageKey(tenantId)}/${sourceCutoverKey(id)}`;
+export const sourceCutoverIntentSchema = z.object({
+    schemaVersion: z.literal(1), cutoverId: sourceCutoverIdSchema, cutoverRef: stableUriSchema, tenantId: materialTenantIdSchema, actor: knowledgeActorContextSchema, createdAt: isoDateTimeSchema,
+    legacySource: projectSourceSnapshotSchema, plan: tenantCollectionPlanSchema, existingBinding: tenantSourceBindingRevisionSchema.nullable(),
+    demandContext: tenantSourceBindingContextSchema,
+}).strict().superRefine((v, ctx) => {
+    if (v.cutoverRef !== sourceCutoverRef(v.tenantId, v.cutoverId) || v.actor.tenantId !== v.tenantId || v.legacySource.actor.tenantId !== v.tenantId || v.plan.tenantId !== v.tenantId || v.legacySource.targetId !== v.plan.source.targetId || v.legacySource.access !== v.plan.source.semantics.access || v.demandContext.projectIntentRef !== v.legacySource.projectIntentRef)
+        ctx.addIssue({ code: 'custom', message: 'Cutover must retain exact owner, source and Project demand' });
+    if (v.existingBinding && (v.existingBinding.tenantId !== v.tenantId || v.existingBinding.projectKey !== v.legacySource.projectKey || v.existingBinding.sourceId !== v.plan.source.sourceId))
+        ctx.addIssue({ code: 'custom', path: ['existingBinding'], message: 'Prior binding belongs to another context' });
+});
+export const sourceCutoverStepNameSchema = z.enum(['LEGACY_STOPPED', 'DRAINED', 'ACTIVATED', 'NATIVE_STOPPED', 'NATIVE_DRAINED', 'RESTORE_AUTHORIZED', 'LEGACY_RESTORED', 'ROLLED_BACK']);
+export const sourceCutoverStepSchema = z.object({ schemaVersion: z.literal(1), cutoverRef: stableUriSchema, step: sourceCutoverStepNameSchema, actor: knowledgeActorContextSchema, at: isoDateTimeSchema, details: z.record(z.string().max(64), z.union([z.string().max(4096), z.number().finite(), z.boolean(), z.null()])).refine(v => Object.keys(v).length <= 32) }).strict();
+export const sourceCutoverRuntimeProofSchema = z.object({ nodeId: idSchema, codeRevision: z.string().regex(/^[A-Za-z0-9._-]{7,64}$/), capability: z.literal(SOURCE_CUTOVER_FENCE_CAPABILITY), unmanagedExecutions: z.literal('QUIESCED'), observedAt: isoDateTimeSchema }).strict();