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

package/dist/internal/contracts/evidence.js

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+export const evidenceModalitySchema = z.enum(['TEXT', 'PDF', 'IMAGE', 'AUDIO', 'VIDEO', 'BINARY']);
+export const evidenceReviewModeSchema = z.enum(['TEXT_NATIVE', 'MULTIMODAL_NATIVE', 'EXTERNAL_EXTRACTOR_REQUIRED']);
+export const evidenceReviewInstructionSchema = z.enum([
+    'READ_ORIGINAL_TEXT',
+    'INSPECT_ORIGINAL_DOCUMENT',
+    'INSPECT_ORIGINAL_IMAGE',
+    'LISTEN_TO_ORIGINAL_AUDIO',
+    'INSPECT_ORIGINAL_VIDEO',
+    'USE_APPROVED_EXTERNAL_EXTRACTOR',
+]);
+const pageRangeSchema = z.object({
+    startPage: z.number().int().positive(),
+    endPage: z.number().int().positive(),
+}).strict().superRefine((value, ctx) => {
+    if (value.endPage < value.startPage)
+        ctx.addIssue({ code: 'custom', path: ['endPage'], message: 'endPage must be >= startPage' });
+});
+const timeRangeSchema = z.object({
+    startMs: z.number().int().nonnegative(),
+    endMs: z.number().int().nonnegative(),
+}).strict().superRefine((value, ctx) => {
+    if (value.endMs < value.startMs)
+        ctx.addIssue({ code: 'custom', path: ['endMs'], message: 'endMs must be >= startMs' });
+});
+export const evidenceReviewHintsSchema = z.object({
+    pageRanges: z.array(pageRangeSchema).max(64).default([]),
+    timeRanges: z.array(timeRangeSchema).max(64).default([]),
+    frameTimestampsMs: z.array(z.number().int().nonnegative()).max(64).default([]),
+}).strict();
+export const evidenceReviewAttachmentSchema = z.object({
+    evidenceRef: stableUriSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative().nullable(),
+    modality: evidenceModalitySchema,
+    reviewMode: evidenceReviewModeSchema,
+    instruction: evidenceReviewInstructionSchema,
+    rawBytesEmbedded: z.literal(false),
+    materializationRequired: z.literal(true),
+    reviewHints: evidenceReviewHintsSchema.optional(),
+}).strict().superRefine((value, ctx) => {
+    const expected = value.modality === 'TEXT' ? ['TEXT_NATIVE', 'READ_ORIGINAL_TEXT']
+        : value.modality === 'PDF' ? ['MULTIMODAL_NATIVE', 'INSPECT_ORIGINAL_DOCUMENT']
+            : value.modality === 'IMAGE' ? ['MULTIMODAL_NATIVE', 'INSPECT_ORIGINAL_IMAGE']
+                : value.modality === 'AUDIO' ? ['MULTIMODAL_NATIVE', 'LISTEN_TO_ORIGINAL_AUDIO']
+                    : value.modality === 'VIDEO' ? ['MULTIMODAL_NATIVE', 'INSPECT_ORIGINAL_VIDEO']
+                        : ['EXTERNAL_EXTRACTOR_REQUIRED', 'USE_APPROVED_EXTERNAL_EXTRACTOR'];
+    if (value.reviewMode !== expected[0])
+        ctx.addIssue({ code: 'custom', path: ['reviewMode'], message: `reviewMode must be ${expected[0]} for ${value.modality}` });
+    if (value.instruction !== expected[1])
+        ctx.addIssue({ code: 'custom', path: ['instruction'], message: `instruction must be ${expected[1]} for ${value.modality}` });
+    const hints = value.reviewHints;
+    if (hints?.pageRanges.length && value.modality !== 'PDF')
+        ctx.addIssue({ code: 'custom', path: ['reviewHints', 'pageRanges'], message: 'pageRanges require PDF modality' });
+    if (hints?.timeRanges.length && !['AUDIO', 'VIDEO'].includes(value.modality))
+        ctx.addIssue({ code: 'custom', path: ['reviewHints', 'timeRanges'], message: 'timeRanges require AUDIO or VIDEO modality' });
+    if (hints?.frameTimestampsMs.length && value.modality !== 'VIDEO')
+        ctx.addIssue({ code: 'custom', path: ['reviewHints', 'frameTimestampsMs'], message: 'frameTimestampsMs require VIDEO modality' });
+});
+export const evidenceMaterializationReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    evidenceRef: stableUriSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    modality: evidenceModalitySchema,
+    reviewMode: evidenceReviewModeSchema,
+    instruction: evidenceReviewInstructionSchema,
+    reviewHints: evidenceReviewHintsSchema.optional(),
+    access: accessClassificationSchema,
+    runtimeNodeId: idSchema,
+    materializedAt: isoDateTimeSchema,
+    runtimeLocalPath: z.string().trim().min(1).max(4096).startsWith('/'),
+    reused: z.boolean(),
+}).strict();
+export const collectorIdentitySchema = z.object({
+    collectorId: idSchema,
+    version: z.string().trim().min(1).max(128),
+}).strict();
+/** 附属媒体沿用 Source 身份，但不能替代该 Source 的主文档。 */
+export const RICH_MEDIA_COLLECTOR_ID = 'knowledge-v2.rich-document-media';
+// 中文职责：保存只读 POST 的请求体对象索引，响应 contentHash 始终代表原始响应。
+export const evidenceRequestSchema = z.object({
+    schemaVersion: z.literal(1), method: z.literal('POST'),
+    bodyContentHash: sha256Schema, bodyMediaType: z.literal('application/x-www-form-urlencoded'),
+    bodyByteLength: z.number().int().nonnegative().max(16 * 1024),
+}).strict();
+export const evidenceRefSchema = z.object({
+    // Re-admission preserves acquisition facts; this link records reuse rather than a new download.
+    recoveryProvenance: z.object({ mode: z.literal('REUSED_PRIOR_EVIDENCE'), originEvidenceRef: stableUriSchema, originProjectRef: stableUriSchema, originSourceRevisionRef: stableUriSchema, originRuntimeNodeId: idSchema, handoffReceiptRef: stableUriSchema }).strict().optional(),
+    request: evidenceRequestSchema.optional(),
+    schemaVersion: schemaVersionSchema,
+    evidenceId: idSchema,
+    sourceId: idSchema,
+    sourceIds: z.array(idSchema).min(1).max(64).optional(),
+    projectKey: projectKeySchema.optional(),
+    projectRef: stableUriSchema.optional(),
+    collector: collectorIdentitySchema,
+    contentHash: sha256Schema,
+    observedAt: isoDateTimeSchema,
+    runtimeNodeId: idSchema,
+    access: accessClassificationSchema,
+    canonicalUri: stableUriSchema.optional(),
+    mediaType: z.string().trim().min(1).max(256).optional(),
+    byteLength: z.number().int().nonnegative().optional(),
+    sourceSetRef: stableUriSchema.optional(),
+    sourceItemId: idSchema.optional(),
+    sourceRevisionRef: stableUriSchema.optional(),
+    collectionBatchRef: stableUriSchema.optional(),
+    collectionTaskId: idSchema.optional(),
+    reviewHints: evidenceReviewHintsSchema.optional(),
+}).strict().superRefine((value, ctx) => {
+    if (value.recoveryProvenance) {
+        const origin = value.recoveryProvenance;
+        if (value.access !== 'PUBLIC')
+            ctx.addIssue({ code: 'custom', path: ['recoveryProvenance'], message: 'Recovery re-admission requires PUBLIC evidence' });
+        for (const [key, protocol] of [['originEvidenceRef', 'evidence:'], ['originProjectRef', 'knowledge-project:'], ['originSourceRevisionRef', 'project-source:'], ['handoffReceiptRef', 'runtime-handoff:']]) {
+            const url = new URL(origin[key]);
+            if (url.protocol !== protocol || url.hostname !== value.projectKey)
+                ctx.addIssue({ code: 'custom', path: ['recoveryProvenance', key], message: 'Recovery provenance must retain the same project and expected reference type' });
+        }
+        if (origin.originEvidenceRef === `evidence://${value.projectKey}/${encodeURIComponent(value.evidenceId)}`)
+            ctx.addIssue({ code: 'custom', path: ['recoveryProvenance'], message: 'Recovery origin cannot be self' });
+    }
+    if (Boolean(value.sourceSetRef) !== Boolean(value.sourceItemId))
+        ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'sourceSetRef and sourceItemId must be provided together' });
+    if (Boolean(value.collectionBatchRef) !== Boolean(value.collectionTaskId))
+        ctx.addIssue({ code: 'custom', path: ['collectionBatchRef'], message: 'collectionBatchRef and collectionTaskId must be provided together' });
+    if (value.projectRef && value.projectKey) {
+        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 Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'Invalid projectRef' });
+        }
+    }
+    if (value.sourceSetRef && value.projectKey) {
+        try {
+            const url = new URL(value.sourceSetRef);
+            if (url.protocol !== 'source-set:' || url.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'sourceSetRef project must match Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'Invalid sourceSetRef' });
+        }
+    }
+    if (value.sourceRevisionRef && value.projectKey) {
+        try {
+            const url = new URL(value.sourceRevisionRef);
+            if (url.protocol !== 'project-source:' || url.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['sourceRevisionRef'], message: 'sourceRevisionRef project must match Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['sourceRevisionRef'], message: 'Invalid sourceRevisionRef' });
+        }
+    }
+    if (value.collectionBatchRef && value.projectKey) {
+        try {
+            const url = new URL(value.collectionBatchRef);
+            if (url.protocol !== 'collection-batch:' || url.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['collectionBatchRef'], message: 'collectionBatchRef project must match Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['collectionBatchRef'], message: 'Invalid collectionBatchRef' });
+        }
+    }
+});

package/dist/{types → internal}/contracts/index.d.ts

@@ -52,4 +52,3 @@ export * from './tenant-web-content-plan.js';
 export * from './tenant-web-content-result.js';
 export * from './tenant-web-content.js';
 export * from './tenant-web-workflow.js';
-export * from './resource-transfer.js';

package/dist/internal/contracts/index.js

@@ -0,0 +1,54 @@
+export * from './common.js';
+export * from './source.js';
+export * from './evidence.js';
+export * from './observation.js';
+export * from './runtime.js';
+export * from './event.js';
+export * from './signal.js';
+export * from './artifact.js';
+export * from './review-packet.js';
+export * from './scheduler.js';
+export * from './currentness.js';
+export * from './projection.js';
+export * from './source-governance.js';
+export * from './review-plane.js';
+export * from './persistence.js';
+export * from './remote-file.js';
+export * from './project-intent.js';
+export * from './collection.js';
+export * from './collection-control.js';
+export * from './rich-document.js';
+export * from './material-carrier.js';
+export * from './reference-record.js';
+export * from './material-read.js';
+export * from './material-context.js';
+export * from './tenant-material-api.js';
+export * from './material-capability.js';
+export * from './public-reference.js';
+export * from './resource-scope.js';
+export * from './tenant-resource.js';
+export * from './tenant-resource-api.js';
+export * from './tenant-source.js';
+export * from './tenant-collection.js';
+export * from './tenant-collection-request.js';
+export * from './tenant-source-document.js';
+export * from './tenant-source-bridge.js';
+export * from './tenant-source-binding.js';
+export * from './tenant-source-cutover.js';
+export * from './tenant-rich-document.js';
+export * from './tenant-management.js';
+export * from './tenant-currentness.js';
+export * from './tenant-public-reference.js';
+export * from './tenant-project-control.js';
+export * from './tenant-budget.js';
+export * from './runtime-compatibility.js';
+export * from './tenant-web-collection.js';
+export * from './tenant-web-results.js';
+export * from './tenant-web-crawl.js';
+export * from './tenant-source-lease.js';
+export * from './tenant-web-dynamic.js';
+export * from './tenant-pdf-text.js';
+export * from './tenant-web-content-plan.js';
+export * from './tenant-web-content-result.js';
+export * from './tenant-web-content.js';
+export * from './tenant-web-workflow.js';

package/dist/internal/contracts/material-capability.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { rawRetrievalDecisionSchema, rawMaterialDirectoryItemSchema } from './material-read.js';
+import { sha256Schema } from './common.js';
+export const materialReadStateSchema = z.enum(['READY', 'UNSUPPORTED', 'MISSING', 'INTEGRITY_MISMATCH', 'DENIED']);
+export const materialCapabilitySchema = z.object({
+    item: rawMaterialDirectoryItemSchema, materialAccess: rawRetrievalDecisionSchema,
+    representation: z.object({ state: materialReadStateSchema, format: z.enum(['BYTES', 'JSON']), transfer: z.enum(['VERIFIED_STREAM', 'BUFFERED_JSON', 'UNSUPPORTED']), contentHash: sha256Schema.nullable(), mediaType: z.string().min(1).max(256), byteLength: z.number().int().nonnegative().safe().nullable(), methods: z.array(z.enum(['GET', 'HEAD'])).max(2), range: z.enum(['SINGLE', 'NONE']), verification: z.literal('ON_READ'), verificationChunkBytes: z.number().int().positive().nullable() }).strict(),
+}).strict();

package/dist/internal/contracts/material-carrier.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { accessClassificationSchema, isoDateTimeSchema, projectKeySchema, sha256Schema, stableUriSchema } from './common.js';
+export const materialResourceTypeSchema = z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/);
+/** Provenance-bearing immutable metadata; original bytes live only in the shared CAS. */
+export const materialCarrierManifestSchema = z.object({
+    schemaVersion: z.literal(1), ref: stableUriSchema, projectKey: projectKeySchema, resourceType: materialResourceTypeSchema,
+    kind: z.string().min(1).max(128), access: accessClassificationSchema, title: z.string().max(512), summary: z.string().max(1024),
+    observedAt: isoDateTimeSchema, sourceRefs: z.array(stableUriSchema).min(1).max(128), sourceUri: stableUriSchema.nullable(), sourceSetRef: stableUriSchema.nullable().default(null),
+    storage: z.literal('CAS'), contentHash: sha256Schema, mediaType: z.string().min(1).max(256), byteLength: z.number().int().nonnegative().safe(),
+}).strict().superRefine((value, ctx) => { if (value.sourceSetRef && !value.sourceSetRef.startsWith(`source-set://${value.projectKey}/`))
+    ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'Source Set must belong to the material source project' }); if (['artifact', 'evidence', 'reference', 'media'].includes(value.resourceType))
+    ctx.addIssue({ code: 'custom', path: ['resourceType'], message: 'built-in carriers retain their existing canonical stores' }); });
+export const materialRegistrationMetadataSchema = z.object({ ...materialCarrierManifestSchema.shape }).omit({ schemaVersion: true, contentHash: true, byteLength: true, storage: true });
+export const materialRegistrationRequestSchema = z.object({ projectRef: stableUriSchema, metadata: materialRegistrationMetadataSchema, contentBase64: z.string().max(87384) }).strict();
+export const materialRegistrationInputJsonSchema = z.toJSONSchema(materialRegistrationRequestSchema, { target: 'draft-07' });

