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

package/dist/internal/contracts/scheduler.js

@@ -0,0 +1,256 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema } from './common.js';
+import { signalProfileNameSchema } from './signal.js';
+import { runtimeCapabilitySchema } from './runtime.js';
+export const TIPP_UNIVERSE_MAX_RESOURCE_BYTES = 8 * 1024 * 1024;
+const deploymentPathSchema = z.string().trim().min(1).max(4096).refine((value) => !value.includes('\0'), 'path must not contain NUL');
+const scheduledWorkloadBaseSchema = z.object({
+    workloadId: idSchema,
+    projectKey: projectKeySchema,
+    priority: z.number().int().min(0).max(1000),
+    intervalSeconds: z.number().int().min(60).max(7 * 24 * 60 * 60),
+    timeoutSeconds: z.number().int().min(30).max(2 * 60 * 60).default(15 * 60),
+    assignmentFile: deploymentPathSchema,
+    initialDueAt: isoDateTimeSchema.optional(),
+}).strict();
+const acquisitionInvocationSchema = z.object({
+    command: z.literal('acquisition-run'),
+    programDirectory: deploymentPathSchema,
+    fileRootsFile: deploymentPathSchema.optional(),
+}).strict();
+const reviewPacketInvocationSchema = z.object({
+    command: z.literal('review-packet-project'),
+}).strict();
+// 自动发布只消费已持久化的事件和 Agent 输入，不触发任何来源采集。
+const autoPublicationInvocationSchema = z.object({
+    command: z.literal('auto-publication-tick'),
+    // 同项目发布并发有固定上限；旧 manifest 无此字段时采用 Runner 默认值。
+    concurrency: z.number().int().min(1).max(4).optional(),
+}).strict();
+const publicReferenceInvocationSchema = z.object({ command: z.literal('public-reference-tick'), policyFile: deploymentPathSchema, identityDatabase: deploymentPathSchema }).strict();
+const feedProjectInvocationSchema = z.object({
+    command: z.literal('feed-project'),
+}).strict();
+const procurementProjectInvocationSchema = z.object({
+    command: z.literal('procurement-project'),
+}).strict();
+const pkValuationStatusProjectInvocationSchema = z.object({
+    command: z.literal('pk-valuation-status-project'),
+}).strict();
+const pkStandardsProjectInvocationSchema = z.object({
+    command: z.literal('pk-standards-project'),
+}).strict();
+const cpecProjectInvocationSchema = z.object({
+    command: z.literal('cpec-project'),
+}).strict();
+const tippUniverseProjectInvocationSchema = z.object({
+    command: z.literal('tipp-universe-project'),
+    chapterBatch: z.number().int().min(1).max(96).default(4),
+    maxResourceBytes: z.number().int().min(64 * 1024).max(16 * 1024 * 1024).default(TIPP_UNIVERSE_MAX_RESOURCE_BYTES),
+}).strict();
+const tippDetailProjectInvocationSchema = z.object({
+    command: z.literal('tipp-detail-project'),
+    detailBatch: z.number().int().min(1).max(1000).default(50),
+    detailConcurrency: z.number().int().min(1).max(4).optional(),
+    maxResourceBytes: z.number().int().min(64 * 1024).max(16 * 1024 * 1024).default(4 * 1024 * 1024),
+}).strict();
+const tippTariffProjectInvocationSchema = z.object({
+    command: z.literal('tipp-tariff-project'),
+}).strict();
+const tippRegulatoryProjectInvocationSchema = z.object({
+    command: z.literal('tipp-regulatory-project'),
+}).strict();
+const pkTariffReconciliationProjectInvocationSchema = z.object({
+    command: z.literal('pk-tariff-reconciliation-project'),
+}).strict();
+const collectionInvocationSchema = z.object({
+    command: z.literal('collection-tick'),
+    maxResourceBytes: z.number().int().min(1024).max(64 * 1024 * 1024).default(16 * 1024 * 1024),
+    batchLimit: z.number().int().min(1).max(10_000).default(100),
+    fileRootsFile: deploymentPathSchema.optional(),
+}).strict();
+const collectionProjectionInvocationSchema = z.object({ command: z.literal('collection-projection-tick'), limit: z.number().int().min(1).max(100).default(25) }).strict();
+const signalCollectInvocationSchema = z.object({
+    command: z.literal('signal-collect'),
+    programFile: deploymentPathSchema,
+    profile: signalProfileNameSchema,
+}).strict();
+const signalComposeInvocationSchema = z.object({
+    command: z.literal('signal-compose'),
+    programFile: deploymentPathSchema,
+}).strict();
+const customsCorpusInvocationSchema = z.object({
+    command: z.literal('customs-corpus-run'),
+    programFile: deploymentPathSchema,
+    adapter: z.enum(['us-hts', 'us-cross', 'ca-tariff', 'ca-rulings', 'eu-ebti', 'pk-tariff', 'pk-import-sro', 'pk-tax-authorities', 'pk-classification', 'pk-valuation', 'za-determinations', 'eg-nafeza', 'ae-tariff', 'sa-tariff', 'ru-eaeu']),
+    refreshStoredDocuments: z.boolean().optional(),
+    // GCC 重新访问官方来源必须显式启用，历史文件导入不触发网络。
+    refreshRemoteBundle: z.boolean().optional(),
+}).strict();
+const locationCorpusInvocationSchema = z.object({
+    command: z.literal('location-corpus-run'),
+    programFile: deploymentPathSchema,
+    adapter: z.literal('unlocode'),
+}).strict();
+export const schedulerInvocationSchema = z.discriminatedUnion('command', [
+    z.object({ command: z.literal('business-information-collect'), maxSources: z.number().int().min(1).max(32).default(8), maxResourceBytes: z.number().int().min(1024).max(16 * 1024 * 1024).default(2 * 1024 * 1024), fileRootsFile: deploymentPathSchema.optional() }).strict(),
+    z.object({ command: z.literal('pk-import-rules-project'), acquireLinkedDocuments: z.boolean().default(false), documentBatch: z.number().int().min(1).max(50).default(20), maxDocumentBytes: z.number().int().min(1024).max(32 * 1024 * 1024).default(16 * 1024 * 1024) }).strict(),
+    acquisitionInvocationSchema,
+    collectionInvocationSchema,
+    collectionProjectionInvocationSchema,
+    z.object({ command: z.literal('project-projection-tick'),
+        maxRows: z.number().int().min(1).max(100).optional(),
+        maxDependencyRows: z.number().int().min(1).max(10000).optional(),
+        maxBytes: z.number().int().min(1).max(16 * 1024 ** 3).optional(),
+        maxMs: z.number().int().min(1).max(600000).optional(),
+    }).strict(),
+    reviewPacketInvocationSchema,
+    autoPublicationInvocationSchema,
+    publicReferenceInvocationSchema,
+    feedProjectInvocationSchema,
+    procurementProjectInvocationSchema,
+    pkValuationStatusProjectInvocationSchema,
+    pkStandardsProjectInvocationSchema,
+    cpecProjectInvocationSchema,
+    tippUniverseProjectInvocationSchema,
+    tippDetailProjectInvocationSchema,
+    tippTariffProjectInvocationSchema,
+    tippRegulatoryProjectInvocationSchema,
+    pkTariffReconciliationProjectInvocationSchema,
+    signalCollectInvocationSchema,
+    signalComposeInvocationSchema,
+    customsCorpusInvocationSchema,
+    locationCorpusInvocationSchema,
+]);
+export const scheduledWorkloadSchema = scheduledWorkloadBaseSchema.extend({
+    invocation: schedulerInvocationSchema,
+}).strict().superRefine((value, ctx) => {
+    let expected;
+    switch (value.invocation.command) {
+        case 'acquisition-run':
+            expected = `project:${value.projectKey}:acquisition`;
+            break;
+        case 'collection-projection-tick':
+            expected = `project:${value.projectKey}:material-projection`;
+            break;
+        case 'project-projection-tick':
+            expected = `project:${value.projectKey}:catalog-projection`;
+            break;
+        case 'collection-tick':
+            expected = `project:${value.projectKey}:collection`;
+            break;
+        case 'review-packet-project':
+            expected = `project:${value.projectKey}:review-packets`;
+            break;
+        case 'auto-publication-tick':
+            expected = `project:${value.projectKey}:auto-publication`;
+            break;
+        case 'public-reference-tick':
+            expected = `project:${value.projectKey}:public-reference-publication`;
+            break;
+        case 'feed-project':
+            expected = `project:${value.projectKey}:feed-project`;
+            break;
+        case 'procurement-project':
+            expected = `project:${value.projectKey}:procurement-project`;
+            break;
+        case 'pk-valuation-status-project':
+            expected = `project:${value.projectKey}:pk-valuation-status-project`;
+            break;
+        case 'pk-standards-project':
+            expected = `project:${value.projectKey}:pk-standards-project`;
+            break;
+        case 'pk-import-rules-project':
+            expected = `project:${value.projectKey}:pk-import-rules-project`;
+            break;
+        case 'cpec-project':
+            expected = `project:${value.projectKey}:cpec-project`;
+            break;
+        case 'business-information-collect':
+            expected = `project:${value.projectKey}:business-information-collect`;
+            break;
+        case 'tipp-universe-project':
+            expected = `project:${value.projectKey}:tipp-universe-project`;
+            break;
+        case 'tipp-detail-project':
+            expected = `project:${value.projectKey}:tipp-detail-project`;
+            break;
+        case 'tipp-tariff-project':
+            expected = `project:${value.projectKey}:tipp-tariff-project`;
+            break;
+        case 'tipp-regulatory-project':
+            expected = `project:${value.projectKey}:tipp-regulatory-project`;
+            break;
+        case 'pk-tariff-reconciliation-project':
+            expected = `project:${value.projectKey}:pk-tariff-reconciliation-project`;
+            break;
+        case 'signal-collect':
+            expected = `project:${value.projectKey}:signal:${value.invocation.profile}`;
+            break;
+        case 'signal-compose':
+            expected = `project:${value.projectKey}:signal:compose`;
+            break;
+        case 'customs-corpus-run':
+            expected = `project:${value.projectKey}:customs:${value.invocation.adapter}`;
+            break;
+        case 'location-corpus-run':
+            expected = `project:${value.projectKey}:locations:${value.invocation.adapter}`;
+            break;
+    }
+    if (value.workloadId !== expected) {
+        ctx.addIssue({ code: 'custom', path: ['workloadId'], message: `workloadId must be ${expected}` });
+    }
+});
+export const nodeSchedulerManifestSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    nodeId: idSchema,
+    capabilities: z.array(runtimeCapabilitySchema).max(128).default(['network:http']),
+    maxWorkloadsPerTick: z.number().int().min(1).max(32).default(8),
+    workloads: z.array(scheduledWorkloadSchema).max(256),
+}).strict().superRefine((value, ctx) => {
+    const seen = new Set();
+    const capabilities = new Set(value.capabilities);
+    value.workloads.forEach((workload, index) => {
+        if (seen.has(workload.workloadId))
+            ctx.addIssue({ code: 'custom', path: ['workloads', index, 'workloadId'], message: 'duplicate workloadId' });
+        seen.add(workload.workloadId);
+        if (workload.invocation.command === 'business-information-collect' && !capabilities.has('network:http'))
+            ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation'], message: 'public business collection requires network:http capability' });
+        if ((workload.invocation.command === 'collection-tick' || workload.invocation.command === 'collection-projection-tick') && !capabilities.has('network:http')) {
+            ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation'], message: 'collection tick requires network:http capability' });
+        }
+        if (workload.invocation.command === 'signal-collect') {
+            if (!capabilities.has('network:http')) {
+                ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation'], message: 'signal collection requires network:http capability' });
+            }
+            if (['tiktok', 'douyin', 'meta', 'deep-social'].includes(workload.invocation.profile) && !capabilities.has('browser:playwright')) {
+                ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation'], message: `profile ${workload.invocation.profile} requires browser:playwright capability` });
+            }
+        }
+        if (workload.invocation.command === 'location-corpus-run' && !capabilities.has('network:http')) {
+            ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation'], message: 'reference corpus collection requires network:http capability' });
+        }
+        if (workload.invocation.command === 'tipp-universe-project' && !capabilities.has('network:http')) {
+            ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation'], message: 'TIPP universe collection requires network:http capability' });
+        }
+        if (workload.invocation.command === 'tipp-detail-project' && !capabilities.has('network:http')) {
+            ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation'], message: 'TIPP detail collection requires network:http capability' });
+        }
+        if (workload.invocation.command === 'customs-corpus-run') {
+            if (workload.invocation.refreshRemoteBundle) {
+                if (!['ae-tariff', 'sa-tariff'].includes(workload.invocation.adapter))
+                    ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation', 'refreshRemoteBundle'], message: 'GCC refresh requires ae-tariff or sa-tariff adapter' });
+                if (!capabilities.has('network:http'))
+                    ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation'], message: 'GCC refresh requires network:http capability' });
+            }
+            if (workload.invocation.refreshStoredDocuments && !['pk-import-sro', 'ru-eaeu'].includes(workload.invocation.adapter)) {
+                ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation', 'refreshStoredDocuments'], message: 'stored document refresh requires pk-import-sro or ru-eaeu adapter' });
+            }
+            const localVerifiedBundleAdapter = ['pk-valuation', 'za-determinations', 'ae-tariff', 'sa-tariff'].includes(workload.invocation.adapter);
+            if (!localVerifiedBundleAdapter && !capabilities.has('network:http')) {
+                ctx.addIssue({ code: 'custom', path: ['workloads', index, 'invocation'], message: `customs adapter ${workload.invocation.adapter} requires network:http capability` });
+            }
+        }
+    });
+});
+export const scheduledWorkerCommands = schedulerInvocationSchema.options.map(option => option.shape.command.value);

