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

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.d.ts

@@ -0,0 +1,298 @@
+/** 租户原生不可变信封保留类型事实；不以项目占位或审核状态判断原文读取。 */
+import { z } from 'zod';
+export declare const tenantResourceFactsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"ARTIFACT">;
+    metadata: z.ZodObject<{
+        artifactId: z.ZodString;
+        kind: z.ZodEnum<{
+            SIGNAL_GENERATION: "SIGNAL_GENERATION";
+            RESEARCH: "RESEARCH";
+            REVIEW: "REVIEW";
+            KNOWLEDGE: "KNOWLEDGE";
+            INSIGHT: "INSIGHT";
+        }>;
+        status: z.ZodEnum<{
+            GENERATED: "GENERATED";
+            DRAFT: "DRAFT";
+            READY_FOR_REVIEW: "READY_FOR_REVIEW";
+            REWORK_REQUIRED: "REWORK_REQUIRED";
+            APPROVED: "APPROVED";
+            REJECTED: "REJECTED";
+            SUPERSEDED: "SUPERSEDED";
+        }>;
+        version: z.ZodNumber;
+        title: z.ZodOptional<z.ZodString>;
+        observedAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        validUntil: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        evidenceRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        relatedRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        supersedesRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        sourceMaterialRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"EVIDENCE">;
+    metadata: z.ZodObject<{
+        observedAt: z.ZodISODateTime;
+        sourceIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        runtimeNodeId: z.ZodString;
+        request: z.ZodOptional<z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            method: z.ZodLiteral<"POST">;
+            bodyContentHash: z.ZodString;
+            bodyMediaType: z.ZodLiteral<"application/x-www-form-urlencoded">;
+            bodyByteLength: z.ZodNumber;
+        }, z.core.$strict>>;
+        sourceId: z.ZodString;
+        sourceRevisionRef: z.ZodOptional<z.ZodString>;
+        collectionBatchRef: z.ZodOptional<z.ZodString>;
+        reviewHints: z.ZodOptional<z.ZodObject<{
+            pageRanges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                startPage: z.ZodNumber;
+                endPage: z.ZodNumber;
+            }, z.core.$strict>>>;
+            timeRanges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                startMs: z.ZodNumber;
+                endMs: z.ZodNumber;
+            }, z.core.$strict>>>;
+            frameTimestampsMs: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strict>>;
+        evidenceId: z.ZodString;
+        collector: z.ZodObject<{
+            collectorId: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strict>;
+        canonicalUri: z.ZodOptional<z.ZodString>;
+        sourceSetRef: z.ZodOptional<z.ZodString>;
+        sourceItemId: z.ZodOptional<z.ZodString>;
+        collectionTaskId: z.ZodOptional<z.ZodString>;
+        parentEvidenceRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"REFERENCE">;
+    metadata: z.ZodObject<{
+        version: z.ZodNumber;
+        supersedesRef: z.ZodNullable<z.ZodString>;
+        effectiveFrom: z.ZodNullable<z.ZodISODateTime>;
+        effectiveUntil: z.ZodNullable<z.ZodISODateTime>;
+        authority: z.ZodString;
+        currentness: z.ZodObject<{
+            state: z.ZodEnum<{
+                DUE: "DUE";
+                CURRENT: "CURRENT";
+                STALE: "STALE";
+                UNAVAILABLE: "UNAVAILABLE";
+                NOT_COVERED: "NOT_COVERED";
+            }>;
+            action: z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>;
+            assessedAt: z.ZodISODateTime;
+            validUntil: z.ZodNullable<z.ZodISODateTime>;
+        }, z.core.$strict>;
+        jurisdiction: z.ZodNullable<z.ZodString>;
+        sourceRefs: z.ZodArray<z.ZodString>;
+        corpusKey: z.ZodString;
+        recordKey: z.ZodString;
+        recordType: z.ZodString;
+        digest: z.ZodString;
+        selectors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"CARRIER">;
+    metadata: z.ZodObject<{
+        kind: z.ZodString;
+        title: z.ZodString;
+        summary: z.ZodString;
+        sourceRefs: z.ZodArray<z.ZodString>;
+        observedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+export declare const tenantResourceOriginSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"TENANT_AUTHOR">;
+    actor: z.ZodObject<{
+        tenantId: z.ZodString;
+        userId: z.ZodString;
+        agentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    submittedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"TENANT_SOURCE">;
+    sourceId: z.ZodString;
+    sourceRef: z.ZodString;
+    sourceRevisionRef: z.ZodString;
+    collector: z.ZodObject<{
+        collectorId: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>;
+    runtimeNodeId: z.ZodString;
+    observedAt: z.ZodISODateTime;
+}, z.core.$strict>], "type">;
+export declare const tenantResourceManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    ownerTenantId: z.ZodString;
+    resourceId: z.ZodString;
+    resourceType: z.ZodString;
+    version: z.ZodNumber;
+    ref: z.ZodString;
+    identityRef: z.ZodString;
+    contentHash: z.ZodString;
+    byteLength: z.ZodNumber;
+    mediaType: z.ZodString;
+    access: z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    createdAt: z.ZodISODateTime;
+    origin: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"TENANT_AUTHOR">;
+        actor: z.ZodObject<{
+            tenantId: z.ZodString;
+            userId: z.ZodString;
+            agentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>;
+        submittedAt: z.ZodISODateTime;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"TENANT_SOURCE">;
+        sourceId: z.ZodString;
+        sourceRef: z.ZodString;
+        sourceRevisionRef: z.ZodString;
+        collector: z.ZodObject<{
+            collectorId: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strict>;
+        runtimeNodeId: z.ZodString;
+        observedAt: z.ZodISODateTime;
+    }, z.core.$strict>], "type">;
+    facts: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"ARTIFACT">;
+        metadata: z.ZodObject<{
+            artifactId: z.ZodString;
+            kind: z.ZodEnum<{
+                SIGNAL_GENERATION: "SIGNAL_GENERATION";
+                RESEARCH: "RESEARCH";
+                REVIEW: "REVIEW";
+                KNOWLEDGE: "KNOWLEDGE";
+                INSIGHT: "INSIGHT";
+            }>;
+            status: z.ZodEnum<{
+                GENERATED: "GENERATED";
+                DRAFT: "DRAFT";
+                READY_FOR_REVIEW: "READY_FOR_REVIEW";
+                REWORK_REQUIRED: "REWORK_REQUIRED";
+                APPROVED: "APPROVED";
+                REJECTED: "REJECTED";
+                SUPERSEDED: "SUPERSEDED";
+            }>;
+            version: z.ZodNumber;
+            title: z.ZodOptional<z.ZodString>;
+            observedAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+            validUntil: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+            evidenceRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            relatedRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            supersedesRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            sourceMaterialRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"EVIDENCE">;
+        metadata: z.ZodObject<{
+            observedAt: z.ZodISODateTime;
+            sourceIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            runtimeNodeId: z.ZodString;
+            request: z.ZodOptional<z.ZodObject<{
+                schemaVersion: z.ZodLiteral<1>;
+                method: z.ZodLiteral<"POST">;
+                bodyContentHash: z.ZodString;
+                bodyMediaType: z.ZodLiteral<"application/x-www-form-urlencoded">;
+                bodyByteLength: z.ZodNumber;
+            }, z.core.$strict>>;
+            sourceId: z.ZodString;
+            sourceRevisionRef: z.ZodOptional<z.ZodString>;
+            collectionBatchRef: z.ZodOptional<z.ZodString>;
+            reviewHints: z.ZodOptional<z.ZodObject<{
+                pageRanges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    startPage: z.ZodNumber;
+                    endPage: z.ZodNumber;
+                }, z.core.$strict>>>;
+                timeRanges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    startMs: z.ZodNumber;
+                    endMs: z.ZodNumber;
+                }, z.core.$strict>>>;
+                frameTimestampsMs: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+            }, z.core.$strict>>;
+            evidenceId: z.ZodString;
+            collector: z.ZodObject<{
+                collectorId: z.ZodString;
+                version: z.ZodString;
+            }, z.core.$strict>;
+            canonicalUri: z.ZodOptional<z.ZodString>;
+            sourceSetRef: z.ZodOptional<z.ZodString>;
+            sourceItemId: z.ZodOptional<z.ZodString>;
+            collectionTaskId: z.ZodOptional<z.ZodString>;
+            parentEvidenceRef: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"REFERENCE">;
+        metadata: z.ZodObject<{
+            version: z.ZodNumber;
+            supersedesRef: z.ZodNullable<z.ZodString>;
+            effectiveFrom: z.ZodNullable<z.ZodISODateTime>;
+            effectiveUntil: z.ZodNullable<z.ZodISODateTime>;
+            authority: z.ZodString;
+            currentness: z.ZodObject<{
+                state: z.ZodEnum<{
+                    DUE: "DUE";
+                    CURRENT: "CURRENT";
+                    STALE: "STALE";
+                    UNAVAILABLE: "UNAVAILABLE";
+                    NOT_COVERED: "NOT_COVERED";
+                }>;
+                action: z.ZodEnum<{
+                    ALLOW: "ALLOW";
+                    REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                    DENY: "DENY";
+                }>;
+                assessedAt: z.ZodISODateTime;
+                validUntil: z.ZodNullable<z.ZodISODateTime>;
+            }, z.core.$strict>;
+            jurisdiction: z.ZodNullable<z.ZodString>;
+            sourceRefs: z.ZodArray<z.ZodString>;
+            corpusKey: z.ZodString;
+            recordKey: z.ZodString;
+            recordType: z.ZodString;
+            digest: z.ZodString;
+            selectors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"CARRIER">;
+        metadata: z.ZodObject<{
+            kind: z.ZodString;
+            title: z.ZodString;
+            summary: z.ZodString;
+            sourceRefs: z.ZodArray<z.ZodString>;
+            observedAt: z.ZodISODateTime;
+        }, z.core.$strict>;
+    }, z.core.$strict>], "type">;
+}, z.core.$strict>;
+export type TenantResourceManifest = z.infer<typeof tenantResourceManifestSchema>;
+export type TenantResourceFacts = z.infer<typeof tenantResourceFactsSchema>;
+export type TenantResourceOrigin = z.infer<typeof tenantResourceOriginSchema>;
+export declare const tenantProjectionIntentSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    ref: z.ZodString;
+    manifestRevision: z.ZodString;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type TenantProjectionIntent = z.infer<typeof tenantProjectionIntentSchema>;
+/** 存储、Catalog 与 Identity 共用同一 manifest 身份；undefined 等价于 JSON 省略。 */
+export declare function tenantResourceManifestRevision(raw: TenantResourceManifest): string;
+/** Reference 语义摘要与 CAS 字节摘要分开；只正规化集合字段，不改原始 payload 字节。 */
+export declare function tenantReferenceRecordDigest(tenantId: string, access: unknown, metadata: Extract<TenantResourceFacts, {
+    type: 'REFERENCE';
+}>['metadata'], payload: unknown): string;

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');
+}