package/dist/internal/contracts/material-context.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { projectKeySchema, stableUriSchema } from './common.js';
+export const materialTenantIdSchema = z.string().min(1).max(256).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+export const materialContextSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('TENANT'), tenantId: materialTenantIdSchema, tenantRef: stableUriSchema }).strict(),
+    z.object({ type: z.literal('PROJECT'), tenantId: materialTenantIdSchema, projectKey: projectKeySchema, projectRef: stableUriSchema }).strict(),
+]);
+export const materialProjectScopeInputSchema = z.object({ mode: z.enum(['TENANT', 'EXPLICIT']).optional(), selectors: z.array(z.object({ type: z.enum(['SOURCE_PROJECT', 'REF']), value: z.string().min(1).max(4096), enabled: z.boolean() }).strict()).max(100).default([]) }).strict().superRefine((value, ctx) => { if (!value.mode && !value.selectors.length)
+    ctx.addIssue({ code: 'custom', message: 'An explicit scope mutation is required' }); });

package/dist/internal/contracts/material-read.js

@@ -0,0 +1,12 @@
+/** Retrieval permissions and immutable descriptors, independent of business usage decisions. */
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema } from './common.js';
+import { materialResourceTypeSchema } from './material-carrier.js';
+export const rawRetrievalProblemSchema = z.enum(['NOT_FOUND', 'CONTENT_ACCESS_DENIED', 'INTEGRITY_MISMATCH', 'UNAVAILABLE', 'UNSUPPORTED_RESOURCE']);
+export const rawRetrievalDecisionSchema = z.object({ schemaVersion: schemaVersionSchema, action: z.enum(['ALLOW', 'DENY']), reasonCodes: z.array(rawRetrievalProblemSchema).max(32), assessedAt: isoDateTimeSchema }).strict().superRefine((value, ctx) => { if ((value.action === 'ALLOW') !== (value.reasonCodes.length === 0))
+    ctx.addIssue({ code: 'custom', path: ['reasonCodes'], message: 'Retrieval decision and reasons must agree' }); });
+export const rawContentDescriptorSchema = z.object({ contentHash: sha256Schema, mediaType: z.string().trim().min(1).max(256), byteLength: z.number().int().nonnegative().safe() }).strict();
+export const rawArtifactSummarySchema = z.object({ ref: stableUriSchema, identityRef: stableUriSchema, projectKey: projectKeySchema, projectRef: stableUriSchema.nullable().default(null), artifactId: idSchema, kind: z.string().trim().min(1).max(128), version: z.number().int().positive(), status: z.string().trim().min(1).max(128), access: accessClassificationSchema, title: z.string().max(500).nullable(), createdAt: isoDateTimeSchema, observedAt: isoDateTimeSchema.nullable(), validUntil: isoDateTimeSchema.nullable(), content: rawContentDescriptorSchema }).strict();
+export const rawArtifactDetailSchema = rawArtifactSummarySchema.extend({ evidenceRefs: z.array(stableUriSchema).max(256), relatedRefs: z.array(stableUriSchema).max(256), supersedesRef: stableUriSchema.nullable() }).strict();
+export const rawEvidenceSummarySchema = z.object({ evidenceRef: stableUriSchema, projectKey: projectKeySchema, sourceId: idSchema, contentHash: sha256Schema, observedAt: isoDateTimeSchema, access: accessClassificationSchema, canonicalUri: stableUriSchema.nullable(), mediaType: z.string().max(256).nullable(), byteLength: z.number().int().nonnegative().safe().nullable(), projectRef: stableUriSchema.nullable().default(null), sourceSetRef: stableUriSchema.nullable(), sourceItemId: idSchema.nullable(), sourceRevisionRef: stableUriSchema.nullable().default(null), collectionBatchRef: stableUriSchema.nullable().default(null), collectionTaskId: idSchema.nullable().default(null) }).strict();
+export const rawMaterialDirectoryItemSchema = z.object({ ref: stableUriSchema, resourceType: materialResourceTypeSchema, sourceProjectKey: projectKeySchema, identityHash: sha256Schema, kind: z.string().min(1).max(128), classification: accessClassificationSchema, mediaType: z.string().min(1).max(256), decision: rawRetrievalDecisionSchema }).strict();

