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

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

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const resourceScopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"TENANT">;
+    tenantId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"PROJECT">;
+    tenantId: z.ZodString;
+    projectKey: z.ZodString;
+}, z.core.$strict>], "type">;
+export type ResourceScope = z.infer<typeof resourceScopeSchema>;
+export declare const materialAuthorityPolicySchema: z.ZodEnum<{
+    LEGACY_PROJECT: "LEGACY_PROJECT";
+    TENANT_NATIVE: "TENANT_NATIVE";
+    TENANT_PROJECT_SCOPE: "TENANT_PROJECT_SCOPE";
+}>;
+export type MaterialAuthorityPolicy = z.infer<typeof materialAuthorityPolicySchema>;
+export declare function tenantStorageKey(tenantId: string): string;
+export declare const tenantResourceIdentitySchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    resourceType: z.ZodString;
+    resourceId: z.ZodString;
+    version: z.ZodNumber;
+}, z.core.$strict>;
+export type TenantResourceIdentity = z.infer<typeof tenantResourceIdentitySchema>;
+export declare function tenantResourceRefs(input: TenantResourceIdentity): {
+    identityRef: string;
+    ref: string;
+};
+/** 必须精确匹配规范身份；URL 的容错正规化不能改变对象定位。 */
+export declare function parseTenantResourceRef(ref: string): Omit<TenantResourceIdentity, 'tenantId'> & {
+    storageKey: string;
+} | null;
+export declare const tenantResourceRefSchema: z.ZodString;
+export declare const TENANT_CORE_CAPABILITIES: {
+    readonly resource: "TENANT_RESOURCE_V1";
+    readonly authority: "TENANT_AUTHORITY_V1";
+    readonly source: "TENANT_SOURCE_V1";
+    readonly workflow: "TENANT_WORKFLOW_V1";
+    readonly budget: "TENANT_BUDGET_V1";
+};

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

