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

package/dist/internal/contracts/reference-record.js

@@ -0,0 +1,55 @@
+/** Canonical Reference facts and producer annotations; no consumer admission policy. */
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema } from './common.js';
+export const referenceRecordTypeSchema = z.string().trim().min(1).max(128).regex(/^[A-Z][A-Z0-9_]*$/);
+export const referenceCurrentnessActionSchema = z.enum(['ALLOW', 'REVIEW_REQUIRED', 'DENY']);
+export const referenceSelectorKeySchema = z.string().trim().min(1).max(64).regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/);
+export const referenceSelectorValueSchema = z.string().trim().min(1).max(256);
+export const referenceSelectorsSchema = z.record(referenceSelectorKeySchema, z.array(referenceSelectorValueSchema).min(1).max(256)).superRefine((value, ctx) => {
+    const keys = Object.keys(value);
+    if (keys.length > 32)
+        ctx.addIssue({ code: 'custom', message: 'Reference selectors cannot exceed 32 keys' });
+    for (const key of keys) {
+        const values = value[key] ?? [];
+        if (new Set(values).size !== values.length)
+            ctx.addIssue({ code: 'custom', path: [key], message: 'Reference selector values must be unique' });
+    }
+});
+export const referenceCurrentnessStateSchema = z.enum(['CURRENT', 'DUE', 'STALE', 'UNAVAILABLE', 'NOT_COVERED']);
+export const referenceCurrentnessSchema = z.object({
+    state: referenceCurrentnessStateSchema, action: referenceCurrentnessActionSchema, assessedAt: isoDateTimeSchema, validUntil: isoDateTimeSchema.nullable(),
+}).strict();
+function validateReferenceIdentity(value, ctx) {
+    const expected = `reference://${value.projectKey}/${encodeURIComponent(value.corpusKey)}/${encodeURIComponent(value.recordKey)}/v/${value.version}`;
+    if (value.recordRef !== expected)
+        ctx.addIssue({ code: 'custom', path: ['recordRef'], message: 'recordRef must match project/corpus/recordKey/version' });
+    if (value.version === 1 && value.supersedesRef !== null)
+        ctx.addIssue({ code: 'custom', path: ['supersedesRef'], message: 'first reference version cannot supersede' });
+    if (value.version > 1) {
+        const previous = `reference://${value.projectKey}/${encodeURIComponent(value.corpusKey)}/${encodeURIComponent(value.recordKey)}/v/${value.version - 1}`;
+        if (value.supersedesRef !== previous)
+            ctx.addIssue({ code: 'custom', path: ['supersedesRef'], message: 'reference version must supersede immediately previous version' });
+    }
+}
+export const referenceCorpusSummarySchema = z.object({
+    schemaVersion: schemaVersionSchema, corpusKey: projectKeySchema, recordKey: idSchema, recordRef: stableUriSchema, recordType: referenceRecordTypeSchema, projectKey: projectKeySchema, projectRef: stableUriSchema.optional(),
+    version: z.number().int().positive(), supersedesRef: stableUriSchema.nullable(),
+    access: accessClassificationSchema, authority: z.string().trim().min(1).max(1000), jurisdiction: z.string().trim().min(1).max(128).nullable(), selectors: referenceSelectorsSchema.optional(),
+    sourceRefs: z.array(stableUriSchema).min(1).max(256), digest: sha256Schema, effectiveFrom: isoDateTimeSchema.nullable(), effectiveUntil: isoDateTimeSchema.nullable(),
+    currentness: referenceCurrentnessSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.projectRef) {
+        try {
+            const url = new URL(value.projectRef);
+            if (url.protocol !== 'knowledge-project:' || url.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'projectRef project must match Reference project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'Invalid projectRef' });
+        }
+    }
+    if (value.effectiveFrom && value.effectiveUntil && Date.parse(value.effectiveUntil) <= Date.parse(value.effectiveFrom))
+        ctx.addIssue({ code: 'custom', path: ['effectiveUntil'], message: 'effectiveUntil must be after effectiveFrom' });
+    validateReferenceIdentity(value, ctx);
+});
+export const referenceCorpusRecordSchema = referenceCorpusSummarySchema.extend({ payload: z.json() }).strict();