package/dist/internal/contracts/observation.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+export const observationKindSchema = z.enum([
+    'SOURCE_CHANGE',
+    'WORLD_SIGNAL',
+    'SOURCE_FAILURE',
+    'BUSINESS_FEEDBACK',
+    'AGENT_EVALUATION',
+    'CONTENT_FEEDBACK',
+    'OTHER',
+]);
+export const observationSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    observationId: idSchema,
+    projectKey: projectKeySchema.optional(),
+    projectRef: stableUriSchema.optional(),
+    kind: observationKindSchema,
+    observedAt: isoDateTimeSchema,
+    expiresAt: isoDateTimeSchema.optional(),
+    evidenceRefs: z.array(stableUriSchema).min(1).max(256),
+    payloadHash: sha256Schema.optional(),
+    summary: z.string().trim().min(1).max(4000).optional(),
+}).strict();
+export const signalLaneSchema = z.enum(['DEMAND', 'PAIN', 'COMMERCIAL', 'OTHER']);
+export const velocityStateSchema = z.enum(['NEW', 'RISING', 'STABLE', 'FALLING', 'REAPPEARED', 'UNKNOWN']);
+export const signalObservationSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    observationId: idSchema,
+    projectKey: projectKeySchema.optional(),
+    projectRef: stableUriSchema.optional(),
+    observedAt: isoDateTimeSchema,
+    evidenceRefs: z.array(stableUriSchema).min(1).max(256),
+    signalFamily: z.string().trim().min(1).max(128),
+    subject: z.string().trim().min(1).max(1000),
+    lanes: z.array(signalLaneSchema).min(1).max(4),
+    velocity: velocityStateSchema,
+    attentionScore: z.number().finite().optional(),
+    sourceCount: z.number().int().nonnegative(),
+}).strict();

