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

package/dist/internal/contracts/tenant-pdf-text.d.ts

@@ -0,0 +1,27 @@
+/** Bounded PDF text projection, with real page locators; OCR is a distinct capability. */
+import { z } from 'zod';
+export declare const TENANT_PDF_TEXT_MEDIA_TYPE = "application/vnd.native-knowledge.pdf-text+json";
+export declare const tenantPdfTextSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    format: z.ZodLiteral<"TENANT_PDF_TEXT_V1">;
+    tenantId: z.ZodString;
+    parentEvidenceRef: z.ZodString;
+    sourceContentHash: z.ZodString;
+    sourceByteLength: z.ZodNumber;
+    sourceMediaType: z.ZodString;
+    sourceUri: z.ZodString;
+    observedAt: z.ZodISODateTime;
+    extractedAt: z.ZodISODateTime;
+    extractor: z.ZodObject<{
+        id: z.ZodLiteral<"native-knowledge.pdf-text">;
+        version: z.ZodLiteral<"1.0.0">;
+    }, z.core.$strict>;
+    pages: z.ZodArray<z.ZodObject<{
+        page: z.ZodNumber;
+        locator: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+    gaps: z.ZodArray<z.ZodEnum<{
+        TENANT_PDF_OCR_REQUIRED: "TENANT_PDF_OCR_REQUIRED";
+    }>>;
+}, z.core.$strict>;

package/dist/internal/contracts/tenant-pdf-text.js

@@ -0,0 +1,13 @@
+/** Bounded PDF text projection, with real page locators; OCR is a distinct capability. */
+import { z } from 'zod';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { parseTenantResourceRef, tenantStorageKey } from './resource-scope.js';
+export const TENANT_PDF_TEXT_MEDIA_TYPE = 'application/vnd.native-knowledge.pdf-text+json';
+export const tenantPdfTextSchema = z.object({ schemaVersion: z.literal(1), format: z.literal('TENANT_PDF_TEXT_V1'), tenantId: materialTenantIdSchema, parentEvidenceRef: z.string().max(1024), sourceContentHash: sha256Schema, sourceByteLength: z.number().int().min(5).max(8 * 1024 * 1024), sourceMediaType: z.string().min(1).max(256), sourceUri: z.string().url().max(2048), observedAt: isoDateTimeSchema, extractedAt: isoDateTimeSchema, extractor: z.object({ id: z.literal('native-knowledge.pdf-text'), version: z.literal('1.0.0') }).strict(), pages: z.array(z.object({ page: z.number().int().min(1).max(100), locator: z.string().url().max(2080), text: z.string().max(64000) }).strict()).min(1).max(100), gaps: z.array(z.enum(['TENANT_PDF_OCR_REQUIRED'])).max(1) }).strict().superRefine((v, c) => {
+    const p = parseTenantResourceRef(v.parentEvidenceRef);
+    if (!p || p.storageKey !== tenantStorageKey(v.tenantId) || p.resourceType !== 'evidence')
+        c.addIssue({ code: 'custom', message: 'Exact Tenant PDF parent required' });
+    if (v.pages.some((p, i) => p.page !== i + 1 || p.locator !== v.sourceUri + '#page=' + p.page) || v.pages.reduce((n, p) => n + p.text.length, 0) > 2000000 || !v.pages.some(p => p.text.trim()) || v.pages.some(p => !p.text.trim()) !== v.gaps.includes('TENANT_PDF_OCR_REQUIRED'))
+        c.addIssue({ code: 'custom', message: 'Page identity, text budget or OCR gap mismatch' });
+});

package/dist/internal/contracts/tenant-project-control.d.ts