package/dist/internal/contracts/remote-file.js

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema } from './common.js';
+export const remoteArchiveFormatSchema = z.enum(['TAR_GZ', 'ZIP']);
+export const remoteManifestFormatSchema = z.enum(['FILES_V1', 'LEGACY_PAGES_V1']);
+export const remoteBundlePathSchema = z.string().trim().min(1).max(1024).superRefine((value, ctx) => {
+    if (value.includes('\0') || value.includes('\\') || value.startsWith('/') || value.endsWith('/')) {
+        ctx.addIssue({ code: 'custom', message: 'remote bundle member path must be a relative file path' });
+        return;
+    }
+    const parts = value.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..')) {
+        ctx.addIssue({ code: 'custom', message: 'remote bundle member path must not contain empty, dot or parent segments' });
+    }
+});
+export const remoteFileBundleDeclarationSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    artifactSha256: sha256Schema,
+    byteLength: z.number().int().positive(),
+    archiveFormat: remoteArchiveFormatSchema,
+    manifestPath: remoteBundlePathSchema,
+    manifestSha256: sha256Schema,
+    artifactKind: idSchema,
+    familyId: idSchema,
+    targetId: idSchema,
+    jurisdiction: z.string().trim().min(1).max(128).nullable(),
+    sourceWorker: idSchema,
+    remoteArtifactRef: stableUriSchema.nullable(),
+    declaredAt: isoDateTimeSchema,
+}).strict();
+export const remoteFileManifestEntrySchema = z.object({
+    path: remoteBundlePathSchema,
+    sha256: sha256Schema,
+    byteLength: z.number().int().nonnegative(),
+    mediaType: z.string().trim().min(1).max(256).nullable().default(null),
+    sourceUrl: z.string().url().max(2048).nullable().default(null),
+}).strict();
+export const remoteFileBundleManifestSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    artifactKind: idSchema,
+    familyId: idSchema,
+    targetId: idSchema,
+    jurisdiction: z.string().trim().min(1).max(128).nullable(),
+    generatedAt: isoDateTimeSchema,
+    files: z.array(remoteFileManifestEntrySchema).min(1).max(10000),
+}).strict().superRefine((value, ctx) => {
+    const seen = new Set();
+    value.files.forEach((entry, index) => {
+        if (seen.has(entry.path))
+            ctx.addIssue({ code: 'custom', path: ['files', index, 'path'], message: 'duplicate manifest file path' });
+        seen.add(entry.path);
+    });
+});
+export const remoteVerifiedFileSchema = z.object({
+    path: remoteBundlePathSchema,
+    contentHash: sha256Schema,
+    byteLength: z.number().int().nonnegative(),
+    mediaType: z.string().trim().min(1).max(256).nullable(),
+    sourceUrl: z.string().url().max(2048).nullable(),
+}).strict();
+export const remoteFileVerificationReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    verificationRef: stableUriSchema,
+    projectKey: projectKeySchema,
+    declarationDigest: sha256Schema,
+    artifactSha256: sha256Schema,
+    byteLength: z.number().int().positive(),
+    archiveFormat: remoteArchiveFormatSchema,
+    manifestPath: remoteBundlePathSchema,
+    manifestSha256: sha256Schema,
+    manifestFormat: remoteManifestFormatSchema,
+    manifestGeneratedAt: isoDateTimeSchema.nullable(),
+    artifactKind: idSchema,
+    familyId: idSchema,
+    targetId: idSchema,
+    jurisdiction: z.string().trim().min(1).max(128).nullable(),
+    sourceWorker: idSchema,
+    remoteArtifactRef: stableUriSchema.nullable(),
+    verifierNodeId: idSchema,
+    verifiedAt: isoDateTimeSchema,
+    files: z.array(remoteVerifiedFileSchema).min(1).max(10000),
+}).strict().superRefine((value, ctx) => {
+    const expected = `remote-file-verification://${value.projectKey}/${value.artifactSha256.slice('sha256:'.length)}`;
+    if (value.verificationRef !== expected)
+        ctx.addIssue({ code: 'custom', path: ['verificationRef'], message: 'verificationRef must match project and artifact hash' });
+    const seen = new Set();
+    value.files.forEach((entry, index) => {
+        if (seen.has(entry.path))
+            ctx.addIssue({ code: 'custom', path: ['files', index, 'path'], message: 'duplicate verified file path' });
+        seen.add(entry.path);
+    });
+});
+export const remoteFileProjectSourceBindingSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    bindingRef: stableUriSchema,
+    verificationRef: stableUriSchema,
+    projectKey: projectKeySchema,
+    artifactSha256: sha256Schema,
+    projectRef: stableUriSchema,
+    projectIntentRef: stableUriSchema,
+    sourceId: idSchema,
+    sourceRef: stableUriSchema,
+    sourceRevisionId: sha256Schema,
+    sourceRevisionRef: stableUriSchema,
+    projectSourceTargetId: sha256Schema,
+    boundAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    const artifactDigest = value.artifactSha256.slice('sha256:'.length);
+    const revisionDigest = value.sourceRevisionId.slice('sha256:'.length);
+    const expectedVerification = `remote-file-verification://${value.projectKey}/${artifactDigest}`;
+    const expectedBinding = `remote-file-source-binding://${value.projectKey}/${artifactDigest}/${revisionDigest}`;
+    const expectedSource = `project-source://${value.projectKey}/${value.sourceId}`;
+    const expectedRevision = `${expectedSource}/v/${revisionDigest}`;
+    if (value.verificationRef !== expectedVerification)
+        ctx.addIssue({ code: 'custom', path: ['verificationRef'], message: 'verificationRef must match project and artifact hash' });
+    if (value.bindingRef !== expectedBinding)
+        ctx.addIssue({ code: 'custom', path: ['bindingRef'], message: 'bindingRef must match project, artifact hash and source revision' });
+    if (value.sourceRef !== expectedSource)
+        ctx.addIssue({ code: 'custom', path: ['sourceRef'], message: 'sourceRef must match project and source id' });
+    if (value.sourceRevisionRef !== expectedRevision)
+        ctx.addIssue({ code: 'custom', path: ['sourceRevisionRef'], message: 'sourceRevisionRef must match source and revision id' });
+});
+export const remoteFileIngestReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    ingestRef: stableUriSchema,
+    verificationRef: stableUriSchema,
+    projectKey: projectKeySchema,
+    artifactSha256: sha256Schema,
+    sourceBindingRef: stableUriSchema.optional(),
+    consumerKey: idSchema,
+    resultRefs: z.array(stableUriSchema).min(1).max(256),
+    ingestedAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    const digest = value.artifactSha256.slice('sha256:'.length);
+    const expectedVerification = `remote-file-verification://${value.projectKey}/${digest}`;
+    let sourceRevisionDigest = null;
+    if (value.sourceBindingRef) {
+        const prefix = `remote-file-source-binding://${value.projectKey}/${digest}/`;
+        if (!value.sourceBindingRef.startsWith(prefix))
+            ctx.addIssue({ code: 'custom', path: ['sourceBindingRef'], message: 'sourceBindingRef must match project and artifact hash' });
+        else {
+            const candidate = value.sourceBindingRef.slice(prefix.length);
+            if (!/^[a-f0-9]{64}$/.test(candidate))
+                ctx.addIssue({ code: 'custom', path: ['sourceBindingRef'], message: 'sourceBindingRef must end with source revision digest' });
+            else
+                sourceRevisionDigest = candidate;
+        }
+    }
+    const expectedIngest = sourceRevisionDigest
+        ? `remote-file-ingest://${value.projectKey}/${digest}/${encodeURIComponent(value.consumerKey)}/${sourceRevisionDigest}`
+        : `remote-file-ingest://${value.projectKey}/${digest}/${encodeURIComponent(value.consumerKey)}`;
+    if (value.verificationRef !== expectedVerification)
+        ctx.addIssue({ code: 'custom', path: ['verificationRef'], message: 'verificationRef must match project and artifact hash' });
+    if (value.ingestRef !== expectedIngest)
+        ctx.addIssue({ code: 'custom', path: ['ingestRef'], message: 'ingestRef must match project, artifact hash, consumer and optional source binding' });
+    if (new Set(value.resultRefs).size !== value.resultRefs.length)
+        ctx.addIssue({ code: 'custom', path: ['resultRefs'], message: 'resultRefs must be unique' });
+});

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