package/dist/internal/contracts/persistence.js

@@ -0,0 +1,239 @@
+import { z } from 'zod';
+import { artifactKindSchema } from './artifact.js';
+import { evidenceRefSchema } from './evidence.js';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+import { sourceDeclaredStateSchema } from './source-governance.js';
+export const portableRelativePathSchema = z.string().trim().min(1).max(4096).superRefine((value, ctx) => {
+    if (value.startsWith('/') || value.includes('\\'))
+        ctx.addIssue({ code: 'custom', message: 'Path must be portable and relative' });
+    const parts = value.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..'))
+        ctx.addIssue({ code: 'custom', message: 'Path contains invalid segment' });
+});
+export const sourceSetRegistryHashSchema = z.object({
+    acquisitionSourceId: idSchema,
+    relativePath: portableRelativePathSchema,
+    contentHash: sha256Schema,
+}).strict();
+export const sourceSetItemBindingSchema = z.object({
+    acquisitionSourceId: idSchema,
+    concreteSourceId: idSchema,
+    authority: z.string().trim().min(1).max(512).nullable(),
+    access: accessClassificationSchema,
+    declaredGitSha: z.string().trim().min(1).max(128).nullable(),
+}).strict();
+export const sourceSetItemSchema = z.object({
+    itemId: idSchema,
+    kind: z.enum(['WEB', 'FILE']),
+    logicalSourceRef: stableUriSchema,
+    sourceIds: z.array(idSchema).min(1).max(64),
+    bindings: z.array(sourceSetItemBindingSchema).min(1).max(64),
+    contentPolicy: z.enum(['public-excerpt', 'metadata-only']),
+    cadenceMs: z.number().int().positive(),
+    url: z.url().nullable(),
+    rootBinding: projectKeySchema.nullable(),
+    relativePath: portableRelativePathSchema.nullable(),
+}).strict().superRefine((value, ctx) => {
+    if (value.kind === 'WEB' && (!value.url || value.rootBinding || value.relativePath))
+        ctx.addIssue({ code: 'custom', path: ['url'], message: 'WEB item requires url only' });
+    if (value.kind === 'FILE' && (value.url || !value.rootBinding || !value.relativePath))
+        ctx.addIssue({ code: 'custom', path: ['relativePath'], message: 'FILE item requires rootBinding + relativePath only' });
+});
+export const sourceSetLogicalSourceSchema = z.object({
+    logicalSourceId: idSchema,
+    familyId: idSchema,
+    declaredState: sourceDeclaredStateSchema,
+    locator: stableUriSchema.nullable(),
+    acquisitionSourceIds: z.array(idSchema).max(64),
+    itemIds: z.array(idSchema).max(5000),
+}).strict();
+export const sourceSetSnapshotSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    sourceSetId: sha256Schema,
+    sourceSetRef: stableUriSchema,
+    projectKey: projectKeySchema,
+    programRevision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    acquisitionConfigHash: sha256Schema,
+    sourceUniverseHash: sha256Schema.nullable(),
+    registryHashes: z.array(sourceSetRegistryHashSchema).max(256),
+    items: z.array(sourceSetItemSchema).max(20000),
+    logicalSources: z.array(sourceSetLogicalSourceSchema).max(5000),
+}).strict().superRefine((value, ctx) => {
+    const digest = value.sourceSetId.slice('sha256:'.length);
+    if (value.sourceSetRef !== `source-set://${value.projectKey}/${digest}`)
+        ctx.addIssue({ code: 'custom', path: ['sourceSetRef'], message: 'sourceSetRef must match sourceSetId' });
+    const itemIds = value.items.map((row) => row.itemId);
+    if (new Set(itemIds).size !== itemIds.length)
+        ctx.addIssue({ code: 'custom', path: ['items'], message: 'itemId must be unique' });
+    const logicalIds = value.logicalSources.map((row) => row.logicalSourceId);
+    if (new Set(logicalIds).size !== logicalIds.length)
+        ctx.addIssue({ code: 'custom', path: ['logicalSources'], message: 'logicalSourceId must be unique' });
+    const registryKeys = value.registryHashes.map((row) => `${row.acquisitionSourceId}\n${row.relativePath}`);
+    if (new Set(registryKeys).size !== registryKeys.length)
+        ctx.addIssue({ code: 'custom', path: ['registryHashes'], message: 'registry hash binding must be unique' });
+});
+export const sourceSetPointerSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    sourceSetId: sha256Schema,
+    sourceSetRef: stableUriSchema,
+    manifestRelativePath: portableRelativePathSchema,
+    updatedAt: isoDateTimeSchema,
+}).strict();
+export const libraryProjectionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectionId: sha256Schema,
+    projectKey: projectKeySchema,
+    subjectType: z.enum(['ARTIFACT', 'EVIDENCE']),
+    subjectRef: stableUriSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    relativePath: portableRelativePathSchema,
+    manifestRelativePath: portableRelativePathSchema,
+}).strict();
+export const deliverySupportProofSchema = z.object({
+    action: z.literal('ALLOW'),
+    supportState: z.string().trim().min(1).max(128),
+    semanticHash: sha256Schema,
+}).strict();
+export const deliveryConsumerRequestSchema = z.object({
+    mediaType: z.string().trim().min(1).max(256),
+    contentHash: sha256Schema,
+    byteLength: z.number().int().nonnegative(),
+}).strict();
+export const knowledgeDeliveryEnvelopeSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    deliveryId: sha256Schema,
+    producerProjectKey: projectKeySchema,
+    producerProjectRef: stableUriSchema.optional(),
+    consumerKey: projectKeySchema,
+    artifactRef: stableUriSchema,
+    artifactKind: artifactKindSchema,
+    artifactAccess: accessClassificationSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    libraryPath: portableRelativePathSchema,
+    observedAt: isoDateTimeSchema.nullable(),
+    validUntil: isoDateTimeSchema.nullable(),
+    support: deliverySupportProofSchema.nullable(),
+    consumerRequest: deliveryConsumerRequestSchema.nullable(),
+    createdAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => { if (value.producerProjectRef) {
+    try {
+        const url = new URL(value.producerProjectRef);
+        if (url.protocol !== 'knowledge-project:' || url.hostname.toLowerCase() !== value.producerProjectKey.toLowerCase())
+            ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'producerProjectRef project must match producer project' });
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'Invalid producerProjectRef' });
+    }
+} });
+export const knowledgeDeliveryClaimSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    deliveryId: sha256Schema,
+    producerProjectKey: projectKeySchema,
+    producerProjectRef: stableUriSchema.optional(),
+    consumerKey: projectKeySchema,
+    claimId: z.string().uuid(),
+    workerId: z.string().trim().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/),
+    claimedAt: isoDateTimeSchema,
+    expiresAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.producerProjectRef) {
+        try {
+            const url = new URL(value.producerProjectRef);
+            if (url.protocol !== 'knowledge-project:' || url.hostname.toLowerCase() !== value.producerProjectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'producerProjectRef project must match producer project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'Invalid producerProjectRef' });
+        }
+    }
+    const claimedAt = Date.parse(value.claimedAt), expiresAt = Date.parse(value.expiresAt), leaseSeconds = (expiresAt - claimedAt) / 1000;
+    if (expiresAt <= claimedAt)
+        ctx.addIssue({ code: 'custom', path: ['expiresAt'], message: 'Delivery claim expiry must be after claim time' });
+    else if (leaseSeconds < 30 || leaseSeconds > 3600)
+        ctx.addIssue({ code: 'custom', path: ['expiresAt'], message: 'Delivery claim lease must be between 30 and 3600 seconds' });
+});
+export const knowledgeDeliveryOutcomeSchema = z.enum(['DELIVERED', 'BLOCKED', 'FAILED_RETRYABLE', 'FAILED_TERMINAL']);
+export const knowledgeDeliveryReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    deliveryId: sha256Schema,
+    producerProjectKey: projectKeySchema,
+    producerProjectRef: stableUriSchema.optional(),
+    consumerKey: projectKeySchema,
+    artifactRef: stableUriSchema,
+    contentHash: sha256Schema,
+    outcome: knowledgeDeliveryOutcomeSchema,
+    attempts: z.number().int().positive().max(999999),
+    deliveredAt: isoDateTimeSchema,
+    nextAttemptAt: isoDateTimeSchema.nullable(),
+    externalRef: stableUriSchema.nullable(),
+    consumerResponseHash: sha256Schema.nullable(),
+    message: z.string().trim().min(1).max(4000).nullable(),
+}).strict().superRefine((value, ctx) => {
+    if (value.producerProjectRef) {
+        try {
+            const url = new URL(value.producerProjectRef);
+            if (url.protocol !== 'knowledge-project:' || url.hostname.toLowerCase() !== value.producerProjectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'producerProjectRef project must match producer project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['producerProjectRef'], message: 'Invalid producerProjectRef' });
+        }
+    }
+    if (value.outcome === 'DELIVERED' && value.nextAttemptAt)
+        ctx.addIssue({ code: 'custom', path: ['nextAttemptAt'], message: 'DELIVERED cannot schedule retry' });
+    if (value.outcome === 'FAILED_RETRYABLE' && !value.nextAttemptAt)
+        ctx.addIssue({ code: 'custom', path: ['nextAttemptAt'], message: 'FAILED_RETRYABLE requires nextAttemptAt' });
+    if (value.outcome === 'FAILED_RETRYABLE' && value.nextAttemptAt && Date.parse(value.nextAttemptAt) <= Date.parse(value.deliveredAt))
+        ctx.addIssue({ code: 'custom', path: ['nextAttemptAt'], message: 'Retry must be scheduled after this attempt completes' });
+    if (value.outcome !== 'FAILED_RETRYABLE' && value.nextAttemptAt)
+        ctx.addIssue({ code: 'custom', path: ['nextAttemptAt'], message: 'Only retryable failure may schedule retry' });
+});
+export const distributionConsumerSchema = z.object({
+    consumerKey: projectKeySchema,
+    enabled: z.boolean(),
+    artifactKinds: z.array(artifactKindSchema).min(1).max(16),
+    acceptedAccess: z.array(accessClassificationSchema).min(1).max(7),
+    supportPolicy: z.enum(['NONE', 'REQUIRE_ALLOW']),
+    adapter: z.string().trim().min(1).max(128),
+}).strict().superRefine((value, ctx) => {
+    if (value.artifactKinds.some((kind) => ['KNOWLEDGE', 'INSIGHT'].includes(kind)) && value.supportPolicy !== 'REQUIRE_ALLOW') {
+        ctx.addIssue({ code: 'custom', path: ['supportPolicy'], message: 'Knowledge/Insight distribution requires REQUIRE_ALLOW' });
+    }
+    if (new Set(value.acceptedAccess).size !== value.acceptedAccess.length)
+        ctx.addIssue({ code: 'custom', path: ['acceptedAccess'], message: 'acceptedAccess must be unique' });
+});
+export const distributionConfigSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    consumers: z.array(distributionConsumerSchema).max(128),
+}).strict().superRefine((value, ctx) => {
+    const keys = value.consumers.map((row) => row.consumerKey);
+    if (new Set(keys).size !== keys.length)
+        ctx.addIssue({ code: 'custom', path: ['consumers'], message: 'consumerKey must be unique' });
+});
+export const durableEvidenceManifestSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    evidenceRef: stableUriSchema,
+    evidence: evidenceRefSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.evidence.projectKey !== value.projectKey)
+        ctx.addIssue({ code: 'custom', path: ['evidence', 'projectKey'], message: 'Durable Evidence project must match manifest project' });
+    const expected = `evidence://${value.projectKey}/${encodeURIComponent(value.evidence.evidenceId)}`;
+    if (value.evidenceRef !== expected)
+        ctx.addIssue({ code: 'custom', path: ['evidenceRef'], message: 'Durable Evidence ref must match evidence identity' });
+    if (value.evidence.sourceSetRef) {
+        try {
+            if (new URL(value.evidence.sourceSetRef).hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['evidence', 'sourceSetRef'], message: 'Source Set project must match Evidence project' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['evidence', 'sourceSetRef'], message: 'Invalid Source Set ref' });
+        }
+    }
+});