@@ -0,0 +1,94 @@
+/** Project controls select purpose/context; receipts do not own Tenant assets or lifecycle state. */
+import { z } from 'zod';
+import { tenantOperationRef } from './tenant-management.js';
+export declare const tenantProjectScopeChangeSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    projectKey: z.ZodString;
+    expectedRevision: z.ZodString;
+    changes: 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>;
+}, z.core.$strict>;
+export declare const tenantProjectLifecycleChangeSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    projectKey: z.ZodString;
+    expectedRevision: z.ZodString;
+    state: z.ZodEnum<{
+        ACTIVE: "ACTIVE";
+        ARCHIVED: "ARCHIVED";
+    }>;
+}, z.core.$strict>;
+export declare const tenantProjectControlResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"SCOPE">;
+    changed: z.ZodBoolean;
+    mode: z.ZodEnum<{
+        TENANT: "TENANT";
+        EXPLICIT: "EXPLICIT";
+    }>;
+    revision: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"LIFECYCLE">;
+    changed: z.ZodBoolean;
+    state: z.ZodEnum<{
+        ACTIVE: "ACTIVE";
+        ARCHIVED: "ARCHIVED";
+    }>;
+    revision: z.ZodString;
+}, z.core.$strict>], "type">;
+export declare const tenantProjectControlReceiptSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    operationRef: z.ZodString;
+    tenantId: z.ZodString;
+    projectKey: z.ZodString;
+    action: z.ZodEnum<{
+        SET_SCOPE: "SET_SCOPE";
+        SET_LIFECYCLE: "SET_LIFECYCLE";
+    }>;
+    inputHash: z.ZodString;
+    actor: z.ZodObject<{
+        tenantId: z.ZodString;
+        userId: z.ZodString;
+        agentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"HOST">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"OAUTH">;
+        authorityVersion: z.ZodLiteral<2>;
+        clientId: z.ZodString;
+        grantId: z.ZodString;
+        resource: z.ZodString;
+    }, z.core.$strict>], "type">;
+    result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"SCOPE">;
+        changed: z.ZodBoolean;
+        mode: z.ZodEnum<{
+            TENANT: "TENANT";
+            EXPLICIT: "EXPLICIT";
+        }>;
+        revision: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"LIFECYCLE">;
+        changed: z.ZodBoolean;
+        state: z.ZodEnum<{
+            ACTIVE: "ACTIVE";
+            ARCHIVED: "ARCHIVED";
+        }>;
+        revision: z.ZodString;
+    }, z.core.$strict>], "type">;
+    committedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type TenantProjectControlReceipt = z.infer<typeof tenantProjectControlReceiptSchema>;
+export type TenantProjectControlResult = z.infer<typeof tenantProjectControlResultSchema>;
+export { tenantOperationRef as tenantProjectOperationRef };

package/dist/internal/contracts/tenant-project-control.js

@@ -0,0 +1,19 @@
+/** Project controls select purpose/context; receipts do not own Tenant assets or lifecycle state. */
+import { z } from 'zod';
+import { sha256Schema, stableUriSchema, isoDateTimeSchema, projectKeySchema } from './common.js';
+import { materialTenantIdSchema, materialProjectScopeInputSchema } from './material-context.js';
+import { knowledgeActorContextSchema } from './project-intent.js';
+import { tenantManagementRequestIdSchema, tenantInvocationAuthoritySchema, tenantOperationRef } from './tenant-management.js';
+import { tenantStorageKey } from './resource-scope.js';
+export const tenantProjectScopeChangeSchema = z.object({ requestId: tenantManagementRequestIdSchema, projectKey: projectKeySchema, expectedRevision: sha256Schema, changes: materialProjectScopeInputSchema }).strict();
+export const tenantProjectLifecycleChangeSchema = z.object({ requestId: tenantManagementRequestIdSchema, projectKey: projectKeySchema, expectedRevision: sha256Schema, state: z.enum(['ACTIVE', 'ARCHIVED']) }).strict();
+export const tenantProjectControlResultSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('SCOPE'), changed: z.boolean(), mode: z.enum(['TENANT', 'EXPLICIT']), revision: sha256Schema }).strict(),
+    z.object({ type: z.literal('LIFECYCLE'), changed: z.boolean(), state: z.enum(['ACTIVE', 'ARCHIVED']), revision: sha256Schema }).strict(),
+]);
+export const tenantProjectControlReceiptSchema = z.object({ schemaVersion: z.literal(1), operationRef: stableUriSchema, tenantId: materialTenantIdSchema, projectKey: projectKeySchema, action: z.enum(['SET_SCOPE', 'SET_LIFECYCLE']), inputHash: sha256Schema, actor: knowledgeActorContextSchema, authority: tenantInvocationAuthoritySchema, result: tenantProjectControlResultSchema, committedAt: isoDateTimeSchema }).strict().superRefine((value, ctx) => {
+    const prefix = `tenant-operation://${tenantStorageKey(value.tenantId)}/`;
+    if (value.actor.tenantId !== value.tenantId || !value.operationRef.startsWith(prefix) || !/^[a-f0-9]{64}$/.test(value.operationRef.slice(prefix.length)) || value.action !== (value.result.type === 'SCOPE' ? 'SET_SCOPE' : 'SET_LIFECYCLE'))
+        ctx.addIssue({ code: 'custom', message: 'Project control receipt preserves exact Tenant, action and operation identity' });
+});
+export { tenantOperationRef as tenantProjectOperationRef };

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