@@ -0,0 +1,38 @@
+/** 存储/执行范围显式区分租户与历史项目；范围本身不是授权凭据。 */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { projectKeySchema, stableUriSchema } from './common.js';
+import { materialTenantIdSchema } from './material-context.js';
+export const resourceScopeSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('TENANT'), tenantId: materialTenantIdSchema }).strict(),
+    z.object({ type: z.literal('PROJECT'), tenantId: materialTenantIdSchema, projectKey: projectKeySchema }).strict(),
+]);
+export const materialAuthorityPolicySchema = z.enum(['LEGACY_PROJECT', 'TENANT_NATIVE', 'TENANT_PROJECT_SCOPE']);
+export function tenantStorageKey(tenantId) {
+    return createHash('sha256').update(materialTenantIdSchema.parse(tenantId), 'utf8').digest('hex');
+}
+export const tenantResourceIdentitySchema = z.object({
+    tenantId: materialTenantIdSchema,
+    resourceType: z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/),
+    resourceId: z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
+    version: z.number().int().positive().safe(),
+}).strict();
+export function tenantResourceRefs(input) {
+    const value = tenantResourceIdentitySchema.parse(input);
+    const identityRef = `tenant-resource://${tenantStorageKey(value.tenantId)}/${value.resourceType}/${value.resourceId}`;
+    return { identityRef, ref: `${identityRef}/v/${value.version}` };
+}
+/** 必须精确匹配规范身份；URL 的容错正规化不能改变对象定位。 */
+export function parseTenantResourceRef(ref) {
+    if (typeof ref !== 'string' || ref.length > 2048)
+        return null;
+    const match = /^tenant-resource:\/\/([a-f0-9]{64})\/([a-z][a-z0-9._-]{0,63})\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\/v\/([1-9][0-9]*)$/.exec(ref);
+    if (!match)
+        return null;
+    const version = Number(match[4]);
+    if (!Number.isSafeInteger(version))
+        return null;
+    return { storageKey: match[1], resourceType: match[2], resourceId: match[3], version };
+}
+export const tenantResourceRefSchema = stableUriSchema.refine(value => parseTenantResourceRef(value) !== null, 'Noncanonical tenant resource ref');
+export const TENANT_CORE_CAPABILITIES = { resource: 'TENANT_RESOURCE_V1', authority: 'TENANT_AUTHORITY_V1', source: 'TENANT_SOURCE_V1', workflow: 'TENANT_WORKFLOW_V1', budget: 'TENANT_BUDGET_V1' };