package/dist/internal/contracts/signal.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from './common.js';
+export const signalProfileNameSchema = z.enum([
+    'trends',
+    'hn',
+    'github',
+    'autocomplete',
+    'youtube',
+    'tiktok',
+    'douyin',
+    'meta',
+    'deep-social',
+]);
+export const signalSourceHealthSchema = z.object({
+    ok: z.boolean(),
+    items: z.number().int().nonnegative().optional(),
+    state: z.string().trim().min(1).max(128).optional(),
+    note: z.string().trim().max(2000).optional(),
+    error: z.string().trim().max(2000).optional(),
+}).catchall(z.unknown());
+export const signalSourceSnapshotSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    sourceRef: stableUriSchema.optional(),
+    sourceRevisionRef: stableUriSchema.optional(),
+    sourceKey: idSchema,
+    profile: signalProfileNameSchema,
+    collectedAt: isoDateTimeSchema,
+    contentHash: sha256Schema,
+    evidenceId: idSchema,
+    signalCount: z.number().int().nonnegative(),
+    health: signalSourceHealthSchema,
+}).strict();
+export const signalSourceAttemptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    sourceRef: stableUriSchema.optional(),
+    sourceRevisionRef: stableUriSchema.optional(),
+    sourceKey: idSchema,
+    profile: signalProfileNameSchema,
+    lastAttemptAt: isoDateTimeSchema,
+    lastSuccessAt: isoDateTimeSchema.nullable(),
+    success: z.boolean(),
+    durationMs: z.number().int().nonnegative(),
+    state: z.string().trim().min(1).max(128).nullable(),
+    error: z.string().trim().max(2000).nullable(),
+}).strict();
+export const signalGenerationSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    generationKey: sha256Schema,
+    scoringProfile: z.string().trim().min(1).max(128),
+    generatedAt: isoDateTimeSchema,
+    snapshotManifest: z.record(idSchema, sha256Schema),
+    historyBasis: z.array(sha256Schema).max(512).default([]),
+    contentHash: sha256Schema,
+    candidateCount: z.number().int().nonnegative(),
+    observationCount: z.number().int().nonnegative(),
+}).strict();
+export const signalHistoryCandidateSchema = z.object({
+    query: z.string().trim().min(1).max(1000),
+    score: z.number().finite(),
+    sources: z.array(idSchema).max(64),
+}).strict();
+export const signalHistorySeedSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    projectRef: stableUriSchema.optional(),
+    historyKey: sha256Schema,
+    generatedAt: isoDateTimeSchema,
+    scoringVersion: z.number().int().positive(),
+    origin: z.string().trim().min(1).max(128),
+    candidates: z.array(signalHistoryCandidateSchema).max(120),
+}).strict();

