@native-knowledge/knowledge-sdk 0.1.0-rc.1 → 0.1.0-rc.2

package/dist/internal/contracts/project-intent.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+const text = (max) => z.string().trim().min(1).max(max);
+const optionalText = (max) => z.string().trim().min(1).max(max).nullable().default(null);
+/**
+ * Attribution for an Agent-native Knowledge write. This is provenance, not an
+ * authorization decision. agentId is deliberately nullable because humans,
+ * schedulers and migrations may write without an Agent identity.
+ */
+export const knowledgeActorContextSchema = z.object({
+    tenantId: idSchema,
+    userId: idSchema,
+    agentId: idSchema.nullable().default(null),
+}).strict();
+export const projectIntentScopeSchema = z.object({
+    scopeId: idSchema,
+    title: text(256),
+    description: text(4000),
+    sourceRequirements: z.array(text(1000)).max(256).default([]),
+    sourceFamilies: z.array(idSchema).max(256).default([]),
+    notes: optionalText(4000),
+}).strict();
+export const projectIdentitySchema = z.object({
+    name: text(256),
+    summary: text(4000),
+    domains: z.array(text(256)).max(256).default([]),
+    notes: optionalText(4000),
+}).strict();
+export const projectIntentBasisSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    actor: knowledgeActorContextSchema,
+    projectIdentity: projectIdentitySchema,
+    scopes: z.array(projectIntentScopeSchema).max(1000).default([]),
+}).strict().superRefine((value, ctx) => {
+    const seen = new Set();
+    for (let i = 0; i < value.scopes.length; i += 1) {
+        const scopeId = value.scopes[i].scopeId;
+        if (seen.has(scopeId))
+            ctx.addIssue({ code: 'custom', path: ['scopes', i, 'scopeId'], message: 'scopeId must be unique' });
+        seen.add(scopeId);
+    }
+});
+export const projectIntentSnapshotSchema = projectIntentBasisSchema.extend({
+    projectRef: stableUriSchema,
+    revisionId: sha256Schema,
+    revisionRef: stableUriSchema,
+}).strict();
+export const projectIntentPointerSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    tenantId: idSchema,
+    projectRef: stableUriSchema,
+    revisionId: sha256Schema,
+    revisionRef: stableUriSchema,
+    manifestRelativePath: text(2048),
+    updatedAt: isoDateTimeSchema,
+}).strict();
+export const collectionRefreshSchema = z.discriminatedUnion('mode', [
+    z.object({ mode: z.literal('MANUAL') }).strict(),
+    z.object({ mode: z.literal('INTERVAL'), intervalSeconds: z.number().int().min(60).max(31_536_000) }).strict(),
+]);
+/** Project-neutral executable target. Project/domain semantics stay on ProjectSource. */
+const relativeTargetPathSchema = z.string().trim().min(1).max(2048).superRefine((value, ctx) => {
+    if (value.includes('\\') || value.startsWith('/') || value.endsWith('/')) {
+        ctx.addIssue({ code: 'custom', message: 'FILE target path must be a normalized relative file path' });
+        return;
+    }
+    const parts = value.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..'))
+        ctx.addIssue({ code: 'custom', message: 'FILE target path must not contain empty, dot or parent segments' });
+});
+const executorParameterScalarSchema = z.union([z.string().max(4000), z.number().finite(), z.boolean(), z.null()]);
+const executorParameterValueSchema = z.union([executorParameterScalarSchema, z.array(executorParameterScalarSchema).max(256)]);
+const urlAcquisitionTargetSchema = z.object({ kind: z.literal('URL'), locator: z.url() }).strict();
+const fileAcquisitionTargetSchema = z.object({ kind: z.literal('FILE'), rootBinding: projectKeySchema, relativePath: relativeTargetPathSchema }).strict();
+const executorAcquisitionTargetSchema = z.object({
+    kind: z.literal('EXECUTOR'), executorId: idSchema, bindingRef: stableUriSchema.nullable().default(null), parameters: z.record(z.string().trim().min(1).max(128), executorParameterValueSchema).default({}),
+}).strict().superRefine((value, ctx) => {
+    if (Object.keys(value.parameters).length > 128)
+        ctx.addIssue({ code: 'custom', path: ['parameters'], message: 'EXECUTOR target supports at most 128 parameters' });
+    if (Buffer.byteLength(JSON.stringify(value.parameters), 'utf8') > 32 * 1024)
+        ctx.addIssue({ code: 'custom', path: ['parameters'], message: 'EXECUTOR target parameters exceed 32 KiB' });
+});
+export const acquisitionTargetSchema = z.discriminatedUnion('kind', [urlAcquisitionTargetSchema, fileAcquisitionTargetSchema, executorAcquisitionTargetSchema]);
+const metadataScalarSchema = z.union([z.string().max(4000), z.number(), z.boolean(), z.null()]);
+export const projectSourceBasisSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    actor: knowledgeActorContextSchema,
+    target: acquisitionTargetSchema,
+    enabled: z.boolean().default(true),
+    access: accessClassificationSchema.default('PUBLIC'),
+    scopeIds: z.array(idSchema).max(256).default([]),
+    sourceFamilies: z.array(idSchema).max(256).default([]),
+    purpose: optionalText(4000),
+    refresh: collectionRefreshSchema.default({ mode: 'MANUAL' }),
+    metadata: z.record(z.string().trim().min(1).max(128), metadataScalarSchema).default({}),
+}).strict();
+export const projectSourceSnapshotSchema = projectSourceBasisSchema.extend({
+    projectRef: stableUriSchema,
+    projectIntentRef: stableUriSchema.nullable().default(null),
+    targetId: sha256Schema,
+    sourceId: idSchema,
+    revisionId: sha256Schema,
+    sourceRef: stableUriSchema,
+    revisionRef: stableUriSchema,
+}).strict();
+export const projectSourcePointerSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema,
+    projectIntentRef: stableUriSchema.nullable(),
+    sourceId: idSchema,
+    targetId: sha256Schema,
+    sourceRef: stableUriSchema,
+    revisionId: sha256Schema,
+    revisionRef: stableUriSchema,
+    manifestRelativePath: text(2048),
+    updatedAt: isoDateTimeSchema,
+}).strict();