package/dist/internal/contracts/review-packet.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+import { currentnessAssessmentSchema } from './currentness.js';
+import { evidenceReviewAttachmentSchema } from './evidence.js';
+export const reviewPacketEvidenceSchema = z.object({
+    evidenceRef: stableUriSchema,
+    evidenceId: idSchema,
+    sourceId: idSchema,
+    sourceIds: z.array(idSchema).max(64).default([]),
+    projectRef: stableUriSchema.optional(),
+    sourceRevisionRef: stableUriSchema.optional(),
+    collectionBatchRef: stableUriSchema.optional(),
+    collectionTaskId: idSchema.optional(),
+    canonicalUri: stableUriSchema.optional(),
+    observedAt: isoDateTimeSchema,
+    access: accessClassificationSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256).optional(),
+    byteLength: z.number().int().nonnegative().optional(),
+    currentness: currentnessAssessmentSchema.optional(),
+    attachment: evidenceReviewAttachmentSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.attachment.evidenceRef !== value.evidenceRef)
+        ctx.addIssue({ code: 'custom', path: ['attachment', 'evidenceRef'], message: 'attachment evidenceRef must match evidence row' });
+    if (value.attachment.contentHash !== value.contentHash)
+        ctx.addIssue({ code: 'custom', path: ['attachment', 'contentHash'], message: 'attachment contentHash must match evidence row' });
+    if (value.mediaType && value.attachment.mediaType !== value.mediaType.toLowerCase())
+        ctx.addIssue({ code: 'custom', path: ['attachment', 'mediaType'], message: 'attachment mediaType must match evidence row' });
+    if (value.byteLength !== undefined && value.attachment.byteLength !== value.byteLength)
+        ctx.addIssue({ code: 'custom', path: ['attachment', 'byteLength'], message: 'attachment byteLength must match evidence row' });
+});
+export const reviewPacketSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    packetType: z.literal('KNOWLEDGE_REVIEW_PACKET'),
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    sourceEvent: z.object({
+        eventId: idSchema,
+        type: z.enum(['SOURCE_CHANGED', 'BOUNDARY_RISK', 'CURRENTNESS_RISK']),
+        createdAt: isoDateTimeSchema,
+        runtimeNodeId: idSchema.optional(),
+        sourceRef: stableUriSchema.optional(),
+        sourceRevisionRef: stableUriSchema.optional(),
+        collectionBatchRef: stableUriSchema.optional(),
+        contentHash: sha256Schema.optional(),
+    }).strict(),
+    evidence: z.array(reviewPacketEvidenceSchema).max(256),
+    reviewPolicy: z.object({
+        semanticSynthesisRequired: z.literal(true),
+        rawChunkApprovalForbidden: z.literal(true),
+        highRiskAutoApprovalForbidden: z.literal(true),
+        decisions: z.tuple([z.literal('PASS'), z.literal('REWORK'), z.literal('REJECT')]),
+    }).strict(),
+}).strict().superRefine((value, ctx) => {
+    if (value.projectRef)
+        for (let i = 0; i < value.evidence.length; i += 1) {
+            const row = value.evidence[i];
+            if (row.projectRef && row.projectRef !== value.projectRef)
+                ctx.addIssue({ code: 'custom', path: ['evidence', i, 'projectRef'], message: 'Evidence projectRef must match packet projectRef' });
+        }
+});

