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

package/dist/types/contracts/reference-record.d.ts

@@ -0,0 +1,124 @@
+/** Canonical Reference facts and producer annotations; no consumer admission policy. */
+import { z } from 'zod';
+export declare const referenceRecordTypeSchema: z.ZodString;
+export declare const referenceCurrentnessActionSchema: z.ZodEnum<{
+    ALLOW: "ALLOW";
+    REVIEW_REQUIRED: "REVIEW_REQUIRED";
+    DENY: "DENY";
+}>;
+export declare const referenceSelectorKeySchema: z.ZodString;
+export declare const referenceSelectorValueSchema: z.ZodString;
+export declare const referenceSelectorsSchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+export declare const referenceCurrentnessStateSchema: z.ZodEnum<{
+    DUE: "DUE";
+    CURRENT: "CURRENT";
+    STALE: "STALE";
+    UNAVAILABLE: "UNAVAILABLE";
+    NOT_COVERED: "NOT_COVERED";
+}>;
+export declare const referenceCurrentnessSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        DUE: "DUE";
+        CURRENT: "CURRENT";
+        STALE: "STALE";
+        UNAVAILABLE: "UNAVAILABLE";
+        NOT_COVERED: "NOT_COVERED";
+    }>;
+    action: z.ZodEnum<{
+        ALLOW: "ALLOW";
+        REVIEW_REQUIRED: "REVIEW_REQUIRED";
+        DENY: "DENY";
+    }>;
+    assessedAt: z.ZodISODateTime;
+    validUntil: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export declare const referenceCorpusSummarySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    corpusKey: z.ZodString;
+    recordKey: z.ZodString;
+    recordRef: z.ZodString;
+    recordType: z.ZodString;
+    projectKey: z.ZodString;
+    projectRef: z.ZodOptional<z.ZodString>;
+    version: z.ZodNumber;
+    supersedesRef: z.ZodNullable<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";
+    }>;
+    authority: z.ZodString;
+    jurisdiction: z.ZodNullable<z.ZodString>;
+    selectors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    sourceRefs: z.ZodArray<z.ZodString>;
+    digest: z.ZodString;
+    effectiveFrom: z.ZodNullable<z.ZodISODateTime>;
+    effectiveUntil: z.ZodNullable<z.ZodISODateTime>;
+    currentness: z.ZodObject<{
+        state: z.ZodEnum<{
+            DUE: "DUE";
+            CURRENT: "CURRENT";
+            STALE: "STALE";
+            UNAVAILABLE: "UNAVAILABLE";
+            NOT_COVERED: "NOT_COVERED";
+        }>;
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        assessedAt: z.ZodISODateTime;
+        validUntil: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const referenceCorpusRecordSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    corpusKey: z.ZodString;
+    recordKey: z.ZodString;
+    recordRef: z.ZodString;
+    recordType: z.ZodString;
+    projectKey: z.ZodString;
+    projectRef: z.ZodOptional<z.ZodString>;
+    version: z.ZodNumber;
+    supersedesRef: z.ZodNullable<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";
+    }>;
+    authority: z.ZodString;
+    jurisdiction: z.ZodNullable<z.ZodString>;
+    selectors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    sourceRefs: z.ZodArray<z.ZodString>;
+    digest: z.ZodString;
+    effectiveFrom: z.ZodNullable<z.ZodISODateTime>;
+    effectiveUntil: z.ZodNullable<z.ZodISODateTime>;
+    currentness: z.ZodObject<{
+        state: z.ZodEnum<{
+            DUE: "DUE";
+            CURRENT: "CURRENT";
+            STALE: "STALE";
+            UNAVAILABLE: "UNAVAILABLE";
+            NOT_COVERED: "NOT_COVERED";
+        }>;
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        assessedAt: z.ZodISODateTime;
+        validUntil: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    payload: z.ZodJSONSchema;
+}, z.core.$strict>;
+export type ReferenceSelectors = z.infer<typeof referenceSelectorsSchema>;
+export type ReferenceCorpusSummary = z.infer<typeof referenceCorpusSummarySchema>;
+export type ReferenceCorpusRecord = z.infer<typeof referenceCorpusRecordSchema>;