@@ -0,0 +1,274 @@
+import { z } from 'zod';
+export declare const reviewPacketEvidenceSchema: z.ZodObject<{
+    evidenceRef: z.ZodString;
+    evidenceId: z.ZodString;
+    sourceId: z.ZodString;
+    sourceIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    projectRef: z.ZodOptional<z.ZodString>;
+    sourceRevisionRef: z.ZodOptional<z.ZodString>;
+    collectionBatchRef: z.ZodOptional<z.ZodString>;
+    collectionTaskId: z.ZodOptional<z.ZodString>;
+    canonicalUri: z.ZodOptional<z.ZodString>;
+    observedAt: z.ZodISODateTime;
+    access: z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    contentHash: z.ZodString;
+    mediaType: z.ZodOptional<z.ZodString>;
+    byteLength: z.ZodOptional<z.ZodNumber>;
+    currentness: z.ZodOptional<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        subjectRef: z.ZodString;
+        subjectKind: z.ZodEnum<{
+            SOURCE: "SOURCE";
+            EVIDENCE: "EVIDENCE";
+            ARTIFACT: "ARTIFACT";
+        }>;
+        projectRef: z.ZodOptional<z.ZodString>;
+        sourceRevisionRef: z.ZodOptional<z.ZodString>;
+        basisRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        state: z.ZodEnum<{
+            UNKNOWN: "UNKNOWN";
+            DUE: "DUE";
+            CURRENT: "CURRENT";
+            STALE: "STALE";
+            BLOCKED: "BLOCKED";
+        }>;
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        assessedAt: z.ZodISODateTime;
+        observedAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        lastSuccessAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        lastAttemptAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        dueAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        staleAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+        ageSeconds: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        reasonCode: z.ZodEnum<{
+            CURRENT_WITHIN_CADENCE: "CURRENT_WITHIN_CADENCE";
+            REFRESH_DUE: "REFRESH_DUE";
+            STALE_AFTER_THRESHOLD: "STALE_AFTER_THRESHOLD";
+            SOURCE_BLOCKED: "SOURCE_BLOCKED";
+            SOURCE_CONTENT_CHANGED: "SOURCE_CONTENT_CHANGED";
+            NO_SUCCESSFUL_OBSERVATION: "NO_SUCCESSFUL_OBSERVATION";
+        }>;
+        policy: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            dueAfterSeconds: z.ZodNumber;
+            staleAfterSeconds: z.ZodNumber;
+            staleAction: z.ZodDefault<z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>>;
+            unknownAction: z.ZodDefault<z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>>;
+            blockedAction: z.ZodDefault<z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    attachment: z.ZodObject<{
+        evidenceRef: z.ZodString;
+        contentHash: z.ZodString;
+        mediaType: z.ZodString;
+        byteLength: z.ZodNullable<z.ZodNumber>;
+        modality: z.ZodEnum<{
+            TEXT: "TEXT";
+            PDF: "PDF";
+            IMAGE: "IMAGE";
+            AUDIO: "AUDIO";
+            VIDEO: "VIDEO";
+            BINARY: "BINARY";
+        }>;
+        reviewMode: z.ZodEnum<{
+            TEXT_NATIVE: "TEXT_NATIVE";
+            MULTIMODAL_NATIVE: "MULTIMODAL_NATIVE";
+            EXTERNAL_EXTRACTOR_REQUIRED: "EXTERNAL_EXTRACTOR_REQUIRED";
+        }>;
+        instruction: z.ZodEnum<{
+            READ_ORIGINAL_TEXT: "READ_ORIGINAL_TEXT";
+            INSPECT_ORIGINAL_DOCUMENT: "INSPECT_ORIGINAL_DOCUMENT";
+            INSPECT_ORIGINAL_IMAGE: "INSPECT_ORIGINAL_IMAGE";
+            LISTEN_TO_ORIGINAL_AUDIO: "LISTEN_TO_ORIGINAL_AUDIO";
+            INSPECT_ORIGINAL_VIDEO: "INSPECT_ORIGINAL_VIDEO";
+            USE_APPROVED_EXTERNAL_EXTRACTOR: "USE_APPROVED_EXTERNAL_EXTRACTOR";
+        }>;
+        rawBytesEmbedded: z.ZodLiteral<false>;
+        materializationRequired: z.ZodLiteral<true>;
+        reviewHints: z.ZodOptional<z.ZodObject<{
+            pageRanges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                startPage: z.ZodNumber;
+                endPage: z.ZodNumber;
+            }, z.core.$strict>>>;
+            timeRanges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                startMs: z.ZodNumber;
+                endMs: z.ZodNumber;
+            }, z.core.$strict>>>;
+            frameTimestampsMs: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const reviewPacketSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    packetType: z.ZodLiteral<"KNOWLEDGE_REVIEW_PACKET">;
+    projectKey: z.ZodString;
+    projectRef: z.ZodOptional<z.ZodString>;
+    sourceEvent: z.ZodObject<{
+        eventId: z.ZodString;
+        type: z.ZodEnum<{
+            SOURCE_CHANGED: "SOURCE_CHANGED";
+            BOUNDARY_RISK: "BOUNDARY_RISK";
+            CURRENTNESS_RISK: "CURRENTNESS_RISK";
+        }>;
+        createdAt: z.ZodISODateTime;
+        runtimeNodeId: z.ZodOptional<z.ZodString>;
+        sourceRef: z.ZodOptional<z.ZodString>;
+        sourceRevisionRef: z.ZodOptional<z.ZodString>;
+        collectionBatchRef: z.ZodOptional<z.ZodString>;
+        contentHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    evidence: z.ZodArray<z.ZodObject<{
+        evidenceRef: z.ZodString;
+        evidenceId: z.ZodString;
+        sourceId: z.ZodString;
+        sourceIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        projectRef: z.ZodOptional<z.ZodString>;
+        sourceRevisionRef: z.ZodOptional<z.ZodString>;
+        collectionBatchRef: z.ZodOptional<z.ZodString>;
+        collectionTaskId: z.ZodOptional<z.ZodString>;
+        canonicalUri: z.ZodOptional<z.ZodString>;
+        observedAt: z.ZodISODateTime;
+        access: z.ZodEnum<{
+            PUBLIC: "PUBLIC";
+            PUBLIC_METADATA: "PUBLIC_METADATA";
+            TENANT: "TENANT";
+            INTERNAL: "INTERNAL";
+            FDE_INTERNAL: "FDE_INTERNAL";
+            ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+            UNKNOWN: "UNKNOWN";
+        }>;
+        contentHash: z.ZodString;
+        mediaType: z.ZodOptional<z.ZodString>;
+        byteLength: z.ZodOptional<z.ZodNumber>;
+        currentness: z.ZodOptional<z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            subjectRef: z.ZodString;
+            subjectKind: z.ZodEnum<{
+                SOURCE: "SOURCE";
+                EVIDENCE: "EVIDENCE";
+                ARTIFACT: "ARTIFACT";
+            }>;
+            projectRef: z.ZodOptional<z.ZodString>;
+            sourceRevisionRef: z.ZodOptional<z.ZodString>;
+            basisRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            state: z.ZodEnum<{
+                UNKNOWN: "UNKNOWN";
+                DUE: "DUE";
+                CURRENT: "CURRENT";
+                STALE: "STALE";
+                BLOCKED: "BLOCKED";
+            }>;
+            action: z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>;
+            assessedAt: z.ZodISODateTime;
+            observedAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+            lastSuccessAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+            lastAttemptAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+            dueAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+            staleAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+            ageSeconds: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+            reasonCode: z.ZodEnum<{
+                CURRENT_WITHIN_CADENCE: "CURRENT_WITHIN_CADENCE";
+                REFRESH_DUE: "REFRESH_DUE";
+                STALE_AFTER_THRESHOLD: "STALE_AFTER_THRESHOLD";
+                SOURCE_BLOCKED: "SOURCE_BLOCKED";
+                SOURCE_CONTENT_CHANGED: "SOURCE_CONTENT_CHANGED";
+                NO_SUCCESSFUL_OBSERVATION: "NO_SUCCESSFUL_OBSERVATION";
+            }>;
+            policy: z.ZodObject<{
+                schemaVersion: z.ZodLiteral<1>;
+                dueAfterSeconds: z.ZodNumber;
+                staleAfterSeconds: z.ZodNumber;
+                staleAction: z.ZodDefault<z.ZodEnum<{
+                    ALLOW: "ALLOW";
+                    REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                    DENY: "DENY";
+                }>>;
+                unknownAction: z.ZodDefault<z.ZodEnum<{
+                    ALLOW: "ALLOW";
+                    REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                    DENY: "DENY";
+                }>>;
+                blockedAction: z.ZodDefault<z.ZodEnum<{
+                    ALLOW: "ALLOW";
+                    REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                    DENY: "DENY";
+                }>>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        attachment: z.ZodObject<{
+            evidenceRef: z.ZodString;
+            contentHash: z.ZodString;
+            mediaType: z.ZodString;
+            byteLength: z.ZodNullable<z.ZodNumber>;
+            modality: z.ZodEnum<{
+                TEXT: "TEXT";
+                PDF: "PDF";
+                IMAGE: "IMAGE";
+                AUDIO: "AUDIO";
+                VIDEO: "VIDEO";
+                BINARY: "BINARY";
+            }>;
+            reviewMode: z.ZodEnum<{
+                TEXT_NATIVE: "TEXT_NATIVE";
+                MULTIMODAL_NATIVE: "MULTIMODAL_NATIVE";
+                EXTERNAL_EXTRACTOR_REQUIRED: "EXTERNAL_EXTRACTOR_REQUIRED";
+            }>;
+            instruction: z.ZodEnum<{
+                READ_ORIGINAL_TEXT: "READ_ORIGINAL_TEXT";
+                INSPECT_ORIGINAL_DOCUMENT: "INSPECT_ORIGINAL_DOCUMENT";
+                INSPECT_ORIGINAL_IMAGE: "INSPECT_ORIGINAL_IMAGE";
+                LISTEN_TO_ORIGINAL_AUDIO: "LISTEN_TO_ORIGINAL_AUDIO";
+                INSPECT_ORIGINAL_VIDEO: "INSPECT_ORIGINAL_VIDEO";
+                USE_APPROVED_EXTERNAL_EXTRACTOR: "USE_APPROVED_EXTERNAL_EXTRACTOR";
+            }>;
+            rawBytesEmbedded: z.ZodLiteral<false>;
+            materializationRequired: z.ZodLiteral<true>;
+            reviewHints: z.ZodOptional<z.ZodObject<{
+                pageRanges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    startPage: z.ZodNumber;
+                    endPage: z.ZodNumber;
+                }, z.core.$strict>>>;
+                timeRanges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    startMs: z.ZodNumber;
+                    endMs: z.ZodNumber;
+                }, z.core.$strict>>>;
+                frameTimestampsMs: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    reviewPolicy: z.ZodObject<{
+        semanticSynthesisRequired: z.ZodLiteral<true>;
+        rawChunkApprovalForbidden: z.ZodLiteral<true>;
+        highRiskAutoApprovalForbidden: z.ZodLiteral<true>;
+        decisions: z.ZodTuple<[z.ZodLiteral<"PASS">, z.ZodLiteral<"REWORK">, z.ZodLiteral<"REJECT">], null>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ReviewPacket = z.infer<typeof reviewPacketSchema>;

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

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+export declare const reviewPlaneStageSchema: z.ZodEnum<{
+    REVIEWED: "REVIEWED";
+    PROGRAM: "PROGRAM";
+    INBOX: "INBOX";
+    USER_APPROVED: "USER_APPROVED";
+    PROMOTION_RECEIPTS: "PROMOTION_RECEIPTS";
+    GUIDES: "GUIDES";
+    REJECTED_SUPERSEDED: "REJECTED_SUPERSEDED";
+}>;
+export declare const reviewPlaneWorkspaceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    provider: z.ZodLiteral<"GOOGLE_DRIVE">;
+    rootPath: z.ZodString;
+    folders: z.ZodObject<{
+        PROGRAM: z.ZodString;
+        INBOX: z.ZodString;
+        REVIEWED: z.ZodString;
+        USER_APPROVED: z.ZodString;
+        PROMOTION_RECEIPTS: z.ZodString;
+        GUIDES: z.ZodOptional<z.ZodString>;
+        REJECTED_SUPERSEDED: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const reviewPlaneApprovalSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    approvalId: z.ZodString;
+    projectKey: z.ZodString;
+    sourceProvider: z.ZodLiteral<"GOOGLE_DRIVE">;
+    sourcePath: z.ZodString;
+    sourceFileId: z.ZodNullable<z.ZodString>;
+    sourceContentHash: z.ZodString;
+    sourceArtifactRef: z.ZodNullable<z.ZodString>;
+    reviewedAt: z.ZodISODateTime;
+    approvedAt: z.ZodISODateTime;
+    decision: z.ZodLiteral<"PASS">;
+    approvalAuthority: z.ZodLiteral<"EXPLICIT_HUMAN">;
+    hostDisposition: z.ZodEnum<{
+        APPROVED_RESEARCH: "APPROVED_RESEARCH";
+        APPROVED_KNOWLEDGE: "APPROVED_KNOWLEDGE";
+        APPROVED_INSIGHT: "APPROVED_INSIGHT";
+    }>;
+    targetArtifactId: z.ZodString;
+    targetVersion: z.ZodNumber;
+    targetTitle: z.ZodString;
+    mediaType: z.ZodString;
+    observedAt: z.ZodNullable<z.ZodISODateTime>;
+    validUntil: z.ZodNullable<z.ZodISODateTime>;
+    access: z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    evidenceRefs: z.ZodArray<z.ZodString>;
+    approvalEvidenceRefs: z.ZodArray<z.ZodString>;
+    supersedesRef: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const reviewPlanePromotionReceiptSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    approvalId: z.ZodString;
+    sourcePath: z.ZodString;
+    sourceFileId: z.ZodNullable<z.ZodString>;
+    sourceContentHash: z.ZodString;
+    promotedAt: z.ZodISODateTime;
+    targetKind: z.ZodEnum<{
+        SIGNAL_GENERATION: "SIGNAL_GENERATION";
+        RESEARCH: "RESEARCH";
+        REVIEW: "REVIEW";
+        KNOWLEDGE: "KNOWLEDGE";
+        INSIGHT: "INSIGHT";
+    }>;
+    draftRef: z.ZodString;
+    readyRef: z.ZodString;
+    reviewRef: z.ZodString;
+    approvedRef: z.ZodString;
+    approvedContentHash: z.ZodString;
+    exactBytesVerified: z.ZodLiteral<true>;
+    humanApprovalVerified: z.ZodLiteral<true>;
+    automaticPromotion: z.ZodLiteral<false>;
+}, z.core.$strict>;
+export type ReviewPlaneStage = z.infer<typeof reviewPlaneStageSchema>;
+export type ReviewPlaneWorkspace = z.infer<typeof reviewPlaneWorkspaceSchema>;
+export type ReviewPlaneApproval = z.infer<typeof reviewPlaneApprovalSchema>;
+export type ReviewPlanePromotionReceipt = z.infer<typeof reviewPlanePromotionReceiptSchema>;