package/dist/internal/contracts/source-governance.js

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, stableUriSchema, } from './common.js';
+export const sourceExpectationSchema = z.enum(['REQUIRED', 'OPTIONAL', 'CONDITIONAL']);
+export const sourceDeclaredStateSchema = z.enum([
+    'CONFIGURED',
+    'PENDING_DISCOVERY',
+    'KNOWN_MISSING',
+    'ACCESS_CONTROLLED',
+    'NEED_AUTHORIZED_SOURCE',
+    'DEFERRED',
+    'RETIRED',
+]);
+export const sourceCoverageStateSchema = z.enum([
+    'ACQUIRED',
+    'CONFIGURED_UNOBSERVED',
+    'PARTIAL',
+    'BLOCKED',
+    'ACCESS_CONTROLLED',
+    'PENDING_DISCOVERY',
+    'KNOWN_MISSING',
+    'NEED_AUTHORIZED_SOURCE',
+    'DEFERRED',
+    'RETIRED',
+]);
+const shortText = z.string().trim().min(1).max(512);
+const roleSchema = z.string().trim().min(1).max(256);
+export const sourceDiscoveryPolicySchema = z.object({
+    hostMode: z.enum(['ALLOWLIST', 'EVIDENCE_OBSERVED']).default('ALLOWLIST'),
+    allowedHosts: z.array(z.string().trim().toLowerCase().min(1).max(253)).max(256).default([]),
+    forbiddenHostSuffixes: z.array(z.string().trim().toLowerCase().min(1).max(253)).max(256).default([]),
+    allowedPathPrefixes: z.array(z.string().trim().startsWith('/').max(2048)).min(1).max(128),
+}).strict().superRefine((value, ctx) => {
+    if (value.hostMode === 'ALLOWLIST' && !value.allowedHosts.length)
+        ctx.addIssue({ code: 'custom', path: ['allowedHosts'], message: 'ALLOWLIST discovery requires at least one allowed host' });
+    const allowed = new Set(value.allowedHosts);
+    for (const suffix of value.forbiddenHostSuffixes)
+        if (allowed.has(suffix))
+            ctx.addIssue({ code: 'custom', path: ['forbiddenHostSuffixes'], message: `Host cannot be both allowed and forbidden: ${suffix}` });
+});
+export const sourceUniverseEntrySchema = z.object({
+    sourceId: idSchema,
+    familyId: idSchema,
+    acquisitionSourceIds: z.array(idSchema).max(64).default([]),
+    expectation: sourceExpectationSchema,
+    authority: shortText,
+    access: accessClassificationSchema,
+    freshness: shortText,
+    semanticRoles: z.array(roleSchema).max(64).default([]),
+    locator: stableUriSchema.nullable().default(null),
+    declaredState: sourceDeclaredStateSchema,
+    expectedOwner: shortText.nullable().default(null),
+    requiredFor: z.array(idSchema).max(128).default([]),
+    discoveryPolicy: sourceDiscoveryPolicySchema.nullable().default(null),
+    notes: z.string().trim().max(2000).nullable().default(null),
+}).strict().superRefine((value, ctx) => {
+    if (value.declaredState === 'CONFIGURED' && value.locator === null) {
+        ctx.addIssue({ code: 'custom', path: ['locator'], message: 'CONFIGURED source requires locator' });
+    }
+    if (['PENDING_DISCOVERY', 'KNOWN_MISSING', 'ACCESS_CONTROLLED', 'NEED_AUTHORIZED_SOURCE'].includes(value.declaredState) && value.expectation === 'OPTIONAL' && !value.requiredFor.length) {
+        ctx.addIssue({ code: 'custom', path: ['requiredFor'], message: 'unresolved optional source must declare why it is tracked' });
+    }
+});
+export const sourceUniverseSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    asOf: isoDateTimeSchema,
+    sources: z.array(sourceUniverseEntrySchema).min(1).max(5000),
+}).strict().superRefine((value, ctx) => {
+    const ids = new Set();
+    for (let i = 0; i < value.sources.length; i += 1) {
+        const id = value.sources[i].sourceId;
+        if (ids.has(id))
+            ctx.addIssue({ code: 'custom', path: ['sources', i, 'sourceId'], message: 'sourceId must be unique' });
+        ids.add(id);
+    }
+});
+export const sourceCoverageEntrySchema = z.object({
+    sourceId: idSchema,
+    familyId: idSchema,
+    expectation: sourceExpectationSchema,
+    declaredState: sourceDeclaredStateSchema,
+    coverageState: sourceCoverageStateSchema,
+    configuredItemCount: z.number().int().nonnegative(),
+    observedItemCount: z.number().int().nonnegative(),
+    acquiredItemCount: z.number().int().nonnegative(),
+    blockedItemCount: z.number().int().nonnegative(),
+    accessControlledItemCount: z.number().int().nonnegative(),
+    evidenceRefs: z.array(stableUriSchema).max(2048),
+    blockers: z.array(shortText).max(256),
+}).strict();
+export const sourceCoverageAssessmentSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    assessedAt: isoDateTimeSchema,
+    complete: z.boolean(),
+    requiredSourceCount: z.number().int().nonnegative(),
+    coveredRequiredSourceCount: z.number().int().nonnegative(),
+    entries: z.array(sourceCoverageEntrySchema).max(5000),
+    blockers: z.array(shortText).max(1000),
+}).strict();
+export const sourceGapStateSchema = z.enum([
+    'PENDING_DISCOVERY',
+    'KNOWN_MISSING',
+    'ACCESS_CONTROLLED',
+    'NEED_AUTHORIZED_SOURCE',
+    'DEFERRED',
+]);
+export const sourceGapSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    gapId: idSchema,
+    projectKey: projectKeySchema,
+    sourceId: idSchema,
+    familyId: idSchema,
+    state: sourceGapStateSchema,
+    access: accessClassificationSchema,
+    expectedOwner: shortText.nullable(),
+    reason: z.string().trim().min(1).max(2000),
+    requiredFor: z.array(idSchema).max(128),
+    evidenceRefs: z.array(stableUriSchema).max(256),
+    recordedAt: isoDateTimeSchema,
+}).strict();
+const discoveryLinkIdSchema = z.string().trim().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+const discoveredLinkSchema = z.object({
+    linkId: discoveryLinkIdSchema,
+    url: z.url(),
+    locator: z.string().trim().min(1).max(2048),
+    parentEvidenceRef: stableUriSchema,
+    title: z.string().trim().min(1).max(500).optional(),
+}).strict();
+export const sourceDiscoveryProposalSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    proposalId: idSchema,
+    familyId: idSchema,
+    createdAt: isoDateTimeSchema,
+    observedLinks: z.array(discoveredLinkSchema).min(1).max(1000),
+    selectedLinkIds: z.array(discoveryLinkIdSchema).max(1000),
+    completeness: z.object({
+        claim: z.enum(['COMPLETE', 'INCOMPLETE']),
+        missing: z.array(z.string().trim().min(1).max(500)).max(1000),
+        notes: z.string().trim().max(4000).nullable().default(null),
+    }).strict(),
+}).strict();
+export const sourceDiscoveryValidationSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    proposalId: idSchema,
+    familyId: idSchema,
+    proposalHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    valid: z.boolean(),
+    selectedSources: z.array(z.object({ linkId: idSchema, url: z.url(), parentEvidenceRef: stableUriSchema }).strict()).max(1000),
+    completeness: z.object({ claim: z.enum(['COMPLETE', 'INCOMPLETE']), missing: z.array(z.string()).max(1000), notes: z.string().nullable() }).strict(),
+    evidenceRefs: z.array(stableUriSchema).max(1000),
+    errors: z.array(shortText).max(1000),
+    warnings: z.array(shortText).max(1000),
+}).strict();
+export const sourceDiscoveryReceiptSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    proposalId: idSchema,
+    familyId: idSchema,
+    proposalHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    state: z.enum(['COMPLETE', 'REVIEWED_PARTIAL']),
+    proposalRef: stableUriSchema,
+    reviewRef: stableUriSchema,
+    reviewedAt: isoDateTimeSchema,
+    selectedSources: z.array(z.object({ linkId: idSchema, url: z.url(), parentEvidenceRef: stableUriSchema }).strict()).max(1000),
+    completeness: z.object({ claim: z.enum(['COMPLETE', 'INCOMPLETE']), missing: z.array(z.string()).max(1000), notes: z.string().nullable() }).strict(),
+    evidenceRefs: z.array(stableUriSchema).max(1000),
+    configMutationPerformed: z.literal(false),
+}).strict().superRefine((value, ctx) => {
+    if (value.state === 'COMPLETE' && (value.completeness.claim !== 'COMPLETE' || value.completeness.missing.length))
+        ctx.addIssue({ code: 'custom', path: ['state'], message: 'COMPLETE receipt requires complete proposal without missing sources' });
+    if (value.state === 'REVIEWED_PARTIAL' && value.completeness.claim !== 'INCOMPLETE')
+        ctx.addIssue({ code: 'custom', path: ['state'], message: 'REVIEWED_PARTIAL receipt requires INCOMPLETE proposal' });
+});
+export const sourceAdmissionMatchSchema = z.object({
+    url: z.url(),
+    status: z.enum(['ADMITTED', 'BLOCKED', 'MISSING', 'DUPLICATE']),
+    universeSourceId: idSchema.nullable(),
+    acquisitionSourceId: idSchema.nullable(),
+    concreteSourceId: idSchema.nullable(),
+    issues: z.array(shortText).max(128),
+}).strict();
+export const sourceAdmissionAssessmentSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    projectKey: projectKeySchema,
+    familyId: idSchema,
+    state: z.enum(['ADMITTED', 'BLOCKED']),
+    selectedSourceCount: z.number().int().nonnegative(),
+    matches: z.array(sourceAdmissionMatchSchema).max(1000),
+    blockers: z.array(shortText).max(1000),
+    configMutationPerformed: z.literal(false),
+}).strict();

