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

package/dist/internal/contracts/source.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, projectKeySchema, schemaVersionSchema, stableUriSchema, } from './common.js';
+export const sourceKindSchema = z.enum([
+    'WEB',
+    'API',
+    'FILE',
+    'REPOSITORY',
+    'FEED',
+    'SOCIAL',
+    'BROWSER',
+    'MANUAL',
+    'OTHER',
+]);
+export const sourceDefinitionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    sourceId: idSchema,
+    projectKey: projectKeySchema.optional(),
+    kind: sourceKindSchema,
+    authority: z.string().trim().min(1).max(256),
+    access: accessClassificationSchema,
+    canonicalUri: stableUriSchema.optional(),
+    refreshPolicy: z.string().trim().min(1).max(256),
+    enabled: z.boolean(),
+    tags: z.array(z.string().trim().min(1).max(128)).max(64).default([]),
+}).strict();
+export const collectorDefinitionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    collectorId: idSchema,
+    version: z.string().trim().min(1).max(128),
+    supportedSourceKinds: z.array(sourceKindSchema).min(1),
+    capabilities: z.array(z.string().trim().min(1).max(128)).max(64),
+}).strict();

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

@@ -0,0 +1,34 @@
+/** Host-authored admission accounting, independent of business authorization and receipt schemas. */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { materialTenantIdSchema } from './material-context.js';
+import { isoDateTimeSchema } from './common.js';
+import { parseTenantCollectionBatchRef } from './tenant-collection.js';
+import { tenantStorageKey } from './resource-scope.js';
+const positive = (max) => z.number().int().min(1).max(max);
+export const tenantBudgetPolicySchema = z.object({ tenantId: materialTenantIdSchema, maxInFlight: positive(32), maxWorkUnits: positive(1_000_000), maxRuntimeMs: positive(86_400_000), weight: positive(8), paused: z.boolean() }).strict();
+export const tenantBudgetConfigSchema = z.object({ schemaVersion: z.literal(1), windowSeconds: z.number().int().min(60).max(86400), maxInFlight: positive(128), maxWaitRounds: positive(2048), tenants: z.array(tenantBudgetPolicySchema).min(1).max(128) }).strict().superRefine((value, ctx) => {
+    if (new Set(value.tenants.map(t => t.tenantId)).size !== value.tenants.length || value.tenants.some(t => t.maxInFlight > value.maxInFlight) || value.tenants.reduce((sum, t) => sum + t.weight, 0) > value.maxWaitRounds)
+        ctx.addIssue({ code: 'custom', message: 'Unique Tenants, Host limits and weighted waiting bound are required' });
+});
+export const tenantBudgetCandidateSchema = z.object({ key: z.string().regex(/^[a-f0-9]{64}$/), tenantId: materialTenantIdSchema, workUnits: positive(100_000), runtimeMs: z.number().int().min(1000).max(7_200_000) }).strict();
+export const tenantBudgetReservationSchema = tenantBudgetCandidateSchema.extend({ admissionId: z.string().uuid(), nodeId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/), startedAt: isoDateTimeSchema, expiresAt: isoDateTimeSchema, windowStart: isoDateTimeSchema }).strict();
+export const tenantBudgetReasonSchema = z.enum(['READY', 'TENANT_UNCONFIGURED', 'PAUSED', 'HOST_IN_FLIGHT', 'TENANT_IN_FLIGHT', 'WORK_BUDGET', 'TIME_BUDGET', 'WORK_ACTIVE']);
+/** 两小时是整个准入的硬上限；短任务保留结算余量，合法的上限任务不因此被排除。 */
+export function tenantLegacyAdmissionRuntimeMs(timeoutSeconds) {
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 30 || timeoutSeconds > 7200)
+        throw new Error('TENANT_LEGACY_TIMEOUT_INVALID');
+    return Math.min(7_200_000, timeoutSeconds * 1000 + 2000);
+}
+export function tenantCollectionAdmissionKey(tenantId, batchRef) {
+    const batch = parseTenantCollectionBatchRef(batchRef);
+    if (!batch || batch.storageKey !== tenantStorageKey(tenantId))
+        throw new Error('TENANT_BUDGET_WORK_SCOPE_INVALID');
+    return createHash('sha256').update(JSON.stringify(['TENANT_COLLECTION_ADMISSION_V1', tenantId, batchRef])).digest('hex');
+}
+export function tenantLegacyAdmissionKey(tenantId, workloadId) {
+    materialTenantIdSchema.parse(tenantId);
+    if (typeof workloadId !== 'string' || workloadId.length > 256 || !/^project:[A-Za-z0-9][A-Za-z0-9._-]{0,127}:.+$/.test(workloadId))
+        throw new Error('TENANT_BUDGET_WORK_SCOPE_INVALID');
+    return createHash('sha256').update(JSON.stringify(['TENANT_LEGACY_ADMISSION_V1', tenantId, workloadId])).digest('hex');
+}

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

