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

package/dist/internal/contracts/public-reference.d.ts

@@ -0,0 +1,237 @@
+import { z } from 'zod';
+export declare const publicReferenceCatalogueScopeSchema: z.ZodObject<{
+    countryCode: z.ZodString;
+    topicKey: z.ZodString;
+    scopeRef: z.ZodString;
+    coverage: z.ZodEnum<{
+        PARTIAL: "PARTIAL";
+        OBSERVED: "OBSERVED";
+    }>;
+}, z.core.$strict>;
+export declare const publicReferenceApprovedSourceSchema: z.ZodObject<{
+    sourceRef: z.ZodString;
+    contentHash: z.ZodString;
+}, z.core.$strict>;
+export declare const publicReferenceLegacyReviewSchema: z.ZodObject<{
+    authority: z.ZodLiteral<"AUTHORIZED_PUBLISHER">;
+    reviewedAt: z.ZodISODateTime;
+    note: z.ZodString;
+    approvedSources: z.ZodArray<z.ZodObject<{
+        sourceRef: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const publicReferencePolicySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    policyId: z.ZodString;
+    revision: z.ZodNumber;
+    enabled: z.ZodBoolean;
+    sourceProjectKey: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        corpusKey: z.ZodString;
+        catalogue: z.ZodObject<{
+            countryCode: z.ZodString;
+            topicKey: z.ZodString;
+            scopeRef: z.ZodString;
+            coverage: z.ZodEnum<{
+                PARTIAL: "PARTIAL";
+                OBSERVED: "OBSERVED";
+            }>;
+        }, z.core.$strict>;
+        recordTypes: z.ZodArray<z.ZodString>;
+        authorities: z.ZodArray<z.ZodString>;
+        minimumRecordCount: z.ZodNumber;
+        maximumAssessmentAgeSeconds: z.ZodNumber;
+        sources: z.ZodArray<z.ZodObject<{
+            collectorId: z.ZodString;
+            sourceIds: z.ZodArray<z.ZodString>;
+            origin: z.ZodString;
+            pathPrefixes: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const publicReferenceMachineReviewSchema: z.ZodObject<{
+    authority: z.ZodLiteral<"POLICY_ENGINE">;
+    reviewedAt: z.ZodISODateTime;
+    note: z.ZodLiteral<"DETERMINISTIC_PUBLIC_SOURCE_VALIDATION">;
+    validationRule: z.ZodLiteral<"public-reference.policy.v1">;
+    policyId: z.ZodString;
+    policyRevision: z.ZodNumber;
+    policyDigest: z.ZodString;
+    executorRevision: z.ZodString;
+    approvedSources: z.ZodArray<z.ZodObject<{
+        sourceRef: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const publicReferenceReviewSchema: z.ZodUnion<readonly [z.ZodObject<{
+    authority: z.ZodLiteral<"AUTHORIZED_PUBLISHER">;
+    reviewedAt: z.ZodISODateTime;
+    note: z.ZodString;
+    approvedSources: z.ZodArray<z.ZodObject<{
+        sourceRef: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    authority: z.ZodLiteral<"POLICY_ENGINE">;
+    reviewedAt: z.ZodISODateTime;
+    note: z.ZodLiteral<"DETERMINISTIC_PUBLIC_SOURCE_VALIDATION">;
+    validationRule: z.ZodLiteral<"public-reference.policy.v1">;
+    policyId: z.ZodString;
+    policyRevision: z.ZodNumber;
+    policyDigest: z.ZodString;
+    executorRevision: z.ZodString;
+    approvedSources: z.ZodArray<z.ZodObject<{
+        sourceRef: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
+export type PublicReferencePolicy = z.infer<typeof publicReferencePolicySchema>;
+export declare const publicReferencePublishInputSchema: z.ZodObject<{
+    publicationKey: z.ZodString;
+    corpusKey: z.ZodString;
+    releaseId: z.ZodString;
+    recordsContentHash: z.ZodString;
+    catalogue: z.ZodObject<{
+        countryCode: z.ZodString;
+        topicKey: z.ZodString;
+        scopeRef: z.ZodString;
+        coverage: z.ZodEnum<{
+            PARTIAL: "PARTIAL";
+            OBSERVED: "OBSERVED";
+        }>;
+    }, z.core.$strict>;
+    review: z.ZodUnion<readonly [z.ZodObject<{
+        authority: z.ZodLiteral<"AUTHORIZED_PUBLISHER">;
+        reviewedAt: z.ZodISODateTime;
+        note: z.ZodString;
+        approvedSources: z.ZodArray<z.ZodObject<{
+            sourceRef: z.ZodString;
+            contentHash: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        authority: z.ZodLiteral<"POLICY_ENGINE">;
+        reviewedAt: z.ZodISODateTime;
+        note: z.ZodLiteral<"DETERMINISTIC_PUBLIC_SOURCE_VALIDATION">;
+        validationRule: z.ZodLiteral<"public-reference.policy.v1">;
+        policyId: z.ZodString;
+        policyRevision: z.ZodNumber;
+        policyDigest: z.ZodString;
+        executorRevision: z.ZodString;
+        approvedSources: z.ZodArray<z.ZodObject<{
+            sourceRef: z.ZodString;
+            contentHash: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+export declare const publicReferenceWithdrawInputSchema: z.ZodObject<{
+    publicationRef: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export declare const publicReferencePublicationBasisSchema: z.ZodObject<{
+    schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+    visibility: z.ZodLiteral<"PUBLIC_REFERENCE">;
+    sourceProjectKey: z.ZodString;
+    corpusKey: z.ZodString;
+    sourceReleaseId: z.ZodString;
+    sourceReleaseRef: z.ZodString;
+    recordsContentHash: z.ZodString;
+    recordsByteLength: z.ZodNumber;
+    recordCount: z.ZodNumber;
+    recordTypes: z.ZodArray<z.ZodString>;
+    sourceCreatedAt: z.ZodISODateTime;
+    catalogue: z.ZodObject<{
+        countryCode: z.ZodString;
+        topicKey: z.ZodString;
+        scopeRef: z.ZodString;
+        coverage: z.ZodEnum<{
+            PARTIAL: "PARTIAL";
+            OBSERVED: "OBSERVED";
+        }>;
+    }, z.core.$strict>;
+    review: z.ZodUnion<readonly [z.ZodObject<{
+        authority: z.ZodLiteral<"AUTHORIZED_PUBLISHER">;
+        reviewedAt: z.ZodISODateTime;
+        note: z.ZodString;
+        approvedSources: z.ZodArray<z.ZodObject<{
+            sourceRef: z.ZodString;
+            contentHash: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        authority: z.ZodLiteral<"POLICY_ENGINE">;
+        reviewedAt: z.ZodISODateTime;
+        note: z.ZodLiteral<"DETERMINISTIC_PUBLIC_SOURCE_VALIDATION">;
+        validationRule: z.ZodLiteral<"public-reference.policy.v1">;
+        policyId: z.ZodString;
+        policyRevision: z.ZodNumber;
+        policyDigest: z.ZodString;
+        executorRevision: z.ZodString;
+        approvedSources: z.ZodArray<z.ZodObject<{
+            sourceRef: z.ZodString;
+            contentHash: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>]>;
+    publishedAt: z.ZodISODateTime;
+    checkedAt: z.ZodISODateTime;
+    validUntil: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const publicReferencePublicationSchema: z.ZodObject<{
+    schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+    visibility: z.ZodLiteral<"PUBLIC_REFERENCE">;
+    sourceProjectKey: z.ZodString;
+    corpusKey: z.ZodString;
+    sourceReleaseId: z.ZodString;
+    sourceReleaseRef: z.ZodString;
+    recordsContentHash: z.ZodString;
+    recordsByteLength: z.ZodNumber;
+    recordCount: z.ZodNumber;
+    recordTypes: z.ZodArray<z.ZodString>;
+    sourceCreatedAt: z.ZodISODateTime;
+    catalogue: z.ZodObject<{
+        countryCode: z.ZodString;
+        topicKey: z.ZodString;
+        scopeRef: z.ZodString;
+        coverage: z.ZodEnum<{
+            PARTIAL: "PARTIAL";
+            OBSERVED: "OBSERVED";
+        }>;
+    }, z.core.$strict>;
+    review: z.ZodUnion<readonly [z.ZodObject<{
+        authority: z.ZodLiteral<"AUTHORIZED_PUBLISHER">;
+        reviewedAt: z.ZodISODateTime;
+        note: z.ZodString;
+        approvedSources: z.ZodArray<z.ZodObject<{
+            sourceRef: z.ZodString;
+            contentHash: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        authority: z.ZodLiteral<"POLICY_ENGINE">;
+        reviewedAt: z.ZodISODateTime;
+        note: z.ZodLiteral<"DETERMINISTIC_PUBLIC_SOURCE_VALIDATION">;
+        validationRule: z.ZodLiteral<"public-reference.policy.v1">;
+        policyId: z.ZodString;
+        policyRevision: z.ZodNumber;
+        policyDigest: z.ZodString;
+        executorRevision: z.ZodString;
+        approvedSources: z.ZodArray<z.ZodObject<{
+            sourceRef: z.ZodString;
+            contentHash: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>]>;
+    publishedAt: z.ZodISODateTime;
+    checkedAt: z.ZodISODateTime;
+    validUntil: z.ZodISODateTime;
+    publicationId: z.ZodString;
+    publicationRef: z.ZodString;
+}, z.core.$strict>;
+export declare const publicReferenceCatalogueQuerySchema: z.ZodObject<{
+    countryCode: z.ZodOptional<z.ZodString>;
+    topicKey: z.ZodOptional<z.ZodString>;
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type PublicReferencePublishInput = z.infer<typeof publicReferencePublishInputSchema>;
+export type PublicReferencePublicationBasis = z.infer<typeof publicReferencePublicationBasisSchema>;
+export type PublicReferencePublication = z.infer<typeof publicReferencePublicationSchema>;
+export type PublicReferenceCatalogueQuery = z.infer<typeof publicReferenceCatalogueQuerySchema>;
+export declare function publicReferencePublicationBasis(value: PublicReferencePublication): PublicReferencePublicationBasis;

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

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { isoDateTimeSchema, projectKeySchema, sha256Schema, stableUriSchema } from './common.js';
+export const publicReferenceCatalogueScopeSchema = z.object({
+    countryCode: z.string().regex(/^[A-Z]{2}$/),
+    topicKey: projectKeySchema,
+    scopeRef: stableUriSchema,
+    // Publication permission is distinct from an independent completeness proof.
+    coverage: z.enum(['OBSERVED', 'PARTIAL']),
+}).strict();
+export const publicReferenceApprovedSourceSchema = z.object({ sourceRef: stableUriSchema, contentHash: sha256Schema }).strict();
+export const publicReferenceLegacyReviewSchema = z.object({
+    authority: z.literal('AUTHORIZED_PUBLISHER'),
+    reviewedAt: isoDateTimeSchema,
+    note: z.string().trim().min(1).max(2000),
+    approvedSources: z.array(publicReferenceApprovedSourceSchema).min(1).max(256),
+}).strict().superRefine((value, ctx) => {
+    if (new Set(value.approvedSources.map(s => s.sourceRef)).size !== value.approvedSources.length)
+        ctx.addIssue({ code: 'custom', message: 'approvedSources must be unique' });
+});
+export const publicReferencePolicySchema = z.object({
+    schemaVersion: z.literal(1), policyId: projectKeySchema, revision: z.number().int().positive(), enabled: z.boolean(),
+    sourceProjectKey: projectKeySchema,
+    entries: z.array(z.object({
+        corpusKey: projectKeySchema, catalogue: publicReferenceCatalogueScopeSchema,
+        recordTypes: z.array(projectKeySchema).min(1).max(128), authorities: z.array(z.string().trim().min(1).max(256)).min(1).max(128),
+        minimumRecordCount: z.number().int().positive().max(100_000),
+        maximumAssessmentAgeSeconds: z.number().int().positive().max(31_536_000),
+        sources: z.array(z.object({
+            collectorId: z.string().trim().min(1).max(128), sourceIds: z.array(z.string().trim().min(1).max(128)).min(1).max(256),
+            origin: z.string().url().refine(value => { const u = new URL(value); return u.protocol === 'https:' && u.origin === value; }),
+            pathPrefixes: z.array(z.string().regex(/^\//).max(2048)).min(1).max(128),
+        }).strict()).min(1).max(256),
+    }).strict()).min(1).max(128),
+}).strict().superRefine((value, ctx) => {
+    if (Buffer.byteLength(JSON.stringify(value)) > 1024 * 1024)
+        ctx.addIssue({ code: 'custom', message: 'Policy exceeds 1 MiB' });
+    if (new Set(value.entries.map(entry => entry.corpusKey)).size !== value.entries.length)
+        ctx.addIssue({ code: 'custom', message: 'Policy corpus keys must be unique' });
+});
+export const publicReferenceMachineReviewSchema = z.object({
+    authority: z.literal('POLICY_ENGINE'), reviewedAt: isoDateTimeSchema,
+    note: z.literal('DETERMINISTIC_PUBLIC_SOURCE_VALIDATION'),
+    validationRule: z.literal('public-reference.policy.v1'), policyId: projectKeySchema,
+    policyRevision: z.number().int().positive(), policyDigest: sha256Schema,
+    executorRevision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    approvedSources: z.array(publicReferenceApprovedSourceSchema).max(256),
+}).strict();
+export const publicReferenceReviewSchema = z.union([publicReferenceLegacyReviewSchema, publicReferenceMachineReviewSchema]);
+export const publicReferencePublishInputSchema = z.object({
+    publicationKey: projectKeySchema, corpusKey: projectKeySchema, releaseId: sha256Schema, recordsContentHash: sha256Schema,
+    catalogue: publicReferenceCatalogueScopeSchema, review: publicReferenceReviewSchema,
+}).strict();
+export const publicReferenceWithdrawInputSchema = z.object({
+    publicationRef: z.string().regex(/^public-reference:\/\/[a-f0-9]{64}$/),
+    reason: z.string().trim().min(1).max(2000),
+}).strict();
+export const publicReferencePublicationBasisSchema = z.object({
+    schemaVersion: z.union([z.literal(1), z.literal(2)]), visibility: z.literal('PUBLIC_REFERENCE'),
+    sourceProjectKey: projectKeySchema, corpusKey: projectKeySchema,
+    sourceReleaseId: sha256Schema, sourceReleaseRef: stableUriSchema,
+    recordsContentHash: sha256Schema, recordsByteLength: z.number().int().positive().max(512 * 1024 * 1024),
+    recordCount: z.number().int().positive().max(100_000),
+    recordTypes: z.array(projectKeySchema).min(1).max(128),
+    sourceCreatedAt: isoDateTimeSchema,
+    catalogue: publicReferenceCatalogueScopeSchema, review: publicReferenceReviewSchema,
+    publishedAt: isoDateTimeSchema, checkedAt: isoDateTimeSchema, validUntil: isoDateTimeSchema,
+}).strict();
+export const publicReferencePublicationSchema = publicReferencePublicationBasisSchema.extend({
+    publicationId: sha256Schema,
+    publicationRef: z.string().regex(/^public-reference:\/\/[a-f0-9]{64}$/),
+}).strict().superRefine((value, ctx) => {
+    if ((value.schemaVersion === 2) !== (value.review.authority === 'POLICY_ENGINE') || !value.review.approvedSources.length)
+        ctx.addIssue({ code: 'custom', message: 'Publication validation authority invalid' });
+    if (value.publicationRef !== 'public-reference://' + value.publicationId.slice(7))
+        ctx.addIssue({ code: 'custom', message: 'publication identity mismatch' });
+    if (Date.parse(value.validUntil) <= Date.parse(value.publishedAt) || Date.parse(value.checkedAt) > Date.parse(value.publishedAt)
+        || Date.parse(value.review.reviewedAt) > Date.parse(value.publishedAt) || Date.parse(value.review.reviewedAt) < Date.parse(value.sourceCreatedAt))
+        ctx.addIssue({ code: 'custom', message: 'publication chronology invalid' });
+});
+export const publicReferenceCatalogueQuerySchema = z.object({
+    countryCode: z.string().regex(/^[A-Z]{2}$/).optional(), topicKey: projectKeySchema.optional(),
+    after: sha256Schema.optional(), limit: z.number().int().min(1).max(100).default(20),
+}).strict();
+export function publicReferencePublicationBasis(value) {
+    const { publicationId: _id, publicationRef: _ref, ...basis } = value;
+    return publicReferencePublicationBasisSchema.parse(basis);
+}

package/dist/internal/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/internal/contracts/reference-record.js

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

package/dist/internal/contracts/remote-file.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>;