package/dist/internal/contracts/source.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { accessClassificationSchema, idSchema, projectKeySchema, schemaVersionSchema, stableUriSchema, } from './common.js';
+export const sourceKindSchema = z.enum([
+    'WEB',
+    'API',
+    'FILE',
+    'REPOSITORY',
+    'FEED',
+    'SOCIAL',
+    'BROWSER',
+    'MANUAL',
+    'OTHER',
+]);
+export const sourceDefinitionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    sourceId: idSchema,
+    projectKey: projectKeySchema.optional(),
+    kind: sourceKindSchema,
+    authority: z.string().trim().min(1).max(256),
+    access: accessClassificationSchema,
+    canonicalUri: stableUriSchema.optional(),
+    refreshPolicy: z.string().trim().min(1).max(256),
+    enabled: z.boolean(),
+    tags: z.array(z.string().trim().min(1).max(128)).max(64).default([]),
+}).strict();
+export const collectorDefinitionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    collectorId: idSchema,
+    version: z.string().trim().min(1).max(128),
+    supportedSourceKinds: z.array(sourceKindSchema).min(1),
+    capabilities: z.array(z.string().trim().min(1).max(128)).max(64),
+}).strict();

package/dist/internal/contracts/tenant-budget.js

@@ -0,0 +1,34 @@
+/** Host-authored admission accounting, independent of business authorization and receipt schemas. */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { materialTenantIdSchema } from './material-context.js';
+import { isoDateTimeSchema } from './common.js';
+import { parseTenantCollectionBatchRef } from './tenant-collection.js';
+import { tenantStorageKey } from './resource-scope.js';
+const positive = (max) => z.number().int().min(1).max(max);
+export const tenantBudgetPolicySchema = z.object({ tenantId: materialTenantIdSchema, maxInFlight: positive(32), maxWorkUnits: positive(1_000_000), maxRuntimeMs: positive(86_400_000), weight: positive(8), paused: z.boolean() }).strict();
+export const tenantBudgetConfigSchema = z.object({ schemaVersion: z.literal(1), windowSeconds: z.number().int().min(60).max(86400), maxInFlight: positive(128), maxWaitRounds: positive(2048), tenants: z.array(tenantBudgetPolicySchema).min(1).max(128) }).strict().superRefine((value, ctx) => {
+    if (new Set(value.tenants.map(t => t.tenantId)).size !== value.tenants.length || value.tenants.some(t => t.maxInFlight > value.maxInFlight) || value.tenants.reduce((sum, t) => sum + t.weight, 0) > value.maxWaitRounds)
+        ctx.addIssue({ code: 'custom', message: 'Unique Tenants, Host limits and weighted waiting bound are required' });
+});
+export const tenantBudgetCandidateSchema = z.object({ key: z.string().regex(/^[a-f0-9]{64}$/), tenantId: materialTenantIdSchema, workUnits: positive(100_000), runtimeMs: z.number().int().min(1000).max(7_200_000) }).strict();
+export const tenantBudgetReservationSchema = tenantBudgetCandidateSchema.extend({ admissionId: z.string().uuid(), nodeId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/), startedAt: isoDateTimeSchema, expiresAt: isoDateTimeSchema, windowStart: isoDateTimeSchema }).strict();
+export const tenantBudgetReasonSchema = z.enum(['READY', 'TENANT_UNCONFIGURED', 'PAUSED', 'HOST_IN_FLIGHT', 'TENANT_IN_FLIGHT', 'WORK_BUDGET', 'TIME_BUDGET', 'WORK_ACTIVE']);
+/** 两小时是整个准入的硬上限；短任务保留结算余量，合法的上限任务不因此被排除。 */
+export function tenantLegacyAdmissionRuntimeMs(timeoutSeconds) {
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 30 || timeoutSeconds > 7200)
+        throw new Error('TENANT_LEGACY_TIMEOUT_INVALID');
+    return Math.min(7_200_000, timeoutSeconds * 1000 + 2000);
+}
+export function tenantCollectionAdmissionKey(tenantId, batchRef) {
+    const batch = parseTenantCollectionBatchRef(batchRef);
+    if (!batch || batch.storageKey !== tenantStorageKey(tenantId))
+        throw new Error('TENANT_BUDGET_WORK_SCOPE_INVALID');
+    return createHash('sha256').update(JSON.stringify(['TENANT_COLLECTION_ADMISSION_V1', tenantId, batchRef])).digest('hex');
+}
+export function tenantLegacyAdmissionKey(tenantId, workloadId) {
+    materialTenantIdSchema.parse(tenantId);
+    if (typeof workloadId !== 'string' || workloadId.length > 256 || !/^project:[A-Za-z0-9][A-Za-z0-9._-]{0,127}:.+$/.test(workloadId))
+        throw new Error('TENANT_BUDGET_WORK_SCOPE_INVALID');
+    return createHash('sha256').update(JSON.stringify(['TENANT_LEGACY_ADMISSION_V1', tenantId, workloadId])).digest('hex');
+}