package/dist/types/contracts/remote-file.d.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+export declare const remoteArchiveFormatSchema: z.ZodEnum<{
+    TAR_GZ: "TAR_GZ";
+    ZIP: "ZIP";
+}>;
+export declare const remoteManifestFormatSchema: z.ZodEnum<{
+    FILES_V1: "FILES_V1";
+    LEGACY_PAGES_V1: "LEGACY_PAGES_V1";
+}>;
+export declare const remoteBundlePathSchema: z.ZodString;
+export declare const remoteFileBundleDeclarationSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    artifactSha256: z.ZodString;
+    byteLength: z.ZodNumber;
+    archiveFormat: z.ZodEnum<{
+        TAR_GZ: "TAR_GZ";
+        ZIP: "ZIP";
+    }>;
+    manifestPath: z.ZodString;
+    manifestSha256: z.ZodString;
+    artifactKind: z.ZodString;
+    familyId: z.ZodString;
+    targetId: z.ZodString;
+    jurisdiction: z.ZodNullable<z.ZodString>;
+    sourceWorker: z.ZodString;
+    remoteArtifactRef: z.ZodNullable<z.ZodString>;
+    declaredAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const remoteFileManifestEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodString;
+    byteLength: z.ZodNumber;
+    mediaType: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sourceUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const remoteFileBundleManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectKey: z.ZodString;
+    artifactKind: z.ZodString;
+    familyId: z.ZodString;
+    targetId: z.ZodString;
+    jurisdiction: z.ZodNullable<z.ZodString>;
+    generatedAt: z.ZodISODateTime;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        byteLength: z.ZodNumber;
+        mediaType: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        sourceUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const remoteVerifiedFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    contentHash: z.ZodString;
+    byteLength: z.ZodNumber;
+    mediaType: z.ZodNullable<z.ZodString>;
+    sourceUrl: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const remoteFileVerificationReceiptSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    verificationRef: z.ZodString;
+    projectKey: z.ZodString;
+    declarationDigest: z.ZodString;
+    artifactSha256: z.ZodString;
+    byteLength: z.ZodNumber;
+    archiveFormat: z.ZodEnum<{
+        TAR_GZ: "TAR_GZ";
+        ZIP: "ZIP";
+    }>;
+    manifestPath: z.ZodString;
+    manifestSha256: z.ZodString;
+    manifestFormat: z.ZodEnum<{
+        FILES_V1: "FILES_V1";
+        LEGACY_PAGES_V1: "LEGACY_PAGES_V1";
+    }>;
+    manifestGeneratedAt: z.ZodNullable<z.ZodISODateTime>;
+    artifactKind: z.ZodString;
+    familyId: z.ZodString;
+    targetId: z.ZodString;
+    jurisdiction: z.ZodNullable<z.ZodString>;
+    sourceWorker: z.ZodString;
+    remoteArtifactRef: z.ZodNullable<z.ZodString>;
+    verifierNodeId: z.ZodString;
+    verifiedAt: z.ZodISODateTime;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        contentHash: z.ZodString;
+        byteLength: z.ZodNumber;
+        mediaType: z.ZodNullable<z.ZodString>;
+        sourceUrl: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const remoteFileProjectSourceBindingSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    bindingRef: z.ZodString;
+    verificationRef: z.ZodString;
+    projectKey: z.ZodString;
+    artifactSha256: z.ZodString;
+    projectRef: z.ZodString;
+    projectIntentRef: z.ZodString;
+    sourceId: z.ZodString;
+    sourceRef: z.ZodString;
+    sourceRevisionId: z.ZodString;
+    sourceRevisionRef: z.ZodString;
+    projectSourceTargetId: z.ZodString;
+    boundAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const remoteFileIngestReceiptSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    ingestRef: z.ZodString;
+    verificationRef: z.ZodString;
+    projectKey: z.ZodString;
+    artifactSha256: z.ZodString;
+    sourceBindingRef: z.ZodOptional<z.ZodString>;
+    consumerKey: z.ZodString;
+    resultRefs: z.ZodArray<z.ZodString>;
+    ingestedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type RemoteArchiveFormat = z.infer<typeof remoteArchiveFormatSchema>;
+export type RemoteManifestFormat = z.infer<typeof remoteManifestFormatSchema>;
+export type RemoteFileBundleDeclaration = z.infer<typeof remoteFileBundleDeclarationSchema>;
+export type RemoteFileManifestEntry = z.infer<typeof remoteFileManifestEntrySchema>;
+export type RemoteFileBundleManifest = z.infer<typeof remoteFileBundleManifestSchema>;
+export type RemoteVerifiedFile = z.infer<typeof remoteVerifiedFileSchema>;
+export type RemoteFileVerificationReceipt = z.infer<typeof remoteFileVerificationReceiptSchema>;
+export type RemoteFileProjectSourceBinding = z.infer<typeof remoteFileProjectSourceBindingSchema>;
+export type RemoteFileIngestReceipt = z.infer<typeof remoteFileIngestReceiptSchema>;

package/dist/types/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/types/contracts/resource-transfer.d.ts

@@ -0,0 +1,24 @@
+/** Explicit transfer binding leaves historical Provider16 JSON and clients unchanged. */
+import { z } from 'zod';
+export declare const resourceTransferRequestHeader = "x-knowledge-resource-transfer";
+export declare const resourceTransferFeature = "context-v1";
+export declare const resourceTransferResponseHeader = "x-knowledge-resource-context";
+export declare const resourceTransferBindingSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    context: 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">;
+    policy: z.ZodEnum<{
+        LEGACY_PROJECT: "LEGACY_PROJECT";
+        TENANT_NATIVE: "TENANT_NATIVE";
+        TENANT_PROJECT_SCOPE: "TENANT_PROJECT_SCOPE";
+    }>;
+    refHash: z.ZodString;
+}, z.core.$strict>;

package/dist/types/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/types/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>;