@native-knowledge/knowledge-sdk 0.0.0-stage → 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/internal/contracts/index.d.ts

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

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+export declare const materialReadStateSchema: z.ZodEnum<{
+    MISSING: "MISSING";
+    INTEGRITY_MISMATCH: "INTEGRITY_MISMATCH";
+    READY: "READY";
+    UNSUPPORTED: "UNSUPPORTED";
+    DENIED: "DENIED";
+}>;
+export declare const materialCapabilitySchema: z.ZodObject<{
+    item: z.ZodObject<{
+        ref: z.ZodString;
+        resourceType: z.ZodString;
+        sourceProjectKey: z.ZodString;
+        identityHash: z.ZodString;
+        kind: z.ZodString;
+        classification: z.ZodEnum<{
+            PUBLIC: "PUBLIC";
+            PUBLIC_METADATA: "PUBLIC_METADATA";
+            TENANT: "TENANT";
+            INTERNAL: "INTERNAL";
+            FDE_INTERNAL: "FDE_INTERNAL";
+            ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+            UNKNOWN: "UNKNOWN";
+        }>;
+        mediaType: z.ZodString;
+        decision: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            action: z.ZodEnum<{
+                ALLOW: "ALLOW";
+                DENY: "DENY";
+            }>;
+            reasonCodes: z.ZodArray<z.ZodEnum<{
+                UNAVAILABLE: "UNAVAILABLE";
+                NOT_FOUND: "NOT_FOUND";
+                CONTENT_ACCESS_DENIED: "CONTENT_ACCESS_DENIED";
+                INTEGRITY_MISMATCH: "INTEGRITY_MISMATCH";
+                UNSUPPORTED_RESOURCE: "UNSUPPORTED_RESOURCE";
+            }>>;
+            assessedAt: z.ZodISODateTime;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    materialAccess: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            DENY: "DENY";
+        }>;
+        reasonCodes: z.ZodArray<z.ZodEnum<{
+            UNAVAILABLE: "UNAVAILABLE";
+            NOT_FOUND: "NOT_FOUND";
+            CONTENT_ACCESS_DENIED: "CONTENT_ACCESS_DENIED";
+            INTEGRITY_MISMATCH: "INTEGRITY_MISMATCH";
+            UNSUPPORTED_RESOURCE: "UNSUPPORTED_RESOURCE";
+        }>>;
+        assessedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    representation: z.ZodObject<{
+        state: z.ZodEnum<{
+            MISSING: "MISSING";
+            INTEGRITY_MISMATCH: "INTEGRITY_MISMATCH";
+            READY: "READY";
+            UNSUPPORTED: "UNSUPPORTED";
+            DENIED: "DENIED";
+        }>;
+        format: z.ZodEnum<{
+            BYTES: "BYTES";
+            JSON: "JSON";
+        }>;
+        transfer: z.ZodEnum<{
+            UNSUPPORTED: "UNSUPPORTED";
+            VERIFIED_STREAM: "VERIFIED_STREAM";
+            BUFFERED_JSON: "BUFFERED_JSON";
+        }>;
+        contentHash: z.ZodNullable<z.ZodString>;
+        mediaType: z.ZodString;
+        byteLength: z.ZodNullable<z.ZodNumber>;
+        methods: z.ZodArray<z.ZodEnum<{
+            GET: "GET";
+            HEAD: "HEAD";
+        }>>;
+        range: z.ZodEnum<{
+            NONE: "NONE";
+            SINGLE: "SINGLE";
+        }>;
+        verification: z.ZodLiteral<"ON_READ">;
+        verificationChunkBytes: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;

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

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+export declare const materialResourceTypeSchema: z.ZodString;
+/** Provenance-bearing immutable metadata; original bytes live only in the shared CAS. */
+export declare const materialCarrierManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    ref: z.ZodString;
+    projectKey: z.ZodString;
+    resourceType: z.ZodString;
+    kind: z.ZodString;
+    access: z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    title: z.ZodString;
+    summary: z.ZodString;
+    observedAt: z.ZodISODateTime;
+    sourceRefs: z.ZodArray<z.ZodString>;
+    sourceUri: z.ZodNullable<z.ZodString>;
+    sourceSetRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    storage: z.ZodLiteral<"CAS">;
+    contentHash: z.ZodString;
+    mediaType: z.ZodString;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>;
+export type MaterialCarrierManifest = z.infer<typeof materialCarrierManifestSchema>;
+export declare const materialRegistrationMetadataSchema: z.ZodObject<{
+    kind: z.ZodString;
+    projectKey: z.ZodString;
+    ref: z.ZodString;
+    access: z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    title: z.ZodString;
+    observedAt: z.ZodISODateTime;
+    mediaType: z.ZodString;
+    summary: z.ZodString;
+    sourceSetRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sourceUri: z.ZodNullable<z.ZodString>;
+    resourceType: z.ZodString;
+    sourceRefs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const materialRegistrationRequestSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    metadata: z.ZodObject<{
+        kind: z.ZodString;
+        projectKey: z.ZodString;
+        ref: z.ZodString;
+        access: z.ZodEnum<{
+            PUBLIC: "PUBLIC";
+            PUBLIC_METADATA: "PUBLIC_METADATA";
+            TENANT: "TENANT";
+            INTERNAL: "INTERNAL";
+            FDE_INTERNAL: "FDE_INTERNAL";
+            ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+            UNKNOWN: "UNKNOWN";
+        }>;
+        title: z.ZodString;
+        observedAt: z.ZodISODateTime;
+        mediaType: z.ZodString;
+        summary: z.ZodString;
+        sourceSetRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        sourceUri: z.ZodNullable<z.ZodString>;
+        resourceType: z.ZodString;
+        sourceRefs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    contentBase64: z.ZodString;
+}, z.core.$strict>;
+export declare const materialRegistrationInputJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    projectRef: z.ZodString;
+    metadata: z.ZodObject<{
+        kind: z.ZodString;
+        projectKey: z.ZodString;
+        ref: z.ZodString;
+        access: z.ZodEnum<{
+            PUBLIC: "PUBLIC";
+            PUBLIC_METADATA: "PUBLIC_METADATA";
+            TENANT: "TENANT";
+            INTERNAL: "INTERNAL";
+            FDE_INTERNAL: "FDE_INTERNAL";
+            ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+            UNKNOWN: "UNKNOWN";
+        }>;
+        title: z.ZodString;
+        observedAt: z.ZodISODateTime;
+        mediaType: z.ZodString;
+        summary: z.ZodString;
+        sourceSetRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        sourceUri: z.ZodNullable<z.ZodString>;
+        resourceType: z.ZodString;
+        sourceRefs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    contentBase64: z.ZodString;
+}, z.core.$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.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export declare const materialTenantIdSchema: z.ZodString;
+export declare const materialContextSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"TENANT">;
+    tenantId: z.ZodString;
+    tenantRef: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"PROJECT">;
+    tenantId: z.ZodString;
+    projectKey: z.ZodString;
+    projectRef: z.ZodString;
+}, z.core.$strict>], "type">;
+export type MaterialContext = z.infer<typeof materialContextSchema>;
+export declare const materialProjectScopeInputSchema: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+        TENANT: "TENANT";
+        EXPLICIT: "EXPLICIT";
+    }>>;
+    selectors: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            SOURCE_PROJECT: "SOURCE_PROJECT";
+            REF: "REF";
+        }>;
+        value: z.ZodString;
+        enabled: z.ZodBoolean;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type MaterialProjectScopeInput = z.infer<typeof materialProjectScopeInputSchema>;

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