package/dist/internal/contracts/review-plane.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+import { artifactKindSchema } from './artifact.js';
+import { driveRelativePathSchema } from './projection.js';
+export const reviewPlaneStageSchema = z.enum([
+    'PROGRAM',
+    'INBOX',
+    'REVIEWED',
+    'USER_APPROVED',
+    'PROMOTION_RECEIPTS',
+    'GUIDES',
+    'REJECTED_SUPERSEDED',
+]);
+export const reviewPlaneWorkspaceSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    provider: z.literal('GOOGLE_DRIVE'),
+    rootPath: driveRelativePathSchema,
+    folders: z.object({
+        PROGRAM: driveRelativePathSchema,
+        INBOX: driveRelativePathSchema,
+        REVIEWED: driveRelativePathSchema,
+        USER_APPROVED: driveRelativePathSchema,
+        PROMOTION_RECEIPTS: driveRelativePathSchema,
+        GUIDES: driveRelativePathSchema.optional(),
+        REJECTED_SUPERSEDED: driveRelativePathSchema,
+    }).strict(),
+}).strict().superRefine((value, ctx) => {
+    const seen = new Set();
+    for (const [key, folder] of Object.entries(value.folders)) {
+        if (folder === undefined)
+            continue;
+        if (seen.has(folder))
+            ctx.addIssue({ code: 'custom', path: ['folders', key], message: 'review-plane folders must be unique' });
+        seen.add(folder);
+    }
+});
+export const reviewPlaneApprovalSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    approvalId: idSchema,
+    projectKey: projectKeySchema,
+    sourceProvider: z.literal('GOOGLE_DRIVE'),
+    sourcePath: driveRelativePathSchema,
+    sourceFileId: z.string().trim().min(1).max(512).nullable(),
+    sourceContentHash: sha256Schema,
+    sourceArtifactRef: stableUriSchema.nullable(),
+    reviewedAt: isoDateTimeSchema,
+    approvedAt: isoDateTimeSchema,
+    decision: z.literal('PASS'),
+    approvalAuthority: z.literal('EXPLICIT_HUMAN'),
+    hostDisposition: z.enum(['APPROVED_RESEARCH', 'APPROVED_KNOWLEDGE', 'APPROVED_INSIGHT']),
+    targetArtifactId: idSchema,
+    targetVersion: z.number().int().positive(),
+    targetTitle: z.string().trim().min(1).max(500),
+    mediaType: z.string().trim().min(1).max(256),
+    observedAt: isoDateTimeSchema.nullable(),
+    validUntil: isoDateTimeSchema.nullable(),
+    access: accessClassificationSchema,
+    evidenceRefs: z.array(stableUriSchema).max(256),
+    approvalEvidenceRefs: z.array(stableUriSchema).max(256),
+    supersedesRef: stableUriSchema.nullable(),
+}).strict().superRefine((value, ctx) => {
+    if (Date.parse(value.approvedAt) < Date.parse(value.reviewedAt))
+        ctx.addIssue({ code: 'custom', path: ['approvedAt'], message: 'approvedAt must not precede reviewedAt' });
+    if (value.validUntil && value.observedAt && Date.parse(value.validUntil) < Date.parse(value.observedAt))
+        ctx.addIssue({ code: 'custom', path: ['validUntil'], message: 'validUntil must not precede observedAt' });
+    if (value.targetVersion === 1 && value.supersedesRef !== null)
+        ctx.addIssue({ code: 'custom', path: ['supersedesRef'], message: 'version 1 cannot supersede' });
+    if (value.targetVersion > 1 && value.supersedesRef === null)
+        ctx.addIssue({ code: 'custom', path: ['supersedesRef'], message: 'later version requires exact predecessor ref' });
+});
+export const reviewPlanePromotionReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    approvalId: idSchema,
+    sourcePath: driveRelativePathSchema,
+    sourceFileId: z.string().trim().min(1).max(512).nullable(),
+    sourceContentHash: sha256Schema,
+    promotedAt: isoDateTimeSchema,
+    targetKind: artifactKindSchema,
+    draftRef: stableUriSchema,
+    readyRef: stableUriSchema,
+    reviewRef: stableUriSchema,
+    approvedRef: stableUriSchema,
+    approvedContentHash: sha256Schema,
+    exactBytesVerified: z.literal(true),
+    humanApprovalVerified: z.literal(true),
+    automaticPromotion: z.literal(false),
+}).strict();

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

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema } from './common.js';
+export const RICH_DOCUMENT_MEDIA_TYPE = 'application/vnd.knowledge-v2.rich-document+json';
+export const richDocumentRoleSchema = z.enum(['SOURCE_MIRROR', 'KNOWLEDGE', 'INSIGHT']);
+export const publicationProfileSchema = z.enum(['HUMAN_ARTICLE_V1', 'KNOWLEDGE_CARD_V1']);
+export const publicationReadinessReasonSchema = z.enum(['ROLE_MISMATCH', 'TITLE_REQUIRED', 'SUMMARY_REQUIRED', 'TEXT_TOO_SHORT', 'STRUCTURE_TOO_THIN', 'SOURCE_EVIDENCE_REQUIRED', 'CITATION_COVERAGE_REQUIRED', 'EVIDENCE_MISMATCH', 'MEDIA_UNAVAILABLE']);
+export const richDocumentMediaAvailabilitySchema = z.enum(['MIRRORED', 'REMOTE_ONLY', 'UNAVAILABLE']);
+const ordinalSchema = z.number().int().nonnegative().max(100_000);
+const humanText = (max) => z.string().max(max);
+const httpUrlSchema = z.string().url().max(2048).superRefine((value, ctx) => { const protocol = new URL(value).protocol; if (!['http:', 'https:'].includes(protocol))
+    ctx.addIssue({ code: 'custom', message: 'rich document media/source URL must use HTTP(S)' }); });
+const richInlineSchema = z.object({ text: humanText(64_000), href: httpUrlSchema.nullable() }).strict();
+const inlines = z.array(richInlineSchema).max(10_000).optional();
+const textBlockBase = { ordinal: ordinalSchema };
+export const richHeadingBlockSchema = z.object({ ...textBlockBase, kind: z.literal('HEADING'), level: z.number().int().min(1).max(6), text: humanText(16_000), inlines }).strict();
+export const richParagraphBlockSchema = z.object({ ...textBlockBase, kind: z.literal('PARAGRAPH'), text: humanText(64_000), inlines }).strict();
+export const richListItemBlockSchema = z.object({ ...textBlockBase, kind: z.literal('LIST_ITEM'), text: humanText(32_000), ordered: z.boolean(), level: z.number().int().min(0).max(16), index: z.number().int().positive().nullable(), inlines }).strict();
+export const richQuoteBlockSchema = z.object({ ...textBlockBase, kind: z.literal('QUOTE'), text: humanText(64_000), inlines }).strict();
+export const richCodeBlockSchema = z.object({ ...textBlockBase, kind: z.literal('CODE'), text: humanText(128_000), language: z.string().trim().min(1).max(128).nullable() }).strict();
+export const richDividerBlockSchema = z.object({ ...textBlockBase, kind: z.literal('DIVIDER') }).strict();
+export const richTableBlockSchema = z.object({ ...textBlockBase, kind: z.literal('TABLE'), rows: z.array(z.object({ cells: z.array(z.object({ text: humanText(16_000), header: z.boolean() }).strict()).max(128) }).strict()).min(1).max(1000) }).strict();
+const mediaBase = {
+    ordinal: ordinalSchema,
+    sourceUrl: httpUrlSchema,
+    canonicalUrl: httpUrlSchema.nullable(),
+    availability: richDocumentMediaAvailabilitySchema,
+    mediaRef: stableUriSchema.nullable(),
+    evidenceRef: stableUriSchema.nullable(),
+    contentHash: sha256Schema.nullable(),
+    mediaType: z.string().trim().min(1).max(256).nullable(),
+    byteLength: z.number().int().nonnegative().nullable(),
+    caption: humanText(16_000).nullable(),
+};
+function mediaConsistency(value, ctx) {
+    const mirrored = Boolean(value.mediaRef && value.evidenceRef && value.contentHash && value.mediaType && value.byteLength !== null);
+    if (value.availability === 'MIRRORED' && !mirrored)
+        ctx.addIssue({ code: 'custom', message: 'MIRRORED media requires EvidenceRef, hash, mediaType and byteLength' });
+    if (value.availability !== 'MIRRORED' && (value.mediaRef || value.evidenceRef || value.contentHash || value.mediaType || value.byteLength !== null))
+        ctx.addIssue({ code: 'custom', message: 'non-MIRRORED media cannot claim mirrored Evidence' });
+}
+export const richImageBlockSchema = z.object({ ...mediaBase, kind: z.literal('IMAGE'), alt: humanText(4000).nullable(), width: z.number().int().positive().max(100_000).nullable(), height: z.number().int().positive().max(100_000).nullable() }).strict().superRefine(mediaConsistency);
+export const richVideoBlockSchema = z.object({ ...mediaBase, kind: z.literal('VIDEO'), title: humanText(4000).nullable(), posterUrl: httpUrlSchema.nullable(), posterEvidenceRef: stableUriSchema.nullable() }).strict().superRefine(mediaConsistency);
+export const richAudioBlockSchema = z.object({ ...mediaBase, kind: z.literal('AUDIO'), title: humanText(4000).nullable() }).strict().superRefine(mediaConsistency);
+export const richEmbedBlockSchema = z.object({ ...textBlockBase, kind: z.literal('EMBED'), sourceUrl: httpUrlSchema, provider: z.string().trim().min(1).max(128).nullable(), title: humanText(4000).nullable(), caption: humanText(16_000).nullable() }).strict();
+export const richDocumentBlockSchema = z.discriminatedUnion('kind', [
+    richHeadingBlockSchema, richParagraphBlockSchema, richListItemBlockSchema, richQuoteBlockSchema, richCodeBlockSchema,
+    richImageBlockSchema, richVideoBlockSchema, richAudioBlockSchema, richEmbedBlockSchema, richDividerBlockSchema, richTableBlockSchema,
+]);
+export const richDocumentCitationSchema = z.object({
+    blockOrdinal: ordinalSchema,
+    evidenceRefs: z.array(stableUriSchema).min(1).max(32),
+}).strict().superRefine((value, ctx) => { if (new Set(value.evidenceRefs).size !== value.evidenceRefs.length)
+    ctx.addIssue({ code: 'custom', path: ['evidenceRefs'], message: 'citation EvidenceRefs must be unique' }); });
+export const richCompositionDraftSchema = z.object({
+    summary: humanText(4000),
+    byline: humanText(1000).nullable().optional(),
+    language: z.string().trim().min(1).max(64).nullable().optional(),
+    blocks: z.array(richDocumentBlockSchema).min(1).max(10_000),
+    citations: z.array(richDocumentCitationSchema).min(1).max(10_000),
+}).strict();
+export function validateRichDocumentContent(value, ctx, names = { primary: 'primarySourceEvidenceRef', citation: 'evidenceRefs' }) {
+    if (!value.sourceEvidenceRefs.includes(value.primarySourceEvidenceRef))
+        ctx.addIssue({ code: 'custom', path: [names.primary], message: 'primary source must be included in sourceEvidenceRefs' });
+    for (let index = 0; index < value.blocks.length; index += 1)
+        if (value.blocks[index].ordinal !== index)
+            ctx.addIssue({ code: 'custom', path: ['blocks', index, 'ordinal'], message: 'block ordinals must be contiguous and equal array position' });
+    for (let index = 0; index < value.blocks.length; index += 1) {
+        const block = value.blocks[index];
+        if ('inlines' in block && block.inlines && block.inlines.map(part => part.text).join('') !== block.text)
+            ctx.addIssue({ code: 'custom', path: ['blocks', index, 'inlines'], message: 'inline text must equal block text' });
+    }
+    const claimed = new Set(value.mediaEvidenceRefs);
+    if (claimed.size !== value.mediaEvidenceRefs.length)
+        ctx.addIssue({ code: 'custom', path: ['mediaEvidenceRefs'], message: 'mediaEvidenceRefs must be unique' });
+    for (let index = 0; index < value.blocks.length; index += 1) {
+        const block = value.blocks[index];
+        if (['IMAGE', 'VIDEO', 'AUDIO'].includes(block.kind)) {
+            const media = block;
+            if (media.evidenceRef && !claimed.has(media.evidenceRef))
+                ctx.addIssue({ code: 'custom', path: ['blocks', index, 'evidenceRef'], message: 'mirrored media EvidenceRef must be listed in mediaEvidenceRefs' });
+            if (media.kind === 'VIDEO' && media.posterEvidenceRef && !claimed.has(media.posterEvidenceRef))
+                ctx.addIssue({ code: 'custom', path: ['blocks', index, 'posterEvidenceRef'], message: 'video poster EvidenceRef must be listed in mediaEvidenceRefs' });
+        }
+    }
+    const citationOrdinals = new Set(), allowedCitationRefs = new Set([...value.sourceEvidenceRefs, ...value.mediaEvidenceRefs]);
+    for (let index = 0; index < value.citations.length; index += 1) {
+        const citation = value.citations[index];
+        if (citation.blockOrdinal >= value.blocks.length)
+            ctx.addIssue({ code: 'custom', path: ['citations', index, 'blockOrdinal'], message: 'citation block ordinal must identify an existing block' });
+        if (citationOrdinals.has(citation.blockOrdinal))
+            ctx.addIssue({ code: 'custom', path: ['citations', index, 'blockOrdinal'], message: 'only one citation record is allowed per block' });
+        citationOrdinals.add(citation.blockOrdinal);
+        for (const ref of citation.evidenceRefs)
+            if (!allowedCitationRefs.has(ref))
+                ctx.addIssue({ code: 'custom', path: ['citations', index, names.citation], message: 'citation EvidenceRef must be a source or media EvidenceRef' });
+    }
+}
+export const richDocumentSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    format: z.literal('RICH_DOCUMENT_V1'),
+    role: richDocumentRoleSchema,
+    publicationProfile: publicationProfileSchema.nullable().default(null),
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema,
+    sourceEvidenceRefs: z.array(stableUriSchema).min(1).max(256),
+    primarySourceEvidenceRef: stableUriSchema,
+    sourceContentHash: sha256Schema,
+    sourceUri: stableUriSchema,
+    sourceMediaType: z.string().trim().min(1).max(256),
+    sourceByteLength: z.number().int().nonnegative(),
+    title: humanText(1000).nullable(),
+    byline: humanText(1000).nullable(),
+    publishedAt: isoDateTimeSchema.nullable(),
+    language: z.string().trim().min(1).max(64).nullable(),
+    topics: z.array(z.string().trim().min(1).max(160)).max(32).optional(),
+    summary: humanText(4000).nullable(),
+    textContent: humanText(2_000_000),
+    blocks: z.array(richDocumentBlockSchema).max(10_000),
+    mediaEvidenceRefs: z.array(stableUriSchema).max(512),
+    citations: z.array(richDocumentCitationSchema).max(10_000).default([]),
+    extractedAt: isoDateTimeSchema,
+    extractor: z.object({ id: idSchema, version: z.string().trim().min(1).max(128) }).strict(),
+}).strict().superRefine((value, ctx) => {
+    if (value.role === 'SOURCE_MIRROR' && value.publicationProfile !== null)
+        ctx.addIssue({ code: 'custom', path: ['publicationProfile'], message: 'source mirror cannot claim a publication profile' });
+    if (value.role !== 'SOURCE_MIRROR' && value.publicationProfile === null)
+        ctx.addIssue({ code: 'custom', path: ['publicationProfile'], message: 'published Knowledge/Insight requires a publication profile' });
+    try {
+        const u = new URL(value.projectRef);
+        if (u.protocol !== 'knowledge-project:' || u.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+            ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'projectRef project must match rich document project' });
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'invalid projectRef' });
+    }
+    validateRichDocumentContent(value, ctx);
+});
+export const richSourceDocumentManifestSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    documentRef: stableUriSchema,
+    sourceEvidenceRef: stableUriSchema,
+    sourceContentHash: sha256Schema,
+    documentContentHash: sha256Schema,
+    documentByteLength: z.number().int().positive(),
+    extractedAt: isoDateTimeSchema,
+    extractor: z.object({ id: idSchema, version: z.string().trim().min(1).max(128) }).strict(),
+}).strict().superRefine((value, ctx) => { try {
+    const u = new URL(value.documentRef);
+    if (u.protocol !== 'rich-document:' || u.hostname.toLowerCase() !== value.projectKey.toLowerCase() || !/^\/[a-f0-9]{64}\/[a-f0-9]{64}$/.test(u.pathname))
+        ctx.addIssue({ code: 'custom', path: ['documentRef'], message: 'invalid Rich Source Document identity' });
+}
+catch {
+    ctx.addIssue({ code: 'custom', path: ['documentRef'], message: 'invalid Rich Source Document identity' });
+} });
+export const richSourceDocumentPointerSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    sourceEvidenceRef: stableUriSchema,
+    documentRef: stableUriSchema,
+    documentContentHash: sha256Schema,
+    manifestRelativePath: z.string().trim().min(1).max(4096).refine(value => !value.startsWith('/') && !value.split('/').includes('..'), 'manifestRelativePath must remain project-relative'),
+    updatedAt: isoDateTimeSchema,
+}).strict();
+export const publicationReadinessReportSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    profile: publicationProfileSchema,
+    ready: z.boolean(),
+    reasons: z.array(publicationReadinessReasonSchema).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(), sourceEvidenceCount: z.number().int().nonnegative(), citationCount: z.number().int().nonnegative(), citedBlockCount: z.number().int().nonnegative() }).strict(),
+}).strict();
+export const richMediaLinkSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    mediaRef: stableUriSchema,
+    sourceEvidenceRef: stableUriSchema,
+    mediaEvidenceRef: stableUriSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    sourceUrl: httpUrlSchema,
+    canonicalUrl: httpUrlSchema,
+    linkedAt: isoDateTimeSchema,
+}).strict();