@@ -0,0 +1,58 @@
+/** 请求归因与 project-blind 批次分离；只保存委托身份，不保存可使用的 token。 */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, stableUriSchema, sha256Schema } from './common.js';
+import { resourceScopeSchema, tenantStorageKey, parseTenantResourceRef, tenantResourceRefSchema } from './resource-scope.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { knowledgeActorContextSchema } from './project-intent.js';
+import { tenantCollectionPlanSchema, tenantCollectionCycleSchema, tenantCollectionBatchIdentity, tenantCapturedEvidenceIdentity } from './tenant-collection.js';
+export const tenantCollectionRequestAuthoritySchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('HOST') }).strict(),
+    z.object({ type: z.literal('OAUTH'), authorityVersion: z.literal(2), clientId: idSchema, grantId: idSchema, resource: stableUriSchema }).strict(),
+]);
+export function tenantCollectionRequestKey(requestId) { return createHash('sha256').update(tenantCollectionCycleSchema.parse(requestId)).digest('hex'); }
+export function tenantCollectionRequestRef(tenantId, requestId) { return `tenant-collection-request://${tenantStorageKey(tenantId)}/${tenantCollectionRequestKey(requestId)}`; }
+export const tenantCollectionRequestSchema = z.object({
+    schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, requestId: tenantCollectionCycleSchema, requestRef: stableUriSchema,
+    context: resourceScopeSchema, actor: knowledgeActorContextSchema, authority: tenantCollectionRequestAuthoritySchema,
+    plan: tenantCollectionPlanSchema, trigger: z.enum(['MANUAL', 'DUE']), cycleId: tenantCollectionCycleSchema, batchId: z.string().regex(/^batch_[a-f0-9]{64}$/), batchRef: stableUriSchema, requestedAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    const expected = tenantCollectionBatchIdentity(value.tenantId, value.plan.revision, value.trigger, value.cycleId);
+    if (value.context.tenantId !== value.tenantId || value.actor.tenantId !== value.tenantId || value.plan.tenantId !== value.tenantId || value.requestRef !== tenantCollectionRequestRef(value.tenantId, value.requestId))
+        ctx.addIssue({ code: 'custom', path: ['context'], message: 'Request must retain exact Tenant/context/request identity' });
+    if (value.batchId !== expected.batchId || value.batchRef !== expected.batchRef)
+        ctx.addIssue({ code: 'custom', path: ['batchRef'], message: 'Request cannot retarget a different frozen batch' });
+    if (value.trigger === 'DUE' && value.authority.type !== 'HOST')
+        ctx.addIssue({ code: 'custom', path: ['trigger'], message: 'Only an explicit Host dispatcher may request DUE' });
+});
+const completionV1 = z.object({
+    schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, requestRef: stableUriSchema, batchRef: stableUriSchema,
+    phase: z.enum(['RAW_REGISTERED', 'DERIVED_REGISTERED']), evidenceRef: stableUriSchema, contentHash: sha256Schema,
+    runId: idSchema, runtimeNodeId: idSchema, completedAt: isoDateTimeSchema,
+}).strict();
+export const tenantCollectionCompletionSchema = z.union([completionV1, completionV1.extend({ schemaVersion: z.literal(2), phase: z.literal('DERIVED_REGISTERED'), documentRef: tenantResourceRefSchema }).strict()]);
+export function assertTenantCollectionCompletion(request, raw) {
+    const completion = tenantCollectionCompletionSchema.parse(raw), expected = tenantCapturedEvidenceIdentity({ tenantId: request.tenantId, batchRef: request.batchRef, sourceRevisionRef: request.plan.source.revisionRef });
+    const expectedPhase = request.plan.source.semantics.representation.format === 'RAW' ? 'RAW_REGISTERED' : 'DERIVED_REGISTERED';
+    if (completion.tenantId !== request.tenantId || completion.requestRef !== request.requestRef || completion.batchRef !== request.batchRef || completion.evidenceRef !== expected.ref || completion.phase !== expectedPhase)
+        throw new Error('TENANT_COLLECTION_COMPLETION_MISMATCH');
+    if (expectedPhase === 'DERIVED_REGISTERED') {
+        const document = completion.schemaVersion === 2 ? parseTenantResourceRef(completion.documentRef) : null;
+        if (!document || document.storageKey !== tenantStorageKey(request.tenantId) || document.resourceType !== 'source_document')
+            throw new Error('TENANT_COLLECTION_DERIVATION_UNPROVEN');
+    }
+    else if (completion.schemaVersion !== 1)
+        throw new Error('TENANT_COLLECTION_COMPLETION_MISMATCH');
+    return completion;
+}
+/** Admission retirement is not acquisition failure or business completion. */
+export const TENANT_REQUEST_ADMISSION_STOP_CAPABILITY = 'TENANT_REQUEST_ADMISSION_STOP_V1';
+export const tenantCollectionAdmissionStopSchema = z.object({ schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, requestRef: stableUriSchema, requestHash: sha256Schema, reason: z.enum(['GRANT_REVOKED', 'DELEGATION_SUPERSEDED']), stoppedAt: isoDateTimeSchema }).strict();
+/** Acquisition outcome only: a failed request is neither completed nor delegation-retired. */
+export const tenantCollectionFailureSchema = z.object({
+    schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, requestRef: stableUriSchema, requestHash: sha256Schema, batchRef: stableUriSchema,
+    runId: idSchema, runtimeNodeId: idSchema, receiptHash: sha256Schema, failedAt: isoDateTimeSchema, errorCode: z.literal('TENANT_SOURCE_HTTP_TERMINAL'),
+}).strict();
+export function isTenantCollectionTerminalFailure(request, receipt) {
+    return receipt.status === 'FAILED' && receipt.errorCode === 'TENANT_SOURCE_HTTP_TERMINAL' && receipt.workloadId === request.plan.workloadId && receipt.collectionBatchRef === request.batchRef && receipt.inputFingerprint === request.plan.revision && receipt.projectRef === undefined && receipt.projectIntentRef === undefined && receipt.evidenceCount === 0 && receipt.observationCount === 0 && Date.parse(receipt.finishedAt) >= Date.parse(receipt.startedAt) && request.plan.source.semantics.target.kind === 'URL' && request.plan.source.semantics.credential.type === 'PUBLIC';
+}

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