@@ -0,0 +1,179 @@
+/** 原生公共 Reference 候选/receipt 格式3；不改旧 Project release 和 publication wire。 */
+import { z } from 'zod';
+export declare const TENANT_PUBLIC_REFERENCE_LIMITS: {
+    readonly records: 256;
+    readonly sources: 256;
+    readonly totalBytes: number;
+    readonly recordBytes: number;
+};
+export declare const tenantPublicReferenceRecordIdentitySchema: z.ZodObject<{
+    ref: z.ZodString;
+    digest: z.ZodString;
+    contentHash: z.ZodString;
+}, z.core.$strict>;
+export declare const tenantPublicReferenceReviewSchema: 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 tenantPublicReferencePublishInputSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<3>;
+    publicationKey: z.ZodString;
+    corpusKey: z.ZodString;
+    records: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>>;
+    catalogue: z.ZodObject<{
+        countryCode: z.ZodString;
+        topicKey: z.ZodString;
+        scopeRef: z.ZodString;
+        coverage: z.ZodEnum<{
+            PARTIAL: "PARTIAL";
+            OBSERVED: "OBSERVED";
+        }>;
+    }, z.core.$strict>;
+    review: 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.core.$strict>;
+export declare const tenantPublicReferencePublicationBasisSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<3>;
+    visibility: z.ZodLiteral<"PUBLIC_REFERENCE">;
+    source: z.ZodObject<{
+        type: z.ZodLiteral<"TENANT">;
+        tenantId: z.ZodString;
+    }, z.core.$strict>;
+    corpusKey: z.ZodString;
+    records: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>>;
+    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.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>;
+    publishedAt: z.ZodISODateTime;
+    checkedAt: z.ZodISODateTime;
+    validUntil: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare function tenantPublicReferencePublicationDigest(raw: z.infer<typeof tenantPublicReferencePublicationBasisSchema>): string;
+export declare const tenantPublicReferencePublicationSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<3>;
+    visibility: z.ZodLiteral<"PUBLIC_REFERENCE">;
+    source: z.ZodObject<{
+        type: z.ZodLiteral<"TENANT">;
+        tenantId: z.ZodString;
+    }, z.core.$strict>;
+    corpusKey: z.ZodString;
+    records: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>>;
+    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.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>;
+    publishedAt: z.ZodISODateTime;
+    checkedAt: z.ZodISODateTime;
+    validUntil: z.ZodISODateTime;
+    publicationId: z.ZodString;
+    publicationRef: z.ZodString;
+}, z.core.$strict>;
+export type TenantPublicReferencePublishInput = z.infer<typeof tenantPublicReferencePublishInputSchema>;
+export type TenantPublicReferencePublication = z.infer<typeof tenantPublicReferencePublicationSchema>;
+export declare const tenantPublicReferenceDirectorySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<3>;
+    contentClass: z.ZodLiteral<"PUBLIC_REFERENCE_DIRECTORY">;
+    coverageProof: z.ZodLiteral<false>;
+    items: z.ZodArray<z.ZodObject<{
+        publication: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<3>;
+            validUntil: z.ZodISODateTime;
+            publishedAt: z.ZodISODateTime;
+            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>;
+            recordsContentHash: z.ZodString;
+            sourceCreatedAt: z.ZodISODateTime;
+            checkedAt: z.ZodISODateTime;
+            visibility: z.ZodLiteral<"PUBLIC_REFERENCE">;
+            recordsByteLength: z.ZodNumber;
+            recordCount: z.ZodNumber;
+            source: z.ZodObject<{
+                type: z.ZodLiteral<"TENANT">;
+                tenantId: z.ZodString;
+            }, z.core.$strict>;
+            publicationId: z.ZodString;
+            publicationRef: z.ZodString;
+            reviewedAt: z.ZodISODateTime;
+        }, z.core.$strict>;
+        manifestRequired: z.ZodLiteral<true>;
+        availability: z.ZodEnum<{
+            STALE: "STALE";
+            NOT_YET_PUBLISHED: "NOT_YET_PUBLISHED";
+            AVAILABLE: "AVAILABLE";
+        }>;
+    }, z.core.$strict>>;
+    nextAfter: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type TenantPublicReferenceDirectory = z.infer<typeof tenantPublicReferenceDirectorySchema>;

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