package/dist/internal/contracts/runtime-compatibility.js

@@ -0,0 +1,55 @@
+/** Release admission contract. Intermediate, unreleased wave snapshots are not rollback targets. */
+export const tenantCoreReadCapabilities = [
+    'TENANT_RESOURCE_V1', 'TENANT_SOURCE_V1', 'TENANT_SOURCE_DOCUMENT_V2', 'TENANT_WORKFLOW_V1',
+    'TENANT_ROUTES_V1', 'TENANT_CURRENTNESS_V2', 'TENANT_PUBLIC_REFERENCE_V1',
+    'TENANT_PROJECT_CONTEXT_V1', 'TENANT_OAUTH_MANAGEMENT_V1', 'TENANT_RUNTIME_STATUS_V1',
+];
+export const tenantCoreWriteCapabilities = ['TENANT_COLLECTION_V2', 'TENANT_ADMISSION_STOP_V1', 'TENANT_ADMISSION_V2'];
+export function runtimeCompatibility(component) {
+    return { schemaVersion: 1, component, identityReadMinimum: 11, identityReadMaximum: 21,
+        capabilities: component === 'core' ? [...tenantCoreReadCapabilities, ...tenantCoreWriteCapabilities, 'TENANT_NATIVE_CLIENT_AUTH_V1'] : [...tenantCoreReadCapabilities, 'TENANT_NATIVE_CLIENT_AUTH_V1'],
+        tenantProviders: component === 'core' ? [16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26] : [], requiredCoreProviders: component === 'admin-web' ? [20] : [],
+        budgetReadVersions: component === 'core' ? [2] : [], budgetMigrationVersions: component === 'core' ? [1] : [] };
+}
+/** Conservative published compatibility floor: native Identity >=12 requires the complete current Tenant reader. */
+export function assertRuntimeFormatCompatibility(raw, facts, component, mode) {
+    const fail = (code) => { throw new Error('RUNTIME_COMPATIBILITY_' + code); };
+    if (!['core', 'admin-web'].includes(component) || !['INSTALL', 'START', 'ROLLBACK', 'RECOVERY'].includes(mode))
+        fail('CONTEXT_INVALID');
+    if (!Number.isSafeInteger(facts.identityVersion) || facts.identityVersion < 11 || facts.identityVersion > 21)
+        fail('IDENTITY_UNSUPPORTED');
+    if (facts.budgetVersion !== null && ![1, 2].includes(facts.budgetVersion))
+        fail('BUDGET_UNSUPPORTED');
+    if (raw === undefined) {
+        if (facts.identityVersion >= 12 || facts.budgetVersion !== null)
+            fail('DECLARATION_REQUIRED');
+        return;
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        fail('DECLARATION_INVALID');
+    const value = raw, expected = runtimeCompatibility(component), keys = Object.keys(expected);
+    if (Object.keys(value).length !== keys.length || Object.keys(value).some(key => !keys.includes(key)) || value.schemaVersion !== 1 || value.component !== component)
+        fail('DECLARATION_INVALID');
+    if (!Number.isSafeInteger(value.identityReadMinimum) || !Number.isSafeInteger(value.identityReadMaximum) || value.identityReadMinimum < 11 || value.identityReadMaximum > 21 || value.identityReadMinimum > value.identityReadMaximum)
+        fail('DECLARATION_INVALID');
+    for (const key of ['capabilities', 'tenantProviders', 'requiredCoreProviders', 'budgetReadVersions', 'budgetMigrationVersions']) {
+        const list = value[key], allowed = expected[key];
+        if (!Array.isArray(list) || new Set(list).size !== list.length || list.some(item => !allowed.includes(item)))
+            fail('DECLARATION_INVALID');
+    }
+    if (facts.identityVersion < value.identityReadMinimum || facts.identityVersion > value.identityReadMaximum)
+        fail('IDENTITY_UNSUPPORTED');
+    if (facts.identityVersion >= 12 && expected.capabilities.some(cap => (facts.identityVersion >= 21 || cap !== 'TENANT_NATIVE_CLIENT_AUTH_V1') && !value.capabilities.includes(cap)))
+        fail('CAPABILITY_REQUIRED');
+    // New Provider21/22 are advertised, but historical Identity >=12 does not imply the new opt-in writer.
+    if (facts.identityVersion >= 12 && ['tenantProviders', 'requiredCoreProviders'].some(key => (key === 'tenantProviders' && component === 'core' ? [16, 17, 18, 19, 20] : expected[key]).some(version => !value[key].includes(version))))
+        fail('PROVIDER_REQUIRED');
+    if (facts.identityVersion >= 21 && component === 'core' && !value.tenantProviders.includes(26))
+        fail('PROVIDER_REQUIRED');
+    if (component === 'core' && facts.budgetVersion !== null && !value.capabilities.includes('TENANT_ADMISSION_V2'))
+        fail('CAPABILITY_REQUIRED');
+    if (component === 'core' && facts.budgetVersion !== null && !value.budgetReadVersions.includes(facts.budgetVersion)) {
+        if (mode !== 'INSTALL' || !value.budgetMigrationVersions.includes(facts.budgetVersion))
+            fail('BUDGET_MIGRATION_REQUIRED');
+    }
+}