package/dist/internal/contracts/projection.js

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import { artifactKindSchema, artifactStatusSchema } from './artifact.js';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema } from './common.js';
+export const driveRelativePathSchema = z.string().trim().min(1).max(2048).refine((value) => {
+    if (value.startsWith('/') || value.startsWith('\\'))
+        return false;
+    if (value.includes('\\'))
+        return false;
+    return !value.split('/').some((part) => !part || part === '.' || part === '..');
+}, 'Drive relative path must be normalized and traversal-free');
+export const driveArtifactProjectionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectionType: z.literal('GOOGLE_DRIVE'),
+    projectionId: sha256Schema,
+    relativePath: driveRelativePathSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    artifactRef: stableUriSchema,
+    identityRef: stableUriSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    artifactKind: artifactKindSchema,
+    artifactStatus: artifactStatusSchema,
+    artifactVersion: z.number().int().positive(),
+}).strict().superRefine((value, ctx) => {
+    if (!value.relativePath.startsWith(`Knowledge V2/${value.projectKey}/`))
+        ctx.addIssue({ code: 'custom', path: ['relativePath'], message: 'Drive path project must match projectKey' });
+    if (value.projectRef) {
+        try {
+            const project = new URL(value.projectRef);
+            if (project.protocol !== 'knowledge-project:' || project.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'projectRef project must match projectKey' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'Invalid projectRef' });
+        }
+    }
+    try {
+        const artifact = new URL(value.artifactRef);
+        const identity = new URL(value.identityRef);
+        if (artifact.hostname.toLowerCase() !== value.projectKey.toLowerCase() || identity.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+            ctx.addIssue({ code: 'custom', path: ['artifactRef'], message: 'Artifact refs must match projectKey' });
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', path: ['artifactRef'], message: 'Artifact refs must be valid stable URLs' });
+    }
+});
+export const driveReviewPlaneProjectionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectionType: z.literal('GOOGLE_DRIVE_REVIEW'),
+    projectionId: sha256Schema,
+    relativePath: driveRelativePathSchema,
+    workspaceRoot: driveRelativePathSchema,
+    reviewStage: z.enum(['PROGRAM', 'INBOX', 'REVIEWED', 'USER_APPROVED', 'PROMOTION_RECEIPTS', 'GUIDES', 'REJECTED_SUPERSEDED']),
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    artifactRef: stableUriSchema,
+    identityRef: stableUriSchema,
+    contentHash: sha256Schema,
+    mediaType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    artifactKind: artifactKindSchema,
+    artifactStatus: artifactStatusSchema,
+    artifactVersion: z.number().int().positive(),
+}).strict().superRefine((value, ctx) => {
+    if (!value.relativePath.startsWith(`${value.workspaceRoot}/`))
+        ctx.addIssue({ code: 'custom', path: ['relativePath'], message: 'Review projection path must stay under workspaceRoot' });
+    if (value.projectRef) {
+        try {
+            const project = new URL(value.projectRef);
+            if (project.protocol !== 'knowledge-project:' || project.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'projectRef project must match projectKey' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'Invalid projectRef' });
+        }
+    }
+    try {
+        const artifact = new URL(value.artifactRef);
+        const identity = new URL(value.identityRef);
+        if (artifact.hostname.toLowerCase() !== value.projectKey.toLowerCase() || identity.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+            ctx.addIssue({ code: 'custom', path: ['artifactRef'], message: 'Artifact refs must match projectKey' });
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', path: ['artifactRef'], message: 'Artifact refs must be valid stable URLs' });
+    }
+});
+export const driveUploadProjectionSchema = z.union([driveArtifactProjectionSchema, driveReviewPlaneProjectionSchema]);
+export const driveProviderIdSchema = z.string().trim().regex(/^[A-Za-z0-9_-]{10,512}$/);
+export const driveProviderDeliverySchema = z.object({
+    provider: z.literal('GOOGLE_DRIVE'),
+    fileId: driveProviderIdSchema,
+    mimeType: z.string().trim().min(1).max(256),
+    byteLength: z.number().int().nonnegative(),
+    md5Checksum: z.string().regex(/^[a-f0-9]{32}$/),
+    version: z.string().trim().min(1).max(128).nullable(),
+    modifiedTime: isoDateTimeSchema.nullable(),
+}).strict();
+export const driveDeliveryReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectionId: sha256Schema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    artifactRef: stableUriSchema,
+    contentHash: sha256Schema,
+    relativePath: driveRelativePathSchema,
+    deliveredAt: isoDateTimeSchema,
+    provider: driveProviderDeliverySchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.projectRef) {
+        try {
+            const project = new URL(value.projectRef);
+            if (project.protocol !== 'knowledge-project:' || project.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'projectRef project must match projectKey' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'Invalid projectRef' });
+        }
+    }
+});
+export const driveUploadFolderBindingSchema = z.object({
+    relativePath: driveRelativePathSchema,
+    name: z.string().trim().min(1).max(255),
+    parentFileId: driveProviderIdSchema,
+    fileId: driveProviderIdSchema,
+    disposition: z.enum(['EXISTING', 'RESERVED']),
+}).strict();
+export const driveUploadFileBindingSchema = z.object({
+    name: z.string().trim().min(1).max(255),
+    parentFileId: driveProviderIdSchema,
+    fileId: driveProviderIdSchema,
+    disposition: z.enum(['EXISTING', 'RESERVED']),
+}).strict();
+export const driveUploadIntentSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectionId: sha256Schema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    artifactRef: stableUriSchema,
+    contentHash: sha256Schema,
+    relativePath: driveRelativePathSchema,
+    rootParentFolderId: driveProviderIdSchema,
+    sharedDriveId: driveProviderIdSchema.nullable(),
+    reservedAt: isoDateTimeSchema,
+    folders: z.array(driveUploadFolderBindingSchema).max(32),
+    file: driveUploadFileBindingSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.projectRef) {
+        try {
+            const project = new URL(value.projectRef);
+            if (project.protocol !== 'knowledge-project:' || project.hostname.toLowerCase() !== value.projectKey.toLowerCase())
+                ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'projectRef project must match projectKey' });
+        }
+        catch {
+            ctx.addIssue({ code: 'custom', path: ['projectRef'], message: 'Invalid projectRef' });
+        }
+    }
+});
+export const driveProjectionOutboxEntrySchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    deliveryId: sha256Schema,
+    state: z.enum(['PENDING', 'DELIVERED', 'BLOCKED', 'FAILED_RETRYABLE', 'FAILED_TERMINAL']),
+    projection: driveUploadProjectionSchema,
+    outboxDirectory: z.string().trim().min(1).max(4096).startsWith('/'),
+    descriptorPath: z.string().trim().min(1).max(4096).startsWith('/'),
+    payloadPath: z.string().trim().min(1).max(4096).startsWith('/'),
+    uploadIntentPath: z.string().trim().min(1).max(4096).startsWith('/').nullable(),
+    uploadIntent: driveUploadIntentSchema.nullable(),
+    deliveryPath: z.string().trim().min(1).max(4096).startsWith('/').nullable(),
+    delivery: driveDeliveryReceiptSchema.nullable(),
+}).strict().superRefine((value, ctx) => {
+    if ((value.uploadIntentPath === null) !== (value.uploadIntent === null))
+        ctx.addIssue({ code: 'custom', path: ['uploadIntent'], message: 'upload intent path/value must appear together' });
+    if (value.state !== 'DELIVERED' && (value.deliveryPath !== null || value.delivery !== null))
+        ctx.addIssue({ code: 'custom', path: ['delivery'], message: 'Only DELIVERED entry may carry Drive provider delivery' });
+    if (value.state === 'DELIVERED' && (value.deliveryPath === null || value.delivery === null))
+        ctx.addIssue({ code: 'custom', path: ['delivery'], message: 'DELIVERED entry requires delivery' });
+});
+export const driveProjectionStagingReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    deliveryId: sha256Schema,
+    projectionId: sha256Schema,
+    projectRef: stableUriSchema.optional(),
+    artifactRef: stableUriSchema,
+    contentHash: sha256Schema,
+    relativePath: driveRelativePathSchema,
+    runtimeNodeId: idSchema,
+    stagedAt: isoDateTimeSchema,
+    outboxDirectory: z.string().trim().min(1).max(4096).startsWith('/'),
+    descriptorPath: z.string().trim().min(1).max(4096).startsWith('/'),
+    payloadPath: z.string().trim().min(1).max(4096).startsWith('/'),
+    reused: z.boolean(),
+}).strict();

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