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

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.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+export declare const sourceKindSchema: z.ZodEnum<{
+    MANUAL: "MANUAL";
+    FILE: "FILE";
+    WEB: "WEB";
+    API: "API";
+    REPOSITORY: "REPOSITORY";
+    FEED: "FEED";
+    SOCIAL: "SOCIAL";
+    BROWSER: "BROWSER";
+    OTHER: "OTHER";
+}>;
+export declare const sourceDefinitionSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    sourceId: z.ZodString;
+    projectKey: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        MANUAL: "MANUAL";
+        FILE: "FILE";
+        WEB: "WEB";
+        API: "API";
+        REPOSITORY: "REPOSITORY";
+        FEED: "FEED";
+        SOCIAL: "SOCIAL";
+        BROWSER: "BROWSER";
+        OTHER: "OTHER";
+    }>;
+    authority: z.ZodString;
+    access: z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    canonicalUri: z.ZodOptional<z.ZodString>;
+    refreshPolicy: z.ZodString;
+    enabled: z.ZodBoolean;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const collectorDefinitionSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    collectorId: z.ZodString;
+    version: z.ZodString;
+    supportedSourceKinds: z.ZodArray<z.ZodEnum<{
+        MANUAL: "MANUAL";
+        FILE: "FILE";
+        WEB: "WEB";
+        API: "API";
+        REPOSITORY: "REPOSITORY";
+        FEED: "FEED";
+        SOCIAL: "SOCIAL";
+        BROWSER: "BROWSER";
+        OTHER: "OTHER";
+    }>>;
+    capabilities: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type SourceKind = z.infer<typeof sourceKindSchema>;
+export type SourceDefinition = z.infer<typeof sourceDefinitionSchema>;
+export type CollectorDefinition = z.infer<typeof collectorDefinitionSchema>;

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.d.ts