@@ -0,0 +1,26 @@
+/** 原生公共 Reference 候选/receipt 格式3；不改旧 Project release 和 publication wire。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { projectKeySchema, sha256Schema, isoDateTimeSchema } from './common.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { tenantResourceRefSchema, parseTenantResourceRef, tenantStorageKey } from './resource-scope.js';
+import { publicReferenceCatalogueScopeSchema, publicReferenceLegacyReviewSchema } from './public-reference.js';
+export const TENANT_PUBLIC_REFERENCE_LIMITS = { records: 256, sources: 256, totalBytes: 16 * 1024 * 1024, recordBytes: 1024 * 1024 };
+export const tenantPublicReferenceRecordIdentitySchema = z.object({ ref: tenantResourceRefSchema, digest: sha256Schema, contentHash: sha256Schema }).strict();
+const records = z.array(tenantPublicReferenceRecordIdentitySchema).min(1).max(TENANT_PUBLIC_REFERENCE_LIMITS.records).superRefine((rows, ctx) => { if (new Set(rows.map(row => row.ref)).size !== rows.length || rows.some(row => parseTenantResourceRef(row.ref)?.resourceType !== 'reference'))
+    ctx.addIssue({ code: 'custom', message: 'Unique exact native Reference versions required' }); });
+export const tenantPublicReferenceReviewSchema = publicReferenceLegacyReviewSchema.safeExtend({ approvedSources: z.array(z.object({ sourceRef: tenantResourceRefSchema.refine(ref => parseTenantResourceRef(ref)?.resourceType === 'evidence'), contentHash: sha256Schema }).strict()).min(1).max(TENANT_PUBLIC_REFERENCE_LIMITS.sources) });
+export const tenantPublicReferencePublishInputSchema = z.object({ schemaVersion: z.literal(3), publicationKey: projectKeySchema, corpusKey: projectKeySchema, records, catalogue: publicReferenceCatalogueScopeSchema, review: tenantPublicReferenceReviewSchema }).strict();
+export const tenantPublicReferencePublicationBasisSchema = z.object({ schemaVersion: z.literal(3), visibility: z.literal('PUBLIC_REFERENCE'), source: z.object({ type: z.literal('TENANT'), tenantId: materialTenantIdSchema }).strict(), corpusKey: projectKeySchema, records, recordsContentHash: sha256Schema, recordsByteLength: z.number().int().positive().max(TENANT_PUBLIC_REFERENCE_LIMITS.totalBytes), recordCount: z.number().int().positive().max(TENANT_PUBLIC_REFERENCE_LIMITS.records), recordTypes: z.array(projectKeySchema).min(1).max(128), sourceCreatedAt: isoDateTimeSchema, catalogue: publicReferenceCatalogueScopeSchema, review: tenantPublicReferenceReviewSchema, publishedAt: isoDateTimeSchema, checkedAt: isoDateTimeSchema, validUntil: isoDateTimeSchema }).strict();
+export function tenantPublicReferencePublicationDigest(raw) { return 'sha256:' + createHash('sha256').update(JSON.stringify(tenantPublicReferencePublicationBasisSchema.parse(raw))).digest('hex'); }
+export const tenantPublicReferencePublicationSchema = tenantPublicReferencePublicationBasisSchema.extend({ publicationId: sha256Schema, publicationRef: z.string().regex(/^public-reference:\/\/[a-f0-9]{64}$/) }).strict().superRefine((v, ctx) => {
+    const { publicationId, publicationRef, ...basis } = v, key = tenantStorageKey(v.source.tenantId);
+    if (publicationId !== tenantPublicReferencePublicationDigest(basis) || publicationRef !== 'public-reference://' + publicationId.slice(7) || v.records.length !== v.recordCount || v.records.some(row => parseTenantResourceRef(row.ref)?.storageKey !== key))
+        ctx.addIssue({ code: 'custom', message: 'Tenant publication identity mismatch' });
+    if (v.records.some((row, index) => index > 0 && row.ref <= v.records[index - 1].ref) || new Set(v.recordTypes).size !== v.recordTypes.length || v.review.approvedSources.some(row => parseTenantResourceRef(row.sourceRef)?.storageKey !== key))
+        ctx.addIssue({ code: 'custom', message: 'Canonical publication records and same-Tenant sources required' });
+    if (Date.parse(v.validUntil) <= Date.parse(v.publishedAt) || Date.parse(v.checkedAt) > Date.parse(v.publishedAt) || Date.parse(v.review.reviewedAt) > Date.parse(v.publishedAt) || Date.parse(v.review.reviewedAt) < Math.max(Date.parse(v.sourceCreatedAt), Date.parse(v.checkedAt)))
+        ctx.addIssue({ code: 'custom', message: 'Tenant publication chronology invalid' });
+});
+const directoryPublication = z.object({ ...tenantPublicReferencePublicationBasisSchema.shape }).omit({ review: true, records: true }).extend({ publicationId: sha256Schema, publicationRef: tenantPublicReferencePublicationSchema.shape.publicationRef, reviewedAt: isoDateTimeSchema }).strict();
+export const tenantPublicReferenceDirectorySchema = z.object({ schemaVersion: z.literal(3), contentClass: z.literal('PUBLIC_REFERENCE_DIRECTORY'), coverageProof: z.literal(false), items: z.array(z.object({ publication: directoryPublication, manifestRequired: z.literal(true), availability: z.enum(['NOT_YET_PUBLISHED', 'AVAILABLE', 'STALE']) }).strict()).max(100), nextAfter: sha256Schema.nullable() }).strict();