package/dist/internal/contracts/tenant-collection-request.js

@@ -0,0 +1,58 @@
+/** 请求归因与 project-blind 批次分离；只保存委托身份，不保存可使用的 token。 */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, stableUriSchema, sha256Schema } from './common.js';
+import { resourceScopeSchema, tenantStorageKey, parseTenantResourceRef, tenantResourceRefSchema } from './resource-scope.js';
+import { materialTenantIdSchema } from './material-context.js';
+import { knowledgeActorContextSchema } from './project-intent.js';
+import { tenantCollectionPlanSchema, tenantCollectionCycleSchema, tenantCollectionBatchIdentity, tenantCapturedEvidenceIdentity } from './tenant-collection.js';
+export const tenantCollectionRequestAuthoritySchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('HOST') }).strict(),
+    z.object({ type: z.literal('OAUTH'), authorityVersion: z.literal(2), clientId: idSchema, grantId: idSchema, resource: stableUriSchema }).strict(),
+]);
+export function tenantCollectionRequestKey(requestId) { return createHash('sha256').update(tenantCollectionCycleSchema.parse(requestId)).digest('hex'); }
+export function tenantCollectionRequestRef(tenantId, requestId) { return `tenant-collection-request://${tenantStorageKey(tenantId)}/${tenantCollectionRequestKey(requestId)}`; }
+export const tenantCollectionRequestSchema = z.object({
+    schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, requestId: tenantCollectionCycleSchema, requestRef: stableUriSchema,
+    context: resourceScopeSchema, actor: knowledgeActorContextSchema, authority: tenantCollectionRequestAuthoritySchema,
+    plan: tenantCollectionPlanSchema, trigger: z.enum(['MANUAL', 'DUE']), cycleId: tenantCollectionCycleSchema, batchId: z.string().regex(/^batch_[a-f0-9]{64}$/), batchRef: stableUriSchema, requestedAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    const expected = tenantCollectionBatchIdentity(value.tenantId, value.plan.revision, value.trigger, value.cycleId);
+    if (value.context.tenantId !== value.tenantId || value.actor.tenantId !== value.tenantId || value.plan.tenantId !== value.tenantId || value.requestRef !== tenantCollectionRequestRef(value.tenantId, value.requestId))
+        ctx.addIssue({ code: 'custom', path: ['context'], message: 'Request must retain exact Tenant/context/request identity' });
+    if (value.batchId !== expected.batchId || value.batchRef !== expected.batchRef)
+        ctx.addIssue({ code: 'custom', path: ['batchRef'], message: 'Request cannot retarget a different frozen batch' });
+    if (value.trigger === 'DUE' && value.authority.type !== 'HOST')
+        ctx.addIssue({ code: 'custom', path: ['trigger'], message: 'Only an explicit Host dispatcher may request DUE' });
+});
+const completionV1 = z.object({
+    schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, requestRef: stableUriSchema, batchRef: stableUriSchema,
+    phase: z.enum(['RAW_REGISTERED', 'DERIVED_REGISTERED']), evidenceRef: stableUriSchema, contentHash: sha256Schema,
+    runId: idSchema, runtimeNodeId: idSchema, completedAt: isoDateTimeSchema,
+}).strict();
+export const tenantCollectionCompletionSchema = z.union([completionV1, completionV1.extend({ schemaVersion: z.literal(2), phase: z.literal('DERIVED_REGISTERED'), documentRef: tenantResourceRefSchema }).strict()]);
+export function assertTenantCollectionCompletion(request, raw) {
+    const completion = tenantCollectionCompletionSchema.parse(raw), expected = tenantCapturedEvidenceIdentity({ tenantId: request.tenantId, batchRef: request.batchRef, sourceRevisionRef: request.plan.source.revisionRef });
+    const expectedPhase = request.plan.source.semantics.representation.format === 'RAW' ? 'RAW_REGISTERED' : 'DERIVED_REGISTERED';
+    if (completion.tenantId !== request.tenantId || completion.requestRef !== request.requestRef || completion.batchRef !== request.batchRef || completion.evidenceRef !== expected.ref || completion.phase !== expectedPhase)
+        throw new Error('TENANT_COLLECTION_COMPLETION_MISMATCH');
+    if (expectedPhase === 'DERIVED_REGISTERED') {
+        const document = completion.schemaVersion === 2 ? parseTenantResourceRef(completion.documentRef) : null;
+        if (!document || document.storageKey !== tenantStorageKey(request.tenantId) || document.resourceType !== 'source_document')
+            throw new Error('TENANT_COLLECTION_DERIVATION_UNPROVEN');
+    }
+    else if (completion.schemaVersion !== 1)
+        throw new Error('TENANT_COLLECTION_COMPLETION_MISMATCH');
+    return completion;
+}
+/** Admission retirement is not acquisition failure or business completion. */
+export const TENANT_REQUEST_ADMISSION_STOP_CAPABILITY = 'TENANT_REQUEST_ADMISSION_STOP_V1';
+export const tenantCollectionAdmissionStopSchema = z.object({ schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, requestRef: stableUriSchema, requestHash: sha256Schema, reason: z.enum(['GRANT_REVOKED', 'DELEGATION_SUPERSEDED']), stoppedAt: isoDateTimeSchema }).strict();
+/** Acquisition outcome only: a failed request is neither completed nor delegation-retired. */
+export const tenantCollectionFailureSchema = z.object({
+    schemaVersion: z.literal(1), tenantId: materialTenantIdSchema, requestRef: stableUriSchema, requestHash: sha256Schema, batchRef: stableUriSchema,
+    runId: idSchema, runtimeNodeId: idSchema, receiptHash: sha256Schema, failedAt: isoDateTimeSchema, errorCode: z.literal('TENANT_SOURCE_HTTP_TERMINAL'),
+}).strict();
+export function isTenantCollectionTerminalFailure(request, receipt) {
+    return receipt.status === 'FAILED' && receipt.errorCode === 'TENANT_SOURCE_HTTP_TERMINAL' && receipt.workloadId === request.plan.workloadId && receipt.collectionBatchRef === request.batchRef && receipt.inputFingerprint === request.plan.revision && receipt.projectRef === undefined && receipt.projectIntentRef === undefined && receipt.evidenceCount === 0 && receipt.observationCount === 0 && Date.parse(receipt.finishedAt) >= Date.parse(receipt.startedAt) && request.plan.source.semantics.target.kind === 'URL' && request.plan.source.semantics.credential.type === 'PUBLIC';
+}