@@ -0,0 +1,59 @@
+/** Host-authored admission accounting, independent of business authorization and receipt schemas. */
+import { z } from 'zod';
+export declare const tenantBudgetPolicySchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    maxInFlight: z.ZodNumber;
+    maxWorkUnits: z.ZodNumber;
+    maxRuntimeMs: z.ZodNumber;
+    weight: z.ZodNumber;
+    paused: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const tenantBudgetConfigSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    windowSeconds: z.ZodNumber;
+    maxInFlight: z.ZodNumber;
+    maxWaitRounds: z.ZodNumber;
+    tenants: z.ZodArray<z.ZodObject<{
+        tenantId: z.ZodString;
+        maxInFlight: z.ZodNumber;
+        maxWorkUnits: z.ZodNumber;
+        maxRuntimeMs: z.ZodNumber;
+        weight: z.ZodNumber;
+        paused: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const tenantBudgetCandidateSchema: z.ZodObject<{
+    key: z.ZodString;
+    tenantId: z.ZodString;
+    workUnits: z.ZodNumber;
+    runtimeMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const tenantBudgetReservationSchema: z.ZodObject<{
+    key: z.ZodString;
+    tenantId: z.ZodString;
+    workUnits: z.ZodNumber;
+    runtimeMs: z.ZodNumber;
+    admissionId: z.ZodString;
+    nodeId: z.ZodString;
+    startedAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+    windowStart: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const tenantBudgetReasonSchema: z.ZodEnum<{
+    READY: "READY";
+    TENANT_UNCONFIGURED: "TENANT_UNCONFIGURED";
+    PAUSED: "PAUSED";
+    HOST_IN_FLIGHT: "HOST_IN_FLIGHT";
+    TENANT_IN_FLIGHT: "TENANT_IN_FLIGHT";
+    WORK_BUDGET: "WORK_BUDGET";
+    TIME_BUDGET: "TIME_BUDGET";
+    WORK_ACTIVE: "WORK_ACTIVE";
+}>;
+export type TenantBudgetConfig = z.infer<typeof tenantBudgetConfigSchema>;
+export type TenantBudgetCandidate = z.infer<typeof tenantBudgetCandidateSchema>;
+export type TenantBudgetReservation = z.infer<typeof tenantBudgetReservationSchema>;
+/** 两小时是整个准入的硬上限；短任务保留结算余量，合法的上限任务不因此被排除。 */
+export declare function tenantLegacyAdmissionRuntimeMs(timeoutSeconds: number): number;
+export type TenantBudgetReason = z.infer<typeof tenantBudgetReasonSchema>;
+export declare function tenantCollectionAdmissionKey(tenantId: string, batchRef: string): string;
+export declare function tenantLegacyAdmissionKey(tenantId: string, workloadId: string): string;

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.d.ts

@@ -0,0 +1,209 @@
+import { z } from 'zod';
+import type { RunReceipt } from './runtime.js';
+export declare const tenantCollectionRequestAuthoritySchema: 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">;
+export declare function tenantCollectionRequestKey(requestId: string): string;
+export declare function tenantCollectionRequestRef(tenantId: string, requestId: string): string;
+export declare const tenantCollectionRequestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    tenantId: z.ZodString;
+    requestId: z.ZodString;
+    requestRef: z.ZodString;
+    context: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"TENANT">;
+        tenantId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"PROJECT">;
+        tenantId: z.ZodString;
+        projectKey: z.ZodString;
+    }, z.core.$strict>], "type">;
+    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">;
+    plan: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        tenantId: z.ZodString;
+        source: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            tenantId: z.ZodString;
+            sourceId: z.ZodString;
+            title: z.ZodString;
+            semantics: z.ZodObject<{
+                target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"URL">;
+                    locator: z.ZodURL;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"FILE">;
+                    rootBinding: z.ZodString;
+                    relativePath: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"EXECUTOR">;
+                    executorId: z.ZodString;
+                    bindingRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                    parameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>>;
+                }, z.core.$strict>], "kind">;
+                credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    type: z.ZodLiteral<"PUBLIC">;
+                }, z.core.$strict>, z.ZodObject<{
+                    type: z.ZodLiteral<"BOUND">;
+                    bindingRef: z.ZodString;
+                    revision: z.ZodString;
+                }, z.core.$strict>], "type">;
+                executionBinding: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+                    bindingRef: z.ZodString;
+                    revision: z.ZodString;
+                }, z.core.$strict>>>;
+                access: z.ZodEnum<{
+                    PUBLIC: "PUBLIC";
+                    PUBLIC_METADATA: "PUBLIC_METADATA";
+                    TENANT: "TENANT";
+                    INTERNAL: "INTERNAL";
+                    FDE_INTERNAL: "FDE_INTERNAL";
+                    ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+                    UNKNOWN: "UNKNOWN";
+                }>;
+                sourcePolicy: z.ZodObject<{
+                    ref: z.ZodString;
+                    revision: z.ZodString;
+                    acquisition: z.ZodEnum<{
+                        ALLOW: "ALLOW";
+                        DENY: "DENY";
+                    }>;
+                    propagation: z.ZodEnum<{
+                        TENANT_ONLY: "TENANT_ONLY";
+                        SHARE_ALLOWED: "SHARE_ALLOWED";
+                        PUBLIC_ALLOWED: "PUBLIC_ALLOWED";
+                    }>;
+                }, z.core.$strict>;
+                region: z.ZodNullable<z.ZodString>;
+                representation: z.ZodObject<{
+                    format: z.ZodEnum<{
+                        RICH_DOCUMENT_V1: "RICH_DOCUMENT_V1";
+                        RAW: "RAW";
+                    }>;
+                    extractor: z.ZodNullable<z.ZodObject<{
+                        id: z.ZodString;
+                        version: z.ZodString;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>;
+            }, z.core.$strict>;
+            sourceRef: z.ZodString;
+            revision: z.ZodString;
+            revisionRef: z.ZodString;
+            semanticKey: z.ZodString;
+            targetId: z.ZodString;
+        }, z.core.$strict>;
+        maxResourceBytes: z.ZodNumber;
+        revision: z.ZodString;
+        planRef: z.ZodString;
+        workloadId: z.ZodString;
+    }, z.core.$strict>;
+    trigger: z.ZodEnum<{
+        MANUAL: "MANUAL";
+        DUE: "DUE";
+    }>;
+    cycleId: z.ZodString;
+    batchId: z.ZodString;
+    batchRef: z.ZodString;
+    requestedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const tenantCollectionCompletionSchema: z.ZodUnion<readonly [z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    tenantId: z.ZodString;
+    requestRef: z.ZodString;
+    batchRef: z.ZodString;
+    phase: z.ZodEnum<{
+        RAW_REGISTERED: "RAW_REGISTERED";
+        DERIVED_REGISTERED: "DERIVED_REGISTERED";
+    }>;
+    evidenceRef: z.ZodString;
+    contentHash: z.ZodString;
+    runId: z.ZodString;
+    runtimeNodeId: z.ZodString;
+    completedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    tenantId: z.ZodString;
+    requestRef: z.ZodString;
+    batchRef: z.ZodString;
+    evidenceRef: z.ZodString;
+    contentHash: z.ZodString;
+    runId: z.ZodString;
+    runtimeNodeId: z.ZodString;
+    completedAt: z.ZodISODateTime;
+    schemaVersion: z.ZodLiteral<2>;
+    phase: z.ZodLiteral<"DERIVED_REGISTERED">;
+    documentRef: z.ZodString;
+}, z.core.$strict>]>;
+export declare function assertTenantCollectionCompletion(request: TenantCollectionRequest, raw: unknown): {
+    schemaVersion: 1;
+    tenantId: string;
+    requestRef: string;
+    batchRef: string;
+    phase: "RAW_REGISTERED" | "DERIVED_REGISTERED";
+    evidenceRef: string;
+    contentHash: string;
+    runId: string;
+    runtimeNodeId: string;
+    completedAt: string;
+} | {
+    tenantId: string;
+    requestRef: string;
+    batchRef: string;
+    evidenceRef: string;
+    contentHash: string;
+    runId: string;
+    runtimeNodeId: string;
+    completedAt: string;
+    schemaVersion: 2;
+    phase: "DERIVED_REGISTERED";
+    documentRef: string;
+};
+export type TenantCollectionRequest = z.infer<typeof tenantCollectionRequestSchema>;
+export type TenantCollectionCompletion = z.infer<typeof tenantCollectionCompletionSchema>;
+/** Admission retirement is not acquisition failure or business completion. */
+export declare const TENANT_REQUEST_ADMISSION_STOP_CAPABILITY = "TENANT_REQUEST_ADMISSION_STOP_V1";
+export declare const tenantCollectionAdmissionStopSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    tenantId: z.ZodString;
+    requestRef: z.ZodString;
+    requestHash: z.ZodString;
+    reason: z.ZodEnum<{
+        GRANT_REVOKED: "GRANT_REVOKED";
+        DELEGATION_SUPERSEDED: "DELEGATION_SUPERSEDED";
+    }>;
+    stoppedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type TenantCollectionAdmissionStop = z.infer<typeof tenantCollectionAdmissionStopSchema>;
+/** Acquisition outcome only: a failed request is neither completed nor delegation-retired. */
+export declare const tenantCollectionFailureSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    tenantId: z.ZodString;
+    requestRef: z.ZodString;
+    requestHash: z.ZodString;
+    batchRef: z.ZodString;
+    runId: z.ZodString;
+    runtimeNodeId: z.ZodString;
+    receiptHash: z.ZodString;
+    failedAt: z.ZodISODateTime;
+    errorCode: z.ZodLiteral<"TENANT_SOURCE_HTTP_TERMINAL">;
+}, z.core.$strict>;
+export type TenantCollectionFailure = z.infer<typeof tenantCollectionFailureSchema>;
+export declare function isTenantCollectionTerminalFailure(request: Pick<TenantCollectionRequest, 'plan' | 'batchRef'>, receipt: RunReceipt): boolean;

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